@oxy.so/core 7.17.0 → 7.19.0

package/dist/cjs/server/namespaces.js

@@ -9,6 +9,7 @@ const externalMediaRequester_1 = require("./externalMediaRequester");
  * `oxy.assets`.
  */
 const contracts_1 = require("@oxy.so/contracts");
+const callOptions_1 = require("../client/callOptions");
 const requesterContext_1 = require("./requesterContext");
 const assets_1 = require("../api/assets");
 const largeUpload_1 = require("./largeUpload");
@@ -33,6 +34,14 @@ const SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE = 100;
 const SERVICE_LINKED_DOWNLOAD_URL_CHUNK_SIZE = 25;
 /** Server-side cap of `POST`/`DELETE /assets/service/references`. */
 const SERVICE_REFERENCES_CHUNK_SIZE = 100;
+/** Server-side cap of `POST /assets/service/federation/delete`. */
+const SERVICE_FEDERATED_DELETE_CHUNK_SIZE = 20;
+const FEDERATED_DELETE_RESULTS = new Set([
+    'deleted',
+    'not_found',
+    'in_use',
+    'forbidden',
+]);
 /** Server-side cap of `POST /assets/service/app/import/batch`. */
 const SERVICE_IMPORT_BATCH_SIZE = 50;
 /** An import fetches a remote source (up to 60 s server-side): a longer per-attempt timeout. */
@@ -61,14 +70,6 @@ const SERVICE_RECONCILE_RATE_LIMIT_MAX_WAIT_MS = 60000;
 const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/;
 /** A header value fetch accepts on every runtime: printable ASCII only. */
 const HEADER_SAFE_PATTERN = /^[\x20-\x7e]*$/;
-/** The `RequestOptions` half of {@link ServiceCallOptions}, only the fields that were set. */
-function serviceCallRequestOptions(options) {
-    return {
-        ...(options.signal ? { signal: options.signal } : {}),
-        ...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
-        ...(options.retry !== undefined ? { retry: options.retry } : {}),
-    };
-}
 /** The headers both streamed service uploads share. */
 function uploadHeaders(mime, description) {
     return {
@@ -185,6 +186,80 @@ class ServerAssetsApi extends assets_1.AssetsApi {
              */
             reconcile: (entityType, items, options = {}) => this.reconcileReferences(entityType, items, options),
         };
+        /**
+         * The federation media cache (`/assets/service/cache`): copies of remote
+         * media this application serves from Oxy's CDN instead of the remote host,
+         * in a reserved namespace that only holds what may be evicted. Every file
+         * is public by construction (`https://cloud.oxy.so/<id>`, `publicUrl`).
+         *
+         * - `upload` (`files:write`): the bytes as the whole body — a Blob from
+         *   `fs.openAsBlob(path)` streams a file from disk; image, video or audio
+         *   only (415), at most Oxy's cache size (413). Sent once.
+         * - `delete` (`federation:write`): evict one cache object. 404 when it is
+         *   gone, 403 for anything outside the cache namespace — a service token can
+         *   never delete media a person owns.
+         *
+         * A refusal for this application's media-write budget is a 429 whose
+         * `retryAfterSeconds` ({@link retryAfterSecondsOf}) says when to write again.
+         */
+        this.mediaCache = {
+            upload: (bytes, mime, options = {}) => lane(this.ctx).request('POST', '/assets/service/cache', bytes, {
+                headers: uploadHeaders(mime, options),
+                cache: false,
+                retry: false,
+                ...(options.signal ? { signal: options.signal } : {}),
+                ...(options.timeout ? { timeout: options.timeout } : {}),
+            }),
+            delete: async (fileId) => {
+                await lane(this.ctx).request('DELETE', `/assets/service/cache/${encodeURIComponent(fileId)}`, undefined, { cache: false });
+            },
+        };
+        /**
+         * Durable federated media (`/assets/service/federation`): a remote post's
+         * media re-hosted as a normal public file owned by the federated Oxy user
+         * it came from — outside the cache namespace, so a stored post may
+         * reference it for good.
+         *
+         * - `upload` (`files:write`): `ownerUserId` must be an existing federated
+         *   user (403). Idempotent per (owner, application, bytes): the existing
+         *   file with `deduplicated: true`, which other posts may share — check
+         *   your own references before deleting it. Bytes another owner or
+         *   application holds are a 409 `FEDERATED_MEDIA_OWNED_ELSEWHERE`. Sent once.
+         * - `delete` (`files:write` + `federation:write`): one answer per distinct
+         *   id, in order, sent 20 at a time — only federated media this application
+         *   uploaded is ever deleted (`forbidden` otherwise), and bytes another
+         *   account holds are kept (`in_use`). Every step is idempotent, so a failed
+         *   call is retried whole.
+         *
+         * Budget refusals are 429s, as for {@link mediaCache}.
+         */
+        this.federatedMedia = {
+            upload: async (ownerUserId, bytes, mime, options = {}) => {
+                const res = await lane(this.ctx).request('POST', '/assets/service/federation', bytes, {
+                    headers: { ...uploadHeaders(mime, options), 'x-owner-user-id': ownerUserId },
+                    cache: false,
+                    retry: false,
+                    ...(options.signal ? { signal: options.signal } : {}),
+                    ...(options.timeout ? { timeout: options.timeout } : {}),
+                });
+                return { file: res.file, deduplicated: res.deduplicated === true };
+            },
+            delete: async (fileIds) => {
+                const results = [];
+                for (const part of chunk(uniqueIds(fileIds), SERVICE_FEDERATED_DELETE_CHUNK_SIZE)) {
+                    const res = await lane(this.ctx).request('POST', '/assets/service/federation/delete', { ids: part }, { cache: false });
+                    const asked = new Set(part);
+                    for (const entry of Array.isArray(res?.results) ? res.results : []) {
+                        // An id not asked, or a result this build does not know, is no
+                        // answer: the caller sees the id unanswered and retries it.
+                        if (asked.has(entry?.id) && FEDERATED_DELETE_RESULTS.has(entry?.result)) {
+                            results.push({ id: entry.id, result: entry.result });
+                        }
+                    }
+                }
+                return results;
+            },
+        };
         /**
          * Per-play, revocable streaming access (ADR 0043 stage 4c). A play session
          * is ONE file's HLS ladder (a video's, or an audio file's audio-only one)
@@ -330,7 +405,7 @@ class ServerAssetsApi extends assets_1.AssetsApi {
             const chunk = references
                 .slice(start, start + SERVICE_REFERENCES_CHUNK_SIZE)
                 .map(({ fileId, entityType, entityId }) => ({ fileId, entityType, entityId }));
-            const res = await lane(this.ctx).request(method, '/assets/service/references', { references: chunk }, { ...serviceCallRequestOptions(options), cache: false });
+            const res = await (0, callOptions_1.sendWithCallOptions)({ cache: false }, options, (requestOptions) => lane(this.ctx).request(method, '/assets/service/references', { references: chunk }, requestOptions));
             results.push(...res.results);
         }
         return results;
@@ -1037,26 +1112,10 @@ async function waitingOutRateLimits(send) {
 }
 /** How long to wait after a refusal: what Oxy said, else the doubling fallback; capped. */
 function rateLimitWaitMs(error, refusals) {
-    const said = retryAfterSeconds(error);
+    const said = (0, OxyServices_errors_1.retryAfterSecondsOf)(error);
     const wait = said !== undefined ? said * 1000 : SERVICE_RECONCILE_RATE_LIMIT_FALLBACK_MS * 2 ** refusals;
     return Math.min(wait, SERVICE_RECONCILE_RATE_LIMIT_MAX_WAIT_MS);
 }
-/** `details.retryAfterSeconds` of a refusal (`RateLimitedError` on the server), if any. */
-function retryAfterSeconds(error) {
-    if (!error || typeof error !== 'object')
-        return undefined;
-    const candidates = [
-        error.details,
-        error.response
-            ?.data?.details,
-    ];
-    for (const details of candidates) {
-        const seconds = details?.retryAfterSeconds;
-        if (typeof seconds === 'number' && Number.isFinite(seconds) && seconds > 0)
-            return seconds;
-    }
-    return undefined;
-}
 async function waitForCommit(service, path, sessionId) {
     const deadline = Date.now() + SERVICE_RECONCILE_COMMIT_WAIT_MS;
     let interval = assetJobs_1.ASSET_JOB_POLL_INITIAL_MS;

package/dist/cjs/server/requesterClient.js

@@ -15,9 +15,7 @@ class OxyRequesterClient extends OxyServices_1.OxyServices {
         return this.requesterLane.request(method, url, data, options);
     }
     get assets() {
-        if (!this.requesterAssets)
-            this.requesterAssets = new namespaces_1.ServerAssetsApi(this.context);
-        return this.requesterAssets;
+        return this.namespace('assets', (context) => new namespaces_1.ServerAssetsApi(context));
     }
 }
 exports.OxyRequesterClient = OxyRequesterClient;

package/dist/cjs/server/safeFetch.js

@@ -138,6 +138,28 @@ const BLOCKED_IPV6_CIDRS = [
     ['2001:db8::', 32], // documentation
     ['64:ff9b::', 96], // NAT64 (maps to IPv4 — IPv4 denylist still applies after unwrap)
 ];
+/**
+ * Every successful check {@link assertSafePublicUrl} returned, and the exact
+ * URL it checked. `safeFetch({ validated })` accepts only these, for that URL:
+ * a hand-built `{ ok: true, ip }`, or a check of another URL, never pins a
+ * connection.
+ */
+const issuedChecks = new WeakMap();
+/** `rawUrl`'s normalized form, or `null` when it is not a URL. */
+function normalizedUrl(rawUrl) {
+    try {
+        return new node_url_1.URL(rawUrl).href;
+    }
+    catch {
+        return null;
+    }
+}
+/** A successful check of `href`, registered as one this module issued. */
+function issueCheck(href, ip, family) {
+    const check = { ok: true, ip, family };
+    issuedChecks.set(check, href);
+    return check;
+}
 /**
  * Return true if a literal IP address is private/loopback/link-local/reserved/
  * multicast/metadata and therefore must NOT be contacted.
@@ -219,7 +241,7 @@ async function assertSafePublicUrl(rawUrl, options = {}) {
         if (isBlockedIp(literalHost)) {
             return { ok: false, reason: 'literal ip in blocked range' };
         }
-        return { ok: true, ip: literalHost, family: literalFamily === 4 ? 4 : 6 };
+        return issueCheck(parsed.href, literalHost, literalFamily === 4 ? 4 : 6);
     }
     // Reject ambiguous numeric host forms BEFORE touching the resolver. `isIP`
     // returned 0 (not a canonical IP literal), yet the host is made entirely of
@@ -260,11 +282,7 @@ async function assertSafePublicUrl(rawUrl, options = {}) {
     }
     // All records are public. Pin the connection to the first one.
     const chosen = records[0];
-    return {
-        ok: true,
-        ip: chosen.address,
-        family: chosen.family === 4 ? 4 : 6,
-    };
+    return issueCheck(parsed.href, chosen.address, chosen.family === 4 ? 4 : 6);
 }
 /** What a refusal of a first-party Oxy host adds to its reason. */
 const FIRST_PARTY_HOST_HINT = 'first-party Oxy host: inside the VPC it resolves to a private address, which safeFetch refuses by design; call it through OxyServer (its namespaces, serviceRequest, or createServiceClient().fetch), not safeFetch';
@@ -356,7 +374,13 @@ function fetchOnce(options, isHttps, headersTimeoutMs, body) {
  * @throws {UpstreamError} on redirect-loop / malformed-redirect / timeout.
  */
 async function safeFetch(rawUrl, options = {}) {
-    const { method = 'GET', headers: callerHeaders, body, maxRedirects = exports.MAX_REDIRECTS, redirect = 'follow', headersTimeoutMs = exports.UPSTREAM_HEADERS_TIMEOUT_MS, signal, } = options;
+    const { method = 'GET', headers: callerHeaders, body, maxRedirects = exports.MAX_REDIRECTS, redirect = 'follow', headersTimeoutMs = exports.UPSTREAM_HEADERS_TIMEOUT_MS, signal, validated, requireHttps = false, } = options;
+    if (validated !== undefined) {
+        const checked = issuedChecks.get(validated);
+        if (checked === undefined || checked !== normalizedUrl(rawUrl)) {
+            throw new TypeError('safeFetch: `validated` must be the check assertSafePublicUrl returned for this exact URL');
+        }
+    }
     // Normalize a case-insensitive header map and ensure a User-Agent default.
     const baseHeaders = {};
     if (callerHeaders) {
@@ -373,11 +397,18 @@ async function safeFetch(rawUrl, options = {}) {
         if (signal?.aborted) {
             throw new UpstreamError('request aborted');
         }
-        // The lookup shares the headers deadline and the caller's signal.
-        const guard = await assertSafePublicUrl(currentUrl, {
-            lookupTimeoutMs: headersTimeoutMs,
-            signal,
-        });
+        if (requireHttps && !normalizedUrl(currentUrl)?.startsWith('https:')) {
+            throw new SsrfRejection(hop === 0 ? 'https required' : 'https required: redirect to a non-https url');
+        }
+        // Hop 0 may reuse the caller's check of this exact URL; a redirect hop
+        // targets a new URL and is always checked here. The lookup shares the
+        // headers deadline and the caller's signal.
+        const guard = hop === 0 && validated
+            ? validated
+            : await assertSafePublicUrl(currentUrl, {
+                lookupTimeoutMs: headersTimeoutMs,
+                signal,
+            });
         if (!guard.ok) {
             throw guard.incomplete
                 ? new UpstreamError(guard.reason)

package/dist/esm/HttpService.js

@@ -298,7 +298,8 @@ function isAbortLike(error) {
         error !== null &&
         error.name === 'AbortError');
 }
-function linkAbort(parent, child) {
+/** @internal Shared with `client/callOptions.ts`; see the note above `isAbortLike`. */
+export function linkAbort(parent, child) {
     if (parent.aborted) {
         child.abort(parent.reason);
         return () => {

package/dist/esm/OxyServices.errors.js

@@ -136,6 +136,26 @@ export class OxyApiError extends Error {
         }
     }
 }
+/**
+ * How long Oxy asked the caller to wait before trying again, in seconds — the
+ * `Retry-After` of a 429 (`details.retryAfterSeconds` of its body) — or
+ * `undefined` when the error is no such refusal or names no wait.
+ */
+export function retryAfterSecondsOf(error) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const candidates = [
+        error.details,
+        error.response
+            ?.data?.details,
+    ];
+    for (const details of candidates) {
+        const seconds = details?.retryAfterSeconds;
+        if (typeof seconds === 'number' && Number.isFinite(seconds) && seconds > 0)
+            return seconds;
+    }
+    return undefined;
+}
 /**
  * Normalise anything a request rejected with into an `OxyApiError`. An error
  * that already is one (or a typed SDK error such as `OxyAuthenticationError`)

package/dist/esm/OxyServices.js

@@ -25,6 +25,7 @@ import { ContentClaimsApi } from './api/contentClaims.js';
  */
 import { HttpService, } from './HttpService.js';
 import { toOxyApiError } from './OxyServices.errors.js';
+import { assertCallOptions, sendWithCallOptions } from './client/callOptions.js';
 import { SessionApi } from './api/session.js';
 import { AuthApi } from './api/auth.js';
 import { UsersApi } from './api/users.js';
@@ -64,6 +65,9 @@ export class OxyServices {
             deletePrefix: (prefix) => this.http.clearCacheByPrefix(prefix),
             stats: () => this.http.getCacheStats(),
         };
+        // ── Namespaces (created on first access) ─────────────────────────────────
+        /** Each namespace, created on first access and kept for the client's life. */
+        this.namespaceInstances = new Map();
         if (!config || typeof config !== 'object') {
             throw new Error('OxyConfig is required');
         }
@@ -166,150 +170,157 @@ export class OxyServices {
     dispose() {
         this.http.dispose();
     }
+    /** The namespace `name`, created with this client's context on first access. */
+    namespace(name, create) {
+        let instance = this.namespaceInstances.get(name);
+        if (instance === undefined) {
+            instance = create(this.context);
+            this.namespaceInstances.set(name, instance);
+        }
+        return instance;
+    }
+    /**
+     * This client's namespaces with per-call transport options: every request
+     * made through them carries `options`, on top of what each method sets.
+     *
+     * ```ts
+     * // One slow write, one tight read — one client.
+     * await oxy.withCallOptions({ timeout: 60_000 }).assets.setVisibility(id, 'public');
+     * const page = await oxy.withCallOptions({ deadline: 2_500 }).users.byUsername(name);
+     * // A server's own namespaces too:
+     * await server.withCallOptions({ retry: false }).assets.references.add(refs);
+     * ```
+     *
+     * - `timeout` / `deadline` replace the method's own and the client's.
+     * - `retry: false` sends each request once; `retry: true` never re-enables
+     *   a request the method sends once on purpose.
+     * - `signal` aborts the call; a method's own signal still applies too.
+     *
+     * The scope is a view, not a client: it shares this client's session,
+     * cache, credentials and service lane, holds no resource and needs no
+     * disposal. A namespace one call makes into another (`privacy` reading
+     * `users.me()`) keeps the options. `session` is not part of it.
+     */
+    withCallOptions(options) {
+        assertCallOptions(options);
+        const scope = { ...options };
+        const base = this.context;
+        const lane = base.service;
+        const view = Object.create(this);
+        const context = {
+            oxy: view,
+            http: base.http,
+            request: (method, url, data, requestOptions) => sendWithCallOptions(requestOptions, scope, (merged) => base.request(method, url, data, merged)),
+            service: lane && {
+                get available() {
+                    return lane.available;
+                },
+                request: (method, url, data, requestOptions) => sendWithCallOptions(requestOptions, scope, (merged) => lane.request(method, url, data, merged)),
+            },
+        };
+        // The view's own namespaces are built on the scoped context; everything
+        // else (http, cache, config, credentials) is this client's, by prototype.
+        Object.defineProperties(view, {
+            context: { value: context },
+            namespaceInstances: { value: new Map() },
+            session: { get: () => this.session },
+        });
+        return view;
+    }
     /** This client's auth state (token, user id) and its server session. */
     get session() {
-        if (!this._session)
-            this._session = new SessionApi(this.context);
-        return this._session;
+        return this.namespace('session', (context) => new SessionApi(context));
     }
     /** Signing in, signing up, and the account's credentials. */
     get auth() {
-        if (!this._auth)
-            this._auth = new AuthApi(this.context);
-        return this._auth;
+        return this.namespace('auth', (context) => new AuthApi(context));
     }
     /** People and their profiles. */
     get users() {
-        if (!this._users)
-            this._users = new UsersApi(this.context);
-        return this._users;
+        return this.namespace('users', (context) => new UsersApi(context));
     }
     /** The follow graph: people and every other followable target. */
     get follows() {
-        if (!this._follows)
-            this._follows = new FollowsApi(this.context);
-        return this._follows;
+        return this.namespace('follows', (context) => new FollowsApi(context));
     }
     /** Privacy settings, blocks and restrictions. */
     get privacy() {
-        if (!this._privacy)
-            this._privacy = new PrivacyApi(this.context);
-        return this._privacy;
+        return this.namespace('privacy', (context) => new PrivacyApi(context));
     }
     /** The in-app inbox and push tokens. */
     get notifications() {
-        if (!this._notifications)
-            this._notifications = new NotificationsApi(this.context);
-        return this._notifications;
+        return this.namespace('notifications', (context) => new NotificationsApi(context));
     }
     /** Files: upload, link, URLs, content. */
     get assets() {
-        if (!this._assets)
-            this._assets = new AssetsApi(this.context);
-        return this._assets;
+        return this.namespace('assets', (context) => new AssetsApi(context));
     }
     /** DID, keys, identity links, domains, backup and the signed export. */
     get identity() {
-        if (!this._identity)
-            this._identity = new IdentityApi(this.context);
-        return this._identity;
+        return this.namespace('identity', (context) => new IdentityApi(context));
     }
     /** The account graph: accounts and their members. */
     get safety() {
-        if (!this._safety)
-            this._safety = new SafetyApi(this.context);
-        return this._safety;
+        return this.namespace('safety', (context) => new SafetyApi(context));
     }
     /** Content claims: an owner's counter-notice to a takedown (ADR 0043 D10). */
     get contentClaims() {
-        if (!this._contentClaims)
-            this._contentClaims = new ContentClaimsApi(this.context);
-        return this._contentClaims;
+        return this.namespace('contentClaims', (context) => new ContentClaimsApi(context));
     }
     get organizations() {
-        if (!this._organizations)
-            this._organizations = new OrganizationsApi(this.context);
-        return this._organizations;
+        return this.namespace('organizations', (context) => new OrganizationsApi(context));
     }
     get accounts() {
-        if (!this._accounts)
-            this._accounts = new AccountsApi(this.context);
-        return this._accounts;
+        return this.namespace('accounts', (context) => new AccountsApi(context));
     }
     /** Applications an account owns, and the ones this user granted access. */
     get apps() {
-        if (!this._apps)
-            this._apps = new AppsApi(this.context);
-        return this._apps;
+        return this.namespace('apps', (context) => new AppsApi(context));
     }
     /** External accounts (Mastodon, Bluesky) linked by OAuth. */
     get linkedAccounts() {
-        if (!this._linkedAccounts)
-            this._linkedAccounts = new LinkedAccountsApi(this.context);
-        return this._linkedAccounts;
+        return this.namespace('linkedAccounts', (context) => new LinkedAccountsApi(context));
     }
     /** Delegated capabilities for agents. */
     get agency() {
-        if (!this._agency)
-            this._agency = new AgencyApi(this.context);
-        return this._agency;
+        return this.namespace('agency', (context) => new AgencyApi(context));
     }
     /** The app store: storefront, reviews, and a publisher's listing. */
     get store() {
-        if (!this._store)
-            this._store = new StoreApi(this.context);
-        return this._store;
+        return this.namespace('store', (context) => new StoreApi(context));
     }
     /** Subscription, wallet and payments. */
     get billing() {
-        if (!this._billing)
-            this._billing = new BillingApi(this.context);
-        return this._billing;
+        return this.namespace('billing', (context) => new BillingApi(context));
     }
     /** Oxy Trust reputation (read-only for people; apps award it). */
     get reputation() {
-        if (!this._reputation)
-            this._reputation = new ReputationApi(this.context);
-        return this._reputation;
+        return this.namespace('reputation', (context) => new ReputationApi(context));
     }
     /** Oxy ID: cards, attestations, vouching, personhood, credentials. */
     get civic() {
-        if (!this._civic)
-            this._civic = new CivicApi(this.context);
-        return this._civic;
+        return this.namespace('civic', (context) => new CivicApi(context));
     }
     /** The user's personal data node. */
     get nodes() {
-        if (!this._nodes)
-            this._nodes = new NodesApi(this.context);
-        return this._nodes;
+        return this.namespace('nodes', (context) => new NodesApi(context));
     }
     /** This user's devices, their sessions, and device sign-in. */
     get devices() {
-        if (!this._devices)
-            this._devices = new DevicesApi(this.context);
-        return this._devices;
+        return this.namespace('devices', (context) => new DevicesApi(context));
     }
     get topics() {
-        if (!this._topics)
-            this._topics = new TopicsApi(this.context);
-        return this._topics;
+        return this.namespace('topics', (context) => new TopicsApi(context));
     }
     /** Per-app key/value data stored on the user's account. */
     get appData() {
-        if (!this._appData)
-            this._appData = new AppDataApi(this.context);
-        return this._appData;
+        return this.namespace('appData', (context) => new AppDataApi(context));
     }
     /** Oxy Console: first-run onboarding (terms and use cases) for the signed-in person. */
     get console() {
-        if (!this._console)
-            this._console = new ConsoleApi(this.context);
-        return this._console;
+        return this.namespace('console', (context) => new ConsoleApi(context));
     }
     get contacts() {
-        if (!this._contacts)
-            this._contacts = new ContactsApi(this.context);
-        return this._contacts;
+        return this.namespace('contacts', (context) => new ContactsApi(context));
     }
 }

package/dist/esm/client/callOptions.js

@@ -0,0 +1,61 @@
+/**
+ * Per-call transport options, for any namespace call.
+ *
+ * `oxy.withCallOptions({ timeout: 60_000 }).assets.setVisibility(id, 'public')`
+ * sends that one call with its own budget, without a second client and without
+ * every method growing an options parameter of its own. The scope is a view of
+ * the same client: same session, cache, service lane and namespaces' state.
+ */
+import { linkAbort } from '../HttpService.js';
+/** Throws for a budget the transport cannot honour (0, negative, NaN, Infinity). */
+export function assertCallOptions(options) {
+    for (const key of ['timeout', 'deadline']) {
+        const value = options[key];
+        if (value !== undefined && (!Number.isFinite(value) || value <= 0)) {
+            throw new RangeError(`${key} must be a positive number of milliseconds`);
+        }
+    }
+}
+/**
+ * The request options a method chose, with the scope's applied on top. The
+ * signal is NOT merged here: two signals need a linked controller that lives
+ * exactly as long as the request ({@link sendWithCallOptions}).
+ */
+export function applyCallOptions(method, scope) {
+    const merged = { ...method };
+    if (scope.timeout !== undefined)
+        merged.timeout = scope.timeout;
+    if (scope.deadline !== undefined)
+        merged.deadline = scope.deadline;
+    if (scope.retry === false)
+        merged.retry = false;
+    else if (scope.retry === true && merged.retry === undefined)
+        merged.retry = true;
+    return merged;
+}
+/**
+ * Send one request with the scope applied: `send` receives the merged
+ * options, with a signal that aborts when either the method's or the scope's
+ * does. The link between them is released when the request settles.
+ */
+export async function sendWithCallOptions(method, scope, send) {
+    const merged = applyCallOptions(method, scope);
+    const own = method?.signal;
+    if (!scope.signal || !own || own === scope.signal) {
+        const signal = scope.signal ?? own;
+        if (signal)
+            merged.signal = signal;
+        return send(merged);
+    }
+    const controller = new AbortController();
+    const unlinkOwn = linkAbort(own, controller);
+    const unlinkScope = linkAbort(scope.signal, controller);
+    merged.signal = controller.signal;
+    try {
+        return await send(merged);
+    }
+    finally {
+        unlinkOwn();
+        unlinkScope();
+    }
+}

package/dist/esm/index.js

@@ -29,7 +29,7 @@ import './crypto/polyfill.js';
 // API client
 // ---------------------------------------------------------------------------
 export { OxyServices, OXY_API_URL, OXY_CLOUD_URL } from './OxyServices.js';
-export { OxyApiError, OxyAuthenticationError, OxyAuthenticationTimeoutError, AssetUrlResolutionError, ServiceAssetMetadataError, } from './OxyServices.errors.js';
+export { OxyApiError, OxyAuthenticationError, OxyAuthenticationTimeoutError, AssetUrlResolutionError, ServiceAssetMetadataError, retryAfterSecondsOf, } from './OxyServices.errors.js';
 export { sameHolderIdentity } from './api/holderEvidence.js';
 export { ASSET_MULTIPART_UPLOAD_MAX_BYTES, assetUrlCacheTTL, MAX_UPLOAD_BYTES } from './api/assets.js';
 export { DirectUploadInterruptedError } from './api/directUpload.js';