@oxy.so/core 1.18.0 → 3.0.0

package/README.md

@@ -11,7 +11,7 @@ bun add @oxy.so/core
 ## Contents
 
 - **OxyServices API client** — all API methods for interacting with OxyHQ services
-- **Device-first session engine** — `SessionClient` (`src/session/`), `runSessionColdBoot`, and the device-session mixin that back `OxyProvider` in `@oxy.so/services`
+- **Device-first session engine** — `SessionClient` (`src/session/`), `runSessionColdBoot` and `oxy.devices.mintToken` (all in `@oxy.so/core/session` + the client), which back `OxyProvider` in `@oxy.so/services`
 - **OAuth helpers** — `generatePkcePair`, `generateOAuthState`, `buildOAuthAuthorizeUrl` for third-party "Sign in with Oxy" (see [docs/auth/integration-guide.md](../../docs/auth/integration-guide.md))
 - **Crypto** — KeyManager, SignatureService, RecoveryPhraseService
 - **Models and types** — User, ApiError, ClientSession, and more
@@ -27,19 +27,25 @@ bun add @oxy.so/core
 
 The package exposes two public entry points:
 
-- `@oxy.so/core` — main entry (API client, session, crypto, models, shared utilities, i18n, platform, device)
-- `@oxy.so/core/server` — Express-only helpers (`createOxyRateLimit`, `createOxyAuthMiddleware`, `requireOxyAuth`, `getOxyUserId`, `getRequiredOxyUserId`, `createOxyCors`, `createOxySecurityHeaders`, `buildOxyCspDirectives`, `safeFetch`, `verifySecret`, and request types)
+- `@oxy.so/core` — the `OxyServices` client and its namespaces, `OxyApiError`, models, shared utilities, i18n, platform helpers
+- `@oxy.so/core/session` — `SessionClient`, the account dialog controller, auth-state stores, cold boot
+- `@oxy.so/core/crypto` — `KeyManager`, `SignatureService`, `RecoveryPhraseService` and the primitives under them
+- `@oxy.so/core/civic`, `@oxy.so/core/inference`, `@oxy.so/core/logger`
+- `@oxy.so/core/server` — `OxyServer` (service tokens, `middleware.*`) and the Express helpers (`createOxyRateLimit`, `createOxyAuthMiddleware`, `requireOxyAuth`, `getOxyUserId`, `getRequiredOxyUserId`, `createOxyCors`, `createOxySecurityHeaders`, `buildOxyCspDirectives`, `safeFetch`, `verifySecret`, and request types)
 
-All client/runtime symbols (including `SessionClient`, `KeyManager`, `SignatureService`, `RecoveryPhraseService`, and the shared color / theme / error / network / debug helpers) are re-exported from the package root. Server-only Express helpers live under `@oxy.so/core/server` so React Native and browser bundles never import Express.
+Heavy pieces have their own entries so an app ships only what it uses; React Native and browser bundles never import Express. The full API map is [docs/api.mdx](./docs/api.mdx).
 
 ## Usage
 
 ```ts
-import { OxyServices, oxyClient, KeyManager } from '@oxy.so/core';
-import type { User, ApiError } from '@oxy.so/core';
+import { OxyServices } from '@oxy.so/core';
+import { KeyManager } from '@oxy.so/core/crypto';
+import type { User } from '@oxy.so/core';
+
+const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
 
 // Get user
-const user = await oxyClient.getUserById('123');
+const user: User = await oxy.users.get('123');
 
 // Crypto (KeyManager methods are static)
 const hasIdentity = await KeyManager.hasIdentity();

package/dist/cjs/HttpService.js

@@ -19,8 +19,8 @@ const cache_1 = require("./utils/cache");
 const requestUtils_1 = require("./utils/requestUtils");
 const asyncUtils_1 = require("./utils/asyncUtils");
 const errorUtils_1 = require("./utils/errorUtils");
-const jwt_decode_1 = require("jwt-decode");
-const protocol_1 = require("@oxy.so/protocol");
+const tokenClaims_1 = require("./utils/tokenClaims");
+const random_1 = require("@oxy.so/protocol/random");
 const cacheKey_1 = require("./utils/cacheKey");
 const redactUrl_1 = require("./utils/redactUrl");
 const OxyServices_errors_1 = require("./OxyServices.errors");
@@ -32,6 +32,26 @@ const activityId_1 = require("./utils/activityId");
  * endpoint surfaces as an `AbortError` quickly rather than blocking the
  * request queue.
  */
+/**
+ * Strip leading or trailing `/`s without a regex: `/\/+$/` backtracks
+ * polynomially on a long run of slashes (CodeQL js/polynomial-redos), and this
+ * runs on every request.
+ */
+function trimSlashes(value, side) {
+    let start = 0;
+    let end = value.length;
+    if (side === 'start')
+        while (start < end && value.charCodeAt(start) === 47)
+            start++;
+    else
+        while (end > start && value.charCodeAt(end - 1) === 47)
+            end--;
+    return value.slice(start, end);
+}
+/** Methods whose calls concurrent callers may share (read-only). */
+const SAFE_METHODS = new Set(['GET']);
+/** Methods safe to re-send after a transient failure (RFC 9110 §9.2.2). */
+const IDEMPOTENT_METHODS = new Set(['GET', 'PUT', 'DELETE']);
 const DEFAULT_REQUEST_TIMEOUT_MS = 5000;
 /**
  * Cooldown (ms) applied after a failed access-token refresh before another
@@ -97,18 +117,13 @@ const TOKEN_REFRESH_LEAD_SECONDS = 60;
  * lead window. `false` for an expired, opaque or no-`exp` token.
  */
 function isInsideRefreshLeadWindow(token) {
-    try {
-        const decoded = (0, jwt_decode_1.jwtDecode)(token);
-        if (typeof decoded.exp !== 'number') {
-            return false;
-        }
-        const now = Math.floor(Date.now() / 1000);
-        // `<=`: the proactive scheduler fires at exactly `exp - lead`.
-        return decoded.exp > now && decoded.exp - now <= TOKEN_REFRESH_LEAD_SECONDS;
-    }
-    catch {
+    const decoded = (0, tokenClaims_1.decodeTokenClaims)(token);
+    if (typeof decoded?.exp !== 'number') {
         return false;
     }
+    const now = Math.floor(Date.now() / 1000);
+    // `<=`: the proactive scheduler fires at exactly `exp - lead`.
+    return decoded.exp > now && decoded.exp - now <= TOKEN_REFRESH_LEAD_SECONDS;
 }
 /**
  * Soft ceiling on the number of live entries in the identity-scoped GET
@@ -236,6 +251,7 @@ class HttpService {
         this.noFresherTokenThan = null;
         this.authRefreshHandler = null;
         this.accessTokenProvider = null;
+        this.anonymousAuthProvider = null;
         this.deviceSecretMintInFlight = null;
         /**
          * Bumped by every {@link endSession}. A re-mint captures it before its first
@@ -378,7 +394,15 @@ class HttpService {
      * Main request method - handles everything in one place
      */
     async request(config) {
-        const { method, url, data, params, timeout = this.config.requestTimeout || DEFAULT_REQUEST_TIMEOUT_MS, signal, cache: cacheRequested = 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: cacheRequested = method === 'GET', cacheTTL, 
+        // Only reads are shared by default. A write's body can be opaque
+        // (`FormData`, `URLSearchParams` key as empty objects), so two different
+        // uploads used to collapse into one call and the second caller got the
+        // first file's result.
+        deduplicate = SAFE_METHODS.has(method), 
+        // Only idempotent methods are re-sent by default: re-sending a POST after a
+        // 5xx or a dropped connection can apply it twice.
+        retry = this.config.enableRetry !== false && IDEMPOTENT_METHODS.has(method), maxRetries = this.config.maxRetries || 3, } = config;
         // A per-instance disabled cache (`enableCache:false` / `cacheTTL<=0`)
         // overrides any per-request `cache:true`: nothing is read from nor written
         // to the response cache. Request deduplication below is unaffected.
@@ -408,7 +432,9 @@ class HttpService {
         // 401 retry re-enters request() with a fresh config, so it re-resolves
         // this here with the refreshed token.
         const authHeader = config.skipAuth ? null : await this.getAuthHeader();
-        const edgeRegionHeader = await (0, edgeRegion_1.getBrowserEdgeRegionHeader)();
+        // Never awaited: the PoP is a hint, and waiting on its trace fetch put up
+        // to a second in front of requests.
+        const edgeRegionHeader = (0, edgeRegion_1.peekBrowserEdgeRegionHeader)();
         const activityIdHeader = (0, activityId_1.getBrowserActivityIdHeader)();
         // A request the caller has ALREADY abandoned takes no queue slot and makes
         // no network call. Checked here, before enqueue, because a slot is the
@@ -417,40 +443,30 @@ class HttpService {
         if (signal?.aborted) {
             throw (0, errorUtils_1.createCancelledError)('Request cancelled before it was sent');
         }
-        // ONE abort domain for the whole call, linked to the caller's signal ONCE.
-        //
-        // The bug this replaces: the controller used to be built INSIDE `requestFn`
-        // — the function `retryAsync` re-invokes — and the caller's signal was
-        // linked to each new controller with a bare `addEventListener`. An `abort`
-        // event fires once, so on attempt 2 the caller's already-fired signal could
-        // not abort the freshly built controller, and the request the caller had
-        // cancelled went out for real. Hoisting the linkage means a cancellation
-        // arrives once and is then true for every attempt, including ones not yet
-        // started.
-        const callController = new AbortController();
-        const disposeCallerLink = signal ? linkAbort(signal, callController) : undefined;
-        /**
-         * Which of our own timers fired, so a timeout can be told apart from a
-         * cancellation. Both reach us from `fetch` as an indistinguishable
-         * `AbortError`, and collapsing them (as this used to) is what let the retry
-         * predicate treat an abandoned request as a transient failure.
-         */
-        let timedOut = false;
-        // Request function
-        const requestFn = async () => {
+        // One network attempt, inside the call's abort domain `domain`: the caller's
+        // own signal, or — when deduplicated — the shared work's, which aborts only
+        // once every caller waiting on it has cancelled.
+        const attempt = async (domain) => {
             const startTime = Date.now();
             // Re-checked per attempt so no retry can issue a network call after the
             // caller gave up — belt to `retryAsync`'s braces, and the one that holds
             // if a custom `shouldRetry` ever says yes to a cancellation.
-            if (callController.signal.aborted) {
+            if (domain.aborted) {
                 throw (0, errorUtils_1.createCancelledError)('Request cancelled');
             }
+            /**
+             * Whether OUR timer fired, so a timeout can be told apart from a
+             * cancellation. Both reach us from `fetch` as an indistinguishable
+             * `AbortError`, and collapsing them is what let the retry predicate treat
+             * an abandoned request as a transient failure.
+             */
+            let timedOut = false;
             // This attempt's controller carries its own timeout and inherits the
             // call-wide abort domain. Declared OUTSIDE the `try` so the `finally`
             // that releases them can see them — the timer and the listener are
             // exactly what leaked when they lived inside it.
             const controller = new AbortController();
-            const disposeCallLink = linkAbort(callController.signal, controller);
+            const disposeCallLink = linkAbort(domain, controller);
             const timeoutId = timeout
                 ? setTimeout(() => {
                     timedOut = true;
@@ -476,19 +492,19 @@ class HttpService {
                 }
                 // Add authorization header if available
                 if (authHeader) {
-                    headers['Authorization'] = authHeader;
+                    headers.Authorization = authHeader;
                 }
                 // Merge custom headers if provided
                 if (config.headers) {
-                    Object.entries(config.headers).forEach(([key, value]) => {
+                    for (const [key, value] of Object.entries(config.headers)) {
                         // For FormData, explicitly remove Content-Type if user tries to set it
                         // The browser/fetch API will set it automatically with the boundary
                         if (isFormData && key.toLowerCase() === 'content-type') {
                             this.logger.debug('Ignoring Content-Type header for FormData - will be set automatically');
-                            return;
+                            continue;
                         }
                         headers[key] = value;
-                    });
+                    }
                 }
                 // This is Cloudflare's coarse serving PoP (for example `mad`), never an
                 // IP or coordinate. Set it after caller headers so request code cannot
@@ -507,7 +523,7 @@ class HttpService {
                 // RN's native XMLHttpRequest handles those descriptors correctly, so we
                 // route multipart uploads through XHR on RN only. JSON, text, etc. still
                 // use fetch on every platform.
-                const useXhrForUpload = isFormData && (0, protocol_1.isReactNative)() && typeof XMLHttpRequest !== 'undefined';
+                const useXhrForUpload = isFormData && (0, random_1.isReactNative)() && typeof XMLHttpRequest !== 'undefined';
                 const response = useXhrForUpload
                     ? await this.uploadViaXHR(fullUrl, method, headers, bodyValue, controller.signal, timeout, this.shouldSendCredentials(fullUrl))
                     : await fetch(fullUrl, {
@@ -536,7 +552,12 @@ class HttpService {
                             // deduplicated retry would resolve to the still-pending original
                             // and await itself (deadlock). Opting the retry out of dedupe makes
                             // it a fresh request.
-                            return this.request({ ...config, _isAuthRetry: true, retry: false, deduplicate: false });
+                            //
+                            // `bypassQueue: true` is REQUIRED too: this attempt still holds its
+                            // queue slot, so a queued retry waits for a slot while holding one.
+                            // With every slot held by a 401 (a revoked session under load) no
+                            // retry could ever start and the whole client stalled.
+                            return this.request({ ...config, _isAuthRetry: true, retry: false, deduplicate: false, bypassQueue: true });
                         }
                         // Refresh failed or no token — clear tokens
                         this.tokenStore.clearTokens();
@@ -581,7 +602,7 @@ class HttpService {
                 if (config.responseType === 'blob') {
                     responseData = await response.blob();
                 }
-                else if (contentType && contentType.includes('application/json')) {
+                else if (contentType?.includes('application/json')) {
                     // Use response.json() directly for better performance
                     try {
                         responseData = await response.json();
@@ -664,47 +685,55 @@ class HttpService {
                 disposeCallLink();
             }
         };
-        // Wrap with retry if enabled.
+        // Composition: dedupe(retry(queue(attempt))). A queue slot is network
+        // occupancy only — each attempt takes one and releases it — so neither the
+        // retry backoff sleep nor a deduplicated caller waiting on shared work holds
+        // a slot while doing nothing.
         //
-        // `retryOnTimeout` defaults to false in `retryAsync`, which is what makes
-        // the pathological total unreachable: a timeout now costs ONE attempt
-        // instead of four-plus-backoff (~28s at the 5s default), and a cancellation
-        // costs none. `deadline` bounds whatever retries do happen by wall clock
-        // rather than by attempts x timeout + backoff.
-        const requestWithRetry = retry
-            ? () => (0, asyncUtils_1.retryAsync)(requestFn, {
+        // `retryOnTimeout` defaults to false in `retryAsync`: a timeout costs ONE
+        // attempt, a cancellation none. `deadline` bounds whatever retries do happen
+        // by wall clock rather than by attempts x timeout + backoff.
+        const runAttempt = (domain) => 
+        // Control-plane calls the auth lane depends on (`bypassQueue`, e.g. the
+        // device-secret mint) run DIRECTLY — a queued mint could never acquire a
+        // slot when every slot is parked awaiting it.
+        config.bypassQueue ? attempt(domain) : this.requestQueue.enqueue(() => attempt(domain), domain);
+        const execute = (domain) => retry
+            ? (0, asyncUtils_1.retryAsync)(() => runAttempt(domain), {
                 maxRetries,
                 baseDelay: this.config.retryDelay || 1000,
                 retryOnTimeout: config.retryOnTimeout ?? false,
                 deadline: config.deadline !== undefined ? Date.now() + config.deadline : undefined,
             })
-            : requestFn;
-        // Wrap with deduplication if enabled (use optimized key generation)
-        const dedupeKey = deduplicate ? this.generateCacheKey(method, url, data || params) : null;
-        const finalRequest = dedupeKey
-            ? () => this.deduplicator.deduplicate(dedupeKey, requestWithRetry, callController.signal)
-            : requestWithRetry;
-        try {
-            // Execute the request. Control-plane calls the auth lane depends on
-            // (`bypassQueue`, e.g. the device-secret mint) run DIRECTLY — a queued mint
-            // could never acquire a slot when every slot is parked awaiting it.
-            const result = config.bypassQueue
-                ? await finalRequest()
-                : await this.requestQueue.enqueue(finalRequest, callController.signal);
-            // Cache the result if caching is enabled
-            if (cache && cacheKey && result) {
-                this.cache.set(cacheKey, result, cacheTTL);
-                this.warnIfCacheOversized();
+            : runAttempt(domain);
+        let result;
+        if (deduplicate) {
+            // The cache key IS the dedupe key (same method, url, payload, identity);
+            // computed once per call.
+            const dedupeKey = cacheKey ?? this.generateCacheKey(method, url, data || params);
+            result = await this.deduplicator.deduplicate(dedupeKey, execute, signal);
+        }
+        else {
+            // The call's own abort domain, linked to the caller's signal ONCE, so a
+            // cancellation arrives once and is then true for every attempt, including
+            // ones not yet started. Released however the call ends: a caller signal
+            // that outlives the request (a React Query signal) would otherwise accrue
+            // one listener per request.
+            const callController = new AbortController();
+            const disposeCallerLink = signal ? linkAbort(signal, callController) : undefined;
+            try {
+                result = await execute(callController.signal);
+            }
+            finally {
+                disposeCallerLink?.();
             }
-            return result;
         }
-        finally {
-            // The call-wide link to the CALLER's signal, released once the call is
-            // over however it ended. Without this a caller signal that outlives the
-            // request — the normal case for a React Query query signal — accrues one
-            // listener per request for its whole lifetime.
-            disposeCallerLink?.();
+        // 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
@@ -891,16 +920,16 @@ class HttpService {
     buildURL(url, params) {
         const base = /^https?:\/\//i.test(url)
             ? url
-            : `${this.baseURL.replace(/\/+$/, '')}/${url.replace(/^\/+/, '')}`;
+            : `${trimSlashes(this.baseURL, 'end')}/${trimSlashes(url, 'start')}`;
         if (!params || Object.keys(params).length === 0) {
             return base;
         }
         const searchParams = new URLSearchParams();
-        Object.entries(params).forEach(([key, value]) => {
+        for (const [key, value] of Object.entries(params)) {
             if (value !== undefined && value !== null) {
                 searchParams.append(key, String(value));
             }
-        });
+        }
         const queryString = searchParams.toString();
         return queryString ? `${base}${base.includes('?') ? '&' : '?'}${queryString}` : base;
     }
@@ -921,10 +950,12 @@ class HttpService {
     async getAuthHeader() {
         const accessToken = this.syncAccessTokenFromProvider();
         if (!accessToken) {
-            return null;
+            return this.getAnonymousAuthHeader();
         }
         try {
-            const decoded = (0, jwt_decode_1.jwtDecode)(accessToken);
+            const decoded = (0, tokenClaims_1.decodeTokenClaims)(accessToken);
+            if (!decoded)
+                throw new Error('opaque token');
             const currentTime = Math.floor(Date.now() / 1000);
             // If the token expires within the refresh lead window, refresh it.
             if (decoded.exp && decoded.exp - currentTime < TOKEN_REFRESH_LEAD_SECONDS) {
@@ -950,6 +981,24 @@ class HttpService {
             return null;
         }
     }
+    /**
+     * The bearer for a request that has no user session behind it, from the
+     * {@link AnonymousAuthProvider} if one is installed. Never throws: a provider
+     * that fails sends the request anonymous, exactly as it went before any
+     * provider existed.
+     */
+    async getAnonymousAuthHeader() {
+        if (!this.anonymousAuthProvider)
+            return null;
+        try {
+            const token = await this.anonymousAuthProvider();
+            return token ? `Bearer ${token}` : null;
+        }
+        catch (error) {
+            this.logger.debug('Anonymous auth provider failed; sending the request anonymous:', error);
+            return null;
+        }
+    }
     async refreshAccessToken(reason) {
         if (!this.authRefreshHandler) {
             return null;
@@ -1052,26 +1101,22 @@ class HttpService {
         if (!token) {
             return false;
         }
-        try {
-            const decoded = (0, jwt_decode_1.jwtDecode)(token);
-            return typeof decoded.exp === 'number' && decoded.exp <= Math.floor(Date.now() / 1000);
-        }
-        catch {
-            return false;
-        }
+        const exp = (0, tokenClaims_1.decodeTokenClaims)(token)?.exp;
+        return typeof exp === 'number' && exp <= Math.floor(Date.now() / 1000);
     }
     /**
-     * PROCESS-WIDE single-flight for the rotating device-secret mint
+     * PROCESS-WIDE single-flight for the device-secret mint
      * (`POST /session/device/token`).
      *
-     * The server rotates the presented `deviceSecret` on every successful mint, so
-     * two concurrent mints would double-rotate and the durable store could end up
-     * holding a superseded secret → a later cold-boot mint 401s → the user is
-     * signed out. Every mint lane (the re-mint handler behind `refreshAccessToken`,
-     * the device-first cold boot, the socket token transport, the tab-focus
-     * reconcile) funnels its `refreshDeviceSecretArm` call through here, so
-     * concurrent callers await the SAME in-flight mint and all receive its result —
-     * exactly one server rotation.
+     * The server does not rotate the presented `deviceSecret` (it echoes it back
+     * as `nextDeviceSecret`; each holder of a shared DeviceSession has its own
+     * stable credential), so this is no longer what keeps the store's secret
+     * valid. It still collapses concurrent callers onto one request and one
+     * persisted write. Every mint lane (the re-mint handler behind
+     * `refreshAccessToken`, the device-first cold boot, the socket token
+     * transport, the tab-focus reconcile) funnels its `refreshDeviceSecretArm`
+     * call through here, so concurrent callers await the SAME in-flight mint and
+     * all receive its result.
      *
      * Distinct from {@link tokenRefreshPromise} (which dedups the FULL re-mint
      * handler incl. the native shared-key arm + the failure cooldown): this inner
@@ -1168,7 +1213,9 @@ class HttpService {
         // Authentication is owned by this SDK instance. A caller cannot replace
         // the bearer with a different session or leak one across linked apps.
         headers.set('Authorization', authHeader);
-        const edgeRegionHeader = await (0, edgeRegion_1.getBrowserEdgeRegionHeader)();
+        // Never awaited: the PoP is a hint, and waiting on its trace fetch put up
+        // to a second in front of requests.
+        const edgeRegionHeader = (0, edgeRegion_1.peekBrowserEdgeRegionHeader)();
         for (const [name, value] of Object.entries(edgeRegionHeader))
             headers.set(name, value);
         const activityIdHeader = (0, activityId_1.getBrowserActivityIdHeader)();
@@ -1258,6 +1305,16 @@ class HttpService {
     setAccessTokenProvider(provider) {
         this.accessTokenProvider = provider;
     }
+    /**
+     * Authenticate requests that carry no user session with the bearer this
+     * provider returns — in practice a backend's own service token (see
+     * `OxyConfig.serviceIdentity`). A user session always wins: the provider is
+     * consulted only when there is no access token, and never for `skipAuth`
+     * requests. `null` removes it.
+     */
+    setAnonymousAuthProvider(provider) {
+        this.anonymousAuthProvider = provider;
+    }
     clearTokens() {
         this.tokenStore.clearTokens();
         // Drop the response cache on logout. The cache is identity-scoped, so a
@@ -1334,13 +1391,7 @@ class HttpService {
      * identity-scoped variant `<key> id=*`.
      */
     clearCacheEntry(key) {
-        this.cache.delete(key);
-        const identityVariantPrefix = `${key}${HttpService.CACHE_IDENTITY_DELIM}`;
-        for (const existing of this.cache.keys()) {
-            if (existing.startsWith(identityVariantPrefix)) {
-                this.cache.delete(existing);
-            }
-        }
+        this.invalidateCache({ keys: [key] });
     }
     /**
      * Delete every cache entry whose key starts with `prefix`.
@@ -1351,14 +1402,40 @@ class HttpService {
      * deleted entries (for observability in tests).
      */
     clearCacheByPrefix(prefix) {
-        let removed = 0;
-        for (const key of this.cache.keys()) {
-            if (key.startsWith(prefix)) {
-                this.cache.delete(key);
-                removed++;
+        return this.invalidateCache({ prefixes: [prefix] });
+    }
+    /**
+     * Invalidate a set of LOGICAL keys (each with every identity-scoped variant,
+     * see `clearCacheEntry`) and key prefixes in ONE pass over the cache. A
+     * mutation touching many resources (a bulk follow) costs one scan, not one
+     * per resource.
+     * @returns Number of entries deleted
+     */
+    invalidateCache({ keys = [], prefixes = [] }) {
+        if (keys.length === 0 && prefixes.length === 0)
+            return 0;
+        const exact = new Set(keys);
+        const delim = HttpService.CACHE_IDENTITY_DELIM;
+        return this.cache.deleteWhere((stored) => {
+            const cut = stored.lastIndexOf(delim);
+            if (exact.has(cut === -1 ? stored : stored.slice(0, cut)))
+                return true;
+            for (const prefix of prefixes) {
+                if (stored.startsWith(prefix))
+                    return true;
             }
-        }
-        return removed;
+            return false;
+        });
+    }
+    /**
+     * Release this client: its response cache leaves the global cleanup sweep and
+     * is emptied, pending shared calls are forgotten, and the session ends.
+     */
+    dispose() {
+        (0, cache_1.unregisterCacheFromCleanup)(this.cache);
+        this.cache.clear();
+        this.deduplicator.clear();
+        this.endSession();
     }
     getCacheStats() {
         const cacheStats = this.cache.getStats();

package/dist/cjs/OxyServices.errors.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OxyAuthenticationTimeoutError = exports.ServiceLinkedDownloadUrlError = exports.ServiceAssetMetadataError = exports.AssetUrlResolutionError = exports.OxyAuthenticationError = void 0;
+exports.OxyApiError = exports.OxyAuthenticationTimeoutError = exports.ServiceLinkedDownloadUrlError = exports.ServiceAssetMetadataError = exports.AssetUrlResolutionError = exports.OxyAuthenticationError = void 0;
+exports.toOxyApiError = toOxyApiError;
+const errorUtils_1 = require("./utils/errorUtils");
 /**
  * Custom error types for better error handling
  */
@@ -120,3 +122,48 @@ class OxyAuthenticationTimeoutError extends OxyAuthenticationError {
     }
 }
 exports.OxyAuthenticationTimeoutError = OxyAuthenticationTimeoutError;
+/**
+ * The one error every `OxyServices` call rejects with.
+ *
+ * `status` is the HTTP status (0 when no response arrived: a network failure,
+ * a timeout or a cancellation), `code` the API's machine code when it sent one
+ * (else a transport code such as `TIMEOUT`, `NETWORK_ERROR`, `CANCELLED`), and
+ * `details` the API's structured detail. The original error is `cause`.
+ */
+class OxyApiError extends Error {
+    constructor(message, init) {
+        super(message);
+        this.name = 'OxyApiError';
+        this.status = init.status;
+        this.code = init.code;
+        this.details = init.details;
+        this.response = init.response;
+        this.cancelled = init.cancelled ?? false;
+        this.timeout = init.timeout ?? false;
+        if (init.cause !== undefined) {
+            this.cause = init.cause;
+        }
+    }
+}
+exports.OxyApiError = OxyApiError;
+/**
+ * Normalise anything a request rejected with into an `OxyApiError`. An error
+ * that already is one (or a typed SDK error such as `OxyAuthenticationError`)
+ * passes through unchanged.
+ */
+function toOxyApiError(error) {
+    if (error instanceof OxyApiError || error instanceof OxyAuthenticationError) {
+        return error;
+    }
+    const api = (0, errorUtils_1.handleHttpError)(error);
+    const source = (error && typeof error === 'object' ? error : {});
+    return new OxyApiError(api.message?.trim() || 'An unexpected error occurred', {
+        status: api.status,
+        code: api.code,
+        details: api.details,
+        response: source.response,
+        cancelled: source.cancelled === true,
+        timeout: source.timeout === true,
+        cause: error,
+    });
+}