@oxy.so/core 7.17.0 → 7.19.0

package/dist/types/server/namespaces.d.ts

@@ -6,8 +6,9 @@ import { type ExternalMcpDocumentProof, type ExternalMcpMediaProof } from './ext
  * `oxy.assets`.
  */
 import { type AgentAvailability, type FirstPartyTaskInput, type FirstPartyExecutionAuthorizationInput, type ForegroundExecutionAuthorizationInput, type ActorRef, type AppCapabilityCatalog, type AutonomyLevel, type CapabilityTicketClaims, type CapabilityTicketRequest, type GrantLimit, type PolicyDecision, type ResourceRef, type CreateOxyNotificationRequest, type AwardReputationInput, type ReputationTransaction, type ServiceLinkedAccountListResponse, type AccountAccessVerdict } from '@oxy.so/contracts';
+import { type CallOptions } from '../client/callOptions';
 import type { OxyContext } from '../client/context';
-import type { ApplicationFile, ApplicationFileAdoption, AssetLiveStatus, ApplicationFileImport, ApplicationFileImportBatchResult, ApplicationFilePage, ApplicationFileUpload, AudioRenditionOptions, CreatedRecordingTarget, FileImportOptions, FileImportState, FileVisibility, Notification, PlaySession, PlaySessionState, PlaySessionOptions, RecordingTarget, RecordingTargetOptions, ServiceAssetMetadata, ServiceAssetMetadataBySha, ServiceFileReference, ServiceFileReferenceResult, ServiceLinkedDownloadUrl, ServiceReferenceInventoryItem, ServiceReferenceReconcileResult, ServiceUserMediaFile, ServiceUserMediaImport } from '../models/interfaces';
+import type { ApplicationFile, ApplicationFileAdoption, AssetLiveStatus, ApplicationFileImport, ApplicationFileImportBatchResult, ApplicationFilePage, ApplicationFileUpload, AudioRenditionOptions, CreatedRecordingTarget, FileImportOptions, FileImportState, FileVisibility, Notification, PlaySession, PlaySessionState, PlaySessionOptions, RecordingTarget, RecordingTargetOptions, ServiceAssetMetadata, ServiceAssetMetadataBySha, ServiceFileReference, ServiceFileReferenceResult, ServiceLinkedDownloadUrl, ServiceReferenceInventoryItem, ServiceReferenceReconcileResult, ServiceUserMediaFile, ServiceUserMediaImport, ServiceMediaCacheUpload, ServiceFederatedMediaUpload, ServiceFederatedMediaDeletion } from '../models/interfaces';
 import { type RequesterProof } from './requesterContext';
 import { AssetsApi } from '../api/assets';
 import { type LargeServiceUploadOptions, type LargeServiceUploadResult, type LargeUploadSource } from './largeUpload';
@@ -21,20 +22,13 @@ import { type AliaMachineCredentialIntrospection } from './aliaMachineCredential
 import { type BatchLookup } from '../utils/batchLookup';
 /** The bytes of a streamed service upload: sent as the whole request body. */
 export type ServiceUploadBody = Uint8Array | ArrayBuffer | Blob;
-/** What `uploadAppFile` and `uploadUserMedia` may say about the bytes besides their type. */
 /**
- * Per-call transport options for a service call, overriding the server's
- * `requestTimeout` / `enableRetry` for that one call — so one `OxyServer` can
- * make a short, single-shot write and a patient read side by side.
+ * Per-call transport options for a service call — the {@link CallOptions}
+ * `withCallOptions` takes, accepted directly by the methods an outbox calls
+ * (`references.add` / `remove`).
  */
-export interface ServiceCallOptions {
-    /** Abort the call. */
-    signal?: AbortSignal;
-    /** Per-attempt timeout in ms. */
-    timeout?: number;
-    /** `false` sends the call once; a transient failure is the caller's to retry (an outbox). */
-    retry?: boolean;
-}
+export type ServiceCallOptions = CallOptions;
+/** What `uploadAppFile` and `uploadUserMedia` may say about the bytes besides their type. */
 export interface ServiceUploadDescription {
     /**
      * Stored as the file's original name. Sent as a header, so only printable
@@ -103,6 +97,49 @@ export declare class ServerAssetsApi extends AssetsApi {
             dryRun?: boolean;
         }) => Promise<ServiceReferenceReconcileResult>;
     };
+    /**
+     * 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.
+     */
+    readonly mediaCache: {
+        upload: (bytes: ServiceUploadBody, mime: string, options?: ServiceUploadDescription) => Promise<ServiceMediaCacheUpload>;
+        delete: (fileId: string) => Promise<void>;
+    };
+    /**
+     * 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}.
+     */
+    readonly federatedMedia: {
+        upload: (ownerUserId: string, bytes: ServiceUploadBody, mime: string, options?: ServiceUploadDescription) => Promise<ServiceFederatedMediaUpload>;
+        delete: (fileIds: string[]) => Promise<ServiceFederatedMediaDeletion[]>;
+    };
     /**
      * 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)

package/dist/types/server/requesterClient.d.ts

@@ -6,7 +6,6 @@ import { type RequesterProof } from './requesterContext';
 /** Oxy namespaces bound to one verified requester, without sharing mutable auth state. */
 export declare class OxyRequesterClient extends OxyServices {
     private readonly requesterLane;
-    private requesterAssets?;
     constructor(baseURL: string, cloudURL: string, original: ServiceLane, proof: RequesterProof);
     request<T>(method: HttpMethod, url: string, data?: unknown, options?: RequestOptions): Promise<ResponsePayload<T>>;
     get assets(): ServerAssetsApi;

package/dist/types/server/safeFetch.d.ts

@@ -150,6 +150,22 @@ export interface SafeFetchOptions {
      * destroyed.
      */
     signal?: AbortSignal;
+    /**
+     * The check of this very URL the caller already made with
+     * {@link assertSafePublicUrl} (to refuse a URL before it reaches a cache, a
+     * queue or a database, say): the first hop connects to the address it
+     * validated instead of resolving the name again. Only a check
+     * `assertSafePublicUrl` returned for exactly `rawUrl` is accepted; anything
+     * else is a programming error and throws a `TypeError` before any request.
+     * Every redirect hop is still resolved and checked afresh.
+     */
+    validated?: SsrfCheckOk;
+    /**
+     * Refuse ({@link SsrfRejection}) any hop that is not https — the first, and
+     * every redirect — so no request of the chain is sent in the clear. Without
+     * it, http and https are both allowed on every hop.
+     */
+    requireHttps?: boolean;
 }
 /**
  * The validated response returned by {@link safeFetch}: the first non-redirect

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.17.0",
+  "version": "7.19.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/HttpService.ts

@@ -514,7 +514,8 @@ function isAbortLike(error: unknown): boolean {
   );
 }
 
-function linkAbort(parent: AbortSignal, child: AbortController): () => void {
+/** @internal Shared with `client/callOptions.ts`; see the note above `isAbortLike`. */
+export function linkAbort(parent: AbortSignal, child: AbortController): () => void {
   if (parent.aborted) {
     child.abort((parent as AbortSignal & { reason?: unknown }).reason);
     return () => {

package/src/OxyServices.errors.ts

@@ -208,6 +208,25 @@ 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: unknown): number | undefined {
+  if (!error || typeof error !== 'object') return undefined;
+  const candidates = [
+    (error as { details?: { retryAfterSeconds?: unknown } }).details,
+    (error as { response?: { data?: { details?: { retryAfterSeconds?: unknown } } } }).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/src/OxyServices.ts

@@ -32,6 +32,7 @@ import {
 import type { OxyConfig as OxyConfigBase } from './models/interfaces';
 import { toOxyApiError } from './OxyServices.errors';
 import type { HttpMethod, OxyContext } from './client/context';
+import { assertCallOptions, type CallOptions, sendWithCallOptions } from './client/callOptions';
 import { SessionApi } from './api/session';
 import { AuthApi } from './api/auth';
 import { UsersApi } from './api/users';
@@ -79,6 +80,42 @@ export const OXY_CLOUD_URL = 'https://cloud.oxy.so';
 /** Default Oxy API URL. */
 export const OXY_API_URL = 'https://api.oxy.so';
 
+/**
+ * The namespaces a call scope ({@link OxyServices.withCallOptions}) carries:
+ * every one but `session`, which is the client's auth state rather than a call.
+ */
+export type OxyCallScopeNamespace =
+  | 'auth'
+  | 'users'
+  | 'follows'
+  | 'privacy'
+  | 'notifications'
+  | 'assets'
+  | 'identity'
+  | 'safety'
+  | 'contentClaims'
+  | 'organizations'
+  | 'accounts'
+  | 'apps'
+  | 'linkedAccounts'
+  | 'agency'
+  | 'store'
+  | 'billing'
+  | 'reputation'
+  | 'civic'
+  | 'nodes'
+  | 'devices'
+  | 'topics'
+  | 'appData'
+  | 'console'
+  | 'contacts';
+
+/**
+ * The namespaces of a client — an `OxyServer`'s server namespaces included —
+ * whose every request carries one set of {@link CallOptions}.
+ */
+export type OxyCallScope<T extends OxyServices = OxyServices> = Pick<T, OxyCallScopeNamespace>;
+
 export class OxyServices {
   /** The transport. Every namespace call goes through it. */
   readonly http: HttpService;
@@ -216,153 +253,170 @@ export class OxyServices {
 
   // ── Namespaces (created on first access) ─────────────────────────────────
 
-  private _session?: SessionApi;
-  private _auth?: AuthApi;
-  private _users?: UsersApi;
-  private _follows?: FollowsApi;
-  private _privacy?: PrivacyApi;
-  private _notifications?: NotificationsApi;
-  private _assets?: AssetsApi;
-  private _identity?: IdentityApi;
-  private _accounts?: AccountsApi;
-  private _organizations?: OrganizationsApi;
-  private _safety?: SafetyApi;
-  private _apps?: AppsApi;
-  private _linkedAccounts?: LinkedAccountsApi;
-  private _agency?: AgencyApi;
-  private _store?: StoreApi;
-  private _billing?: BillingApi;
-  private _reputation?: ReputationApi;
-  private _civic?: CivicApi;
-  private _nodes?: NodesApi;
-  private _devices?: DevicesApi;
-  private _topics?: TopicsApi;
-  private _appData?: AppDataApi;
-  private _contacts?: ContactsApi;
-  private _console?: ConsoleApi;
-  private _contentClaims?: ContentClaimsApi;
+  /** Each namespace, created on first access and kept for the client's life. */
+  private readonly namespaceInstances = new Map<string, unknown>();
+
+  /** The namespace `name`, created with this client's context on first access. */
+  protected namespace<T>(name: string, create: (context: OxyContext) => T): T {
+    let instance = this.namespaceInstances.get(name) as T | undefined;
+    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: CallOptions): OxyCallScope<this> {
+    assertCallOptions(options);
+    const scope: CallOptions = { ...options };
+    const base = this.context;
+    const lane = base.service;
+    const view = Object.create(this) as this;
+    const context: OxyContext = {
+      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<string, unknown>() },
+      session: { get: () => this.session },
+    });
+    return view;
+  }
 
   /** This client's auth state (token, user id) and its server session. */
   get session(): SessionApi {
-    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(): AuthApi {
-    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(): UsersApi {
-    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(): FollowsApi {
-    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(): PrivacyApi {
-    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(): NotificationsApi {
-    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(): AssetsApi {
-    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(): IdentityApi {
-    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(): SafetyApi {
-    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(): ContentClaimsApi {
-    if (!this._contentClaims) this._contentClaims = new ContentClaimsApi(this.context);
-    return this._contentClaims;
+    return this.namespace('contentClaims', (context) => new ContentClaimsApi(context));
   }
 
   get organizations(): OrganizationsApi {
-    if (!this._organizations) this._organizations = new OrganizationsApi(this.context);
-    return this._organizations;
+    return this.namespace('organizations', (context) => new OrganizationsApi(context));
   }
 
   get accounts(): AccountsApi {
-    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(): AppsApi {
-    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(): LinkedAccountsApi {
-    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(): AgencyApi {
-    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(): StoreApi {
-    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(): BillingApi {
-    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(): ReputationApi {
-    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(): CivicApi {
-    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(): NodesApi {
-    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(): DevicesApi {
-    if (!this._devices) this._devices = new DevicesApi(this.context);
-    return this._devices;
+    return this.namespace('devices', (context) => new DevicesApi(context));
   }
   get topics(): TopicsApi {
-    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(): AppDataApi {
-    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(): ConsoleApi {
-    if (!this._console) this._console = new ConsoleApi(this.context);
-    return this._console;
+    return this.namespace('console', (context) => new ConsoleApi(context));
   }
   get contacts(): ContactsApi {
-    if (!this._contacts) this._contacts = new ContactsApi(this.context);
-    return this._contacts;
+    return this.namespace('contacts', (context) => new ContactsApi(context));
   }
 }

package/src/client/callOptions.ts

@@ -0,0 +1,88 @@
+/**
+ * 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, type RequestOptions } from '../HttpService';
+
+/**
+ * Transport options for the calls made through `withCallOptions`, overriding
+ * the client's `requestTimeout` / `enableRetry` for those calls only.
+ */
+export interface CallOptions {
+  /** Abort the call. Combined with any signal the method passes itself. */
+  signal?: AbortSignal;
+  /** Per-attempt timeout in ms. Replaces the method's own default. */
+  timeout?: number;
+  /**
+   * Wall-clock budget in ms for the whole call, retries and backoff included
+   * (`RequestOptions.deadline`) — "never more than 2.5 s" in one number.
+   */
+  deadline?: number;
+  /**
+   * `false` sends each request once; a transient failure is the caller's to
+   * retry (an outbox). `true` allows the transport's retries where the client
+   * turned them off — but never on a request the method sends once on purpose
+   * (a non-idempotent write whose lost answer would duplicate it).
+   */
+  retry?: boolean;
+}
+
+/** Throws for a budget the transport cannot honour (0, negative, NaN, Infinity). */
+export function assertCallOptions(options: CallOptions): void {
+  for (const key of ['timeout', 'deadline'] as const) {
+    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<T extends RequestOptions>(
+  method: T | undefined,
+  scope: CallOptions,
+): T {
+  const merged = { ...method } as T;
+  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<T, O extends RequestOptions>(
+  method: O | undefined,
+  scope: CallOptions,
+  send: (options: O) => Promise<T>,
+): Promise<T> {
+  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/src/index.ts

@@ -31,13 +31,20 @@ import './crypto/polyfill';
 // API client
 // ---------------------------------------------------------------------------
 export { OxyServices, OXY_API_URL, OXY_CLOUD_URL } from './OxyServices';
-export type { OxyConfig, LinkedHttpClient } from './OxyServices';
+export type {
+  OxyConfig,
+  LinkedHttpClient,
+  OxyCallScope,
+  OxyCallScopeNamespace,
+} from './OxyServices';
+export type { CallOptions } from './client/callOptions';
 export {
   OxyApiError,
   OxyAuthenticationError,
   OxyAuthenticationTimeoutError,
   AssetUrlResolutionError,
   ServiceAssetMetadataError,
+  retryAfterSecondsOf,
 } from './OxyServices.errors';
 export type { HttpMethod } from './client/context';
 export type {
@@ -407,6 +414,10 @@ export type {
   ServiceReferenceInventoryItem,
   ServiceReferenceReconcileResult,
   ServiceUserMediaFile,
+  ServiceMediaCacheUpload,
+  ServiceFederatedMediaUpload,
+  ServiceFederatedMediaDeleteResult,
+  ServiceFederatedMediaDeletion,
   FileImportOutcome,
   FileImportSource,
   FileImportOptions,

package/src/models/interfaces.ts

@@ -1041,6 +1041,31 @@ export interface ServiceUserMediaFile {
   visibility: FileVisibility;
 }
 
+/** `POST /assets/service/cache`: the file now in the federation media cache. */
+export interface ServiceMediaCacheUpload {
+  file: { id: string };
+}
+
+/** `POST /assets/service/federation`: durable federated media, owned by the federated user. */
+export interface ServiceFederatedMediaUpload {
+  file: ServiceUserMediaFile;
+  /** The owner already held these bytes from this application: the existing file, maybe shared. */
+  deduplicated: boolean;
+}
+
+/**
+ * Oxy's answer for one id of `assets.federatedMedia.delete`: `deleted` (this
+ * call removed it), `not_found` (nothing to delete), `in_use` (kept: another
+ * account holds the same bytes) or `forbidden` (not federated media this
+ * application uploaded; left untouched).
+ */
+export type ServiceFederatedMediaDeleteResult = 'deleted' | 'not_found' | 'in_use' | 'forbidden';
+
+export interface ServiceFederatedMediaDeletion {
+  id: string;
+  result: ServiceFederatedMediaDeleteResult;
+}
+
 /**
  * How Oxy renders an AUDIO file it stores (ADR 0043 stage 4c). Every audio
  * file gets an audio-only HLS ladder (AAC 64k/128k/256k, a rung above the