@oxyhq/core 6.0.0 → 7.1.0

package/dist/esm/session/accountDialogController.js

@@ -0,0 +1,536 @@
+/**
+ * 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 { logger } from '../utils/loggerUtils.js';
+import { CENTRAL_IDP_APEX } from '../utils/authWebUrl.js';
+import { projectSwitchableAccounts, switchableAccountIds, } from './accountProjection.js';
+const DEFAULT_POLL_INTERVAL_MS = 3000;
+const IDLE_SIGN_IN = {
+    phase: 'idle',
+    authorizeCode: null,
+    qrPayload: null,
+    expiresAt: null,
+    error: null,
+};
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export class AccountDialogController {
+    constructor(options) {
+        this.listeners = new Set();
+        // --- Internal (unprojected) state ---
+        this.view = 'accounts';
+        this.graph = [];
+        this.profilesById = new Map();
+        this.loading = false;
+        this.error = null;
+        this.switchingAccountId = null;
+        this.signIn = IDLE_SIGN_IN;
+        // --- Sign-in device-flow bookkeeping ---
+        /** The secret device-flow token of the active QR flow (never surfaced). */
+        this.signInToken = null;
+        this.pollTimer = null;
+        // --- Store plumbing ---
+        this.unsubscribeSession = null;
+        this.started = false;
+        this.refreshSeq = 0;
+        this.oxyServices = options.oxyServices;
+        this.sessionClient = options.sessionClient;
+        this.clientId = options.clientId ?? null;
+        this.locale = options.locale;
+        this.commitSession = options.commitSession;
+        this.onSignedIn = options.onSignedIn;
+        this.idpApex = options.idpApex ?? CENTRAL_IDP_APEX;
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.openUrl = options.openUrl;
+        this.snapshot = this.computeSnapshot();
+    }
+    // =========================================================================
+    // Store surface (useSyncExternalStore)
+    // =========================================================================
+    /** Returns the current immutable snapshot (stable reference between changes). */
+    getSnapshot() {
+        return this.snapshot;
+    }
+    /** Subscribe to snapshot changes. Returns an unsubscribe function. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    // =========================================================================
+    // Lifecycle
+    // =========================================================================
+    /**
+     * 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() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.unsubscribeSession = this.sessionClient.subscribe(() => {
+            // A device-state change (switch / sign-out / sibling sign-in) can add or
+            // remove accounts — re-project immediately, and refetch profiles when new
+            // account ids appeared.
+            this.emit();
+            void this.ensureProfiles();
+        });
+        void this.refresh();
+    }
+    /**
+     * Stop driving the dialog: unsubscribe from `SessionClient` and tear down the
+     * active sign-in flow (timers). Idempotent.
+     */
+    destroy() {
+        this.started = false;
+        if (this.unsubscribeSession) {
+            this.unsubscribeSession();
+            this.unsubscribeSession = null;
+        }
+        this.clearPollTimer();
+        this.listeners.clear();
+    }
+    // =========================================================================
+    // View actions
+    // =========================================================================
+    /** Set the dialog view directly. */
+    setView(view) {
+        if (this.view === view)
+            return;
+        this.view = view;
+        this.emit();
+    }
+    /** Return to the account list and cancel any in-flight sign-in flow. */
+    close() {
+        this.cancelSignIn();
+        this.setView('accounts');
+    }
+    /** Switch to the "add account" view (the sign-in entry chooser). */
+    add() {
+        this.setView('add');
+    }
+    // =========================================================================
+    // Account list
+    // =========================================================================
+    /**
+     * 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.
+     */
+    async refresh() {
+        const seq = ++this.refreshSeq;
+        const hadAccounts = this.snapshot.accounts.length > 0;
+        this.loading = !hadAccounts;
+        this.error = null;
+        this.emit();
+        let graph = this.graph;
+        try {
+            graph = await this.oxyServices.listAccounts();
+        }
+        catch (error) {
+            // A graph-load failure is non-fatal: device rows still render. Surface the
+            // message but keep going with whatever graph we already had.
+            this.error = errorMessage(error);
+            logger.warn('[AccountDialogController] listAccounts failed', { component: 'AccountDialogController' }, error);
+        }
+        if (seq !== this.refreshSeq)
+            return; // superseded by a newer refresh
+        this.graph = graph;
+        await this.loadProfiles(seq);
+        if (seq !== this.refreshSeq)
+            return;
+        this.loading = false;
+        this.emit();
+    }
+    /**
+     * 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.
+     */
+    async ensureProfiles() {
+        const ids = switchableAccountIds(this.sessionClient.getState(), this.graph);
+        if (ids.every((id) => this.profilesById.has(id)))
+            return;
+        await this.loadProfiles(this.refreshSeq);
+        this.emit();
+    }
+    async loadProfiles(seq) {
+        const ids = switchableAccountIds(this.sessionClient.getState(), this.graph);
+        if (ids.length === 0)
+            return;
+        let profiles = [];
+        try {
+            profiles = await this.oxyServices.getUsersByIds(ids);
+        }
+        catch (error) {
+            // `getUsersByIds` already swallows per-chunk failures and returns `[]`;
+            // this guards the unexpected total failure. Non-fatal — keep prior map.
+            logger.warn('[AccountDialogController] getUsersByIds failed', { component: 'AccountDialogController' }, error);
+            return;
+        }
+        if (seq !== this.refreshSeq)
+            return; // superseded
+        const next = new Map(this.profilesById);
+        for (const profile of profiles) {
+            next.set(profile.id, profile);
+        }
+        this.profilesById = next;
+    }
+    // =========================================================================
+    // Switching (uniform switch model — reuses the existing SDK primitives)
+    // =========================================================================
+    /**
+     * 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.
+     */
+    async switchTo(accountId) {
+        if (this.switchingAccountId)
+            return;
+        this.switchingAccountId = accountId;
+        this.error = null;
+        this.emit();
+        try {
+            const state = this.sessionClient.getState();
+            const onDevice = state?.accounts.some((account) => account.accountId === accountId) ?? false;
+            if (onDevice) {
+                await this.sessionClient.switchAccount(accountId);
+            }
+            else {
+                const result = await this.oxyServices.switchToAccount(accountId);
+                if (!result?.user || !result?.sessionId) {
+                    throw new Error('Account switch did not return a valid session');
+                }
+                await this.commitAuthorizedSession({
+                    sessionId: result.sessionId,
+                    deviceId: result.deviceId,
+                    expiresAt: result.expiresAt,
+                    user: result.user,
+                    accessToken: result.accessToken,
+                    ...(readRefreshToken(result) ? { refreshToken: readRefreshToken(result) } : {}),
+                }, result.user);
+            }
+            // Re-project + refetch immediately; the subscription also fires.
+            await this.refresh();
+        }
+        catch (error) {
+            this.error = errorMessage(error);
+        }
+        finally {
+            this.switchingAccountId = null;
+            this.emit();
+        }
+    }
+    // =========================================================================
+    // Sign in with Oxy (device flow — shared keychain, else cross-device QR)
+    // =========================================================================
+    /**
+     * 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.
+     */
+    async signInWithOxy() {
+        this.setView('qr');
+        this.setSignIn({ ...IDLE_SIGN_IN, phase: 'starting' });
+        try {
+            const session = await this.oxyServices.signInWithSharedIdentity();
+            if (session) {
+                await this.completeSignIn(session, session.user);
+                return;
+            }
+        }
+        catch (error) {
+            // Shared-key mint failed — log and fall through to the QR handoff rather
+            // than dead-ending the sign-in.
+            logger.warn('[AccountDialogController] signInWithSharedIdentity failed', { component: 'AccountDialogController' }, error);
+        }
+        await this.showQr();
+    }
+    /**
+     * 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`.
+     */
+    async showQr() {
+        this.cancelSignIn();
+        this.setView('qr');
+        if (!this.clientId) {
+            this.setSignIn({ ...IDLE_SIGN_IN, phase: 'error', error: 'This app is not configured for sign-in (missing clientId).' });
+            return;
+        }
+        this.setSignIn({ ...IDLE_SIGN_IN, phase: 'starting' });
+        try {
+            const handle = await this.oxyServices.startCommonsSignIn({ clientId: this.clientId });
+            this.signInToken = handle.sessionToken;
+            this.setSignIn({
+                phase: 'waiting',
+                authorizeCode: handle.authorizeCode,
+                qrPayload: handle.qrPayload,
+                expiresAt: handle.expiresAt,
+                error: null,
+            });
+            this.scheduleNextPoll(handle.sessionToken);
+        }
+        catch (error) {
+            this.setSignIn({ ...IDLE_SIGN_IN, phase: 'error', error: errorMessage(error) });
+        }
+    }
+    /** Tear down the active sign-in device flow (timers + token) and reset to idle. */
+    cancelSignIn() {
+        this.clearPollTimer();
+        this.signInToken = null;
+        if (this.signIn !== IDLE_SIGN_IN) {
+            this.setSignIn(IDLE_SIGN_IN);
+        }
+    }
+    /**
+     * 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 = {}) {
+        const base = `https://auth.${this.idpApex}`;
+        const url = new URL('/login', base);
+        const returnUrl = params.returnUrl ?? currentLocationHref();
+        if (returnUrl) {
+            url.searchParams.set('redirect_uri', returnUrl);
+        }
+        if (this.clientId) {
+            url.searchParams.set('client_id', this.clientId);
+        }
+        if (params.state) {
+            url.searchParams.set('state', params.state);
+        }
+        const href = url.toString();
+        this.openUrl?.(href);
+        return href;
+    }
+    // =========================================================================
+    // Internal sign-in helpers
+    // =========================================================================
+    scheduleNextPoll(sessionToken) {
+        this.clearPollTimer();
+        this.pollTimer = setTimeout(() => {
+            void this.pollOnce(sessionToken);
+        }, this.pollIntervalMs);
+    }
+    async pollOnce(sessionToken) {
+        // A superseded / cancelled flow must not act.
+        if (this.signInToken !== sessionToken)
+            return;
+        const expiresAt = this.signIn.expiresAt;
+        if (typeof expiresAt === 'number' && Date.now() > expiresAt) {
+            this.failSignIn('Session expired. Please try again.');
+            return;
+        }
+        try {
+            const status = await this.oxyServices.pollCommonsSignIn(sessionToken);
+            if (this.signInToken !== sessionToken)
+                return; // cancelled mid-request
+            if (status.authorized && status.sessionId) {
+                this.clearPollTimer();
+                await this.claimAndComplete(status.sessionId, sessionToken);
+                return;
+            }
+            if (status.status === 'cancelled') {
+                this.failSignIn('Authorization was denied.');
+                return;
+            }
+            if (status.status === 'expired') {
+                this.failSignIn('Session expired. Please try again.');
+                return;
+            }
+        }
+        catch (error) {
+            // Transient poll error — the next tick retries. Logged, never thrown.
+            logger.debug('[AccountDialogController] poll error (will retry)', { component: 'AccountDialogController' }, error);
+        }
+        if (this.signInToken === sessionToken) {
+            this.scheduleNextPoll(sessionToken);
+        }
+    }
+    async claimAndComplete(sessionId, sessionToken) {
+        this.setSignIn({ ...this.signIn, phase: 'authorized' });
+        let claimed;
+        try {
+            claimed = await this.oxyServices.claimSessionByToken(sessionToken);
+        }
+        catch (error) {
+            this.failSignIn(errorMessage(error));
+            return;
+        }
+        if (!claimed?.accessToken || !claimed.user) {
+            this.failSignIn('Authorization succeeded but the session could not be claimed. Please try again.');
+            return;
+        }
+        // `SessionLoginResponse.user` is the minimal session-carried shape; the claim
+        // returns the full `User` (avatar is `string | null | undefined`). Normalize
+        // rather than widening the minimal shape to accept `null`.
+        const minimalUser = {
+            id: claimed.user.id,
+            username: claimed.user.username,
+            name: claimed.user.name,
+            avatar: claimed.user.avatar ?? undefined,
+        };
+        const refreshToken = readRefreshToken(claimed);
+        try {
+            await this.completeSignIn({
+                sessionId: claimed.sessionId || sessionId,
+                deviceId: claimed.deviceId ?? '',
+                expiresAt: claimed.expiresAt ?? '',
+                user: minimalUser,
+                accessToken: claimed.accessToken,
+                ...(refreshToken ? { refreshToken } : {}),
+            }, minimalUser);
+        }
+        catch (error) {
+            this.failSignIn(errorMessage(error));
+        }
+    }
+    /**
+     * 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.
+     */
+    async completeSignIn(session, user) {
+        await this.commitAuthorizedSession(session, user);
+        this.signInToken = null;
+        this.clearPollTimer();
+        this.signIn = IDLE_SIGN_IN;
+        this.view = 'accounts';
+        this.emit();
+        this.onSignedIn?.(user);
+        await this.refresh();
+    }
+    /**
+     * 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).
+     */
+    async commitAuthorizedSession(session, user) {
+        if (this.commitSession) {
+            await this.commitSession(session);
+        }
+        else {
+            await this.sessionClient.registerAndActivate(user.id);
+        }
+    }
+    failSignIn(message) {
+        this.clearPollTimer();
+        this.signInToken = null;
+        this.setSignIn({ ...IDLE_SIGN_IN, phase: 'error', error: message });
+    }
+    clearPollTimer() {
+        if (this.pollTimer !== null) {
+            clearTimeout(this.pollTimer);
+            this.pollTimer = null;
+        }
+    }
+    // =========================================================================
+    // Snapshot plumbing
+    // =========================================================================
+    setSignIn(next) {
+        this.signIn = next;
+        this.emit();
+    }
+    computeSnapshot() {
+        const state = this.sessionClient.getState();
+        return {
+            view: this.view,
+            accounts: projectSwitchableAccounts({
+                state,
+                graph: this.graph,
+                profilesById: this.profilesById,
+                locale: this.locale,
+                resolveAvatarUrl: (avatar) => (avatar ? this.oxyServices.getFileDownloadUrl(avatar, 'thumb') : undefined),
+            }),
+            activeAccountId: state?.activeAccountId ?? null,
+            loading: this.loading,
+            error: this.error,
+            switchingAccountId: this.switchingAccountId,
+            signIn: this.signIn,
+        };
+    }
+    /** Recompute the snapshot and notify subscribers. */
+    emit() {
+        this.snapshot = this.computeSnapshot();
+        for (const listener of this.listeners) {
+            try {
+                listener(this.snapshot);
+            }
+            catch (error) {
+                logger.error('[AccountDialogController] subscriber threw', error);
+            }
+        }
+    }
+}
+/** Factory mirroring `createSessionClient`, for ergonomic wiring by consumers. */
+export function createAccountDialogController(options) {
+    return new AccountDialogController(options);
+}
+// ---------------------------------------------------------------------------
+// Local helpers
+// ---------------------------------------------------------------------------
+/**
+ * The rotating refresh-token family head is threaded on the runtime object by
+ * the trusted device-flow / switch lanes even though it is NOT on the typed
+ * return of `claimSessionByToken` / `switchToAccount`. Read it defensively so
+ * the commit funnel can persist a durable session.
+ */
+function readRefreshToken(value) {
+    const token = value.refreshToken;
+    return typeof token === 'string' ? token : undefined;
+}
+/** Current document URL on web; empty string where `location` is absent (native/SSR). */
+function currentLocationHref() {
+    const location = globalThis.location;
+    return typeof location?.href === 'string' ? location.href : '';
+}

package/dist/esm/session/accountProjection.js

@@ -0,0 +1,127 @@
+/**
+ * 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 { getAccountDisplayName, getAccountFallbackHandle } from '../utils/accountUtils.js';
+/**
+ * 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 function projectSwitchableAccounts(input) {
+    const { state, graph, profilesById, activeUser, locale, resolveAvatarUrl } = input;
+    const activeAccountId = state?.activeAccountId ?? null;
+    const toRow = (accountUser, opts) => {
+        const accountId = accountUser.id?.toString() ?? '';
+        const handle = getAccountFallbackHandle(accountUser);
+        const secondaryHandle = handle ? `@${handle}` : null;
+        return {
+            accountId,
+            sessionId: opts.sessionId,
+            authuser: opts.authuser,
+            isCurrent: Boolean(accountId) && accountId === activeAccountId,
+            onDevice: Boolean(opts.sessionId),
+            relationship: opts.relationship,
+            kind: opts.kind,
+            parentAccountId: opts.parentAccountId,
+            callerMembership: opts.callerMembership,
+            displayName: getAccountDisplayName(accountUser, locale),
+            // Real email, or the `@handle` fallback (NEVER synthesized).
+            email: accountUser.email ?? secondaryHandle,
+            avatarUrl: resolveAvatarUrl(accountUser.avatar),
+            color: accountUser.color ?? null,
+            user: accountUser,
+        };
+    };
+    // --- Device rows (from the server-authoritative session set) ---
+    const deviceRows = (state?.accounts ?? []).flatMap((account) => {
+        const isActive = account.accountId === activeAccountId;
+        // The active row prefers the freshest `activeUser` (when supplied), then the
+        // batch-resolved profile; every other row uses the batch-resolved profile.
+        const accountUser = isActive && activeUser
+            ? activeUser
+            : profilesById.get(account.accountId);
+        if (!accountUser) {
+            return [];
+        }
+        return [toRow(accountUser, { sessionId: account.sessionId, authuser: account.authuser })];
+    });
+    // --- Merge graph nodes, deduping by account id ---
+    const byAccountId = new Map();
+    const order = [];
+    const remember = (row) => {
+        if (!row.accountId || byAccountId.has(row.accountId)) {
+            return;
+        }
+        byAccountId.set(row.accountId, row);
+        order.push(row.accountId);
+    };
+    for (const row of deviceRows) {
+        remember(row);
+    }
+    for (const node of graph) {
+        const existing = byAccountId.get(node.accountId);
+        if (existing) {
+            // On-device account that is ALSO in the graph: enrich the device row with
+            // graph metadata; keep its (freshest) profile + sessionId + active flag.
+            byAccountId.set(node.accountId, {
+                ...existing,
+                relationship: node.relationship,
+                kind: node.kind,
+                parentAccountId: node.parentAccountId,
+                callerMembership: node.callerMembership,
+            });
+            continue;
+        }
+        // Graph-only account (owned org / shared, not yet a device session).
+        remember(toRow(node.account, {
+            relationship: node.relationship,
+            kind: node.kind,
+            parentAccountId: node.parentAccountId,
+            callerMembership: node.callerMembership,
+        }));
+    }
+    return order.flatMap((id) => {
+        const row = byAccountId.get(id);
+        return row ? [row] : [];
+    });
+}
+/**
+ * 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 function switchableAccountIds(state, graph) {
+    const ids = new Set();
+    for (const account of state?.accounts ?? []) {
+        if (account.accountId) {
+            ids.add(account.accountId);
+        }
+    }
+    for (const node of graph) {
+        if (node.accountId) {
+            ids.add(node.accountId);
+        }
+    }
+    return Array.from(ids).sort();
+}

package/dist/esm/session/createSessionClient.js

@@ -22,8 +22,15 @@ import { createSessionClientHost } from './sessionClientHost.js';
  * specifier (bundler-fragile in Metro/Expo-web and Vite against the published
  * dist). When omitted, the client falls back to the lazy loader.
  */
-export function createSessionClient(oxyServices, transport, socketFactory) {
+export function createSessionClient(oxyServices, transport, socketFactory, 
+/**
+ * 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) {
     const host = createSessionClientHost(oxyServices);
-    const client = new SessionClient(host, { transport, socketFactory });
+    const client = new SessionClient(host, { transport, socketFactory, ...extra });
     return { client, host };
 }