@nulvless/nulvless-js 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,2324 @@
+/**
+ * Storage adapter interface used by the SDK to persist session tokens.
+ *
+ * All methods are async to support both synchronous storages (localStorage)
+ * and asynchronous ones (Cache Storage API, IndexedDB, etc.).
+ */
+interface NulvlessStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+
+type Language = 'en-US' | 'pt-BR';
+interface Phone {
+    /** Country dial code — e.g. "+55" */
+    country_code: string;
+    /** Digits only, 6–18 chars */
+    number: string;
+}
+interface NulvlessError {
+    code: string;
+    message: string | string[];
+    status_code: number;
+}
+/**
+ * Every SDK method returns this type.
+ * Check `error` first — if null, `data` is guaranteed to be present.
+ */
+type NulvlessResult<T> = {
+    data: T;
+    error: null;
+} | {
+    data: null;
+    error: NulvlessError;
+};
+interface AuthOptions {
+    captcha_token?: string;
+}
+interface ClientOptions {
+    /** Returns the BCP 47 language tag sent on every request. Defaults to `'en-US'`. */
+    language?: () => Language;
+    /** Abort requests after this many milliseconds. */
+    timeout?: number;
+    /** Log request/response info to the console. */
+    debug?: boolean;
+    /**
+     * Extra headers merged into every request.
+     *
+     * Pass a function to resolve headers lazily per request — useful for
+     * forwarding values from a request-local context (CLS, AsyncLocalStorage,
+     * NestJS REQUEST, etc.) without rebuilding the client.
+     *
+     * @example Static headers
+     * ```ts
+     * createServerClient(url, sk, { headers: { 'x-app-version': '1.0.0' } })
+     * ```
+     *
+     * @example Per-request resolution (e.g. forwardUserHeaders from a CLS store)
+     * ```ts
+     * createServerClient(url, sk, {
+     *   trackUser: true,
+     *   headers: () => forwardUserHeaders(cls.get('req')),
+     * })
+     * ```
+     */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /**
+     * Renews the access token on a timer, ahead of expiry, instead of waiting
+     * for a request to find it expired. Defaults to `true`; turn it off when the
+     * host controls renewal itself. Browser clients only.
+     */
+    autoRefresh?: boolean;
+    /**
+     * When `true`, failed requests throw a `NulvlessException` instead of
+     * returning `{ data: null, error }`.
+     *
+     * Can be overridden per-request via `RequestOptions.throwErrors`.
+     */
+    throwErrors?: boolean;
+    /**
+     * Storage adapter for persisting session tokens.
+     *
+     * Defaults to `localStorage` in the browser and to a per-client in-memory
+     * store elsewhere (SSR, tests, workers).
+     *
+     * Use the built-in `Storage` adapters from `@nulvless/nulvless-js`:
+     * ```ts
+     * import { Storage } from '@nulvless/nulvless-js'
+     *
+     * createClient(url, key, { storage: Storage.Local })
+     * ```
+     *
+     * Only used by `createClient` (browser). Has no effect on `createServerClient`.
+     */
+    storage?: NulvlessStorage;
+    /**
+     * Custom storage keys for the browser session.
+     *
+     * - `token` — key for the active session token. Defaults to `nlv-<slug>-token`.
+     * - `accounts` — key for the multi-account store. Defaults to `nlv-<slug>-token-accounts`.
+     *
+     * Only used by `createClient` (browser).
+     */
+    storageKeys?: {
+        token?: string;
+        accounts?: string;
+    };
+    /**
+     * When `true`, enables multi-account support — the SDK stores all signed-in
+     * accounts and exposes `auth.add`, `auth.list`, `auth.remove`, and `auth.switch`.
+     *
+     * Defaults to `false`. Enable explicitly only when your app needs account switching.
+     *
+     * Only used by `createClient` (browser).
+     */
+    multiUser?: boolean;
+    /**
+     * When `true`, sends `nlv-user-tracking: "true"` on every request, signalling
+     * the auth service to collect device/browser fingerprint data for the session.
+     *
+     * In the browser (`createClient`), standard headers like `User-Agent`,
+     * `Origin`, and `Referer` are sent automatically by `fetch`.
+     *
+     * In the server (`createServerClient`), use `forwardUserHeaders(req)` via
+     * `options.headers` on each call to forward the real user's browser headers.
+     */
+    trackUser?: boolean;
+}
+/**
+ * Options for `createServerClient` / `NulvlessServerClient`.
+ * Identical to `ClientOptions` but without `storage` — session persistence
+ * is a browser-only concern and must not be used on the server.
+ */
+type ServerClientOptions = Omit<ClientOptions, 'storage' | 'storageKeys'>;
+/**
+ * Per-request options — override client-level config for a single call.
+ * Passed as the last argument to methods that support it.
+ *
+ * Lib-side toggles stay camelCase (`throwErrors`, `language`, `timeout`,
+ * `headers`). Backend-bound fields use snake_case (`redirect_uri`) so they
+ * pass through to the wire unchanged.
+ */
+interface RequestOptions {
+    /** Override the language header for this request. */
+    language?: () => Language;
+    /**
+     * Override (or add) HTTP headers for this request. Merged over client-level headers.
+     *
+     * For lazy/context-resolved headers shared across all calls, use
+     * `ClientOptions.headers` (function form) instead.
+     */
+    headers?: Record<string, string>;
+    /** Override the `throwErrors` strategy for this request. */
+    throwErrors?: boolean;
+    /** Redirect URI passed as body/query param for OAuth and confirmation flows. */
+    redirect_uri?: string;
+    /** Abort this request after the given number of milliseconds. Overrides the client-level `timeout`. */
+    timeout?: number;
+}
+
+type QueryValue = string | number | boolean;
+type QueryParams = Record<string, QueryValue | QueryValue[] | undefined>;
+interface SendOptions {
+    query?: QueryParams;
+    /** Override or add headers for this request. Merged over client-level headers. */
+    headers?: Record<string, string>;
+    body?: unknown;
+    /** Override the language header for this request. */
+    language?: () => Language;
+    /** Override the throwErrors strategy for this request. */
+    throwErrors?: boolean;
+    /** Abort this request after the given number of milliseconds. Overrides the client-level timeout. */
+    timeout?: number;
+    /** Single-use sudo nonce, sent as the `nlv-sudo-nonce` header. */
+    nonce?: string | undefined;
+    /** Omit the `x-platform-key` header — for public endpoints that don't require it. */
+    skipApiKey?: boolean;
+}
+interface HttpClientConfig extends ClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    /**
+     * Called when a request fails with a retryable auth error (401 or specific 403 codes).
+     * Should return a fresh access token, or `null` if refresh is not possible.
+     * The request is retried once with the new token.
+     *
+     * `deauthOnFailure` is `true` for 401/unauthorized (token is invalid — clear session
+     * and notify if refresh fails) and `false` for 403/forbidden_resource_access (token
+     * is valid but lacks the scope — refresh once to pick up new scopes, but never
+     * deauthenticate; surface the API error instead).
+     */
+    onTokenExpired?: (context: {
+        deauthOnFailure: boolean;
+        expiredToken?: string;
+    }) => Promise<string | null>;
+}
+declare class HttpClient {
+    private readonly config;
+    private onSudoRequired?;
+    constructor(config: HttpClientConfig);
+    /**
+     * Injected after construction to avoid circular dependency.
+     * Called when a request fails with `403 protected_action_denied`,
+     * indicating the user must enable sudo mode before retrying.
+     */
+    setOnSudoRequired(cb: () => void): void;
+    hasAuthorization(headers?: Record<string, string>): boolean;
+    get<T>(path: string, options?: Omit<SendOptions, 'body'>): Promise<NulvlessResult<T>>;
+    post<T>(path: string, body?: unknown, options?: Omit<SendOptions, 'body'>): Promise<NulvlessResult<T>>;
+    put<T>(path: string, body?: unknown, options?: Omit<SendOptions, 'body'>): Promise<NulvlessResult<T>>;
+    patch<T>(path: string, body?: unknown, options?: Omit<SendOptions, 'body'>): Promise<NulvlessResult<T>>;
+    delete<T>(path: string, options?: Omit<SendOptions, 'body'>): Promise<NulvlessResult<T>>;
+    /**
+     * Returns `true` when the error warrants a single token-refresh retry:
+     * - Any 401 on an authenticated request
+     * - 403 with `forbidden_access_waiting_accept` or `forbidden_resource_access` codes
+     */
+    private shouldRetryWithRefresh;
+    private send;
+    private buildUrl;
+    private buildHeaders;
+    private parseBody;
+}
+
+/**
+ * Single-use sudo nonce for step-up auth.
+ *
+ * Pass the code the user received from `auth.sessions.sudo()` to authorize a
+ * single sudo-protected call without elevating the whole session. Sent as the
+ * `nlv-sudo-nonce` header (never in the request body).
+ *
+ * Params of sudo-protected methods extend this; methods that take no other input
+ * accept it directly.
+ */
+interface Nonce {
+    nonce?: string;
+}
+interface RevokeSessionParams extends Nonce {
+    id: string;
+}
+type OAuthProvider = 'google' | 'github' | 'gitlab' | 'bitbucket' | 'facebook' | 'linked_in' | 'discord' | 'twitch' | 'slack' | 'azure' | 'apple';
+type UserGender = 'male' | 'female' | 'other' | 'prefer_not_to_say';
+interface UserProfile {
+    name?: string;
+    biography?: string;
+    gender?: UserGender;
+    avatar_uri?: string;
+    /** ISO date — YYYY-MM-DD */
+    date_of_birth?: string;
+}
+interface User {
+    id: string;
+    email?: string;
+    phone?: Phone;
+    username?: string;
+    profile?: UserProfile;
+    confirmed_at?: string;
+    is_confirmed?: boolean;
+    banned_at?: string;
+    is_banned?: boolean;
+    last_sign_in_at?: string;
+    identities?: Identity[];
+    metadata?: Record<string, string | number>;
+    created_at?: string;
+    updated_at?: string;
+}
+/** At least one of `email`, `phone`, or `username` must be provided. */
+interface SignUpParams {
+    email?: string;
+    phone?: Phone;
+    /** 3–30 chars: letters, numbers, dots, underscores */
+    username?: string;
+    profile?: UserProfile;
+    password: string;
+    options?: AuthOptions;
+}
+/** At least one of `email`, `phone`, or `username` must be provided. */
+interface SignInParams {
+    email?: string;
+    phone?: Phone;
+    username?: string;
+    password: string;
+    options?: AuthOptions;
+}
+/** At least one of `email` or `phone` must be provided. */
+interface SignInWithOTPParams {
+    email?: string;
+    phone?: Phone;
+    options?: AuthOptions;
+}
+/** At least one of `email`, `phone`, or `username` must be provided. */
+interface LookupParams {
+    email?: string;
+    phone?: Phone;
+    username?: string;
+    options?: AuthOptions;
+}
+interface RefreshTokenParams {
+    refresh_token: string;
+}
+interface RecoverParams {
+    email: string;
+    options?: AuthOptions;
+}
+interface ResetPasswordParams {
+    /** Token received via the recovery link/email. */
+    token: string;
+    password: string;
+}
+type TokenType = 'bearer';
+type AssuranceLevel = 'aal1' | 'aal2' | 'aal3';
+type MFAMethod = 'totp' | 'sms_otp' | 'email_otp' | 'recovery_codes';
+type ChallengeSubject = 'sign_in_with_otp' | 'verify_pending_user' | 'sign_up' | 'add_email' | 'add_phone' | 'mfa' | 'sudo';
+/** Methods accepted to elevate a session to sudo. Subset of `MFAMethod`. */
+type SudoMethod = 'totp' | 'email_otp' | 'sms_otp';
+interface Challenge {
+    /** MFA method to present first to the user. */
+    preferred: MFAMethod;
+    /** Masked identifier shown to the user — e.g. "u***@example.com". */
+    identifier?: string;
+    factors: AuthMethod[];
+    subject: ChallengeSubject;
+    /** Short-lived token used to continue the challenge flow. */
+    token: string;
+    expires_in: number;
+}
+interface VerifyChallengeParams {
+    /** Short-lived token from the `Challenge` object. */
+    token: string;
+    /** OTP code, TOTP code, or recovery code entered by the user. */
+    code: string;
+}
+interface ChangeChallengeParams {
+    /** Short-lived token from the current `Challenge`. */
+    token: string;
+    /** MFA method to switch to. */
+    type: MFAMethod;
+}
+type AuthFactorStatus = 'configured' | 'not_configured';
+interface AuthMethod {
+    id?: string;
+    /** MFA method, sign-in method, or OAuth provider. */
+    type: MFAMethod | SignInMethod | OAuthProvider;
+    name?: string;
+    status: AuthFactorStatus;
+    identifier?: string;
+    created_at?: string;
+    updated_at?: string;
+}
+interface AuthMethods {
+    sign_in: AuthMethod[];
+    mfas: AuthMethod[];
+    oauth: AuthMethod[];
+}
+/** Returned by `auth.factors.enroll`. Pass `token` + `code` to `auth.factors.enable`. */
+interface FactorEnrollment {
+    type: MFAMethod;
+    /** Short-lived token to pass to `factors.enable`. */
+    token: string;
+    /** TOTP shared secret for manual entry. */
+    secret?: string;
+    /** TOTP provisioning URL (useful for generating a QR code). */
+    url?: string;
+}
+interface EnableFactorParams {
+    /** Token received from `factors.enroll`. */
+    token: string;
+    /** OTP or TOTP code to confirm enrollment. */
+    code: string;
+}
+interface EnrollFactorParams extends Nonce {
+    type: MFAMethod;
+    name?: string;
+}
+interface UnenrollFactorParams extends Nonce {
+    id: string;
+}
+type IdentityType = 'email' | 'phone' | 'oauth';
+interface Identity {
+    id: string;
+    type: IdentityType;
+    provider_id?: string;
+    provider?: OAuthProvider;
+    identifier: string;
+    data?: Record<string, unknown>;
+    created_at?: string;
+    updated_at?: string;
+}
+interface AddEmailIdentityParams extends Nonce {
+    email: string;
+}
+interface AddPhoneIdentityParams extends Nonce {
+    phone: Phone;
+}
+interface UpdateIdentityParams extends Nonce {
+    id: string;
+    primary: boolean;
+}
+interface RemoveIdentityParams extends Nonce {
+    id: string;
+}
+interface SendOTPToUpdateEmailParams extends Nonce {
+    email: string;
+}
+interface SendOTPToUpdatePhoneParams extends Nonce {
+    phone: Phone;
+}
+type GrantStatus = 'granted' | 'invited' | 'requested' | 'blocked';
+interface Role {
+    id: string;
+    name: string;
+    description?: string;
+    key: string;
+    context: string;
+    scopes: string[];
+    cannot_scopes?: string[];
+}
+interface Grant {
+    id: string;
+    status: GrantStatus;
+    name?: string;
+    email?: string;
+    resource: string;
+    granted_to?: User;
+    role?: Role;
+    scopes: string[];
+    cannot_scopes: string[];
+    created_at?: string;
+    updated_at?: string;
+}
+/** Grouped grants returned by `auth.grants.getMembers`. */
+interface GrantMembers {
+    granted: Grant[];
+    invitations: Grant[];
+    requesteds: Grant[];
+    blockeds: Grant[];
+}
+interface Invite {
+    email: string;
+    role_id?: string;
+    scopes?: string[];
+    cannot_scopes?: string[];
+}
+interface InviteParams extends Nonce {
+    invites: Invite[];
+    resource: string;
+    message?: string;
+}
+interface RevokeGrantParams extends Nonce {
+    id: string;
+}
+interface BlockGrantParams extends Nonce {
+    id: string;
+}
+interface UpdateGrantParams extends Nonce {
+    scopes?: string[];
+    cannot_scopes?: string[];
+}
+interface LeaveGrantParams extends Nonce {
+    id: string;
+}
+interface ChangePasswordParams extends Nonce {
+    password: string;
+    new_password: string;
+}
+interface PlatformInfo {
+    id: string;
+    name: string;
+    slug: string;
+}
+type PaginationSort = 'asc' | 'desc';
+interface Paginated<T> {
+    items: T[];
+    page?: number;
+    page_size?: number;
+    total?: number;
+    sort?: PaginationSort;
+}
+interface PaginateUsersParams {
+    page?: number;
+    page_size?: number;
+    sort?: PaginationSort;
+    id?: string;
+    email?: string;
+    username?: string;
+    phone?: string;
+    is_confirmed?: boolean;
+    is_banned?: boolean;
+}
+interface PaginateGrantsParams {
+    page?: number;
+    page_size?: number;
+    sort?: PaginationSort;
+    resource?: string;
+    context?: string;
+    granted_to_user_id?: string;
+    role_id?: string;
+}
+interface SetGrantParams {
+    resource: string;
+    granted_to_user_id: string;
+    role_id?: string;
+    scopes?: string[];
+    cannot_scopes?: string[];
+}
+interface CreateRoleParams {
+    name: string;
+    description?: string;
+    key: string;
+    context: string;
+    scopes: string[];
+    cannot_scopes?: string[];
+}
+interface UpdateRoleParams {
+    name?: string;
+    description?: string;
+    scopes?: string[];
+    cannot_scopes?: string[];
+}
+interface AdminCreateUserParams {
+    email?: string;
+    phone?: Phone;
+    username?: string;
+    profile?: UserProfile;
+    password?: string;
+    metadata?: Record<string, string | number>;
+}
+interface AdminUpdateUserParams {
+    username?: string;
+    profile?: UserProfile;
+    metadata?: Record<string, string | number | null>;
+}
+/**
+ * Returned by `signUp`, `signIn`, `verifyChallenge`, and `refreshToken`.
+ *
+ * Check in this order:
+ * 1. `access_token` present → authenticated.
+ * 2. `challenge` present → MFA/OTP step required — call `verifyChallenge`.
+ * 3. Only `user` present → pending confirmation (signUp only).
+ */
+interface Authenticated {
+    token_type?: TokenType;
+    access_token?: string;
+    refresh_token?: string;
+    expires_in?: number;
+    user?: User;
+    challenge?: Challenge;
+    /**
+     * Present only when this authentication elevated the session to sudo
+     * (e.g. resolving a sudo challenge via `challenges.verify`).
+     */
+    sudo?: {
+        /** Seconds until sudo mode expires. */
+        expires_in: number;
+    };
+}
+type SignInMethod = 'email_password' | 'username_password' | 'phone_password' | 'email_otp' | 'sms_otp';
+type ConfirmationType = 'none' | 'link' | 'otp';
+type VerifyReason = 'signin_with_otp' | 'verify_after_with_link' | 'requires_otp_for_registration' | 'waiting_confirmation_link' | 'confirmation_link_resent' | 'no_confirmation_required';
+interface LookupMatch {
+    exists: boolean;
+    method: SignInMethod;
+    allowed_methods: SignInMethod[];
+    confirmation_type: ConfirmationType;
+    reason?: VerifyReason;
+}
+/**
+ * Returned by `lookup`.
+ * If `challenge` is present, proceed to `verifyChallenge`.
+ */
+interface LookupResult {
+    lookup: LookupMatch;
+    challenge?: Challenge;
+}
+type SignOutScope = 'global' | 'local' | 'others';
+interface VerifyParams {
+    resource?: string;
+    scopes?: string[];
+    roles?: string[];
+    reject_assurance_level_error?: boolean;
+}
+interface Verified {
+    user: {
+        id: string;
+    };
+    session: {
+        id: string;
+        amr: Array<{
+            method: string;
+            timestamp?: number;
+        }>;
+        scopes: string[];
+        assurance_level: AssuranceLevel;
+        /** Whether sudo mode is currently active for the session. */
+        sudo?: boolean;
+        /** Date-time until sudo mode expires. Null/absent when not elevated. */
+        sudo_expires_at?: string | null;
+    };
+}
+interface SessionFingerPrint {
+    hash?: string;
+    ip?: string;
+    browser?: {
+        name?: string;
+        version?: string;
+    };
+    engine?: {
+        name?: string;
+        version?: string;
+    };
+    cpu?: {
+        architecture?: string;
+    };
+    os?: {
+        name?: string;
+        version?: string;
+    };
+    device?: {
+        name?: string;
+        type?: string;
+    };
+    location?: {
+        country?: string;
+        region?: string;
+        timezone?: string;
+        city?: string;
+        position?: {
+            lat?: number;
+            lng?: number;
+        };
+    };
+}
+interface Session {
+    id: string;
+    finger_print?: SessionFingerPrint;
+    amr: Array<{
+        method: string;
+        timestamp?: number;
+    }>;
+    scopes: string[];
+    aal: AssuranceLevel;
+    invalidated: boolean;
+    is_current_session: boolean;
+    created_at: string;
+    updated_at: string;
+    expires_at: string;
+    sudo_expires_at?: string | null;
+}
+type OAuthAppType = 'public' | 'confidential';
+type OAuthAppTokenEndpointAuthMethod = 'none' | 'client_secret_basic' | 'client_secret_post';
+type OAuthAppGrantType = 'authorization_code' | 'refresh_token';
+/** A registered third-party application (OAuth client) of the project. */
+interface OAuthApp {
+    id: string;
+    client_id: string;
+    client_type: OAuthAppType;
+    token_endpoint_auth_method: OAuthAppTokenEndpointAuthMethod;
+    redirect_uris: string[];
+    grant_types: OAuthAppGrantType[];
+    client_name?: string;
+    client_uri?: string;
+    logo_uri?: string;
+    /** Only present right after create/regenerate (confidential apps). */
+    client_secret?: string;
+    created_at?: string;
+    updated_at?: string;
+}
+interface RegisterOAuthAppParams {
+    client_type: OAuthAppType;
+    token_endpoint_auth_method: OAuthAppTokenEndpointAuthMethod;
+    redirect_uris: string[];
+    grant_types: OAuthAppGrantType[];
+    client_name?: string;
+    client_uri?: string;
+    logo_uri?: string;
+}
+/** `client_type` is immutable; the secret rotates via `regenerateSecret`. */
+interface UpdateOAuthAppParams {
+    token_endpoint_auth_method?: OAuthAppTokenEndpointAuthMethod;
+    redirect_uris?: string[];
+    grant_types?: OAuthAppGrantType[];
+    client_name?: string;
+    client_uri?: string;
+    logo_uri?: string;
+}
+/** Query parameters for the `/oauth/authorize` redirect (PKCE required, S256). */
+interface OAuthAuthorizeParams {
+    client_id: string;
+    redirect_uri: string;
+    code_challenge: string;
+    code_challenge_method: 'S256';
+    response_type?: 'code';
+    scope?: string;
+    state?: string;
+    resource?: string;
+    nonce?: string;
+}
+interface ExchangeOAuthCodeParams {
+    code: string;
+    code_verifier: string;
+    redirect_uri?: string;
+    client_id?: string;
+    /** Only for confidential clients. */
+    client_secret?: string;
+    resource?: string;
+}
+interface RefreshOAuthTokenParams {
+    refresh_token: string;
+    client_id?: string;
+    /** Only for confidential clients. */
+    client_secret?: string;
+}
+interface OAuthTokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    refresh_token?: string;
+    scope: string;
+    id_token?: string;
+}
+interface OAuthAuthorization {
+    client: {
+        id: string;
+        name?: string;
+        logo_uri?: string;
+        uri?: string;
+    };
+    scope: string[];
+    auto_approved: boolean;
+    redirect?: {
+        uri: string;
+    };
+}
+type OAuthConsentAction = 'approve' | 'deny';
+interface OAuthConsentResult {
+    redirect: {
+        uri: string;
+    };
+}
+interface OAuthUserInfo {
+    sub: string;
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    picture?: string;
+    preferred_username?: string;
+    phone_number?: string;
+    phone_number_verified?: boolean;
+}
+/** An app the authenticated user has authorized. */
+interface OAuthUserGrant {
+    client: {
+        id: string;
+        name?: string;
+        logo_uri?: string;
+        uri?: string;
+    };
+    scopes: string[];
+    granted_at: string;
+}
+interface OAuthDiscovery {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    userinfo_endpoint: string;
+    jwks_uri: string;
+    registration_endpoint: string;
+    response_types_supported: string[];
+    subject_types_supported: string[];
+    id_token_signing_alg_values_supported: string[];
+    scopes_supported: string[];
+    token_endpoint_auth_methods_supported: string[];
+    grant_types_supported: string[];
+    code_challenge_methods_supported: string[];
+}
+interface OAuthJWKS {
+    keys: Array<Record<string, unknown>>;
+}
+
+interface StoredSession {
+    access_token: string;
+    refresh_token?: string;
+    /** Unix timestamp (ms) when the access token expires. */
+    expires_at: number;
+    token_type: string;
+    /** Full user object from the auth response, when provided by the server. */
+    user?: User;
+}
+
+type RefreshFn = (refresh_token: string) => Promise<NulvlessResult<Authenticated>>;
+type TokenRefreshedCb = (auth: Authenticated) => void;
+/** Receives the session that could not be recovered (null when none was stored). */
+type UnauthorizedCb = (session: StoredSession | null) => void;
+declare class SessionManager {
+    private readonly storage;
+    private refreshFn?;
+    private onTokenRefreshed?;
+    private onUnauthorized?;
+    private readonly sessionKey;
+    private readonly lockName;
+    private inFlight;
+    private ticker;
+    private onVisibilityChange;
+    constructor(storage: NulvlessStorage, sessionKey: string);
+    /**
+     * Injected by `AuthClient` after construction to avoid circular dependency.
+     * Called automatically when the access token is about to expire.
+     */
+    setRefreshFn(fn: RefreshFn): void;
+    /** Called after a successful automatic token refresh. */
+    setOnTokenRefreshed(cb: TokenRefreshedCb): void;
+    /**
+     * Called when the SDK cannot recover the session:
+     * - no refresh token present, or
+     * - the refresh request was refused by the server.
+     */
+    setOnUnauthorized(cb: UnauthorizedCb): void;
+    save(auth: Authenticated): Promise<void>;
+    get(): Promise<StoredSession | null>;
+    clear(): Promise<void>;
+    private expiresSoon;
+    private refresh;
+    private runExclusiveRefresh;
+    private refreshHoldingLock;
+    private callRefreshFn;
+    /**
+     * Forces a token refresh regardless of expiry.
+     * Used for reactive refresh after a 401/403 response.
+     *
+     * Returns the new access token, or `null` if refresh fails.
+     *
+     * `deauthOnFailure` (default `true`) controls side effects when the refresh
+     * itself is refused: clearing the stored session and invoking `onUnauthorized`.
+     * Pass `false` for soft refreshes (e.g. 403/forbidden_resource_access) where
+     * the session must remain intact so the caller can surface the API error.
+     */
+    forceRefresh(options?: {
+        deauthOnFailure?: boolean;
+        expiredToken?: string;
+    }): Promise<string | null>;
+    /**
+     * Returns a valid access token, refreshing it automatically if it is
+     * expired or about to expire (within the refresh margin).
+     *
+     * Returns `null` when there is no session or the refresh fails.
+     */
+    getValidToken(): Promise<string | null>;
+    startAutoRefresh(): void;
+    stopAutoRefresh(): void;
+    private tick;
+}
+
+type BearerResolution = {
+    ok: true;
+    headers: Record<string, string>;
+} | {
+    ok: false;
+    error: NulvlessError;
+};
+declare abstract class AuthSubClient {
+    protected readonly http: HttpClient;
+    protected readonly getToken: () => Promise<string | null>;
+    constructor(http: HttpClient, getToken: () => Promise<string | null>);
+    protected bearer(options?: RequestOptions): Promise<BearerResolution>;
+}
+
+/**
+ * MFA factor management.
+ *
+ * Available on both `createClient` (browser) and `createServerClient` (server).
+ *
+ * All methods require authentication. Pass `options.headers.Authorization` on
+ * the server, or rely on the configured storage for automatic token injection.
+ */
+declare class FactorsClient extends AuthSubClient {
+    /**
+     * Lists all configured MFA factors for the authenticated user.
+     */
+    list(options?: RequestOptions): Promise<NulvlessResult<AuthMethod[]>>;
+    /**
+     * Returns the user's recovery codes.
+     *
+     * Requires sudo: `MANAGE_MFA`.
+     */
+    getRecoveryCodes(params?: Nonce, options?: RequestOptions): Promise<NulvlessResult<{
+        codes: string[];
+    }>>;
+    /**
+     * Deletes (invalidates) the user's recovery codes.
+     *
+     * Requires sudo: `MANAGE_MFA`.
+     */
+    deleteRecoveryCodes(params?: Nonce, options?: RequestOptions): Promise<NulvlessResult<null>>;
+    /**
+     * Begins enrolling a new MFA factor. Returns credentials needed to configure
+     * the factor on the user's device.
+     *
+     * For TOTP: use `secret` for manual entry or `url` to generate a QR code.
+     *
+     * After the user configures their device, call `enable` with the `token` and
+     * the first OTP code to activate the factor.
+     *
+     * Requires sudo: `MANAGE_MFA`.
+     *
+     * @example
+     * const { data } = await nulvless.auth.factors.enroll({ type: 'totp', name: 'My Authenticator' })
+     * // data.url → QR code provisioning URL
+     * // data.secret → manual entry secret
+     * // data.token → pass to factors.enable
+     */
+    enroll(params: EnrollFactorParams, options?: RequestOptions): Promise<NulvlessResult<FactorEnrollment>>;
+    /**
+     * Activates a pending factor enrollment by confirming the first OTP code.
+     *
+     * Pass the `token` from `enroll` and the code generated by the user's device.
+     */
+    enable(params: EnableFactorParams, options?: RequestOptions): Promise<NulvlessResult<null>>;
+    /**
+     * Unenrolls (removes) an MFA factor by its ID.
+     *
+     * Use `factors.list()` to retrieve the factor `id` before calling this.
+     * Returns the removed factor.
+     *
+     * Requires sudo: `MANAGE_MFA`.
+     *
+     * @example
+     * const { data: factors } = await nulvless.auth.factors.list()
+     * const totp = factors?.find(f => f.type === 'totp')
+     * if (totp?.id) await nulvless.auth.factors.unenroll({ id: totp.id })
+     */
+    unenroll(params: UnenrollFactorParams, options?: RequestOptions): Promise<NulvlessResult<AuthMethod>>;
+}
+
+/**
+ * Current-user management.
+ *
+ * Available on both `createClient` (browser) and `createServerClient` (server).
+ *
+ * All methods require authentication. Pass `options.headers.Authorization` on
+ * the server, or rely on the configured storage for automatic token injection.
+ */
+declare class UsersClient extends AuthSubClient {
+    /**
+     * Returns the authenticated user's full profile.
+     */
+    me(options?: RequestOptions): Promise<NulvlessResult<User>>;
+    /**
+     * Updates the authenticated user's profile fields.
+     *
+     * Omit fields to leave them unchanged.
+     */
+    update(params: {
+        username?: string;
+        profile?: UserProfile;
+    }, options?: RequestOptions): Promise<NulvlessResult<User>>;
+    /**
+     * Lists all identities (email, phone, OAuth) linked to the authenticated user.
+     *
+     * @param type Filter by identity type: `'email'`, `'phone'`, or `'oauth'`.
+     */
+    getIdentities(type?: IdentityType, options?: RequestOptions): Promise<NulvlessResult<Identity[]>>;
+    /**
+     * Initiates adding a new email identity. Sends an OTP to the provided address.
+     *
+     * Complete the flow with `verifyIdentity`.
+     *
+     * Requires sudo: `MANAGE_IDENTITIES`.
+     */
+    addEmailIdentity(params: AddEmailIdentityParams, options?: RequestOptions): Promise<NulvlessResult<Challenge>>;
+    /**
+     * Initiates adding a new phone identity. Sends an OTP to the provided number.
+     *
+     * Complete the flow with `verifyIdentity`.
+     *
+     * Requires sudo: `MANAGE_IDENTITIES`.
+     */
+    addPhoneIdentity(params: AddPhoneIdentityParams, options?: RequestOptions): Promise<NulvlessResult<Challenge>>;
+    /**
+     * Confirms an identity addition by submitting the OTP received via
+     * `addEmailIdentity` or `addPhoneIdentity`.
+     */
+    verifyIdentity(params: VerifyChallengeParams, options?: RequestOptions): Promise<NulvlessResult<User>>;
+    /**
+     * Updates an identity — currently used to set an identity as primary.
+     *
+     * Requires sudo: `MANAGE_IDENTITIES`.
+     */
+    updateIdentity(params: UpdateIdentityParams, options?: RequestOptions): Promise<NulvlessResult<User>>;
+    /**
+     * Unlinks (removes) an identity from the authenticated user.
+     *
+     * Requires sudo: `MANAGE_IDENTITIES`.
+     */
+    removeIdentity(params: RemoveIdentityParams, options?: RequestOptions): Promise<NulvlessResult<Identity>>;
+    /**
+     * Sends an OTP to the new email address to initiate an email change.
+     *
+     * Complete the flow with `confirmEmailUpdate`.
+     *
+     * Requires sudo: `MANAGE_CREDENTIALS`.
+     */
+    sendOTPToUpdateEmail(params: SendOTPToUpdateEmailParams, options?: RequestOptions): Promise<NulvlessResult<{
+        token: string;
+    }>>;
+    /**
+     * Confirms an email change by submitting the OTP received via `sendOTPToUpdateEmail`.
+     */
+    confirmEmailUpdate(params: VerifyChallengeParams, options?: RequestOptions): Promise<NulvlessResult<User>>;
+    /**
+     * Sends an OTP to the new phone number to initiate a phone change.
+     *
+     * Complete the flow with `confirmPhoneUpdate`.
+     *
+     * Requires sudo: `MANAGE_CREDENTIALS`.
+     */
+    sendOTPToUpdatePhone(params: SendOTPToUpdatePhoneParams, options?: RequestOptions): Promise<NulvlessResult<{
+        token: string;
+    }>>;
+    /**
+     * Confirms a phone change by submitting the OTP received via `sendOTPToUpdatePhone`.
+     */
+    confirmPhoneUpdate(params: VerifyChallengeParams, options?: RequestOptions): Promise<NulvlessResult<User>>;
+}
+
+/**
+ * Active session management for the authenticated user.
+ *
+ * Available on both `createClient` (browser) and `createServerClient` (server).
+ *
+ * All methods require authentication. Pass `options.headers.Authorization` on
+ * the server, or rely on the configured storage for automatic token injection.
+ */
+declare class SessionsClient extends AuthSubClient {
+    private readonly persist;
+    constructor(http: HttpClient, getToken: () => Promise<string | null>, persist: (result: NulvlessResult<Authenticated>) => Promise<NulvlessResult<Authenticated>>);
+    /**
+     * Returns all active sessions for the authenticated user across all devices.
+     * The current session is marked with `is_current_session: true`.
+     */
+    list(options?: RequestOptions): Promise<NulvlessResult<Session[]>>;
+    /**
+     * Revokes (invalidates) a specific session by its ID.
+     *
+     * Use `auth.getSession()` to get the current session ID.
+     *
+     * Requires sudo: `MANAGE_SESSIONS`.
+     */
+    revoke(params: RevokeSessionParams, options?: RequestOptions): Promise<NulvlessResult<null>>;
+    /**
+     * Starts a sudo elevation by requesting a verification challenge.
+     *
+     * The available methods are derived from what the user has (TOTP if active,
+     * email OTP, SMS OTP). Pass `method` to request a specific one; if omitted and
+     * the user has a single method it is emitted automatically, otherwise an empty
+     * challenge is returned so the user can pick which one to send.
+     *
+     * Prompt the user for the code, then call `sudoVerify({ code })` to complete
+     * the elevation. The verify response carries `sudo.expires_in` (seconds until
+     * sudo mode expires) alongside the refreshed session tokens.
+     *
+     * @example
+     * const { data } = await nulvless.auth.sessions.sudo() // or sudo('email_otp')
+     * // prompt the user for the code, then call sudoVerify({ code })
+     */
+    sudo(method?: SudoMethod, options?: RequestOptions): Promise<NulvlessResult<{
+        challenge: Challenge;
+    }>>;
+    /**
+     * Completes a sudo elevation started by `sudo()`. Submit the `code` the user
+     * received (or read from their authenticator) — the pending sudo challenge is
+     * resolved by the current session, so no challenge token is needed.
+     *
+     * On success the session is re-issued with sudo mode active and stored
+     * automatically; `data.sudo.expires_in` carries the seconds until it expires.
+     *
+     * @example
+     * const { data } = await nulvless.auth.sessions.sudoVerify({ code })
+     * // data.sudo?.expires_in → 300
+     */
+    sudoVerify(params: {
+        code: string;
+    }, options?: RequestOptions): Promise<NulvlessResult<Authenticated>>;
+    /**
+     * Verifies that sudo mode is currently active for the session.
+     *
+     * Returns `204 No Content` on success. Returns an error if sudo is not active.
+     *
+     * @example
+     * const { error } = await nulvless.auth.sessions.checkSudo()
+     * if (error) {
+     *   // Start the sudo flow: sessions.sudo() → sessions.sudoVerify
+     * }
+     */
+    checkSudo(params?: Nonce, options?: RequestOptions): Promise<NulvlessResult<null>>;
+}
+
+/**
+ * Account security operations (password).
+ *
+ * Available on both `createClient` (browser) and `createServerClient` (server).
+ *
+ * All methods require authentication. Pass `options.headers.Authorization` on
+ * the server, or rely on the configured storage for automatic token injection.
+ */
+declare class SecurityClient extends AuthSubClient {
+    /**
+     * Changes the authenticated user's password.
+     *
+     * @example
+     * await nulvless.auth.security.changePassword({
+     *   password: 'current-password',
+     *   new_password: 'new-password',
+     * })
+     */
+    changePassword(params: ChangePasswordParams, options?: RequestOptions): Promise<NulvlessResult<null>>;
+}
+
+/**
+ * Challenge lifecycle — create, inspect, switch method, and verify.
+ *
+ * Mirrors the `/challenges` resource. Used by MFA, OTP sign-in, sign-up
+ * confirmation and step-up (sudo) flows.
+ *
+ * Available on both `createClient` (browser) and `createServerClient` (server).
+ */
+declare class ChallengesClient extends AuthSubClient {
+    private readonly persist;
+    constructor(http: HttpClient, getToken: () => Promise<string | null>, persist: (result: NulvlessResult<Authenticated>) => Promise<NulvlessResult<Authenticated>>);
+    /**
+     * Creates a verification challenge for the given MFA method (step-up).
+     *
+     * Requires an authenticated session. Prompt the user for the code, then call
+     * `verify({ token, code })`.
+     *
+     * @example
+     * const { data } = await nulvless.auth.challenges.create('totp')
+     */
+    create(targetType: MFAMethod, options?: RequestOptions): Promise<NulvlessResult<{
+        challenge: Challenge;
+    }>>;
+    /**
+     * Retrieves the current state of a challenge by its token.
+     */
+    get(token: string, options?: RequestOptions): Promise<NulvlessResult<Challenge>>;
+    /**
+     * Switches the preferred MFA method for an ongoing challenge.
+     *
+     * @example
+     * const { data } = await nulvless.auth.challenges.change({ token, type: 'totp' })
+     */
+    change(params: ChangeChallengeParams, options?: RequestOptions): Promise<NulvlessResult<{
+        challenge: Challenge;
+    }>>;
+    /**
+     * Verifies a challenge by submitting the token and the code entered by the user.
+     *
+     * Used for OTP sign-in, MFA verification after `signIn`, and sign-up
+     * confirmation. Session is stored automatically when the response contains an
+     * access token.
+     */
+    verify(params: VerifyChallengeParams, options?: RequestOptions): Promise<NulvlessResult<Authenticated>>;
+}
+
+/**
+ * Grant management for the authenticated user.
+ *
+ * Available on `createServerClient` only (requires private key `sk_`).
+ *
+ * All methods require authentication. Pass `options.headers.Authorization` to
+ * forward the user's bearer token on each server-side call.
+ */
+declare class GrantsClient extends AuthSubClient {
+    /**
+     * Returns all grants granted to the authenticated user, optionally
+     * filtered by context.
+     */
+    list(context?: string, options?: RequestOptions): Promise<NulvlessResult<Grant[]>>;
+    /**
+     * Returns all grants for a given resource, grouped by status
+     * (granted, invited, requested, blocked).
+     *
+     * The authenticated user must own or manage the resource.
+     */
+    getMembers(resource: string, options?: RequestOptions): Promise<NulvlessResult<GrantMembers>>;
+    /**
+     * Creates grant invitations for one or more users on a resource.
+     *
+     * Each invite sends a notification to the target email address.
+     *
+     * Requires sudo: `MANAGE_GRANTS`.
+     *
+     * @example
+     * await nulvless.auth.grants.invite({
+     *   resource: 'project-123',
+     *   invites: [{ email: 'user@example.com', scopes: ['read', 'write'] }],
+     * })
+     */
+    invite(params: InviteParams, options?: RequestOptions): Promise<NulvlessResult<Grant[]>>;
+    /**
+     * Returns a single grant by ID.
+     */
+    get(id: string, options?: RequestOptions): Promise<NulvlessResult<Grant>>;
+    /**
+     * Revokes (removes) a grant.
+     *
+     * Requires sudo: `MANAGE_GRANTS`.
+     */
+    revoke(params: RevokeGrantParams, options?: RequestOptions): Promise<NulvlessResult<Grant>>;
+    /**
+     * Accepts a pending invitation (`status: 'invited'`).
+     */
+    accept(id: string, options?: RequestOptions): Promise<NulvlessResult<Grant>>;
+    /**
+     * Cancels a pending invitation or request (`status: 'invited'` or `'requested'`).
+     */
+    cancel(id: string, options?: RequestOptions): Promise<NulvlessResult<Grant>>;
+    /**
+     * Blocks a grant.
+     *
+     * Requires sudo: `MANAGE_GRANTS`.
+     */
+    block(params: BlockGrantParams, options?: RequestOptions): Promise<NulvlessResult<Grant>>;
+    /**
+     * Updates the scopes of an existing grant.
+     *
+     * Requires sudo: `MANAGE_GRANTS`.
+     */
+    update(id: string, params: UpdateGrantParams, options?: RequestOptions): Promise<NulvlessResult<Grant>>;
+    /**
+     * Removes the authenticated user from a resource they were granted access to.
+     *
+     * Requires sudo: `MANAGE_GRANTS`.
+     */
+    leave(params: LeaveGrantParams, options?: RequestOptions): Promise<NulvlessResult<Grant>>;
+}
+
+/**
+ * Manages the OAuth apps the authenticated user has authorized
+ * (`/user/oauth/grants`). Requires authentication (bearer token).
+ */
+declare class OAuthGrantsClient extends AuthSubClient {
+    /**
+     * Lists the apps the authenticated user has granted access to.
+     */
+    list(options?: RequestOptions): Promise<NulvlessResult<OAuthUserGrant[]>>;
+    /**
+     * Revokes a previously granted app by its public `client_id`.
+     * Also invalidates the app's active sessions for this user.
+     */
+    revoke(clientId: string, options?: RequestOptions): Promise<NulvlessResult<null>>;
+}
+/**
+ * The project's OAuth 2.1 / OpenID Connect provider surface — the project
+ * acting as an identity provider for third-party applications.
+ *
+ * Available with both public (`pk_`) and private (`sk_`) keys
+ * (`@SetPlatformGuardRoles([PUBLIC, PRIVATE])`).
+ *
+ * Method scopes:
+ * - `token`, `register` — platform key only (no bearer token).
+ * - `getAuthorization`, `consent`, `userinfo`, and the `grants` namespace —
+ *   authenticated user (bearer token).
+ * - `discovery`, `jwks` — public OIDC metadata (no auth).
+ *
+ * The `/oauth/authorize` entry point is a browser redirect (302), not a JSON
+ * API — build it from `discovery().authorization_endpoint` and redirect the
+ * user agent there.
+ */
+declare class OAuthClient extends AuthSubClient {
+    /** Apps the authenticated user has authorized — list and revoke. */
+    readonly grants: OAuthGrantsClient;
+    constructor(http: HttpClient, getToken: () => Promise<string | null>);
+    /**
+     * Builds the OAuth authorization URL and, in the browser, redirects the user
+     * agent to it. On the server the URL is returned for manual handling.
+     *
+     * Mirrors `auth.authorize` (social sign-in): redirects automatically in the
+     * browser, returns `data.url` on the server. The endpoint itself is a 302
+     * redirect, so the URL is composed from the discovery `authorization_endpoint`.
+     *
+     * PKCE is required (RFC 7636, https://www.rfc-editor.org/rfc/rfc7636): provide
+     * `code_challenge` = BASE64URL(SHA256(code_verifier)) with
+     * `code_challenge_method: 'S256'`. Send the `code_verifier` later to
+     * `exchangeCodeForToken`.
+     *
+     * @example
+     * // Browser — redirects automatically
+     * await nulvless.auth.oauth.authorize({ client_id, redirect_uri, code_challenge, code_challenge_method: 'S256' })
+     *
+     * // Server — use the returned URL
+     * const { data } = await nulvless.auth.oauth.authorize(params)
+     * return Response.redirect(data.url)
+     */
+    authorize(params: OAuthAuthorizeParams, options?: RequestOptions): Promise<NulvlessResult<{
+        url: string;
+    }>>;
+    /**
+     * Exchanges an authorization code for tokens
+     * (`POST /oauth/token`, `grant_type=authorization_code`).
+     *
+     * Called by the relying-party app after the user is redirected back with the
+     * `code`. PKCE `code_verifier` is required; `client_secret` only for
+     * confidential clients. Public endpoint — no platform key.
+     */
+    exchangeCodeForToken(params: ExchangeOAuthCodeParams, options?: RequestOptions): Promise<NulvlessResult<OAuthTokenResponse>>;
+    /**
+     * Refreshes an access token using a refresh token
+     * (`POST /oauth/token`, `grant_type=refresh_token`).
+     *
+     * `client_secret` only for confidential clients. Public endpoint — no
+     * platform key.
+     */
+    refreshToken(params: RefreshOAuthTokenParams, options?: RequestOptions): Promise<NulvlessResult<OAuthTokenResponse>>;
+    /**
+     * Dynamically registers a new OAuth app (RFC 7591, `POST /oauth/register`).
+     *
+     * Requires the OAuth server to be enabled with dynamic client registration
+     * allowed. For server-side managed registration use `admin.oauthClients`.
+     */
+    register(params: RegisterOAuthAppParams, options?: RequestOptions): Promise<NulvlessResult<OAuthApp>>;
+    /**
+     * Loads a pending authorization for the consent screen
+     * (`GET /oauth/authorizations/:id`).
+     *
+     * Claims the authorization for the authenticated user. When a matching
+     * consent already exists it is auto-approved and `redirect.uri` is returned.
+     *
+     * Requires authentication.
+     */
+    getAuthorization(authorizationId: string, options?: RequestOptions): Promise<NulvlessResult<OAuthAuthorization>>;
+    /**
+     * Approves or denies a pending authorization
+     * (`POST /oauth/authorizations/:id/consent`).
+     *
+     * Returns the `redirect.uri` to send the user agent back to (carrying the
+     * authorization `code` on approve, or `error=access_denied` on deny).
+     *
+     * Requires authentication.
+     */
+    consent(authorizationId: string, action: OAuthConsentAction, options?: RequestOptions): Promise<NulvlessResult<OAuthConsentResult>>;
+    /**
+     * Returns OIDC UserInfo claims for the access token (`GET /oauth/userinfo`).
+     *
+     * The access token must have been issued with the `openid` scope.
+     *
+     * Requires authentication.
+     */
+    userinfo(options?: RequestOptions): Promise<NulvlessResult<OAuthUserInfo>>;
+    /**
+     * Returns the OpenID Connect discovery document
+     * (`GET /.well-known/openid-configuration`). Public — no auth required.
+     */
+    discovery(options?: RequestOptions): Promise<NulvlessResult<OAuthDiscovery>>;
+    /**
+     * Returns the JSON Web Key Set used to verify issued tokens
+     * (`GET /.well-known/jwks.json`). Public — no auth required.
+     */
+    jwks(options?: RequestOptions): Promise<NulvlessResult<OAuthJWKS>>;
+}
+
+/**
+ * Admin operations on platform users.
+ * Requires private key (`sk_`). No bearer token needed.
+ */
+declare class AdminUsersClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Creates a new user bypassing normal sign-up flows.
+     */
+    create(params: AdminCreateUserParams, options?: RequestOptions): Promise<NulvlessResult<User>>;
+    /**
+     * Lists users with pagination and optional filters.
+     */
+    list(params?: PaginateUsersParams, options?: RequestOptions): Promise<NulvlessResult<Paginated<User>>>;
+    /**
+     * Returns a single user by ID.
+     */
+    get(userId: string, options?: RequestOptions): Promise<NulvlessResult<User>>;
+    /**
+     * Updates a user's profile fields.
+     */
+    update(userId: string, params: AdminUpdateUserParams, options?: RequestOptions): Promise<NulvlessResult<User>>;
+    /**
+     * Permanently deletes a user.
+     */
+    delete(userId: string, options?: RequestOptions): Promise<NulvlessResult<User>>;
+    /**
+     * Bans a user, preventing them from signing in.
+     */
+    ban(userId: string, options?: RequestOptions): Promise<NulvlessResult<User>>;
+    /**
+     * Lifts a ban on a user.
+     */
+    unban(userId: string, options?: RequestOptions): Promise<NulvlessResult<User>>;
+    /**
+     * Returns all active sessions for a specific user.
+     */
+    getSessions(userId: string, options?: RequestOptions): Promise<NulvlessResult<Session[]>>;
+    /**
+     * Invalidates all sessions for a specific user (signs them out everywhere).
+     */
+    signOutAll(userId: string, options?: RequestOptions): Promise<NulvlessResult<null>>;
+    /**
+     * Invalidates a specific session for a user.
+     */
+    revokeSession(userId: string, sessionId: string, options?: RequestOptions): Promise<NulvlessResult<Session>>;
+    /**
+     * Returns all configured MFA factors for a specific user.
+     */
+    getFactors(userId: string, options?: RequestOptions): Promise<NulvlessResult<AuthMethod[]>>;
+    /**
+     * Removes a specific MFA factor from a user.
+     */
+    removeFactor(userId: string, factorId: string, options?: RequestOptions): Promise<NulvlessResult<null>>;
+}
+/**
+ * Role management. Requires private key (`sk_`). No bearer token needed.
+ */
+declare class AdminRolesClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Returns all roles, optionally filtered by context.
+     */
+    list(context?: string, options?: RequestOptions): Promise<NulvlessResult<Role[]>>;
+    /**
+     * Creates a new role with the given scopes.
+     */
+    create(params: CreateRoleParams, options?: RequestOptions): Promise<NulvlessResult<Role>>;
+    /**
+     * Updates an existing role.
+     */
+    update(role_id: string, params: UpdateRoleParams, options?: RequestOptions): Promise<NulvlessResult<Role>>;
+    /**
+     * Deletes a role.
+     */
+    delete(role_id: string, options?: RequestOptions): Promise<NulvlessResult<null>>;
+}
+/**
+ * Platform-level grant management.
+ * Requires private key (`sk_`). No bearer token needed.
+ */
+declare class AdminGrantsClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Lists grants with pagination and optional filters.
+     */
+    list(params?: PaginateGrantsParams, options?: RequestOptions): Promise<NulvlessResult<Paginated<Grant>>>;
+    /**
+     * Creates or upserts a grant for a user on a resource.
+     */
+    set(params: SetGrantParams, options?: RequestOptions): Promise<NulvlessResult<Grant>>;
+    /**
+     * Deletes a grant by ID.
+     */
+    delete(grantId: string, options?: RequestOptions): Promise<NulvlessResult<null>>;
+    /**
+     * Removes all grants associated with a resource.
+     *
+     * Use with caution — this will revoke access for all users on the resource.
+     */
+    deleteByResource(resource: string, options?: RequestOptions): Promise<NulvlessResult<null>>;
+}
+/**
+ * Manage the project's OAuth applications (clients) — the third-party apps
+ * allowed to authenticate users through the project's OAuth server.
+ *
+ * Requires private key (`sk_`). No bearer token needed.
+ */
+declare class AdminOAuthClientsClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Registers a new OAuth app. For confidential apps the response includes a
+     * one-time `client_secret` — store it securely, it is never returned again.
+     */
+    create(params: RegisterOAuthAppParams, options?: RequestOptions): Promise<NulvlessResult<OAuthApp>>;
+    /**
+     * Lists all registered OAuth apps.
+     */
+    list(options?: RequestOptions): Promise<NulvlessResult<OAuthApp[]>>;
+    /**
+     * Returns a single OAuth app by its internal id.
+     */
+    get(id: string, options?: RequestOptions): Promise<NulvlessResult<OAuthApp>>;
+    /**
+     * Updates an OAuth app. `client_type` is immutable and the secret rotates via
+     * `regenerateSecret` — neither can be changed here.
+     */
+    update(id: string, params: UpdateOAuthAppParams, options?: RequestOptions): Promise<NulvlessResult<OAuthApp>>;
+    /**
+     * Deletes an OAuth app.
+     */
+    delete(id: string, options?: RequestOptions): Promise<NulvlessResult<null>>;
+    /**
+     * Rotates the client secret (confidential apps only). The new `client_secret`
+     * is returned once — the previous one stops working immediately.
+     */
+    regenerateSecret(id: string, options?: RequestOptions): Promise<NulvlessResult<OAuthApp>>;
+}
+/**
+ * Admin namespace — platform management operations.
+ *
+ * Available on `createServerClient` only (requires private key `sk_`).
+ * No bearer token is required for any method in this namespace.
+ *
+ * Sub-namespaces:
+ * - `admin.users` — create, list, update, delete users; manage sessions & factors
+ * - `admin.roles` — create, list, update, delete roles
+ * - `admin.grants` — set, list, delete platform grants
+ * - `admin.oauthClients` — register and manage OAuth apps (clients)
+ */
+declare class AdminClient {
+    private readonly http;
+    readonly users: AdminUsersClient;
+    readonly roles: AdminRolesClient;
+    readonly grants: AdminGrantsClient;
+    readonly oauthClients: AdminOAuthClientsClient;
+    constructor(http: HttpClient);
+    /**
+     * Returns basic platform information (id, name, slug).
+     */
+    getPlatform(options?: RequestOptions): Promise<NulvlessResult<PlatformInfo>>;
+}
+
+interface AccountEntry {
+    userId: string;
+    access_token: string;
+    /** Seconds remaining until the token expires. May be negative if already expired. */
+    expires_in: number;
+    refresh_token?: string;
+    user?: User;
+}
+
+interface AuthEvents {
+    /** Emitted when a sign-in or sign-up succeeds and an access token is stored. */
+    'signed-in': Authenticated;
+    /** Emitted after `signOut` succeeds. */
+    'signed-out': {
+        userId?: string;
+    };
+    /** Emitted when the server returns a challenge (MFA/OTP) with no access token. */
+    'challenge': Authenticated;
+    /** Emitted after the access token is refreshed automatically. */
+    'token-refreshed': Authenticated;
+    /** Emitted when `switch()` succeeds. */
+    'account-switched': {
+        userId: string;
+    };
+    /**
+     * Emitted when the SDK cannot authenticate the user:
+     * - there is no refresh token, or
+     * - a refresh attempt was rejected by the server (401 / `unauthorized`).
+     *
+     * The payload carries the failed session (its `user` when known), so
+     * multi-user callers can remove the right entry from the accounts store.
+     */
+    'unauthorized': Authenticated;
+    /**
+     * Emitted when any request fails with `403 protected_action_denied`,
+     * meaning the action requires an active sudo session.
+     * Run the sudo flow (`auth.sessions.sudo()` → `auth.challenges.verify()`)
+     * to activate sudo mode, then retry.
+     */
+    'sudo-required': void;
+}
+type Listener<T> = T extends void ? () => void : (payload: T) => void;
+type UnsubscribeFn = () => void;
+declare class AuthEventEmitter {
+    private readonly listeners;
+    on<K extends keyof AuthEvents>(event: K, handler: Listener<AuthEvents[K]>): UnsubscribeFn;
+    emit<K extends keyof AuthEvents>(...args: AuthEvents[K] extends void ? [event: K] : [event: K, payload: AuthEvents[K]]): void;
+    removeAllListeners(event?: keyof AuthEvents): void;
+}
+
+/**
+ * Auth methods accessible with both public (`pk_`) and private (`sk_`) keys.
+ * Corresponds to endpoints decorated with `@SetPlatformGuardRoles([PUBLIC, PRIVATE])`.
+ */
+declare class AuthClient {
+    protected readonly http: HttpClient;
+    protected readonly session?: SessionManager | undefined;
+    /** MFA factor management — enroll, enable, disable, recovery codes. */
+    readonly factors: FactorsClient;
+    /** Current-user management — profile, identities, credential updates. */
+    readonly users: UsersClient;
+    /** Active session management — list, revoke, sudo mode. */
+    readonly sessions: SessionsClient;
+    /** Account security — change password. */
+    readonly security: SecurityClient;
+    /** Challenge lifecycle — create, get, change, verify (MFA / OTP / step-up). */
+    readonly challenges: ChallengesClient;
+    /** OAuth server (project as OIDC provider) — token, consent, userinfo, grants, discovery. */
+    readonly oauth: OAuthClient;
+    protected readonly _getToken: () => Promise<string | null>;
+    constructor(http: HttpClient, session?: SessionManager | undefined);
+    /**
+     * Returns the current active access token from storage.
+     * Refreshes automatically if the token is expired or about to expire.
+     * Returns `null` when there is no active session.
+     */
+    getAccessToken(): Promise<string | null>;
+    protected persistSession(result: NulvlessResult<Authenticated>): Promise<NulvlessResult<Authenticated>>;
+    /**
+     * Creates a new user account.
+     *
+     * At least one of `email`, `phone`, or `username` must be provided.
+     *
+     * Check the response in this order:
+     * 1. `data.access_token` → authenticated immediately — session stored automatically.
+     * 2. `data.challenge` → MFA/OTP step required — call `verifyChallenge`.
+     * 3. `data.user` only → pending email/phone confirmation.
+     */
+    signUp(params: SignUpParams, options?: RequestOptions): Promise<NulvlessResult<Authenticated>>;
+    /**
+     * Signs in with password (`grant_type=password`).
+     *
+     * At least one of `email`, `phone`, or `username` must be provided.
+     *
+     * Check the response in this order:
+     * 1. `data.access_token` → signed in — session stored automatically.
+     * 2. `data.challenge` → MFA step required — call `verifyChallenge`.
+     */
+    signIn(params: SignInParams, options?: RequestOptions): Promise<NulvlessResult<Authenticated>>;
+    /**
+     * Requests a one-time password sent to the user's email or phone.
+     *
+     * Returns a `Challenge` (`202 Accepted`). Pass the received code to `verifyChallenge`.
+     *
+     * At least one of `email` or `phone` must be provided.
+     */
+    signInWithOTP(params: SignInWithOTPParams, options?: RequestOptions): Promise<NulvlessResult<Challenge>>;
+    /**
+     * Initiates an OAuth sign-in flow for the given provider.
+     *
+     * In a browser environment the user is redirected automatically to the
+     * authorization URL. On the server the URL is returned for manual handling.
+     *
+     * After the redirect, the server-side callback exchanges the code automatically
+     * and redirects back to `options.redirect_uri`. For server-side code exchange, use `exchangeCodeForToken`.
+     *
+     * @example
+     * // Browser — redirects automatically
+     * await nulvless.auth.authorize('google', { redirect_uri: 'https://myapp.com/callback' })
+     *
+     * // Server — use the returned URL
+     * const { data } = await nulvless.auth.authorize('google', { redirect_uri: 'https://myapp.com/callback' })
+     * return Response.redirect(data.url)
+     */
+    authorize(provider: OAuthProvider, options?: RequestOptions): Promise<NulvlessResult<{
+        url: string;
+        provider: OAuthProvider;
+    }>>;
+    /**
+     * Initiates an OAuth flow to connect a new provider to the authenticated user's account.
+     *
+     * Same behaviour as `authorize`, but for users who are already signed in — the resulting
+     * provider identity is linked to the current account instead of starting a sign-in flow.
+     *
+     * In a browser environment the user is redirected automatically to the
+     * authorization URL. On the server the URL is returned for manual handling.
+     *
+     * Requires authentication. Token is resolved automatically from storage
+     * (browser) or from `options.headers.Authorization` (server).
+     *
+     * @example
+     * await nulvless.auth.connect('github', { redirect_uri: 'https://myapp.com/settings/connections' })
+     */
+    connect(provider: OAuthProvider, options?: RequestOptions): Promise<NulvlessResult<{
+        url: string;
+        provider: OAuthProvider;
+    }>>;
+    /**
+     * Signs in with an ID token issued by a third-party OAuth provider.
+     *
+     * Useful for mobile apps where you obtain the ID token natively (e.g. Google Sign-In SDK).
+     *
+     * Session is stored automatically when the response contains an access token.
+     *
+     * @example
+     * const { data } = await nulvless.auth.signInWithIdToken('google', googleIdToken)
+     */
+    signInWithIdToken(provider: OAuthProvider, idToken: string, options?: RequestOptions): Promise<NulvlessResult<Authenticated>>;
+    /**
+     * Exchanges an OAuth authorization code for an access token
+     * (`grant_type=authorization_code`).
+     *
+     * Must be called with `Content-Type: application/x-www-form-urlencoded`.
+     * The `code` must be the authorization code received from the OAuth callback.
+     *
+     * Session is stored automatically when the response contains an access token.
+     *
+     * @example
+     * const { data } = await nulvless.auth.exchangeCodeForToken('auth-code-from-callback')
+     */
+    exchangeCodeForToken(code: string, options?: RequestOptions): Promise<NulvlessResult<Authenticated>>;
+    /**
+     * Returns all sign-in methods, MFA factors, and OAuth providers configured
+     * for the authenticated user on this platform.
+     *
+     * Requires authentication.
+     */
+    getMethods(options?: RequestOptions): Promise<NulvlessResult<AuthMethods>>;
+    /**
+     * Looks up whether an identifier exists and which sign-in method applies.
+     *
+     * Useful for adaptive sign-in UIs. May return a `challenge` directly
+     * when the user's method is OTP-only.
+     *
+     * At least one of `email`, `phone`, or `username` must be provided.
+     */
+    lookup(params: LookupParams, options?: RequestOptions): Promise<NulvlessResult<LookupResult>>;
+    /**
+     * Verifies a challenge by submitting the token and the code entered by the user.
+     *
+     * Used for:
+     * - OTP sign-in (`signInWithOTP` flow)
+     * - MFA verification after `signIn`
+     * - Sign-up confirmation (`signUp` challenge flow)
+     *
+     * Convenience alias for `auth.challenges.verify`. Session is stored
+     * automatically when the response contains an access token. For the rest of
+     * the challenge lifecycle (create, get, change) use `auth.challenges`.
+     */
+    verifyChallenge(params: VerifyChallengeParams, options?: RequestOptions): Promise<NulvlessResult<Authenticated>>;
+    /**
+     * Activates an account via the confirmation link sent to the user's email/phone.
+     */
+    activate(token: string, options?: RequestOptions): Promise<NulvlessResult<null>>;
+    /**
+     * Refreshes the access token using a refresh token (`grant_type=refresh_token`).
+     * Session is updated automatically in storage.
+     */
+    refreshToken(params: RefreshTokenParams, options?: RequestOptions): Promise<NulvlessResult<Authenticated>>;
+    /**
+     * Sends a password-recovery email to the user.
+     */
+    recover(params: RecoverParams, options?: RequestOptions): Promise<NulvlessResult<null>>;
+    /**
+     * Resets the user's password using the token from the recovery email.
+     */
+    resetPassword(params: ResetPasswordParams, options?: RequestOptions): Promise<NulvlessResult<null>>;
+    /**
+     * Validates the current session and optionally checks a grant.
+     *
+     * Requires authentication. Token is resolved automatically from storage
+     * (browser) or from `options.headers.Authorization` (server).
+     */
+    verify(grant?: VerifyParams, options?: RequestOptions): Promise<NulvlessResult<Verified>>;
+    /**
+     * Returns the current session details.
+     *
+     * Requires authentication. Token is resolved automatically from storage
+     * (browser) or from `options.headers.Authorization` (server).
+     */
+    getSession(options?: RequestOptions): Promise<NulvlessResult<Session>>;
+    /**
+     * Signs out the user and clears the stored session.
+     *
+     * - `'local'` (default) — invalidates only the current session.
+     * - `'global'` — invalidates all sessions across all devices.
+     * - `'others'` — invalidates all sessions except the current one.
+     *
+     * Requires authentication. Token is resolved automatically from storage
+     * (browser) or from `options.headers.Authorization` (server).
+     */
+    signOut(scope?: SignOutScope, options?: RequestOptions): Promise<NulvlessResult<null>>;
+}
+/**
+ * Auth client for browser use (`createClient` / public key).
+ * Extends `AuthClient` with session management and multi-account helpers.
+ */
+declare class AuthBrowserClient extends AuthClient {
+    private readonly accountsManager;
+    private readonly emitter;
+    private readonly multiUser;
+    private readonly tabs;
+    constructor(http: HttpClient, session: SessionManager, storage: NulvlessStorage, accountsKey: string, multiUser?: boolean, autoRefresh?: boolean);
+    /**
+     * Renews the access token now, sharing the attempt with any refresh already
+     * in flight. Returns the new token, or `null` when the session could not be
+     * recovered.
+     */
+    refreshSession(): Promise<string | null>;
+    /** Releases the refresh timer and the cross-tab channel. */
+    dispose(): void;
+    /**
+     * Subscribes to an auth event.
+     *
+     * Returns an unsubscribe function — call it to stop listening.
+     *
+     * @example
+     * const off = nulvless.auth.on('signed-in', (session) => {
+     *   console.log('signed in as', session.user?.id)
+     * })
+     * off() // unsubscribe
+     */
+    on<K extends keyof AuthEvents>(event: K, handler: AuthEvents[K] extends void ? () => void : (payload: AuthEvents[K]) => void): () => void;
+    protected persistSession(result: NulvlessResult<Authenticated>): Promise<NulvlessResult<Authenticated>>;
+    /**
+     * Returns the session currently stored in storage, or `null` if there is none.
+     *
+     * `expires_in` is the number of seconds remaining until expiry (may be negative
+     * if the token is already expired).
+     *
+     * @example
+     * const session = await nulvless.auth.get()
+     * if (session) {
+     *   console.log(session.access_token, session.expires_in)
+     * }
+     */
+    get(): Promise<Authenticated | null>;
+    /**
+     * Manually persists a session as the active session.
+     *
+     * Use this when you obtain an `Authenticated` outside the normal SDK flow
+     * (e.g. server-side login, custom OAuth callback) and want the SDK to treat
+     * it as the active session.
+     *
+     * @example
+     * await nulvless.auth.set({ access_token: 'eyJ...', refresh_token: 'rt_...', expires_in: 3600 })
+     */
+    set(data: Authenticated): Promise<void>;
+    /**
+     * Adds an account to the accounts store without switching the active session.
+     *
+     * The account is identified by the `user.id` in the response, or by the `sub`
+     * claim in the access token JWT.
+     *
+     * Call this after a sign-in to register additional accounts. Accounts are
+     * also saved automatically whenever a sign-in / sign-up succeeds.
+     *
+     * @example
+     * const { data } = await nulvless.auth.signIn(params)
+     * // already saved automatically — or add manually:
+     * await nulvless.auth.add(data)
+     */
+    add(auth: Authenticated): Promise<void>;
+    /**
+     * Switches the active session to a previously saved account.
+     *
+     * Returns `true` on success, `false` if the account is not found.
+     *
+     * @example
+     * const ok = await nulvless.auth.switch('user-id-123')
+     */
+    switch(userId: string): Promise<boolean>;
+    /**
+     * Returns all accounts currently saved in the accounts store.
+     *
+     * @example
+     * const accounts = await nulvless.auth.list()
+     * // [{ userId: '...', access_token: '...', expires_in: 3540 }]
+     */
+    list(): Promise<AccountEntry[]>;
+    /**
+     * Removes a saved account from the accounts store.
+     *
+     * Does not affect the active session.
+     *
+     * @example
+     * await nulvless.auth.remove('user-id-123')
+     */
+    remove(userId: string): Promise<void>;
+    /**
+     * Drops the active session without ending it on the server.
+     *
+     * The account stays in the accounts store, so `switch` brings it back. Use
+     * this when the user leaves the authenticated area to pick or add another
+     * account: with no active session the automatic refresh goes quiet instead
+     * of keeping a session warm that nothing is using.
+     *
+     * @example
+     * await nulvless.auth.deselect()
+     * // later
+     * await nulvless.auth.switch('user-id-123')
+     */
+    deselect(): Promise<void>;
+    signOut(scope?: SignOutScope, options?: RequestOptions): Promise<NulvlessResult<null>>;
+}
+/**
+ * Auth methods exclusive to private (`sk_`) keys.
+ * Extends `AuthClient` — all public methods and sub-namespaces are available here too.
+ *
+ * Additional sub-namespaces:
+ * - `auth.grants` — grant management (invite, revoke, accept, etc.)
+ * - `auth.admin` — platform administration (users, roles, grants)
+ *
+ * Never use in browser code.
+ */
+declare class AuthServerClient extends AuthClient {
+    /** User-facing grant management — invite, accept, revoke, etc. */
+    readonly grants: GrantsClient;
+    /** Platform administration — manage users, roles, and grants server-side. */
+    readonly admin: AdminClient;
+    constructor(http: HttpClient);
+}
+
+interface SendEmailParams {
+    /** Recipient address. */
+    to: string;
+    /** Template slug — e.g. `"welcome"`, `"password-reset"`. */
+    template: string;
+    /** Language variant of the template. Uses platform default when omitted. */
+    language?: Language;
+    /** Variables injected into the template. */
+    params?: Record<string, unknown>;
+}
+interface SendSMSParams {
+    phone: Phone;
+    /** Template slug. */
+    template: string;
+    /** Language variant of the template. Uses platform default when omitted. */
+    language?: Language;
+    /** Variables injected into the template. */
+    params?: Record<string, unknown>;
+}
+type NotificationChannel = 'email' | 'sms' | 'webhook';
+type TemplateLanguage = 'en-US' | 'pt-BR';
+interface Template {
+    id: string;
+    name?: string;
+    description?: string;
+    slug: string;
+    channel: NotificationChannel;
+    subject?: string;
+    content: string;
+    url?: string;
+    config?: Record<string, unknown>;
+    language: TemplateLanguage;
+    last_submission?: string;
+    /** `true` when this is a platform-level common template, not a custom one. */
+    common: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateTemplateParams {
+    slug: string;
+    channel: NotificationChannel;
+    content: string;
+    language: TemplateLanguage;
+    name?: string;
+    description?: string;
+    /** Email subject. Required for `email` channel. */
+    subject?: string;
+    /** Webhook URL. Required for `webhook` channel. */
+    url?: string;
+    config?: Record<string, unknown>;
+}
+interface UpdateTemplateParams {
+    name?: string;
+    description?: string;
+    subject?: string;
+    content?: string;
+    url?: string;
+    config?: Record<string, unknown>;
+}
+interface TemplateFilters {
+    page?: number;
+    page_size?: number;
+    sort?: 'asc' | 'desc';
+    channel?: NotificationChannel;
+    language?: TemplateLanguage;
+}
+interface PaginatedTemplates {
+    items: Template[];
+    page?: number;
+    page_size?: number;
+    total?: number;
+    sort?: 'asc' | 'desc';
+}
+
+/**
+ * Template management for the notifications service.
+ *
+ * Available on `createServerClient` only (requires private key).
+ *
+ * @example
+ * const { data } = await nulvless.comms.templates.create({
+ *   slug: 'welcome',
+ *   channel: 'email',
+ *   language: 'en-US',
+ *   subject: 'Welcome!',
+ *   content: '<h1>Hello {{name}}</h1>',
+ * })
+ */
+declare class TemplatesClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Creates a new notification template.
+     *
+     * - `email` channel: `subject` required, `url` not allowed.
+     * - `sms` channel: `subject` and `url` not allowed.
+     * - `webhook` channel: `url` required, `subject` not allowed.
+     */
+    create(params: CreateTemplateParams, options?: RequestOptions): Promise<NulvlessResult<Template>>;
+    /**
+     * Updates an existing template.
+     *
+     * `language` defaults to `'en-US'` when omitted.
+     *
+     * @example
+     * await nulvless.comms.templates.update('email', 'welcome', { subject: 'Welcome aboard!' })
+     */
+    update(channel: NotificationChannel, slug: string, params: UpdateTemplateParams, language?: TemplateLanguage, options?: RequestOptions): Promise<NulvlessResult<Template>>;
+    /**
+     * Deletes a template.
+     *
+     * `language` defaults to `'en-US'` when omitted.
+     */
+    delete(channel: NotificationChannel, slug: string, language?: TemplateLanguage, options?: RequestOptions): Promise<NulvlessResult<Template>>;
+    /**
+     * Returns a template by channel and slug, falling back to the common template
+     * if no custom one exists.
+     *
+     * `language` defaults to `'en-US'` when omitted.
+     *
+     * The response includes `common: true` when the returned template is the
+     * platform-level fallback rather than a custom override.
+     */
+    get(channel: NotificationChannel, slug: string, language?: TemplateLanguage, options?: RequestOptions): Promise<NulvlessResult<Template>>;
+    /**
+     * Returns a paginated list of templates, optionally filtered by channel and language.
+     *
+     * @example
+     * const { data } = await nulvless.comms.templates.list({ channel: 'email', page_size: 20 })
+     */
+    list(filters?: TemplateFilters, options?: RequestOptions): Promise<NulvlessResult<PaginatedTemplates>>;
+}
+
+declare class EmailClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Sends a transactional email using a pre-configured template.
+     *
+     * Returns `null` on success — the API responds with `200` and no body.
+     *
+     * @example
+     * const { error } = await nulvless.comms.email.send({
+     *   to: 'user@example.com',
+     *   template: 'welcome',
+     *   params: { name: 'Gleisson' },
+     * })
+     */
+    send(params: SendEmailParams, options?: RequestOptions): Promise<NulvlessResult<null>>;
+    /**
+     * Sends a test email to validate the platform's email provider configuration.
+     *
+     * Returns `null` on success.
+     *
+     * @example
+     * const { error } = await nulvless.comms.email.test('user@example.com')
+     */
+    test(email: string, options?: RequestOptions): Promise<NulvlessResult<null>>;
+}
+declare class SmsClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Sends a transactional SMS using a pre-configured template.
+     *
+     * Returns `null` on success — the API responds with `200` and no body.
+     *
+     * @example
+     * const { error } = await nulvless.comms.sms.send({
+     *   phone: { country_code: '+55', number: '11999999999' },
+     *   template: 'verification-code',
+     *   params: { code: '123456' },
+     * })
+     */
+    send(params: SendSMSParams, options?: RequestOptions): Promise<NulvlessResult<null>>;
+    /**
+     * Sends a test SMS to validate the platform's SMS provider configuration.
+     *
+     * Returns `null` on success.
+     *
+     * @example
+     * const { error } = await nulvless.comms.sms.test('user@example.com')
+     */
+    test(email: string, options?: RequestOptions): Promise<NulvlessResult<null>>;
+}
+declare class CommsClient {
+    readonly email: EmailClient;
+    readonly sms: SmsClient;
+    readonly templates: TemplatesClient;
+    constructor(http: HttpClient);
+}
+
+/**
+ * Browser client — use with a public key (`pk_...`).
+ *
+ * Only exposes endpoints that accept public keys.
+ * Safe to instantiate in frontend code.
+ */
+declare class NulvlessClient {
+    readonly auth: AuthBrowserClient;
+    constructor(baseUrl: string, publicKey: string, options?: ClientOptions);
+}
+/**
+ * Server client — use with a private key (`sk_...`).
+ *
+ * Has access to everything in `NulvlessClient` plus private-only endpoints.
+ * Never instantiate in browser code — the private key must stay secret.
+ */
+declare class NulvlessServerClient {
+    readonly auth: AuthServerClient;
+    readonly comms: CommsClient;
+    constructor(baseUrl: string, privateKey: string, options?: ServerClientOptions);
+}
+
+/**
+ * Thrown when `throwErrors: true` is set and the API returns an error response.
+ *
+ * Mirrors the same `{ code, message, status_code }` shape returned by default —
+ * the only difference is delivery: exception vs. discriminated union.
+ *
+ * @example
+ * import { NulvlessException } from '@nulvless/nulvless-js'
+ *
+ * try {
+ *   const { data } = await nulvless.auth.signIn({ email, password })
+ * } catch (err) {
+ *   if (err instanceof NulvlessException) {
+ *     console.error(err.code, err.status_code, err.message)
+ *   }
+ * }
+ */
+declare class NulvlessException extends Error {
+    readonly code: string;
+    readonly status_code: number;
+    constructor(message: string | string[], code: string, status_code: number);
+}
+
+/** Persists in `localStorage`. Data survives page reloads and browser restarts. */
+declare class LocalStorageAdapter implements NulvlessStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+
+/** Persists in `sessionStorage`. Data is cleared when the tab or browser is closed. */
+declare class SessionStorageAdapter implements NulvlessStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+
+/**
+ * Persists in memory (plain `Map`). Data is lost on page reload.
+ *
+ * Useful for SSR environments, tests, or situations where persistent
+ * storage is not available or desired.
+ */
+declare class MemoryStorageAdapter implements NulvlessStorage {
+    private readonly store;
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+
+/**
+ * Persists using the browser's Cache Storage API.
+ *
+ * Available in modern browsers and service workers. Data survives page
+ * reloads but can be cleared by the browser under storage pressure.
+ *
+ * Keys are mapped to fake URLs (`https://nulvless.storage/<key>`) since
+ * the Cache API uses URLs as identifiers.
+ */
+declare class CacheStorageAdapter implements NulvlessStorage {
+    private key;
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+
+/**
+ * Built-in storage adapters for session persistence.
+ *
+ * @example
+ * import { Storage } from '@nulvless/nulvless-js'
+ *
+ * const nulvless = createClient(url, key, {
+ *   storage: Storage.Local,   // localStorage — survives reloads
+ *   storage: Storage.Session, // sessionStorage — cleared on tab close
+ *   storage: Storage.Memory,  // in-memory — useful for SSR / tests
+ *   storage: Storage.Cache,   // Cache Storage API — browser / service workers
+ * })
+ */
+declare const Storage: {
+    /** `localStorage` — data survives page reloads and browser restarts. */
+    readonly Local: LocalStorageAdapter;
+    /** `sessionStorage` — data is cleared when the tab or browser is closed. */
+    readonly Session: SessionStorageAdapter;
+    /** In-memory `Map` — data is lost on page reload. Good for SSR and tests. */
+    readonly Memory: MemoryStorageAdapter;
+    /** Cache Storage API — survives reloads, available in service workers. */
+    readonly Cache: CacheStorageAdapter;
+};
+
+type NodeHeaders = Record<string, string | string[] | undefined>;
+/**
+ * Extracts user browser headers from an incoming server request and returns
+ * them as a plain `Record<string, string>` ready to pass via `options.headers`.
+ *
+ * Accepts:
+ * - **Web `Request`** — Next.js App Router, Cloudflare Workers, Deno
+ * - **Node.js `IncomingMessage`** — Express, Next.js Pages Router, Fastify raw
+ *
+ * @example
+ * // Next.js App Router
+ * export async function POST(request: Request) {
+ *   const { data } = await nulvless.auth.signIn(params, {
+ *     headers: forwardUserHeaders(request),
+ *   })
+ * }
+ *
+ * @example
+ * // Express / Next.js Pages Router
+ * app.post('/login', async (req, res) => {
+ *   const { data } = await nulvless.auth.signIn(params, {
+ *     headers: forwardUserHeaders(req),
+ *   })
+ * })
+ */
+declare function forwardUserHeaders(req: Request | {
+    headers: NodeHeaders;
+}): Record<string, string>;
+
+/**
+ * Headers that keep a response carrying auth state out of every cache.
+ *
+ * `no-store` alone covers HTTP/1.1; `Pragma` and `Expires` cover HTTP/1.0 caches
+ * and proxies that predate it. RFC 6749 §5.1 and OpenID Connect Core §3.1.3.3
+ * both require the first two on any response carrying a token.
+ */
+declare const AUTH_CACHE_HEADERS: {
+    readonly 'Cache-Control': "private, no-cache, no-store, must-revalidate, max-age=0";
+    readonly Expires: "0";
+    readonly Pragma: "no-cache";
+};
+/**
+ * Marks a response as carrying auth state so no cache stores it, and returns it
+ * so the call can be inlined into a `return`.
+ *
+ * Apply this to **your own** response whenever it sets, rotates or clears a
+ * session — sign-in, refresh, sign-out. A CDN that caches such a response serves
+ * one visitor's session cookie to the next, signing them in as someone else; it
+ * is a failure that has happened in production on CloudFront, Vercel Edge and
+ * Cloudflare. The usual protection does not apply here: shared caches are barred
+ * from reusing responses to requests carrying `Authorization`, but yours is
+ * authenticated by cookie, which carries no such rule.
+ *
+ * Accepts a Web `Response` (Next.js App Router, Workers, Deno) or a Node
+ * `ServerResponse` (Express, Next.js Pages Router). Use {@link AUTH_CACHE_HEADERS}
+ * directly where a framework takes a plain header map instead.
+ *
+ * @example
+ * // Next.js App Router
+ * export async function POST(request: Request) {
+ *   const { data } = await nulvless.auth.signIn(params, {
+ *     headers: forwardUserHeaders(request),
+ *   })
+ *
+ *   const response = NextResponse.json({ ok: true })
+ *   response.cookies.set('session', data.access_token)
+ *
+ *   return applyAuthCacheHeaders(response)
+ * }
+ *
+ * @example
+ * // Express
+ * app.post('/login', async (req, res) => {
+ *   const { data } = await nulvless.auth.signIn(params, {
+ *     headers: forwardUserHeaders(req),
+ *   })
+ *
+ *   applyAuthCacheHeaders(res)
+ *   res.cookie('session', data.access_token, { httpOnly: true, sameSite: 'lax' })
+ *   res.json({ ok: true })
+ * })
+ */
+declare function applyAuthCacheHeaders<T>(response: T): T;
+
+/**
+ * Creates a browser-safe client using a public key (`pk_...`).
+ *
+ * Exposes: `.auth`
+ *
+ * @example
+ * import { createClient } from '@nulvless/nulvless-js'
+ *
+ * const nulvless = createClient('https://auth.example.com', 'pk_live_...')
+ *
+ * const { data, error } = await nulvless.auth.signIn({
+ *   email: 'user@example.com',
+ *   password: 'secret',
+ * })
+ */
+declare function createClient(url: string, publicKey: string, options?: ClientOptions): NulvlessClient;
+/**
+ * Creates a server-side client using a private key (`sk_...`).
+ * Never use this in browser code.
+ *
+ * Exposes: `.auth`, `.comms`
+ *
+ * @example
+ * import { createServerClient } from '@nulvless/nulvless-js'
+ *
+ * const nulvless = createServerClient('https://api.example.com', 'sk_live_...')
+ *
+ * const { error } = await nulvless.comms.email.send({
+ *   to: 'user@example.com',
+ *   template: 'welcome',
+ *   params: { name: 'Gleisson' },
+ * })
+ */
+declare function createServerClient(url: string, privateKey: string, options?: ServerClientOptions): NulvlessServerClient;
+
+export { AUTH_CACHE_HEADERS, type AccountEntry, type AddEmailIdentityParams, type AddPhoneIdentityParams, AdminClient, type AdminCreateUserParams, type AdminUpdateUserParams, type AssuranceLevel, AuthBrowserClient, AuthClient, AuthEventEmitter, type AuthEvents, type AuthFactorStatus, type AuthMethod, type AuthMethods, type AuthOptions, AuthServerClient, type Authenticated, type BlockGrantParams, type Challenge, type ChallengeSubject, type ChangeChallengeParams, type ChangePasswordParams, type ClientOptions, CommsClient, type ConfirmationType, type CreateRoleParams, type CreateTemplateParams, EmailClient, type EnableFactorParams, type EnrollFactorParams, type ExchangeOAuthCodeParams, type FactorEnrollment, FactorsClient, type Grant, type GrantMembers, type GrantStatus, GrantsClient, HttpClient, type Identity, type IdentityType, type Invite, type InviteParams, type Language, type LeaveGrantParams, type LookupMatch, type LookupParams, type LookupResult, type MFAMethod, type Nonce, type NotificationChannel, NulvlessClient, type NulvlessError, NulvlessException, type NulvlessResult, NulvlessServerClient, type NulvlessStorage, type OAuthApp, type OAuthAppGrantType, type OAuthAppTokenEndpointAuthMethod, type OAuthAppType, type OAuthAuthorization, type OAuthAuthorizeParams, OAuthClient, type OAuthConsentAction, type OAuthConsentResult, type OAuthDiscovery, OAuthGrantsClient, type OAuthJWKS, type OAuthProvider, type OAuthTokenResponse, type OAuthUserGrant, type OAuthUserInfo, type PaginateGrantsParams, type PaginateUsersParams, type Paginated, type PaginatedTemplates, type PaginationSort, type Phone, type PlatformInfo, type RecoverParams, type RefreshOAuthTokenParams, type RefreshTokenParams, type RegisterOAuthAppParams, type RemoveIdentityParams, type RequestOptions, type ResetPasswordParams, type RevokeGrantParams, type RevokeSessionParams, type Role, SecurityClient, type SendEmailParams, type SendOTPToUpdateEmailParams, type SendOTPToUpdatePhoneParams, type SendSMSParams, type ServerClientOptions, type Session, type SessionFingerPrint, SessionManager, SessionsClient, type SetGrantParams, type SignInMethod, type SignInParams, type SignInWithOTPParams, type SignOutScope, type SignUpParams, SmsClient, Storage, type StoredSession, type SudoMethod, type Template, type TemplateFilters, type TemplateLanguage, TemplatesClient, type TokenType, type UnenrollFactorParams, type UpdateGrantParams, type UpdateIdentityParams, type UpdateOAuthAppParams, type UpdateRoleParams, type UpdateTemplateParams, type User, type UserGender, type UserProfile, UsersClient, type Verified, type VerifyChallengeParams, type VerifyParams, type VerifyReason, applyAuthCacheHeaders, createClient, createServerClient, forwardUserHeaders };