@oxyhq/core 1.11.24 → 2.1.0

package/dist/types/mixins/OxyServices.contacts.d.ts

@@ -53,6 +53,7 @@ export declare function OxyServicesContactsMixin<T extends typeof OxyServicesBas
         __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
+        getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
         getMetrics(): {
             totalRequests: number;

package/dist/types/mixins/OxyServices.developer.d.ts

@@ -58,6 +58,7 @@ export declare function OxyServicesDeveloperMixin<T extends typeof OxyServicesBa
         __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
+        getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
         getMetrics(): {
             totalRequests: number;

package/dist/types/mixins/OxyServices.devices.d.ts

@@ -55,6 +55,7 @@ export declare function OxyServicesDevicesMixin<T extends typeof OxyServicesBase
         __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
+        getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
         getMetrics(): {
             totalRequests: number;

package/dist/types/mixins/OxyServices.features.d.ts

@@ -183,6 +183,7 @@ export declare function OxyServicesFeaturesMixin<T extends typeof OxyServicesBas
         __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
+        getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
         getMetrics(): {
             totalRequests: number;
@@ -216,11 +217,7 @@ export declare function OxyServicesFeaturesMixin<T extends typeof OxyServicesBas
         withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
             maxRetries?: number;
             retryDelay?: number;
-            authTimeoutMs
-            /**
-             * Get user statistics
-             */
-            ?: number;
+            authTimeoutMs?: number;
         }): Promise<T_1>;
         validate(): Promise<boolean>;
         handleError(error: unknown): Error;

package/dist/types/mixins/OxyServices.fedcm.d.ts

@@ -234,12 +234,30 @@ export declare function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(
         storeLoginHint(userId: string): void;
         /** @internal */
         clearLoginHint(): void;
+        /**
+         * List the authenticated user's authorized RP apps.
+         *
+         * Returns the intersection of the user's FedCM grants and the currently-
+         * approved RP catalog — what powers the "Connected apps" management UI in
+         * @oxyhq/services. Requires a real user session; service tokens are
+         * rejected by the underlying endpoint.
+         */
+        listAuthorizedApps(): Promise<AuthorizedApp[]>;
+        /**
+         * Revoke the authenticated user's authorization for a specific RP origin.
+         *
+         * The next FedCM sign-in from that origin will require explicit re-consent.
+         * The corresponding cache entry is invalidated so a subsequent
+         * `listAuthorizedApps()` call sees fresh data.
+         */
+        revokeAuthorizedApp(origin: string): Promise<void>;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;
         __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
+        getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
         getMetrics(): {
             totalRequests: number;
@@ -292,4 +310,20 @@ export declare function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(
      */
     isFedCMSupported(): boolean;
 } & T;
+/**
+ * Public summary of an RP application the user has authorized — mirrors the
+ * `AuthorizedAppSummary` shape returned by `GET /fedcm/me/authorized-apps`.
+ */
+export interface AuthorizedApp {
+    /** Normalised RP origin. */
+    origin: string;
+    /** Friendly display name. */
+    name: string;
+    /** Optional human-readable description. */
+    description?: string;
+    /** ISO-8601 timestamp of when the user first authorized this RP. */
+    firstGrantedAt: string;
+    /** ISO-8601 timestamp of the most recent FedCM exchange for this user+RP. */
+    lastUsedAt: string;
+}
 export { OxyServicesFedCMMixin as FedCMMixin };

package/dist/types/mixins/OxyServices.karma.d.ts

@@ -44,6 +44,7 @@ export declare function OxyServicesKarmaMixin<T extends typeof OxyServicesBase>(
         __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
+        getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
         getMetrics(): {
             totalRequests: number;

package/dist/types/mixins/OxyServices.language.d.ts

@@ -40,6 +40,7 @@ export declare function OxyServicesLanguageMixin<T extends typeof OxyServicesBas
         __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
+        getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
         getMetrics(): {
             totalRequests: number;

package/dist/types/mixins/OxyServices.location.d.ts

@@ -23,6 +23,7 @@ export declare function OxyServicesLocationMixin<T extends typeof OxyServicesBas
         __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
+        getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
         getMetrics(): {
             totalRequests: number;

package/dist/types/mixins/OxyServices.managedAccounts.d.ts

@@ -80,6 +80,7 @@ export declare function OxyServicesManagedAccountsMixin<T extends typeof OxyServ
         __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
+        getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
         getMetrics(): {
             totalRequests: number;

package/dist/types/mixins/OxyServices.payment.d.ts

@@ -70,6 +70,7 @@ export declare function OxyServicesPaymentMixin<T extends typeof OxyServicesBase
         __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
+        getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
         getMetrics(): {
             totalRequests: number;

package/dist/types/mixins/OxyServices.popup.d.ts

@@ -5,6 +5,23 @@ export interface PopupAuthOptions {
     height?: number;
     timeout?: number;
     mode?: 'login' | 'signup';
+    /**
+     * A popup window handle the caller already opened SYNCHRONOUSLY inside the
+     * user-gesture event handler (e.g. an `onClick`). The mixin will navigate
+     * this window to the auth URL instead of calling `window.open` itself.
+     *
+     * Why this exists: Chrome (and other modern browsers) only honor
+     * `window.open` while a transient user-activation is in scope. The
+     * activation is consumed by the FIRST `await` in the click handler — so any
+     * caller that awaits FedCM / silent SSO before reaching `signInWithPopup`
+     * loses the activation and sees the popup blocked. The caller can dodge
+     * this by opening a blank popup on the raw click via `openBlankPopup()`,
+     * then passing the handle in here.
+     *
+     * `null` is accepted (and is the same as omitting the option) so consumers
+     * can pass through the result of `openBlankPopup()` without an extra guard.
+     */
+    popup?: Window | null;
 }
 export interface SilentAuthOptions {
     timeout?: number;
@@ -100,6 +117,28 @@ export declare function OxyServicesPopupAuthMixin<T extends typeof OxyServicesBa
          * ```
          */
         silentSignIn(options?: SilentAuthOptions): Promise<SessionLoginResponse | null>;
+        /**
+         * Open a blank, centered popup window SYNCHRONOUSLY.
+         *
+         * Use this in a click (or other user-gesture) handler BEFORE any `await`
+         * to capture the transient user-activation. Pass the returned handle into
+         * `signInWithPopup({ popup })` once the async portion of the flow runs.
+         *
+         * Returns `null` if the browser's popup blocker rejected the open.
+         *
+         * @example
+         * ```typescript
+         * const onSignInClick = () => {
+         *   const popup = oxyServices.openBlankPopup();
+         *   (async () => {
+         *     const silent = await oxyServices.silentSignInWithFedCM();
+         *     if (silent) { popup?.close(); return; }
+         *     await oxyServices.signInWithPopup({ popup });
+         *   })();
+         * };
+         * ```
+         */
+        openBlankPopup(width?: number, height?: number): Window | null;
         /**
          * Open a centered popup window
          *
@@ -160,6 +199,7 @@ export declare function OxyServicesPopupAuthMixin<T extends typeof OxyServicesBa
         __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
+        getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
         getMetrics(): {
             totalRequests: number;

package/dist/types/mixins/OxyServices.privacy.d.ts

@@ -81,6 +81,7 @@ export declare function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase
         __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
+        getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
         getMetrics(): {
             totalRequests: number;

package/dist/types/mixins/OxyServices.redirect.d.ts

@@ -197,6 +197,7 @@ export declare function OxyServicesRedirectAuthMixin<T extends typeof OxyService
         __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
+        getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
         getMetrics(): {
             totalRequests: number;

package/dist/types/mixins/OxyServices.security.d.ts

@@ -37,6 +37,7 @@ export declare function OxyServicesSecurityMixin<T extends typeof OxyServicesBas
         __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
+        getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
         getMetrics(): {
             totalRequests: number;

package/dist/types/mixins/OxyServices.topics.d.ts

@@ -63,6 +63,7 @@ export declare function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>
         __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
+        getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
         getMetrics(): {
             totalRequests: number;

package/dist/types/mixins/OxyServices.user.d.ts

@@ -1,7 +1,7 @@
 /**
  * User Management Methods Mixin
  */
-import type { User, Notification, SearchProfilesResponse, PrivacySettings } from '../models/interfaces';
+import type { User, Notification, NotificationPreferences, UserPreferences, SearchProfilesResponse, PrivacySettings } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { type PaginationParams } from '../utils/apiUtils';
 export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T): {
@@ -116,6 +116,20 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          * @param userId - The user ID (defaults to current user)
          */
         updatePrivacySettings(settings: Partial<PrivacySettings>, userId?: string): Promise<PrivacySettings>;
+        /**
+         * Update the authenticated user's notification preferences.
+         *
+         * Thin wrapper over `updateProfile` that constrains the patch to known
+         * notification channels — same persistence path, same cache invalidation,
+         * but type-safe at the call site.
+         */
+        updateNotificationPreferences(preferences: Partial<NotificationPreferences>): Promise<User>;
+        /**
+         * Update the authenticated user's general preferences (language, theme,
+         * reduce-motion, timezone). Persisted on the User document via
+         * `PUT /users/me` — same cache-invalidation behaviour as `updateProfile`.
+         */
+        updateUserPreferences(preferences: Partial<UserPreferences>): Promise<User>;
         /**
          * Request account verification
          */
@@ -208,6 +222,7 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
         __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
+        getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
         getMetrics(): {
             totalRequests: number;

package/dist/types/mixins/OxyServices.utility.d.ts

@@ -246,6 +246,7 @@ export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase
         __resetTokensForTests(): void;
         makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
         getBaseURL(): string;
+        getSessionBaseUrl(): string;
         getClient(): import("../HttpService").HttpService;
         getMetrics(): {
             totalRequests: number;

package/dist/types/models/interfaces.d.ts

@@ -1,6 +1,20 @@
 export interface OxyConfig {
     baseURL: string;
     cloudURL?: string;
+    /**
+     * Base URL the SDK's first-party session/refresh calls target.
+     *
+     * Per the 2026 session architecture (docs/SESSION-ARCHITECTURE.md), every app
+     * keeps its OWN first-party session on its OWN domain. For non-`oxy.so` apps
+     * this is the app's own same-site backend (e.g. `https://api.mention.earth`),
+     * whose session bridge forwards the user's refresh credential to
+     * `api.oxy.so`. For `*.oxy.so` apps this is omitted and falls back to
+     * `baseURL` (`https://api.oxy.so`), so their behavior is unchanged.
+     *
+     * Resolve via {@link OxyServices.getSessionBaseUrl}; when unset it returns
+     * `baseURL`. This is purely additive — no refresh/auth logic reads it yet.
+     */
+    sessionBaseUrl?: string;
     authWebUrl?: string;
     authRedirectUri?: string;
     enableCache?: boolean;
@@ -98,8 +112,37 @@ export interface User {
     };
     isManagedAccount?: boolean;
     managedBy?: string;
+    notificationPreferences?: NotificationPreferences;
+    userPreferences?: UserPreferences;
     [key: string]: unknown;
 }
+/**
+ * User-controlled notification channels. Persisted on the User document.
+ */
+export interface NotificationPreferences {
+    /** Push notifications on registered devices. */
+    pushEnabled?: boolean;
+    /** Periodic email digest of activity. */
+    emailDigest?: boolean;
+    /** Security/account alerts (sign-ins, recovery, key changes). */
+    securityAlerts?: boolean;
+    /** Marketing / product update emails. */
+    marketingEmails?: boolean;
+}
+/**
+ * General per-user preferences applied across all Oxy apps for the user.
+ * Persisted on the User document.
+ */
+export interface UserPreferences {
+    /** BCP-47 language tag, e.g. "en-US", "es-ES". Empty string = follow device. */
+    language?: string;
+    /** Theme mode preference. */
+    theme?: 'light' | 'dark' | 'system';
+    /** Mirror of OS reduce-motion preference, persisted server-side. */
+    reduceMotion?: boolean;
+    /** IANA timezone, e.g. "Europe/Madrid". Empty string = follow device. */
+    timezone?: string;
+}
 export interface LoginResponse {
     accessToken?: string;
     refreshToken?: string;
@@ -488,3 +531,58 @@ export interface UpdateDeviceNameResponse {
     message: string;
     deviceName: string;
 }
+/**
+ * Minimal user shape included in a `RefreshAllAccount` entry. The server
+ * projects a small whitelist (`username name avatar email color`) so the
+ * client can render the account chooser without an extra `/users/me` round
+ * trip per account.
+ *
+ * `avatar` and `color` are `string | null` because they are stored as nullable
+ * fields in the user document.
+ */
+export interface RefreshAllAccountUser {
+    id: string;
+    username: string;
+    name?: string;
+    avatar?: string | null;
+    email?: string;
+    color?: string | null;
+}
+/**
+ * One rotated account entry returned by `POST /auth/refresh-all`. `authuser` is
+ * the device-local slot index (0..N-1) the cookie was bound to. The legacy
+ * un-suffixed `oxy_rt` cookie yields `authuser: null` server-side, but the SDK
+ * normalises that to `0` before exposing it (the chooser always operates on
+ * numeric indices).
+ *
+ * `user` is `null` only on the SDK-side synthesised legacy fallback (when the
+ * server is too old to support `/auth/refresh-all` and we wrap a
+ * `/auth/refresh` response — that endpoint does not project a user shape).
+ * On the modern path every accepted entry carries a non-null user.
+ */
+export interface RefreshAllAccount {
+    authuser: number;
+    accessToken: string;
+    expiresAt: string;
+    sessionId: string;
+    user: RefreshAllAccountUser | null;
+}
+/**
+ * Wire shape of `POST /auth/refresh-all`. Always 200 with a (possibly empty)
+ * accounts array — 401 means "no accounts signed in on this device" and is
+ * normalised to `{ accounts: [] }` at the SDK layer.
+ */
+export interface RefreshAllResponse {
+    accounts: RefreshAllAccount[];
+}
+/**
+ * Wire shape of `POST /auth/refresh` (single-account refresh, optionally
+ * targeting a specific `?authuser=N` slot). The server includes `authuser` in
+ * the response when an indexed slot was rotated; the legacy slot yields
+ * `authuser: null`.
+ */
+export interface RefreshCookieResponse {
+    accessToken: string;
+    expiresAt: string;
+    authuser: number | null;
+}

package/dist/types/models/session.d.ts

@@ -5,6 +5,14 @@ export interface ClientSession {
     lastActive: string;
     userId?: string;
     isCurrent?: boolean;
+    /**
+     * Web-only: the device-local refresh-cookie slot index (0..N) that backs
+     * this session. Populated from `POST /auth/refresh-all` and from login /
+     * signup / fedcm-exchange responses. Required for per-session web token
+     * refresh via `refreshTokenViaCookie({ authuser })` without a bearer token.
+     * Absent on native (RN uses the bearer-protected session id directly).
+     */
+    authuser?: number;
 }
 export interface StorageKeys {
     sessions: string;

package/dist/types/utils/accountUtils.d.ts

@@ -2,6 +2,7 @@
  * Shared account types and pure helper functions.
  * Used by both @oxyhq/services (React Native) and @oxyhq/auth (Web) account stores.
  */
+import type { RefreshAllAccount } from '../models/interfaces';
 export interface QuickAccount {
     sessionId: string;
     userId?: string;
@@ -9,6 +10,19 @@ export interface QuickAccount {
     displayName: string;
     avatar?: string;
     avatarUrl?: string;
+    /**
+     * Device-local account slot index, 0..N-1 (Google-style multi-account).
+     * Mirrors the server's `oxy_rt_${authuser}` cookie slot. Optional so that
+     * pre-multi-account QuickAccounts (sessionId-only, non-cookie auth on RN)
+     * remain valid; web flows always populate it after `refreshAllSessions`.
+     */
+    authuser?: number;
+    /**
+     * Account's preferred Bloom color preset (e.g. `"blue"`, `"oxy"`). Drives
+     * per-account theming in the account chooser. `null` / `undefined` means
+     * the account has no preference and the base theme should be used.
+     */
+    color?: string | null;
 }
 /** Minimal user shape accepted by display-name helpers. Avoids importing the full User type. */
 export interface DisplayNameUserShape {
@@ -74,3 +88,22 @@ export declare const createQuickAccount: (sessionId: string, userData: {
     } | string;
     avatar?: string;
 }, existingAccount?: QuickAccount, getFileDownloadUrl?: (fileId: string, variant: string) => string) => QuickAccount;
+/**
+ * Merge a fresh `/auth/refresh-all` snapshot into an existing QuickAccount
+ * list, preserving any cached fields (`avatarUrl`) for slots that didn't
+ * change. The fresh response is canonical: the resulting list contains EXACTLY
+ * the slots present in `fresh`, sorted by `authuser` ascending. Stale stored
+ * accounts that no longer appear in `fresh` are dropped (the server already
+ * authoritatively cleared the corresponding cookie).
+ *
+ * @param stored Previously persisted QuickAccount list (any order).
+ * @param fresh Server's authoritative refresh-all response.
+ * @returns Canonical merged list, sorted by `authuser` asc.
+ */
+export declare const mergeAccountsFromRefreshAll: (stored: QuickAccount[] | undefined, fresh: RefreshAllAccount[]) => QuickAccount[];
+/**
+ * Return the account's preferred Bloom color preset, or `null` if it has no
+ * preference. Centralises the `color ?? null` normalisation so consumers can
+ * drive per-account theming without duplicating the nullish-handling.
+ */
+export declare const getAccountColor: (account: QuickAccount) => string | null;

package/dist/types/utils/coldBoot.d.ts

@@ -0,0 +1,102 @@
+/**
+ * coldBoot — a pure, ordered, short-circuit runner for "cold boot"
+ * authentication resolution.
+ *
+ * On a fresh page load / app launch the SDK may have several ways to recover an
+ * existing session (silent FedCM, a persisted refresh token, a cross-domain
+ * claim, an explicit popup flow, …). They must be attempted in a *deterministic
+ * order*, and the FIRST one that yields a session wins — every later step is
+ * skipped. This module encodes exactly that contract and nothing else.
+ *
+ * Design constraints (all enforced):
+ *   - PURE: no DOM, no `navigator`, no `window`, no React, no platform globals.
+ *   - NO module-level mutable state. Every call to {@link runColdBoot} is fully
+ *     self-contained, so it is safe under bundler re-evaluation (e.g. the Metro
+ *     web bundle, which is precisely why the FedCM silent-SSO guard had to live
+ *     in consumers rather than a core singleton).
+ *   - Architecture-agnostic: both candidate cross-domain SSO designs consume
+ *     this same primitive; it knows nothing about HOW a step resolves a session.
+ *
+ * A step is skipped (without running) when its `enabled` predicate returns
+ * false. Any thrown error — from either `enabled` or `run` — is reported via
+ * `onStepError` and treated as a non-fatal skip, so one broken recovery path
+ * can never prevent a later, healthy one from succeeding.
+ */
+/**
+ * A successful step result carrying the recovered session.
+ */
+export interface ColdBootSession<S> {
+    readonly kind: 'session';
+    readonly session: S;
+}
+/**
+ * A step result indicating this step has nothing to contribute; the runner
+ * should fall through to the next step.
+ */
+export interface ColdBootSkip {
+    readonly kind: 'skip';
+}
+/**
+ * The result of running a single cold-boot step.
+ */
+export type ColdBootStepResult<S> = ColdBootSession<S> | ColdBootSkip;
+/**
+ * A single ordered cold-boot recovery step.
+ */
+export interface ColdBootStep<S> {
+    /** Stable identifier; surfaced as {@link ColdBootOutcome.via} on success. */
+    readonly id: string;
+    /**
+     * Optional gate. When provided and it returns `false`, `run` is NOT called
+     * and the runner moves to the next step. A throw is treated as disabled
+     * (and reported via `onStepError`).
+     */
+    readonly enabled?: () => boolean;
+    /**
+     * Attempts to recover a session. Resolve with `{ kind: 'session' }` to win
+     * the cold boot, or `{ kind: 'skip' }` to defer to the next step. A throw is
+     * treated as a skip (and reported via `onStepError`).
+     */
+    readonly run: () => Promise<ColdBootStepResult<S>>;
+}
+/**
+ * The terminal outcome of a cold boot: either the winning step's session
+ * (with the step `id` it came from), or `unauthenticated` if every step
+ * skipped, was disabled, or errored.
+ */
+export type ColdBootOutcome<S> = {
+    readonly kind: 'session';
+    readonly via: string;
+    readonly session: S;
+} | {
+    readonly kind: 'unauthenticated';
+};
+/**
+ * Options for {@link runColdBoot}.
+ */
+export interface RunColdBootOptions<S> {
+    /** Ordered steps; evaluated front to back, first session wins. */
+    readonly steps: ReadonlyArray<ColdBootStep<S>>;
+    /**
+     * Optional observer invoked whenever a step's `enabled` or `run` throws.
+     * Receives the offending step `id` and the thrown value. Must not throw;
+     * the runner does not guard against an observer that itself throws.
+     */
+    readonly onStepError?: (id: string, error: unknown) => void;
+}
+/**
+ * Run the ordered cold-boot steps and resolve to the first recovered session,
+ * or `unauthenticated` if none recovers one.
+ *
+ * Semantics:
+ *   1. Iterate `steps` in order.
+ *   2. If a step has an `enabled` predicate, call it inside try/catch:
+ *      - throw → report via `onStepError(id, err)` → treat as disabled → continue.
+ *      - returns false → continue (skip, `run` not called).
+ *   3. Otherwise await `step.run()` inside try/catch:
+ *      - throw → report via `onStepError(id, err)` → continue.
+ *      - `{ kind: 'session' }` → return `{ kind: 'session', via: step.id, session }`.
+ *      - `{ kind: 'skip' }` → continue.
+ *   4. After the loop with no winner → `{ kind: 'unauthenticated' }`.
+ */
+export declare function runColdBoot<S>(options: RunColdBootOptions<S>): Promise<ColdBootOutcome<S>>;

package/dist/types/utils/fapiAutoDetect.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Auto-detect the FAPI (IdP) URL from the current browser hostname.
+ *
+ * This is the canonical cross-domain IdP-resolution primitive for the Oxy
+ * ecosystem. Both candidate cross-domain SSO designs derive `auth.<rp-apex>`
+ * through this helper; do not fork it.
+ *
+ * Clerk-style multi-domain SSO depends on the IdP being reachable on a
+ * subdomain of the RP's own apex (e.g. `auth.mention.earth` CNAMEd to the
+ * central Oxy IdP). That way every FedCM endpoint, the session cookie,
+ * and any popup/redirect target are same-site with the RP — the only way
+ * to get first-party cookies in Safari ITP and Firefox Total Cookie
+ * Protection.
+ *
+ * This helper computes `https://auth.<rp-apex>` from
+ * `window.location.hostname` so a consuming app doesn't have to pass
+ * `authWebUrl` explicitly. Returns `undefined` for environments where
+ * auto-detection would be wrong:
+ *
+ *   - SSR / non-browser (no `window`).
+ *   - `localhost`, `127.0.0.1`, IPv4/IPv6 literals.
+ *   - Hostnames with fewer than two labels.
+ *   - Hostnames whose trailing two labels form a known multi-part public
+ *     suffix (e.g. `co.uk`), where the naive `labels.slice(-2)` apex would be
+ *     an attacker-registrable suffix like `auth.co.uk` rather than the real
+ *     registrable domain.
+ *
+ * When the page is already loaded ON the IdP itself (`auth.<anything>`),
+ * the helper returns the current origin so the SDK keeps everything
+ * same-origin instead of hopping to a different IdP host.
+ *
+ * The IdP backend independently derives `iss`, `provider_urls`, and the
+ * `fedcm.json` icon URLs from the request host
+ * (`packages/auth/server/index.ts`), so an honest CNAME pair is all that
+ * is required for end-to-end FedCM correctness — no per-RP config.
+ */
+export declare function autoDetectAuthWebUrl(location?: Pick<Location, 'hostname' | 'protocol'> | undefined): string | undefined;