@oxy.so/core 1.0.0

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

@@ -0,0 +1,123 @@
+/**
+ * Connected-apps (OAuth grants) SDK tests.
+ *
+ * `listConnectedApps()` reads the user's authorized applications from
+ * `GET /auth/grants` and caches the response (identity-scoped). `revokeAppGrant`
+ * deletes a grant via `DELETE /auth/grants/:applicationId` and MUST invalidate
+ * the cached `GET:/auth/grants` so a re-read observes the removal instead of the
+ * STALE pre-revoke list (mirrors the privacy/follow invalidation contract).
+ */
+
+import { OxyServices } from '../../OxyServices';
+import type { ConnectedApp } from '../OxyServices.connectedApps';
+
+/** Build a non-verified JWT whose payload decodes to the given claims. */
+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`;
+}
+
+/** A JSON `Response` mimicking the API's `{ data: ... }` success envelope. */
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+const APP_A: ConnectedApp = {
+  applicationId: 'app-a',
+  name: 'App A',
+  logoUrl: 'https://cdn.example/a.png',
+  scopes: ['profile', 'email'],
+  firstGrantedAt: '2026-01-01T00:00:00.000Z',
+  lastUsedAt: '2026-06-01T00:00:00.000Z',
+};
+
+const APP_B: ConnectedApp = {
+  applicationId: 'app-b',
+  name: 'App B',
+  scopes: ['profile'],
+  firstGrantedAt: '2026-02-01T00:00:00.000Z',
+  lastUsedAt: '2026-06-02T00:00:00.000Z',
+};
+
+describe('connected apps (OAuth grants)', () => {
+  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' });
+    oxy.httpService.setTokens(makeJwt({ userId: 'me' }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  it('lists connected apps, unwrapping the { data } envelope', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse([APP_A, APP_B]));
+    const apps = await oxy.listConnectedApps();
+    expect(apps).toEqual([APP_A, APP_B]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(String(url)).toBe('http://test.invalid/auth/grants');
+    expect(init?.method).toBe('GET');
+  });
+
+  it('caches the list within the TTL (second read is a cache hit)', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse([APP_A]));
+    expect(await oxy.listConnectedApps()).toEqual([APP_A]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // Second read within the TTL must not hit the network.
+    expect(await oxy.listConnectedApps()).toEqual([APP_A]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('revokes a grant via DELETE /auth/grants/:applicationId', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ revoked: true }));
+    await expect(oxy.revokeAppGrant('app-a')).resolves.toBeUndefined();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(String(url)).toBe('http://test.invalid/auth/grants/app-a');
+    expect(init?.method).toBe('DELETE');
+  });
+
+  it('busts the cached list after revokeAppGrant', async () => {
+    // 1) Warm the cache.
+    fetchMock.mockResolvedValueOnce(jsonResponse([APP_A, APP_B]));
+    expect(await oxy.listConnectedApps()).toEqual([APP_A, APP_B]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // A second read is a cache hit (no extra network call).
+    await oxy.listConnectedApps();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // 2) Revoke — must invalidate the cached list.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ revoked: true }));
+    await oxy.revokeAppGrant('app-a');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    // 3) Re-read MUST re-fetch and observe the revoked app gone.
+    fetchMock.mockResolvedValueOnce(jsonResponse([APP_B]));
+    const after = await oxy.listConnectedApps();
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(after).toEqual([APP_B]);
+  });
+
+  it('invalidates the exact GET:/auth/grants key on revoke', async () => {
+    const clearSpy = jest.spyOn(oxy, 'clearCacheEntry');
+    fetchMock.mockResolvedValueOnce(jsonResponse({ revoked: true }));
+    await oxy.revokeAppGrant('app-a');
+    expect(clearSpy).toHaveBeenCalledWith('GET:/auth/grants');
+    clearSpy.mockRestore();
+  });
+});

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

@@ -0,0 +1,113 @@
+/**
+ * `mintFromDeviceSecret` — the pinned (identity-bound) mint.
+ *
+ * The pinned form adds `accountId` to the zero-cookie mint body so an identity
+ * vault gets ITS account's token without the device's `activeAccountId` being
+ * touched. Its one new failure mode — `401 account_not_on_device` — must be
+ * distinguishable from a bad device secret, because the remedies are opposite:
+ * a bad secret is dropped, a stale identity binding is re-established while the
+ * (healthy) secret is kept.
+ */
+import { OxyServices } from '../../OxyServices';
+import { AccountNotOnDeviceError } from '../OxyServices.deviceBoot';
+
+const MINT_RESPONSE = {
+  accessToken: 'access-1',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+  nextDeviceSecret: 'ds-next',
+  state: {
+    deviceId: 'dev-1',
+    accounts: [{ accountId: 'vault-user', sessionId: 'sess-vault', authuser: 0 }],
+    activeAccountId: 'other-user',
+    revision: 3,
+    updatedAt: 1_700_000_000_000,
+  },
+};
+
+describe('OxyServices.mintFromDeviceSecret', () => {
+  let oxy: OxyServices;
+  let makeRequestSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequestSpy = jest.spyOn(oxy, 'makeRequest');
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('omits accountId from the body when unpinned', async () => {
+    makeRequestSpy.mockResolvedValue(MINT_RESPONSE);
+
+    await oxy.mintFromDeviceSecret('dev-1', 'ds-1');
+
+    expect(makeRequestSpy).toHaveBeenCalledWith(
+      'POST',
+      '/session/device/token',
+      { deviceId: 'dev-1', deviceSecret: 'ds-1' },
+      expect.objectContaining({ cache: false, skipAuth: true, retry: false, bypassQueue: true }),
+    );
+  });
+
+  it('sends accountId when pinned', async () => {
+    makeRequestSpy.mockResolvedValue(MINT_RESPONSE);
+
+    const mint = await oxy.mintFromDeviceSecret('dev-1', 'ds-1', { accountId: 'vault-user' });
+
+    expect(makeRequestSpy).toHaveBeenCalledWith(
+      'POST',
+      '/session/device/token',
+      { deviceId: 'dev-1', deviceSecret: 'ds-1', accountId: 'vault-user' },
+      expect.anything(),
+    );
+    // The response still reports the device's TRUE active account — a pinned
+    // mint never mutates it.
+    expect(mint.state.activeAccountId).toBe('other-user');
+  });
+
+  it('maps a 401 account_not_on_device to the typed AccountNotOnDeviceError', async () => {
+    makeRequestSpy.mockRejectedValue(
+      Object.assign(new Error('account_not_on_device'), { status: 401, code: 'UNAUTHORIZED' }),
+    );
+
+    const error = await oxy
+      .mintFromDeviceSecret('dev-1', 'ds-1', { accountId: 'vault-user' })
+      .then(
+        () => null,
+        (thrown: unknown) => thrown,
+      );
+
+    expect(error).toBeInstanceOf(AccountNotOnDeviceError);
+    expect(error).toMatchObject({ name: 'AccountNotOnDeviceError', accountId: 'vault-user', status: 401 });
+  });
+
+  it('leaves every OTHER 401 as an ordinary error (a bad secret is not an identity problem)', async () => {
+    makeRequestSpy.mockRejectedValue(
+      Object.assign(new Error('invalid_device_secret'), { status: 401, code: 'UNAUTHORIZED' }),
+    );
+
+    const error = await oxy
+      .mintFromDeviceSecret('dev-1', 'ds-1', { accountId: 'vault-user' })
+      .then(
+        () => null,
+        (thrown: unknown) => thrown,
+      );
+
+    expect(error).not.toBeInstanceOf(AccountNotOnDeviceError);
+    expect(error).toMatchObject({ message: 'invalid_device_secret', status: 401 });
+  });
+
+  it('does not classify an UNPINNED mint failure as account_not_on_device', async () => {
+    makeRequestSpy.mockRejectedValue(
+      Object.assign(new Error('account_not_on_device'), { status: 401, code: 'UNAUTHORIZED' }),
+    );
+
+    const error = await oxy.mintFromDeviceSecret('dev-1', 'ds-1').then(
+      () => null,
+      (thrown: unknown) => thrown,
+    );
+
+    expect(error).not.toBeInstanceOf(AccountNotOnDeviceError);
+  });
+});

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

@@ -0,0 +1,266 @@
+/**
+ * Discovery error-handling tests (C3).
+ *
+ * `resolveProfile` and `getProfileRecommendations` are best-effort discovery
+ * reads. Previously they swallowed every failure identically (`catch { return
+ * null }`), making a 404 "handle not found" indistinguishable from a 5xx /
+ * network failure in the field. These tests pin down the hardened behavior:
+ *
+ *  - `resolveProfile` STILL returns `null` on any failure (contract unchanged),
+ *    but emits a `debug` log that flags whether it was a not-found vs a failure.
+ *  - `getProfileRecommendations` STILL rethrows (contract unchanged), but emits
+ *    a `debug` log first for observability.
+ */
+
+import { OxyServices } from '../../OxyServices';
+import { logger } from '../../logger';
+
+/** A JSON success `Response` mimicking the API's `{ data: ... }` envelope. */
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+/**
+ * Build a non-verified JWT whose payload decodes to the given claims.
+ * `jwtDecode` only base64url-decodes the middle segment (no signature check).
+ * Used to put the SDK in an authenticated state so a state-changing POST
+ * carries a bearer header and skips the CSRF-token pre-fetch.
+ */
+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`;
+}
+
+/** A JSON error `Response` with the given HTTP status. */
+function errorResponse(status: number, message: string): Response {
+  return new Response(JSON.stringify({ message }), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+describe('discovery error handling', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+  let debugSpy: jest.SpyInstance;
+  let oxy: OxyServices;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    debugSpy = jest.spyOn(logger, 'debug').mockImplementation(() => {});
+    // Disable retry so a single error response surfaces immediately.
+    oxy = new OxyServices({ baseURL: 'http://test.invalid', enableRetry: false });
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    debugSpy.mockRestore();
+    jest.clearAllMocks();
+  });
+
+  describe('resolveProfile', () => {
+    it('returns the normalized user when discovery succeeds', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'u1', username: 'remote' }));
+      const result = await oxy.resolveProfile('remote@mastodon.social');
+      expect(result?.id).toBe('u1');
+      expect(debugSpy).not.toHaveBeenCalled();
+    });
+
+    it('returns null AND logs a not-found debug entry on 404', async () => {
+      fetchMock.mockResolvedValueOnce(errorResponse(404, 'not found'));
+      const result = await oxy.resolveProfile('ghost@nowhere.example');
+      expect(result).toBeNull();
+      expect(debugSpy).toHaveBeenCalledTimes(1);
+      const [message, context] = debugSpy.mock.calls[0];
+      expect(message).toContain('not found');
+      expect(context).toMatchObject({
+        method: 'resolveProfile',
+        handle: 'ghost@nowhere.example',
+        status: 404,
+        notFound: true,
+      });
+    });
+
+    it('returns null AND logs a failure (not not-found) debug entry on 5xx', async () => {
+      fetchMock.mockResolvedValueOnce(errorResponse(503, 'upstream down'));
+      const result = await oxy.resolveProfile('remote@down.example');
+      expect(result).toBeNull();
+      expect(debugSpy).toHaveBeenCalledTimes(1);
+      const [message, context] = debugSpy.mock.calls[0];
+      expect(message).toContain('discovery failed');
+      expect(context).toMatchObject({
+        method: 'resolveProfile',
+        status: 503,
+        notFound: false,
+      });
+    });
+
+    it('returns null on a network failure (no status)', async () => {
+      fetchMock.mockRejectedValueOnce(new TypeError('Failed to fetch'));
+      const result = await oxy.resolveProfile('remote@offline.example');
+      expect(result).toBeNull();
+      expect(debugSpy).toHaveBeenCalledTimes(1);
+      const [, context] = debugSpy.mock.calls[0];
+      expect(context).toMatchObject({ notFound: false });
+    });
+  });
+
+  describe('getProfileRecommendations', () => {
+    it('returns the list on success without logging', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse([{ id: 'r1', username: 'rec' }]));
+      const result = await oxy.getProfileRecommendations();
+      expect(result).toHaveLength(1);
+      expect(debugSpy).not.toHaveBeenCalled();
+    });
+
+    it('rethrows on failure AND logs a debug entry first (contract unchanged)', async () => {
+      fetchMock.mockResolvedValueOnce(errorResponse(500, 'boom'));
+      await expect(oxy.getProfileRecommendations()).rejects.toThrow();
+      expect(debugSpy).toHaveBeenCalledTimes(1);
+      const [message, context] = debugSpy.mock.calls[0];
+      expect(message).toContain('discovery read failed');
+      expect(context).toMatchObject({
+        method: 'getProfileRecommendations',
+        status: 500,
+      });
+    });
+  });
+
+  /**
+   * GET-vs-POST routing for the recommendation contract (Wave 2).
+   *
+   * The simple/back-compat case (no options, or only `excludeTypes`/`limit`)
+   * keeps using the cached `GET /profiles/recommendations`. The scored (v2)
+   * fields (`clientId`/`offset`/`excludeIds`/`boosts`/`signalWeights`) switch to
+   * `POST /profiles/recommendations` with the validated request body.
+   */
+  describe('getProfileRecommendations routing (GET vs POST)', () => {
+    // Authenticate so the state-changing POST carries a bearer header and the
+    // SDK skips the CSRF-token pre-fetch (which would otherwise consume a mock).
+    // A bearer token does not affect GET routing or the request body, so the
+    // GET-path assertions below are unaffected.
+    beforeEach(() => {
+      oxy.httpService.setTokens(makeJwt({ userId: 'me' }));
+    });
+
+    /** The `(url, init)` pair of the single recorded fetch call. */
+    function lastCall(): { url: string; init: RequestInit | undefined } {
+      const [input, init] = fetchMock.mock.calls[fetchMock.mock.calls.length - 1];
+      return { url: String(input), init };
+    }
+
+    it('uses GET (no body) when called with no options', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse([{ id: 'r1' }]));
+      await oxy.getProfileRecommendations();
+      const { url, init } = lastCall();
+      expect(init?.method).toBe('GET');
+      expect(init?.body).toBeUndefined();
+      expect(url).toContain('/profiles/recommendations');
+      expect(url).not.toContain('excludeTypes');
+    });
+
+    it('uses GET with excludeTypes as a comma-joined query param (legacy shape)', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse([{ id: 'r1' }]));
+      await oxy.getProfileRecommendations({ excludeTypes: ['federated', 'agent'] });
+      const { url, init } = lastCall();
+      expect(init?.method).toBe('GET');
+      expect(init?.body).toBeUndefined();
+      // Comma is URL-encoded as %2C in the query string.
+      expect(decodeURIComponent(url)).toContain('excludeTypes=federated,agent');
+    });
+
+    it('uses GET with limit as a query param', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse([{ id: 'r1' }]));
+      await oxy.getProfileRecommendations({ limit: 5 });
+      const { url, init } = lastCall();
+      expect(init?.method).toBe('GET');
+      expect(url).toContain('limit=5');
+    });
+
+    it('uses POST with the validated body when clientId is present', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse([{ id: 'r1' }]));
+      await oxy.getProfileRecommendations({ clientId: 'app-123', limit: 10 });
+      const { url, init } = lastCall();
+      expect(init?.method).toBe('POST');
+      expect(url).toContain('/profiles/recommendations');
+      expect(url).not.toContain('?');
+      expect(JSON.parse(String(init?.body))).toMatchObject({ clientId: 'app-123', limit: 10 });
+    });
+
+    it('uses POST when boosts are present', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse([{ id: 'r1' }]));
+      await oxy.getProfileRecommendations({
+        boosts: [{ userIds: ['u1', 'u2'], weight: 2, reason: 'editorial' }],
+      });
+      const { init } = lastCall();
+      expect(init?.method).toBe('POST');
+      expect(JSON.parse(String(init?.body)).boosts[0]).toMatchObject({
+        userIds: ['u1', 'u2'],
+        weight: 2,
+      });
+    });
+
+    it('uses POST when excludeIds are present', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse([{ id: 'r1' }]));
+      await oxy.getProfileRecommendations({ excludeIds: ['x1', 'x2'] });
+      const { init } = lastCall();
+      expect(init?.method).toBe('POST');
+      expect(JSON.parse(String(init?.body)).excludeIds).toEqual(['x1', 'x2']);
+    });
+
+    it('uses POST when signalWeights are present', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse([{ id: 'r1' }]));
+      await oxy.getProfileRecommendations({ signalWeights: { graph: 3 } });
+      const { init } = lastCall();
+      expect(init?.method).toBe('POST');
+      expect(JSON.parse(String(init?.body)).signalWeights).toEqual({ graph: 3 });
+    });
+
+    it('uses POST when offset is present', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse([{ id: 'r1' }]));
+      await oxy.getProfileRecommendations({ offset: 20, limit: 10 });
+      const { init } = lastCall();
+      expect(init?.method).toBe('POST');
+      expect(JSON.parse(String(init?.body))).toMatchObject({ offset: 20, limit: 10 });
+    });
+
+    it('validates the POST body against the contract and rejects bad input', async () => {
+      // weight is clamped to [-5, 5] by the schema; 99 must be rejected
+      // client-side BEFORE any network call.
+      await expect(
+        oxy.getProfileRecommendations({ boosts: [{ userIds: ['u1'], weight: 99 }] }),
+      ).rejects.toThrow();
+      expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('returns the scored items (score/matchedSignals) from the POST path', async () => {
+      fetchMock.mockResolvedValueOnce(
+        jsonResponse([
+          {
+            id: 'r1',
+            name: { displayName: 'Rec One' },
+            mutualCount: 3,
+            score: 0.87,
+            matchedSignals: ['graph', 'verified'],
+            _count: { followers: 10, following: 5 },
+          },
+        ]),
+      );
+      const result = await oxy.getProfileRecommendations({ clientId: 'app-1' });
+      expect(result).toHaveLength(1);
+      expect(result[0]).toMatchObject({
+        id: 'r1',
+        score: 0.87,
+        matchedSignals: ['graph', 'verified'],
+        mutualCount: 3,
+      });
+    });
+  });
+});

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

@@ -0,0 +1,173 @@
+/**
+ * Follow-status cache invalidation tests.
+ *
+ * Regression coverage for the "follow resets after navigating away and back"
+ * bug. `getFollowStatus(userId)` caches `GET /users/<id>/follow-status` for
+ * ~1 minute (identity-scoped). A follow/unfollow write must INVALIDATE that
+ * cached entry, otherwise a `FollowButton` that remounts within the TTL window
+ * re-reads the STALE pre-write status and reverts the optimistic UI.
+ *
+ * These tests pin down that:
+ *  - a cached `follow-status` is NOT served after `followUser` /
+ *    `unfollowUser` / `followUsers` / `unfollowUsers` — the next read
+ *    re-fetches and observes the new server truth,
+ *  - each mutation invalidates the exact logical key(s) for the affected ids.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+/**
+ * Build a non-verified JWT whose payload decodes to the given claims.
+ * `jwtDecode` only base64url-decodes the middle segment (no signature check).
+ */
+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`;
+}
+
+/** A JSON `Response` mimicking the API's `{ data: ... }` success envelope. */
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+describe('follow-status cache invalidation', () => {
+  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' });
+    oxy.httpService.setTokens(makeJwt({ userId: 'me' }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  it('does NOT serve a stale cached follow-status after followUser', async () => {
+    // 1) Warm the cache: not following yet.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: false }));
+    const before = await oxy.getFollowStatus('target-1');
+    expect(before.isFollowing).toBe(false);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // A second read within the TTL is a cache hit (no extra network call).
+    await oxy.getFollowStatus('target-1');
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // 2) Follow — write succeeds and must bust the cached follow-status.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ success: true, message: 'ok' }));
+    await oxy.followUser('target-1');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    // 3) Remount-style re-read MUST re-fetch and observe the fresh truth.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: true }));
+    const after = await oxy.getFollowStatus('target-1');
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(after.isFollowing).toBe(true);
+  });
+
+  it('does NOT serve a stale cached follow-status after unfollowUser', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: true }));
+    const before = await oxy.getFollowStatus('target-2');
+    expect(before.isFollowing).toBe(true);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ success: true, message: 'ok' }));
+    await oxy.unfollowUser('target-2');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: false }));
+    const after = await oxy.getFollowStatus('target-2');
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(after.isFollowing).toBe(false);
+  });
+
+  it('busts cached follow-status for every id after followUsers (bulk)', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: false }));
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: false }));
+    await oxy.getFollowStatus('a');
+    await oxy.getFollowStatus('b');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        results: [
+          { userId: 'a', success: true, alreadyFollowing: false },
+          { userId: 'b', success: true, alreadyFollowing: false },
+        ],
+        followedCount: 2,
+      }),
+    );
+    await oxy.followUsers(['a', 'b']);
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+
+    // Both ids must re-fetch.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: true }));
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: true }));
+    expect((await oxy.getFollowStatus('a')).isFollowing).toBe(true);
+    expect((await oxy.getFollowStatus('b')).isFollowing).toBe(true);
+    expect(fetchMock).toHaveBeenCalledTimes(5);
+  });
+
+  it('busts cached follow-status for every id after unfollowUsers (bulk)', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: true }));
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: true }));
+    await oxy.getFollowStatus('a');
+    await oxy.getFollowStatus('b');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        results: [
+          { userId: 'a', success: true, wasFollowing: true },
+          { userId: 'b', success: true, wasFollowing: true },
+        ],
+        unfollowedCount: 2,
+      }),
+    );
+    await oxy.unfollowUsers(['a', 'b']);
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: false }));
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: false }));
+    expect((await oxy.getFollowStatus('a')).isFollowing).toBe(false);
+    expect((await oxy.getFollowStatus('b')).isFollowing).toBe(false);
+    expect(fetchMock).toHaveBeenCalledTimes(5);
+  });
+
+  it('invalidates the exact logical follow-status key on a single follow', async () => {
+    const clearSpy = jest.spyOn(oxy, 'clearCacheEntry');
+    const clearPrefixSpy = jest.spyOn(oxy, 'clearCacheByPrefix');
+    fetchMock.mockResolvedValueOnce(jsonResponse({ success: true, message: 'ok' }));
+
+    await oxy.followUser('target-3');
+
+    expect(clearSpy).toHaveBeenCalledWith('GET:/users/target-3/follow-status');
+    expect(clearSpy).toHaveBeenCalledWith('GET:/users/target-3');
+    expect(clearPrefixSpy).toHaveBeenCalledWith('GET:/profiles/username/');
+    expect(clearPrefixSpy).toHaveBeenCalledWith('GET:/profiles/resolve');
+    clearSpy.mockRestore();
+    clearPrefixSpy.mockRestore();
+  });
+
+  it('does not invalidate or call the network when bulk follow gets an empty list', async () => {
+    const clearSpy = jest.spyOn(oxy, 'clearCacheEntry');
+
+    const result = await oxy.followUsers([]);
+
+    expect(result).toEqual({ results: [], followedCount: 0 });
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(clearSpy).not.toHaveBeenCalled();
+    clearSpy.mockRestore();
+  });
+});