@oxyhq/core 5.2.0 → 5.3.0

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

@@ -0,0 +1,132 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+
+type Handler = (...args: unknown[]) => void;
+class FakeSocket {
+  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; this.trigger('connect'); }
+  disconnect() { this.connected = false; }
+  trigger(event: string, ...args: unknown[]) { for (const h of this.handlers.get(event) ?? []) h(...args); }
+}
+let fakeSocket: FakeSocket;
+const ioMock = jest.fn((_uri: string, opts?: Record<string, unknown>) => {
+  // honor autoConnect like real socket.io (connect immediately unless autoConnect:false)
+  if (!opts || opts.autoConnect !== false) fakeSocket.connected = true;
+  return fakeSocket;
+});
+jest.mock('socket.io-client', () => ({ __esModule: true, io: (...args: unknown[]) => ioMock(...(args as [string, Record<string, unknown>?])) }));
+
+import { SessionClient, type SessionClientHost } from '../SessionClient';
+
+const STATE = (rev: number): DeviceSessionState => ({ deviceId: 'd1', accounts: [{ accountId: 'a1', sessionId: 's1', authuser: 0 }], activeAccountId: 'a1', revision: rev, updatedAt: 1720000000000 });
+// The server wraps the sync payload in a REST `{ data }` envelope; makeRequest does NOT unwrap it.
+const SYNC = (rev: number) => ({ data: { 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,
+  };
+}
+
+beforeEach(() => { fakeSocket = new FakeSocket(); ioMock.mockClear(); });
+
+describe('SessionClient socket', () => {
+  it('start() bootstraps then opens ONE socket to the base URL with a token-in-handshake auth callback', async () => {
+    const host = makeHost();
+    const c = new SessionClient(host);
+    await c.start();
+    expect(host.makeRequest).toHaveBeenCalledWith('GET', '/session/device/state', undefined, { cache: false });
+    expect(ioMock).toHaveBeenCalledTimes(1);
+    const [uri, opts] = ioMock.mock.calls[0];
+    expect(uri).toBe('http://test.invalid');
+    const authCb = jest.fn();
+    (opts?.auth as (cb: (d: { token: string }) => void) => void)(authCb);
+    expect(authCb).toHaveBeenCalledWith({ token: 'tok' });
+    c.stop();
+  });
+
+  it('applies a pushed session_state event', async () => {
+    const c = new SessionClient(makeHost());
+    await c.start();
+    fakeSocket.trigger('session_state', STATE(9));
+    expect(c.getState()?.revision).toBe(9);
+    c.stop();
+  });
+
+  it('fetches the active token via bootstrap when a pushed state changes the active account', async () => {
+    const makeRequest = jest.fn().mockResolvedValue(SYNC(1));
+    const host = makeHost({ makeRequest, getCurrentAccountId: () => 'other-account' });
+    const c = new SessionClient(host);
+    await c.start();
+    makeRequest.mockClear();
+    fakeSocket.trigger('session_state', STATE(9));
+    await Promise.resolve();
+    expect(makeRequest).toHaveBeenCalledWith('GET', '/session/device/state', undefined, { cache: false });
+    c.stop();
+  });
+
+  it('C1 regression: plants the active token on a socket-pushed switch even when the post-push bootstrap returns the SAME revision as the push', async () => {
+    const setTokens = jest.fn();
+    const makeRequest = jest
+      .fn()
+      .mockResolvedValueOnce(SYNC(1)) // initial bootstrap in start()
+      .mockResolvedValue(SYNC(9)); // post-push bootstrap: same revision as the socket push below
+    const host = makeHost({ makeRequest, setTokens, getCurrentAccountId: () => 'other-account' });
+    const c = new SessionClient(host);
+    await c.start();
+    makeRequest.mockClear();
+    setTokens.mockClear();
+    fakeSocket.trigger('session_state', STATE(9));
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(makeRequest).toHaveBeenCalledWith('GET', '/session/device/state', undefined, { cache: false });
+    expect(setTokens).toHaveBeenCalledWith('jwt-9');
+    c.stop();
+  });
+
+  it('does not re-fetch when the pushed active account matches the host-held account', async () => {
+    const makeRequest = jest.fn().mockResolvedValue(SYNC(1));
+    const host = makeHost({ makeRequest, getCurrentAccountId: () => 'a1' });
+    const c = new SessionClient(host);
+    await c.start();
+    makeRequest.mockClear();
+    fakeSocket.trigger('session_state', STATE(9));
+    await Promise.resolve();
+    expect(makeRequest).not.toHaveBeenCalled();
+    c.stop();
+  });
+
+  it('does not connect the socket when there is no token (autoConnect false)', async () => {
+    const c = new SessionClient(makeHost({ getAccessToken: () => null }));
+    await c.start();
+    const [, opts] = ioMock.mock.calls[0];
+    expect(opts?.autoConnect).toBe(false);
+    c.stop();
+  });
+
+  it('reconnects when a token arrives after being disconnected', async () => {
+    let tokenListener: ((t: string | null) => void) | null = null;
+    const host = makeHost({ getAccessToken: () => null, onTokensChanged: (l) => { tokenListener = l; return () => undefined; } });
+    const c = new SessionClient(host);
+    await c.start();
+    fakeSocket.connected = false;
+    tokenListener?.('fresh-token');
+    expect(fakeSocket.connected).toBe(true);
+    c.stop();
+  });
+
+  it('stop() disconnects the socket', async () => {
+    const c = new SessionClient(makeHost());
+    await c.start();
+    c.stop();
+    expect(fakeSocket.connected).toBe(false);
+  });
+});

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

@@ -0,0 +1,64 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import { SessionClient, type SessionClientHost, type TokenTransport } from '../SessionClient';
+
+function makeHost(): SessionClientHost {
+  return {
+    makeRequest: jest.fn(),
+    getBaseURL: () => 'http://test.invalid',
+    getAccessToken: () => 't',
+    onTokensChanged: () => () => undefined,
+    setTokens: jest.fn(),
+    getCurrentAccountId: () => null,
+  };
+}
+const STATE = (rev: number, active: string | null = 'a1'): DeviceSessionState => ({
+  deviceId: 'd1', accounts: active ? [{ accountId: 'a1', sessionId: 's1', authuser: 0 }] : [], activeAccountId: active, revision: rev, updatedAt: 1720000000000,
+});
+
+// SessionClient.applyState is protected; a tiny subclass exposes it for the unit test.
+class TestClient extends SessionClient { public apply(raw: unknown): boolean { return this.applyState(raw); } }
+
+describe('SessionClient state', () => {
+  it('starts with null state', () => {
+    expect(new SessionClient(makeHost()).getState()).toBeNull();
+  });
+
+  it('applies a valid state and notifies subscribers', () => {
+    const c = new TestClient(makeHost());
+    const seen: (DeviceSessionState | null)[] = [];
+    c.subscribe((s) => seen.push(s));
+    expect(c.apply(STATE(1))).toBe(true);
+    expect(c.getState()?.revision).toBe(1);
+    expect(seen.at(-1)?.revision).toBe(1);
+  });
+
+  it('ignores a stale or equal revision (last-writer-wins)', () => {
+    const c = new TestClient(makeHost());
+    c.apply(STATE(5));
+    expect(c.apply(STATE(5))).toBe(false);
+    expect(c.apply(STATE(4))).toBe(false);
+    expect(c.getState()?.revision).toBe(5);
+  });
+
+  it('rejects an invalid (unvalidated) state without applying', () => {
+    const c = new TestClient(makeHost());
+    expect(c.apply({ deviceId: 'd1', accounts: 'nope', revision: 1 })).toBe(false);
+    expect(c.getState()).toBeNull();
+  });
+
+  it('calls transport.ensureActiveToken when a state is applied', () => {
+    const transport: TokenTransport = { ensureActiveToken: jest.fn().mockResolvedValue(undefined) };
+    const c = new TestClient(makeHost(), { transport });
+    c.apply(STATE(1));
+    expect(transport.ensureActiveToken).toHaveBeenCalledWith(expect.objectContaining({ revision: 1 }));
+  });
+
+  it('unsubscribe stops notifications', () => {
+    const c = new TestClient(makeHost());
+    const seen: unknown[] = [];
+    const off = c.subscribe((s) => seen.push(s));
+    off();
+    c.apply(STATE(1));
+    expect(seen).toHaveLength(0);
+  });
+});

package/src/session/__tests__/sessionIntegration.test.ts

@@ -0,0 +1,202 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import type { User } from '../../models/interfaces';
+import { SessionClient, type TokenTransport } from '../SessionClient';
+import { createSessionClientHost } from '../sessionClientHost';
+import { createSessionClient } from '../createSessionClient';
+import {
+  accountIdsOf,
+  activeSessionIdOf,
+  activeUserOf,
+  deviceStateToClientSessions,
+} from '../projectSessionState';
+
+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)),
+  };
+}
+
+describe('createSessionClientHost', () => {
+  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);
+  });
+});
+
+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([]);
+    });
+  });
+});
+
+describe('createSessionClient', () => {
+  function fakeTransport(): TokenTransport {
+    return { ensureActiveToken: jest.fn().mockResolvedValue(undefined) };
+  }
+
+  test('wires a SessionClient instance backed by the host + injected transport', () => {
+    const oxy = fakeOxy();
+
+    const { client, host } = createSessionClient(oxy as never, fakeTransport());
+
+    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, fakeTransport());
+
+    expect(host.getCurrentAccountId()).toBeNull();
+    host.setCurrentAccountId('u1');
+    expect(host.getCurrentAccountId()).toBe('u1');
+  });
+
+  test('uses the injected transport (not a hard-coded one) when the client bootstraps', async () => {
+    const oxy = fakeOxy();
+    oxy.makeRequest.mockResolvedValue({ data: { state, activeToken: null } });
+    const transport = fakeTransport();
+
+    const { client } = createSessionClient(oxy as never, transport);
+    await client.bootstrap();
+
+    expect(transport.ensureActiveToken).toHaveBeenCalledWith(expect.objectContaining({ revision: state.revision }));
+  });
+});

package/src/session/createSessionClient.ts

@@ -0,0 +1,31 @@
+import type { OxyServices } from '../OxyServices';
+import { SessionClient, type TokenTransport } from './SessionClient';
+import { createSessionClientHost } from './sessionClientHost';
+
+/**
+ * Wires a `SessionClient` over the given `OxyServices` instance: builds the
+ * `SessionClientHost` adapter and passes it through together with a
+ * caller-supplied `TokenTransport`.
+ *
+ * The transport is a required parameter (not constructed here) because it is
+ * the one piece of this integration that is NOT platform-agnostic: `services`
+ * branches native (shared-keychain sign-in) vs. web (silent sign-in), while
+ * `auth-sdk` is web-only. Each consumer builds its own transport and passes
+ * it in; this factory only wires the platform-agnostic parts (host + client)
+ * so neither consumer re-implements them.
+ *
+ * The host is returned alongside the client (not just the client) so the
+ * caller can call `host.setCurrentAccountId(...)` as the active account
+ * changes.
+ */
+export function createSessionClient(
+  oxyServices: OxyServices,
+  transport: TokenTransport,
+): {
+  client: SessionClient;
+  host: ReturnType<typeof createSessionClientHost>;
+} {
+  const host = createSessionClientHost(oxyServices);
+  const client = new SessionClient(host, { transport });
+  return { client, host };
+}

package/src/session/projectSessionState.ts

@@ -0,0 +1,83 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import type { ClientSession } from '../models/session';
+import type { User } from '../models/interfaces';
+
+/**
+ * Pure projection helpers: `DeviceSessionState` (the device-scoped
+ * multi-account session-sync state produced by `SessionClient`) -> the
+ * shapes consumers (`@oxyhq/services`, `@oxyhq/auth`) render 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.
+ *
+ * `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: expiresAt/lastActive are not carried on 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/session/sessionClientHost.ts

@@ -0,0 +1,32 @@
+import type { OxyServices } from '../OxyServices';
+import type { SessionClientHost } from './SessionClient';
+
+/**
+ * Thin `SessionClientHost` adapter over an `OxyServices` instance.
+ *
+ * `SessionClient` 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 `@oxyhq/services`, `WebOxyProvider` in
+ * `@oxyhq/auth`) via `setCurrentAccountId`.
+ *
+ * Shared here (rather than duplicated per consumer) because it is entirely
+ * platform-agnostic: every method it calls exists identically on
+ * `OxyServices` regardless of host (web, Expo/RN, Node).
+ */
+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/session/socketLoader.ts

@@ -0,0 +1,28 @@
+import { logger } from '../utils/loggerUtils';
+
+export interface MinimalSocket {
+  connected: boolean;
+  on(event: string, handler: (...args: unknown[]) => void): void;
+  off(event: string, handler?: (...args: unknown[]) => void): void;
+  connect(): void;
+  disconnect(): void;
+}
+
+export type SocketIOFactory = (uri: string, opts?: Record<string, unknown>) => MinimalSocket;
+
+let cachedFactory: SocketIOFactory | null = null;
+let loadAttempted = false;
+
+export async function getSocketIO(): Promise<SocketIOFactory | null> {
+  if (cachedFactory) return cachedFactory;
+  if (loadAttempted) return null;
+  loadAttempted = true;
+  try {
+    const mod = (await import('socket.io-client')) as { io?: SocketIOFactory; default?: SocketIOFactory };
+    cachedFactory = mod.io ?? mod.default ?? null;
+    return cachedFactory;
+  } catch (error) {
+    logger.warn('[SessionClient] socket.io-client import failed; realtime session sync disabled', { component: 'SessionClient' }, error);
+    return null;
+  }
+}