@oxyhq/core 6.0.0 → 7.1.0

package/dist/types/HttpService.d.ts

@@ -157,7 +157,7 @@ export declare class HttpService {
      * `clearCacheByPrefix` sweeps and `clearCacheEntry` base-key matching.
      * The `clearCacheEntry` callsites all pass fixed, dataless logical keys
      * (`GET:/users/<id>`, `GET:/session/user/<sessionId>`,
-     * `GET:/fedcm/me/authorized-apps`), so this readable suffix can never be
+     * `GET:/auth/grants`), so this readable suffix can never be
      * ambiguous with a serialized request body.
      */
     private static readonly CACHE_IDENTITY_DELIM;

package/dist/types/index.d.ts

@@ -21,7 +21,6 @@ export { OxyServices, OxyAuthenticationError, OxyAuthenticationTimeoutError } fr
 export { OXY_CLOUD_URL, oxyClient } from './OxyServices';
 export type { LinkedHttpClient } from './OxyServices.base';
 export type { AuthRefreshReason, AuthRefreshHandler } from './HttpService';
-export type { AuthorizedApp } from './mixins/OxyServices.authorizedApps';
 export { ServiceCredentialMismatchError } from './mixins/OxyServices.auth';
 export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
 export type { CommonsSignInHandle, CommonsSignInStatus, CommonsApprovalInfo, CommonsSignInActionResult, } from './mixins/OxyServices.auth';
@@ -80,8 +79,8 @@ export type { LogContext } from './utils/loggerUtils';
 export { updateAvatarVisibility } from './utils/avatarUtils';
 export { buildAccountsArray, createQuickAccount, getAccountDisplayName, getAccountFallbackHandle, formatPublicKeyHandle, getAccountColor, } from './utils/accountUtils';
 export type { QuickAccount, DisplayNameUserShape } from './utils/accountUtils';
-export { registrableApex } from './utils/fapiAutoDetect';
-export { CENTRAL_AUTH_URL, CENTRAL_IDP_APEX } from './utils/authWebUrl';
+export { registrableApex } from './utils/registrableApex';
+export { CENTRAL_IDP_APEX } from './utils/authWebUrl';
 export { SSO_CALLBACK_PATH } from './utils/ssoBounce';
 export { runColdBoot } from './utils/coldBoot';
 export type { ColdBootStep, ColdBootStepResult, ColdBootSession, ColdBootSkip, ColdBootOutcome, RunColdBootOptions, } from './utils/coldBoot';
@@ -91,6 +90,10 @@ export type { SocketIOFactory, MinimalSocket } from './session/socketLoader';
 export { createSessionClientHost } from './session/sessionClientHost';
 export { createSessionClient } from './session/createSessionClient';
 export { deviceStateToClientSessions, activeSessionIdOf, activeUserOf, accountIdsOf, } from './session/projectSessionState';
+export { projectSwitchableAccounts, switchableAccountIds, } from './session/accountProjection';
+export type { SwitchableAccount, SwitchableAccountUser, ProjectSwitchableAccountsInput, } from './session/accountProjection';
+export { AccountDialogController, createAccountDialogController, } from './session/accountDialogController';
+export type { AccountDialogControllerOptions, AccountDialogSnapshot, AccountDialogView, SignInFlowPhase, SignInFlowState, } from './session/accountDialogController';
 export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, AUTH_STATE_STORAGE_KEY, DEVICE_TOKEN_STORAGE_KEY, } from './session/authStateStore';
 export type { PersistedAuthState, AuthStateStore, NativeKeyValueStorage, } from './session/authStateStore';
 export { refreshPersistedSession, createAuthRefreshHandler, installAuthRefreshHandler, startTokenRefreshScheduler, TOKEN_REFRESH_LEAD_MS, } from './session/refresh';

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

@@ -28,8 +28,9 @@
  * SWITCHING INTO AN ACCOUNT: `switchToAccount(accountId)` mints a REAL session
  * for the target account and plants it as the active session — there is no
  * per-request "acting-as" header. Identity is carried by the session/token, not
- * a delegation header, so a switch propagates through reload and `refresh-all`
- * exactly like a login.
+ * a delegation header, so a switch propagates through reload and cross-domain
+ * exactly like a login, via the device-first session model (the server
+ * registers the switched session into the operator's device-set directly).
  */
 import type { User } from '../models/interfaces';
 import type { SessionLoginResponse } from '../models/session';
@@ -387,22 +388,22 @@ export interface AccountSuccessResult {
 /**
  * Result of {@link OxyServicesAccountsMixin.switchToAccount} — the freshly
  * minted session for the target account, in the SAME shape the canonical login
- * / `claimSessionByToken` responses use (`SessionLoginResponse`), plus the
- * device-local refresh-cookie slot index.
+ * / `claimSessionByToken` responses use (`SessionLoginResponse`).
  *
  * `accessToken` is the first access token for the new session (already planted
- * as the active token by `switchToAccount`). The refresh token is NOT in the
- * body — the server sets it as the httpOnly `oxy_rt_<authuser>` cookie, which
- * joins the device multi-account set so the switched session survives reload and
- * propagates cross-domain via `/auth/refresh-all`. `user` is the target account.
+ * as the active token by `switchToAccount`). The switched session's survival
+ * across reload and cross-domain sync is device-first: the server registers
+ * it into the operator's `DeviceSession` set directly
+ * (`deviceSessionService.addAccount`, broadcast to the device room) — there is
+ * no client-side refresh-cookie slot to establish. `user` is the target
+ * account.
  */
 export interface SwitchAccountResult extends SessionLoginResponse {
     /**
-     * The device-local refresh-cookie slot index (`oxy_rt_<authuser>`) the server
-     * assigned to the minted session. Surfaced so the consumer can register the
-     * new session in its device multi-account set exactly like a login response.
-     * Absent only when the server could not set the cookie (best-effort — the
-     * switch itself still succeeds).
+     * Legacy device-local refresh-cookie slot index. The current server switch
+     * response never sets this field (device-set registration replaced the
+     * cookie-slot model) — kept optional for backward type-compatibility with
+     * any caller still reading it, but always `undefined` in practice.
      */
     authuser?: number;
 }
@@ -432,24 +433,18 @@ export declare function OxyServicesAccountsMixin<T extends typeof OxyServicesBas
          * target, directly or inherited — else 403; 404 if missing/archived; 403 if
          * the target is a personal account), then mints a REAL session for the
          * target account and returns it in the canonical login / `claimSessionByToken`
-         * shape (`{ sessionId, deviceId, expiresAt, accessToken, user, authuser }`).
+         * shape (`{ sessionId, deviceId, expiresAt, accessToken, user }`).
          *
          * Unlike the removed `X-Acting-As` delegation header, the returned session
          * IS the new identity: this plants `accessToken` as the active token —
          * exactly like `claimSessionByToken` / `verifyChallenge` — so every
          * subsequent request authenticates as the target account.
          *
-         * Joining the device multi-account set (so the switch survives a reload and
-         * propagates cross-domain via `/auth/refresh-all`) requires a SECOND call, to
-         * `POST /auth/session`, made here after the token is planted. The switch route
-         * lives at `/accounts/*`, OUTSIDE the `oxy_rt_<authuser>` cookie's `Path=/auth`
-         * scope, so the server never sees the device's existing slots from it and
-         * would clobber slot 0 (destroying the operator's own session). `/auth/session`
-         * runs where those cookies ARE visible, so the server allocates a NEW slot that
-         * coexists with the operator's and returns its `authuser`. This step is
-         * web-only (native multi-account uses stored sessions, not cookies) and
-         * best-effort — a failure leaves the in-session switch intact; the switched
-         * account simply won't survive a reload until the cookie is next established.
+         * A single call is all that's needed: the server registers the switched
+         * session into the operator's `DeviceSession` set directly, inheriting the
+         * operator's central `deviceId` so the switch survives a reload and syncs
+         * cross-domain via the same device-first session model as a normal login —
+         * there is no separate client-side cookie/slot step to make it stick.
          *
          * After planting, the SDK's identity-scoped GET cache is fully cleared so
          * every cached read re-fetches as the new account. (The consuming
@@ -459,7 +454,7 @@ export declare function OxyServicesAccountsMixin<T extends typeof OxyServicesBas
          * same-user silent refreshes, so the sweep here is explicit.)
          *
          * @param accountId - The target account's Mongo `_id`.
-         * @returns The minted session (planted) plus the device `authuser` slot.
+         * @returns The minted session, already planted as the active session.
          */
         switchToAccount(accountId: string): Promise<SwitchAccountResult>;
         /**
@@ -694,7 +689,9 @@ export declare function OxyServicesAccountsMixin<T extends typeof OxyServicesBas
         handleError(error: unknown): Error;
         healthCheck(): Promise<{
             status: string;
-            users?: number;
+            users
+            /** Aggregate totals for an application over the requested period. */
+            ? /** Aggregate totals for an application over the requested period. */: number;
             timestamp?: string;
             [key: string]: any;
         }>;

package/dist/types/mixins/index.d.ts

@@ -6,7 +6,6 @@
  */
 import { OxyServicesBase } from '../OxyServices.base';
 import { OxyServicesAuthMixin } from './OxyServices.auth';
-import { OxyServicesAuthorizedAppsMixin } from './OxyServices.authorizedApps';
 import { OxyServicesUserMixin } from './OxyServices.user';
 import { OxyServicesIdentityMixin } from './OxyServices.identity';
 import { OxyServicesPrivacyMixin } from './OxyServices.privacy';
@@ -38,7 +37,7 @@ import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
  * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
  * are visible without a cast.
  */
-type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAuthorizedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 /**
  * Constructor type for the fully composed mixin pipeline. Each mixin returns
  * a new constructor that augments its input; reducing across the pipeline

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

@@ -7,11 +7,10 @@ export interface ClientSession {
     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).
+     * The account's ordinal slot (0..N) within the device's account set
+     * (`SessionAccount.authuser` in `@oxyhq/contracts`), projected from the
+     * device-first `DeviceSessionState` — used purely for stable Google-style
+     * account-chooser ordering, not for any token-refresh mechanism.
      */
     authuser?: number;
 }

package/dist/types/server/index.d.ts

@@ -23,5 +23,5 @@ export type { SafeFetchOptions, SafeFetchResult, SsrfCheckFail, SsrfCheckOk, Ssr
 export { createOxyCors } from './cors';
 export type { OxyCorsOptions } from './cors';
 export { verifySecret } from './verifySecret';
-export { registrableApex } from '../utils/fapiAutoDetect';
+export { registrableApex } from '../utils/registrableApex';
 export { SSO_CALLBACK_PATH } from '../utils/ssoBounce';

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

@@ -1,7 +1,7 @@
 import { type DeviceSessionState } from '@oxyhq/contracts';
 import type { MinimalSocket, SocketIOFactory } from './socketLoader';
 export interface TokenTransport {
-    /** Ensure this app holds a per-domain access token for state.activeAccountId (mint via FedCM/silent/sso/keychain). Best-effort. */
+    /** Ensure this app holds a per-domain access token for state.activeAccountId (mint via the persisted refresh family / shared keychain). Best-effort. */
     ensureActiveToken(state: DeviceSessionState): Promise<void>;
 }
 export interface SessionClientHost {
@@ -38,6 +38,30 @@ export interface SessionClientOptions {
      * absent it falls back to `getSocketIO()`.
      */
     socketFactory?: SocketIOFactory;
+    /**
+     * Gate + credential for opening the realtime socket while SIGNED OUT (no
+     * access token), so an idle tab still joins its `device:<id>` room and can
+     * self-acquire the moment a sibling app/tab signs in on the same device.
+     * Returns:
+     *   - `true`   → connect and rely on the first-party `oxy_device` cookie
+     *     riding the same-site handshake (web `*.oxy.so`; the cookie is HttpOnly
+     *     so JS cannot read it, but the browser sends it automatically).
+     *   - a string → connect and present it as `deviceToken` in the handshake
+     *     auth (native shared-keychain device token; RN has no cookie jar).
+     *   - `false`/`null` → do NOT open a signed-out socket (the default — e.g. a
+     *     native app with no known device yet).
+     * Called at connect time (and each reconnect); may be async (keychain read).
+     */
+    signedOutSocketAuth?: () => boolean | string | null | Promise<boolean | string | null>;
+    /**
+     * Invoked when a `session_state` push (or a same-origin BroadcastChannel wake)
+     * arrives while this tab is SIGNED OUT and the pushed device state has at
+     * least one account — i.e. a sibling just signed in on this device. The
+     * consumer runs its session acquisition (cold boot / `requestWebSession`),
+     * which plants a token and flips the tab to signed-in. Guarded + idempotent:
+     * only one acquisition runs at a time, and a returned promise gates the next.
+     */
+    onSessionAppeared?: () => void | Promise<void>;
 }
 type StateListener = (state: DeviceSessionState | null) => void;
 export declare class SessionClient {
@@ -48,6 +72,12 @@ export declare class SessionClient {
     protected socket: MinimalSocket | null;
     private tokenUnsub;
     private started;
+    /** In-flight guard so a burst of pushes triggers at most ONE acquisition. */
+    private acquiring;
+    /** True while the live socket is an anonymous (signed-out) device connection. */
+    private socketAnonymous;
+    /** Same-origin cross-tab wake channel; null on platforms without BroadcastChannel. */
+    private channel;
     constructor(host: SessionClientHost, options?: SessionClientOptions);
     getState(): DeviceSessionState | null;
     subscribe(listener: StateListener): () => void;
@@ -88,5 +118,26 @@ export declare class SessionClient {
     start(): Promise<void>;
     stop(): void;
     private connectSocket;
+    /**
+     * Run the consumer's session acquisition at most once at a time. A returned
+     * promise gates the next attempt (reset on settle), so a failed acquisition
+     * can retry on the NEXT push while a burst of identical pushes cannot pile up.
+     */
+    private requestAcquisition;
+    /**
+     * Open the same-origin `BroadcastChannel` (web only). A sibling tab that
+     * commits a session posts a wake ping; on receipt a signed-in tab re-syncs its
+     * device state and a signed-out tab self-acquires — instant + network-free for
+     * the common "two tabs of the same origin" case, with no state (and no tokens)
+     * ever crossing the channel. No-op on native (no BroadcastChannel).
+     */
+    private openBroadcastChannel;
+    /**
+     * Wake same-origin sibling tabs after a locally-initiated session mutation.
+     * Opens the channel lazily: a sign-in registers the account (`addCurrentAccount`
+     * / `switchAccount`) BEFORE `start()` runs, so the ping must not depend on
+     * `start()` having opened the channel first.
+     */
+    private postCommitPing;
 }
 export {};

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

@@ -0,0 +1,246 @@
+/**
+ * Headless controller for the unified Oxy account dialog.
+ *
+ * A framework-agnostic state machine + subscribe/getSnapshot store (the same
+ * pattern {@link SessionClient} uses — no React, no RN) that both
+ * `@oxyhq/services` (RN `OxyProvider`) and `@oxyhq/auth` (web `WebOxyProvider`)
+ * bind to via `useSyncExternalStore`, so the account chooser is ONE
+ * implementation across the ecosystem instead of the five drifting copies it
+ * replaces.
+ *
+ * The controller owns:
+ *   - the unified account list (via {@link projectSwitchableAccounts}), fetched
+ *     from `SessionClient` state ∪ `oxyServices.listAccounts()` and hydrated
+ *     with `oxyServices.getUsersByIds()`;
+ *   - the dialog `view` state machine (`accounts` | `signin` | `qr` | `add`);
+ *   - `switchTo` (the uniform switch: `SessionClient.switchAccount` for an
+ *     account already on the device, `oxyServices.switchToAccount` to mint on
+ *     first entry into a graph account — reusing the existing SDK primitives, no
+ *     new switch path);
+ *   - the "Sign in with Oxy" device flow (same-device shared-keychain via
+ *     `oxyServices.signInWithSharedIdentity`, else the cross-device QR handoff
+ *     via `startCommonsSignIn` → poll → `claimSessionByToken`).
+ *
+ * It deliberately owns NO password/2FA logic — those live at the IdP
+ * (auth.oxy.so). {@link AccountDialogController.openPasswordAtOxyAuth} only
+ * builds the hand-off URL; device-first convergence syncs the session back.
+ */
+import type { OxyServices } from '../OxyServices';
+import type { SessionLoginResponse, MinimalUserData } from '../models/session';
+import { SessionClient } from './SessionClient';
+import { type SwitchableAccount } from './accountProjection';
+/** The dialog's top-level view. */
+export type AccountDialogView = 'accounts' | 'signin' | 'qr' | 'add';
+/** Lifecycle phase of the "Sign in with Oxy" device flow. */
+export type SignInFlowPhase = 'idle' | 'starting' | 'waiting' | 'authorized' | 'error';
+/** State of the "Sign in with Oxy" (shared-key / QR) device flow. */
+export interface SignInFlowState {
+    phase: SignInFlowPhase;
+    /**
+     * The PUBLIC, single-use authorize code (safe to display), or `null`. NOT the
+     * secret `sessionToken` — the approver resolves the app identity from this.
+     */
+    authorizeCode: string | null;
+    /**
+     * The structured deep-link / QR payload (`oxycommons://approve?...`) to render
+     * as a QR (cross-device) and open as a deep link (same-device), or `null`.
+     */
+    qrPayload: string | null;
+    /** Server-authoritative expiry (epoch ms), or `null`. */
+    expiresAt: number | null;
+    /** Human-readable error for the retry UI, or `null`. */
+    error: string | null;
+}
+/** Immutable snapshot consumed by `useSyncExternalStore`. */
+export interface AccountDialogSnapshot {
+    /** The current view. */
+    view: AccountDialogView;
+    /** The unified, deduped account list (device sign-ins ∪ graph accounts). */
+    accounts: SwitchableAccount[];
+    /** The currently-active account id, or `null` when signed out. */
+    activeAccountId: string | null;
+    /** `true` while the initial account-list fetch is in flight with no data yet. */
+    loading: boolean;
+    /** A human-readable account-list error, or `null`. */
+    error: string | null;
+    /** The `accountId` of an in-flight switch, or `null`. */
+    switchingAccountId: string | null;
+    /** The "Sign in with Oxy" device-flow state. */
+    signIn: SignInFlowState;
+}
+/** Construction options for {@link AccountDialogController}. */
+export interface AccountDialogControllerOptions {
+    /** The API client. Source of graph accounts, profiles, and the sign-in methods. */
+    oxyServices: OxyServices;
+    /** The device-first session authority. Source of device rows + the switch path. */
+    sessionClient: SessionClient;
+    /**
+     * The RP's registered OAuth client id (ApplicationCredential publicKey).
+     * Required for the QR handoff (`startCommonsSignIn`); when absent, `showQr`
+     * fails with a clear configuration error instead of creating a session the
+     * server would reject.
+     */
+    clientId?: string | null;
+    /** Locale for display-name resolution. */
+    locale?: string;
+    /**
+     * Commit a freshly-authorized session (device flow / shared identity / minted
+     * graph switch) into the host's session set — device-first registration +
+     * durable persist + profile hydration. The consumer supplies its provider's
+     * commit path (`useOxy().handleWebSession` / the auth-sdk equivalent). Called
+     * AFTER the SDK has planted the access token. When omitted the controller
+     * falls back to `SessionClient.registerAndActivate` (registration + activation
+     * only — no provider-side durable persist/hydration).
+     */
+    commitSession?: (session: SessionLoginResponse & {
+        refreshToken?: string;
+    }) => Promise<void>;
+    /** Notified after a completed sign-in (bearer planted + session committed). */
+    onSignedIn?: (user: MinimalUserData) => void;
+    /** Central IdP apex for `openPasswordAtOxyAuth` (defaults to `CENTRAL_IDP_APEX`). */
+    idpApex?: string;
+    /** QR device-flow poll interval in ms (default 3000). */
+    pollIntervalMs?: number;
+    /**
+     * Optional URL opener. When provided, `openPasswordAtOxyAuth` invokes it with
+     * the built URL in addition to returning it (web: `location.assign`; native:
+     * `Linking.openURL`). Headless core never touches `window`/`Linking` itself.
+     */
+    openUrl?: (url: string) => void;
+}
+type SnapshotListener = (snapshot: AccountDialogSnapshot) => void;
+export declare class AccountDialogController {
+    private readonly oxyServices;
+    private readonly sessionClient;
+    private readonly clientId;
+    private readonly locale?;
+    private readonly commitSession?;
+    private readonly onSignedIn?;
+    private readonly idpApex;
+    private readonly pollIntervalMs;
+    private readonly openUrl?;
+    private readonly listeners;
+    private view;
+    private graph;
+    private profilesById;
+    private loading;
+    private error;
+    private switchingAccountId;
+    private signIn;
+    /** The secret device-flow token of the active QR flow (never surfaced). */
+    private signInToken;
+    private pollTimer;
+    private unsubscribeSession;
+    private started;
+    private refreshSeq;
+    private snapshot;
+    constructor(options: AccountDialogControllerOptions);
+    /** Returns the current immutable snapshot (stable reference between changes). */
+    getSnapshot(): AccountDialogSnapshot;
+    /** Subscribe to snapshot changes. Returns an unsubscribe function. */
+    subscribe(listener: SnapshotListener): () => void;
+    /**
+     * Begin driving the dialog: subscribe to `SessionClient` state and load the
+     * account list. Idempotent — a second `start()` is a no-op. Pair with
+     * {@link destroy}.
+     */
+    start(): void;
+    /**
+     * Stop driving the dialog: unsubscribe from `SessionClient` and tear down the
+     * active sign-in flow (timers). Idempotent.
+     */
+    destroy(): void;
+    /** Set the dialog view directly. */
+    setView(view: AccountDialogView): void;
+    /** Return to the account list and cancel any in-flight sign-in flow. */
+    close(): void;
+    /** Switch to the "add account" view (the sign-in entry chooser). */
+    add(): void;
+    /**
+     * Reload the account graph and per-account profiles, then re-project. Safe to
+     * call repeatedly; concurrent calls are reconciled by a sequence guard so a
+     * slow earlier fetch never overwrites a newer result.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Fetch profiles for any account id (device set ∪ graph) not yet resolved.
+     * Cheap no-op when everything is already hydrated — used from the session
+     * subscription so a newly-added device account gets a name/avatar.
+     */
+    private ensureProfiles;
+    private loadProfiles;
+    /**
+     * Switch the active account to `accountId`.
+     *
+     * Uniform switch model, mirroring the SDK's existing path — NOT a new switch
+     * mechanism:
+     *   - already on this device → `SessionClient.switchAccount` (device-first
+     *     switch of `/session/device/switch`);
+     *   - a graph account not yet on the device (first entry) →
+     *     `oxyServices.switchToAccount` mints + plants a real session and the
+     *     server registers it into the device set, then it is committed
+     *     (`commitSession` when supplied, else `SessionClient.registerAndActivate`).
+     *
+     * The resulting device-state change flows back through the `SessionClient`
+     * subscription, which re-projects the active row. Concurrent switches are
+     * ignored while one is in flight.
+     */
+    switchTo(accountId: string): Promise<void>;
+    /**
+     * Start "Sign in with Oxy". Native devices with a shared identity mint a
+     * session silently (`signInWithSharedIdentity`); everything else (web, or a
+     * native device without a shared identity) falls through to the cross-device
+     * QR handoff.
+     */
+    signInWithOxy(): Promise<void>;
+    /**
+     * Begin (or restart) the cross-device QR handoff: create a device-flow
+     * session, surface its `authorizeCode` + `qrPayload`, and poll for approval.
+     * On approval the secret token is exchanged (`claimSessionByToken`) and the
+     * session committed. Requires `clientId`.
+     */
+    showQr(): Promise<void>;
+    /** Tear down the active sign-in device flow (timers + token) and reset to idle. */
+    cancelSignIn(): void;
+    /**
+     * Build (and, when an `openUrl` handler was supplied, open) the auth.oxy.so
+     * password sign-in URL. Password + 2FA are NOT in the SDK — they live at the
+     * IdP; this only hands off. Device-first: after login at the IdP the device
+     * session converges and the caller is woken via the device socket /
+     * `BroadcastChannel`, so the URL only needs to point at the IdP sign-in with
+     * the right return.
+     *
+     * @param params.returnUrl - Where the IdP returns after login. Defaults to the
+     *   current document URL on web (`globalThis.location.href`); pass explicitly
+     *   on native (no `location`).
+     * @param params.state - Optional opaque state echoed back on return.
+     * @returns The absolute auth.oxy.so sign-in URL.
+     */
+    openPasswordAtOxyAuth(params?: {
+        returnUrl?: string;
+        state?: string;
+    }): string;
+    private scheduleNextPoll;
+    private pollOnce;
+    private claimAndComplete;
+    /**
+     * Commit an authorized session, notify, and return to the account list. Shared
+     * by the shared-key, QR, and mint-switch paths so they cannot drift.
+     */
+    private completeSignIn;
+    /**
+     * Register a token-planted session into the device set. Prefers the
+     * consumer's `commitSession` (durable persist + hydration); falls back to
+     * `SessionClient.registerAndActivate` (registration + activation only).
+     */
+    private commitAuthorizedSession;
+    private failSignIn;
+    private clearPollTimer;
+    private setSignIn;
+    private computeSnapshot;
+    /** Recompute the snapshot and notify subscribers. */
+    private emit;
+}
+/** Factory mirroring `createSessionClient`, for ergonomic wiring by consumers. */
+export declare function createAccountDialogController(options: AccountDialogControllerOptions): AccountDialogController;
+export {};