@oxyhq/core 3.5.0 → 3.7.0

package/src/__tests__/httpServiceCache.test.ts

@@ -195,4 +195,75 @@ describe('HttpService identity-scoped response cache', () => {
     await http.get('/users/u1', { cache: true });
     expect(fetchMock).toHaveBeenCalledTimes(3);
   });
+
+  /**
+   * The soft cache-size guard is observability-only: it must warn (once,
+   * throttled) when the entry count blows past the soft ceiling, but must NEVER
+   * evict a live entry. We synthesize bloat by giving every request a distinct
+   * undecodable token, so each write mints a fresh identity tag → a fresh key.
+   */
+  describe('soft cache-size telemetry guard', () => {
+    /** Number of distinct cached entries needed to cross the 500 soft ceiling. */
+    const ENTRIES_PAST_LIMIT = 520;
+
+    const newLoggingService = (): HttpService =>
+      new HttpService({
+        baseURL: 'http://test.invalid',
+        enableRetry: false,
+        requestTimeout: 1000,
+        enableLogging: true,
+        logLevel: 'warn',
+      });
+
+    let warnSpy: jest.SpyInstance;
+    beforeEach(() => {
+      // SimpleLogger routes `warn` to console.warn; spy there to assert telemetry.
+      warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    });
+    afterEach(() => {
+      warnSpy.mockRestore();
+    });
+
+    it('warns (throttled) once the cache exceeds the soft entry limit and never evicts', async () => {
+      const http = newLoggingService();
+
+      // Each iteration: a fresh undecodable token → fresh identity tag → fresh
+      // key, so the cache grows by one live entry per call.
+      for (let i = 0; i < ENTRIES_PAST_LIMIT; i++) {
+        http.setTokens(`undecodable-token-${i}`);
+        fetchMock.mockResolvedValueOnce(jsonResponse({ i }));
+        await http.get('/profiles/recommendations', { cache: true });
+      }
+
+      // No eviction: every distinct entry is still resident.
+      expect(http.getCacheStats().size).toBe(ENTRIES_PAST_LIMIT);
+
+      // Telemetry fired, and exactly once within the throttle window.
+      const cacheWarnings = warnSpy.mock.calls.filter((args) =>
+        args.some(
+          (a: unknown) =>
+            typeof a === 'string' && a.includes('exceeded soft entry limit'),
+        ),
+      );
+      expect(cacheWarnings.length).toBe(1);
+    });
+
+    it('does not warn while the cache stays under the soft limit', async () => {
+      const http = newLoggingService();
+
+      for (let i = 0; i < 10; i++) {
+        http.setTokens(`undecodable-token-${i}`);
+        fetchMock.mockResolvedValueOnce(jsonResponse({ i }));
+        await http.get('/profiles/recommendations', { cache: true });
+      }
+
+      const cacheWarnings = warnSpy.mock.calls.filter((args) =>
+        args.some(
+          (a: unknown) =>
+            typeof a === 'string' && a.includes('exceeded soft entry limit'),
+        ),
+      );
+      expect(cacheWarnings.length).toBe(0);
+    });
+  });
 });

package/src/index.ts

@@ -64,6 +64,8 @@ export type {
 export type {
     BulkFollowEntry,
     BulkFollowResult,
+    BulkUnfollowEntry,
+    BulkUnfollowResult,
 } from './mixins/OxyServices.user';
 export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';
 

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 {
@@ -35,6 +43,24 @@ export interface BulkFollowResult {
   followedCount: number;
 }
 
+/** Per-user outcome returned by `POST /users/unfollow/bulk`. */
+export interface BulkUnfollowEntry {
+  /** The user ID that was processed. */
+  userId: string;
+  /** Whether the unfollow was applied (or already absent) without error. */
+  success: boolean;
+  /** Whether the caller was following this user before the request. */
+  wasFollowing: boolean;
+}
+
+/** Response shape of `POST /users/unfollow/bulk`. */
+export interface BulkUnfollowResult {
+  /** Per-user outcomes, in request order. */
+  results: BulkUnfollowEntry[];
+  /** Number of users newly unfollowed by this request. */
+  unfollowedCount: number;
+}
+
 export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
     constructor(...args: any[]) {
@@ -131,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;
       }
     }
@@ -155,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
@@ -163,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);
       }
     }
@@ -263,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 ||
@@ -412,11 +502,20 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
 
 
     /**
-     * Follow a user
+     * Follow a user.
+     *
+     * Invalidates the cached `GET /users/<id>/follow-status` response after
+     * the write. `getFollowStatus` caches for ~1 minute (identity-scoped);
+     * without busting that entry, a `FollowButton` that remounts within the
+     * TTL window re-reads the STALE pre-write status and reverts the optimistic
+     * UI (the "follow resets after navigating away and back" bug).
+     * `clearCacheEntry` deletes every identity-scoped variant of the key.
      */
     async followUser(userId: string): Promise<{ success: boolean; message: string }> {
       try {
-        return await this.makeRequest('POST', `/users/${userId}/follow`, undefined, { cache: false });
+        const result = await this.makeRequest<{ success: boolean; message: string }>('POST', `/users/${userId}/follow`, undefined, { cache: false });
+        this.clearCacheEntry(`GET:/users/${userId}/follow-status`);
+        return result;
       } catch (error) {
         throw this.handleError(error);
       }
@@ -435,7 +534,36 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
         return { results: [], followedCount: 0 };
       }
       try {
-        return await this.makeRequest<BulkFollowResult>('POST', '/users/follow/bulk', { userIds }, { cache: false });
+        const result = await this.makeRequest<BulkFollowResult>('POST', '/users/follow/bulk', { userIds }, { cache: false });
+        // Bust each affected user's cached follow-status (see `followUser`).
+        for (const id of userIds) {
+          this.clearCacheEntry(`GET:/users/${id}/follow-status`);
+        }
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Unfollow multiple users in a single request.
+     *
+     * POSTs `/users/unfollow/bulk` with `{ userIds }` (server caps the batch at
+     * 200). Returns the per-user outcomes and the count of users newly
+     * unfollowed. An empty `userIds` array resolves immediately with an empty
+     * result and performs no network call.
+     */
+    async unfollowUsers(userIds: string[]): Promise<BulkUnfollowResult> {
+      if (userIds.length === 0) {
+        return { results: [], unfollowedCount: 0 };
+      }
+      try {
+        const result = await this.makeRequest<BulkUnfollowResult>('POST', '/users/unfollow/bulk', { userIds }, { cache: false });
+        // Bust each affected user's cached follow-status (see `followUser`).
+        for (const id of userIds) {
+          this.clearCacheEntry(`GET:/users/${id}/follow-status`);
+        }
+        return result;
       } catch (error) {
         throw this.handleError(error);
       }
@@ -446,7 +574,10 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async unfollowUser(userId: string): Promise<{ success: boolean; message: string }> {
       try {
-        return await this.makeRequest('DELETE', `/users/${userId}/follow`, undefined, { cache: false });
+        const result = await this.makeRequest<{ success: boolean; message: string }>('DELETE', `/users/${userId}/follow`, undefined, { cache: false });
+        // Bust the cached follow-status so a remount reads fresh truth (see `followUser`).
+        this.clearCacheEntry(`GET:/users/${userId}/follow-status`);
+        return result;
       } catch (error) {
         throw this.handleError(error);
       }

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,
+      });
+    });
+  });
+});