@oxy.so/core 1.0.0

package/src/mixins/__tests__/appData.test.ts

@@ -0,0 +1,203 @@
+/**
+ * App-Data Mixin Tests
+ *
+ * Exercises the typed helpers around `/users/me/app-data/...`. We stub
+ * `makeRequest` so the tests run without a network or a database — what we
+ * care about here is request shape (method, URL, body), identifier
+ * validation, and response handling (`null` when missing, echo on write).
+ *
+ * The mixin sits behind `withAuthRetry`, which polls for a token before
+ * running the operation. We force a token in via `__resetTokensForTests`'
+ * companion path (set access token directly) so the auth wait short-circuits.
+ */
+
+import { OxyServices } from '../../OxyServices';
+import { OxyAppDataIdentifierError } from '../OxyServices.appData';
+
+const setAccessTokenForTest = (oxy: OxyServices): void => {
+  // Tokens are managed by HttpService — `hasAccessToken()` is the gate the
+  // `withAuthRetry` loop polls. Reaching in via the public httpService and
+  // calling setTokens with a dummy avoids us needing to expose new test
+  // hooks just for this.
+  oxy.httpService.setTokens('test-token');
+};
+
+describe('OxyServices.appData', () => {
+  let oxy: OxyServices;
+  let makeRequestSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    setAccessTokenForTest(oxy);
+    makeRequestSpy = jest.spyOn(oxy, 'makeRequest');
+  });
+
+  afterEach(() => {
+    makeRequestSpy.mockRestore();
+  });
+
+  describe('getAppData', () => {
+    it('returns the stored value when the API responds with one', async () => {
+      makeRequestSpy.mockResolvedValue({ value: { completed: ['intro'] } });
+
+      const result = await oxy.getAppData<{ completed: string[] }>(
+        'academy',
+        'getting-started',
+      );
+
+      expect(result).toEqual({ completed: ['intro'] });
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'GET',
+        '/users/me/app-data/academy/getting-started',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+    });
+
+    it('returns null when the API responds with `value: null`', async () => {
+      makeRequestSpy.mockResolvedValue({ value: null });
+      const result = await oxy.getAppData('academy', 'unknown');
+      expect(result).toBeNull();
+    });
+
+    it('returns null when the response object is missing `value`', async () => {
+      makeRequestSpy.mockResolvedValue({});
+      const result = await oxy.getAppData('academy', 'unknown');
+      expect(result).toBeNull();
+    });
+
+    it('URL-encodes namespace and key path segments', async () => {
+      makeRequestSpy.mockResolvedValue({ value: 'ok' });
+      await oxy.getAppData('a-b_c', 'd-e_f');
+      // URL-encoding is a no-op for our allowed character set, but we still
+      // run through encodeURIComponent — make sure that's wired so the call
+      // site doesn't accidentally bypass it later.
+      expect(makeRequestSpy.mock.calls[0][1]).toBe('/users/me/app-data/a-b_c/d-e_f');
+    });
+
+    it('throws OxyAppDataIdentifierError for invalid namespace', async () => {
+      await expect(oxy.getAppData('Bad Namespace', 'k')).rejects.toBeInstanceOf(
+        OxyAppDataIdentifierError,
+      );
+      expect(makeRequestSpy).not.toHaveBeenCalled();
+    });
+
+    it('throws OxyAppDataIdentifierError for invalid key', async () => {
+      await expect(oxy.getAppData('ns', 'Bad/Key')).rejects.toBeInstanceOf(
+        OxyAppDataIdentifierError,
+      );
+      expect(makeRequestSpy).not.toHaveBeenCalled();
+    });
+
+    it('rejects empty identifiers (regex requires at least one char)', async () => {
+      await expect(oxy.getAppData('', 'k')).rejects.toBeInstanceOf(
+        OxyAppDataIdentifierError,
+      );
+      await expect(oxy.getAppData('n', '')).rejects.toBeInstanceOf(
+        OxyAppDataIdentifierError,
+      );
+    });
+
+    it('rejects identifiers longer than 64 chars', async () => {
+      const tooLong = 'a'.repeat(65);
+      await expect(oxy.getAppData(tooLong, 'k')).rejects.toBeInstanceOf(
+        OxyAppDataIdentifierError,
+      );
+    });
+
+    it('surfaces API errors (e.g. 401) via withAuthRetry', async () => {
+      const err = Object.assign(new Error('Authentication required'), {
+        response: { status: 401 },
+      });
+      makeRequestSpy.mockRejectedValue(err);
+      await expect(oxy.getAppData('academy', 'getting-started')).rejects.toThrow();
+    });
+  });
+
+  describe('setAppData', () => {
+    it('writes the value and returns the server-echoed value', async () => {
+      makeRequestSpy.mockResolvedValue({ value: { completed: ['intro'] } });
+
+      const result = await oxy.setAppData('academy', 'getting-started', {
+        completed: ['intro'],
+      });
+
+      expect(result).toEqual({ completed: ['intro'] });
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'PUT',
+        '/users/me/app-data/academy/getting-started',
+        { value: { completed: ['intro'] } },
+        expect.objectContaining({ cache: false }),
+      );
+    });
+
+    it('falls back to the caller value when the server response omits it', async () => {
+      makeRequestSpy.mockResolvedValue({});
+      const result = await oxy.setAppData('academy', 'k', 'hello');
+      expect(result).toBe('hello');
+    });
+
+    it('throws OxyAppDataIdentifierError before issuing a request', async () => {
+      await expect(oxy.setAppData('UPPER', 'k', 1)).rejects.toBeInstanceOf(
+        OxyAppDataIdentifierError,
+      );
+      expect(makeRequestSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('deleteAppData', () => {
+    it('issues a DELETE and resolves', async () => {
+      makeRequestSpy.mockResolvedValue(undefined);
+
+      await expect(oxy.deleteAppData('academy', 'getting-started')).resolves.toBeUndefined();
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'DELETE',
+        '/users/me/app-data/academy/getting-started',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+    });
+
+    it('throws OxyAppDataIdentifierError on invalid identifiers', async () => {
+      await expect(oxy.deleteAppData('ns', 'BAD KEY')).rejects.toBeInstanceOf(
+        OxyAppDataIdentifierError,
+      );
+    });
+  });
+
+  describe('listAppData', () => {
+    it('returns the entries map from the API', async () => {
+      makeRequestSpy.mockResolvedValue({
+        entries: {
+          'getting-started': { completed: ['intro'] },
+          'using-oxy-id': { completed: [] },
+        },
+      });
+
+      const result = await oxy.listAppData<{ completed: string[] }>('academy');
+
+      expect(result).toEqual({
+        'getting-started': { completed: ['intro'] },
+        'using-oxy-id': { completed: [] },
+      });
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'GET',
+        '/users/me/app-data/academy',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+    });
+
+    it('returns an empty object when the API returns no entries', async () => {
+      makeRequestSpy.mockResolvedValue({});
+      const result = await oxy.listAppData('academy');
+      expect(result).toEqual({});
+    });
+
+    it('throws OxyAppDataIdentifierError on invalid namespace', async () => {
+      await expect(oxy.listAppData('Bad Namespace')).rejects.toBeInstanceOf(
+        OxyAppDataIdentifierError,
+      );
+    });
+  });
+});

package/src/mixins/__tests__/assetCredentials.test.ts

@@ -0,0 +1,47 @@
+import { OxyServices } from '../../OxyServices';
+
+interface FetchCall {
+  url: string;
+  init: RequestInit | undefined;
+}
+
+describe('asset fetch credentials', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+  });
+
+  it('omits credentials for arbitrary asset content URLs', async () => {
+    const calls: FetchCall[] = [];
+    globalThis.fetch = async (input, init) => {
+      calls.push({ url: String(input), init });
+      return new Response('asset-body', { status: 200 });
+    };
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+
+    await oxy.fetchAssetContent('https://attacker.oxy.so/cdn/object.txt', 'text');
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toBe('https://attacker.oxy.so/cdn/object.txt');
+    expect(calls[0].init?.credentials).toBe('omit');
+  });
+
+  it('includes credentials for asset content fetched from the configured API origin', async () => {
+    const calls: FetchCall[] = [];
+    globalThis.fetch = async (input, init) => {
+      calls.push({ url: String(input), init });
+      return new Response('asset-body', { status: 200 });
+    };
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+
+    await oxy.fetchAssetContent('https://api.oxy.so/assets/private-file/stream', 'text');
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toBe('https://api.oxy.so/assets/private-file/stream');
+    expect(calls[0].init?.credentials).toBe('include');
+  });
+});

package/src/mixins/__tests__/assetUpload.test.ts

@@ -0,0 +1,191 @@
+/**
+ * `OxyServices.assetUpload()` multipart-body tests.
+ *
+ * `assetUpload` accepts three input shapes: a web `File`, a web `Blob`, or a
+ * React Native `{ uri, type?, name?, size? }` descriptor. The descriptor path
+ * is platform-sensitive:
+ *
+ *   - React Native — RN's FormData reads the file from disk via the uri during
+ *     the multipart request, so the descriptor is appended as-is.
+ *   - Web (browser/Node) — the browser's FormData CANNOT read bytes from a plain
+ *     `{ uri }` object (it would serialize `[object Object]` → the server stores
+ *     a 0-byte asset). The uri must be materialized into a real `Blob` via
+ *     `fetch` before appending. An empty fetched blob must throw instead of
+ *     silently uploading an empty asset.
+ *
+ * These tests assert exactly which value lands in the FormData `file` part for
+ * each platform, and that an empty web source is rejected.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+/**
+ * Captures every `FormData.append` call so a test can inspect the multipart body
+ * that `assetUpload` built without sending a real network request.
+ */
+function captureUpload(oxy: OxyServices) {
+  const appended: Array<{ name: string; value: unknown; fileName?: string }> = [];
+  // Capture-only: do NOT delegate to the real (undici) FormData.append. Node's
+  // undici rejects a plain { uri } object as not-a-Blob, but real React Native
+  // FormData accepts it — the test asserts on captured args, not a built body.
+  const appendSpy = jest
+    .spyOn(FormData.prototype, 'append')
+    .mockImplementation(function (this: FormData, name: string, value: unknown, fileName?: string) {
+      appended.push({ name, value, fileName });
+    });
+
+  const requestSpy = jest
+    .spyOn(oxy.getClient(), 'request')
+    .mockResolvedValue({ file: { id: 'asset123' } } as never);
+
+  return {
+    appended,
+    requestSpy,
+    restore: () => {
+      appendSpy.mockRestore();
+      requestSpy.mockRestore();
+    },
+  };
+}
+
+describe('OxyServices.assetUpload — uri descriptor', () => {
+  const originalNavigator = (globalThis as { navigator?: unknown }).navigator;
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    if (originalNavigator === undefined) {
+      delete (globalThis as { navigator?: unknown }).navigator;
+    } else {
+      (globalThis as { navigator?: unknown }).navigator = originalNavigator;
+    }
+    globalThis.fetch = originalFetch;
+  });
+
+  describe('web (NOT React Native)', () => {
+    beforeEach(() => {
+      // Node/jsdom-like: no React Native navigator → isReactNative() === false.
+      delete (globalThis as { navigator?: unknown }).navigator;
+    });
+
+    it('materializes a blob: uri into a real, non-empty Blob before appending', async () => {
+      const bytes = new Blob([new Uint8Array([1, 2, 3, 4, 5])], { type: 'image/png' });
+      const fetchMock = jest
+        .fn()
+        .mockResolvedValue({ ok: true, status: 200, blob: async () => bytes });
+      globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+      const capture = captureUpload(oxy);
+
+      try {
+        await oxy.assetUpload({ uri: 'blob:https://app.test/abc', type: 'image/png', name: 'avatar.png' });
+
+        expect(fetchMock).toHaveBeenCalledWith('blob:https://app.test/abc');
+
+        const filePart = capture.appended.find((p) => p.name === 'file');
+        expect(filePart).toBeDefined();
+        // The appended value is the fetched Blob with real bytes — NOT the { uri } object.
+        expect(filePart?.value).toBeInstanceOf(Blob);
+        expect((filePart?.value as Blob).size).toBe(5);
+        expect((filePart?.value as { uri?: string }).uri).toBeUndefined();
+        expect(filePart?.fileName).toBe('avatar.png');
+      } finally {
+        capture.restore();
+      }
+    });
+
+    it('wraps a typeless fetched blob with the descriptor MIME type', async () => {
+      const typeless = new Blob([new Uint8Array([9, 9, 9])]); // type === ''
+      const fetchMock = jest
+        .fn()
+        .mockResolvedValue({ ok: true, status: 200, blob: async () => typeless });
+      globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+      const capture = captureUpload(oxy);
+
+      try {
+        await oxy.assetUpload({ uri: 'data:application/octet-stream;base64,CQkJ', type: 'image/jpeg', name: 'x.jpg' });
+
+        const filePart = capture.appended.find((p) => p.name === 'file');
+        expect(filePart?.value).toBeInstanceOf(Blob);
+        expect((filePart?.value as Blob).size).toBe(3);
+        expect((filePart?.value as Blob).type).toBe('image/jpeg');
+      } finally {
+        capture.restore();
+      }
+    });
+
+    it('throws "Cannot upload an empty file" when the fetched blob is empty', async () => {
+      const empty = new Blob([], { type: 'image/png' });
+      const fetchMock = jest
+        .fn()
+        .mockResolvedValue({ ok: true, status: 200, blob: async () => empty });
+      globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+      const capture = captureUpload(oxy);
+
+      try {
+        await expect(
+          oxy.assetUpload({ uri: 'blob:https://app.test/empty', type: 'image/png', name: 'empty.png' }),
+        ).rejects.toThrow('Cannot upload an empty file');
+
+        // Nothing was sent — the empty source surfaces instead of creating a 0-byte asset.
+        expect(capture.requestSpy).not.toHaveBeenCalled();
+      } finally {
+        capture.restore();
+      }
+    });
+
+    it('throws when the uri cannot be fetched (non-ok response)', async () => {
+      const fetchMock = jest
+        .fn()
+        .mockResolvedValue({ ok: false, status: 404, blob: async () => new Blob([]) });
+      globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+      const capture = captureUpload(oxy);
+
+      try {
+        await expect(
+          oxy.assetUpload({ uri: 'https://cdn.test/missing.png', type: 'image/png', name: 'missing.png' }),
+        ).rejects.toThrow('Failed to read file from uri (status 404)');
+        expect(capture.requestSpy).not.toHaveBeenCalled();
+      } finally {
+        capture.restore();
+      }
+    });
+  });
+
+  describe('React Native', () => {
+    beforeEach(() => {
+      // Make isReactNative() === true: navigator.product === 'ReactNative'.
+      (globalThis as { navigator?: unknown }).navigator = { product: 'ReactNative' };
+    });
+
+    it('appends the descriptor as-is and never calls fetch', async () => {
+      const fetchMock = jest.fn();
+      globalThis.fetch = fetchMock as unknown as typeof fetch;
+
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+      const capture = captureUpload(oxy);
+
+      const descriptor = { uri: 'file:///tmp/avatar.png', type: 'image/png', name: 'avatar.png', size: 1024 };
+
+      try {
+        await oxy.assetUpload(descriptor);
+
+        // RN path: the raw descriptor object lands in the multipart body unchanged.
+        const filePart = capture.appended.find((p) => p.name === 'file');
+        expect(filePart?.value).toBe(descriptor);
+        expect(filePart?.fileName).toBe('avatar.png');
+        // No in-JS materialization on RN — FormData reads the file from the uri.
+        expect(fetchMock).not.toHaveBeenCalled();
+      } finally {
+        capture.restore();
+      }
+    });
+  });
+});

package/src/mixins/__tests__/backgroundCredential.httpIntegration.test.ts

@@ -0,0 +1,135 @@
+import type { DeviceBackgroundCredentialResponse } from '@oxy.so/contracts';
+import { OxyServices } from '../../OxyServices';
+
+/**
+ * Real-stack integration test for `provisionBackgroundCredential`: a genuine
+ * `HttpService` (via `OxyServices`) with `global.fetch` stubbed to return the
+ * EXACT wire bodies oxy-api sends, rather than a `makeRequest` spy.
+ *
+ * The unit suite (`OxyServices.deviceBoot.test.ts`) stubs `makeRequest`, so by
+ * construction it cannot see either of the two things this file pins:
+ *
+ *  1. **The `{ data }` envelope.** The route answers
+ *     `{ data: { deviceId, secret, accountId, expiresAt } }`, and
+ *     `HttpService.unwrapResponse` strips that outer envelope — so the mixin
+ *     must validate the FLAT credential and must not read `.data` a second
+ *     time. A spy returning the flat shape asserts that assumption instead of
+ *     testing it; the same blind spot produced a P0 in `SessionClient` (see
+ *     `SessionClient.httpIntegration.test.ts`).
+ *  2. **The 404 degrade against the REAL error object.** The `404 → null` path
+ *     is what keeps a client on a newer SDK than the server from breaking, and
+ *     it keys on the status surviving whatever `HttpService` throws. A
+ *     hand-built `Object.assign(new Error(), { status: 404 })` proves only that
+ *     the branch reads the shape the test itself invented.
+ *
+ * The stub is URL-aware because a state-changing request through the real stack
+ * fetches `GET /csrf-token` FIRST. A blanket stub answers that call too, which
+ * both shifts the request under test out of `calls[0]` and (on a non-200 stub)
+ * makes the CSRF fetch burn its own retries — so a naive call-count assertion
+ * measures CSRF attempts rather than the route.
+ */
+const ROUTE = '/session/device/background-credential';
+
+const CREDENTIAL: DeviceBackgroundCredentialResponse = {
+  deviceId: 'device-real',
+  secret: 'bg-secret-from-the-wire',
+  accountId: 'acct-1',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+};
+
+/** The route's success body: the credential under this API's `data` envelope. */
+const ROUTE_BODY = { data: CREDENTIAL };
+
+/** oxy-api's 404 body for an unmatched path (server.ts's terminal handler). */
+const NOT_FOUND_BODY = { error: 'NOT_FOUND', message: 'Resource not found' };
+
+const jsonResponse = (body: unknown, status: number) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+
+/**
+ * A syntactically real, far-future access token. It must be a decodable JWT:
+ * `HttpService.getAuthHeader` runs `jwtDecode` and sends NO bearer at all when
+ * that throws, so an opaque placeholder would silently turn this into an
+ * anonymous request and make the bearer assertion below untestable.
+ */
+const ACCESS_TOKEN = (() => {
+  const segment = (payload: object) => Buffer.from(JSON.stringify(payload)).toString('base64url');
+  return [
+    segment({ alg: 'none', typ: 'JWT' }),
+    segment({ sub: 'acct-1', exp: 4_102_444_800 }), // 2100-01-01
+    'signature-not-verified-client-side',
+  ].join('.');
+})();
+
+describe('provisionBackgroundCredential over a real HttpService', () => {
+  const originalFetch = global.fetch;
+
+  /** Answers the CSRF preflight properly; answers the route under test with `body`/`status`. */
+  const stubFetch = (body: unknown, status: number) => {
+    const fetchMock = jest.fn(async (input: unknown) => {
+      if (String(input).includes('/csrf-token')) {
+        return jsonResponse({ csrfToken: 'csrf-test-token' }, 200);
+      }
+      return jsonResponse(body, status);
+    });
+    global.fetch = fetchMock as unknown as typeof fetch;
+    return fetchMock;
+  };
+
+  /** Every stubbed call whose URL is the route under test (i.e. not the CSRF preflight). */
+  const routeCalls = (fetchMock: jest.Mock) =>
+    fetchMock.mock.calls.filter(([input]) => String(input).includes(ROUTE));
+
+  const client = () => {
+    const oxy = new OxyServices({ baseURL: 'http://api.test.invalid' });
+    // Bearer required: the server derives both the deviceId and the account
+    // from it, and this call (unlike the device-secret mint) does not skipAuth.
+    oxy.setTokens(ACCESS_TOKEN);
+    return oxy;
+  };
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it('unwraps the { data } envelope and returns the flat credential', async () => {
+    stubFetch(ROUTE_BODY, 200);
+
+    const result = await client().provisionBackgroundCredential();
+
+    // Would be `{ data: {...} }` if the envelope were not unwrapped, and would
+    // throw (contract validation failure) if `.data` were read twice.
+    expect(result).toEqual(CREDENTIAL);
+    expect(result?.secret).toBe('bg-secret-from-the-wire');
+  });
+
+  it('sends a POST to the route with NO body and a bearer', async () => {
+    const fetchMock = stubFetch(ROUTE_BODY, 200);
+
+    await client().provisionBackgroundCredential();
+
+    const calls = routeCalls(fetchMock);
+    expect(calls).toHaveLength(1);
+    const [, init] = calls[0] as unknown as [string, RequestInit];
+    expect(init.method).toBe('POST');
+    // No body at all — not `'undefined'`, not `'{}'`. The server derives the
+    // deviceId and the account from the bearer; anything sent here would be
+    // ignored at best and mass-assignment surface at worst.
+    expect(init.body ?? null).toBeNull();
+    expect(new Headers(init.headers).get('authorization')).toBe(`Bearer ${ACCESS_TOKEN}`);
+  });
+
+  it('returns null on the real 404 response, without retrying the route', async () => {
+    const fetchMock = stubFetch(NOT_FOUND_BODY, 404);
+
+    await expect(client().provisionBackgroundCredential()).resolves.toBeNull();
+
+    // 4xx is not retried (`retryAsync`'s default shouldRetry), so an absent
+    // endpoint costs exactly one request to the route — the degrade must not
+    // burn a backoff loop on every provision attempt.
+    expect(routeCalls(fetchMock)).toHaveLength(1);
+  });
+});

package/src/mixins/__tests__/chains.test.ts

@@ -0,0 +1,113 @@
+/**
+ * The chains client — what it puts on the wire.
+ *
+ * There is exactly one piece of real logic here and it is the read's query
+ * string: joining two lists, and including `since`/`limit` only when the caller
+ * gave them. Everything else is a pass-through, so these cases pin the part that
+ * can actually be wrong rather than restating the method bodies.
+ *
+ * `makeServiceRequest` is stubbed because it belongs to the auth mixin and has
+ * its own suites; what matters here is the method, path and payload it is handed.
+ */
+
+import { OxyServicesChainsMixin } from '../OxyServices.chains';
+
+type Call = { method: string; url: string; data?: unknown };
+
+/** A minimal host carrying the mixin, with the service transport recorded. */
+function client(): { calls: Call[]; api: any } {
+  const calls: Call[] = [];
+  class Base {
+    makeServiceRequest(method: string, url: string, data?: unknown) {
+      calls.push({ method, url, data });
+      return Promise.resolve({ records: [], nextCursor: null });
+    }
+  }
+  const Mixed = OxyServicesChainsMixin(Base as any);
+  return { calls, api: new (Mixed as any)() };
+}
+
+describe('appendChainRecord', () => {
+  it('POSTs the record to /chains/records untouched', async () => {
+    const { calls, api } = client();
+
+    await api.appendChainRecord({
+      oxyUserId: 'u1',
+      collection: 'app.mention.feed.post',
+      rkey: 'p1',
+      record: { text: 'hi' },
+    });
+
+    expect(calls).toEqual([
+      {
+        method: 'POST',
+        url: '/chains/records',
+        data: {
+          oxyUserId: 'u1',
+          collection: 'app.mention.feed.post',
+          rkey: 'p1',
+          record: { text: 'hi' },
+        },
+      },
+    ]);
+  });
+});
+
+describe('readChainRecords', () => {
+  it('joins authors and collections into one comma-separated query each', async () => {
+    const { calls, api } = client();
+
+    await api.readChainRecords({
+      oxyUserIds: ['u1', 'u2'],
+      collections: ['app.mention.feed.post', 'app.mention.feed.like'],
+    });
+
+    const url = new URL(`http://x${calls[0].url}`);
+    expect(calls[0].method).toBe('GET');
+    expect(url.pathname).toBe('/chains/records');
+    expect(url.searchParams.get('authors')).toBe('u1,u2');
+    expect(url.searchParams.get('collections')).toBe('app.mention.feed.post,app.mention.feed.like');
+  });
+
+  it('omits since and limit when the caller gave neither', async () => {
+    // A `since=` or `limit=` sent as an empty string is not the same request —
+    // the server validates both, so an always-present key would 400 a first page.
+    const { calls, api } = client();
+
+    await api.readChainRecords({ oxyUserIds: ['u1'], collections: ['app.mention.feed.post'] });
+
+    const url = new URL(`http://x${calls[0].url}`);
+    expect(url.searchParams.has('since')).toBe(false);
+    expect(url.searchParams.has('limit')).toBe(false);
+  });
+
+  it('sends since and limit when it did', async () => {
+    const { calls, api } = client();
+
+    await api.readChainRecords({
+      oxyUserIds: ['u1'],
+      collections: ['app.mention.feed.post'],
+      since: 'Y3Vyc29y',
+      limit: 25,
+    });
+
+    const url = new URL(`http://x${calls[0].url}`);
+    expect(url.searchParams.get('since')).toBe('Y3Vyc29y');
+    expect(url.searchParams.get('limit')).toBe('25');
+  });
+
+  it('escapes a cursor that is not URL-safe', async () => {
+    // Cursors are opaque to the caller, so this client must not assume the
+    // encoding the server happens to use today.
+    const { calls, api } = client();
+
+    await api.readChainRecords({
+      oxyUserIds: ['u1'],
+      collections: ['app.mention.feed.post'],
+      since: 'a+b/c=',
+    });
+
+    const url = new URL(`http://x${calls[0].url}`);
+    expect(url.searchParams.get('since')).toBe('a+b/c=');
+  });
+});