@oxyhq/core 21.0.0 → 21.0.2

package/dist/cjs/HttpService.js

@@ -965,19 +965,46 @@ class HttpService {
         return this.deviceSecretMintInFlight;
     }
     /**
-     * Unwrap standardized API response format
+     * Unwrap the standardized API response envelope — EXCEPT when the envelope is
+     * a page, in which case it travels whole.
+     *
+     * `{ data: <payload> }` is the house success envelope (`sendSuccess`), and
+     * reducing it to `<payload>` is what every call site in the SDK expects. But
+     * the reduction DISCARDS every sibling key, silently, and a page's siblings
+     * are the only thing that says where the next page starts. That is how
+     * `GET /accounts/:id/audit` lost its `nextCursor`: the caller received a bare
+     * array, `getNextPageParam` read `undefined`, and pagination was dead past the
+     * first page with nothing to show that it was.
+     *
+     * ## Why the rule is narrow, and not "any sibling key survives"
+     *
+     * "An object carrying `data` plus anything else is not an envelope" is the
+     * tempting general rule, and it is wrong here: this API already answers
+     * `{ data, count }` on ~15 routes, plus `{ data, source }`, `{ data, reason }`
+     * and `{ data, secretDestroyed }`, and a dozen measured Console call sites
+     * type those as the bare payload (`Array<ProviderConnection>`,
+     * `AccountBillingState | null`, …). Preserving those envelopes would hand every
+     * one of them an object where it expects its payload — at runtime only, since
+     * the response type is a call-site assertion. So the rule names PAGINATION
+     * specifically: `data` beside {@link PAGE_ENVELOPE_KEYS} is a page.
+     *
+     * A route whose sibling key genuinely matters to its caller belongs in that
+     * list, or should not be a sibling of `data` at all — the cursor-paginated
+     * surfaces already in the SDK (`{ follows, nextCursor }`,
+     * `{ records, nextCursor }`) sidestep this by never using `data`.
      */
     unwrapResponse(responseData) {
-        // Handle paginated responses: { data: [...], pagination: {...} }
-        if (responseData && typeof responseData === 'object' && 'data' in responseData && 'pagination' in responseData) {
+        if (!responseData || typeof responseData !== 'object' || !('data' in responseData)) {
+            // Not the success envelope (or not an object at all) — as-is.
             return responseData;
         }
-        // Handle regular success responses: { data: ... }
-        if (responseData && typeof responseData === 'object' && 'data' in responseData && !Array.isArray(responseData)) {
-            return responseData.data;
+        // A page travels whole: its cursor/pagination sibling is unrecoverable
+        // information, not decoration.
+        if (HttpService.PAGE_ENVELOPE_KEYS.some((key) => key in responseData)) {
+            return responseData;
         }
-        // Return as-is for responses that don't use sendSuccess wrapper
-        return responseData;
+        // Regular success envelope: `{ data: ... }` -> the payload.
+        return Array.isArray(responseData) ? responseData : responseData.data;
     }
     /**
      * Update request metrics
@@ -1155,3 +1182,15 @@ exports.HttpService = HttpService;
  * ambiguous with a serialized request body.
  */
 HttpService.CACHE_IDENTITY_DELIM = ' id=';
+/**
+ * The keys whose presence beside `data` makes a body a PAGE rather than a
+ * payload — see {@link unwrapResponse} for why this list is narrow.
+ *
+ *  - `pagination` — the offset-paginated house envelope (`sendPaginated`).
+ *  - `nextCursor` — the keyset-paginated one (the account audit trails).
+ *
+ * Membership is decided by key PRESENCE, never by value: the last page sends
+ * `nextCursor: null`, and an envelope that collapsed into a bare payload
+ * exactly when the stream ended would be a worse bug than the one this fixes.
+ */
+HttpService.PAGE_ENVELOPE_KEYS = ['pagination', 'nextCursor'];

package/dist/cjs/i18n/locales/en-US.json

@@ -2136,8 +2136,13 @@
             "filesWrite": "Upload and modify your files",
             "filesDelete": "Delete your files",
             "webhooksReceive": "Receive webhooks",
-            "chatCompletions": "Use AI chat on your behalf",
-            "modelsRead": "List available AI models",
+            "inferenceInvoke": "Run AI requests on your behalf",
+            "inferenceModelsRead": "List available AI models",
+            "inferenceUsageRead": "Read its AI usage and costs",
+            "inferenceRoutingRead": "Read how AI requests are routed",
+            "inferenceRoutingWrite": "Change how AI requests are routed",
+            "inferenceProvidersRead": "Read its connected AI providers",
+            "inferenceProvidersWrite": "Manage its connected AI providers",
             "federationWrite": "Act across federated services"
         },
         "account": {

package/dist/cjs/i18n/locales/es-ES.json

@@ -2136,8 +2136,13 @@
             "filesWrite": "Subir y modificar tus archivos",
             "filesDelete": "Eliminar tus archivos",
             "webhooksReceive": "Recibir webhooks",
-            "chatCompletions": "Usar el chat con IA en tu nombre",
-            "modelsRead": "Ver los modelos de IA disponibles",
+            "inferenceInvoke": "Ejecutar peticiones de IA en tu nombre",
+            "inferenceModelsRead": "Ver los modelos de IA disponibles",
+            "inferenceUsageRead": "Ver su consumo y costes de IA",
+            "inferenceRoutingRead": "Ver cómo se enrutan las peticiones de IA",
+            "inferenceRoutingWrite": "Cambiar cómo se enrutan las peticiones de IA",
+            "inferenceProvidersRead": "Ver sus proveedores de IA conectados",
+            "inferenceProvidersWrite": "Gestionar sus proveedores de IA conectados",
             "federationWrite": "Actuar en servicios federados"
         },
         "account": {

package/dist/cjs/i18n/locales/locales/en-US.json

@@ -2136,8 +2136,13 @@
       "filesWrite": "Upload and modify your files",
       "filesDelete": "Delete your files",
       "webhooksReceive": "Receive webhooks",
-      "chatCompletions": "Use AI chat on your behalf",
-      "modelsRead": "List available AI models",
+      "inferenceInvoke": "Run AI requests on your behalf",
+      "inferenceModelsRead": "List available AI models",
+      "inferenceUsageRead": "Read its AI usage and costs",
+      "inferenceRoutingRead": "Read how AI requests are routed",
+      "inferenceRoutingWrite": "Change how AI requests are routed",
+      "inferenceProvidersRead": "Read its connected AI providers",
+      "inferenceProvidersWrite": "Manage its connected AI providers",
       "federationWrite": "Act across federated services"
     },
     "account": {

package/dist/cjs/i18n/locales/locales/es-ES.json

@@ -2136,8 +2136,13 @@
       "filesWrite": "Subir y modificar tus archivos",
       "filesDelete": "Eliminar tus archivos",
       "webhooksReceive": "Recibir webhooks",
-      "chatCompletions": "Usar el chat con IA en tu nombre",
-      "modelsRead": "Ver los modelos de IA disponibles",
+      "inferenceInvoke": "Ejecutar peticiones de IA en tu nombre",
+      "inferenceModelsRead": "Ver los modelos de IA disponibles",
+      "inferenceUsageRead": "Ver su consumo y costes de IA",
+      "inferenceRoutingRead": "Ver cómo se enrutan las peticiones de IA",
+      "inferenceRoutingWrite": "Cambiar cómo se enrutan las peticiones de IA",
+      "inferenceProvidersRead": "Ver sus proveedores de IA conectados",
+      "inferenceProvidersWrite": "Gestionar sus proveedores de IA conectados",
       "federationWrite": "Actuar en servicios federados"
     },
     "account": {

package/dist/cjs/index.js

@@ -22,7 +22,7 @@ exports.AEAD_KEY_LENGTH = exports.decryptAead = exports.encryptAead = exports.hk
 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.getPrimaryLanguage = exports.getUserLanguages = exports.isRTLLocale = exports.getNativeLanguageName = exports.getLanguageName = exports.getLanguageMetadata = exports.isSupportedLocale = exports.normalizeLocale = exports.getBaseLanguage = exports.FALLBACK_LOCALE = exports.SUPPORTED_LANGUAGES = exports.TopicSource = exports.TopicType = exports.SECURITY_EVENT_SEVERITY_MAP = exports.DeviceManager = exports.deriveSharedSecret = exports.AEAD_NONCE_LENGTH = 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.isValidDisplayName = exports.isValidPassword = exports.isValidUsername = exports.isValidEmail = exports.DISPLAY_NAME_INVALID_MESSAGE = exports.MAX_DISPLAY_NAME_LENGTH = exports.PASSWORD_REGEX = exports.USERNAME_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.translate = exports.withRetry = exports.delay = exports.shouldAllowRequest = exports.recordSuccess = exports.recordFailure = void 0;
 exports.projectDevicePrincipals = exports.directoryHandle = exports.directoryDisplayName = exports.canActivateContext = exports.accountIdsOf = exports.activeUserOf = exports.activeSessionIdOf = exports.deviceStateToClientSessions = exports.createSessionClient = exports.createSessionClientHost = exports.SessionClient = exports.isAllowedDeviceJoinOrigin = exports.isOfficialWebOrigin = exports.isLoopbackOrigin = 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.runColdBoot = exports.isOxyRpOrigin = exports.CENTRAL_IDP_APEX = exports.registrableApex = 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.packageInfo = exports.runSessionColdBoot = exports.TOKEN_REFRESH_LEAD_MS = exports.startTokenRefreshScheduler = exports.installAuthRefreshHandler = exports.createAuthRefreshHandler = exports.refreshDeviceSecretArm = exports.refreshPersistedSession = exports.AccountNotOnDeviceError = exports.establishIdentitySession = exports.resolveIdentityPin = exports.IDENTITY_PIN_STORAGE_KEY = exports.identityPinMatches = exports.createMemoryIdentityPinStore = exports.createNativeIdentityPinStore = exports.createWebIdentityPinStore = exports.readLocalDeviceCredential = exports.publishProvenDeviceCredential = exports.normalizeSharedDeviceSessionRead = exports.decideSharedDevicePublish = exports.decideSharedDeviceJoin = exports.createSharedMirroringAuthStateStore = exports.AUTH_STATE_STORAGE_KEY = exports.createMemoryAuthStateStore = exports.createNativeAuthStateStore = exports.createWebAuthStateStore = exports.createAccountDialogController = exports.AccountDialogController = exports.canSwitchIntoAccount = exports.isSwitchTargetAccount = exports.showsPrincipalHeaders = exports.buildSwitcherRows = exports.resolveDeviceContext = exports.resolveActiveContext = void 0;
+exports.packageInfo = exports.runSessionColdBoot = exports.OXY_INFERENCE_BASE_URL = exports.OxyInferenceError = exports.OxyInferenceClient = exports.TOKEN_REFRESH_LEAD_MS = exports.startTokenRefreshScheduler = exports.installAuthRefreshHandler = exports.createAuthRefreshHandler = exports.refreshDeviceSecretArm = exports.refreshPersistedSession = exports.AccountNotOnDeviceError = exports.establishIdentitySession = exports.resolveIdentityPin = exports.IDENTITY_PIN_STORAGE_KEY = exports.identityPinMatches = exports.createMemoryIdentityPinStore = exports.createNativeIdentityPinStore = exports.createWebIdentityPinStore = exports.readLocalDeviceCredential = exports.publishProvenDeviceCredential = exports.normalizeSharedDeviceSessionRead = exports.decideSharedDevicePublish = exports.decideSharedDeviceJoin = exports.createSharedMirroringAuthStateStore = exports.AUTH_STATE_STORAGE_KEY = exports.createMemoryAuthStateStore = exports.createNativeAuthStateStore = exports.createWebAuthStateStore = exports.createAccountDialogController = exports.AccountDialogController = exports.canSwitchIntoAccount = exports.isSwitchTargetAccount = exports.showsPrincipalHeaders = exports.buildSwitcherRows = exports.resolveDeviceContext = exports.resolveActiveContext = void 0;
 // Ensure crypto polyfills are loaded before anything else
 require("./crypto/polyfill");
 // ---------------------------------------------------------------------------
@@ -470,6 +470,13 @@ Object.defineProperty(exports, "createAuthRefreshHandler", { enumerable: true, g
 Object.defineProperty(exports, "installAuthRefreshHandler", { enumerable: true, get: function () { return refresh_1.installAuthRefreshHandler; } });
 Object.defineProperty(exports, "startTokenRefreshScheduler", { enumerable: true, get: function () { return refresh_1.startTokenRefreshScheduler; } });
 Object.defineProperty(exports, "TOKEN_REFRESH_LEAD_MS", { enumerable: true, get: function () { return refresh_1.TOKEN_REFRESH_LEAD_MS; } });
+// The inference API. `oxyServices.inference()` binds the session bearer into
+// the same client an external developer constructs with an `oxy_sk_…` machine
+// key — one surface, two credential lanes. See `docs/inference/sdk.md`.
+var OxyInferenceClient_1 = require("./inference/OxyInferenceClient");
+Object.defineProperty(exports, "OxyInferenceClient", { enumerable: true, get: function () { return OxyInferenceClient_1.OxyInferenceClient; } });
+Object.defineProperty(exports, "OxyInferenceError", { enumerable: true, get: function () { return OxyInferenceClient_1.OxyInferenceError; } });
+Object.defineProperty(exports, "OXY_INFERENCE_BASE_URL", { enumerable: true, get: function () { return OxyInferenceClient_1.OXY_INFERENCE_BASE_URL; } });
 var sessionColdBoot_1 = require("./boot/sessionColdBoot");
 Object.defineProperty(exports, "runSessionColdBoot", { enumerable: true, get: function () { return sessionColdBoot_1.runSessionColdBoot; } });
 // API response contracts (request/response Zod schemas + inferred types) live in

package/dist/cjs/inference/OxyInferenceClient.js

@@ -0,0 +1,330 @@
+"use strict";
+/**
+ * The Oxy inference client — one surface, two credential lanes (issue #972,
+ * workstream 15).
+ *
+ * ```typescript
+ * // An OpenAI-style machine key: one bearer string, no session, no exchange.
+ * const oxy = new OxyInferenceClient({ credential: process.env.OXY_API_KEY });
+ *
+ * // Oxy auth: whatever bearer the session or the service-token mint holds.
+ * const oxy = oxyServices.inference();
+ * ```
+ *
+ * Both lanes reach the SAME endpoints and are told apart only by how the bearer
+ * is produced: a machine key is a constant string, and an Oxy bearer rotates, so
+ * it is a function this client calls on every request rather than a value it
+ * captures once. There is no third lane, and no method behaves differently
+ * depending on which one you used.
+ *
+ * ## What you will observe today
+ *
+ * **Every invoke refuses.** `respond()` reaches the public edge, which
+ * authenticates the credential, resolves attribution, authorizes scopes, pins a
+ * routing policy and reserves spend — and then has no data plane to forward to,
+ * so it releases the hold and answers `service_unavailable`. That surfaces here
+ * as an {@link OxyInferenceError} with `code: 'service_unavailable'`,
+ * `retryable: false` and a `requestId`. It is the correct answer, not a
+ * misconfiguration of yours, and no balance is spent.
+ *
+ * **The catalogue is empty**, so {@link OxyInferenceClient.listModels} answers
+ * `[]` and {@link OxyInferenceClient.getModel} throws for every id. `[]` is a
+ * normal answer to render, not an error to retry.
+ *
+ * `docs/inference/README.md` is the status board; `docs/inference/sdk.md` is
+ * this client's page.
+ *
+ * ## Why this is a client and not more methods on `OxyServices`
+ *
+ * Two reasons, both structural. A machine-key holder has no Oxy session at all,
+ * so a surface reached only through the session client would be unreachable for
+ * exactly the developer this workstream exists to serve. And the `/v1` error
+ * body is the contract's `InferenceError` at the top level rather than the
+ * platform's `{ error, message }` envelope — it carries `requestId`, `retryable`
+ * and `retryAfterMs`, all of which `OxyServices.handleError` would flatten into a
+ * message string. `oxyServices.inference()` binds the session bearer into this
+ * client so a session-holding app writes no plumbing of its own.
+ *
+ * ## Streaming is absent on purpose
+ *
+ * There is no `stream()` method and no `stream` field on a request. The stream
+ * event union exists in `@oxyhq/contracts` and no endpoint emits one — the edge
+ * refuses `stream: true` with `invalid_request`. A method that always failed
+ * would be a worse artefact than an absent one. See
+ * `docs/inference/streaming.md`.
+ *
+ * ## Field names, and the one place they could drift
+ *
+ * Every VALUE type here comes from `@oxyhq/contracts` — messages, tools, tool
+ * choice, response format, usage quantities, unit prices, error codes. The
+ * request FIELD NAMES cannot: they belong to `responsesRequestSchema`, which
+ * lives in the API because it is a public dialect rather than an Oxy↔data-plane
+ * contract. `packages/api/src/schemas/__tests__/sdkRequestCompatibility.test.ts`
+ * is the gate — it parses a value of this module's request type against that
+ * schema, so a rename on either side fails a build rather than a customer's
+ * request.
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _OxyInferenceClient_instances, _OxyInferenceClient_baseURL, _OxyInferenceClient_credential, _OxyInferenceClient_fetch, _OxyInferenceClient_bearer, _OxyInferenceClient_request;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OxyInferenceClient = exports.OxyInferenceError = exports.OXY_INFERENCE_BASE_URL = void 0;
+const contracts_1 = require("@oxyhq/contracts");
+/** The base URL of the Oxy API, when a caller names none. */
+exports.OXY_INFERENCE_BASE_URL = 'https://api.oxy.so';
+/**
+ * Anything the inference API refused.
+ *
+ * `retryable` is asserted by the server and looked up from a total map over the
+ * closed code set — never inferred here from the status. A client that decides
+ * retryability from an HTTP status is exactly what the contract's retryability
+ * rule exists to prevent, so this class carries the server's answer and does not
+ * compute one.
+ */
+class OxyInferenceError extends Error {
+    constructor(input) {
+        super(input.message);
+        this.name = 'OxyInferenceError';
+        this.code = input.code;
+        this.retryable = input.retryable;
+        this.requestId = input.requestId;
+        this.status = input.status;
+        if (input.retryAfterMs !== undefined)
+            this.retryAfterMs = input.retryAfterMs;
+        if (input.param !== undefined)
+            this.param = input.param;
+    }
+}
+exports.OxyInferenceError = OxyInferenceError;
+/**
+ * The Oxy inference API.
+ *
+ * Stateless: it holds a base URL, a way to get a bearer and a `fetch`. Nothing
+ * is cached, because the two things worth caching here are a catalogue that is
+ * audience-scoped and a receipt that is immutable but rarely re-read.
+ *
+ * Successful responses are TYPED, not re-parsed. The server validates every one
+ * against its own schema before serving it, and a second client-side parse of a
+ * non-strict shape would silently DROP fields a newer API added — turning
+ * forward compatibility into data loss. Refusals are read defensively, because
+ * two routers answer under `/v1` and an unreadable failure must still reach the
+ * caller as one.
+ */
+class OxyInferenceClient {
+    constructor(options) {
+        _OxyInferenceClient_instances.add(this);
+        _OxyInferenceClient_baseURL.set(this, void 0);
+        _OxyInferenceClient_credential.set(this, void 0);
+        _OxyInferenceClient_fetch.set(this, void 0);
+        const baseURL = options.baseURL ?? exports.OXY_INFERENCE_BASE_URL;
+        __classPrivateFieldSet(this, _OxyInferenceClient_baseURL, baseURL.endsWith('/') ? baseURL.slice(0, -1) : baseURL, "f");
+        __classPrivateFieldSet(this, _OxyInferenceClient_credential, options.credential, "f");
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (fetchImpl === undefined) {
+            throw new Error('OxyInferenceClient needs a fetch implementation: this runtime has no global fetch, so pass one as `fetch`.');
+        }
+        __classPrivateFieldSet(this, _OxyInferenceClient_fetch, fetchImpl, "f");
+    }
+    /**
+     * The models this caller may use — `GET /v1/models`.
+     *
+     * Audience-scoped server-side. A machine credential and an anonymous caller
+     * both see the PUBLIC catalogue; only an internal/system application's
+     * service token sees internal-only routes.
+     *
+     * **`[]` is a normal answer**, and is the only answer today: the catalogue
+     * is populated by operators, and a route is not publicly exposed until
+     * somebody has reviewed the right to resell it.
+     */
+    async listModels(options = {}) {
+        const body = await __classPrivateFieldGet(this, _OxyInferenceClient_instances, "m", _OxyInferenceClient_request).call(this, 'GET', '/v1/models', { ...(options.signal === undefined ? {} : { signal: options.signal }) });
+        return body.data;
+    }
+    /**
+     * One catalogue entry by its canonical id — `GET /v1/models/:publisher/:model`.
+     *
+     * The id is TWO path segments, because a canonical model id contains a slash
+     * and a single encoded segment would never match the route.
+     *
+     * A model you may not see answers 404 identically to one that does not
+     * exist, deliberately: the catalogue is never an existence oracle for what
+     * Oxy runs internally.
+     *
+     * @param modelId - `<publisher>/<model>`. A revision pin
+     *   (`<publisher>/<model>@<revision>`) names a model REFERENCE rather than a
+     *   model and is rejected here rather than sent, because the catalogue is
+     *   keyed on models and a pinned reference would 404 indistinguishably from
+     *   "no such model".
+     */
+    async getModel(modelId, options = {}) {
+        const parsed = contracts_1.modelIdSchema.safeParse(modelId);
+        if (!parsed.success) {
+            throw new Error(`Not a canonical model id: ${modelId}. Expected <publisher>/<model>, e.g. acme/some-model.`);
+        }
+        const [publisher, model] = parsed.data.split('/');
+        const body = await __classPrivateFieldGet(this, _OxyInferenceClient_instances, "m", _OxyInferenceClient_request).call(this, 'GET', `/v1/models/${encodeURIComponent(publisher)}/${encodeURIComponent(model)}`, { ...(options.signal === undefined ? {} : { signal: options.signal }) });
+        return body.data;
+    }
+    /**
+     * The routing profiles this caller may select — `GET /v1/models/routing-profiles`.
+     *
+     * A profile is a named strategy for CHOOSING among routes, not a model: no
+     * publisher, no revision, no licence, no weights. Like the model list, `[]`
+     * is a normal answer.
+     */
+    async listRoutingProfiles(options = {}) {
+        const body = await __classPrivateFieldGet(this, _OxyInferenceClient_instances, "m", _OxyInferenceClient_request).call(this, 'GET', '/v1/models/routing-profiles', { ...(options.signal === undefined ? {} : { signal: options.signal }) });
+        return body.data;
+    }
+    /**
+     * Send one non-streaming inference request — `POST /v1/responses`.
+     *
+     * **This refuses in every deployment today** with `service_unavailable`,
+     * because there is no data plane behind the edge. The spend held for the
+     * request is released before the refusal returns, so nothing is charged.
+     *
+     * @throws {OxyInferenceError} for every refusal, carrying the server's own
+     *   `code`, `retryable` and `requestId`.
+     */
+    async respond(request, options = {}) {
+        return __classPrivateFieldGet(this, _OxyInferenceClient_instances, "m", _OxyInferenceClient_request).call(this, 'POST', '/v1/responses', {
+            body: request,
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            ...(options.idempotencyKey === undefined
+                ? {}
+                : { idempotencyKey: options.idempotencyKey }),
+            ...(options.delegatedUserId === undefined
+                ? {}
+                : { delegatedUserId: options.delegatedUserId }),
+        });
+    }
+    /**
+     * Read back the settled receipt for one request —
+     * `GET /v1/generations/:id`.
+     *
+     * `id` is the `requestId` you already hold (it is on every response and
+     * every error) or the `generationId`. Requires the `inference:usage:read`
+     * scope; a caller without it, or one whose application did not make the
+     * request, is told the receipt does not exist rather than that it belongs to
+     * somebody else.
+     */
+    async getGeneration(id, options = {}) {
+        const body = await __classPrivateFieldGet(this, _OxyInferenceClient_instances, "m", _OxyInferenceClient_request).call(this, 'GET', `/v1/generations/${encodeURIComponent(id)}`, { ...(options.signal === undefined ? {} : { signal: options.signal }) });
+        return body.data;
+    }
+}
+exports.OxyInferenceClient = OxyInferenceClient;
+_OxyInferenceClient_baseURL = new WeakMap(), _OxyInferenceClient_credential = new WeakMap(), _OxyInferenceClient_fetch = new WeakMap(), _OxyInferenceClient_instances = new WeakSet(), _OxyInferenceClient_bearer = 
+/** The bearer for this request, from whichever lane was configured. */
+async function _OxyInferenceClient_bearer() {
+    const value = typeof __classPrivateFieldGet(this, _OxyInferenceClient_credential, "f") === 'string'
+        ? __classPrivateFieldGet(this, _OxyInferenceClient_credential, "f")
+        : await __classPrivateFieldGet(this, _OxyInferenceClient_credential, "f").call(this);
+    if (value === null || value === undefined || value.length === 0) {
+        throw new Error('OxyInferenceClient has no bearer: the configured credential resolved to nothing. On the Oxy auth lane this usually means the session is not restored yet.');
+    }
+    return value;
+}, _OxyInferenceClient_request = 
+/**
+ * One request, and the one place a refusal becomes an
+ * {@link OxyInferenceError}.
+ *
+ * Two error shapes arrive here, because two routers serve `/v1`. The edge
+ * returns the contract error at the top level; the catalogue returns the
+ * platform's `{ error, message }` envelope. Both are read, and a body that
+ * is neither still produces an `OxyInferenceError` — with the code the
+ * status maps to — rather than a bare `Error`, so a caller's `catch` never
+ * has to branch on which router answered.
+ */
+async function _OxyInferenceClient_request(method, path, options) {
+    const headers = {
+        Authorization: `Bearer ${await __classPrivateFieldGet(this, _OxyInferenceClient_instances, "m", _OxyInferenceClient_bearer).call(this)}`,
+        Accept: 'application/json',
+    };
+    if (options.body !== undefined)
+        headers['Content-Type'] = 'application/json';
+    if (options.idempotencyKey !== undefined) {
+        headers['Idempotency-Key'] = options.idempotencyKey;
+    }
+    if (options.delegatedUserId !== undefined) {
+        headers['X-Oxy-User-Id'] = options.delegatedUserId;
+    }
+    const response = await __classPrivateFieldGet(this, _OxyInferenceClient_fetch, "f").call(this, `${__classPrivateFieldGet(this, _OxyInferenceClient_baseURL, "f")}${path}`, {
+        method,
+        headers,
+        ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    const payload = await response.json().catch(() => undefined);
+    if (!response.ok) {
+        throw toInferenceError(payload, response.status, response.headers.get('X-Oxy-Request-Id'));
+    }
+    return payload;
+};
+/**
+ * Which code a status means when the body did not name one.
+ *
+ * Deliberately partial: only the statuses whose meaning is unambiguous without a
+ * body. Everything else becomes `internal_error`, which is non-retryable — the
+ * safe direction, since inventing a retryable code for an unreadable failure is
+ * how one outage becomes a retry storm.
+ */
+const STATUS_FALLBACK_CODE = {
+    400: 'invalid_request',
+    401: 'authentication_failed',
+    403: 'permission_denied',
+    404: 'model_not_found',
+    409: 'idempotency_conflict',
+    413: 'request_too_large',
+    429: 'rate_limited',
+    502: 'provider_error',
+    503: 'service_unavailable',
+    504: 'provider_timeout',
+};
+/**
+ * The closed set the contract defines, as a lookup.
+ *
+ * A `code` outside it is a contract violation rather than a code this client
+ * has not caught up with — `INFERENCE_ERROR_CODES` and the version header move
+ * together — so an unrecognised one falls back to the status map instead of
+ * being asserted into the type.
+ */
+const INFERENCE_ERROR_CODE_SET = new Set(contracts_1.INFERENCE_ERROR_CODES);
+/** Read whichever error shape arrived into the one this client throws. */
+function toInferenceError(payload, status, requestIdHeader) {
+    const body = (payload ?? {});
+    // The edge's own shape is the contract error at the top level; the
+    // catalogue's is the platform envelope, whose `error` is a string.
+    const code = typeof body.code === 'string' && INFERENCE_ERROR_CODE_SET.has(body.code)
+        ? body.code
+        : (STATUS_FALLBACK_CODE[status] ?? 'internal_error');
+    const message = typeof body.message === 'string' && body.message.length > 0
+        ? body.message
+        : typeof body.error === 'string' && body.error.length > 0
+            ? body.error
+            : `The inference API answered ${status}.`;
+    return new OxyInferenceError({
+        code,
+        message,
+        // A body that did not assert retryability is not retryable: the server
+        // is the only thing that may say a retry could succeed.
+        retryable: body.retryable === true,
+        requestId: typeof body.requestId === 'string' && body.requestId.length > 0
+            ? body.requestId
+            : (requestIdHeader ?? ''),
+        status,
+        ...(body.retryable === true && typeof body.retryAfterMs === 'number'
+            ? { retryAfterMs: body.retryAfterMs }
+            : {}),
+        ...(typeof body.param === 'string' ? { param: body.param } : {}),
+    });
+}

package/dist/cjs/mixins/OxyServices.accounts.js

@@ -341,76 +341,6 @@ function OxyServicesAccountsMixin(Base) {
             }
         }
         // =========================================================================
-        // Bot (account) service credentials  —  /accounts/:id/credentials
-        // =========================================================================
-        /**
-         * List a bot account's service credentials. The response NEVER includes
-         * secrets.
-         * @param accountId - The account's Mongo `_id`.
-         */
-        async listAccountCredentials(accountId) {
-            try {
-                const res = await this.makeRequest('GET', `/accounts/${encodeURIComponent(accountId)}/credentials`, undefined, { cache: true, cacheTTL: mixinHelpers_1.CACHE_TIMES.MEDIUM });
-                return res.credentials ?? [];
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Create a service credential for a bot account. The plaintext `secret` is
-         * returned exactly ONCE; the server stores only a hash and will never return
-         * it again.
-         * @param accountId - The account's Mongo `_id`.
-         * @param data - Credential configuration (`type` is always `service`).
-         */
-        async createAccountCredential(accountId, data) {
-            try {
-                const result = await this.makeRequest('POST', `/accounts/${encodeURIComponent(accountId)}/credentials`, data, { cache: false });
-                this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/credentials`);
-                return result;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Rotate a bot credential's secret. The new plaintext `secret` is returned
-         * exactly ONCE, along with audit fields: `rotatedFrom` (the previous
-         * credentialId) and `graceExpiresAt` (ISO string for the grace window during
-         * which the old credential is still honoured).
-         * @param accountId - The account's Mongo `_id`.
-         * @param credentialId - The credential's Mongo `_id`.
-         */
-        async rotateAccountCredential(accountId, credentialId) {
-            try {
-                const result = await this.makeRequest('POST', `/accounts/${encodeURIComponent(accountId)}/credentials/${encodeURIComponent(credentialId)}/rotate`, undefined, { cache: false });
-                // Rotation changes credential status/audit fields surfaced by the list.
-                this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/credentials`);
-                return result;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        /**
-         * Revoke a bot credential (`status='revoked'`). Revoked credentials can no
-         * longer authenticate.
-         * @param accountId - The account's Mongo `_id`.
-         * @param credentialId - The credential's Mongo `_id`.
-         */
-        async revokeAccountCredential(accountId, credentialId) {
-            try {
-                const result = await this.makeRequest('DELETE', `/accounts/${encodeURIComponent(accountId)}/credentials/${encodeURIComponent(credentialId)}`, undefined, { cache: false });
-                // Revocation flips the credential's status in the cached list.
-                this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/credentials`);
-                return result;
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-        // =========================================================================
         // Applications owned by an account  —  /applications
         // =========================================================================
         /**
@@ -531,10 +461,13 @@ function OxyServicesAccountsMixin(Base) {
          * which the old credential is still honoured).
          * @param applicationId - The application's Mongo `_id`.
          * @param credentialId - The credential's Mongo `_id`.
+         * @param options - `graceSeconds` keeps a superseded `machine` token working
+         *   for that long. Omitted, the previous token dies the moment the
+         *   replacement is minted.
          */
-        async rotateAppCredential(applicationId, credentialId) {
+        async rotateAppCredential(applicationId, credentialId, options) {
             try {
-                const result = await this.makeRequest('POST', `/applications/${encodeURIComponent(applicationId)}/credentials/${encodeURIComponent(credentialId)}/rotate`, undefined, { cache: false });
+                const result = await this.makeRequest('POST', `/applications/${encodeURIComponent(applicationId)}/credentials/${encodeURIComponent(credentialId)}/rotate`, options, { cache: false });
                 // Rotation changes credential status/audit fields surfaced by the list.
                 this.clearCacheEntry(`GET:/applications/${encodeURIComponent(applicationId)}/credentials`);
                 return result;