@oxy.so/core 7.18.0 → 7.19.0

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

package/src/server/OxyServer.ts

@@ -552,65 +552,47 @@ export class OxyServer extends OxyServices {
 
   // ── Server-side namespaces ───────────────────────────────────────────────
 
-  private _serverAccounts?: ServerAccountsApi;
-  private _serverAssets?: ServerAssetsApi;
-  private _serverNotifications?: ServerNotificationsApi;
-  private _serverLinkedAccounts?: ServerLinkedAccountsApi;
-  private _serverAgency?: ServerAgencyApi;
-  private _serverApps?: ServerAppsApi;
-  private _serverReputation?: ServerReputationApi;
-  private _serverSafety?: ServerSafetyApi;
-  private _serverSession?: ServerSessionApi;
-
   /** The account graph, plus the service-only `accessFor` membership verdict. */
   override get accounts(): ServerAccountsApi {
-    if (!this._serverAccounts) this._serverAccounts = new ServerAccountsApi(this.context);
-    return this._serverAccounts;
+    return this.namespace('accounts', (context) => new ServerAccountsApi(context));
   }
   /** Files, plus the service-only metadata and linked-URL lookups. */
   override get assets(): ServerAssetsApi {
-    if (!this._serverAssets) this._serverAssets = new ServerAssetsApi(this.context);
-    return this._serverAssets;
+    return this.namespace('assets', (context) => new ServerAssetsApi(context));
   }
   /** The inbox and push tokens, plus `create`. */
   override get notifications(): ServerNotificationsApi {
-    if (!this._serverNotifications)
-      this._serverNotifications = new ServerNotificationsApi(this.context);
-    return this._serverNotifications;
+    return this.namespace('notifications', (context) => new ServerNotificationsApi(context));
   }
   /** Linked external accounts, plus `forUser`. */
   override get linkedAccounts(): ServerLinkedAccountsApi {
-    if (!this._serverLinkedAccounts)
-      this._serverLinkedAccounts = new ServerLinkedAccountsApi(this.context);
-    return this._serverLinkedAccounts;
+    return this.namespace('linkedAccounts', (context) => new ServerLinkedAccountsApi(context));
   }
   /** Delegated capabilities, with the service-only authority calls. */
   override get agency(): ServerAgencyApi {
-    if (!this._serverAgency) this._serverAgency = new ServerAgencyApi(this.context);
-    return this._serverAgency;
+    return this.namespace('agency', (context) => new ServerAgencyApi(context));
   }
   /** Application management, plus the receiver-bound Alia machine-key lookup. */
   override get apps(): ServerAppsApi {
-    if (!this._serverApps) this._serverApps = new ServerAppsApi(this.context);
-    return this._serverApps;
+    return this.namespace('apps', (context) => new ServerAppsApi(context));
   }
   /** Reputation reads, plus `award`. */
   override get reputation(): ServerReputationApi {
-    if (!this._serverReputation) this._serverReputation = new ServerReputationApi(this.context);
-    return this._serverReputation;
+    return this.namespace('reputation', (context) => new ServerReputationApi(context));
   }
   /** Policy reads, plus the consumer-service decision lanes (ADR 0041). */
   override get safety(): ServerSafetyApi {
-    if (!this._serverSafety) this._serverSafety = new ServerSafetyApi(this.context);
-    return this._serverSafety;
+    return this.namespace('safety', (context) => new ServerSafetyApi(context));
   }
   /** Session state, plus validation through a reviewed supervised action. */
   override get session(): ServerSessionApi {
-    if (!this._serverSession)
-      this._serverSession = new ServerSessionApi(this.context, this.sessionValidationTtlMs, () =>
-        this.revocationFeedEpoch(),
-      );
-    return this._serverSession;
+    return this.namespace(
+      'session',
+      (context) =>
+        new ServerSessionApi(context, this.sessionValidationTtlMs, () =>
+          this.revocationFeedEpoch(),
+        ),
+    );
   }
 
   /** Close the revocation feed along with the HTTP client. */