@oxy.so/core 1.0.0

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

@@ -0,0 +1,208 @@
+import { generateKeyPairSync, sign as signBytes, type KeyObject } from 'node:crypto';
+import { OxyServices } from '../../OxyServices';
+import { createOxyAuthMiddleware } from '../../server/auth';
+
+const b64url = (value: string | Uint8Array): string => Buffer.from(value).toString('base64url');
+
+function token(
+  privateKey: KeyObject,
+  keyId: string,
+  claims: Record<string, unknown> = {},
+): string {
+  const now = Math.floor(Date.now() / 1_000);
+  const header = { alg: 'EdDSA', typ: 'JWT', kid: keyId };
+  const payload = {
+    type: 'service',
+    appId: 'app-exact',
+    appName: 'Homiio',
+    credentialId: 'credential-exact',
+    ownerAccountId: 'account-exact',
+    environment: 'production',
+    scopes: ['inference:invoke'],
+    iss: 'oxy-auth',
+    aud: 'oxy-api',
+    iat: now,
+    exp: now + 3_600,
+    ...claims,
+  };
+  const signingInput = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(payload))}`;
+  return `${signingInput}.${b64url(signBytes(null, Buffer.from(signingInput), privateKey))}`;
+}
+
+function responseHarness() {
+  const response = {
+    statusCode: 0,
+    body: undefined as unknown,
+    status(code: number) {
+      this.statusCode = code;
+      return this;
+    },
+    json(body: unknown) {
+      this.body = body;
+      return this;
+    },
+  };
+  return response;
+}
+
+async function authenticate(oxy: OxyServices, bearer: string) {
+  const request = {
+    method: 'POST',
+    path: '/v1/chat/completions',
+    query: {},
+    headers: { authorization: `Bearer ${bearer}` },
+  };
+  const response = responseHarness();
+  const next = jest.fn();
+  await oxy.auth()(request as never, response as never, next as never);
+  return { request, response, next };
+}
+
+async function authenticateThroughExpress(oxy: OxyServices, bearer: string, delegatedUserId: string) {
+  const request = {
+    method: 'POST',
+    path: '/v1/chat/completions',
+    query: {},
+    headers: {
+      authorization: `Bearer ${bearer}`,
+      'x-oxy-user-id': delegatedUserId,
+    },
+  };
+  let settle!: () => void;
+  const settled = new Promise<void>((resolve) => { settle = resolve; });
+  const response = responseHarness();
+  const originalJson = response.json.bind(response);
+  response.json = (body: unknown) => {
+    const result = originalJson(body);
+    settle();
+    return result;
+  };
+  const next = jest.fn(() => settle());
+  createOxyAuthMiddleware(oxy)(request as never, response as never, next as never);
+  await settled;
+  return { request, response, next };
+}
+
+describe('Ed25519 Oxy service-token verification through JWKS', () => {
+  const primary = generateKeyPairSync('ed25519');
+  const secondary = generateKeyPairSync('ed25519');
+  const primaryJwk = {
+    ...primary.publicKey.export({ format: 'jwk' }),
+    use: 'sig',
+    alg: 'EdDSA',
+    kid: 'service-2026-09-a',
+  };
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('accepts a real service token without any shared signing secret', async () => {
+    const fetchSpy = jest.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(
+      JSON.stringify({ keys: [primaryJwk] }),
+      { status: 200, headers: { 'content-type': 'application/json' } },
+    ));
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.test' });
+    const result = await authenticate(oxy, token(primary.privateKey, primaryJwk.kid));
+
+    expect(fetchSpy).toHaveBeenCalledWith(
+      'https://api.oxy.test/.well-known/jwks.json',
+      expect.objectContaining({ method: 'GET', redirect: 'error' }),
+    );
+    expect(result.next).toHaveBeenCalledTimes(1);
+    expect(result.request).toMatchObject({
+      serviceApp: {
+        appId: 'app-exact',
+        credentialId: 'credential-exact',
+        ownerAccountId: 'account-exact',
+        scopes: ['inference:invoke'],
+      },
+    });
+  });
+
+  it('admits a real delegated service token through createOxyAuthMiddleware', async () => {
+    const fetchSpy = jest.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(
+      JSON.stringify({ keys: [primaryJwk] }),
+      { status: 200, headers: { 'content-type': 'application/json' } },
+    ));
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.test' });
+    jest.spyOn(oxy, 'verifyServiceActingAs').mockResolvedValue({
+      authorized: true,
+      scopes: ['inference:invoke'],
+    });
+
+    const result = await authenticateThroughExpress(
+      oxy,
+      token(primary.privateKey, primaryJwk.kid),
+      'user-exact',
+    );
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    expect(result.next).toHaveBeenCalledTimes(1);
+    expect(result.request).toMatchObject({
+      userId: 'user-exact',
+      serviceActingAs: { userId: 'user-exact', scopes: ['inference:invoke'] },
+      serviceApp: { appId: 'app-exact', scopes: ['inference:invoke'] },
+    });
+  });
+
+  it.each([' user-exact', 'user-exact '])(
+    'rejects delegated user id whitespace byte-for-byte: %j',
+    async (delegatedUserId) => {
+      jest.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(
+        JSON.stringify({ keys: [primaryJwk] }),
+        { status: 200 },
+      ));
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.test' });
+      const verifyGrant = jest.spyOn(oxy, 'verifyServiceActingAs');
+      const result = await authenticateThroughExpress(
+        oxy,
+        token(primary.privateKey, primaryJwk.kid),
+        delegatedUserId,
+      );
+
+      expect(result.next).not.toHaveBeenCalled();
+      expect(result.response.statusCode).toBe(401);
+      expect(verifyGrant).not.toHaveBeenCalled();
+    },
+  );
+
+  it('caches a key set and rate-limits unknown-kid refresh attempts', async () => {
+    const fetchSpy = jest.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(
+      JSON.stringify({ keys: [primaryJwk] }),
+      { status: 200 },
+    ));
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.test' });
+    expect((await authenticate(oxy, token(primary.privateKey, primaryJwk.kid))).next).toHaveBeenCalled();
+    const unknown = token(secondary.privateKey, 'unknown-key');
+    expect((await authenticate(oxy, unknown)).response.statusCode).toBe(401);
+    expect((await authenticate(oxy, unknown)).response.statusCode).toBe(401);
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([
+    ['wrong issuer', { iss: 'attacker' }],
+    ['wrong audience', { aud: 'other-api' }],
+    ['expired', { exp: 1 }],
+    ['future nbf', { nbf: Math.floor(Date.now() / 1_000) + 600 }],
+    ['malformed scopes', { scopes: ['inference:invoke', ' inference:invoke'] }],
+    ['missing app name', { appName: undefined }],
+    ['application id leading whitespace', { appId: ' app-exact' }],
+    ['application id trailing whitespace', { appId: 'app-exact ' }],
+    ['credential id leading whitespace', { credentialId: ' credential-exact' }],
+    ['credential id trailing whitespace', { credentialId: 'credential-exact ' }],
+    ['owner id leading whitespace', { ownerAccountId: ' account-exact' }],
+    ['owner id trailing whitespace', { ownerAccountId: 'account-exact ' }],
+  ])('fails closed on %s', async (_label, claims) => {
+    jest.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(
+      JSON.stringify({ keys: [primaryJwk] }),
+      { status: 200 },
+    ));
+    const result = await authenticate(
+      new OxyServices({ baseURL: 'https://api.oxy.test' }),
+      token(primary.privateKey, primaryJwk.kid, claims),
+    );
+    expect(result.next).not.toHaveBeenCalled();
+    expect(result.response.statusCode).toBe(401);
+  });
+});

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

@@ -0,0 +1,304 @@
+/**
+ * App Store Mixin Tests
+ *
+ * `makeRequest` is stubbed, so what these cover is the seam between this client
+ * and the API: the method, the URL, whether a value is URL-encoded, whether a
+ * read is cached, and — the part worth the most here — which envelope a
+ * response is unwrapped from.
+ *
+ * The API has two of those and they are not interchangeable. A single object
+ * comes back under `data`; a page comes back under `data` with its counts under
+ * `pagination`. Reading `meta` instead, which is the plausible mistake, yields
+ * `total: 0` on every page with no error anywhere and no type complaint — so it
+ * is asserted against a fixture that has a non-zero total rather than trusted.
+ *
+ * The publisher's listing routes answer with the object itself, no envelope at
+ * all, which is a third shape and is asserted separately for the same reason.
+ */
+
+import { OxyServices } from '../../OxyServices';
+import type {
+  PublisherListing,
+  StoreCategory,
+  StoreListingDetail,
+  StoreListingSummary,
+  StoreOwnReview,
+  StoreReview,
+  StoreScreenshot,
+} from '../OxyServices.store';
+
+const categoryFixture: StoreCategory = {
+  slug: 'productivity',
+  label: 'Productivity',
+  description: 'Get things done',
+};
+
+const summaryFixture: StoreListingSummary = {
+  slug: 'mention',
+  name: 'Mention',
+  tagline: 'The fediverse, at home',
+  icon: 'file-1',
+  category: categoryFixture,
+  rating: { average: 4.6, count: 31 },
+};
+
+const detailFixture: StoreListingDetail = {
+  ...summaryFixture,
+  description: '# Mention',
+  websiteUrl: 'https://mention.earth',
+  privacyPolicyUrl: null,
+  termsUrl: null,
+  supportUrl: null,
+  supportEmail: null,
+  publishedAt: '2026-08-01T00:00:00.000Z',
+  screenshots: [],
+  ratingBreakdown: { 4: 10, 5: 21 },
+};
+
+const reviewFixture: StoreReview = {
+  id: 'r1',
+  rating: 5,
+  title: null,
+  body: 'Good',
+  createdAt: '2026-08-01T00:00:00.000Z',
+  author: { id: 'u1', username: 'nate' },
+  reply: null,
+  authorUsesApp: true,
+};
+
+const ownReviewFixture: StoreOwnReview = {
+  id: 'r1',
+  rating: 5,
+  title: null,
+  body: 'Good',
+  status: 'visible',
+  createdAt: '2026-08-01T00:00:00.000Z',
+  updatedAt: '2026-08-01T00:00:00.000Z',
+};
+
+const listingFixture: PublisherListing = {
+  id: 'l1',
+  applicationId: 'app1',
+  slug: 'mention',
+  tagline: 'The fediverse, at home',
+  description: null,
+  category: categoryFixture,
+  supportUrl: null,
+  supportEmail: null,
+  status: 'draft',
+  publishedAt: null,
+  createdAt: '2026-08-01T00:00:00.000Z',
+  updatedAt: '2026-08-01T00:00:00.000Z',
+};
+
+const screenshotFixture: StoreScreenshot = {
+  id: 's1',
+  fileId: 'file-9',
+  platform: 'desktop',
+  caption: null,
+  position: 0,
+};
+
+describe('OxyServicesStoreMixin', () => {
+  let oxy: OxyServices;
+  let makeRequestSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    oxy.httpService.setTokens('test-token');
+    makeRequestSpy = jest.spyOn(oxy, 'makeRequest');
+  });
+
+  describe('the storefront', () => {
+    it('unwraps the shelves from `data` and caches the read', async () => {
+      makeRequestSpy.mockResolvedValue({ data: [categoryFixture] });
+
+      expect(await oxy.listStoreCategories()).toEqual([categoryFixture]);
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'GET',
+        '/store/categories',
+        undefined,
+        expect.objectContaining({ cache: true }),
+      );
+    });
+
+    it('reads a page count from `pagination`, not from `meta`', async () => {
+      makeRequestSpy.mockResolvedValue({
+        data: [summaryFixture],
+        pagination: { total: 42, limit: 24, offset: 0, hasMore: true },
+      });
+
+      const page = await oxy.listStoreApps();
+
+      // The fixture's total is deliberately not the length of `data`, and not
+      // zero: reading the wrong envelope key would give 0 and reading `length`
+      // would give 1, so only the right one gives 42.
+      expect(page).toEqual({ items: [summaryFixture], total: 42, hasMore: true });
+    });
+
+    it('sends only the options that were supplied', async () => {
+      makeRequestSpy.mockResolvedValue({ data: [], pagination: { total: 0 } });
+
+      await oxy.listStoreApps();
+      expect(makeRequestSpy.mock.calls[0][1]).toBe('/store/apps');
+
+      // An absent option must not travel as `undefined`, which is what a naive
+      // template string produces and what the server would then have to reject.
+      await oxy.listStoreApps({ category: 'productivity', limit: 12 });
+      expect(makeRequestSpy.mock.calls[1][1]).toBe('/store/apps?category=productivity&limit=12');
+    });
+
+    it('survives a response with neither key', async () => {
+      makeRequestSpy.mockResolvedValue({});
+      expect(await oxy.listStoreApps()).toEqual({ items: [], total: 0, hasMore: false });
+    });
+
+    it('URL-encodes a slug in the path', async () => {
+      makeRequestSpy.mockResolvedValue({ data: detailFixture });
+
+      expect(await oxy.getStoreApp('a b/c')).toEqual(detailFixture);
+      expect(makeRequestSpy.mock.calls[0][1]).toBe('/store/apps/a%20b%2Fc');
+    });
+
+    it('pages reviews, and passes the sort through', async () => {
+      makeRequestSpy.mockResolvedValue({
+        data: [reviewFixture],
+        pagination: { total: 3, hasMore: false },
+      });
+
+      const page = await oxy.listStoreReviews('mention', { sort: 'rating', limit: 5 });
+
+      expect(page.total).toBe(3);
+      expect(page.items[0].authorUsesApp).toBe(true);
+
+      // Parsed rather than compared as a string: the parameter ORDER follows
+      // whatever order the caller wrote their options object in, and pinning
+      // that would make the test fail on a harmless edit at the call site.
+      const [path, query] = String(makeRequestSpy.mock.calls[0][1]).split('?');
+      expect(path).toBe('/store/apps/mention/reviews');
+      expect(Object.fromEntries(new URLSearchParams(query))).toEqual({
+        sort: 'rating',
+        limit: '5',
+      });
+    });
+  });
+
+  describe('reviewing', () => {
+    it('answers null when the caller has not written one', async () => {
+      makeRequestSpy.mockResolvedValue({ data: null });
+      expect(await oxy.getMyStoreReview('mention')).toBeNull();
+    });
+
+    it('PUTs the review — one per person, so it sets rather than adds', async () => {
+      makeRequestSpy.mockResolvedValue({ data: ownReviewFixture });
+
+      expect(await oxy.writeStoreReview('mention', { rating: 5, body: 'Good' })).toEqual(
+        ownReviewFixture,
+      );
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'PUT',
+        '/store/apps/mention/review',
+        { rating: 5, body: 'Good' },
+        expect.objectContaining({ cache: false }),
+      );
+    });
+
+    it('withdraws the caller’s own review', async () => {
+      makeRequestSpy.mockResolvedValue(undefined);
+
+      await oxy.deleteMyStoreReview('mention');
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'DELETE',
+        '/store/apps/mention/review',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+    });
+
+    it('addresses a reply by review id, not by the listing’s slug', async () => {
+      makeRequestSpy.mockResolvedValue({ data: { id: 'p1', reviewId: 'r1', body: 'Fixed' } });
+
+      await oxy.replyToStoreReview('r1', 'Fixed');
+      expect(makeRequestSpy.mock.calls[0][1]).toBe('/store/reviews/r1/reply');
+    });
+  });
+
+  describe('the publisher’s listing', () => {
+    it('takes the object straight — these routes carry no envelope', async () => {
+      makeRequestSpy.mockResolvedValue(listingFixture);
+
+      expect(await oxy.getAppListing('app1')).toEqual(listingFixture);
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'GET',
+        '/applications/app1/listing',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+    });
+
+    it('PUTs the whole page, without a status field', async () => {
+      makeRequestSpy.mockResolvedValue(listingFixture);
+
+      await oxy.writeAppListing('app1', { slug: 'mention', tagline: 'Hello' });
+
+      const body = makeRequestSpy.mock.calls[0][2];
+      expect(body).toEqual({ slug: 'mention', tagline: 'Hello' });
+      expect(body).not.toHaveProperty('status');
+    });
+
+    it('submits and unpublishes through their own routes', async () => {
+      makeRequestSpy.mockResolvedValue(listingFixture);
+
+      await oxy.submitAppListing('app1');
+      expect(makeRequestSpy.mock.calls[0].slice(0, 2)).toEqual([
+        'POST',
+        '/applications/app1/listing/submit',
+      ]);
+
+      await oxy.unpublishAppListing('app1');
+      expect(makeRequestSpy.mock.calls[1].slice(0, 2)).toEqual([
+        'POST',
+        '/applications/app1/listing/unpublish',
+      ]);
+    });
+
+    it('URL-encodes the application id', async () => {
+      makeRequestSpy.mockResolvedValue(listingFixture);
+      await oxy.getAppListing('a b/c');
+      expect(makeRequestSpy.mock.calls[0][1]).toBe('/applications/a%20b%2Fc/listing');
+    });
+  });
+
+  describe('screenshots', () => {
+    it('attaches an uploaded file', async () => {
+      makeRequestSpy.mockResolvedValue(screenshotFixture);
+
+      await oxy.addAppListingScreenshot('app1', { fileId: 'file-9', platform: 'phone' });
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'POST',
+        '/applications/app1/listing/screenshots',
+        { fileId: 'file-9', platform: 'phone' },
+        expect.objectContaining({ cache: false }),
+      );
+    });
+
+    it('encodes both ids on an edit', async () => {
+      makeRequestSpy.mockResolvedValue(screenshotFixture);
+
+      await oxy.updateAppListingScreenshot('a b', 's/1', { caption: 'Home' });
+      expect(makeRequestSpy.mock.calls[0][1]).toBe('/applications/a%20b/listing/screenshots/s%2F1');
+    });
+
+    it('reorders by sending every id, on its own route', async () => {
+      makeRequestSpy.mockResolvedValue([screenshotFixture]);
+
+      await oxy.reorderAppListingScreenshots('app1', ['s2', 's1']);
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'PUT',
+        '/applications/app1/listing/screenshots/order',
+        { screenshotIds: ['s2', 's1'] },
+        expect.objectContaining({ cache: false }),
+      );
+    });
+  });
+});

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

@@ -0,0 +1,156 @@
+/**
+ * Topics mixin envelope-unwrapping tests.
+ *
+ * oxy-api returns ENVELOPES for the list/collection topic routes
+ * (`{ topics, total, limit, offset }`, `{ categories }`, `{ topics }`,
+ * `{ topics: <name-keyed map> }`), while the SDK's `unwrapResponse` only unwraps
+ * the `{ data }` success shape. These tests pin the mixin's own unwrapping so the
+ * public methods genuinely return `TopicData[]` / the pagination envelope — not a
+ * raw wrapper that a caller would `.map` over and crash on.
+ *
+ * They drive the REAL `makeRequest` path by mocking `globalThis.fetch`, so the
+ * `unwrapResponse` pass-through (no `data` key) is exercised end to end.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+/** A raw JSON `Response` — the body is exactly what the topic routes return. */
+function rawResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+/**
+ * A non-verified JWT whose payload decodes to the given claims. Puts the SDK in
+ * an authenticated state so the `POST /topics/resolve` carries a bearer header
+ * and skips the CSRF-token pre-fetch (which would otherwise consume a mock).
+ */
+function makeJwt(payload: Record<string, unknown>): string {
+  const b64url = (obj: Record<string, unknown>): string =>
+    Buffer.from(JSON.stringify(obj)).toString('base64url');
+  const fullPayload = { exp: Math.floor(Date.now() / 1000) + 3600, ...payload };
+  return `${b64url({ alg: 'none', typ: 'JWT' })}.${b64url(fullPayload)}.sig`;
+}
+
+const topic = (id: string, name: string, extra: Record<string, unknown> = {}) => ({
+  _id: id,
+  name,
+  slug: name,
+  displayName: name,
+  description: '',
+  type: 'topic',
+  source: 'ai',
+  aliases: [],
+  isActive: true,
+  createdAt: '2026-01-01T00:00:00.000Z',
+  updatedAt: '2026-01-01T00:00:00.000Z',
+  ...extra,
+});
+
+describe('topics mixin envelope unwrapping', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+  let oxy: OxyServices;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    oxy = new OxyServices({ baseURL: 'http://test.invalid', enableRetry: false });
+    // Authenticate so the resolve POST skips the CSRF pre-fetch. Harmless for GETs.
+    oxy.httpService.setTokens(makeJwt({ userId: 'me' }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  describe('getTopicCategories', () => {
+    it('unwraps { categories } into a TopicData[]', async () => {
+      fetchMock.mockResolvedValueOnce(
+        rawResponse({ categories: [topic('c1', 'tech', { type: 'category' }), topic('c2', 'sports', { type: 'category' })] }),
+      );
+      const result = await oxy.getTopicCategories();
+      expect(Array.isArray(result)).toBe(true);
+      expect(result.map((t) => t._id)).toEqual(['c1', 'c2']);
+    });
+
+    it('returns [] when the envelope omits categories', async () => {
+      fetchMock.mockResolvedValueOnce(rawResponse({}));
+      await expect(oxy.getTopicCategories()).resolves.toEqual([]);
+    });
+  });
+
+  describe('searchTopics', () => {
+    it('unwraps { topics } into a TopicData[]', async () => {
+      fetchMock.mockResolvedValueOnce(rawResponse({ topics: [topic('t1', 'react'), topic('t2', 'reactivity')] }));
+      const result = await oxy.searchTopics('react');
+      expect(result.map((t) => t.name)).toEqual(['react', 'reactivity']);
+    });
+
+    it('returns [] when the envelope omits topics', async () => {
+      fetchMock.mockResolvedValueOnce(rawResponse({}));
+      await expect(oxy.searchTopics('nothing')).resolves.toEqual([]);
+    });
+  });
+
+  describe('listTopics', () => {
+    it('returns the full pagination envelope', async () => {
+      fetchMock.mockResolvedValueOnce(
+        rawResponse({ topics: [topic('t1', 'a'), topic('t2', 'b')], total: 42, limit: 2, offset: 10 }),
+      );
+      const result = await oxy.listTopics({ limit: 2, offset: 10 });
+      expect(result.topics.map((t) => t._id)).toEqual(['t1', 't2']);
+      expect(result.total).toBe(42);
+      expect(result.limit).toBe(2);
+      expect(result.offset).toBe(10);
+    });
+
+    it('falls back to the requested limit/offset and topics.length when the server omits them', async () => {
+      fetchMock.mockResolvedValueOnce(rawResponse({ topics: [topic('t1', 'a')] }));
+      const result = await oxy.listTopics({ limit: 5, offset: 3 });
+      expect(result.topics).toHaveLength(1);
+      expect(result.total).toBe(1);
+      expect(result.limit).toBe(5);
+      expect(result.offset).toBe(3);
+    });
+
+    it('returns an empty envelope when the server returns nothing useful', async () => {
+      fetchMock.mockResolvedValueOnce(rawResponse({}));
+      const result = await oxy.listTopics();
+      expect(result).toEqual({ topics: [], total: 0, limit: 0, offset: 0 });
+    });
+  });
+
+  describe('resolveTopicNames', () => {
+    it('flattens the name-keyed { topics } map into a TopicData[]', async () => {
+      // POST /topics/resolve returns a Record keyed by lowercased name, NOT an array.
+      fetchMock.mockResolvedValueOnce(
+        rawResponse({ topics: { react: topic('t1', 'react'), vue: topic('t2', 'vue') } }),
+      );
+      const result = await oxy.resolveTopicNames([
+        { name: 'react', type: 'topic' },
+        { name: 'vue', type: 'topic' },
+      ]);
+      expect(Array.isArray(result)).toBe(true);
+      expect(result.map((t) => t.name).sort()).toEqual(['react', 'vue']);
+    });
+
+    it('returns [] when the map is empty or missing', async () => {
+      fetchMock.mockResolvedValueOnce(rawResponse({ topics: {} }));
+      await expect(oxy.resolveTopicNames([])).resolves.toEqual([]);
+    });
+  });
+
+  describe('getTopicBySlug (single, no envelope)', () => {
+    it('returns the raw TopicData unchanged', async () => {
+      fetchMock.mockResolvedValueOnce(rawResponse(topic('t1', 'react')));
+      const result = await oxy.getTopicBySlug('react');
+      expect(result._id).toBe('t1');
+      expect(result.name).toBe('react');
+    });
+  });
+});