@oxyhq/core 21.0.0 → 21.0.2

package/dist/types/HttpService.d.ts

@@ -194,6 +194,18 @@ export declare class HttpService {
      * ambiguous with a serialized request body.
      */
     private static readonly CACHE_IDENTITY_DELIM;
+    /**
+     * 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.
+     */
+    private static readonly PAGE_ENVELOPE_KEYS;
     /**
      * Derive a stable, non-sensitive identity discriminator for cache scoping.
      *
@@ -270,7 +282,33 @@ export declare class HttpService {
      */
     runSingleFlightDeviceSecretMint(mint: () => Promise<DeviceSecretMintOutcome>): Promise<DeviceSecretMintOutcome>;
     /**
-     * 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`.
      */
     private unwrapResponse;
     /**

package/dist/types/index.d.ts

@@ -40,7 +40,7 @@ export { normalizeProfileLinks } from './utils/profileLinks';
 export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
 export type { PublicApplication, ConnectedApp, } from './mixins/OxyServices.connectedApps';
 export type { StoreCategory, StoreRating, StoreListingSummary, StoreListingDetail, StoreScreenshot, StoreScreenshotPlatform, StoreReview, StoreOwnReview, WriteStoreReviewInput, StoreListingStatus, PublisherListing, WriteListingInput, AddScreenshotInput, UpdateScreenshotInput, StorePage, StorePageOptions, StoreReviewsOptions, } from './mixins/OxyServices.store';
-export type { AccountKind, AccountCategoryId, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, AccountCredentialType, AccountCredentialEnvironment, AccountCredentialStatus, AccountCredential, AccountCredentialWithSecret, RotateAccountCredentialResult, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, ProvisionChannelInput, ProvisionChannelMemberInput, ProvisionChannelResult, InviteAccountMemberInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, CreateAccountCredentialInput, AccountSuccessResult, SwitchAccountResult, Application, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, } from './mixins/OxyServices.accounts';
+export type { AccountKind, AccountCategoryId, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, ProvisionChannelInput, ProvisionChannelMemberInput, ProvisionChannelResult, InviteAccountMemberInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, AccountSuccessResult, SwitchAccountResult, Application, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, RotateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, } from './mixins/OxyServices.accounts';
 export { ACCOUNT_CATEGORY_IDS, MAX_ACCOUNT_CATEGORIES, SELECTABLE_ACCOUNT_CATEGORY_IDS, isSelectableAccountCategoryId, kindAcceptsAccountCategories, } from './mixins/OxyServices.accounts';
 export { buildUserDid } from './mixins/OxyServices.identity';
 export type { IdentityRecordType, UnlinkableAuthMethodType, LinkAuthMethodResult, PublishRecordResult, VerifyRecordResult, VerifyDomainResult, RemoveDomainResult, RotateKeyProof, RotateKeyOptions, RotateKeyResult, } from './mixins/OxyServices.identity';
@@ -134,6 +134,8 @@ export type { IdentityBinding, IdentityRequestOptions, EstablishedIdentitySessio
 export { AccountNotOnDeviceError } from './mixins/OxyServices.deviceBoot';
 export { refreshPersistedSession, refreshDeviceSecretArm, createAuthRefreshHandler, installAuthRefreshHandler, startTokenRefreshScheduler, TOKEN_REFRESH_LEAD_MS, } from './session/refresh';
 export type { RefreshDeps, TokenRefreshSchedulerHandle, DeviceSecretMintOutcome } from './session/refresh';
+export { OxyInferenceClient, OxyInferenceError, OXY_INFERENCE_BASE_URL, } from './inference/OxyInferenceClient';
+export type { OxyInferenceClientOptions, OxyInferenceCredential, OxyInferenceFetch, OxyInferenceRequestOptions, OxyInferenceResponse, OxyGenerationReceipt, OxyResponsesRequest, } from './inference/OxyInferenceClient';
 export { runSessionColdBoot } from './boot/sessionColdBoot';
 export type { RunSessionColdBootOptions, SessionMode, SignedOutReason, DeviceBootSession, } from './boot/sessionColdBoot';
 export { packageInfo } from './constants/version';

package/dist/types/inference/OxyInferenceClient.d.ts

@@ -0,0 +1,324 @@
+/**
+ * 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.
+ */
+import type { CurrencyCode, ExactDecimal, InferenceEnvironment, InferenceErrorCode, InferenceFinishReason, InferenceMessage, InferenceRequestOutcome, ModelCatalogueEntry, ResponseFormat, RoutingPolicyReference, RoutingProfile, ToolChoice, ToolDefinition, UnitPrice, UsageQuantity, UsageSource } from '@oxyhq/contracts';
+/** The base URL of the Oxy API, when a caller names none. */
+export declare const OXY_INFERENCE_BASE_URL = "https://api.oxy.so";
+/**
+ * How this client gets its bearer.
+ *
+ * A `string` is a static machine credential (`oxy_sk_…`) — presented verbatim,
+ * exactly as a stock OpenAI SDK would present it. A function is the Oxy auth
+ * lane and is called on EVERY request, because a session bearer and a service
+ * token both rotate and a captured one goes stale inside the hour.
+ */
+export type OxyInferenceCredential = string | (() => string | null | Promise<string | null>);
+/**
+ * The `fetch` this client calls.
+ *
+ * The global signature rather than a narrowed one, so any drop-in
+ * implementation — a test double, an instrumented wrapper, a Node agent — is
+ * assignable without a cast at either end.
+ */
+export type OxyInferenceFetch = typeof fetch;
+export interface OxyInferenceClientOptions {
+    readonly credential: OxyInferenceCredential;
+    /** Defaults to {@link OXY_INFERENCE_BASE_URL}. A trailing slash is trimmed. */
+    readonly baseURL?: string;
+    /** Defaults to the global `fetch`. */
+    readonly fetch?: OxyInferenceFetch;
+}
+/**
+ * A request to `POST /v1/responses`.
+ *
+ * `model` and `routingProfile` are mutually exclusive and BOTH are optional: an
+ * application whose routing policy carries a `defaultTarget` may name neither,
+ * which is what "per-application default model or routing profile" means. Naming
+ * both is refused by the edge with `invalid_request`.
+ */
+export interface OxyResponsesRequest {
+    /** `<publisher>/<model>` or `<publisher>/<model>@<revision>`. */
+    readonly model?: string;
+    /** A routing profile slug. Never contains a slash, so it is never a model id. */
+    readonly routingProfile?: string;
+    /** A prompt, or the message list it is shorthand for. */
+    readonly input: string | readonly InferenceMessage[];
+    readonly maxOutputTokens?: number;
+    readonly temperature?: number;
+    readonly topP?: number;
+    readonly topK?: number;
+    readonly frequencyPenalty?: number;
+    readonly presencePenalty?: number;
+    readonly seed?: number;
+    readonly stopSequences?: readonly string[];
+    readonly tools?: readonly ToolDefinition[];
+    readonly toolChoice?: ToolChoice;
+    readonly responseFormat?: ResponseFormat;
+    /** Cost-attribution tags, echoed back on the receipt. At most 16. */
+    readonly labels?: Readonly<Record<string, string>>;
+    /** Your own correlation id, echoed on the response. */
+    readonly clientRequestId?: string;
+}
+export interface OxyInferenceRequestOptions {
+    /**
+     * Abort the request. The edge treats a client disconnect as a cancellation:
+     * it settles what was produced and refunds the rest, so a cancelled request
+     * is a normal terminal state rather than an error to clean up after.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * `Idempotency-Key`. A key already bound to a reservation is REFUSED with
+     * `idempotency_conflict` rather than replayed — responses are not retained,
+     * so there is nothing to replay, and refusing is what makes "a retry never
+     * produces a second charge" structural. At most 128 characters.
+     */
+    readonly idempotencyKey?: string;
+    /**
+     * `X-Oxy-User-Id` — the end user this request is made on behalf of.
+     * ATTRIBUTION ONLY: it never changes which account is charged.
+     */
+    readonly delegatedUserId?: string;
+}
+/** The body of a successful `POST /v1/responses`. */
+export interface OxyInferenceResponse {
+    readonly schemaVersion: 1;
+    /** Also on `X-Oxy-Request-Id`, on success and on every refusal. */
+    readonly requestId: string;
+    readonly generationId?: string;
+    /** Always revision-pinned, even when you named only the model line. */
+    readonly model: string;
+    readonly servingProvider: string;
+    readonly finishReason: InferenceFinishReason;
+    readonly output: readonly InferenceMessage[];
+    /** Metered quantities. Never money — the charge is on the receipt. */
+    readonly usage: readonly UsageQuantity[];
+    /** The exact policy version this request was admitted under. */
+    readonly routingPolicy: RoutingPolicyReference;
+    /**
+     * How long Oxy took over this request, in whole milliseconds — also on
+     * `X-Oxy-Latency-Ms`.
+     *
+     * Measured from the moment the edge received the request through
+     * authentication, admission, routing, the reservation, the call to the
+     * inference data plane and the settlement of the hold. Most of it is the
+     * upstream generating tokens; it does not separate the two.
+     *
+     * It is NOT the round trip you can measure yourself, which additionally
+     * covers DNS, TLS, both network legs and your own parse. Report them side by
+     * side rather than picking one — this figure has no network in it and yours
+     * cannot be attributed to the model.
+     *
+     * Optional because it is additive: an Oxy deployment older than the field
+     * omits it, and a streamed request never carries it (the head is written
+     * before the first frame arrives, so the number does not exist yet).
+     */
+    readonly latencyMs?: number;
+}
+/**
+ * A settled receipt, as `GET /v1/generations/:id` returns it.
+ *
+ * Carries the price SNAPSHOT rather than a reference to a price version, so the
+ * arithmetic stays checkable after that version has been superseded.
+ */
+export interface OxyGenerationReceipt {
+    readonly schemaVersion: 1;
+    readonly receiptId: string;
+    readonly requestId: string;
+    readonly generationId?: string;
+    readonly applicationId: string;
+    readonly credentialId: string;
+    /** Attribution only. Never the billing identity. */
+    readonly delegatedUserId?: string;
+    readonly environment: InferenceEnvironment;
+    readonly outcome: InferenceRequestOutcome;
+    readonly usageSource: UsageSource;
+    /** EVERY unit, including the zeros — see `usageSource` for what a zero means. */
+    readonly units: readonly UsageQuantity[];
+    readonly resolvedModelReference: string;
+    readonly servingProvider: string;
+    readonly priceSnapshot: {
+        readonly priceVersionId: string;
+        readonly currency: CurrencyCode;
+        readonly unitPrices: readonly UnitPrice[];
+    };
+    readonly billedAmount: ExactDecimal;
+    readonly currency: CurrencyCode;
+    /** A BYOK route: `billedAmount` is Oxy's fee, not the cost of the tokens. */
+    readonly platformFeeOnly: boolean;
+    readonly settledAt: string;
+}
+/**
+ * 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.
+ */
+export declare class OxyInferenceError extends Error {
+    readonly code: InferenceErrorCode;
+    readonly retryable: boolean;
+    readonly requestId: string;
+    readonly status: number;
+    /** How long to wait. Only ever present when `retryable`. */
+    readonly retryAfterMs?: number;
+    /** The request field at fault, for `invalid_request`. */
+    readonly param?: string;
+    constructor(input: {
+        code: InferenceErrorCode;
+        message: string;
+        retryable: boolean;
+        requestId: string;
+        status: number;
+        retryAfterMs?: number;
+        param?: string;
+    });
+}
+/**
+ * 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.
+ */
+export declare class OxyInferenceClient {
+    #private;
+    constructor(options: OxyInferenceClientOptions);
+    /**
+     * 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.
+     */
+    listModels(options?: {
+        signal?: AbortSignal;
+    }): Promise<ModelCatalogueEntry[]>;
+    /**
+     * 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".
+     */
+    getModel(modelId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ModelCatalogueEntry>;
+    /**
+     * 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.
+     */
+    listRoutingProfiles(options?: {
+        signal?: AbortSignal;
+    }): Promise<RoutingProfile[]>;
+    /**
+     * 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`.
+     */
+    respond(request: OxyResponsesRequest, options?: OxyInferenceRequestOptions): Promise<OxyInferenceResponse>;
+    /**
+     * 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.
+     */
+    getGeneration(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<OxyGenerationReceipt>;
+}

package/dist/types/mixins/OxyServices.accounts.d.ts

@@ -267,61 +267,6 @@ export interface UpdateAccountMemberInput {
 export interface TransferAccountOwnershipInput {
     userId: string;
 }
-/** Credential kind. Account (bot) credentials are always `service` tokens. */
-export type AccountCredentialType = 'service';
-/** Deployment environment a bot credential is scoped to. */
-export type AccountCredentialEnvironment = 'development' | 'staging' | 'production';
-/** Bot credential lifecycle status. */
-export type AccountCredentialStatus = 'active' | 'deprecated' | 'revoked';
-/** Input accepted by `createAccountCredential`. Credential `type` is always `service`. */
-export interface CreateAccountCredentialInput {
-    name: string;
-    environment: AccountCredentialEnvironment;
-    scopes?: string[];
-}
-/**
- * Client-facing AccountCredential shape (a bot account's service token). The raw
- * secret is NEVER part of this shape — it is returned exactly once, separately,
- * at creation/rotation.
- */
-export interface AccountCredential {
-    _id: string;
-    /** The bot account this credential authenticates as (account `_id`). */
-    accountId: string;
-    name: string;
-    publicKey: string;
-    type: AccountCredentialType;
-    environment: AccountCredentialEnvironment;
-    scopes: string[];
-    status: AccountCredentialStatus;
-    lastUsedAt?: string;
-    expiresAt?: string;
-    /**
-     * Audit link to the credential this one was rotated FROM. Populated on
-     * credentials created via rotation; absent on original credentials.
-     */
-    rotatedFromCredentialId?: string;
-    createdByUserId: string;
-    createdAt: string;
-    updatedAt: string;
-}
-/** Result of creating a bot credential — `secret` is returned ONCE. */
-export interface AccountCredentialWithSecret {
-    credential: AccountCredential;
-    secret: string;
-}
-/**
- * Result of rotating a bot credential. Extends the create result with audit
- * fields: the new plaintext `secret` is returned ONCE, plus `rotatedFrom` (the
- * previous credential's `credentialId`) and `graceExpiresAt` (ISO string marking
- * when the old credential stops being honoured during the rotation grace window).
- */
-export interface RotateAccountCredentialResult extends AccountCredentialWithSecret {
-    /** The previous credential's `credentialId` that this rotation supersedes. */
-    rotatedFrom: string;
-    /** ISO timestamp at which the rotated-from credential's grace window ends. */
-    graceExpiresAt: string;
-}
 /**
  * Application classification. Set only by Oxy platform staff — never editable
  * through the normal member-facing update path.
@@ -329,8 +274,18 @@ export interface RotateAccountCredentialResult extends AccountCredentialWithSecr
 export type ApplicationType = 'first_party' | 'third_party' | 'internal' | 'system';
 /** Lifecycle status of an application. */
 export type ApplicationStatus = 'active' | 'suspended' | 'deleted' | 'pending_review';
-/** OAuth credential kind. `service` credentials mint service tokens. */
-export type ApplicationCredentialType = 'public' | 'confidential' | 'service';
+/**
+ * Credential kind.
+ *
+ * The first three are OAuth clients: the `oxy_dk_…` `publicKey` is the
+ * `client_id`, and any secret is presented BESIDE it. `service` credentials
+ * additionally mint service tokens.
+ *
+ * `machine` is the OpenAI-SDK-compatible API key (issue #972 §2.3): its
+ * credential material is ONE `oxy_sk_…` bearer string returned in `token`
+ * exactly once on create/rotate, never in `secret`.
+ */
+export type ApplicationCredentialType = 'public' | 'confidential' | 'service' | 'machine';
 /** Deployment environment an application credential is scoped to. */
 export type ApplicationEnvironment = 'development' | 'staging' | 'production';
 /** Application credential lifecycle status. */
@@ -386,6 +341,12 @@ export interface ApplicationCredential {
     applicationId: string;
     name: string;
     publicKey: string;
+    /**
+     * `oxy_sk_<id>` — the PUBLIC lookup half of a `machine` credential's bearer
+     * token, present only on that type. Safe to render: the secret half is 256
+     * bits that were shown exactly once and are never returned again.
+     */
+    tokenPrefix?: string;
     type: ApplicationCredentialType;
     environment: ApplicationEnvironment;
     scopes: string[];
@@ -441,23 +402,67 @@ export interface CreateApplicationCredentialInput {
     type: ApplicationCredentialType;
     environment: ApplicationEnvironment;
     scopes?: string[];
+    /**
+     * Lifetime of a `machine` credential, in seconds — 60 to 730 days. Omit for a
+     * key that does not expire on its own.
+     *
+     * **`machine` only.** On every other credential type `expires_at` means the
+     * rotation grace deadline, so a caller setting it at creation would make a
+     * brand-new credential indistinguishable from a rotated one. The server
+     * REJECTS it for those types rather than ignoring it, so sending it with the
+     * wrong `type` is a 400, not a silently dropped field.
+     */
+    expiresInSeconds?: number;
+}
+/** Input accepted by `rotateAppCredential`. */
+export interface RotateApplicationCredentialInput {
+    /**
+     * How long the superseded `machine` token keeps working, in seconds — 1 to 30
+     * days. Omitting it revokes the previous token the instant the replacement is
+     * minted, which is the safe default for a leaked key.
+     *
+     * **`machine` only, and opt-in.** `confidential`/`service` credentials always
+     * retire on the platform's fixed seven-day grace and the server REJECTS this
+     * field for them, so their contract is unchanged.
+     */
+    graceSeconds?: number;
 }
-/** Result of creating an application credential — `secret` is returned ONCE. */
+/**
+ * Result of creating an application credential — credential material is returned
+ * ONCE and can never be read back.
+ *
+ * Exactly one of the two fields carries it, decided by
+ * {@link ApplicationCredentialType}: `secret` for a `confidential`/`service`
+ * client, `token` for a `machine` API key, and NEITHER for a `public` client
+ * (`secret` is `null`). They are separate fields rather than one, so a surface
+ * that renders "the secret" cannot silently render an API key's bearer token
+ * under the wrong label, or a `null` where a token should be.
+ */
 export interface ApplicationCredentialWithSecret {
     credential: ApplicationCredential;
-    secret: string;
+    /** The OAuth client secret. `null` for `public` and `machine` credentials. */
+    secret: string | null;
+    /** The full `oxy_sk_…` bearer token. Present ONLY for a `machine` credential. */
+    token?: string;
 }
 /**
  * Result of rotating an application credential. Extends the create result with
- * audit fields: the new plaintext `secret` is returned ONCE, plus `rotatedFrom`
- * (the previous credential's `credentialId`) and `graceExpiresAt` (ISO string
- * marking when the old credential stops being honoured during the grace window).
+ * audit fields: the new credential material is returned ONCE, plus `rotatedFrom`
+ * (the previous credential's `credentialId`) and `graceExpiresAt`.
  */
 export interface RotateApplicationCredentialResult extends ApplicationCredentialWithSecret {
     /** The previous credential's `credentialId` that this rotation supersedes. */
     rotatedFrom: string;
-    /** ISO timestamp at which the rotated-from credential's grace window ends. */
-    graceExpiresAt: string;
+    /**
+     * ISO timestamp at which the rotated-from credential stops being honoured, or
+     * `null` when no grace window was configured and it was revoked outright.
+     *
+     * Nullable because a `machine` credential's grace is OPT-IN (issue #972 §2.3):
+     * rotating an API key without asking for a window kills the old token
+     * immediately, and there is then no deadline to report. The OAuth/service
+     * types always carry their fixed seven-day deadline.
+     */
+    graceExpiresAt: string | null;
 }
 /** Time window for application usage statistics. */
 export type ApplicationUsagePeriod = '24h' | '7d' | '30d' | '90d';
@@ -675,36 +680,6 @@ export declare function OxyServicesAccountsMixin<T extends typeof OxyServicesBas
          * @param data - Target user id.
          */
         transferAccountOwnership(accountId: string, data: TransferAccountOwnershipInput): Promise<AccountSuccessResult>;
-        /**
-         * List a bot account's service credentials. The response NEVER includes
-         * secrets.
-         * @param accountId - The account's Mongo `_id`.
-         */
-        listAccountCredentials(accountId: string): Promise<AccountCredential[]>;
-        /**
-         * 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`).
-         */
-        createAccountCredential(accountId: string, data: CreateAccountCredentialInput): Promise<AccountCredentialWithSecret>;
-        /**
-         * 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`.
-         */
-        rotateAccountCredential(accountId: string, credentialId: string): Promise<RotateAccountCredentialResult>;
-        /**
-         * 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`.
-         */
-        revokeAccountCredential(accountId: string, credentialId: string): Promise<AccountSuccessResult>;
         /**
          * List the applications owned by an account. Backed by
          * `GET /applications?ownerAccountId=<id>`.
@@ -753,8 +728,11 @@ export declare function OxyServicesAccountsMixin<T extends typeof OxyServicesBas
          * 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.
          */
-        rotateAppCredential(applicationId: string, credentialId: string): Promise<RotateApplicationCredentialResult>;
+        rotateAppCredential(applicationId: string, credentialId: string, options?: RotateApplicationCredentialInput): Promise<RotateApplicationCredentialResult>;
         /**
          * Revoke an application credential (`status='revoked'`). Revoked credentials
          * can no longer authenticate.