@oxyhq/core 7.0.0 → 7.1.1

package/dist/types/index.d.ts

@@ -90,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/session/SessionClient.d.ts

@@ -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,273 @@
+/**
+ * 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 unsubscribeTokens;
+    /** Last-observed SDK auth readiness (a planted bearer). Drives the fetch edge. */
+    private authed;
+    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;
+    /**
+     * Whether a PRIVATE endpoint may be called right now. Mirrors the
+     * `hasAccessToken` term of `OxyContext.canUsePrivateApi`
+     * (`authResolved && isAuthenticated && tokenReady && hasAccessToken`, where
+     * `hasAccessToken = Boolean(oxyServices.getAccessToken())`): a planted bearer
+     * is the only term that decides whether a request carries auth — the other
+     * three are provider render-lifecycle gates with no headless equivalent.
+     *
+     * `listAccounts()` (`GET /accounts`) and `getUsersByIds()`
+     * (`POST /users/by-ids`) are private; calling either before cold-boot restore
+     * plants the token 401s → `HttpService` clears the bearer + emits
+     * `onTokensChanged(null)` → the app signs out. Every graph/profile fetch gates
+     * on this.
+     */
+    private isAuthenticated;
+    /**
+     * Reconcile the account graph against the current auth-readiness edge. On the
+     * signed-out → signed-in edge fetch the graph ONCE; on signed-in → signed-out
+     * drop it and re-project device-only. A no-op when readiness is unchanged, so
+     * a burst of token events / device pushes cannot restart the fetch — and a
+     * failed `listAccounts()` never flips the edge, so it cannot re-trigger itself
+     * (no retry storm).
+     */
+    private reconcileAuth;
+    /** 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 {};

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

@@ -0,0 +1,142 @@
+/**
+ * Unified account-list projection — THE single source of truth.
+ *
+ * Produces the flat `SwitchableAccount[]` every account chooser renders, by
+ * merging the device's server-authoritative session set (`DeviceSessionState`
+ * from {@link SessionClient}) with the caller's account graph (`AccountNode[]`
+ * from `oxyServices.listAccounts()`), deduped by `accountId`. This lives in
+ * `@oxyhq/core` so `@oxyhq/services` (RN) and `@oxyhq/auth` (web) — and
+ * `auth.oxy.so` — all render the SAME list from the SAME logic and cannot
+ * diverge.
+ *
+ * Pure and I/O-free: the caller resolves per-account profiles via
+ * `oxyServices.getUsersByIds(...)` and passes them in as `profilesById`, and
+ * binds `resolveAvatarUrl` to `oxyServices.getFileDownloadUrl`. This is the same
+ * split the former `@oxyhq/services` `buildSwitchableAccounts` used — hoisted
+ * into core, keyed directly on `DeviceSessionState` (whose `activeAccountId` is
+ * atomic, so no cross-call current-row reconciliation is needed).
+ */
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import type { User } from '../models/interfaces';
+import type { AccountNode, AccountRelationship, AccountKind, AccountMember } from '../mixins/OxyServices.accounts';
+/**
+ * The per-account user shape carried by a {@link SwitchableAccount}. The SDK's
+ * canonical {@link User} document — either a profile resolved via
+ * `oxyServices.getUsersByIds()` (device rows), the caller-supplied
+ * `activeUser` override (the freshest copy of the active row), or the `account`
+ * document embedded in an account-graph node (graph-only rows).
+ */
+export type SwitchableAccountUser = User;
+/**
+ * One account the signed-in user can switch INTO, in the uniform switch model.
+ *
+ * A switchable account is either a device sign-in, an account-graph node (owned
+ * org / shared-with-you), or BOTH (an account that has been switched into
+ * becomes a device session while still being a graph node — the two are deduped
+ * into a single row). Every row carries a canonical `accountId` (the uniform
+ * switch key); `sessionId` is present IFF the account is currently signed in on
+ * THIS device.
+ */
+export interface SwitchableAccount {
+    /**
+     * Canonical account id (the underlying `User._id`). The single key EVERY
+     * switch uses — `controller.switchTo(accountId)`. Always present.
+     */
+    accountId: string;
+    /**
+     * Device session id, present IFF this account is signed in on THIS device.
+     * Absent for a graph account not yet switched into. Used only for
+     * device-scoped actions (per-account sign-out); switching ALWAYS goes through
+     * `switchTo(accountId)`.
+     */
+    sessionId?: string;
+    /**
+     * Device-local account slot index (0..N-1) carried on the underlying
+     * `SessionAccount`. Absent for graph-only rows.
+     */
+    authuser?: number;
+    /** Whether this account is the currently-active one (`accountId === activeAccountId`). */
+    isCurrent: boolean;
+    /** Whether this account is signed in on THIS device (has a `sessionId`). */
+    onDevice: boolean;
+    /**
+     * The caller's relationship to this account when it appears in the account
+     * graph: `self` (the caller's own personal account), `owner` (an org/project/
+     * bot the caller owns), or `member` (shared with the caller). Absent for an
+     * independent device sign-in that is NOT in the active account's graph.
+     */
+    relationship?: AccountRelationship;
+    /** Account classification (personal/organization/…). Cosmetic badge only. */
+    kind?: AccountKind;
+    /** Parent account id for 2-level tree grouping, or `null` for a root. */
+    parentAccountId?: string | null;
+    /**
+     * The caller's effective membership (role + permissions) in this account when
+     * it appears in the graph, or `null`/absent otherwise. Use `permissions` to
+     * gate per-account settings UI.
+     */
+    callerMembership?: AccountMember | null;
+    /** Friendly display name (never blank — falls back to a handle/sentinel). */
+    displayName: string;
+    /**
+     * Real account email, or `null` when the account genuinely has none. NEVER a
+     * synthesized `username@oxy.so` — a missing email falls back to the `@handle`
+     * secondary line.
+     */
+    email: string | null;
+    /** Resolved avatar thumbnail URL, or `undefined` when the account has no avatar. */
+    avatarUrl?: string;
+    /** Account's preferred Bloom color preset, or `null` when unset. */
+    color: string | null;
+    /** The underlying per-account user payload. */
+    user: SwitchableAccountUser;
+}
+/** Input to {@link projectSwitchableAccounts}. */
+export interface ProjectSwitchableAccountsInput {
+    /**
+     * The device-scoped session state from `SessionClient.getState()`. `null`
+     * (or an empty account set) contributes no device rows.
+     */
+    state: DeviceSessionState | null;
+    /** The caller's account graph (`oxyServices.listAccounts()`). `[]` when none. */
+    graph: AccountNode[];
+    /**
+     * Per-account profiles resolved via `oxyServices.getUsersByIds()`, keyed by
+     * account id (`User.id`). Device accounts whose profile is absent here are
+     * omitted until a subsequent fetch resolves them (unless they are the active
+     * account and `activeUser` is supplied).
+     */
+    profilesById: Map<string, User>;
+    /**
+     * The freshest copy of the ACTIVE account's user (e.g. `useOxy().user`),
+     * preferred over `profilesById` for the active row so a just-committed profile
+     * edit is reflected immediately. Optional — the controller relies on
+     * `profilesById` alone when omitted.
+     */
+    activeUser?: User | null;
+    /** Locale for display-name resolution (passed to `getAccountDisplayName`). */
+    locale?: string;
+    /**
+     * Resolves an avatar file id to a thumbnail URL — bind to
+     * `(id) => id ? oxyServices.getFileDownloadUrl(id, 'thumb') : undefined`.
+     */
+    resolveAvatarUrl: (avatar: string | null | undefined) => string | undefined;
+}
+/**
+ * Pure union of device sign-ins and account-graph nodes into the flat
+ * {@link SwitchableAccount}[] every switcher renders.
+ *
+ * Order: device rows first (in `state.accounts` order, active flagged), then
+ * graph-only rows (in graph order). An account present as BOTH a device session
+ * and a graph node is deduped into ONE device row enriched with the graph
+ * metadata (relationship / kind / parent / membership).
+ */
+export declare function projectSwitchableAccounts(input: ProjectSwitchableAccountsInput): SwitchableAccount[];
+/**
+ * Every distinct account id referenced by a device session set AND an account
+ * graph, sorted for a stable profile-fetch key. Feed to
+ * `oxyServices.getUsersByIds(...)`; graph nodes already embed their `account`
+ * document, but including their ids lets the caller pass one id set and lets the
+ * projection prefer freshly-fetched profiles uniformly.
+ */
+export declare function switchableAccountIds(state: DeviceSessionState | null, graph: AccountNode[]): string[];

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

@@ -1,5 +1,5 @@
 import type { OxyServices } from '../OxyServices';
-import { SessionClient, type TokenTransport } from './SessionClient';
+import { SessionClient, type SessionClientOptions, type TokenTransport } from './SessionClient';
 import type { SocketIOFactory } from './socketLoader';
 import { createSessionClientHost } from './sessionClientHost';
 /**
@@ -24,7 +24,14 @@ import { createSessionClientHost } from './sessionClientHost';
  * specifier (bundler-fragile in Metro/Expo-web and Vite against the published
  * dist). When omitted, the client falls back to the lazy loader.
  */
-export declare function createSessionClient(oxyServices: OxyServices, transport: TokenTransport, socketFactory?: SocketIOFactory): {
+export declare function createSessionClient(oxyServices: OxyServices, transport: TokenTransport, socketFactory?: SocketIOFactory, 
+/**
+ * Optional signed-out realtime wiring: `signedOutSocketAuth` (open the socket
+ * while signed out so an idle tab receives its device pushes) and
+ * `onSessionAppeared` (self-acquire when a sibling signs in). See
+ * {@link SessionClientOptions}.
+ */
+extra?: Pick<SessionClientOptions, 'signedOutSocketAuth' | 'onSessionAppeared'>): {
     client: SessionClient;
     host: ReturnType<typeof createSessionClientHost>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "7.0.0",
+  "version": "7.1.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/index.ts

@@ -543,6 +543,37 @@ export {
     accountIdsOf,
 } from './session/projectSessionState';
 
+// Unified account-list projection (THE single source of truth for the account
+// chooser: device sign-ins ∪ account graph, deduped by accountId). Pure +
+// I/O-free — the caller hydrates profiles via `getUsersByIds`. Shared by
+// `@oxyhq/services`, `@oxyhq/auth`, and auth.oxy.so so the list can't diverge.
+export {
+    projectSwitchableAccounts,
+    switchableAccountIds,
+} from './session/accountProjection';
+export type {
+    SwitchableAccount,
+    SwitchableAccountUser,
+    ProjectSwitchableAccountsInput,
+} from './session/accountProjection';
+
+// Headless controller for the unified account dialog. Framework-agnostic
+// state machine + subscribe/getSnapshot store (bind via `useSyncExternalStore`)
+// — no password/2FA logic (that lives at the IdP; `openPasswordAtOxyAuth` only
+// hands off). Reuses `SessionClient.switchAccount` / `oxyServices.switchToAccount`
+// for the uniform switch and the existing device-flow methods for sign-in.
+export {
+    AccountDialogController,
+    createAccountDialogController,
+} from './session/accountDialogController';
+export type {
+    AccountDialogControllerOptions,
+    AccountDialogSnapshot,
+    AccountDialogView,
+    SignInFlowPhase,
+    SignInFlowState,
+} from './session/accountDialogController';
+
 // ---------------------------------------------------------------------------
 // Device-first session machinery (auth centralization, wave 1) — additive.
 // Persisted auth-state store, the unified refresh handler + scheduler, the