@oxy.so/core 7.18.0 → 7.19.0

package/dist/cjs/HttpService.js

@@ -15,6 +15,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpService = void 0;
+exports.linkAbort = linkAbort;
 const cache_1 = require("./utils/cache");
 const requestUtils_1 = require("./utils/requestUtils");
 const asyncUtils_1 = require("./utils/asyncUtils");
@@ -301,6 +302,7 @@ function isAbortLike(error) {
         error !== null &&
         error.name === 'AbortError');
 }
+/** @internal Shared with `client/callOptions.ts`; see the note above `isAbortLike`. */
 function linkAbort(parent, child) {
     if (parent.aborted) {
         child.abort(parent.reason);

package/dist/cjs/OxyServices.errors.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OxyApiError = exports.OxyAuthenticationTimeoutError = exports.ServiceLinkedDownloadUrlError = exports.ServiceAssetMetadataError = exports.AssetUrlResolutionError = exports.OxyAuthenticationError = void 0;
+exports.retryAfterSecondsOf = retryAfterSecondsOf;
 exports.toOxyApiError = toOxyApiError;
 const errorUtils_1 = require("./utils/errorUtils");
 /**
@@ -146,6 +147,26 @@ class OxyApiError extends Error {
     }
 }
 exports.OxyApiError = OxyApiError;
+/**
+ * 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.
+ */
+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/cjs/OxyServices.js

@@ -28,6 +28,7 @@ const contentClaims_1 = require("./api/contentClaims");
  */
 const HttpService_1 = require("./HttpService");
 const OxyServices_errors_1 = require("./OxyServices.errors");
+const callOptions_1 = require("./client/callOptions");
 const session_1 = require("./api/session");
 const auth_1 = require("./api/auth");
 const users_1 = require("./api/users");
@@ -67,6 +68,9 @@ 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');
         }
@@ -169,151 +173,158 @@ 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) {
+        (0, callOptions_1.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) => (0, callOptions_1.sendWithCallOptions)(requestOptions, scope, (merged) => base.request(method, url, data, merged)),
+            service: lane && {
+                get available() {
+                    return lane.available;
+                },
+                request: (method, url, data, requestOptions) => (0, callOptions_1.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 session_1.SessionApi(this.context);
-        return this._session;
+        return this.namespace('session', (context) => new session_1.SessionApi(context));
     }
     /** Signing in, signing up, and the account's credentials. */
     get auth() {
-        if (!this._auth)
-            this._auth = new auth_1.AuthApi(this.context);
-        return this._auth;
+        return this.namespace('auth', (context) => new auth_1.AuthApi(context));
     }
     /** People and their profiles. */
     get users() {
-        if (!this._users)
-            this._users = new users_1.UsersApi(this.context);
-        return this._users;
+        return this.namespace('users', (context) => new users_1.UsersApi(context));
     }
     /** The follow graph: people and every other followable target. */
     get follows() {
-        if (!this._follows)
-            this._follows = new follows_1.FollowsApi(this.context);
-        return this._follows;
+        return this.namespace('follows', (context) => new follows_1.FollowsApi(context));
     }
     /** Privacy settings, blocks and restrictions. */
     get privacy() {
-        if (!this._privacy)
-            this._privacy = new privacy_1.PrivacyApi(this.context);
-        return this._privacy;
+        return this.namespace('privacy', (context) => new privacy_1.PrivacyApi(context));
     }
     /** The in-app inbox and push tokens. */
     get notifications() {
-        if (!this._notifications)
-            this._notifications = new notifications_1.NotificationsApi(this.context);
-        return this._notifications;
+        return this.namespace('notifications', (context) => new notifications_1.NotificationsApi(context));
     }
     /** Files: upload, link, URLs, content. */
     get assets() {
-        if (!this._assets)
-            this._assets = new assets_1.AssetsApi(this.context);
-        return this._assets;
+        return this.namespace('assets', (context) => new assets_1.AssetsApi(context));
     }
     /** DID, keys, identity links, domains, backup and the signed export. */
     get identity() {
-        if (!this._identity)
-            this._identity = new identity_1.IdentityApi(this.context);
-        return this._identity;
+        return this.namespace('identity', (context) => new identity_1.IdentityApi(context));
     }
     /** The account graph: accounts and their members. */
     get safety() {
-        if (!this._safety)
-            this._safety = new safety_1.SafetyApi(this.context);
-        return this._safety;
+        return this.namespace('safety', (context) => new safety_1.SafetyApi(context));
     }
     /** Content claims: an owner's counter-notice to a takedown (ADR 0043 D10). */
     get contentClaims() {
-        if (!this._contentClaims)
-            this._contentClaims = new contentClaims_1.ContentClaimsApi(this.context);
-        return this._contentClaims;
+        return this.namespace('contentClaims', (context) => new contentClaims_1.ContentClaimsApi(context));
     }
     get organizations() {
-        if (!this._organizations)
-            this._organizations = new organizations_1.OrganizationsApi(this.context);
-        return this._organizations;
+        return this.namespace('organizations', (context) => new organizations_1.OrganizationsApi(context));
     }
     get accounts() {
-        if (!this._accounts)
-            this._accounts = new accounts_1.AccountsApi(this.context);
-        return this._accounts;
+        return this.namespace('accounts', (context) => new accounts_1.AccountsApi(context));
     }
     /** Applications an account owns, and the ones this user granted access. */
     get apps() {
-        if (!this._apps)
-            this._apps = new apps_1.AppsApi(this.context);
-        return this._apps;
+        return this.namespace('apps', (context) => new apps_1.AppsApi(context));
     }
     /** External accounts (Mastodon, Bluesky) linked by OAuth. */
     get linkedAccounts() {
-        if (!this._linkedAccounts)
-            this._linkedAccounts = new linkedAccounts_1.LinkedAccountsApi(this.context);
-        return this._linkedAccounts;
+        return this.namespace('linkedAccounts', (context) => new linkedAccounts_1.LinkedAccountsApi(context));
     }
     /** Delegated capabilities for agents. */
     get agency() {
-        if (!this._agency)
-            this._agency = new agency_1.AgencyApi(this.context);
-        return this._agency;
+        return this.namespace('agency', (context) => new agency_1.AgencyApi(context));
     }
     /** The app store: storefront, reviews, and a publisher's listing. */
     get store() {
-        if (!this._store)
-            this._store = new store_1.StoreApi(this.context);
-        return this._store;
+        return this.namespace('store', (context) => new store_1.StoreApi(context));
     }
     /** Subscription, wallet and payments. */
     get billing() {
-        if (!this._billing)
-            this._billing = new billing_1.BillingApi(this.context);
-        return this._billing;
+        return this.namespace('billing', (context) => new billing_1.BillingApi(context));
     }
     /** Oxy Trust reputation (read-only for people; apps award it). */
     get reputation() {
-        if (!this._reputation)
-            this._reputation = new reputation_1.ReputationApi(this.context);
-        return this._reputation;
+        return this.namespace('reputation', (context) => new reputation_1.ReputationApi(context));
     }
     /** Oxy ID: cards, attestations, vouching, personhood, credentials. */
     get civic() {
-        if (!this._civic)
-            this._civic = new civic_1.CivicApi(this.context);
-        return this._civic;
+        return this.namespace('civic', (context) => new civic_1.CivicApi(context));
     }
     /** The user's personal data node. */
     get nodes() {
-        if (!this._nodes)
-            this._nodes = new nodes_1.NodesApi(this.context);
-        return this._nodes;
+        return this.namespace('nodes', (context) => new nodes_1.NodesApi(context));
     }
     /** This user's devices, their sessions, and device sign-in. */
     get devices() {
-        if (!this._devices)
-            this._devices = new devices_1.DevicesApi(this.context);
-        return this._devices;
+        return this.namespace('devices', (context) => new devices_1.DevicesApi(context));
     }
     get topics() {
-        if (!this._topics)
-            this._topics = new topics_1.TopicsApi(this.context);
-        return this._topics;
+        return this.namespace('topics', (context) => new topics_1.TopicsApi(context));
     }
     /** Per-app key/value data stored on the user's account. */
     get appData() {
-        if (!this._appData)
-            this._appData = new appData_1.AppDataApi(this.context);
-        return this._appData;
+        return this.namespace('appData', (context) => new appData_1.AppDataApi(context));
     }
     /** Oxy Console: first-run onboarding (terms and use cases) for the signed-in person. */
     get console() {
-        if (!this._console)
-            this._console = new console_1.ConsoleApi(this.context);
-        return this._console;
+        return this.namespace('console', (context) => new console_1.ConsoleApi(context));
     }
     get contacts() {
-        if (!this._contacts)
-            this._contacts = new contacts_1.ContactsApi(this.context);
-        return this._contacts;
+        return this.namespace('contacts', (context) => new contacts_1.ContactsApi(context));
     }
 }
 exports.OxyServices = OxyServices;

package/dist/cjs/client/callOptions.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertCallOptions = assertCallOptions;
+exports.applyCallOptions = applyCallOptions;
+exports.sendWithCallOptions = sendWithCallOptions;
+/**
+ * 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.
+ */
+const HttpService_1 = require("../HttpService");
+/** Throws for a budget the transport cannot honour (0, negative, NaN, Infinity). */
+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}).
+ */
+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.
+ */
+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 = (0, HttpService_1.linkAbort)(own, controller);
+    const unlinkScope = (0, HttpService_1.linkAbort)(scope.signal, controller);
+    merged.signal = controller.signal;
+    try {
+        return await send(merged);
+    }
+    finally {
+        unlinkOwn();
+        unlinkScope();
+    }
+}

package/dist/cjs/index.js

@@ -21,10 +21,10 @@
  * If a symbol does not appear here, it is NOT part of the public API.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FALLBACK_LOCALE = exports.SUPPORTED_LANGUAGES = exports.TopicSource = exports.TopicType = exports.SECURITY_EVENT_SEVERITY_MAP = exports.sessionsArraysEqual = exports.normalizeAndSortSessions = exports.mergeSessions = exports.authenticatedApiCall = exports.withAuthErrorHandling = exports.isAuthenticationError = exports.ensureValidToken = exports.AuthenticationFailedError = exports.SessionSyncRequiredError = exports.normalizeProfileLinks = exports.getNormalizedUserHandle = exports.getCanonicalUserHandle = exports.normalizeUserIdentityOrNull = exports.normalizeUserIdentity = exports.getNormalizedUserId = exports.commonsDeliveryPlatform = exports.pushTargetsFromDelivery = exports.selectCommonsDelivery = exports.parseCommonsApprovalExpiresAt = exports.getCommonsApprovalBlockingReason = exports.OxyAppDataIdentifierError = exports.AccountNotOnDeviceError = exports.REPUTATION_CACHE_PREFIX = exports.StoreInstallerError = exports.setStoreInstaller = exports.getStoreInstaller = exports.kindAcceptsAccountCategories = exports.isSelectableAccountCategoryId = exports.SELECTABLE_ACCOUNT_CATEGORY_IDS = exports.MAX_ACCOUNT_CATEGORIES = exports.ACCOUNT_CATEGORY_IDS = exports.buildUserDid = exports.DirectUploadInterruptedError = exports.MAX_UPLOAD_BYTES = exports.assetUrlCacheTTL = exports.ASSET_MULTIPART_UPLOAD_MAX_BYTES = exports.sameHolderIdentity = exports.ServiceAssetMetadataError = exports.AssetUrlResolutionError = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.OxyApiError = exports.OXY_CLOUD_URL = exports.OXY_API_URL = exports.OxyServices = void 0;
-exports.loadLocale = exports.translate = exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = exports.calculateBackoffInterval = exports.createCircuitBreakerState = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = exports.isRetryableError = exports.isNetworkError = exports.isServerError = exports.isRateLimitError = exports.isNotFoundError = exports.isForbiddenError = exports.isUnauthorizedError = exports.isAlreadyRegisteredError = exports.getErrorMessage = exports.getErrorStatus = exports.HttpStatus = exports.getSystemColorScheme = exports.systemPrefersDarkMode = exports.getOppositeTheme = exports.normalizeColorScheme = exports.normalizeTheme = exports.getContrastTextColor = exports.isLightColor = exports.withOpacity = exports.rgbToHex = exports.hexToRgb = exports.lightenColor = exports.darkenColor = exports.isWebBrowser = exports.isAndroid = exports.isIOS = exports.isNative = exports.isWeb = exports.setPlatformOS = exports.getPlatformOS = exports.coerceToSupportedLocale = exports.getPrimaryLanguage = exports.getUserLanguages = exports.isRTLLocale = exports.getNativeLanguageName = exports.getLanguageName = exports.getLanguageMetadata = exports.isSupportedLocale = exports.normalizeLocale = exports.getBaseLanguage = void 0;
-exports.normalizeInlineText = exports.validateAndSanitizeUserInput = exports.isValidObjectId = exports.sanitizeHTML = exports.sanitizeString = exports.isValidFileType = exports.isValidFileSize = exports.isValidDate = exports.isValidURL = exports.isValidUUID = exports.isValidObject = exports.isValidArray = exports.isRequiredBoolean = exports.isRequiredNumber = exports.isRequiredString = exports.DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE = exports.DISPLAY_NAME_ORPHANED_MARK_SOURCE = exports.DISPLAY_NAME_DISALLOWED_SOURCE = exports.DISPLAY_NAME_ALLOWED_SCRIPTS = exports.accountNameInvalidKey = exports.accountNameInvalidMessage = exports.accountNameMaxLength = exports.isValidAccountName = exports.isValidDisplayName = exports.isValidPassword = exports.isValidEmail = exports.ACCOUNT_TITLE_INVALID_MESSAGE = exports.DISPLAY_NAME_INVALID_MESSAGE = exports.MAX_DISPLAY_NAME_LENGTH = exports.PASSWORD_REGEX = exports.EMAIL_REGEX = exports.retryAsync = exports.validateRequiredFields = exports.parseHttpErrorBody = exports.isHttpRequestError = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.safeJsonParse = exports.buildPaginationParams = exports.buildUrl = exports.buildSearchParams = exports.buildQueryParams = exports.trustTierLabel = exports.reputationCategoryLabel = exports.accountRoleLabel = exports.accountCategoryLabel = exports.getLocalesVersion = exports.subscribeLocales = exports.isLocaleLoaded = void 0;
-exports.packageInfo = exports.consumeOAuthReturnPath = exports.persistOAuthReturnPath = exports.clearOAuthHandshake = exports.readOAuthHandshake = exports.persistOAuthHandshake = exports.canonicalizeOAuthRedirectUri = exports.normalizeOAuthRedirectUri = exports.OXY_OAUTH_RETURN_PATH_STORAGE_KEY = exports.OXY_OAUTH_REDIRECT_URI_STORAGE_KEY = exports.OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = exports.OXY_OAUTH_STATE_STORAGE_KEY = exports.OXY_AUTHORIZE_URL = exports.DEFAULT_OAUTH_SCOPE = exports.generatePkcePair = exports.generateOAuthState = exports.computeCodeChallenge = exports.buildOAuthAuthorizeUrl = exports.CENTRAL_IDP_APEX = exports.AUTH_WEB_ORIGIN = exports.getAccountColor = exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.isDev = exports.consoleSink = exports.resetLoggerConfig = exports.getLoggerConfig = exports.configureLogger = exports.createLogger = exports.logger = exports.normalizeMultilineText = void 0;
+exports.SUPPORTED_LANGUAGES = exports.TopicSource = exports.TopicType = exports.SECURITY_EVENT_SEVERITY_MAP = exports.sessionsArraysEqual = exports.normalizeAndSortSessions = exports.mergeSessions = exports.authenticatedApiCall = exports.withAuthErrorHandling = exports.isAuthenticationError = exports.ensureValidToken = exports.AuthenticationFailedError = exports.SessionSyncRequiredError = exports.normalizeProfileLinks = exports.getNormalizedUserHandle = exports.getCanonicalUserHandle = exports.normalizeUserIdentityOrNull = exports.normalizeUserIdentity = exports.getNormalizedUserId = exports.commonsDeliveryPlatform = exports.pushTargetsFromDelivery = exports.selectCommonsDelivery = exports.parseCommonsApprovalExpiresAt = exports.getCommonsApprovalBlockingReason = exports.OxyAppDataIdentifierError = exports.AccountNotOnDeviceError = exports.REPUTATION_CACHE_PREFIX = exports.StoreInstallerError = exports.setStoreInstaller = exports.getStoreInstaller = exports.kindAcceptsAccountCategories = exports.isSelectableAccountCategoryId = exports.SELECTABLE_ACCOUNT_CATEGORY_IDS = exports.MAX_ACCOUNT_CATEGORIES = exports.ACCOUNT_CATEGORY_IDS = exports.buildUserDid = exports.DirectUploadInterruptedError = exports.MAX_UPLOAD_BYTES = exports.assetUrlCacheTTL = exports.ASSET_MULTIPART_UPLOAD_MAX_BYTES = exports.sameHolderIdentity = exports.retryAfterSecondsOf = exports.ServiceAssetMetadataError = exports.AssetUrlResolutionError = exports.OxyAuthenticationTimeoutError = exports.OxyAuthenticationError = exports.OxyApiError = exports.OXY_CLOUD_URL = exports.OXY_API_URL = exports.OxyServices = void 0;
+exports.translate = exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = exports.calculateBackoffInterval = exports.createCircuitBreakerState = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = exports.isRetryableError = exports.isNetworkError = exports.isServerError = exports.isRateLimitError = exports.isNotFoundError = exports.isForbiddenError = exports.isUnauthorizedError = exports.isAlreadyRegisteredError = exports.getErrorMessage = exports.getErrorStatus = exports.HttpStatus = exports.getSystemColorScheme = exports.systemPrefersDarkMode = exports.getOppositeTheme = exports.normalizeColorScheme = exports.normalizeTheme = exports.getContrastTextColor = exports.isLightColor = exports.withOpacity = exports.rgbToHex = exports.hexToRgb = exports.lightenColor = exports.darkenColor = exports.isWebBrowser = exports.isAndroid = exports.isIOS = exports.isNative = exports.isWeb = exports.setPlatformOS = exports.getPlatformOS = exports.coerceToSupportedLocale = exports.getPrimaryLanguage = exports.getUserLanguages = exports.isRTLLocale = exports.getNativeLanguageName = exports.getLanguageName = exports.getLanguageMetadata = exports.isSupportedLocale = exports.normalizeLocale = exports.getBaseLanguage = exports.FALLBACK_LOCALE = void 0;
+exports.validateAndSanitizeUserInput = exports.isValidObjectId = exports.sanitizeHTML = exports.sanitizeString = exports.isValidFileType = exports.isValidFileSize = exports.isValidDate = exports.isValidURL = exports.isValidUUID = exports.isValidObject = exports.isValidArray = exports.isRequiredBoolean = exports.isRequiredNumber = exports.isRequiredString = exports.DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE = exports.DISPLAY_NAME_ORPHANED_MARK_SOURCE = exports.DISPLAY_NAME_DISALLOWED_SOURCE = exports.DISPLAY_NAME_ALLOWED_SCRIPTS = exports.accountNameInvalidKey = exports.accountNameInvalidMessage = exports.accountNameMaxLength = exports.isValidAccountName = exports.isValidDisplayName = exports.isValidPassword = exports.isValidEmail = exports.ACCOUNT_TITLE_INVALID_MESSAGE = exports.DISPLAY_NAME_INVALID_MESSAGE = exports.MAX_DISPLAY_NAME_LENGTH = exports.PASSWORD_REGEX = exports.EMAIL_REGEX = exports.retryAsync = exports.validateRequiredFields = exports.parseHttpErrorBody = exports.isHttpRequestError = exports.handleHttpError = exports.createApiError = exports.ErrorCodes = exports.safeJsonParse = exports.buildPaginationParams = exports.buildUrl = exports.buildSearchParams = exports.buildQueryParams = exports.trustTierLabel = exports.reputationCategoryLabel = exports.accountRoleLabel = exports.accountCategoryLabel = exports.getLocalesVersion = exports.subscribeLocales = exports.isLocaleLoaded = exports.loadLocale = void 0;
+exports.packageInfo = exports.consumeOAuthReturnPath = exports.persistOAuthReturnPath = exports.clearOAuthHandshake = exports.readOAuthHandshake = exports.persistOAuthHandshake = exports.canonicalizeOAuthRedirectUri = exports.normalizeOAuthRedirectUri = exports.OXY_OAUTH_RETURN_PATH_STORAGE_KEY = exports.OXY_OAUTH_REDIRECT_URI_STORAGE_KEY = exports.OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = exports.OXY_OAUTH_STATE_STORAGE_KEY = exports.OXY_AUTHORIZE_URL = exports.DEFAULT_OAUTH_SCOPE = exports.generatePkcePair = exports.generateOAuthState = exports.computeCodeChallenge = exports.buildOAuthAuthorizeUrl = exports.CENTRAL_IDP_APEX = exports.AUTH_WEB_ORIGIN = exports.getAccountColor = exports.formatPublicKeyHandle = exports.getAccountFallbackHandle = exports.getAccountDisplayName = exports.createQuickAccount = exports.buildAccountsArray = exports.updateAvatarVisibility = exports.isDev = exports.consoleSink = exports.resetLoggerConfig = exports.getLoggerConfig = exports.configureLogger = exports.createLogger = exports.logger = exports.normalizeMultilineText = exports.normalizeInlineText = void 0;
 // The crypto shim MUST stay the first import. The root itself ships no crypto
 // library (`__tests__/rootEntryGraph.test.ts`), but `@oxy.so/protocol`'s root
 // entry (reached by the OAuth/PKCE and device helpers) does, and Metro does not
@@ -44,6 +44,7 @@ Object.defineProperty(exports, "OxyAuthenticationError", { enumerable: true, get
 Object.defineProperty(exports, "OxyAuthenticationTimeoutError", { enumerable: true, get: function () { return OxyServices_errors_1.OxyAuthenticationTimeoutError; } });
 Object.defineProperty(exports, "AssetUrlResolutionError", { enumerable: true, get: function () { return OxyServices_errors_1.AssetUrlResolutionError; } });
 Object.defineProperty(exports, "ServiceAssetMetadataError", { enumerable: true, get: function () { return OxyServices_errors_1.ServiceAssetMetadataError; } });
+Object.defineProperty(exports, "retryAfterSecondsOf", { enumerable: true, get: function () { return OxyServices_errors_1.retryAfterSecondsOf; } });
 var holderEvidence_1 = require("./api/holderEvidence");
 Object.defineProperty(exports, "sameHolderIdentity", { enumerable: true, get: function () { return holderEvidence_1.sameHolderIdentity; } });
 var assets_1 = require("./api/assets");

package/dist/cjs/server/OxyServer.js

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

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;