@oxyhq/services 13.3.0 → 14.0.0

package/src/ui/session/__tests__/createSessionClient.test.ts

@@ -0,0 +1,41 @@
+import { SessionClient } from '@oxyhq/core';
+import { createSessionClient } from '../createSessionClient';
+
+function fakeOxy() {
+  const listeners = new Set<(t: string | null) => void>();
+  return {
+    makeRequest: jest.fn().mockResolvedValue(undefined),
+    getBaseURL: jest.fn().mockReturnValue('https://api.oxy.so'),
+    getAccessToken: jest.fn().mockReturnValue(null),
+    setTokens: jest.fn(),
+    onTokensChanged: jest.fn((l: (t: string | null) => void) => {
+      listeners.add(l);
+      return () => listeners.delete(l);
+    }),
+    silentSignIn: jest.fn().mockResolvedValue(null),
+    signInWithSharedIdentity: jest.fn().mockResolvedValue(null),
+  };
+}
+
+describe('createSessionClient', () => {
+  test('wires a SessionClient instance backed by the host + token transport', () => {
+    const oxy = fakeOxy();
+
+    const { client, host } = createSessionClient(oxy as never);
+
+    expect(client).toBeInstanceOf(SessionClient);
+    expect(typeof client.bootstrap).toBe('function');
+    expect(client.getState()).toBeNull();
+    expect(typeof host.setCurrentAccountId).toBe('function');
+  });
+
+  test('the returned host reflects setCurrentAccountId', () => {
+    const oxy = fakeOxy();
+
+    const { host } = createSessionClient(oxy as never);
+
+    expect(host.getCurrentAccountId()).toBeNull();
+    host.setCurrentAccountId('u1');
+    expect(host.getCurrentAccountId()).toBe('u1');
+  });
+});

package/src/ui/session/__tests__/projectSessionState.test.ts

@@ -0,0 +1,114 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import type { User } from '@oxyhq/core';
+import {
+  accountIdsOf,
+  activeSessionIdOf,
+  activeUserOf,
+  deviceStateToClientSessions,
+} from '../projectSessionState';
+
+function makeUser(id: string): User {
+  return {
+    id,
+    publicKey: `pk-${id}`,
+    username: `user-${id}`,
+    name: {},
+  };
+}
+
+// DeviceSessionState.updatedAt is an epoch-ms number on the wire (see
+// packages/contracts/src/deviceSession.ts: `updatedAt: z.number()`), not an
+// ISO string.
+const UPDATED_AT_MS = Date.UTC(2026, 6, 1, 0, 0, 0, 0);
+const UPDATED_AT_ISO = new Date(UPDATED_AT_MS).toISOString();
+
+const state: DeviceSessionState = {
+  deviceId: 'device-1',
+  accounts: [
+    { accountId: 'a1', sessionId: 'sess-a1', authuser: 0 },
+    { accountId: 'a2', sessionId: 'sess-a2', authuser: 1 },
+  ],
+  activeAccountId: 'a2',
+  revision: 1,
+  updatedAt: UPDATED_AT_MS,
+};
+
+const usersById = new Map<string, User>([
+  ['a1', makeUser('a1')],
+  ['a2', makeUser('a2')],
+]);
+
+describe('projectSessionState', () => {
+  describe('activeSessionIdOf', () => {
+    test('returns the active account sessionId', () => {
+      expect(activeSessionIdOf(state)).toBe('sess-a2');
+    });
+
+    test('returns null for null state', () => {
+      expect(activeSessionIdOf(null)).toBeNull();
+    });
+
+    test('returns null when activeAccountId is null', () => {
+      expect(activeSessionIdOf({ ...state, activeAccountId: null })).toBeNull();
+    });
+  });
+
+  describe('deviceStateToClientSessions', () => {
+    test('maps every account in order with isCurrent + authuser', () => {
+      const sessions = deviceStateToClientSessions(state, usersById);
+      expect(sessions).toHaveLength(2);
+      expect(sessions[0]).toEqual({
+        sessionId: 'sess-a1',
+        deviceId: 'device-1',
+        expiresAt: UPDATED_AT_ISO,
+        lastActive: UPDATED_AT_ISO,
+        userId: 'a1',
+        isCurrent: false,
+        authuser: 0,
+      });
+      expect(sessions[1]).toEqual({
+        sessionId: 'sess-a2',
+        deviceId: 'device-1',
+        expiresAt: UPDATED_AT_ISO,
+        lastActive: UPDATED_AT_ISO,
+        userId: 'a2',
+        isCurrent: true,
+        authuser: 1,
+      });
+    });
+
+    test('still projects a session for an account absent from usersById', () => {
+      const sessions = deviceStateToClientSessions(state, new Map());
+      expect(sessions).toHaveLength(2);
+      expect(sessions.map((session) => session.userId)).toEqual(['a1', 'a2']);
+    });
+  });
+
+  describe('activeUserOf', () => {
+    test('returns the active account user', () => {
+      expect(activeUserOf(state, usersById)).toEqual(makeUser('a2'));
+    });
+
+    test('returns null for null state', () => {
+      expect(activeUserOf(null, usersById)).toBeNull();
+    });
+
+    test('returns null when activeAccountId is null', () => {
+      expect(activeUserOf({ ...state, activeAccountId: null }, usersById)).toBeNull();
+    });
+
+    test('returns null when the active account id is absent from usersById', () => {
+      expect(activeUserOf(state, new Map())).toBeNull();
+    });
+  });
+
+  describe('accountIdsOf', () => {
+    test('returns every account id in order', () => {
+      expect(accountIdsOf(state)).toEqual(['a1', 'a2']);
+    });
+
+    test('returns [] for null state', () => {
+      expect(accountIdsOf(null)).toEqual([]);
+    });
+  });
+});

package/src/ui/session/__tests__/sessionClientHost.test.ts

@@ -0,0 +1,43 @@
+import { createSessionClientHost } from '../sessionClientHost';
+
+function fakeOxy() {
+  const listeners = new Set<(t: string | null) => void>();
+  return {
+    makeRequest: jest.fn().mockResolvedValue({ ok: true }),
+    getBaseURL: jest.fn().mockReturnValue('https://api.oxy.so'),
+    getAccessToken: jest.fn().mockReturnValue('tok'),
+    setTokens: jest.fn(),
+    onTokensChanged: jest.fn((l: (t: string | null) => void) => { listeners.add(l); return () => listeners.delete(l); }),
+    _emit: (t: string | null) => listeners.forEach((l) => l(t)),
+  };
+}
+
+test('delegates REST + token methods to oxyServices', async () => {
+  const oxy = fakeOxy();
+  const host = createSessionClientHost(oxy as never);
+  await host.makeRequest('GET', '/session/device/state', undefined, { cache: false });
+  expect(oxy.makeRequest).toHaveBeenCalledWith('GET', '/session/device/state', undefined, { cache: false });
+  expect(host.getBaseURL()).toBe('https://api.oxy.so');
+  expect(host.getAccessToken()).toBe('tok');
+  host.setTokens('new');
+  expect(oxy.setTokens).toHaveBeenCalledWith('new');
+});
+
+test('getCurrentAccountId reflects setCurrentAccountId', () => {
+  const host = createSessionClientHost(fakeOxy() as never);
+  expect(host.getCurrentAccountId()).toBeNull();
+  host.setCurrentAccountId('u1');
+  expect(host.getCurrentAccountId()).toBe('u1');
+});
+
+test('onTokensChanged forwards to oxyServices and unsubscribes', () => {
+  const oxy = fakeOxy();
+  const host = createSessionClientHost(oxy as never);
+  const cb = jest.fn();
+  const unsub = host.onTokensChanged(cb);
+  oxy._emit(null);
+  expect(cb).toHaveBeenCalledWith(null);
+  unsub();
+  oxy._emit('x');
+  expect(cb).toHaveBeenCalledTimes(1);
+});

package/src/ui/session/__tests__/tokenTransport.test.ts

@@ -0,0 +1,142 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import { logger } from '@oxyhq/core';
+import { createTokenTransport } from '../tokenTransport';
+import { isWebBrowser } from '../../hooks/useWebSSO';
+
+jest.mock('../../hooks/useWebSSO', () => ({
+  isWebBrowser: jest.fn(),
+}));
+
+const mockedIsWebBrowser = isWebBrowser as jest.MockedFunction<typeof isWebBrowser>;
+
+function fakeOxy(accessToken: string | null) {
+  return {
+    getAccessToken: jest.fn().mockReturnValue(accessToken),
+    silentSignIn: jest.fn().mockResolvedValue(null),
+    signInWithSharedIdentity: jest.fn().mockResolvedValue(null),
+  };
+}
+
+const state: DeviceSessionState = {
+  deviceId: 'device-1',
+  accounts: [{ accountId: 'a1', sessionId: 'sess-a1', authuser: 0 }],
+  activeAccountId: 'a1',
+  revision: 1,
+  updatedAt: Date.UTC(2026, 6, 1, 0, 0, 0, 0),
+};
+
+describe('createTokenTransport', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  test('no-ops when a token is already present', async () => {
+    const oxy = fakeOxy('tok');
+    const transport = createTokenTransport(oxy as never);
+
+    await transport.ensureActiveToken(state);
+
+    expect(oxy.silentSignIn).not.toHaveBeenCalled();
+    expect(oxy.signInWithSharedIdentity).not.toHaveBeenCalled();
+  });
+
+  test('mints via silentSignIn on web when no token is present', async () => {
+    mockedIsWebBrowser.mockReturnValue(true);
+    const oxy = fakeOxy(null);
+    const transport = createTokenTransport(oxy as never);
+
+    await transport.ensureActiveToken(state);
+
+    expect(oxy.silentSignIn).toHaveBeenCalledTimes(1);
+    expect(oxy.signInWithSharedIdentity).not.toHaveBeenCalled();
+  });
+
+  test('mints via signInWithSharedIdentity off web when no token is present', async () => {
+    mockedIsWebBrowser.mockReturnValue(false);
+    const oxy = fakeOxy(null);
+    const transport = createTokenTransport(oxy as never);
+
+    await transport.ensureActiveToken(state);
+
+    expect(oxy.signInWithSharedIdentity).toHaveBeenCalledTimes(1);
+    expect(oxy.silentSignIn).not.toHaveBeenCalled();
+  });
+
+  test('resolves (never rejects) and logs a warning when the mint throws', async () => {
+    mockedIsWebBrowser.mockReturnValue(true);
+    const oxy = fakeOxy(null);
+    oxy.silentSignIn.mockRejectedValue(new Error('mint boom'));
+    const transport = createTokenTransport(oxy as never);
+    const warnSpy = jest.spyOn(logger, 'warn').mockImplementation(() => undefined);
+
+    await expect(transport.ensureActiveToken(state)).resolves.toBeUndefined();
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      'ensureActiveToken: mint failed',
+      { component: 'TokenTransport' },
+      expect.any(Error),
+    );
+
+    warnSpy.mockRestore();
+  });
+
+  test('resolves cleanly when the mint returns null', async () => {
+    mockedIsWebBrowser.mockReturnValue(true);
+    const oxy = fakeOxy(null);
+    const transport = createTokenTransport(oxy as never);
+
+    await expect(transport.ensureActiveToken(state)).resolves.toBeUndefined();
+    expect(oxy.silentSignIn).toHaveBeenCalledTimes(1);
+  });
+
+  test('coalesces concurrent calls into a single mint', async () => {
+    mockedIsWebBrowser.mockReturnValue(true);
+    const oxy = fakeOxy(null);
+    let resolveMint: ((value: null) => void) | null = null;
+    oxy.silentSignIn.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolveMint = resolve;
+        }),
+    );
+    const transport = createTokenTransport(oxy as never);
+
+    const first = transport.ensureActiveToken(state);
+    const second = transport.ensureActiveToken(state);
+
+    expect(oxy.silentSignIn).toHaveBeenCalledTimes(1);
+
+    resolveMint?.(null);
+    await Promise.all([first, second]);
+
+    expect(oxy.silentSignIn).toHaveBeenCalledTimes(1);
+
+    // A later call after the in-flight mint settled starts a fresh mint
+    // (the mock reassigns `resolveMint` on the second silentSignIn call).
+    const third = transport.ensureActiveToken(state);
+    expect(oxy.silentSignIn).toHaveBeenCalledTimes(2);
+    resolveMint?.(null);
+    await third;
+  });
+
+  test('treats a throwing getAccessToken as no-token and still mints', async () => {
+    mockedIsWebBrowser.mockReturnValue(true);
+    const oxy = fakeOxy(null);
+    oxy.getAccessToken.mockImplementation(() => {
+      throw new Error('storage unavailable');
+    });
+    const transport = createTokenTransport(oxy as never);
+    const warnSpy = jest.spyOn(logger, 'warn').mockImplementation(() => undefined);
+
+    await expect(transport.ensureActiveToken(state)).resolves.toBeUndefined();
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      'ensureActiveToken: getAccessToken threw',
+      { component: 'TokenTransport' },
+      expect.any(Error),
+    );
+    expect(oxy.silentSignIn).toHaveBeenCalledTimes(1);
+
+    warnSpy.mockRestore();
+  });
+});

package/src/ui/session/createSessionClient.ts

@@ -0,0 +1,21 @@
+import type { OxyServices } from '@oxyhq/core';
+import { SessionClient } from '@oxyhq/core';
+import { createSessionClientHost } from './sessionClientHost';
+import { createTokenTransport } from './tokenTransport';
+
+/**
+ * Wires a `SessionClient` for `@oxyhq/services`: builds the `SessionClientHost`
+ * adapter (Task 1) and the platform `TokenTransport` (Task 3) over the given
+ * `OxyServices` instance, and returns both the client and the host — the host
+ * is returned (not just the client) so `OxyContext` (Fase 3-B) can call
+ * `host.setCurrentAccountId(...)` as the active account changes.
+ */
+export function createSessionClient(oxyServices: OxyServices): {
+  client: SessionClient;
+  host: ReturnType<typeof createSessionClientHost>;
+} {
+  const host = createSessionClientHost(oxyServices);
+  const transport = createTokenTransport(oxyServices);
+  const client = new SessionClient(host, { transport });
+  return { client, host };
+}

package/src/ui/session/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Session-sync integration layer (Fase 3-A) — intra-package use only.
+ *
+ * These modules let `@oxyhq/services` drive the platform-agnostic
+ * `SessionClient` (in `@oxyhq/core`): a thin host adapter over `OxyServices`,
+ * pure `DeviceSessionState → services` projection helpers, a platform token
+ * transport, and the factory that wires them together. Nothing here is
+ * re-exported from the package root — `OxyContext` consumes it directly in
+ * Fase 3-B.
+ */
+export { createSessionClient } from './createSessionClient';
+export { createSessionClientHost } from './sessionClientHost';
+export { createTokenTransport } from './tokenTransport';
+export {
+  accountIdsOf,
+  activeSessionIdOf,
+  activeUserOf,
+  deviceStateToClientSessions,
+} from './projectSessionState';

package/src/ui/session/projectSessionState.ts

@@ -0,0 +1,85 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import type { ClientSession, User } from '@oxyhq/core';
+
+/**
+ * Pure projection helpers: `DeviceSessionState` (the device-scoped
+ * multi-account session-sync state produced by `@oxyhq/core`'s
+ * `SessionClient`) -> the shapes `OxyContext` renders today
+ * (`ClientSession[]`, an active session id, an active `User`).
+ *
+ * No I/O. The caller fetches profiles via
+ * `oxyServices.getUsersByIds(accountIdsOf(state))` and builds `usersById`
+ * from the result before calling `deviceStateToClientSessions` /
+ * `activeUserOf`.
+ */
+
+/**
+ * Maps every `SessionAccount` in `state.accounts` to a `ClientSession`.
+ *
+ * `DeviceSessionState` carries no per-account `expiresAt` / `lastActive` —
+ * both are set to `state.updatedAt` (converted to an ISO-8601 string; the
+ * wire value is an epoch-ms number) as a provisional value. Fase 3-B
+ * rewrites `ClientSession` to make `expiresAt`/`lastActive` optional (they
+ * are not derivable from `DeviceSessionState`).
+ *
+ * `usersById` is accepted for signature symmetry with `activeUserOf` even
+ * though `ClientSession` only stores `userId` — a session is still
+ * projected for an account whose id is absent from `usersById` (no
+ * placeholder user is fabricated).
+ */
+export function deviceStateToClientSessions(
+  state: DeviceSessionState,
+  usersById: Map<string, User>,
+): ClientSession[] {
+  const provisionalTimestamp = new Date(state.updatedAt).toISOString();
+  return state.accounts.map((account) => ({
+    sessionId: account.sessionId,
+    deviceId: state.deviceId,
+    // provisional: Fase 3-B rewrites ClientSession to make expiresAt/lastActive
+    // optional (they are not in DeviceSessionState)
+    expiresAt: provisionalTimestamp,
+    lastActive: provisionalTimestamp,
+    userId: account.accountId,
+    isCurrent: account.accountId === state.activeAccountId,
+    authuser: account.authuser,
+  }));
+}
+
+/**
+ * The active account's `sessionId`, or `null` when there is no state or no
+ * active account is set.
+ */
+export function activeSessionIdOf(state: DeviceSessionState | null): string | null {
+  if (state === null || state.activeAccountId === null) {
+    return null;
+  }
+  const activeAccountId = state.activeAccountId;
+  const activeAccount = state.accounts.find((account) => account.accountId === activeAccountId);
+  return activeAccount?.sessionId ?? null;
+}
+
+/**
+ * The active account's `User`, resolved from `usersById`. `null` when there
+ * is no state, no active account is set, or the active account id is absent
+ * from `usersById`.
+ */
+export function activeUserOf(
+  state: DeviceSessionState | null,
+  usersById: Map<string, User>,
+): User | null {
+  if (state === null || state.activeAccountId === null) {
+    return null;
+  }
+  return usersById.get(state.activeAccountId) ?? null;
+}
+
+/**
+ * All account ids in `state`, suitable for an `oxyServices.getUsersByIds(...)`
+ * fetch. `[]` for `null` state.
+ */
+export function accountIdsOf(state: DeviceSessionState | null): string[] {
+  if (state === null) {
+    return [];
+  }
+  return state.accounts.map((account) => account.accountId);
+}

package/src/ui/session/sessionClientHost.ts

@@ -0,0 +1,27 @@
+import type { OxyServices, SessionClientHost } from '@oxyhq/core';
+
+/**
+ * Thin `SessionClientHost` adapter over an `OxyServices` instance.
+ *
+ * `SessionClient` (in `@oxyhq/core`) is host-agnostic: it only needs a REST +
+ * token surface. `OxyServices` already exposes all of that except
+ * `getCurrentAccountId`, which has no direct equivalent — the adapter holds a
+ * mutable ref set by the caller (`OxyContext`, in Fase 3-B) via
+ * `setCurrentAccountId`.
+ */
+export function createSessionClientHost(
+  oxyServices: OxyServices,
+): SessionClientHost & { setCurrentAccountId(id: string | null): void } {
+  let currentAccountId: string | null = null;
+  return {
+    makeRequest: (method, url, data, options) => oxyServices.makeRequest(method, url, data, options),
+    getBaseURL: () => oxyServices.getBaseURL(),
+    getAccessToken: () => oxyServices.getAccessToken(),
+    onTokensChanged: (listener) => oxyServices.onTokensChanged(listener),
+    setTokens: (accessToken) => oxyServices.setTokens(accessToken),
+    getCurrentAccountId: () => currentAccountId,
+    setCurrentAccountId: (id) => {
+      currentAccountId = id;
+    },
+  };
+}

package/src/ui/session/tokenTransport.ts

@@ -0,0 +1,76 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import type { OxyServices, TokenTransport } from '@oxyhq/core';
+import { logger } from '@oxyhq/core';
+import { isWebBrowser } from '../hooks/useWebSSO';
+
+/**
+ * Platform `TokenTransport` for `SessionClient`: mints an access token when
+ * none is currently held, reusing the SAME primitives `OxyContext`'s cold
+ * boot already relies on (never re-implemented here):
+ *
+ * - web: `oxyServices.silentSignIn()` (per-apex `/auth/silent` iframe).
+ * - native: `oxyServices.signInWithSharedIdentity()` (app-group keychain).
+ *
+ * Both primitives plant the token internally on success (the "Sign-In Token
+ * Planting" rule) — `ensureActiveToken` never calls `setTokens` itself.
+ *
+ * `ensureActiveToken` treats a PRESENT token as sufficient in this phase; it
+ * does not decode/match the token's subject against `state.activeAccountId`
+ * (that refinement is Fase 3-B). Account switching itself is server-driven
+ * via the `activeToken` carried in the sync envelope — this transport is
+ * only the fallback used when the envelope carried no token.
+ *
+ * A failed mint is logged and swallowed: it must never throw out of
+ * `ensureActiveToken`, since that would crash the caller (the SessionClient
+ * socket handler in Fase 3-B).
+ */
+export function createTokenTransport(oxyServices: OxyServices): TokenTransport {
+  // Coalesces concurrent mints: `SessionClient.applyState` can fire
+  // `ensureActiveToken` on rapid successive state pushes; a second call while a
+  // mint is already in flight must reuse it, not spawn a second silent iframe /
+  // shared-key challenge round-trip.
+  let inFlightMint: Promise<void> | null = null;
+
+  return {
+    async ensureActiveToken(state: DeviceSessionState): Promise<void> {
+      // Read the current token defensively: it is an in-memory getter that
+      // should never throw, but the documented contract is that this method
+      // never throws out — so a surprising throw is logged and treated as "no
+      // token" (fall through to mint) rather than rejecting the promise.
+      try {
+        if (oxyServices.getAccessToken()) {
+          return;
+        }
+      } catch (error) {
+        logger.warn('ensureActiveToken: getAccessToken threw', { component: 'TokenTransport' }, error);
+      }
+
+      if (inFlightMint) {
+        return inFlightMint;
+      }
+
+      inFlightMint = (async () => {
+        try {
+          const session = isWebBrowser()
+            ? await oxyServices.silentSignIn()
+            : await oxyServices.signInWithSharedIdentity();
+
+          if (!session) {
+            logger.debug('ensureActiveToken: platform mint returned no session', {
+              component: 'TokenTransport',
+              deviceId: state.deviceId,
+            });
+          }
+        } catch (error) {
+          logger.warn('ensureActiveToken: mint failed', { component: 'TokenTransport' }, error);
+        }
+      })();
+
+      try {
+        await inFlightMint;
+      } finally {
+        inFlightMint = null;
+      }
+    },
+  };
+}