/**
 * Typed taxonomy of auth-flow failure reasons.
 *
 * Every value is a sanitized enum literal — never a raw error message,
 * never a truncated user input, never any byte from Cognito's response.
 * Adding a new failure mode means extending this union; the compiler
 * then forces every emit site to either use a known value or produce
 * a type error.
 *
 * Keep values snake_case to match GA4 custom-dimension conventions
 * used elsewhere in the codebase (`step`, `source`, `reason`).
 */
export type AuthFailureReason = 'port_in_use' | 'server_listen_failed' | 'browser_open_failed' | 'login_timeout' | 'cognito_rejected' | 'state_mismatch' | 'no_authorization_code' | 'token_exchange_failed' | 'token_exchange_network_error' | 'keychain_write_failed' | 'user_aborted' | 'unknown';
/**
 * Auth flow stage the failure occurred in. Useful for GA4 faceting;
 * each reason has an implicit stage but keeping it as a distinct
 * param lets dashboards split `login_timeout` at `awaiting_callback`
 * from `login_timeout` at `storing_tokens` (which would be a bug,
 * not user AFK).
 */
export type AuthStage = 'server_start' | 'browser_open' | 'awaiting_callback' | 'exchanging_code' | 'storing_tokens' | 'unknown';
/**
 * Fire the `auth_completed` success beacon. Replaces the inline POST
 * previously duplicated in `auth-cli.ts`. Includes `user_id` so the
 * event can be joined against DynamoDB activity for funnel analysis.
 *
 * `userId` here is the Cognito `sub` — a pseudonymous identifier that
 * we already ship to GA4 on this event today. It is NOT an email
 * address.
 */
export declare function fireAuthCompletedBeacon(userId: string): Promise<void>;
/**
 * Fire the `auth_failed` failure beacon with a sanitized `reason`
 * literal. Optional `httpStatus` captures the numeric HTTP status
 * code from Cognito on `token_exchange_failed` (so dashboards can
 * split "401 bad client" from "500 Cognito down" from "429 rate
 * limited"). Optional `stage` overrides the default from
 * `DEFAULT_STAGE`.
 *
 * `reason` is constrained to the `AuthFailureReason` union — this
 * is the ONLY input path; passing a raw error message is a compile
 * error.
 */
export declare function fireAuthFailedBeacon(reason: AuthFailureReason, extra?: {
    httpStatus?: number;
    stage?: AuthStage;
}): Promise<void>;
/**
 * Attach the reason + beaconed marker to an Error. Non-enumerable so
 * the symbols don't serialize if the error object is ever JSON'd.
 */
export declare function markErrorBeaconed(err: Error, reason: AuthFailureReason): Error;
/** Has this error already had a beacon fired for it? */
export declare function errorWasBeaconed(err: unknown): boolean;
/** Retrieve the tagged reason from a previously-marked error, if any. */
export declare function getErrorReason(err: unknown): AuthFailureReason | undefined;
