@oxyhq/core 3.6.0 → 3.7.1

package/dist/esm/HttpService.js

@@ -18,37 +18,67 @@ import { retryAsync } from './utils/asyncUtils.js';
 import { handleHttpError } from './utils/errorUtils.js';
 import { jwtDecode } from 'jwt-decode';
 import { isNative, isReactNative, getPlatformOS } from './utils/platform.js';
+import { computeIdentityTag, fnv1a32 } from './utils/cacheKey.js';
 /**
  * Check if we're running in a native app environment (React Native, not web)
  * This is used to determine CSRF handling mode
  */
 const isNativeApp = isNative();
 /**
- * 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.
+ * 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.
  */
-function fnv1a32(str) {
-    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');
-}
+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
@@ -101,6 +131,12 @@ export class HttpService {
         this.tokenRefreshCooldownUntil = 0;
         this.authRefreshHandler = null;
         this.accessTokenProvider = 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.
+         */
+        this.cacheSizeWarningSilentUntil = 0;
         /**
          * Fan-out listeners notified on EVERY access-token change on this instance:
          * explicit `setTokens`, `clearTokens`, an AuthManager-owned refresh, and the
@@ -202,7 +238,7 @@ export class HttpService {
      * Main request method - handles everything in one place
      */
     async request(config) {
-        const { method, url, data, params, timeout = this.config.requestTimeout || 5000, signal, cache = method === 'GET', cacheTTL, deduplicate = true, retry = this.config.enableRetry !== false, maxRetries = this.config.maxRetries || 3, } = config;
+        const { method, url, data, params, timeout = this.config.requestTimeout || DEFAULT_REQUEST_TIMEOUT_MS, signal, cache = method === 'GET', cacheTTL, deduplicate = true, retry = this.config.enableRetry !== false, maxRetries = this.config.maxRetries || 3, } = config;
         // Generate cache key (optimized for large objects)
         const cacheKey = cache ? this.generateCacheKey(method, url, data || params) : null;
         // Check cache first
@@ -433,9 +469,35 @@ 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.
+     */
+    warnIfCacheOversized() {
+        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).
      *
@@ -542,38 +604,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).
      */
     computeIdentityTag() {
-        const accessToken = this.tokenStore.getAccessToken();
-        let principal = 'anon';
-        if (accessToken) {
-            try {
-                const decoded = jwtDecode(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);
     }
     /**
      * Generate cache key efficiently
@@ -651,13 +688,12 @@ export class HttpService {
             return existingPromise;
         }
         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',
                         headers: { 'Accept': 'application/json' },
@@ -688,9 +724,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;
@@ -711,8 +747,8 @@ export class HttpService {
         try {
             const decoded = jwtDecode(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}`;
@@ -740,7 +776,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) {
@@ -752,7 +788,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/dist/esm/mixins/OxyServices.assets.js

@@ -15,9 +15,42 @@ export function OxyServicesAssetsMixin(Base) {
             }
         }
         /**
-         * 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, variant, expiresIn) {
+            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)
@@ -25,7 +58,6 @@ export function OxyServicesAssetsMixin(Base) {
             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/dist/esm/mixins/OxyServices.user.js

@@ -1,7 +1,10 @@
+import { recommendationRequestSchema } from '@oxyhq/contracts';
 import { buildSearchParams, buildPaginationParams } from '../utils/apiUtils.js';
 import { KeyManager } from '../crypto/keyManager.js';
 import { SignatureService } from '../crypto/signatureService.js';
 import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity.js';
+import { logger } from '../utils/loggerUtils.js';
+import { extractErrorStatus } from '../utils/errorUtils.js';
 export function OxyServicesUserMixin(Base) {
     return class extends Base {
         constructor(...args) {
@@ -81,7 +84,23 @@ export function OxyServicesUserMixin(Base) {
                 });
                 return normalizeUserIdentityOrNull(result);
             }
-            catch {
+            catch (error) {
+                // 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;
             }
         }
@@ -94,7 +113,7 @@ export function OxyServicesUserMixin(Base) {
             return normalizeUserIdentity(await this.makeRequest('PUT', '/users/resolve', data));
         }
         /**
-         * 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
@@ -102,15 +121,67 @@ export function OxyServicesUserMixin(Base) {
          * 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) {
+            // 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 });
+                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('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 = {};
+                if (options?.excludeTypes?.length) {
+                    params.excludeTypes = options.excludeTypes.join(',');
+                }
+                if (options?.limit !== undefined) {
+                    params.limit = String(options.limit);
+                }
+                return await this.makeRequest('GET', '/profiles/recommendations', Object.keys(params).length > 0 ? params : undefined, { cache: true });
             }
             catch (error) {
+                // 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);
             }
         }
@@ -183,14 +254,7 @@ export function OxyServicesUserMixin(Base) {
             }
             catch (error) {
                 const errorMessage = error instanceof Error ? error.message : String(error);
-                const errorRecord = error && typeof error === 'object'
-                    ? error
-                    : 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 ||
                     errorMessage.includes('Authentication required') ||

package/dist/esm/utils/cacheKey.js

@@ -0,0 +1,82 @@
+/**
+ * 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';
+/**
+ * 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) {
+    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, actingAsUserId) {
+    let principal = ANON_IDENTITY;
+    if (accessToken) {
+        try {
+            const decoded = jwtDecode(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/dist/esm/utils/errorUtils.js

@@ -117,6 +117,30 @@ export function getErrorCodeFromStatus(status) {
             return ErrorCodes.INTERNAL_ERROR;
     }
 }
+/**
+ * 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) {
+    if (!error || typeof error !== 'object') {
+        return undefined;
+    }
+    const record = error;
+    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
  */