@oxyhq/core 3.6.0 → 3.7.1

package/src/mixins/OxyServices.assets.ts

@@ -19,15 +19,49 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
     }
 
     /**
-     * Get file download URL (synchronous - uses stream endpoint for images to avoid ORB blocking)
+     * Build a synchronous file URL from an Oxy asset id.
+     *
+     * This is the single chokepoint every Oxy app uses to turn a stored file id
+     * (avatars, post media, etc.) into a `<img src>`-ready URL, so it resolves to
+     * one of two forms depending on whether the caller needs a signed/private URL:
+     *
+     * - **Public asset (default)** — no access token planted on the client AND no
+     *   `expiresIn` requested → returns the clean CDN form
+     *   `${cloudURL}/<id>[?variant=...]` (e.g. `https://cloud.oxy.so/<id>?variant=thumb`).
+     *   CloudFront resolves the id against the public media origin. No token,
+     *   `fallback`, or origin query params are emitted — these URLs are cacheable
+     *   and shareable.
+     * - **Signed / private asset** — an access token is present on the client OR
+     *   `expiresIn` was passed (the caller explicitly wants an expiring/authorized
+     *   URL) → keeps the authenticated origin form
+     *   `${baseURL}/assets/<id>/stream?...&token=...`. Private assets are NOT on
+     *   the public CDN, so they must go through the API origin that can authorize
+     *   the request.
+     *
+     * `cloudURL` (default `https://cloud.oxy.so`) is configured once on the
+     * `OxyServices` constructor and read via `getCloudURL()`; the API origin is
+     * `getBaseURL()` (e.g. `https://api.oxy.so`).
+     *
+     * For a CDN-signed URL fetched from the API, use {@link getFileDownloadUrlAsync}.
      */
     getFileDownloadUrl(fileId: string, variant?: string, expiresIn?: number): string {
+      const token = this.getClient().getAccessToken();
+
+      // Public case: no auth token and no expiry requested → clean CDN URL.
+      // CloudFront serves the public media origin under `${cloudURL}/<id>`.
+      if (!token && !expiresIn) {
+        const variantQs = variant ? `?variant=${encodeURIComponent(variant)}` : '';
+        return `${this.getCloudURL()}/${encodeURIComponent(fileId)}${variantQs}`;
+      }
+
+      // Signed / private case: route through the authenticated API origin's
+      // stream endpoint so the request can be authorized (private assets are not
+      // exposed on the public CDN).
       const base = this.getBaseURL();
       const params = new URLSearchParams();
       if (variant) params.set('variant', variant);
       if (expiresIn) params.set('expiresIn', String(expiresIn));
       params.set('fallback', 'placeholderVisible');
-      const token = this.getClient().getAccessToken();
       if (token) params.set('token', token);
 
       const qs = params.toString();

package/src/mixins/OxyServices.user.ts

@@ -10,12 +10,20 @@ import type {
   PaginationInfo,
   PrivacySettings,
 } from '../models/interfaces';
-import type { UserNameResponse, UserProfileUpdate } from '@oxyhq/contracts';
+import type {
+  UserNameResponse,
+  UserProfileUpdate,
+  RecommendationRequest,
+  RecommendationItem,
+} from '@oxyhq/contracts';
+import { recommendationRequestSchema } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { buildSearchParams, buildPaginationParams, type PaginationParams } from '../utils/apiUtils';
 import { KeyManager } from '../crypto/keyManager';
 import { SignatureService } from '../crypto/signatureService';
 import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity';
+import { logger } from '../utils/loggerUtils';
+import { extractErrorStatus } from '../utils/errorUtils';
 
 /** Per-user outcome returned by `POST /users/follow/bulk`. */
 export interface BulkFollowEntry {
@@ -149,7 +157,26 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
           cacheTTL: 24 * 60 * 60 * 1000, // 24h cache — matches server-side staleness window
         });
         return normalizeUserIdentityOrNull(result);
-      } catch {
+      } catch (error: unknown) {
+        // Discovery is best-effort: an unresolvable handle is a normal "not
+        // found", not an exceptional condition, so the contract stays `null`.
+        // But a 404 (handle genuinely absent) must be distinguishable from a
+        // network/server failure (WebFinger upstream down, 5xx) for debugging —
+        // both used to be swallowed identically. Log at `debug` with context so
+        // the distinction is observable without turning expected misses into
+        // noise. Return contract is unchanged.
+        const status = extractErrorStatus(error);
+        const isNotFound = status === 404;
+        logger.debug(
+          isNotFound ? 'resolveProfile: handle not found' : 'resolveProfile: discovery failed',
+          {
+            method: 'resolveProfile',
+            handle,
+            status,
+            notFound: isNotFound,
+            error: error instanceof Error ? error.message : String(error),
+          },
+        );
         return null;
       }
     }
@@ -173,7 +200,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
     /**
-     * Get profile recommendations, optionally filtering out specific user types.
+     * Get profile recommendations.
      *
      * Public discovery read — works WITHOUT authentication. The SDK attaches the
      * access token automatically when one is available (personalized via
@@ -181,29 +208,81 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      * the caller is logged out. This deliberately does NOT use `withAuthRetry`,
      * which would throw an authentication timeout for logged-out callers before
      * the request is ever sent.
+     *
+     * Routing (two server endpoints, both validated against the same
+     * `@oxyhq/contracts` recommendation schemas so the wire shape cannot drift):
+     *
+     *  - **GET `/profiles/recommendations`** (cached) is used for the simple,
+     *    back-compatible case: no options at all, or only `excludeTypes` and/or
+     *    `limit`. `excludeTypes` is sent as a comma-joined query param and
+     *    `limit` as a numeric query param — byte-for-byte identical to the legacy
+     *    behavior so every existing caller keeps the same request and cache key.
+     *  - **POST `/profiles/recommendations`** is used whenever any of the scored
+     *    (v2) fields — `boosts`, `excludeIds`, `signalWeights`, `clientId`, or
+     *    `offset` — is present. The full options object is validated with
+     *    `recommendationRequestSchema` and sent as the request body. The POST is
+     *    cached by the HttpService keyed on the serialized body, so repeated
+     *    identical scored requests are deduplicated/cached just like the GET path.
+     *
+     * @param options - {@link RecommendationRequest} from `@oxyhq/contracts`.
+     *   Omitted entirely (or `{ excludeTypes }`) preserves the legacy GET path.
      */
-    async getProfileRecommendations(options?: {
-      excludeTypes?: Array<'federated' | 'agent' | 'automated'>;
-    }): Promise<Array<{
-      id: string;
-      username: string;
-      name: UserNameResponse;
-      description?: string;
-      isFederated?: boolean;
-      isAgent?: boolean;
-      isAutomated?: boolean;
-      instance?: string;
-      federation?: { actorUri?: string; domain?: string; actorId?: string };
-      automation?: { ownerId?: string };
-      _count?: { followers: number; following: number };
-      [key: string]: unknown;
-    }>> {
+    async getProfileRecommendations(
+      options?: RecommendationRequest,
+    ): Promise<RecommendationItem[]> {
+      // The scored (v2) POST path is selected when any field beyond the
+      // legacy GET-supported `excludeTypes`/`limit` pair is present.
+      const usesScoredPath = Boolean(
+        options &&
+          (options.clientId !== undefined ||
+            options.offset !== undefined ||
+            (options.excludeIds?.length ?? 0) > 0 ||
+            (options.boosts?.length ?? 0) > 0 ||
+            options.signalWeights !== undefined),
+      );
+
       try {
-        const params = options?.excludeTypes?.length
-          ? { excludeTypes: options.excludeTypes.join(',') }
-          : undefined;
-        return await this.makeRequest('GET', '/profiles/recommendations', params, { cache: true });
-      } catch (error) {
+        if (usesScoredPath && options) {
+          // Validate the full request against the shared contract before
+          // sending. A malformed payload is surfaced to the caller rather than
+          // bounced by the server, and the parsed value strips unknown keys.
+          const body = recommendationRequestSchema.parse(options);
+          return await this.makeRequest<RecommendationItem[]>(
+            'POST',
+            '/profiles/recommendations',
+            body,
+            // Cache keyed on the serialized body (see HttpService.generateCacheKey)
+            // so identical scored requests are served from cache, matching the
+            // GET path's caching semantics.
+            { cache: true },
+          );
+        }
+
+        const params: Record<string, string> = {};
+        if (options?.excludeTypes?.length) {
+          params.excludeTypes = options.excludeTypes.join(',');
+        }
+        if (options?.limit !== undefined) {
+          params.limit = String(options.limit);
+        }
+        return await this.makeRequest<RecommendationItem[]>(
+          'GET',
+          '/profiles/recommendations',
+          Object.keys(params).length > 0 ? params : undefined,
+          { cache: true },
+        );
+      } catch (error: unknown) {
+        // Recommendations are a discovery read; failures are surfaced to the
+        // caller (contract unchanged: rethrow via `handleError`). Add debug
+        // observability first so a recurring upstream failure is diagnosable
+        // — distinguishing an auth/transport problem from a server 5xx.
+        logger.debug('getProfileRecommendations: discovery read failed', {
+          method: 'getProfileRecommendations',
+          path: usesScoredPath ? 'POST' : 'GET',
+          excludeTypes: options?.excludeTypes,
+          status: extractErrorStatus(error),
+          error: error instanceof Error ? error.message : String(error),
+        });
         throw this.handleError(error);
       }
     }
@@ -281,14 +360,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
         return result;
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
-        const errorRecord = error && typeof error === 'object'
-          ? error as { status?: unknown; response?: { status?: unknown } }
-          : null;
-        const status = typeof errorRecord?.status === 'number'
-          ? errorRecord.status
-          : typeof errorRecord?.response?.status === 'number'
-            ? errorRecord.response.status
-            : undefined;
+        const status = extractErrorStatus(error);
 
         // Check if it's an authentication error (401)
         const isAuthError = status === 401 ||

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 '../../utils/loggerUtils';
+
+/** 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__/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');