@oxyhq/core 3.6.0 → 3.7.1

package/dist/types/HttpService.d.ts

@@ -54,6 +54,12 @@ export declare class HttpService {
     private tokenRefreshCooldownUntil;
     private authRefreshHandler;
     private accessTokenProvider;
+    /**
+     * Epoch (ms) before which a cache-size telemetry warning must not be
+     * re-emitted. Throttles the {@link CACHE_SOFT_MAX_ENTRIES} warning to at most
+     * one per {@link CACHE_SIZE_WARNING_THROTTLE_MS} window.
+     */
+    private cacheSizeWarningSilentUntil;
     /**
      * Fan-out listeners notified on EVERY access-token change on this instance:
      * explicit `setTokens`, `clearTokens`, an AuthManager-owned refresh, and the
@@ -89,6 +95,20 @@ export declare class HttpService {
      * Main request method - handles everything in one place
      */
     request<T = unknown>(config: RequestConfig): Promise<T>;
+    /**
+     * Soft cache-size guard. Emits a single throttled telemetry warning when the
+     * identity-scoped response cache grows past {@link CACHE_SOFT_MAX_ENTRIES}.
+     *
+     * This intentionally does NOT evict: the {@link TTLCache} already bounds
+     * memory by TTL (and the global cleanup interval sweeps expired entries), so
+     * an LRU here would only risk thrashing a legitimately warm cache. The point
+     * is observability — if entry count climbs and stays high, an identity tag or
+     * cache key is folding in volatile data (a per-request nonce, an undecodable
+     * rotating token) and the cache is no longer doing its job. Surfacing that via
+     * the logger lets a consumer with `enableLogging` catch the regression in the
+     * field instead of debugging silent memory growth.
+     */
+    private warnIfCacheOversized;
     /**
      * Upload via XMLHttpRequest (React Native FormData workaround).
      *
@@ -122,22 +142,10 @@ export declare class HttpService {
     /**
      * 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`
-     * (the previous behavior) 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.
-     *
-     * We use the access token's decoded user id (`userId || 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. Falls back
-     * to `'anon'` when there is no token, and to a short FNV-1a hash of the token
-     * only if it is present but cannot be decoded (degraded but still partitioned,
-     * never colliding anon with authed).
+     * Thin instance wrapper over the pure {@link computeIdentityTag} helper —
+     * binds it to this instance's live access token and acting-as id. See that
+     * function's docs for the full resolution contract (anon fallback, decoded
+     * `userId || id`, token-hash fallback for undecodable tokens).
      */
     private computeIdentityTag;
     /**

package/dist/types/mixins/OxyServices.assets.d.ts

@@ -7,7 +7,30 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
          */
         deleteFile(fileId: string): Promise<any>;
         /**
-         * 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;
         /**

package/dist/types/mixins/OxyServices.user.d.ts

@@ -2,7 +2,7 @@
  * User Management Methods Mixin
  */
 import type { User, Notification, NotificationPreferences, UserPreferences, SearchProfilesResponse, PrivacySettings } from '../models/interfaces';
-import type { UserNameResponse, UserProfileUpdate } from '@oxyhq/contracts';
+import type { UserNameResponse, UserProfileUpdate, RecommendationRequest, RecommendationItem } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { type PaginationParams } from '../utils/apiUtils';
 /** Per-user outcome returned by `POST /users/follow/bulk`. */
@@ -81,7 +81,7 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
             ownerId?: string;
         }): Promise<User>;
         /**
-         * 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
@@ -89,32 +89,26 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          * 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.
          */
-        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;
-        }>>;
+        getProfileRecommendations(options?: RecommendationRequest): Promise<RecommendationItem[]>;
         /**
          * Get profiles similar to a given user, based on co-follower overlap.
          */

package/dist/types/utils/cacheKey.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare 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 declare function fnv1a32(str: string): string;
+/**
+ * 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 declare function computeIdentityTag(accessToken: string | null, actingAsUserId: string | null): string;

package/dist/types/utils/errorUtils.d.ts

@@ -36,6 +36,18 @@ export declare function handleHttpError(error: unknown): ApiError;
  * Exported for use in other modules
  */
 export declare 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 declare function extractErrorStatus(error: unknown): number | undefined;
 /**
  * Validate required fields and throw error if missing
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.6.0",
+  "version": "3.7.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -97,7 +97,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "^0.1.1",
+    "@oxyhq/contracts": "^0.2.0",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",
     "elliptic": "^6.6.1",

package/src/HttpService.ts

@@ -19,6 +19,7 @@ import { retryAsync } from './utils/asyncUtils';
 import { handleHttpError } from './utils/errorUtils';
 import { jwtDecode } from 'jwt-decode';
 import { isNative, isReactNative, getPlatformOS } from './utils/platform';
+import { computeIdentityTag, fnv1a32 } from './utils/cacheKey';
 import type { OxyConfig } from './models/interfaces';
 
 /**
@@ -58,33 +59,6 @@ interface FormDataLike {
   has(name: string): boolean;
 }
 
-/**
- * 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. Content-addressed: every
- * byte of the input contributes to the digest, so two payloads 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.
- */
-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');
-}
-
 export interface RequestOptions {
   cache?: boolean;
   cacheTTL?: number;
@@ -107,6 +81,69 @@ interface RequestConfig extends RequestOptions {
   _isCsrfRetry?: boolean;
 }
 
+/**
+ * Default per-request timeout (ms) when neither the call site nor
+ * {@link OxyConfig.requestTimeout} overrides it. Kept tight so a stalled
+ * endpoint surfaces as an `AbortError` quickly rather than blocking the
+ * request queue.
+ */
+const DEFAULT_REQUEST_TIMEOUT_MS = 5000;
+
+/**
+ * Timeout (ms) for the dedicated `GET /csrf-token` fetch. Independent of the
+ * regular request timeout: this is a small, fast, unauthenticated call and
+ * should never inherit a longer per-request budget.
+ */
+const CSRF_FETCH_TIMEOUT_MS = 5000;
+
+/**
+ * Number of attempts for fetching a CSRF token before giving up. The first
+ * failure is usually a cold edge/cookie race; a single retry recovers it
+ * without masking a genuinely broken `/csrf-token` route.
+ */
+const CSRF_FETCH_MAX_ATTEMPTS = 2;
+
+/**
+ * Backoff (ms) between CSRF-token fetch attempts. Short by design — a CSRF
+ * fetch sits in the critical path of a state-changing request, so the retry
+ * must add minimal latency.
+ */
+const CSRF_FETCH_RETRY_DELAY_MS = 500;
+
+/**
+ * Cooldown (ms) applied after a failed access-token refresh before another
+ * refresh is attempted. Prevents a refresh storm (and server hammering) when
+ * the AuthManager's refresh handler is failing — every in-flight request that
+ * hits a 401 would otherwise trigger its own refresh.
+ */
+const TOKEN_REFRESH_COOLDOWN_MS = 15000;
+
+/**
+ * Lead time (seconds) before access-token expiry at which a preflight refresh
+ * is triggered. A token within this window of `exp` is treated as effectively
+ * expired so the request carries a fresh bearer rather than racing the clock.
+ */
+const TOKEN_REFRESH_LEAD_SECONDS = 60;
+
+/**
+ * Soft ceiling on the number of live entries in the identity-scoped GET
+ * response cache. Crossing it does NOT evict anything (the {@link TTLCache}
+ * still expires by TTL and is swept on its cleanup interval) — it emits a
+ * single throttled telemetry warning via the logger so an unbounded-growth
+ * regression (e.g. an endpoint that mints a fresh identity tag per request, or
+ * a cache-key that accidentally folds in volatile data) is observable in the
+ * field instead of silently consuming memory. Tuned well above the working set
+ * a single authenticated user generates in normal use.
+ */
+const CACHE_SOFT_MAX_ENTRIES = 500;
+
+/**
+ * Minimum interval (ms) between successive cache-size telemetry warnings, so a
+ * cache that sits above the soft limit logs at most once per window rather than
+ * on every cached write.
+ */
+const CACHE_SIZE_WARNING_THROTTLE_MS = 60000;
+
 /**
  * Token store for authentication (instance-based)
  * Each HttpService gets its own TokenStore to prevent conflicts
@@ -174,6 +211,13 @@ export class HttpService {
   private authRefreshHandler: AuthRefreshHandler | null = null;
   private accessTokenProvider: AccessTokenProvider | null = null;
 
+  /**
+   * Epoch (ms) before which a cache-size telemetry warning must not be
+   * re-emitted. Throttles the {@link CACHE_SOFT_MAX_ENTRIES} warning to at most
+   * one per {@link CACHE_SIZE_WARNING_THROTTLE_MS} window.
+   */
+  private cacheSizeWarningSilentUntil: number = 0;
+
   /**
    * Fan-out listeners notified on EVERY access-token change on this instance:
    * explicit `setTokens`, `clearTokens`, an AuthManager-owned refresh, and the
@@ -306,7 +350,7 @@ export class HttpService {
       url,
       data,
       params,
-      timeout = this.config.requestTimeout || 5000,
+      timeout = this.config.requestTimeout || DEFAULT_REQUEST_TIMEOUT_MS,
       signal,
       cache = method === 'GET',
       cacheTTL,
@@ -571,11 +615,41 @@ export class HttpService {
     // Cache the result if caching is enabled
     if (cache && cacheKey && result) {
       this.cache.set(cacheKey, result, cacheTTL);
+      this.warnIfCacheOversized();
     }
 
     return result;
   }
 
+  /**
+   * Soft cache-size guard. Emits a single throttled telemetry warning when the
+   * identity-scoped response cache grows past {@link CACHE_SOFT_MAX_ENTRIES}.
+   *
+   * This intentionally does NOT evict: the {@link TTLCache} already bounds
+   * memory by TTL (and the global cleanup interval sweeps expired entries), so
+   * an LRU here would only risk thrashing a legitimately warm cache. The point
+   * is observability — if entry count climbs and stays high, an identity tag or
+   * cache key is folding in volatile data (a per-request nonce, an undecodable
+   * rotating token) and the cache is no longer doing its job. Surfacing that via
+   * the logger lets a consumer with `enableLogging` catch the regression in the
+   * field instead of debugging silent memory growth.
+   */
+  private warnIfCacheOversized(): void {
+    const size = this.cache.size();
+    if (size <= CACHE_SOFT_MAX_ENTRIES) {
+      return;
+    }
+    const now = Date.now();
+    if (now < this.cacheSizeWarningSilentUntil) {
+      return;
+    }
+    this.cacheSizeWarningSilentUntil = now + CACHE_SIZE_WARNING_THROTTLE_MS;
+    this.logger.warn(
+      'Response cache exceeded soft entry limit — possible identity-tag or cache-key bloat',
+      { size, softLimit: CACHE_SOFT_MAX_ENTRIES },
+    );
+  }
+
   /**
    * Upload via XMLHttpRequest (React Native FormData workaround).
    *
@@ -701,37 +775,13 @@ export class HttpService {
   /**
    * 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`
-   * (the previous behavior) 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.
-   *
-   * We use the access token's decoded user id (`userId || 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. Falls back
-   * to `'anon'` when there is no token, and to a short FNV-1a hash of the token
-   * only if it is present but cannot be decoded (degraded but still partitioned,
-   * never colliding anon with authed).
+   * Thin instance wrapper over the pure {@link computeIdentityTag} helper —
+   * binds it to this instance's live access token and acting-as id. See that
+   * function's docs for the full resolution contract (anon fallback, decoded
+   * `userId || id`, token-hash fallback for undecodable tokens).
    */
   private computeIdentityTag(): string {
-    const accessToken = this.tokenStore.getAccessToken();
-    let principal = 'anon';
-    if (accessToken) {
-      try {
-        const decoded = jwtDecode<JwtPayload>(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'.
-        principal = `t${fnv1a32(accessToken)}`;
-      }
-    }
-    return this._actingAsUserId ? `${principal}~as${this._actingAsUserId}` : principal;
+    return computeIdentityTag(this.tokenStore.getAccessToken(), this._actingAsUserId);
   }
 
   /**
@@ -820,14 +870,13 @@ export class HttpService {
     }
 
     const fetchPromise = (async () => {
-      const maxAttempts = 2;
-      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      for (let attempt = 1; attempt <= CSRF_FETCH_MAX_ATTEMPTS; attempt++) {
         try {
           this.logger.debug('Fetching CSRF token from:', `${this.baseURL}/csrf-token`, `(attempt ${attempt})`);
 
           // Use AbortController for timeout (more compatible than AbortSignal.timeout)
           const controller = new AbortController();
-          const timeoutId = setTimeout(() => controller.abort(), 5000);
+          const timeoutId = setTimeout(() => controller.abort(), CSRF_FETCH_TIMEOUT_MS);
 
           const response = await fetch(`${this.baseURL}/csrf-token`, {
             method: 'GET',
@@ -863,9 +912,9 @@ export class HttpService {
           this.logger.debug('CSRF fetch error:', error);
           this.logger.warn('CSRF token fetch error:', error);
         }
-        // Wait before retry (500ms)
-        if (attempt < maxAttempts) {
-          await new Promise(resolve => setTimeout(resolve, 500));
+        // Brief backoff before the next attempt.
+        if (attempt < CSRF_FETCH_MAX_ATTEMPTS) {
+          await new Promise(resolve => setTimeout(resolve, CSRF_FETCH_RETRY_DELAY_MS));
         }
       }
       return null;
@@ -890,8 +939,8 @@ export class HttpService {
       const decoded = jwtDecode<JwtPayload>(accessToken);
       const currentTime = Math.floor(Date.now() / 1000);
 
-      // If token expires in less than 60 seconds, refresh it
-      if (decoded.exp && decoded.exp - currentTime < 60) {
+      // If the token expires within the refresh lead window, refresh it.
+      if (decoded.exp && decoded.exp - currentTime < TOKEN_REFRESH_LEAD_SECONDS) {
         const refreshed = await this.refreshAccessToken('preflight');
         if (refreshed) return `Bearer ${refreshed}`;
         if (decoded.exp > currentTime) {
@@ -921,7 +970,7 @@ export class HttpService {
       this.tokenRefreshPromise = this.authRefreshHandler(reason)
         .then((newToken) => {
           if (!newToken) {
-            this.tokenRefreshCooldownUntil = Date.now() + 15000;
+            this.tokenRefreshCooldownUntil = Date.now() + TOKEN_REFRESH_COOLDOWN_MS;
             return null;
           }
           if (this.tokenStore.getAccessToken() !== newToken) {
@@ -933,7 +982,7 @@ export class HttpService {
         })
         .catch((error) => {
           this.logger.warn('Token refresh failed:', error);
-          this.tokenRefreshCooldownUntil = Date.now() + 15000;
+          this.tokenRefreshCooldownUntil = Date.now() + TOKEN_REFRESH_COOLDOWN_MS;
           return null;
         })
         .finally(() => {

package/src/__tests__/authManager.cookiePath.test.ts

@@ -85,14 +85,14 @@ const TWO_ACCOUNTS: RefreshAllResponse = {
       accessToken: TOKEN_SLOT_0,
       expiresAt: '2099-01-01T00:00:00.000Z',
       sessionId: 'sess-slot-0',
-      user: { id: 'user-0', username: 'alice', avatar: null, color: '#1abc9c' },
+      user: { id: 'user-0', username: 'alice', name: { displayName: 'Alice' }, avatar: null, color: '#1abc9c' },
     },
     {
       authuser: 1,
       accessToken: TOKEN_SLOT_1,
       expiresAt: '2099-01-01T00:00:00.000Z',
       sessionId: 'sess-slot-1',
-      user: { id: 'user-1', username: 'bob', avatar: null, color: '#3498db' },
+      user: { id: 'user-1', username: 'bob', name: { displayName: 'Bob' }, avatar: null, color: '#3498db' },
     },
   ],
 };

package/src/__tests__/authManager.security.test.ts

@@ -89,14 +89,14 @@ const TWO_ACCOUNTS: RefreshAllResponse = {
       accessToken: TOKEN_SLOT_0,
       expiresAt: '2099-01-01T00:00:00.000Z',
       sessionId: 'sess-slot-0',
-      user: { id: 'user-0', username: 'alice', avatar: null, color: '#1abc9c' },
+      user: { id: 'user-0', username: 'alice', name: { displayName: 'Alice' }, avatar: null, color: '#1abc9c' },
     },
     {
       authuser: 1,
       accessToken: TOKEN_SLOT_1,
       expiresAt: '2099-01-01T00:00:00.000Z',
       sessionId: 'sess-slot-1',
-      user: { id: 'user-1', username: 'bob', avatar: null, color: '#3498db' },
+      user: { id: 'user-1', username: 'bob', name: { displayName: 'Bob' }, avatar: null, color: '#3498db' },
     },
   ],
 };

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