herald-auth-web 0.5.1

package/dist/index.d.ts

@@ -0,0 +1,772 @@
+type AuthToken = string | undefined;
+interface Auth {
+    /**
+     * Which part of the request do we use to send the auth?
+     *
+     * @default 'header'
+     */
+    in?: 'header' | 'query' | 'cookie';
+    /**
+     * Header or query parameter name.
+     *
+     * @default 'Authorization'
+     */
+    name?: string;
+    scheme?: 'basic' | 'bearer';
+    type: 'apiKey' | 'http';
+}
+
+interface SerializerOptions<T> {
+    /**
+     * @default true
+     */
+    explode: boolean;
+    style: T;
+}
+type ArrayStyle = 'form' | 'spaceDelimited' | 'pipeDelimited';
+type ObjectStyle = 'form' | 'deepObject';
+
+type QuerySerializer = (query: Record<string, unknown>) => string;
+type BodySerializer = (body: any) => any;
+type QuerySerializerOptionsObject = {
+    allowReserved?: boolean;
+    array?: Partial<SerializerOptions<ArrayStyle>>;
+    object?: Partial<SerializerOptions<ObjectStyle>>;
+};
+type QuerySerializerOptions = QuerySerializerOptionsObject & {
+    /**
+     * Per-parameter serialization overrides. When provided, these settings
+     * override the global array/object settings for specific parameter names.
+     */
+    parameters?: Record<string, QuerySerializerOptionsObject>;
+};
+
+type HttpMethod = 'connect' | 'delete' | 'get' | 'head' | 'options' | 'patch' | 'post' | 'put' | 'trace';
+type Client$1<RequestFn = never, Config = unknown, MethodFn = never, BuildUrlFn = never, SseFn = never> = {
+    /**
+     * Returns the final request URL.
+     */
+    buildUrl: BuildUrlFn;
+    getConfig: () => Config;
+    request: RequestFn;
+    setConfig: (config: Config) => Config;
+} & {
+    [K in HttpMethod]: MethodFn;
+} & ([SseFn] extends [never] ? {
+    sse?: never;
+} : {
+    sse: {
+        [K in HttpMethod]: SseFn;
+    };
+});
+interface Config$1 {
+    /**
+     * Auth token or a function returning auth token. The resolved value will be
+     * added to the request payload as defined by its `security` array.
+     */
+    auth?: ((auth: Auth) => Promise<AuthToken> | AuthToken) | AuthToken;
+    /**
+     * A function for serializing request body parameter. By default,
+     * {@link JSON.stringify()} will be used.
+     */
+    bodySerializer?: BodySerializer | null;
+    /**
+     * An object containing any HTTP headers that you want to pre-populate your
+     * `Headers` object with.
+     *
+     * {@link https://developer.mozilla.org/docs/Web/API/Headers/Headers#init See more}
+     */
+    headers?: RequestInit['headers'] | Record<string, string | number | boolean | (string | number | boolean)[] | null | undefined | unknown>;
+    /**
+     * The request method.
+     *
+     * {@link https://developer.mozilla.org/docs/Web/API/fetch#method See more}
+     */
+    method?: Uppercase<HttpMethod>;
+    /**
+     * A function for serializing request query parameters. By default, arrays
+     * will be exploded in form style, objects will be exploded in deepObject
+     * style, and reserved characters are percent-encoded.
+     *
+     * This method will have no effect if the native `paramsSerializer()` Axios
+     * API function is used.
+     *
+     * {@link https://swagger.io/docs/specification/serialization/#query View examples}
+     */
+    querySerializer?: QuerySerializer | QuerySerializerOptions;
+    /**
+     * A function validating request data. This is useful if you want to ensure
+     * the request conforms to the desired shape, so it can be safely sent to
+     * the server.
+     */
+    requestValidator?: (data: unknown) => Promise<unknown>;
+    /**
+     * A function transforming response data before it's returned. This is useful
+     * for post-processing data, e.g. converting ISO strings into Date objects.
+     */
+    responseTransformer?: (data: unknown) => Promise<unknown>;
+    /**
+     * A function validating response data. This is useful if you want to ensure
+     * the response conforms to the desired shape, so it can be safely passed to
+     * the transformers and returned to the user.
+     */
+    responseValidator?: (data: unknown) => Promise<unknown>;
+}
+
+type ServerSentEventsOptions<TData = unknown> = Omit<RequestInit, 'method'> & Pick<Config$1, 'method' | 'responseTransformer' | 'responseValidator'> & {
+    /**
+     * Fetch API implementation. You can use this option to provide a custom
+     * fetch instance.
+     *
+     * @default globalThis.fetch
+     */
+    fetch?: typeof fetch;
+    /**
+     * Implementing clients can call request interceptors inside this hook.
+     */
+    onRequest?: (url: string, init: RequestInit) => Promise<Request>;
+    /**
+     * Callback invoked when a network or parsing error occurs during streaming.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @param error The error that occurred.
+     */
+    onSseError?: (error: unknown) => void;
+    /**
+     * Callback invoked when an event is streamed from the server.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @param event Event streamed from the server.
+     * @returns Nothing (void).
+     */
+    onSseEvent?: (event: StreamEvent<TData>) => void;
+    serializedBody?: RequestInit['body'];
+    /**
+     * Default retry delay in milliseconds.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @default 3000
+     */
+    sseDefaultRetryDelay?: number;
+    /**
+     * Maximum number of retry attempts before giving up.
+     */
+    sseMaxRetryAttempts?: number;
+    /**
+     * Maximum retry delay in milliseconds.
+     *
+     * Applies only when exponential backoff is used.
+     *
+     * This option applies only if the endpoint returns a stream of events.
+     *
+     * @default 30000
+     */
+    sseMaxRetryDelay?: number;
+    /**
+     * Optional sleep function for retry backoff.
+     *
+     * Defaults to using `setTimeout`.
+     */
+    sseSleepFn?: (ms: number) => Promise<void>;
+    url: string;
+};
+interface StreamEvent<TData = unknown> {
+    data: TData;
+    event?: string;
+    id?: string;
+    retry?: number;
+}
+type ServerSentEventsResult<TData = unknown, TReturn = void, TNext = unknown> = {
+    stream: AsyncGenerator<TData extends Record<string, unknown> ? TData[keyof TData] : TData, TReturn, TNext>;
+};
+
+type ErrInterceptor<Err, Res, Req, Options> = (error: Err, response: Res, request: Req, options: Options) => Err | Promise<Err>;
+type ReqInterceptor<Req, Options> = (request: Req, options: Options) => Req | Promise<Req>;
+type ResInterceptor<Res, Req, Options> = (response: Res, request: Req, options: Options) => Res | Promise<Res>;
+declare class Interceptors<Interceptor> {
+    fns: Array<Interceptor | null>;
+    clear(): void;
+    eject(id: number | Interceptor): void;
+    exists(id: number | Interceptor): boolean;
+    getInterceptorIndex(id: number | Interceptor): number;
+    update(id: number | Interceptor, fn: Interceptor): number | Interceptor | false;
+    use(fn: Interceptor): number;
+}
+interface Middleware<Req, Res, Err, Options> {
+    error: Interceptors<ErrInterceptor<Err, Res, Req, Options>>;
+    request: Interceptors<ReqInterceptor<Req, Options>>;
+    response: Interceptors<ResInterceptor<Res, Req, Options>>;
+}
+
+type ResponseStyle = 'data' | 'fields';
+interface Config<T extends ClientOptions = ClientOptions> extends Omit<RequestInit, 'body' | 'headers' | 'method'>, Config$1 {
+    /**
+     * Base URL for all requests made by this client.
+     */
+    baseUrl?: T['baseUrl'];
+    /**
+     * Fetch API implementation. You can use this option to provide a custom
+     * fetch instance.
+     *
+     * @default globalThis.fetch
+     */
+    fetch?: typeof fetch;
+    /**
+     * Please don't use the Fetch client for Next.js applications. The `next`
+     * options won't have any effect.
+     *
+     * Install {@link https://www.npmjs.com/package/@hey-api/client-next `@hey-api/client-next`} instead.
+     */
+    next?: never;
+    /**
+     * Return the response data parsed in a specified format. By default, `auto`
+     * will infer the appropriate method from the `Content-Type` response header.
+     * You can override this behavior with any of the {@link Body} methods.
+     * Select `stream` if you don't want to parse response data at all.
+     *
+     * @default 'auto'
+     */
+    parseAs?: 'arrayBuffer' | 'auto' | 'blob' | 'formData' | 'json' | 'stream' | 'text';
+    /**
+     * Should we return only data or multiple fields (data, error, response, etc.)?
+     *
+     * @default 'fields'
+     */
+    responseStyle?: ResponseStyle;
+    /**
+     * Throw an error instead of returning it in the response?
+     *
+     * @default false
+     */
+    throwOnError?: T['throwOnError'];
+}
+interface RequestOptions<TData = unknown, TResponseStyle extends ResponseStyle = 'fields', ThrowOnError extends boolean = boolean, Url extends string = string> extends Config<{
+    responseStyle: TResponseStyle;
+    throwOnError: ThrowOnError;
+}>, Pick<ServerSentEventsOptions<TData>, 'onSseError' | 'onSseEvent' | 'sseDefaultRetryDelay' | 'sseMaxRetryAttempts' | 'sseMaxRetryDelay'> {
+    /**
+     * Any body that you want to add to your request.
+     *
+     * {@link https://developer.mozilla.org/docs/Web/API/fetch#body}
+     */
+    body?: unknown;
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    /**
+     * Security mechanism(s) to use for the request.
+     */
+    security?: ReadonlyArray<Auth>;
+    url: Url;
+}
+interface ResolvedRequestOptions<TResponseStyle extends ResponseStyle = 'fields', ThrowOnError extends boolean = boolean, Url extends string = string> extends RequestOptions<unknown, TResponseStyle, ThrowOnError, Url> {
+    serializedBody?: string;
+}
+type RequestResult<TData = unknown, TError = unknown, ThrowOnError extends boolean = boolean, TResponseStyle extends ResponseStyle = 'fields'> = ThrowOnError extends true ? Promise<TResponseStyle extends 'data' ? TData extends Record<string, unknown> ? TData[keyof TData] : TData : {
+    data: TData extends Record<string, unknown> ? TData[keyof TData] : TData;
+    request: Request;
+    response: Response;
+}> : Promise<TResponseStyle extends 'data' ? (TData extends Record<string, unknown> ? TData[keyof TData] : TData) | undefined : ({
+    data: TData extends Record<string, unknown> ? TData[keyof TData] : TData;
+    error: undefined;
+} | {
+    data: undefined;
+    error: TError extends Record<string, unknown> ? TError[keyof TError] : TError;
+}) & {
+    request: Request;
+    response: Response;
+}>;
+interface ClientOptions {
+    baseUrl?: string;
+    responseStyle?: ResponseStyle;
+    throwOnError?: boolean;
+}
+type MethodFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'>) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
+type SseFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'>) => Promise<ServerSentEventsResult<TData, TError>>;
+type RequestFn = <TData = unknown, TError = unknown, ThrowOnError extends boolean = false, TResponseStyle extends ResponseStyle = 'fields'>(options: Omit<RequestOptions<TData, TResponseStyle, ThrowOnError>, 'method'> & Pick<Required<RequestOptions<TData, TResponseStyle, ThrowOnError>>, 'method'>) => RequestResult<TData, TError, ThrowOnError, TResponseStyle>;
+type BuildUrlFn = <TData extends {
+    body?: unknown;
+    path?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    url: string;
+}>(options: TData & Options<TData>) => string;
+type Client = Client$1<RequestFn, Config, MethodFn, BuildUrlFn, SseFn> & {
+    interceptors: Middleware<Request, Response, unknown, ResolvedRequestOptions>;
+};
+interface TDataShape {
+    body?: unknown;
+    headers?: unknown;
+    path?: unknown;
+    query?: unknown;
+    url: string;
+}
+type OmitKeys<T, K> = Pick<T, Exclude<keyof T, K>>;
+type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown, TResponseStyle extends ResponseStyle = 'fields'> = OmitKeys<RequestOptions<TResponse, TResponseStyle, ThrowOnError>, 'body' | 'path' | 'query' | 'url'> & ([TData] extends [never] ? unknown : Omit<TData, 'url'>);
+
+type BrowserTokenResponse = {
+    accessToken: string;
+    expiresIn: number;
+    refreshExpiresIn: number;
+    refreshToken: string;
+    tokenType: string;
+};
+type CredentialClass = 'first_party' | 'custom_user_ui';
+type CredentialScope = 'feature_read' | 'profile_read' | 'profile_write_nickname' | 'change_password' | 'delete_account' | 'totp_manage' | 'passkey_manage' | 'logout' | 'points_read' | 'points_transactions_read' | 'purchase_read' | 'purchase_initiate' | 'purchase_status_read' | 'invoice_read' | 'invoice_apply' | 'subscription_read' | 'subscription_cancel';
+type StatusResponse = {
+    authenticated: boolean;
+    clientAppId: string;
+    clientId: string;
+    credentialClass: CredentialClass;
+    /**
+     * Retained in the response shape for clients that display RBAC grants;
+     * browser-token authorization itself is governed by `scopes`.
+     */
+    permissions?: Array<string> | null;
+    realmId?: string | null;
+    scopes: Array<CredentialScope>;
+    userId?: string | null;
+};
+
+/**
+ * Public SDK types (DEC-js-sdk-010).
+ *
+ * DTO response types are re-exported from the (internal) generated layer so
+ * consumers get a stable, typed surface without depending on generated paths.
+ */
+
+type HeraldCredentialClass = CredentialClass;
+/** A normalized session view, derived from `/api/auth/status`. */
+interface HeraldSession {
+    authenticated: boolean;
+    realmId: string | null;
+    userId: string | null;
+    clientAppId: string | null;
+    clientId: string | null;
+    credentialClass: HeraldCredentialClass | null;
+    permissions: string[];
+    scopes: CredentialScope[];
+}
+type SessionEvent = {
+    type: 'authenticated';
+    session: HeraldSession;
+} | {
+    type: 'session-expired';
+    reason: 'refresh-failed' | 'family-revoked' | 'client-app-disabled';
+} | {
+    type: 'logged-out';
+};
+/** Second factors the backend may request on `POST /login` (DEC-js-sdk-010). */
+type SecondFactor = 'totp' | 'passkey';
+/** Agreement a caller must re-submit (via `agreements`) to pass a consent gate. */
+interface ConsentAgreement {
+    agreementType: string;
+    versionId: string;
+    /**
+     * The backend's original agreement summary (snake_case display fields:
+     * `title`, `version_no`, `effective_at`, `mode`, ...), passed through for
+     * host apps that render the consent list. Optional — the re-submit shape
+     * above is the contract; `raw` is display metadata only.
+     */
+    raw?: Record<string, unknown>;
+}
+interface LoginSuccess {
+    kind: 'success';
+    session: HeraldSession;
+}
+interface LoginRequiresSecondFactor {
+    kind: 'requires-second-factor';
+    tempToken: string;
+    expiresInSeconds: number;
+    secondFactors: SecondFactor[];
+    userId: string;
+    realmId: string;
+}
+interface LoginConsentRequired {
+    kind: 'consent-required';
+    /** Agreements the integrator must render + re-submit via `login`/`verify` `agreements`. */
+    agreements: ConsentAgreement[];
+}
+interface LoginOauthRedirect {
+    kind: 'oauth-redirect';
+    redirectTo: string;
+}
+/** A real send: the code was issued and is valid for `expiresInSeconds`. */
+interface EmailOtpSent {
+    kind: 'sent';
+    message: string;
+    expiresInSeconds: number;
+}
+/**
+ * A 409 control-flow outcome — NOT an error. `consent_required` carries the
+ * agreement list the integrator must render and re-send via `agreements`;
+ * `email_not_registered` means auto-register is off for the realm.
+ */
+interface EmailOtpConflict {
+    kind: 'conflict';
+    /** `consent_required` | `email_not_registered` (backend `email_otp.rs`). */
+    code: string;
+    message: string;
+    consentRequired: boolean;
+    /** Agreement summaries (with `raw` display passthrough) for the consent gate. */
+    agreements: ConsentAgreement[];
+}
+type EmailOtpSendResult = EmailOtpSent | EmailOtpConflict;
+type LoginResult = LoginSuccess | LoginRequiresSecondFactor | LoginConsentRequired | LoginOauthRedirect;
+/** Result of `passkey.loginBegin` (1FA or 2FA). `options` is the WebAuthn
+ *  `PublicKeyCredentialRequestOptions` JSON returned by the server. */
+interface PasskeyLoginBeginResult {
+    authToken: string;
+    options: unknown;
+}
+
+/**
+ * In-memory access-token holder + session state + events.
+ *
+ * Mirrors the Herald own-frontend pattern (`frontend/src/stores/auth-store.ts`
+ * `accessTokenHolder` + persist), with all framework (Zustand/React) coupling
+ * removed.
+ */
+
+/**
+ * Non-persisted, module-instance holder for the access token. A page reload
+ * clears it; the transport restores it via a silent refresh on the next 401.
+ */
+interface AccessTokenHolder {
+    get(): string | null;
+    set(token: string | null): void;
+    clear(): void;
+}
+type SessionListener = (event: SessionEvent) => void;
+interface SessionStore {
+    getSession(): HeraldSession;
+    setSession(session: HeraldSession | null): void;
+    subscribe(listener: SessionListener): () => void;
+    emit(event: SessionEvent): void;
+}
+
+/**
+ * Pluggable refresh-token storage (DEC-js-sdk-006).
+ *
+ * The access token NEVER passes through `TokenStorage` — it lives only in the
+ * in-memory holder (`session.ts`). The default implementation persists the
+ * (rotating, reuse-detected) refresh token to `localStorage`, matching the
+ * Herald own-frontend risk posture. Non-browser / SSR integrators must inject
+ * an adapter or use `memoryStorage()`.
+ */
+interface TokenStorage {
+    getRefreshToken(): string | null;
+    setRefreshToken(token: string | null): void;
+}
+/** In-memory storage: nothing survives a page reload. */
+declare function memoryStorage(): TokenStorage;
+/**
+ * `localStorage`-backed storage (browser default). Throws `HeraldError
+ * { kind: 'ssr-no-storage' }` when `localStorage` is unavailable so SSR/Node
+ * misuse fails fast instead of silently no-op'ing.
+ */
+declare function localStorageStorage(key: string): TokenStorage;
+
+/**
+ * WebAuthn passkey LOGIN assertion helper.
+ *
+ * Only `navigator.credentials.get` (assertion) — no registration/create. The
+ * SDK never manages authenticators (DEC-js-sdk-001). The integrator passes the
+ * server-provided options to `performPasskeyAssertion` and submits the returned
+ * assertion to `passkey.loginFinish`.
+ *
+ * base64url encode/decode is implemented on native `ArrayBuffer` ↔ `string`
+ * (no dependency).
+ */
+/** Server-provided WebAuthn request options, JSON-encoded (base64url fields). */
+interface PublicKeyCredentialRequestOptionsJSON {
+    challenge: string;
+    rpId?: string;
+    timeout?: number;
+    userVerification?: UserVerificationRequirement;
+    allowCredentials?: Array<{
+        type: 'public-key';
+        id: string;
+        transports?: AuthenticatorTransport[];
+    }>;
+}
+/** Assertion result ready to submit to the passkey verify endpoint. */
+interface AssertionResultJSON {
+    id: string;
+    rawId: string;
+    type: 'public-key';
+    response: {
+        authenticatorData: string;
+        clientDataJSON: string;
+        signature: string;
+        userHandle?: string | null;
+    };
+    clientExtensionResults?: Record<string, unknown>;
+}
+/**
+ * Perform a WebAuthn assertion for passkey login.
+ *
+ * @throws when WebAuthn is unavailable or the user cancels.
+ */
+declare function performPasskeyAssertion(options: PublicKeyCredentialRequestOptionsJSON): Promise<AssertionResultJSON>;
+
+/**
+ * Authentication orchestration (DEC-js-sdk-008 / DEC-js-sdk-010).
+ *
+ * Each method calls a generated op through the per-instance transport client
+ * (auto Bearer + silent refresh), maps the result to SDK public types, and
+ * updates the session/token state. Login-family methods normalize the
+ * multi-branch 200 into the `LoginResult` discriminated union.
+ */
+
+interface RegisterPayload {
+    email: string;
+    password: string;
+    username?: string;
+    turnstileToken?: string;
+}
+interface TriggerVerifyEmailPayload {
+    email: string;
+    turnstileToken?: string;
+}
+interface RequestPasswordResetPayload {
+    email: string;
+    turnstileToken?: string;
+}
+interface LoginPayload {
+    username?: string;
+    email?: string;
+    password: string;
+    turnstileToken?: string;
+    /** Agreements to satisfy a prior `consent-required` gate. */
+    agreements?: ConsentAgreement[];
+    /**
+     * Optional OAuth context for host apps that drive an authorization-code flow
+     * themselves (e.g. Herald's own frontend with PKCE). When present the backend
+     * answers with `redirectTo`, surfaced as `{ kind: 'oauth-redirect' }`; the SDK
+     * does NOT perform the token exchange (DEC-js-sdk-008 — that stays with the
+     * caller).
+     */
+    oauthClientId?: string;
+    redirectUri?: string;
+    state?: string;
+}
+interface VerifyTotpPayload {
+    tempToken: string;
+    code?: string;
+    backupCode?: string;
+    agreements?: ConsentAgreement[];
+}
+interface PasskeyLoginBeginPayload {
+    /** Present for 2FA (after a `requires-second-factor` login); absent for 1FA. */
+    tempToken?: string;
+    turnstileToken?: string;
+    /**
+     * Optional OAuth context for host apps driving an authorization-code flow
+     * (first-party passkey logins from an OAuth-linked login page). Passkey
+     * verify then answers with `redirectTo` (kind: 'oauth-redirect'); the SDK
+     * does NOT perform the exchange (DEC-js-sdk-008).
+     */
+    oauth?: {
+        clientId: string;
+        redirectUri: string;
+        state: string;
+    };
+}
+interface PasskeyLoginFinishPayload {
+    authToken: string;
+    assertion: AssertionResultJSON;
+    /** Present when finishing a 2FA passkey login. */
+    tempToken?: string;
+    agreements?: ConsentAgreement[];
+}
+interface EmailOtpSendPayload {
+    email: string;
+    turnstileToken?: string;
+    /** Agreements to satisfy a prior `consent_required` conflict on re-send. */
+    agreements?: ConsentAgreement[];
+}
+interface EmailOtpVerifyPayload {
+    email: string;
+    code: string;
+    agreements?: ConsentAgreement[];
+}
+interface AuthDeps {
+    realmId: string;
+    clientId: string;
+    /** Per-instance transport client; routes every op through its interceptors. */
+    client: Client;
+    accessTokenHolder: AccessTokenHolder;
+    storage: TokenStorage;
+    session: SessionStore;
+    /** Shared single-flight refresh core (from the transport). */
+    refreshTokens: () => Promise<BrowserTokenResponse | null>;
+}
+declare function createAuth(deps: AuthDeps): {
+    register(payload: RegisterPayload): Promise<{
+        message: string;
+        verificationRequired: boolean;
+    }>;
+    triggerVerifyEmail(payload: TriggerVerifyEmailPayload): Promise<{
+        message: string;
+    }>;
+    requestPasswordReset(payload: RequestPasswordResetPayload): Promise<{
+        message: string;
+    }>;
+    login(payload: LoginPayload): Promise<LoginResult>;
+    verifyTotp(payload: VerifyTotpPayload): Promise<LoginResult>;
+    passkey: {
+        loginBegin(payload: PasskeyLoginBeginPayload): Promise<PasskeyLoginBeginResult>;
+        loginFinish(payload: PasskeyLoginFinishPayload): Promise<LoginResult>;
+    };
+    loginWithEmailOtp: {
+        /**
+         * Send a passwordless login code. The two 409 control-flow outcomes
+         * (DEC-js-sdk-014) — `consent_required` (auto-register consent gate) and
+         * `email_not_registered` (auto-register off) — resolve as
+         * `{ kind: 'conflict' }` instead of throwing, mirroring the multi-branch
+         * normalization `login()` applies to its 200 bodies. All other HTTP
+         * failures throw `HeraldError`.
+         */
+        send(payload: EmailOtpSendPayload): Promise<EmailOtpSendResult>;
+        verify(payload: EmailOtpVerifyPayload): Promise<LoginResult>;
+    };
+    getStatus(): Promise<StatusResponse>;
+    /**
+     * Explicitly refresh the Bearer token family (startup restore, proactive
+     * refresh). Single-flight: concurrent calls share one HTTP request with the
+     * 401 auto-refresh interceptor. On success both the in-memory access token
+     * and the stored refresh token are rotated.
+     *
+     * @throws {HeraldError} `kind: 'session-expired'` when no refresh token is
+     *   stored or the refresh failed (reuse / expiry / family revocation); a
+     *   `session-expired` event is emitted either way.
+     */
+    refresh(): Promise<BrowserTokenResponse>;
+    logout(): Promise<{
+        message: string;
+    }>;
+};
+
+/**
+ * Client factory (US-JS-001).
+ *
+ * `createHeraldClient` wires the in-memory access-token holder, the pluggable
+ * refresh-token storage, the session store, the transport interceptors, and the
+ * auth-orchestration methods into a single client object.
+ */
+
+interface HeraldClientConfig {
+    /** Herald API origin (e.g. `https://auth.example.com`). */
+    baseUrl: string;
+    /** Realm the integration belongs to. */
+    realmId: string;
+    /** Client App identifier; injected into request bodies. */
+    clientId: string;
+    /** Refresh-token storage. Defaults to `localStorage`; inject in SSR. */
+    storage?: TokenStorage;
+    /** `localStorage` key for the refresh token (default `herald.refreshToken`). */
+    storageKey?: string;
+    /** Session lifecycle callback (`authenticated` / `session-expired` / `logged-out`). */
+    onSessionChange?: (event: SessionEvent) => void;
+}
+type HeraldClient = ReturnType<typeof createAuth> & {
+    /** The resolved refresh-token storage. */
+    readonly storage: TokenStorage;
+    /** Current session snapshot + per-instance event subscription. */
+    readonly session: {
+        getSession(): HeraldSession;
+        subscribe(listener: (event: SessionEvent) => void): () => void;
+    };
+    /** First-party token bridge: inspect / inject the token family from the host app. */
+    readonly tokens: TokenBridge;
+};
+/** Token set obtained outside the SDK (PKCE exchange, switch-client, direct-issue responses). */
+interface SetTokensPayload {
+    accessToken: string;
+    refreshToken: string;
+    /**
+     * When provided, rebinds the client's request-body `clientId` (e.g. after a
+     * first-party PKCE exchange or a switch-client performed by the host app).
+     */
+    clientId?: string;
+}
+interface TokenBridge {
+    /** Current in-memory access token (null after a reload, until refreshed). */
+    getAccessToken(): string | null;
+    /**
+     * Inject a token set obtained outside the SDK. Pure state update — no session
+     * event is emitted; call `getStatus()` afterwards to hydrate the session.
+     */
+    setTokens(tokens: SetTokensPayload): void;
+    /** Clear the access + refresh tokens without calling the server or emitting events. */
+    clear(): void;
+    /**
+     * Rebind the request-body `clientId` without touching tokens. First-party
+     * hosts pick between built-in products (e.g. console vs account center) per
+     * flow, before any tokens exist.
+     */
+    bindClientId(clientId: string): void;
+}
+/**
+ * Create a Herald browser client. Each client owns its own generated HTTP
+ * client instance, so multiple clients are fully isolated.
+ *
+ * @throws {HeraldError} `kind: 'ssr-no-storage'` when no `storage` is injected
+ *   and `localStorage` is unavailable (SSR / Node).
+ */
+declare function createHeraldClient(config: HeraldClientConfig): HeraldClient;
+
+/**
+ * Typed, programmatically-discriminable error union (US-JS-008).
+ *
+ * Every public SDK method rejects with a `HeraldError`. Branch on the stable
+ * `kind` field instead of parsing messages.
+ */
+type HeraldErrorKind = 
+/** Non-browser/SSR use without an injected `TokenStorage` adapter. */
+'ssr-no-storage'
+/** Cross-origin blocked because the page origin is not on the Client App allow-list. */
+ | 'origin-not-allowed'
+/** Network failure or undifferentiated fetch error. */
+ | 'network'
+/** 401 — credentials invalid (non-refresh context). */
+ | 'unauthorized'
+/** 403. */
+ | 'forbidden'
+/** 404. */
+ | 'not-found'
+/** Login returned a second-factor challenge where a direct token was expected. */
+ | 'requires-second-factor'
+/** Login returned a consent-required gate where a direct token was expected. */
+ | 'consent-required'
+/** Refresh failed / token family revoked / Client App disabled. */
+ | 'session-expired'
+/** 429. */
+ | 'rate-limited'
+/** 400 field validation. */
+ | 'validation'
+/** Any other backend error (carries `code`/`requestId`/`details`). */
+ | 'api';
+interface HeraldErrorInit {
+    kind: HeraldErrorKind;
+    message?: string;
+    status?: number;
+    /** Backend `ApiError.code` (snake_case slug) when available. */
+    code?: string;
+    /** Backend `ApiError.requestId` when available. */
+    requestId?: string;
+    /** Backend `ApiError.details` when available. */
+    details?: unknown;
+}
+declare class HeraldError extends Error {
+    readonly kind: HeraldErrorKind;
+    readonly status?: number;
+    readonly code?: string;
+    readonly requestId?: string;
+    readonly details?: unknown;
+    constructor(init: HeraldErrorInit);
+}
+
+export { type AssertionResultJSON, type BrowserTokenResponse, type ConsentAgreement, type EmailOtpConflict, type EmailOtpSendPayload, type EmailOtpSendResult, type EmailOtpSent, type EmailOtpVerifyPayload, type HeraldClient, type HeraldClientConfig, type HeraldCredentialClass, HeraldError, type HeraldErrorInit, type HeraldErrorKind, type HeraldSession, type LoginConsentRequired, type LoginOauthRedirect, type LoginPayload, type LoginRequiresSecondFactor, type LoginResult, type LoginSuccess, type PasskeyLoginBeginPayload, type PasskeyLoginBeginResult, type PasskeyLoginFinishPayload, type PublicKeyCredentialRequestOptionsJSON, type RegisterPayload, type RequestPasswordResetPayload, type SecondFactor, type SessionEvent, type SetTokensPayload, type StatusResponse, type TokenBridge, type TokenStorage, type TriggerVerifyEmailPayload, type VerifyTotpPayload, createHeraldClient, localStorageStorage, memoryStorage, performPasskeyAssertion };