@oxyhq/core 5.4.3 → 5.5.0

package/dist/types/index.d.ts

@@ -95,12 +95,13 @@ export type { SsoReturnKind, SsoReturnResult, ConsumeSsoReturnDeps } from './uti
 export { generateSsoState } from './mixins/OxyServices.sso';
 export { establishIdpSessionAfterClaim } from './utils/ssoEstablish';
 export type { SsoEstablishClient, EstablishAfterClaimDeps } from './utils/ssoEstablish';
-export { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoAttemptedKey, ssoPriorSessionKey, ssoSignedOutKey, ssoCallbackBootstrapKey, ssoNavigate, getSsoCallbackBootstrapScript, buildSsoBounceUrl, isCentralIdPOrigin, guardActive, silentRestoreSuppressed, allowSsoBounce, } from './utils/ssoBounce';
+export { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoAttemptedKey, ssoPriorSessionKey, ssoSignedOutKey, ssoOutcomeKey, ssoCallbackBootstrapKey, ssoNavigate, getSsoCallbackBootstrapScript, buildSsoBounceUrl, isCentralIdPOrigin, guardActive, silentRestoreSuppressed, allowSsoBounce, } from './utils/ssoBounce';
 export type { SsoBounceGate } from './utils/ssoBounce';
 export { runColdBoot } from './utils/coldBoot';
 export type { ColdBootStep, ColdBootStepResult, ColdBootSession, ColdBootSkip, ColdBootOutcome, RunColdBootOptions, } from './utils/coldBoot';
 export { SessionClient } from './session/SessionClient';
 export type { TokenTransport, SessionClientHost, SessionClientOptions } from './session/SessionClient';
+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';

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

@@ -1,5 +1,5 @@
 import { type DeviceSessionState } from '@oxyhq/contracts';
-import type { MinimalSocket } from './socketLoader';
+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. */
     ensureActiveToken(state: DeviceSessionState): Promise<void>;
@@ -16,6 +16,18 @@ export interface SessionClientHost {
 }
 export interface SessionClientOptions {
     transport?: TokenTransport;
+    /**
+     * Statically-injected `socket.io-client` factory (its `io` export).
+     * `@oxyhq/services` and `@oxyhq/auth` list `socket.io-client` as a real
+     * dependency and pass `io` in directly, so realtime session sync never
+     * depends on a runtime dynamic `import('socket.io-client')` of a bare
+     * specifier — which is bundler-fragile in Metro/Expo-web and Vite when
+     * `@oxyhq/core` is consumed as its published dist (the import resolves to
+     * nothing → `connectSocket` warns and falls back to REST-only). When this is
+     * provided, `connectSocket` uses it and never touches the lazy loader; when
+     * absent it falls back to `getSocketIO()`.
+     */
+    socketFactory?: SocketIOFactory;
 }
 type StateListener = (state: DeviceSessionState | null) => void;
 export declare class SessionClient {

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

@@ -1,5 +1,6 @@
 import type { OxyServices } from '../OxyServices';
 import { SessionClient, type TokenTransport } from './SessionClient';
+import type { SocketIOFactory } from './socketLoader';
 import { createSessionClientHost } from './sessionClientHost';
 /**
  * Wires a `SessionClient` over the given `OxyServices` instance: builds the
@@ -16,8 +17,14 @@ import { createSessionClientHost } from './sessionClientHost';
  * The host is returned alongside the client (not just the client) so the
  * caller can call `host.setCurrentAccountId(...)` as the active account
  * changes.
+ *
+ * `socketFactory` is the statically-injected `socket.io-client` `io` export.
+ * Consumers that bundle socket.io-client as a real dependency pass it so
+ * realtime sync never depends on core's lazy dynamic import of a bare
+ * 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): {
+export declare function createSessionClient(oxyServices: OxyServices, transport: TokenTransport, socketFactory?: SocketIOFactory): {
     client: SessionClient;
     host: ReturnType<typeof createSessionClientHost>;
 };

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

@@ -122,6 +122,24 @@ export declare function ssoPriorSessionKey(origin: string): string;
  * clears it first, so the user can always sign back in.
  */
 export declare function ssoSignedOutKey(origin: string): string;
+/**
+ * Per-origin key holding the LAST consumed SSO-return outcome (`ok` | `none` |
+ * `error`, plus an optional machine-readable `reason` on the non-`ok` outcomes).
+ *
+ * Lives in per-tab `sessionStorage` like the other loop-breaker keys, and for
+ * the same reason: a `none`/`error` return HARD-navigates the RP off the
+ * internal callback path back to its real destination (a fresh document load),
+ * so the outcome an RP wants to render ("the central IdP had no session — show a
+ * branded sign-in screen instead of bouncing again") must survive that
+ * round-trip. The RP reads it on the destination load to decide whether an
+ * AUTOMATIC (guard-driven) sign-in should re-bounce or defer to a user gesture.
+ *
+ * Written as a small JSON blob (`{kind, reason?}`). Set whenever a return is
+ * consumed; cleared on a successful session commit and on an explicit
+ * user-gesture sign-in / full sign-out (so a deliberate retry is never
+ * suppressed by a prior automatic none/error).
+ */
+export declare function ssoOutcomeKey(origin: string): string;
 /**
  * Per-origin marker written by the pre-hydration callback bootstrap.
  *

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

@@ -29,12 +29,22 @@ export type SsoReturnKind = 'ok' | 'none' | 'error';
  * The parsed result of an SSO return fragment.
  *
  * `code` is present only for `kind: 'ok'`. `state` echoes the CSRF state the RP
- * generated for the bounce (when the IdP round-tripped it).
+ * generated for the bounce (when the IdP round-tripped it). `reason` is present
+ * only for a NON-`ok` outcome when the IdP supplied one.
  */
 export interface SsoReturnResult {
     kind: SsoReturnKind;
     code?: string;
     state?: string;
+    /**
+     * Machine-readable reason accompanying a NON-`ok` outcome, when the central
+     * IdP supplies one (e.g. `no_cookie` | `stale_session` | `no_grant` |
+     * `no_grant_establish` on a `none` bounce). Purely informational: it lets a
+     * Relying Party surface WHY a silent probe returned no session (e.g. to brand
+     * a "sign in" screen) without re-deriving it. Absent on `ok`, and whenever the
+     * IdP did not include a `reason` param.
+     */
+    reason?: string;
 }
 /**
  * Parse an SSO return fragment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "5.4.3",
+  "version": "5.5.0",
   "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

@@ -545,6 +545,7 @@ export {
     ssoAttemptedKey,
     ssoPriorSessionKey,
     ssoSignedOutKey,
+    ssoOutcomeKey,
     ssoCallbackBootstrapKey,
     ssoNavigate,
     getSsoCallbackBootstrapScript,
@@ -571,6 +572,10 @@ export type {
 // ---------------------------------------------------------------------------
 export { SessionClient } from './session/SessionClient';
 export type { TokenTransport, SessionClientHost, SessionClientOptions } from './session/SessionClient';
+// The injectable socket factory type: consumers that bundle socket.io-client
+// (services/auth-sdk) pass its `io` export as `socketFactory` so realtime sync
+// never relies on core's lazy dynamic import of a bare specifier.
+export type { SocketIOFactory, MinimalSocket } from './session/socketLoader';
 
 // Shared SessionClient integration layer: the host adapter, the pure
 // DeviceSessionState projection helpers, and the client factory are defined

package/src/session/SessionClient.ts

@@ -6,7 +6,7 @@ import {
 } from '@oxyhq/contracts';
 import { logger } from '../utils/loggerUtils';
 import { getSocketIO } from './socketLoader';
-import type { MinimalSocket } from './socketLoader';
+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. */
@@ -24,6 +24,18 @@ export interface SessionClientHost {
 
 export interface SessionClientOptions {
   transport?: TokenTransport;
+  /**
+   * Statically-injected `socket.io-client` factory (its `io` export).
+   * `@oxyhq/services` and `@oxyhq/auth` list `socket.io-client` as a real
+   * dependency and pass `io` in directly, so realtime session sync never
+   * depends on a runtime dynamic `import('socket.io-client')` of a bare
+   * specifier — which is bundler-fragile in Metro/Expo-web and Vite when
+   * `@oxyhq/core` is consumed as its published dist (the import resolves to
+   * nothing → `connectSocket` warns and falls back to REST-only). When this is
+   * provided, `connectSocket` uses it and never touches the lazy loader; when
+   * absent it falls back to `getSocketIO()`.
+   */
+  socketFactory?: SocketIOFactory;
 }
 
 type StateListener = (state: DeviceSessionState | null) => void;
@@ -157,7 +169,10 @@ export class SessionClient {
   }
 
   private async connectSocket(): Promise<void> {
-    const io = await getSocketIO();
+    // Prefer a statically-injected factory (services/auth-sdk bundle
+    // socket.io-client as a real dep); fall back to the lazy loader — and warn
+    // if THAT yields nothing — only when no factory was injected.
+    const io = this.options.socketFactory ?? (await getSocketIO());
     if (!io) {
       logger.warn('[SessionClient] no socket.io-client; running REST-only (no realtime sync)', { component: 'SessionClient' });
       return;

package/src/session/__tests__/SessionClient.socketFactory.test.ts

@@ -0,0 +1,79 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import * as socketLoader from '../socketLoader';
+import type { MinimalSocket, SocketIOFactory } from '../socketLoader';
+import { SessionClient, type SessionClientHost } from '../SessionClient';
+
+/**
+ * P0 (bundler-fragility): SessionClient must NOT depend on a runtime dynamic
+ * `import('socket.io-client')` when a consumer (services/auth-sdk) injects the
+ * `io` factory statically. These tests pin the two branches of `connectSocket`:
+ *
+ *  1. `socketFactory` injected  → the injected factory is used and the lazy
+ *     loader (`getSocketIO`) is NEVER invoked (the exact call that fails in the
+ *     Metro/Expo-web + Vite published-dist consumers).
+ *  2. no `socketFactory`        → the lazy loader IS invoked (fallback).
+ */
+
+type Handler = (...args: unknown[]) => void;
+class FakeSocket implements MinimalSocket {
+  connected = false;
+  handlers = new Map<string, Handler[]>();
+  on(event: string, cb: Handler) { const l = this.handlers.get(event) ?? []; l.push(cb); this.handlers.set(event, l); }
+  off(event: string, cb?: Handler) { if (!cb) { this.handlers.delete(event); return; } this.handlers.set(event, (this.handlers.get(event) ?? []).filter((h) => h !== cb)); }
+  connect() { this.connected = true; }
+  disconnect() { this.connected = false; }
+}
+
+const STATE = (rev: number): DeviceSessionState => ({ deviceId: 'd1', accounts: [{ accountId: 'a1', sessionId: 's1', authuser: 0 }], activeAccountId: 'a1', revision: rev, updatedAt: 1720000000000 });
+const SYNC = (rev: number) => ({ state: STATE(rev), activeToken: { accessToken: `jwt-${rev}`, expiresAt: 'x' } });
+
+function makeHost(over: Partial<SessionClientHost> = {}): SessionClientHost {
+  return {
+    makeRequest: jest.fn().mockResolvedValue(SYNC(1)),
+    getBaseURL: () => 'http://test.invalid',
+    getAccessToken: () => 'tok',
+    onTokensChanged: () => () => undefined,
+    setTokens: jest.fn(),
+    getCurrentAccountId: () => 'a1',
+    ...over,
+  };
+}
+
+describe('SessionClient injected socketFactory', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('uses the injected factory and NEVER invokes the lazy loader', async () => {
+    const loaderSpy = jest.spyOn(socketLoader, 'getSocketIO');
+    let created: FakeSocket | null = null;
+    const factory: SocketIOFactory = jest.fn((_uri: string) => {
+      created = new FakeSocket();
+      created.connected = true;
+      return created;
+    });
+
+    const client = new SessionClient(makeHost(), { socketFactory: factory });
+    await client.start();
+
+    expect(factory).toHaveBeenCalledTimes(1);
+    expect(factory).toHaveBeenCalledWith('http://test.invalid', expect.objectContaining({ transports: ['websocket'] }));
+    expect(loaderSpy).not.toHaveBeenCalled();
+    expect(created).not.toBeNull();
+    client.stop();
+  });
+
+  it('falls back to the lazy loader when no factory is injected', async () => {
+    const fake = new FakeSocket();
+    fake.connected = true;
+    const lazyFactory: SocketIOFactory = jest.fn(() => fake);
+    const loaderSpy = jest.spyOn(socketLoader, 'getSocketIO').mockResolvedValue(lazyFactory);
+
+    const client = new SessionClient(makeHost());
+    await client.start();
+
+    expect(loaderSpy).toHaveBeenCalledTimes(1);
+    expect(lazyFactory).toHaveBeenCalledWith('http://test.invalid', expect.objectContaining({ transports: ['websocket'] }));
+    client.stop();
+  });
+});

package/src/session/createSessionClient.ts

@@ -1,5 +1,6 @@
 import type { OxyServices } from '../OxyServices';
 import { SessionClient, type TokenTransport } from './SessionClient';
+import type { SocketIOFactory } from './socketLoader';
 import { createSessionClientHost } from './sessionClientHost';
 
 /**
@@ -17,15 +18,22 @@ import { createSessionClientHost } from './sessionClientHost';
  * The host is returned alongside the client (not just the client) so the
  * caller can call `host.setCurrentAccountId(...)` as the active account
  * changes.
+ *
+ * `socketFactory` is the statically-injected `socket.io-client` `io` export.
+ * Consumers that bundle socket.io-client as a real dependency pass it so
+ * realtime sync never depends on core's lazy dynamic import of a bare
+ * 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: OxyServices,
   transport: TokenTransport,
+  socketFactory?: SocketIOFactory,
 ): {
   client: SessionClient;
   host: ReturnType<typeof createSessionClientHost>;
 } {
   const host = createSessionClientHost(oxyServices);
-  const client = new SessionClient(host, { transport });
+  const client = new SessionClient(host, { transport, socketFactory });
   return { client, host };
 }

package/src/utils/__tests__/ssoReturn.test.ts

@@ -70,6 +70,13 @@ describe('parseSsoReturnFragment', () => {
 
       expect(result).toEqual({ kind: 'ok', code: 'a+b/c', state: 's t' });
     });
+
+    it('ignores a stray reason on an ok outcome', () => {
+      const result = parseSsoReturnFragment('#oxy_sso=ok&code=abc123&state=xyz&reason=no_cookie');
+
+      expect(result).toEqual({ kind: 'ok', code: 'abc123', state: 'xyz' });
+      expect(result?.reason).toBeUndefined();
+    });
   });
 
   describe('none', () => {
@@ -85,6 +92,18 @@ describe('parseSsoReturnFragment', () => {
       expect(result).toEqual({ kind: 'none', state: 'xyz' });
       expect(result?.code).toBeUndefined();
     });
+
+    it('carries a machine-readable reason on a none outcome', () => {
+      const result = parseSsoReturnFragment('#oxy_sso=none&reason=no_cookie&state=xyz');
+
+      expect(result).toEqual({ kind: 'none', state: 'xyz', reason: 'no_cookie' });
+    });
+
+    it('omits reason when the none outcome carries none', () => {
+      const result = parseSsoReturnFragment('#oxy_sso=none&state=xyz');
+
+      expect(result?.reason).toBeUndefined();
+    });
   });
 
   describe('error', () => {
@@ -100,6 +119,12 @@ describe('parseSsoReturnFragment', () => {
       expect(result).toEqual({ kind: 'error' });
       expect(result?.code).toBeUndefined();
     });
+
+    it('carries a machine-readable reason on an error outcome', () => {
+      const result = parseSsoReturnFragment('#oxy_sso=error&reason=no_grant_establish');
+
+      expect(result).toEqual({ kind: 'error', reason: 'no_grant_establish' });
+    });
   });
 
   describe('null (not an oxy_sso fragment)', () => {

package/src/utils/ssoBounce.ts

@@ -70,6 +70,7 @@ const ATTEMPTED_KEY_PREFIX = 'oxy_sso_attempted:';
 const CALLBACK_BOOTSTRAP_KEY_PREFIX = 'oxy_sso_callback_bootstrap:';
 const PRIOR_SESSION_KEY_PREFIX = 'oxy_sso_prior_session:';
 const SIGNED_OUT_KEY_PREFIX = 'oxy_signed_out:';
+const OUTCOME_KEY_PREFIX = 'oxy_sso_outcome:';
 
 /** Per-origin CSRF state key (matched on return to defeat fragment forgery). */
 export function ssoStateKey(origin: string): string {
@@ -157,6 +158,27 @@ export function ssoSignedOutKey(origin: string): string {
   return `${SIGNED_OUT_KEY_PREFIX}${origin}`;
 }
 
+/**
+ * Per-origin key holding the LAST consumed SSO-return outcome (`ok` | `none` |
+ * `error`, plus an optional machine-readable `reason` on the non-`ok` outcomes).
+ *
+ * Lives in per-tab `sessionStorage` like the other loop-breaker keys, and for
+ * the same reason: a `none`/`error` return HARD-navigates the RP off the
+ * internal callback path back to its real destination (a fresh document load),
+ * so the outcome an RP wants to render ("the central IdP had no session — show a
+ * branded sign-in screen instead of bouncing again") must survive that
+ * round-trip. The RP reads it on the destination load to decide whether an
+ * AUTOMATIC (guard-driven) sign-in should re-bounce or defer to a user gesture.
+ *
+ * Written as a small JSON blob (`{kind, reason?}`). Set whenever a return is
+ * consumed; cleared on a successful session commit and on an explicit
+ * user-gesture sign-in / full sign-out (so a deliberate retry is never
+ * suppressed by a prior automatic none/error).
+ */
+export function ssoOutcomeKey(origin: string): string {
+  return `${OUTCOME_KEY_PREFIX}${origin}`;
+}
+
 /**
  * Per-origin marker written by the pre-hydration callback bootstrap.
  *

package/src/utils/ssoReturn.ts

@@ -41,12 +41,22 @@ export type SsoReturnKind = 'ok' | 'none' | 'error';
  * The parsed result of an SSO return fragment.
  *
  * `code` is present only for `kind: 'ok'`. `state` echoes the CSRF state the RP
- * generated for the bounce (when the IdP round-tripped it).
+ * generated for the bounce (when the IdP round-tripped it). `reason` is present
+ * only for a NON-`ok` outcome when the IdP supplied one.
  */
 export interface SsoReturnResult {
   kind: SsoReturnKind;
   code?: string;
   state?: string;
+  /**
+   * Machine-readable reason accompanying a NON-`ok` outcome, when the central
+   * IdP supplies one (e.g. `no_cookie` | `stale_session` | `no_grant` |
+   * `no_grant_establish` on a `none` bounce). Purely informational: it lets a
+   * Relying Party surface WHY a silent probe returned no session (e.g. to brand
+   * a "sign in" screen) without re-deriving it. Absent on `ok`, and whenever the
+   * IdP did not include a `reason` param.
+   */
+  reason?: string;
 }
 
 const VALID_KINDS: ReadonlySet<string> = new Set<SsoReturnKind>(['ok', 'none', 'error']);
@@ -99,6 +109,13 @@ export function parseSsoReturnFragment(hash: string | undefined | null): SsoRetu
     if (code !== null && code.length > 0) {
       result.code = code;
     }
+  } else {
+    // A machine-readable reason accompanies a NON-`ok` outcome when the IdP
+    // supplies one. Success carries no reason, so it is only read here.
+    const reason = params.get('reason');
+    if (reason !== null && reason.length > 0) {
+      result.reason = reason;
+    }
   }
 
   return result;