@oxy.so/core 1.0.0

package/src/__tests__/linkedClient.test.ts

@@ -0,0 +1,370 @@
+import { OxyServices } from '../OxyServices';
+
+interface FetchCall {
+  url: string;
+  init: RequestInit | undefined;
+}
+
+function createServices(): OxyServices {
+  return new OxyServices({ baseURL: 'https://api.oxy.so' });
+}
+
+function createJwt(payload: Record<string, unknown>): string {
+  const encode = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString('base64url');
+  return `${encode({ alg: 'HS256', typ: 'JWT' })}.${encode(payload)}.signature`;
+}
+
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+function readHeaders(init: RequestInit | undefined): Record<string, string> {
+  const headers = init?.headers;
+  if (!headers) {
+    return {};
+  }
+  if (headers instanceof Headers) {
+    return Object.fromEntries(headers.entries());
+  }
+  if (Array.isArray(headers)) {
+    return Object.fromEntries(headers);
+  }
+  return headers as Record<string, string>;
+}
+
+describe('OxyServices.createLinkedClient', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+  });
+
+  it('mirrors token changes from the session owner', () => {
+    const oxy = createServices();
+    const linked = oxy.createLinkedClient({ baseURL: 'https://api.syra.fm' });
+
+    expect(linked.client.getAccessToken()).toBeNull();
+
+    oxy.setTokens('access_1');
+    expect(linked.client.getAccessToken()).toBe('access_1');
+
+    oxy.setTokens('access_2');
+    expect(linked.client.getAccessToken()).toBe('access_2');
+
+    oxy.clearTokens();
+    expect(linked.client.getAccessToken()).toBeNull();
+
+    linked.dispose();
+  });
+
+  it('copies the current token when created after sign-in', () => {
+    const oxy = createServices();
+    oxy.setTokens('existing_access');
+
+    const linked = oxy.createLinkedClient({ baseURL: 'https://api.syra.fm' });
+
+    expect(linked.client.getAccessToken()).toBe('existing_access');
+
+    linked.dispose();
+  });
+
+  it('delegates token refresh to the session owner', async () => {
+    const oxy = createServices();
+    const linked = oxy.createLinkedClient({ baseURL: 'https://api.syra.fm' });
+
+    oxy.getClient().setAuthRefreshHandler(async () => 'refreshed_access');
+
+    const refreshed = await linked.client.refreshAccessToken('preflight');
+
+    expect(refreshed).toBe('refreshed_access');
+    expect(oxy.getAccessToken()).toBe('refreshed_access');
+    expect(linked.client.getAccessToken()).toBe('refreshed_access');
+
+    linked.dispose();
+  });
+
+  it('returns an unread authenticated streaming response', async () => {
+    const calls: FetchCall[] = [];
+    globalThis.fetch = async (input, init) => {
+      calls.push({ url: String(input), init });
+      return new Response('data: {"delta":"hello"}\n\n', {
+        status: 200,
+        headers: { 'content-type': 'text/event-stream' },
+      });
+    };
+
+    const oxy = createServices();
+    const accessToken = createJwt({
+      userId: 'user_1',
+      exp: Math.floor(Date.now() / 1000) + 3600,
+    });
+    oxy.setTokens(accessToken);
+    const linked = oxy.createLinkedClient({ baseURL: 'https://api.alia.onl/' });
+
+    const response = await linked.client.requestAuthenticatedResponse({
+      method: 'POST',
+      url: '/alia/chat',
+      body: JSON.stringify({ message: 'hello' }),
+      headers: {
+        Authorization: 'Bearer caller_supplied_token',
+        'Content-Type': 'application/json',
+      },
+    });
+
+    expect(response.bodyUsed).toBe(false);
+    expect(await response.text()).toBe('data: {"delta":"hello"}\n\n');
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.url).toBe('https://api.alia.onl/alia/chat');
+    expect(readHeaders(calls[0]?.init).authorization).toBe(`Bearer ${accessToken}`);
+
+    linked.dispose();
+  });
+
+  it('refreshes once after a streaming response 401 and keeps the final body unread', async () => {
+    const calls: FetchCall[] = [];
+    globalThis.fetch = async (input, init) => {
+      calls.push({ url: String(input), init });
+      if (calls.length === 1) {
+        return new Response('expired', { status: 401 });
+      }
+      return new Response('data: done\n\n', {
+        status: 200,
+        headers: { 'content-type': 'text/event-stream' },
+      });
+    };
+
+    const oxy = createServices();
+    const oldToken = createJwt({
+      userId: 'user_1',
+      exp: Math.floor(Date.now() / 1000) + 3600,
+    });
+    const refreshedToken = createJwt({
+      userId: 'user_1',
+      exp: Math.floor(Date.now() / 1000) + 7200,
+    });
+    oxy.setTokens(oldToken);
+    oxy.getClient().setAuthRefreshHandler(async () => refreshedToken);
+    const linked = oxy.createLinkedClient({ baseURL: 'https://api.alia.onl' });
+
+    const response = await linked.client.requestAuthenticatedResponse({
+      method: 'POST',
+      url: '/alia/chat',
+      body: '{}',
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+    expect(calls).toHaveLength(2);
+    expect(readHeaders(calls[0]?.init).authorization).toBe(`Bearer ${oldToken}`);
+    expect(readHeaders(calls[1]?.init).authorization).toBe(`Bearer ${refreshedToken}`);
+    expect(oxy.getAccessToken()).toBe(refreshedToken);
+    expect(linked.client.getAccessToken()).toBe(refreshedToken);
+    expect(response.bodyUsed).toBe(false);
+    expect(await response.text()).toBe('data: done\n\n');
+
+    linked.dispose();
+  });
+
+  it('rejects an authenticated streaming request before fetch without a session', async () => {
+    const fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    const oxy = createServices();
+    const linked = oxy.createLinkedClient({ baseURL: 'https://api.alia.onl' });
+
+    await expect(linked.client.requestAuthenticatedResponse({
+      method: 'POST',
+      url: '/alia/chat',
+      body: '{}',
+    })).rejects.toMatchObject({
+      code: 'AUTH_REQUIRED',
+      status: 401,
+    });
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    linked.dispose();
+  });
+
+  it('keeps the session owner intact when a linked response 401 cannot refresh', async () => {
+    const oxy = createServices();
+    oxy.setTokens('stale_access');
+    const linked = oxy.createLinkedClient({ baseURL: 'https://api.syra.fm' });
+
+    const refreshed = await linked.client.refreshAccessToken('response-401');
+
+    expect(refreshed).toBeNull();
+    expect(oxy.getAccessToken()).toBe('stale_access');
+    expect(linked.client.getAccessToken()).toBe('stale_access');
+
+    linked.dispose();
+  });
+
+  it('resynchronizes from the session owner after a linked app 401 clears the local token', async () => {
+    const calls: FetchCall[] = [];
+    let queueWriteAttempts = 0;
+    globalThis.fetch = async (input, init) => {
+      const url = String(input);
+      calls.push({ url, init });
+
+      if (url.endsWith('/csrf-token')) {
+        return new Response(JSON.stringify({ csrfToken: 'csrf_1' }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        });
+      }
+
+      if (url.endsWith('/api/queue/current')) {
+        queueWriteAttempts += 1;
+        if (queueWriteAttempts === 1) {
+          return new Response(JSON.stringify({ error: 'MISSING_TOKEN' }), {
+            status: 401,
+            statusText: 'Unauthorized',
+            headers: { 'content-type': 'application/json' },
+          });
+        }
+      }
+
+      return jsonResponse({ ok: true });
+    };
+
+    const oxy = createServices();
+    const accessToken = createJwt({
+      userId: 'user_1',
+      exp: Math.floor(Date.now() / 1000) + 3600,
+    });
+    oxy.setTokens(accessToken);
+    oxy.getClient().setAuthRefreshHandler(async () => null);
+    const linked = oxy.createLinkedClient({ baseURL: 'https://api.syra.fm' });
+
+    await expect(linked.client.put('/api/queue/current', { trackId: 'track_1' }, { retry: false })).rejects.toMatchObject({
+      message: 'MISSING_TOKEN',
+      status: 401,
+    });
+
+    expect(oxy.getAccessToken()).toBe(accessToken);
+    expect(linked.client.getAccessToken()).toBeNull();
+
+    await linked.client.put('/api/queue/current', { trackId: 'track_2' });
+
+    expect(calls.map((call) => call.url)).toEqual([
+      'https://api.syra.fm/api/queue/current',
+      'https://api.syra.fm/api/queue/current',
+    ]);
+    expect(linked.client.getAccessToken()).toBe(accessToken);
+
+    const firstHeaders = readHeaders(calls[0]?.init);
+    expect(firstHeaders.Authorization).toBe(`Bearer ${accessToken}`);
+    expect(firstHeaders['X-CSRF-Token']).toBeUndefined();
+
+    const secondHeaders = readHeaders(calls[1]?.init);
+    expect(secondHeaders.Authorization).toBe(`Bearer ${accessToken}`);
+    expect(secondHeaders['X-CSRF-Token']).toBeUndefined();
+
+    linked.dispose();
+  });
+
+  it('keeps the session owner intact when linked preflight refresh cannot refresh', async () => {
+    const oxy = createServices();
+    oxy.setTokens('existing_access');
+    const linked = oxy.createLinkedClient({ baseURL: 'https://api.syra.fm' });
+
+    const refreshed = await linked.client.refreshAccessToken('preflight');
+
+    expect(refreshed).toBeNull();
+    expect(oxy.getAccessToken()).toBe('existing_access');
+    expect(linked.client.getAccessToken()).toBe('existing_access');
+
+    linked.dispose();
+  });
+
+  it('stops mirroring after dispose', () => {
+    const oxy = createServices();
+    const linked = oxy.createLinkedClient({ baseURL: 'https://api.syra.fm' });
+
+    oxy.setTokens('before_dispose');
+    expect(linked.client.getAccessToken()).toBe('before_dispose');
+
+    linked.dispose();
+    oxy.setTokens('after_dispose');
+
+    expect(linked.client.getAccessToken()).toBeNull();
+  });
+
+  it('joins linked base URLs with relative paths that omit the leading slash', async () => {
+    const fetchMock = jest.fn(async () => jsonResponse({ ok: true }));
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+
+    const oxy = createServices();
+    const linked = oxy.createLinkedClient({ baseURL: 'https://api.mention.earth' });
+
+    await linked.client.get('profile/settings/me');
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(String(fetchMock.mock.calls[0]?.[0])).toBe('https://api.mention.earth/profile/settings/me');
+
+    linked.dispose();
+  });
+
+  /**
+   * GET response caching is OFF by default for linked clients: the SDK cannot
+   * invalidate the consumer backend's resources, so a cached GET there would
+   * serve stale data after the app mutates its own data. The consumer's own
+   * layer (React Query / stores) owns caching. An explicit `enableCache: true`
+   * opts back in.
+   */
+  describe('linked client GET cache default', () => {
+    it('does NOT cache GETs by default — every read hits the network', async () => {
+      const fetchMock = jest.fn();
+      globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+
+      const oxy = createServices();
+      const accessToken = createJwt({
+        userId: 'user_1',
+        exp: Math.floor(Date.now() / 1000) + 3600,
+      });
+      oxy.setTokens(accessToken);
+      const linked = oxy.createLinkedClient({ baseURL: 'https://api.mention.earth' });
+
+      // Two identical GETs with cache:true — both MUST hit the network because
+      // the linked client's cache is disabled by default.
+      fetchMock.mockResolvedValueOnce(jsonResponse({ v: 1 }));
+      const first = await linked.client.get<{ v: number }>('/feed/mtn', { cache: true });
+      fetchMock.mockResolvedValueOnce(jsonResponse({ v: 2 }));
+      const second = await linked.client.get<{ v: number }>('/feed/mtn', { cache: true });
+
+      expect(first.v).toBe(1);
+      expect(second.v).toBe(2);
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+
+      linked.dispose();
+    });
+
+    it('caches GETs when the caller explicitly opts in with enableCache: true', async () => {
+      const fetchMock = jest.fn();
+      globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+
+      const oxy = createServices();
+      const accessToken = createJwt({
+        userId: 'user_1',
+        exp: Math.floor(Date.now() / 1000) + 3600,
+      });
+      oxy.setTokens(accessToken);
+      const linked = oxy.createLinkedClient({
+        baseURL: 'https://api.mention.earth',
+        enableCache: true,
+      });
+
+      // Second identical GET is a warm cache hit — only one network call.
+      fetchMock.mockResolvedValueOnce(jsonResponse({ v: 1 }));
+      const first = await linked.client.get<{ v: number }>('/feed/mtn', { cache: true });
+      const second = await linked.client.get<{ v: number }>('/feed/mtn', { cache: true });
+
+      expect(first).toEqual(second);
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+
+      linked.dispose();
+    });
+  });
+});

package/src/__tests__/parseHttpErrorBody.test.ts

@@ -0,0 +1,116 @@
+import { isHttpRequestError, parseHttpErrorBody } from '../utils/errorUtils';
+
+/**
+ * `parseHttpErrorBody` is the ONE place the SDK decides what a failed request's
+ * message, code and details are, across every error envelope the Oxy ecosystem
+ * emits. The bug it exists to prevent is silent: a nested
+ * `{ error: { code, message } }` assigned straight to `new Error(...)` yields
+ * the literal string `"[object Object]"`, which reads as a rendering bug in
+ * whichever app surfaces it, arbitrarily far from here.
+ *
+ * Each case below pins one envelope AND the discrimination it depends on — in
+ * particular, whether the top-level `error` string is a machine CODE or human
+ * prose is decided solely by whether a sibling human field is present, so both
+ * sides of that fork need a fixture or the rule is untested.
+ */
+describe('parseHttpErrorBody', () => {
+    it('reads the nested { error: { code, message, details } } envelope', () => {
+        expect(
+            parseHttpErrorBody({
+                error: { code: 'case_conflict', message: 'A case already exists', details: { caseId: 'c_1' } },
+            }),
+        ).toEqual({
+            message: 'A case already exists',
+            code: 'case_conflict',
+            details: { caseId: 'c_1' },
+        });
+    });
+
+    it("reads oxy-api's { error: '<CODE>', message } shape — error IS the code", () => {
+        expect(parseHttpErrorBody({ error: 'VALIDATION_ERROR', message: 'username is taken' })).toEqual({
+            message: 'username is taken',
+            code: 'VALIDATION_ERROR',
+            details: undefined,
+        });
+    });
+
+    it("reads RFC 6749 { error: '<CODE>', error_description } from the OAuth endpoints", () => {
+        // The OAuth token/userinfo endpoints are the one part of the API that
+        // does not use the `{ error, message }` envelope. Without this arm the
+        // human text is dropped and the raw code is shown to the user.
+        expect(
+            parseHttpErrorBody({ error: 'invalid_grant', error_description: 'Authorization code expired' }),
+        ).toEqual({
+            message: 'Authorization code expired',
+            code: 'invalid_grant',
+            details: undefined,
+        });
+    });
+
+    it("treats a LONE { error: '<text>' } as the message, never as a code", () => {
+        // The discriminator is the ABSENCE of a sibling human field. Promoting a
+        // bare string to `code` would put prose where callers switch on codes,
+        // so this case and the two above have to disagree.
+        expect(parseHttpErrorBody({ error: 'Something went wrong' })).toEqual({
+            message: 'Something went wrong',
+            code: undefined,
+            details: undefined,
+        });
+    });
+
+    it('reads the flat { message, code } shape (CSRF rejections)', () => {
+        expect(parseHttpErrorBody({ message: 'Invalid CSRF token', code: 'CSRF_TOKEN_INVALID' })).toEqual({
+            message: 'Invalid CSRF token',
+            code: 'CSRF_TOKEN_INVALID',
+            details: undefined,
+        });
+    });
+
+    it('ignores whitespace-only strings rather than reporting them as a message', () => {
+        // A blank message is worse than none: it replaces the status fallback
+        // with an empty error surface the user cannot act on.
+        expect(parseHttpErrorBody({ message: '   ', error: '' })).toEqual({
+            message: undefined,
+            code: undefined,
+            details: undefined,
+        });
+    });
+
+    it('ignores a non-object `details` instead of passing it through', () => {
+        expect(parseHttpErrorBody({ message: 'nope', details: 'not-an-object' }).details).toBeUndefined();
+        expect(parseHttpErrorBody({ message: 'nope', details: ['a'] }).details).toBeUndefined();
+    });
+
+    it.each([null, undefined, [], 'a string', 42, true])('returns {} for the non-object body %p', (body) => {
+        expect(parseHttpErrorBody(body)).toEqual({});
+    });
+
+    it('returns {} for an object carrying none of the known fields', () => {
+        expect(parseHttpErrorBody({ unrelated: 'field' })).toEqual({
+            message: undefined,
+            code: undefined,
+            details: undefined,
+        });
+    });
+});
+
+describe('isHttpRequestError', () => {
+    it('accepts an Error carrying a numeric status', () => {
+        const error = Object.assign(new Error('boom'), { status: 409 });
+        expect(isHttpRequestError(error)).toBe(true);
+    });
+
+    it('rejects a plain ApiError object — those are objects, not Errors', () => {
+        // The distinction is load-bearing: an ApiError has to go through
+        // `handleHttpError` first, and a truthy answer here would let a caller
+        // read `.stack`/`.name` off something that has neither.
+        expect(isHttpRequestError({ message: 'boom', status: 409, code: 'CONFLICT' })).toBe(false);
+    });
+
+    it('rejects an Error whose status is a non-number', () => {
+        // `'409'` is the shape a hand-built error most plausibly carries, and
+        // the narrowing promises callers a number they can compare.
+        expect(isHttpRequestError(Object.assign(new Error('boom'), { status: '409' }))).toBe(false);
+        expect(isHttpRequestError(new Error('boom'))).toBe(false);
+    });
+});

package/src/__tests__/serverValueImportsDeclared.test.ts

@@ -0,0 +1,120 @@
+/**
+ * Every package `@oxy.so/core/server` VALUE-imports must be a real dependency.
+ *
+ * ## The failure this exists for, which happened
+ *
+ * `helmet` was declared an OPTIONAL peer dependency. `src/server/securityHeaders.ts`
+ * imports it at the top level, and the server barrel re-exports that module — so
+ * importing *anything* from `@oxy.so/core/server` loads helmet, and a consumer
+ * that believed the "optional" marking did not install it.
+ *
+ * The result was a backend that could not boot: `Cannot find package 'helmet'`.
+ * `tsc` passed clean the whole time, because types resolve from a peer whether
+ * or not the runtime can find the module. It was found by a test suite failing
+ * to resolve 29 of 63 files while every typecheck was green — which is a very
+ * expensive way to learn it.
+ *
+ * ## Why value imports and not all imports
+ *
+ * `express` is imported by eight files here and every one of them is
+ * `import type`. Those vanish at build time, so an optional peer is a truthful
+ * declaration for it: a consumer of the client entry never needs express
+ * installed. The distinction this test draws is exactly the one that decides
+ * whether a missing package is a warning or a crash.
+ */
+
+import { readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+
+const packageRoot = path.resolve(__dirname, '../..');
+const serverDir = path.join(packageRoot, 'src', 'server');
+
+const manifest = JSON.parse(readFileSync(path.join(packageRoot, 'package.json'), 'utf8')) as {
+  dependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  peerDependenciesMeta?: Record<string, { optional?: boolean }>;
+};
+
+const dependencies = new Set(Object.keys(manifest.dependencies ?? {}));
+const requiredPeers = new Set(
+  Object.keys(manifest.peerDependencies ?? {}).filter(
+    (name) => manifest.peerDependenciesMeta?.[name]?.optional !== true
+  )
+);
+
+/**
+ * Bare specifiers imported for their VALUE — `import x from 'y'`,
+ * `import { a } from 'y'`, `import 'y'` — but never `import type`.
+ */
+function valueImports(source: string): string[] {
+  const found: string[] = [];
+  // Strip comments first: prose in a doc comment can otherwise read as code.
+  const code = source.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/(^|[^:])\/\/[^\n]*/g, '$1 ');
+  for (const match of code.matchAll(/import\s+(?!type\b)([^;']*?)from\s*'([^']+)'/g)) {
+    // `import { type A, type B } from 'x'` is still type-only in effect.
+    const clause = match[1];
+    const specifier = match[2];
+    if (specifier.startsWith('.') || specifier.startsWith('node:')) continue;
+    const names = clause.replace(/[{}]/g, '').split(',').map((n) => n.trim()).filter(Boolean);
+    if (names.length > 0 && names.every((n) => n.startsWith('type '))) continue;
+    found.push(specifier);
+  }
+  for (const match of code.matchAll(/import\s*'([^']+)'/g)) {
+    if (!match[1].startsWith('.') && !match[1].startsWith('node:')) found.push(match[1]);
+  }
+  return found;
+}
+
+function packageNameOf(specifier: string): string {
+  const parts = specifier.split('/');
+  return specifier.startsWith('@') ? `${parts[0]}/${parts[1]}` : parts[0];
+}
+
+const files = readdirSync(serverDir).filter((f) => f.endsWith('.ts') && !f.endsWith('.d.ts'));
+
+describe('@oxy.so/core/server value imports are installable', () => {
+  it('reads a non-trivial number of server modules', () => {
+    // Vacuity floor: a traversal that found nothing would satisfy every
+    // assertion below by having nothing to check.
+    expect(files.length).toBeGreaterThan(5);
+  });
+
+  it('declares every value-imported package as a dependency or a REQUIRED peer', () => {
+    const undeclared: string[] = [];
+    for (const file of files) {
+      const source = readFileSync(path.join(serverDir, file), 'utf8');
+      for (const specifier of valueImports(source)) {
+        const name = packageNameOf(specifier);
+        if (dependencies.has(name) || requiredPeers.has(name)) continue;
+        undeclared.push(`${file} → ${name}`);
+      }
+    }
+
+    // An OPTIONAL peer is not enough here and that is the whole point: the
+    // module is loaded the moment anything is imported from the server barrel,
+    // so "optional" describes a package the consumer cannot actually omit.
+    expect(undeclared.sort()).toEqual([]);
+  });
+
+  it('keeps helmet installable rather than optional', () => {
+    // The specific regression, asserted by name so a failure says what broke
+    // rather than only showing it inside a list.
+    expect(dependencies.has('helmet')).toBe(true);
+    expect(manifest.peerDependenciesMeta?.helmet?.optional).toBeUndefined();
+  });
+
+  it('keeps express-rate-limit installable rather than a peer', () => {
+    // Same class as helmet: `rateLimit.ts` value-imports it and the server
+    // barrel re-exports that module, so a missing install crashes at boot.
+    expect(dependencies.has('express-rate-limit')).toBe(true);
+    expect(manifest.peerDependencies?.['express-rate-limit']).toBeUndefined();
+  });
+
+  it('leaves express as an optional peer, because it is type-only here', () => {
+    // The counter-example that stops this test from being read as "declare
+    // everything": type imports vanish at build time, so an optional peer is a
+    // truthful declaration for express and making it required would nag every
+    // React Native consumer about a package they never load.
+    expect(manifest.peerDependenciesMeta?.express?.optional).toBe(true);
+  });
+});