@oxyhq/core 3.5.0 → 3.7.0

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

@@ -0,0 +1,168 @@
+/**
+ * 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');
+    fetchMock.mockResolvedValueOnce(jsonResponse({ success: true, message: 'ok' }));
+
+    await oxy.followUser('target-3');
+
+    expect(clearSpy).toHaveBeenCalledWith('GET:/users/target-3/follow-status');
+    clearSpy.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();
+  });
+});

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

@@ -0,0 +1,83 @@
+/**
+ * `OxyServices.getFileDownloadUrl()` resolution tests.
+ *
+ * This is the single chokepoint every Oxy app uses to turn a stored asset id
+ * into a `<img src>`-ready URL. It resolves to one of two forms:
+ *
+ *   - PUBLIC (no access token planted, no `expiresIn`) → the clean CDN form
+ *     `${cloudURL}/<id>[?variant=...]` (default `https://cloud.oxy.so/<id>`),
+ *     which CloudFront resolves against the public media origin.
+ *   - SIGNED / PRIVATE (an access token is present OR `expiresIn` is passed) →
+ *     the authenticated API origin form
+ *     `${baseURL}/assets/<id>/stream?...&token=...` — private assets are not on
+ *     the public CDN.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+describe('OxyServices.getFileDownloadUrl', () => {
+  describe('public assets (no token, no expiresIn) → CDN', () => {
+    it('returns the clean cloud.oxy.so URL for a bare file id', () => {
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+
+      expect(oxy.getFileDownloadUrl('file123')).toBe('https://cloud.oxy.so/file123');
+    });
+
+    it('appends only a variant query param (no token/fallback) for the thumb variant', () => {
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+
+      expect(oxy.getFileDownloadUrl('file123', 'thumb')).toBe(
+        'https://cloud.oxy.so/file123?variant=thumb',
+      );
+    });
+
+    it('uses the configured cloudURL when overridden', () => {
+      const oxy = new OxyServices({
+        baseURL: 'https://api.oxy.so',
+        cloudURL: 'https://cdn.example.test',
+      });
+
+      expect(oxy.getFileDownloadUrl('file123', 'thumb')).toBe(
+        'https://cdn.example.test/file123?variant=thumb',
+      );
+    });
+
+    it('URL-encodes the file id and the variant', () => {
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+
+      expect(oxy.getFileDownloadUrl('a/b c', 'large size')).toBe(
+        'https://cloud.oxy.so/a%2Fb%20c?variant=large%20size',
+      );
+    });
+  });
+
+  describe('signed / private assets → authenticated API origin', () => {
+    it('returns the stream endpoint with the token when an access token is present', () => {
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+      oxy.setTokens('access-token-abc');
+
+      const url = oxy.getFileDownloadUrl('file123', 'thumb');
+
+      expect(url.startsWith('https://api.oxy.so/assets/file123/stream?')).toBe(true);
+      const params = new URLSearchParams(url.split('?')[1]);
+      expect(params.get('variant')).toBe('thumb');
+      expect(params.get('token')).toBe('access-token-abc');
+      expect(params.get('fallback')).toBe('placeholderVisible');
+      expect(url).not.toContain('cloud.oxy.so');
+    });
+
+    it('routes through the stream endpoint when expiresIn is requested even without a token', () => {
+      const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+
+      const url = oxy.getFileDownloadUrl('file123', 'thumb', 3600);
+
+      expect(url.startsWith('https://api.oxy.so/assets/file123/stream?')).toBe(true);
+      const params = new URLSearchParams(url.split('?')[1]);
+      expect(params.get('expiresIn')).toBe('3600');
+      expect(params.get('variant')).toBe('thumb');
+      expect(params.get('fallback')).toBe('placeholderVisible');
+      expect(params.get('token')).toBeNull();
+      expect(url).not.toContain('cloud.oxy.so');
+    });
+  });
+});

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

@@ -36,7 +36,12 @@ const VALID_BODY = {
   sessionId: 'sess_sso',
   expiresAt: new Date(Date.now() + 60_000).toISOString(),
   authuser: 0,
-  user: { id: 'user_sso', username: 'ssouser', avatar: 'file_1' },
+  user: {
+    id: 'user_sso',
+    username: 'ssouser',
+    name: { displayName: 'SSO User', first: 'SSO', last: 'User', full: 'SSO User' },
+    avatar: 'file_1',
+  },
 };
 
 describe('OxyServices.exchangeSsoCode', () => {
@@ -83,7 +88,12 @@ describe('OxyServices.exchangeSsoCode', () => {
     expect(oxy.getAccessToken()).toBe('access_sso');
     expect(session.sessionId).toBe('sess_sso');
     expect(session.accessToken).toBe('access_sso');
-    expect(session.user).toEqual({ id: 'user_sso', username: 'ssouser', avatar: 'file_1' });
+    expect(session.user).toEqual({
+      id: 'user_sso',
+      username: 'ssouser',
+      name: { displayName: 'SSO User', first: 'SSO', last: 'User', full: 'SSO User' },
+      avatar: 'file_1',
+    });
     expect(session.expiresAt).toBe(VALID_BODY.expiresAt);
   });
 
@@ -92,7 +102,7 @@ describe('OxyServices.exchangeSsoCode', () => {
     mockFetchOnce({
       accessToken: 'access_sso',
       sessionId: 'sess_sso',
-      user: { _id: 'mongo_id', username: 'ssouser' },
+      user: { _id: 'mongo_id', username: 'ssouser', name: { displayName: 'SSO User' } },
     });
 
     const session = await oxy.exchangeSsoCode('opaque-code-123');

package/src/utils/__tests__/coldBoot.test.ts

@@ -373,4 +373,129 @@ describe('runColdBoot', () => {
       expect(laterRan).not.toHaveBeenCalled();
     });
   });
+
+  /**
+   * End-to-end reproduction of the production FedCM-silent hang at the REAL
+   * overall deadline the SDK ships.
+   *
+   * `OxyContext` runs the web cold-boot chain with `COLD_BOOT_OVERALL_DEADLINE`
+   * (20000 ms): fedcm-silent → /auth/silent iframe → cookie restore →
+   * stored-session → /sso top-level bounce (terminal). The documented gotcha:
+   * `navigator.credentials.get({mediation:'silent'})` can sit pending forever,
+   * ignoring its AbortController. WITHOUT the overall deadline the whole chain
+   * hangs and the terminal `/sso` bounce never fires.
+   *
+   * These tests model that exact chain shape against the real deadline value and
+   * assert the runner (a) abandons the hung silent step at the deadline,
+   * (b) still fires the terminal bounce's synchronous side effect, and
+   * (c) always settles within the bounded budget — it never hangs.
+   */
+  describe('production cold-boot deadline semantics (FedCM-silent hang)', () => {
+    /**
+     * Mirror of `COLD_BOOT_OVERALL_DEADLINE` in
+     * `@oxyhq/services` `OxyContext` (the only consumer that arms the deadline).
+     * Kept as a local literal because core does not — and must not — import the
+     * services package; if the consumer's value changes, update this to match.
+     */
+    const COLD_BOOT_OVERALL_DEADLINE = 20000;
+
+    beforeEach(() => {
+      jest.useFakeTimers();
+    });
+    afterEach(() => {
+      jest.runOnlyPendingTimers();
+      jest.useRealTimers();
+    });
+
+    /** A step whose `run()` never settles — the hung `credentials.get`. */
+    const hungFedcmSilentStep = (): ColdBootStep<TestSession> => ({
+      id: 'fedcm-silent',
+      run: () => new Promise<ColdBootStepResult<TestSession>>(() => {}),
+    });
+
+    it('abandons the hung fedcm-silent step at the 20s deadline and fires the terminal /sso bounce', async () => {
+      const ssoBounced = jest.fn();
+      const onStepDeadline = jest.fn();
+
+      const outcomePromise = runColdBoot<TestSession>({
+        overallDeadlineMs: COLD_BOOT_OVERALL_DEADLINE,
+        onStepDeadline,
+        steps: [
+          hungFedcmSilentStep(),
+          // Every intermediate step has nothing to contribute on this load.
+          skipStep('auth-silent-iframe'),
+          skipStep('cookie-restore'),
+          skipStep('stored-session'),
+          {
+            id: 'sso-bounce',
+            // Terminal: navigates synchronously before its first await, exactly
+            // like the real top-level `/sso` bounce.
+            run: async (): Promise<ColdBootStepResult<TestSession>> => {
+              ssoBounced();
+              return { kind: 'skip' };
+            },
+          },
+        ],
+      });
+
+      // Nothing settles before the deadline — the chain is "stuck" on silent.
+      await jest.advanceTimersByTimeAsync(COLD_BOOT_OVERALL_DEADLINE - 1);
+      expect(ssoBounced).not.toHaveBeenCalled();
+
+      // At the deadline the silent step is abandoned and the chain proceeds.
+      await jest.advanceTimersByTimeAsync(1);
+      const outcome = await outcomePromise;
+
+      expect(onStepDeadline).toHaveBeenCalledWith('fedcm-silent');
+      expect(ssoBounced).toHaveBeenCalledTimes(1);
+      expect(outcome).toEqual({ kind: 'unauthenticated' });
+    });
+
+    it('settles within the bounded budget instead of hanging forever', async () => {
+      let settled = false;
+      const outcomePromise = runColdBoot<TestSession>({
+        overallDeadlineMs: COLD_BOOT_OVERALL_DEADLINE,
+        steps: [hungFedcmSilentStep(), skipStep('terminal')],
+      }).then((o) => {
+        settled = true;
+        return o;
+      });
+
+      // Just before the deadline: still pending (proves the deadline, not an
+      // accidental early settle, is what unblocks it).
+      await jest.advanceTimersByTimeAsync(COLD_BOOT_OVERALL_DEADLINE - 1);
+      expect(settled).toBe(false);
+
+      await jest.advanceTimersByTimeAsync(1);
+      await outcomePromise;
+      expect(settled).toBe(true);
+    });
+
+    it('does not penalize a fast silent success — it wins well before the deadline', async () => {
+      const laterRan = jest.fn();
+      const outcomePromise = runColdBoot<TestSession>({
+        overallDeadlineMs: COLD_BOOT_OVERALL_DEADLINE,
+        steps: [
+          {
+            id: 'fedcm-silent',
+            run: async (): Promise<ColdBootStepResult<TestSession>> => {
+              await Promise.resolve();
+              return { kind: 'session', session: { userId: 'u-silent' } };
+            },
+          },
+          sessionStep('sso-bounce', 'u-should-not-run', laterRan),
+        ],
+      });
+
+      await jest.advanceTimersByTimeAsync(0);
+      const outcome = await outcomePromise;
+
+      expect(outcome).toEqual({
+        kind: 'session',
+        via: 'fedcm-silent',
+        session: { userId: 'u-silent' },
+      });
+      expect(laterRan).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/utils/cacheKey.ts

@@ -0,0 +1,98 @@
+/**
+ * Cache-key primitives for the identity-scoped HTTP GET response cache.
+ *
+ * Extracted from {@link HttpService} so the identity-tag derivation is a pure,
+ * independently testable function with no dependency on instance/token state.
+ * The HTTP service injects the live access token and acting-as id; everything
+ * here is referentially transparent given those inputs.
+ */
+
+import { jwtDecode } from 'jwt-decode';
+
+/**
+ * Minimal JWT payload shape we read for cache scoping. The identity discriminator
+ * comes from `userId` (preferred) or `id`; nothing else is consulted here.
+ */
+export interface CacheIdentityJwtPayload {
+  userId?: string;
+  id?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Discriminator used when there is no access token at all. Anonymous responses
+ * must never collide with any authenticated identity.
+ */
+export const ANON_IDENTITY = 'anon';
+
+/**
+ * FNV-1a 32-bit non-cryptographic hash.
+ *
+ * Used by the cache-key generator for large payloads where full JSON inclusion
+ * would balloon the cache map keys, and as the fallback discriminator for an
+ * undecodable access token. Content-addressed: every byte of the input
+ * contributes to the digest, so two inputs with the same top-level shape but
+ * different field values produce different keys (the previous `keys + length`
+ * heuristic collided on these).
+ *
+ * Trade-offs:
+ *  - 32 bits is ample for an in-process cache (collision risk negligible at our
+ *    key counts; we also prefix with method + url which further partitions the
+ *    keyspace).
+ *  - Not cryptographically secure — never use for security decisions.
+ *  - Zero dependencies, branch-free hot loop, ~1 GiB/s on V8.
+ */
+export function fnv1a32(str: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    // h * 16777619 mod 2^32, written as shift-and-add for portability and
+    // to avoid 53-bit JS number truncation in the intermediate multiply.
+    h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+/**
+ * Derive a stable, non-sensitive identity discriminator for cache scoping.
+ *
+ * The GET-response cache MUST be partitioned by caller identity: endpoints with
+ * optional auth (e.g. `GET /profiles/recommendations`) return different content
+ * for an anonymous vs an authenticated caller, and per-user content for
+ * different authenticated users. Keying solely on `method:url:data` let an
+ * anonymous response be served to an authenticated caller — surfacing as
+ * "Who to follow" recommending accounts the user already follows after a
+ * cold-boot session restore.
+ *
+ * Resolution order:
+ *  - no token            → {@link ANON_IDENTITY} (`'anon'`).
+ *  - decodable token     → the token's `userId || id`.
+ *  - undecodable token   → a short FNV-1a hash of the token, prefixed `t` so it
+ *                          can never collide with `'anon'` or a real user id.
+ *
+ * We use the decoded user id rather than the raw JWT so the token never lands
+ * in a cache key (no token leakage through any cache-key logging, no key bloat).
+ * The acting-as id is folded in because managed-account responses differ per
+ * acting identity — and `X-Acting-As` already changes the server response for
+ * the same bearer token.
+ *
+ * @param accessToken The current bearer access token, or `null` when anonymous.
+ * @param actingAsUserId The active managed-account id, or `null`.
+ */
+export function computeIdentityTag(
+  accessToken: string | null,
+  actingAsUserId: string | null,
+): string {
+  let principal = ANON_IDENTITY;
+  if (accessToken) {
+    try {
+      const decoded = jwtDecode<CacheIdentityJwtPayload>(accessToken);
+      principal = decoded.userId || decoded.id || `t${fnv1a32(accessToken)}`;
+    } catch {
+      // Undecodable token — still partition it away from anon and from other
+      // tokens via a hash. Never silently fall back to ANON_IDENTITY.
+      principal = `t${fnv1a32(accessToken)}`;
+    }
+  }
+  return actingAsUserId ? `${principal}~as${actingAsUserId}` : principal;
+}

package/src/utils/errorUtils.ts

@@ -180,6 +180,31 @@ export function getErrorCodeFromStatus(status: number): string {
   }
 }
 
+/**
+ * Best-effort extraction of an HTTP status code from a thrown value.
+ *
+ * `HttpService` annotates the errors it throws with both `error.status` and
+ * `error.response.status`; an already-normalized {@link ApiError} carries
+ * `error.status`. This reads either, returning `undefined` when the value is
+ * not an object or carries no numeric status (e.g. a thrown string, a network
+ * `TypeError`). Used by discovery/read paths to distinguish a 404 "not found"
+ * from a transport/server failure for observability without re-deriving the
+ * narrowing at every call site.
+ */
+export function extractErrorStatus(error: unknown): number | undefined {
+  if (!error || typeof error !== 'object') {
+    return undefined;
+  }
+  const record = error as { status?: unknown; response?: { status?: unknown } };
+  if (typeof record.status === 'number') {
+    return record.status;
+  }
+  if (typeof record.response?.status === 'number') {
+    return record.response.status;
+  }
+  return undefined;
+}
+
 /**
  * Validate required fields and throw error if missing
  */