import { HookEvent, OnExecutePostLogin } from "../../types/Hooks";
export interface AccountLinkingOptions {
    /**
     * Require `email_verified` on the logged-in user before attempting to link.
     * Disabling this is almost never what you want — unverified email linking
     * lets an attacker claim existing accounts by signing up with a matching
     * email on an unverifying provider.
     * @default true
     */
    requireVerifiedEmail?: boolean;
    /**
     * When the link is performed, merge the secondary user's `user_metadata`
     * into the primary's. Existing keys on the primary are NOT overwritten —
     * only keys absent from the primary are filled in from the secondary, so
     * the primary remains the source of truth for any conflicting values.
     *
     * `app_metadata` is intentionally never copied to avoid auto-merging into
     * the admin-only namespace.
     *
     * @default false
     */
    copyUserMetadata?: boolean;
}
/**
 * Trigger-agnostic event handler used by all `account-linking` template
 * dispatch sites. It accepts the same shape as `OnExecutePostLogin` but
 * ignores the trigger-specific `api` object, which lets the same function
 * back `post-user-login`, `post-user-registration`, and `post-user-update`.
 */
export type AccountLinkingHandler = (event: HookEvent) => Promise<void>;
/**
 * Idempotently links a user to an existing primary user with the same
 * (verified) email address. Safe to invoke from any trigger that has a
 * `user` and a `tenant.id` on the event — `post-user-login`,
 * `post-user-registration`, or `post-user-update`.
 *
 * This is the Auth0-style "Account Linking" action: customers enable it by
 * creating a template hook with `template_id: "account-linking"`. Because
 * the implementation is a no-op when linking is already correct, transient
 * failures self-heal — a later trigger simply retries the link.
 *
 * **Behavior:**
 * - No-op if the user already has `linked_to` set (already a secondary).
 * - No-op if the user has no email or `email_verified` is false (default).
 * - Looks up the primary user with the same email via
 *   `getPrimaryUserByEmail`. If found AND it's not the user themselves,
 *   sets `linked_to` on the user to point at that primary.
 * - Never unlinks; if the current user is already the primary it stays so.
 *
 * **Idempotency:** repeated calls produce the same end state.
 *
 * @example Enable as a config-level post-login hook
 * ```typescript
 * import { init, preDefinedHooks } from "authhero";
 *
 * init({
 *   dataAdapter,
 *   hooks: {
 *     onExecutePostLogin: preDefinedHooks.accountLinking(),
 *   },
 * });
 * ```
 *
 * @example Enable as a per-tenant template hook (admin API)
 * ```typescript
 * await data.hooks.create(tenantId, {
 *   trigger_id: "post-user-registration",
 *   template_id: "account-linking",
 *   enabled: true,
 * });
 * ```
 */
export declare function accountLinking(options?: AccountLinkingOptions): OnExecutePostLogin & AccountLinkingHandler;
