hanzoai 8.5.623 → 8.5.646

package/README.md

@@ -67,7 +67,10 @@ type Completion = { choices?: Array<{ message?: { content?: string } }> };
 
 async function main() {
   const { data } = await new AiApi(config).postChatCompletions({
-    data: { model: 'zen5', messages: [{ role: 'user', content: 'Say hello in five words.' }] },
+    openaiChatCompletionRequest: {
+      model: 'zen5',
+      messages: [{ role: 'user', content: 'Say hello in five words.' }],
+    },
   });
   const reply = data as unknown as Completion;
   console.log(reply.choices?.[0]?.message?.content);
@@ -82,8 +85,8 @@ those, construct a `Configuration` with no `accessToken` and the client sends no
 `Authorization` header.
 
 A generated call that gets a status outside 2xx throws axios's `AxiosError`,
-with the status on `err.response.status`, after one request; nothing is
-retried. A 200 whose body is an error object resolves like any other 200, and a
+with the status on `err.response.status`, after one request — or, for a usage
+refusal, its own class (below). Nothing is retried. A 200 whose body is an error object resolves like any other 200, and a
 completion's content comes back as the server sent it, `<think>` blocks
 included.
 
@@ -94,6 +97,55 @@ environment, and mints its own token rather than being handed one.
 `GET /v1/iam/oauth/userinfo` is how you check a token: it answers the token's
 identity, or `401 {"error":"invalid_token"}`. That is the `hello` flow below.
 
+## Plan usage
+
+Every AI answer says how it was paid for in `X-Hanzo-*` headers. `readUsage`
+reads them off an axios response, a fetch `Response` or a plain record; an
+absent header reads `undefined`.
+
+```ts
+import { AiApi, Configuration, ModelCapError, UsageLimitError, readUsage } from 'hanzoai';
+
+const ai = new AiApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
+try {
+  const res = await ai.postChatCompletions({
+    openaiChatCompletionRequest: { model: 'anthropic/claude-sonnet-4.5', messages },
+  });
+  readUsage(res.headers); // { usage: 'ok', usageClass: 'premium', paidBy: 'credits', served: '…', fallback: undefined, reason: undefined }
+} catch (err) {
+  if (err instanceof ModelCapError) retry(err.fallback);
+  else if (err instanceof UsageLimitError) offer(err.actions);
+  else throw err;
+}
+```
+
+A 402 or 429 refusal nothing may pay for throws a subclass of
+`UsageLimitError`, which carries `status`, `code`, `type`, `usageClass`,
+`model`, `fallback`, `resetsAt`, `upgradeUrl`, `actions`, `request` (the
+`x-request-id`) and, from a generated call, `cause` (the `AxiosError`):
+
+| class | status | `code` |
+|---|---|---|
+| `PlanAllowanceUsedError` | 402 | `plan_allowance_used` |
+| `PaidPlanRequiredError` | 402 | `paid_plan_required` |
+| `FreePlanCapError` | 429 | `free_plan_cap` |
+| `ModelCapError` | 402 | `model_cap` |
+| `UsageCapExceededError` | 429 | `usage_cap_exceeded` |
+| `InsufficientBalanceError` | 402 | `insufficient_balance` |
+
+Any other refusal stays an `AxiosError`, as does a refusal through an `*Api`
+built without the package's `Configuration` or with an axios instance of your
+own. A `responseType: 'stream'` JSON body is read for the code, within the
+request's `signal` and `timeout`, and left whole on `err.cause.response.data`. `Client`'s six throw
+these where they would throw `answer.Fault`; a 402 there is still the `denied`
+arm.
+
+The routes are generated: `aiLimits()` and `aiSetLimits({ aiLimitsSet: {
+creditsAfterAllowance } })` on `/v1/ai/limits`; `SyncApi`'s `getSync`,
+`getSyncById`, `postSync` and `postSyncByIdRun` ("sync now") on `/v1/sync`;
+`postDecisions`; and `getModels`, whose rows carry `class` (premium, ours or
+free), `family` and `pricing.variable`.
+
 ## The six capabilities
 
 Budget, policy, audit, search, kb and graph — the same six words in the Go,
@@ -166,7 +218,7 @@ Types are namespaced by capability: `budget.Allowance`, `search.Hit`,
 
 ## Examples
 
-Eight flows under [`examples/`](examples), one directory each, every one a
+Nine flows under [`examples/`](examples), one directory each, every one a
 complete program:
 
 | flow | what it does | routes |
@@ -179,6 +231,7 @@ complete program:
 | [`agent`](examples/agent) | create + run + read | `POST /v1/agent`, `POST /v1/agent/{ref}/run`, `GET /v1/agent/{ref}/runs` |
 | [`tools`](examples/tools) | tool catalog | `GET /v1/tool` |
 | [`six`](examples/six) | budget → policy → search → kb → graph → audit, in one pass | the six capabilities |
+| [`limits`](examples/limits) | plan, catalog by class, who paid, a typed refusal, repo links | `GET /v1/ai/limits`, `GET /v1/models`, `POST /v1/chat/completions`, `POST /v1/decisions`, `GET /v1/sync` |
 
 `models` runs with nothing exported:
 
@@ -189,8 +242,8 @@ npm ci && npm run build && npx tsx examples/models/index.ts
 (`npm run build` first because the examples import `hanzoai` by name and the
 package resolves its own name through `exports`, which points at `dist/`.)
 
-Six of the others read `HANZO_API_KEY` and `six` reads
-`HANZO_CLIENT_ID`/`HANZO_CLIENT_SECRET`; all eight talk to
+Seven of the others read `HANZO_API_KEY` and `six` reads
+`HANZO_CLIENT_ID`/`HANZO_CLIENT_SECRET`; all nine talk to
 `https://api.hanzo.ai` unless `HANZO_BASE_URL` says otherwise:
 
 ```bash
@@ -202,8 +255,9 @@ A token the server refuses answers `HTTP 401:
 {"error":"invalid_token","error_description":"the access token is invalid or
 revoked"}`.
 
-`npm run examples` type-checks all eight against the client, `npm run wire`
-runs the six against a scripted `fetch`, and `hanzo.yml` makes both a CI gate.
+`npm run examples` type-checks all nine against the client, `npm run wire`
+runs the six and the usage refusals against a scripted `fetch`, and `hanzo.yml`
+makes both a CI gate.
 
 ## The API surface
 
@@ -247,7 +301,8 @@ knob lives once, in that repo's `generate.py` and `sdks.yaml`.
 
 `.generated` lists what the driver owns. A file it does not name is this repo's
 own and a regeneration never touches it — which is where `hanzo.ts`,
-`client.ts`, `answer.ts` and the six capabilities live.
+`client.ts`, `answer.ts`, `usage.ts`, `transport.ts` and the six capabilities
+live.
 
 Requires java 17+ and [uv](https://docs.astral.sh/uv/).
 

package/dist/answer.js

@@ -15,6 +15,7 @@ exports.arm = arm;
 exports.value = value;
 exports.page = page;
 const read_1 = require("./read");
+const usage_1 = require("./usage");
 /**
  * An outcome with no decision in it.
  *
@@ -58,15 +59,17 @@ const refusals = new Set(['spend_cap_exceeded', 'insufficient_balance']);
 function refusal(body) {
     const b = (0, read_1.obj)(body);
     // RFC 9457 spells the code `code` and the sentence `detail`; the spend gate's
-    // own body spells them `error` and `message` and adds `product` and `cure[]`.
-    // Its own `reason` — "unpaid", "unresolved" — names the admit leg that failed
-    // rather than explaining anything to a person, so it is not read. One reader,
-    // named fallbacks — not two paths — so it keeps working unchanged when cloud
-    // settles on the envelope alone.
+    // own body spells them `error` and `message` and adds `product` and `cure[]`;
+    // the AI gateway's OpenAI envelope nests `code` and `message` under `error`.
+    // The spend gate's `reason` — "unpaid", "unresolved" — names the admit leg that
+    // failed rather than explaining anything to a person, so it is not read. One
+    // reader, named fallbacks — not three paths — so it keeps working unchanged
+    // when cloud settles on one envelope.
+    const e = (0, read_1.obj)(b['error']);
     const product = (0, read_1.str)(b['product']);
     return {
-        code: (0, read_1.str)(b['code']) || (0, read_1.str)(b['error']),
-        reason: (0, read_1.str)(b['detail']) || (0, read_1.str)(b['message']),
+        code: (0, read_1.str)(b['code']) || (0, read_1.str)(b['error']) || (0, read_1.str)(e['code']),
+        reason: (0, read_1.str)(b['detail']) || (0, read_1.str)(b['message']) || (0, read_1.str)(e['message']),
         ...(product ? { product } : {}),
         cures: (0, read_1.list)(b['cure']).map((c) => {
             const cure = (0, read_1.obj)(c);
@@ -107,14 +110,21 @@ function arm(r, read) {
     if (r.status === 402 || (r.status === 403 && refusals.has(said.code))) {
         return { status: 'denied', ...said, request: r.request };
     }
-    throw new Fault(r.status, said.code, said.reason || `HTTP ${r.status}`, r.request);
+    throw fault(r, said);
 }
 /** A read no gate refuses: the value, or a [Fault] because nothing was decided. */
 function value(r, read) {
     if (r.status >= 200 && r.status < 300)
         return read(r.body);
-    const said = refusal(r.body);
-    throw new Fault(r.status, said.code, said.reason || `HTTP ${r.status}`, r.request);
+    throw fault(r, refusal(r.body));
+}
+/**
+ * What a call that decided nothing throws: the usage refusal the body names
+ * (usage.ts), or a [Fault]. What [arm] reads as [Denied] never reaches here.
+ */
+function fault(r, said) {
+    return ((0, usage_1.limited)(r.status, r.body, r.request || undefined) ??
+        new Fault(r.status, said.code, said.reason || `HTTP ${r.status}`, r.request));
 }
 /** `{data, total}` — the page shape every listing on this wire answers with. */
 function page(body, read) {

package/dist/api/account-api.d.ts

@@ -13,28 +13,28 @@ import type { Configuration } from '../configuration';
 import type { AxiosPromise, AxiosInstance, RawAxiosRequestConfig } from 'axios';
 import globalAxios from 'axios';
 import { type RequestArgs, BaseAPI } from '../base';
+import type { AccountApiKey } from '../models';
 import type { AccountApiKeyList } from '../models';
 import type { AccountAppearance } from '../models';
 import type { AccountCsrfResp } from '../models';
 import type { AccountEmbedStatusResp } from '../models';
-import type { AccountKeyTypeIn } from '../models';
-import type { AccountMintedKey } from '../models';
+import type { AccountKeyEdit } from '../models';
+import type { AccountKeyIn } from '../models';
 import type { AccountOnboardReq } from '../models';
 import type { AccountOnboardResp } from '../models';
-import type { AccountRevokedKey } from '../models';
 /**
  * AccountApi - axios parameter creator
  * @export
  */
 export declare const AccountApiAxiosParamCreator: (configuration?: Configuration) => {
     /**
-     * Revokes the caller\'s own API key of the requested class. The class is the same field mint takes — `?type=publishable`, defaulting to secret — so revoking the key that ships in a browser bundle does not sign its holder out of their own API: the other key keeps working.  Revoking is how a key is replaced when it does not need replacing; minting the same class again rotates it in one step. IAM drops the credential immediately, but cloud caches a home key\'s principal for up to 60s, so a request inside that window may still be served. A member\'s key is never cached.  For callers written against the older shape, the class is also accepted in a JSON request body, read only when `?type=` is absent.
-     * @summary Revokes the caller\'s own API key of the requested class.
-     * @param {string} [type] Type is the key class to act on: \"secret\" (sk-, session-equivalent, belongs on a server) or \"publishable\" (pk-, org-identifying, safe in a browser bundle). Omitted means secret, which is what every existing caller means.
+     * Revokes exactly one API key, by id. Every other key keeps working. The key stays listed as revoked, with who revoked it and when, and can never be used again. IAM refuses it at once; cloud caches a resolved key for up to 60 seconds, so a request inside that window may still be served.  A member revokes their own keys; an org admin revokes any of the org\'s, and revoking someone else\'s is recorded on the audit trail.
+     * @summary Revokes exactly one API key, by id.
+     * @param {string} id ID is the key to act on, from the path.
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
      */
-    deleteAccountKeys: (type?: string, options?: RawAxiosRequestConfig) => Promise<RequestArgs>;
+    deleteAccountKeysById: (id: string, options?: RawAxiosRequestConfig) => Promise<RequestArgs>;
     /**
      * Returns the signed-in caller\'s own appearance preference — text size, density and accent — read from their IAM account so it is the same on every device and every Hanzo surface. An unset preference is an empty object.  A transient IAM read failure reports the empty preference rather than a 5xx, so a surface applies its published default and never error-toasts on load — the same fail-soft the key read uses.
      * @summary Returns the signed-in caller\'s own appearance preference — text size, density and accent — read from their IAM account so it is the same on every device and every Hanzo surface.
@@ -68,12 +68,21 @@ export declare const AccountApiAxiosParamCreator: (configuration?: Configuration
      */
     getAccountEmbed: (app?: string, options?: RawAxiosRequestConfig) => Promise<RequestArgs>;
     /**
-     * Returns the caller\'s own API keys — every type they hold, read AUTHORITATIVELY from IAM rather than from the session claim, which lags a key minted moments ago. No secret material comes back: a secret key is represented by its prefix, and only a publishable key (public by construction) carries its full value.  A transient IAM read failure reports an empty set rather than a 5xx, so the page shows the honest empty state and never a fabricated key.
-     * @summary Returns the caller\'s own API keys — every type they hold, read AUTHORITATIVELY from IAM rather than from the session claim, which lags a key minted moments ago.
+     * Returns the API keys the caller may see, newest first: their own, or every key the org holds when the caller administers it. Each is its own credential with its own name, prefix, status, expiry and limit. Revoked keys stay listed. No secret material comes back; a publishable key, which is public by construction, carries its full value.
+     * @summary Returns the API keys the caller may see, newest first: their own, or every key the org holds when the caller administers it.
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
      */
     getAccountKeys: (options?: RawAxiosRequestConfig) => Promise<RequestArgs>;
+    /**
+     * Changes one key\'s name, permissions, budget, rate or expiry. The secret is not reissued: the key in your deployment keeps working, under its new policy. Only the person the key belongs to may edit it, and a revoked key cannot be edited.
+     * @summary Changes one key\'s name, permissions, budget, rate or expiry.
+     * @param {string} id ID is the key to edit, from the path.
+     * @param {AccountKeyEdit} accountKeyEdit
+     * @param {*} [options] Override http request option.
+     * @throws {RequiredError}
+     */
+    patchAccountKeysById: (id: string, accountKeyEdit: AccountKeyEdit, options?: RawAxiosRequestConfig) => Promise<RequestArgs>;
     /**
      * Stores the caller\'s appearance preference on their IAM account, preserving every other field of the row. The accent is validated as a real colour token before it is stored; an unset or invalid axis is dropped rather than stored.
      * @summary Stores the caller\'s appearance preference on their IAM account, preserving every other field of the row.
@@ -90,13 +99,13 @@ export declare const AccountApiAxiosParamCreator: (configuration?: Configuration
      */
     postAccountAvatar: (options?: RawAxiosRequestConfig) => Promise<RequestArgs>;
     /**
-     * Creates — or rotates — the caller\'s API key of the requested type and returns it ONCE. A real IAM failure surfaces as 502, never a fabricated key.  Rotating is what creating means here: a user holds one key per type, so the endpoint is idempotent by (caller, type) and the superseded credential stops working. Two live secrets for one user would make \"revoke my key\" a lie.
-     * @summary Creates — or rotates — the caller\'s API key of the requested type and returns it ONCE.
-     * @param {AccountKeyTypeIn} accountKeyTypeIn
+     * Creates a NEW API key and returns its secret ONCE. It never revokes or changes any other key: every key the caller already holds keeps working. The key is filed in the org the caller acts in and names them as its creator.  An org holds at most 1,000 live keys; past that the create is refused until one is revoked.
+     * @summary Creates a NEW API key and returns its secret ONCE.
+     * @param {AccountKeyIn} accountKeyIn
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
      */
-    postAccountKeys: (accountKeyTypeIn: AccountKeyTypeIn, options?: RawAxiosRequestConfig) => Promise<RequestArgs>;
+    postAccountKeys: (accountKeyIn: AccountKeyIn, options?: RawAxiosRequestConfig) => Promise<RequestArgs>;
     /**
      * Creates the caller\'s organization. Two flows, keyed on whether the caller already has a home org (mirrors app/onboard/route.ts):    - FIRST-RUN (no home org): create + MOVE the user in as admin, so their next     JWT carries the new owner and the cloud scopes everything to it. This is the     path a fresh OAuth sign-up takes, from the sign-up application\'s org.   - ADDITIONAL (owner set): create the org but do NOT move the user — a move     changes their IAM owner (stripping a SuperAdmin\'s status + orphaning their     current org). They reach the new org via the OrgSwitcher, which re-scopes     X-Org-Id without touching IAM membership. A personal-org request from someone     who already has an org is meaningless → 409.
      * @summary Creates the caller\'s organization.
@@ -112,13 +121,13 @@ export declare const AccountApiAxiosParamCreator: (configuration?: Configuration
  */
 export declare const AccountApiFp: (configuration?: Configuration) => {
     /**
-     * Revokes the caller\'s own API key of the requested class. The class is the same field mint takes — `?type=publishable`, defaulting to secret — so revoking the key that ships in a browser bundle does not sign its holder out of their own API: the other key keeps working.  Revoking is how a key is replaced when it does not need replacing; minting the same class again rotates it in one step. IAM drops the credential immediately, but cloud caches a home key\'s principal for up to 60s, so a request inside that window may still be served. A member\'s key is never cached.  For callers written against the older shape, the class is also accepted in a JSON request body, read only when `?type=` is absent.
-     * @summary Revokes the caller\'s own API key of the requested class.
-     * @param {string} [type] Type is the key class to act on: \&quot;secret\&quot; (sk-, session-equivalent, belongs on a server) or \&quot;publishable\&quot; (pk-, org-identifying, safe in a browser bundle). Omitted means secret, which is what every existing caller means.
+     * Revokes exactly one API key, by id. Every other key keeps working. The key stays listed as revoked, with who revoked it and when, and can never be used again. IAM refuses it at once; cloud caches a resolved key for up to 60 seconds, so a request inside that window may still be served.  A member revokes their own keys; an org admin revokes any of the org\'s, and revoking someone else\'s is recorded on the audit trail.
+     * @summary Revokes exactly one API key, by id.
+     * @param {string} id ID is the key to act on, from the path.
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
      */
-    deleteAccountKeys(type?: string, options?: RawAxiosRequestConfig): Promise<(axios?: AxiosInstance, basePath?: string) => AxiosPromise<AccountRevokedKey>>;
+    deleteAccountKeysById(id: string, options?: RawAxiosRequestConfig): Promise<(axios?: AxiosInstance, basePath?: string) => AxiosPromise<AccountApiKey>>;
     /**
      * Returns the signed-in caller\'s own appearance preference — text size, density and accent — read from their IAM account so it is the same on every device and every Hanzo surface. An unset preference is an empty object.  A transient IAM read failure reports the empty preference rather than a 5xx, so a surface applies its published default and never error-toasts on load — the same fail-soft the key read uses.
      * @summary Returns the signed-in caller\'s own appearance preference — text size, density and accent — read from their IAM account so it is the same on every device and every Hanzo surface.
@@ -152,12 +161,21 @@ export declare const AccountApiFp: (configuration?: Configuration) => {
      */
     getAccountEmbed(app?: string, options?: RawAxiosRequestConfig): Promise<(axios?: AxiosInstance, basePath?: string) => AxiosPromise<AccountEmbedStatusResp>>;
     /**
-     * Returns the caller\'s own API keys — every type they hold, read AUTHORITATIVELY from IAM rather than from the session claim, which lags a key minted moments ago. No secret material comes back: a secret key is represented by its prefix, and only a publishable key (public by construction) carries its full value.  A transient IAM read failure reports an empty set rather than a 5xx, so the page shows the honest empty state and never a fabricated key.
-     * @summary Returns the caller\'s own API keys — every type they hold, read AUTHORITATIVELY from IAM rather than from the session claim, which lags a key minted moments ago.
+     * Returns the API keys the caller may see, newest first: their own, or every key the org holds when the caller administers it. Each is its own credential with its own name, prefix, status, expiry and limit. Revoked keys stay listed. No secret material comes back; a publishable key, which is public by construction, carries its full value.
+     * @summary Returns the API keys the caller may see, newest first: their own, or every key the org holds when the caller administers it.
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
      */
     getAccountKeys(options?: RawAxiosRequestConfig): Promise<(axios?: AxiosInstance, basePath?: string) => AxiosPromise<AccountApiKeyList>>;
+    /**
+     * Changes one key\'s name, permissions, budget, rate or expiry. The secret is not reissued: the key in your deployment keeps working, under its new policy. Only the person the key belongs to may edit it, and a revoked key cannot be edited.
+     * @summary Changes one key\'s name, permissions, budget, rate or expiry.
+     * @param {string} id ID is the key to edit, from the path.
+     * @param {AccountKeyEdit} accountKeyEdit
+     * @param {*} [options] Override http request option.
+     * @throws {RequiredError}
+     */
+    patchAccountKeysById(id: string, accountKeyEdit: AccountKeyEdit, options?: RawAxiosRequestConfig): Promise<(axios?: AxiosInstance, basePath?: string) => AxiosPromise<AccountApiKey>>;
     /**
      * Stores the caller\'s appearance preference on their IAM account, preserving every other field of the row. The accent is validated as a real colour token before it is stored; an unset or invalid axis is dropped rather than stored.
      * @summary Stores the caller\'s appearance preference on their IAM account, preserving every other field of the row.
@@ -174,13 +192,13 @@ export declare const AccountApiFp: (configuration?: Configuration) => {
      */
     postAccountAvatar(options?: RawAxiosRequestConfig): Promise<(axios?: AxiosInstance, basePath?: string) => AxiosPromise<void>>;
     /**
-     * Creates — or rotates — the caller\'s API key of the requested type and returns it ONCE. A real IAM failure surfaces as 502, never a fabricated key.  Rotating is what creating means here: a user holds one key per type, so the endpoint is idempotent by (caller, type) and the superseded credential stops working. Two live secrets for one user would make \"revoke my key\" a lie.
-     * @summary Creates — or rotates — the caller\'s API key of the requested type and returns it ONCE.
-     * @param {AccountKeyTypeIn} accountKeyTypeIn
+     * Creates a NEW API key and returns its secret ONCE. It never revokes or changes any other key: every key the caller already holds keeps working. The key is filed in the org the caller acts in and names them as its creator.  An org holds at most 1,000 live keys; past that the create is refused until one is revoked.
+     * @summary Creates a NEW API key and returns its secret ONCE.
+     * @param {AccountKeyIn} accountKeyIn
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
      */
-    postAccountKeys(accountKeyTypeIn: AccountKeyTypeIn, options?: RawAxiosRequestConfig): Promise<(axios?: AxiosInstance, basePath?: string) => AxiosPromise<AccountMintedKey>>;
+    postAccountKeys(accountKeyIn: AccountKeyIn, options?: RawAxiosRequestConfig): Promise<(axios?: AxiosInstance, basePath?: string) => AxiosPromise<AccountApiKey>>;
     /**
      * Creates the caller\'s organization. Two flows, keyed on whether the caller already has a home org (mirrors app/onboard/route.ts):    - FIRST-RUN (no home org): create + MOVE the user in as admin, so their next     JWT carries the new owner and the cloud scopes everything to it. This is the     path a fresh OAuth sign-up takes, from the sign-up application\'s org.   - ADDITIONAL (owner set): create the org but do NOT move the user — a move     changes their IAM owner (stripping a SuperAdmin\'s status + orphaning their     current org). They reach the new org via the OrgSwitcher, which re-scopes     X-Org-Id without touching IAM membership. A personal-org request from someone     who already has an org is meaningless → 409.
      * @summary Creates the caller\'s organization.
@@ -196,13 +214,13 @@ export declare const AccountApiFp: (configuration?: Configuration) => {
  */
 export declare const AccountApiFactory: (configuration?: Configuration, basePath?: string, axios?: AxiosInstance) => {
     /**
-     * Revokes the caller\'s own API key of the requested class. The class is the same field mint takes — `?type=publishable`, defaulting to secret — so revoking the key that ships in a browser bundle does not sign its holder out of their own API: the other key keeps working.  Revoking is how a key is replaced when it does not need replacing; minting the same class again rotates it in one step. IAM drops the credential immediately, but cloud caches a home key\'s principal for up to 60s, so a request inside that window may still be served. A member\'s key is never cached.  For callers written against the older shape, the class is also accepted in a JSON request body, read only when `?type=` is absent.
-     * @summary Revokes the caller\'s own API key of the requested class.
-     * @param {AccountApiDeleteAccountKeysRequest} requestParameters Request parameters.
+     * Revokes exactly one API key, by id. Every other key keeps working. The key stays listed as revoked, with who revoked it and when, and can never be used again. IAM refuses it at once; cloud caches a resolved key for up to 60 seconds, so a request inside that window may still be served.  A member revokes their own keys; an org admin revokes any of the org\'s, and revoking someone else\'s is recorded on the audit trail.
+     * @summary Revokes exactly one API key, by id.
+     * @param {AccountApiDeleteAccountKeysByIdRequest} requestParameters Request parameters.
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
      */
-    deleteAccountKeys(requestParameters?: AccountApiDeleteAccountKeysRequest, options?: RawAxiosRequestConfig): AxiosPromise<AccountRevokedKey>;
+    deleteAccountKeysById(requestParameters: AccountApiDeleteAccountKeysByIdRequest, options?: RawAxiosRequestConfig): AxiosPromise<AccountApiKey>;
     /**
      * Returns the signed-in caller\'s own appearance preference — text size, density and accent — read from their IAM account so it is the same on every device and every Hanzo surface. An unset preference is an empty object.  A transient IAM read failure reports the empty preference rather than a 5xx, so a surface applies its published default and never error-toasts on load — the same fail-soft the key read uses.
      * @summary Returns the signed-in caller\'s own appearance preference — text size, density and accent — read from their IAM account so it is the same on every device and every Hanzo surface.
@@ -234,12 +252,20 @@ export declare const AccountApiFactory: (configuration?: Configuration, basePath
      */
     getAccountEmbed(requestParameters?: AccountApiGetAccountEmbedRequest, options?: RawAxiosRequestConfig): AxiosPromise<AccountEmbedStatusResp>;
     /**
-     * Returns the caller\'s own API keys — every type they hold, read AUTHORITATIVELY from IAM rather than from the session claim, which lags a key minted moments ago. No secret material comes back: a secret key is represented by its prefix, and only a publishable key (public by construction) carries its full value.  A transient IAM read failure reports an empty set rather than a 5xx, so the page shows the honest empty state and never a fabricated key.
-     * @summary Returns the caller\'s own API keys — every type they hold, read AUTHORITATIVELY from IAM rather than from the session claim, which lags a key minted moments ago.
+     * Returns the API keys the caller may see, newest first: their own, or every key the org holds when the caller administers it. Each is its own credential with its own name, prefix, status, expiry and limit. Revoked keys stay listed. No secret material comes back; a publishable key, which is public by construction, carries its full value.
+     * @summary Returns the API keys the caller may see, newest first: their own, or every key the org holds when the caller administers it.
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
      */
     getAccountKeys(options?: RawAxiosRequestConfig): AxiosPromise<AccountApiKeyList>;
+    /**
+     * Changes one key\'s name, permissions, budget, rate or expiry. The secret is not reissued: the key in your deployment keeps working, under its new policy. Only the person the key belongs to may edit it, and a revoked key cannot be edited.
+     * @summary Changes one key\'s name, permissions, budget, rate or expiry.
+     * @param {AccountApiPatchAccountKeysByIdRequest} requestParameters Request parameters.
+     * @param {*} [options] Override http request option.
+     * @throws {RequiredError}
+     */
+    patchAccountKeysById(requestParameters: AccountApiPatchAccountKeysByIdRequest, options?: RawAxiosRequestConfig): AxiosPromise<AccountApiKey>;
     /**
      * Stores the caller\'s appearance preference on their IAM account, preserving every other field of the row. The accent is validated as a real colour token before it is stored; an unset or invalid axis is dropped rather than stored.
      * @summary Stores the caller\'s appearance preference on their IAM account, preserving every other field of the row.
@@ -256,13 +282,13 @@ export declare const AccountApiFactory: (configuration?: Configuration, basePath
      */
     postAccountAvatar(options?: RawAxiosRequestConfig): AxiosPromise<void>;
     /**
-     * Creates — or rotates — the caller\'s API key of the requested type and returns it ONCE. A real IAM failure surfaces as 502, never a fabricated key.  Rotating is what creating means here: a user holds one key per type, so the endpoint is idempotent by (caller, type) and the superseded credential stops working. Two live secrets for one user would make \"revoke my key\" a lie.
-     * @summary Creates — or rotates — the caller\'s API key of the requested type and returns it ONCE.
+     * Creates a NEW API key and returns its secret ONCE. It never revokes or changes any other key: every key the caller already holds keeps working. The key is filed in the org the caller acts in and names them as its creator.  An org holds at most 1,000 live keys; past that the create is refused until one is revoked.
+     * @summary Creates a NEW API key and returns its secret ONCE.
      * @param {AccountApiPostAccountKeysRequest} requestParameters Request parameters.
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
      */
-    postAccountKeys(requestParameters: AccountApiPostAccountKeysRequest, options?: RawAxiosRequestConfig): AxiosPromise<AccountMintedKey>;
+    postAccountKeys(requestParameters: AccountApiPostAccountKeysRequest, options?: RawAxiosRequestConfig): AxiosPromise<AccountApiKey>;
     /**
      * Creates the caller\'s organization. Two flows, keyed on whether the caller already has a home org (mirrors app/onboard/route.ts):    - FIRST-RUN (no home org): create + MOVE the user in as admin, so their next     JWT carries the new owner and the cloud scopes everything to it. This is the     path a fresh OAuth sign-up takes, from the sign-up application\'s org.   - ADDITIONAL (owner set): create the org but do NOT move the user — a move     changes their IAM owner (stripping a SuperAdmin\'s status + orphaning their     current org). They reach the new org via the OrgSwitcher, which re-scopes     X-Org-Id without touching IAM membership. A personal-org request from someone     who already has an org is meaningless → 409.
      * @summary Creates the caller\'s organization.
@@ -273,17 +299,17 @@ export declare const AccountApiFactory: (configuration?: Configuration, basePath
     postAccountOrgs(requestParameters: AccountApiPostAccountOrgsRequest, options?: RawAxiosRequestConfig): AxiosPromise<AccountOnboardResp>;
 };
 /**
- * Request parameters for deleteAccountKeys operation in AccountApi.
+ * Request parameters for deleteAccountKeysById operation in AccountApi.
  * @export
- * @interface AccountApiDeleteAccountKeysRequest
+ * @interface AccountApiDeleteAccountKeysByIdRequest
  */
-export interface AccountApiDeleteAccountKeysRequest {
+export interface AccountApiDeleteAccountKeysByIdRequest {
     /**
-     * Type is the key class to act on: \&quot;secret\&quot; (sk-, session-equivalent, belongs on a server) or \&quot;publishable\&quot; (pk-, org-identifying, safe in a browser bundle). Omitted means secret, which is what every existing caller means.
+     * ID is the key to act on, from the path.
      * @type {string}
-     * @memberof AccountApiDeleteAccountKeys
+     * @memberof AccountApiDeleteAccountKeysById
      */
-    readonly type?: string;
+    readonly id: string;
 }
 /**
  * Request parameters for getAccountAvatarByOrgByUserByDigest operation in AccountApi.
@@ -323,6 +349,25 @@ export interface AccountApiGetAccountEmbedRequest {
      */
     readonly app?: string;
 }
+/**
+ * Request parameters for patchAccountKeysById operation in AccountApi.
+ * @export
+ * @interface AccountApiPatchAccountKeysByIdRequest
+ */
+export interface AccountApiPatchAccountKeysByIdRequest {
+    /**
+     * ID is the key to edit, from the path.
+     * @type {string}
+     * @memberof AccountApiPatchAccountKeysById
+     */
+    readonly id: string;
+    /**
+     *
+     * @type {AccountKeyEdit}
+     * @memberof AccountApiPatchAccountKeysById
+     */
+    readonly accountKeyEdit: AccountKeyEdit;
+}
 /**
  * Request parameters for postAccountAppearance operation in AccountApi.
  * @export
@@ -344,10 +389,10 @@ export interface AccountApiPostAccountAppearanceRequest {
 export interface AccountApiPostAccountKeysRequest {
     /**
      *
-     * @type {AccountKeyTypeIn}
+     * @type {AccountKeyIn}
      * @memberof AccountApiPostAccountKeys
      */
-    readonly accountKeyTypeIn: AccountKeyTypeIn;
+    readonly accountKeyIn: AccountKeyIn;
 }
 /**
  * Request parameters for postAccountOrgs operation in AccountApi.
@@ -370,14 +415,14 @@ export interface AccountApiPostAccountOrgsRequest {
  */
 export declare class AccountApi extends BaseAPI {
     /**
-     * Revokes the caller\'s own API key of the requested class. The class is the same field mint takes — `?type=publishable`, defaulting to secret — so revoking the key that ships in a browser bundle does not sign its holder out of their own API: the other key keeps working.  Revoking is how a key is replaced when it does not need replacing; minting the same class again rotates it in one step. IAM drops the credential immediately, but cloud caches a home key\'s principal for up to 60s, so a request inside that window may still be served. A member\'s key is never cached.  For callers written against the older shape, the class is also accepted in a JSON request body, read only when `?type=` is absent.
-     * @summary Revokes the caller\'s own API key of the requested class.
-     * @param {AccountApiDeleteAccountKeysRequest} requestParameters Request parameters.
+     * Revokes exactly one API key, by id. Every other key keeps working. The key stays listed as revoked, with who revoked it and when, and can never be used again. IAM refuses it at once; cloud caches a resolved key for up to 60 seconds, so a request inside that window may still be served.  A member revokes their own keys; an org admin revokes any of the org\'s, and revoking someone else\'s is recorded on the audit trail.
+     * @summary Revokes exactly one API key, by id.
+     * @param {AccountApiDeleteAccountKeysByIdRequest} requestParameters Request parameters.
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
      * @memberof AccountApi
      */
-    deleteAccountKeys(requestParameters?: AccountApiDeleteAccountKeysRequest, options?: RawAxiosRequestConfig): Promise<globalAxios.AxiosResponse<AccountRevokedKey, any, {}>>;
+    deleteAccountKeysById(requestParameters: AccountApiDeleteAccountKeysByIdRequest, options?: RawAxiosRequestConfig): Promise<globalAxios.AxiosResponse<AccountApiKey, any, {}>>;
     /**
      * Returns the signed-in caller\'s own appearance preference — text size, density and accent — read from their IAM account so it is the same on every device and every Hanzo surface. An unset preference is an empty object.  A transient IAM read failure reports the empty preference rather than a 5xx, so a surface applies its published default and never error-toasts on load — the same fail-soft the key read uses.
      * @summary Returns the signed-in caller\'s own appearance preference — text size, density and accent — read from their IAM account so it is the same on every device and every Hanzo surface.
@@ -413,13 +458,22 @@ export declare class AccountApi extends BaseAPI {
      */
     getAccountEmbed(requestParameters?: AccountApiGetAccountEmbedRequest, options?: RawAxiosRequestConfig): Promise<globalAxios.AxiosResponse<AccountEmbedStatusResp, any, {}>>;
     /**
-     * Returns the caller\'s own API keys — every type they hold, read AUTHORITATIVELY from IAM rather than from the session claim, which lags a key minted moments ago. No secret material comes back: a secret key is represented by its prefix, and only a publishable key (public by construction) carries its full value.  A transient IAM read failure reports an empty set rather than a 5xx, so the page shows the honest empty state and never a fabricated key.
-     * @summary Returns the caller\'s own API keys — every type they hold, read AUTHORITATIVELY from IAM rather than from the session claim, which lags a key minted moments ago.
+     * Returns the API keys the caller may see, newest first: their own, or every key the org holds when the caller administers it. Each is its own credential with its own name, prefix, status, expiry and limit. Revoked keys stay listed. No secret material comes back; a publishable key, which is public by construction, carries its full value.
+     * @summary Returns the API keys the caller may see, newest first: their own, or every key the org holds when the caller administers it.
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
      * @memberof AccountApi
      */
     getAccountKeys(options?: RawAxiosRequestConfig): Promise<globalAxios.AxiosResponse<AccountApiKeyList, any, {}>>;
+    /**
+     * Changes one key\'s name, permissions, budget, rate or expiry. The secret is not reissued: the key in your deployment keeps working, under its new policy. Only the person the key belongs to may edit it, and a revoked key cannot be edited.
+     * @summary Changes one key\'s name, permissions, budget, rate or expiry.
+     * @param {AccountApiPatchAccountKeysByIdRequest} requestParameters Request parameters.
+     * @param {*} [options] Override http request option.
+     * @throws {RequiredError}
+     * @memberof AccountApi
+     */
+    patchAccountKeysById(requestParameters: AccountApiPatchAccountKeysByIdRequest, options?: RawAxiosRequestConfig): Promise<globalAxios.AxiosResponse<AccountApiKey, any, {}>>;
     /**
      * Stores the caller\'s appearance preference on their IAM account, preserving every other field of the row. The accent is validated as a real colour token before it is stored; an unset or invalid axis is dropped rather than stored.
      * @summary Stores the caller\'s appearance preference on their IAM account, preserving every other field of the row.
@@ -438,14 +492,14 @@ export declare class AccountApi extends BaseAPI {
      */
     postAccountAvatar(options?: RawAxiosRequestConfig): Promise<globalAxios.AxiosResponse<void, any, {}>>;
     /**
-     * Creates — or rotates — the caller\'s API key of the requested type and returns it ONCE. A real IAM failure surfaces as 502, never a fabricated key.  Rotating is what creating means here: a user holds one key per type, so the endpoint is idempotent by (caller, type) and the superseded credential stops working. Two live secrets for one user would make \"revoke my key\" a lie.
-     * @summary Creates — or rotates — the caller\'s API key of the requested type and returns it ONCE.
+     * Creates a NEW API key and returns its secret ONCE. It never revokes or changes any other key: every key the caller already holds keeps working. The key is filed in the org the caller acts in and names them as its creator.  An org holds at most 1,000 live keys; past that the create is refused until one is revoked.
+     * @summary Creates a NEW API key and returns its secret ONCE.
      * @param {AccountApiPostAccountKeysRequest} requestParameters Request parameters.
      * @param {*} [options] Override http request option.
      * @throws {RequiredError}
      * @memberof AccountApi
      */
-    postAccountKeys(requestParameters: AccountApiPostAccountKeysRequest, options?: RawAxiosRequestConfig): Promise<globalAxios.AxiosResponse<AccountMintedKey, any, {}>>;
+    postAccountKeys(requestParameters: AccountApiPostAccountKeysRequest, options?: RawAxiosRequestConfig): Promise<globalAxios.AxiosResponse<AccountApiKey, any, {}>>;
     /**
      * Creates the caller\'s organization. Two flows, keyed on whether the caller already has a home org (mirrors app/onboard/route.ts):    - FIRST-RUN (no home org): create + MOVE the user in as admin, so their next     JWT carries the new owner and the cloud scopes everything to it. This is the     path a fresh OAuth sign-up takes, from the sign-up application\'s org.   - ADDITIONAL (owner set): create the org but do NOT move the user — a move     changes their IAM owner (stripping a SuperAdmin\'s status + orphaning their     current org). They reach the new org via the OrgSwitcher, which re-scopes     X-Org-Id without touching IAM membership. A personal-org request from someone     who already has an org is meaningless → 409.
      * @summary Creates the caller\'s organization.