@gemmein/sdk 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -120,13 +120,13 @@ export type AuthSession = {
  *  second module). `scripts/sync-version.mjs` rewrites the literal from
  *  package.json before every build (`prebuild`), and a test pins the two
  *  equal, so a bump can never ship with a stale header. */
-export declare const SDK_VERSION = "0.6.0";
+export declare const SDK_VERSION = "0.7.0";
 /** W9.1 / CLIENT-INFO-1: every request the SDK makes to Gemmein carries
  *  `x-client-info: gemmein-sdk/<version>`. The server records it on the
  *  secret-key usage ledger ("last seen from gemmein-sdk/0.5.0"), so a
  *  misbehaving integration can be attributed to an SDK version from day
  *  one. It is a report, not a proof — any caller can set it. */
-export declare const CLIENT_INFO = "gemmein-sdk/0.6.0";
+export declare const CLIENT_INFO = "gemmein-sdk/0.7.0";
 export declare class GemmeinError extends Error {
     readonly status: number;
     readonly code: string;
@@ -183,6 +183,10 @@ export declare class Gemmein {
     readonly purchases: PurchasesClient;
     readonly account: AccountClient;
     readonly files: FilesClient;
+    /** W9.3 — the signed-in person's own credit balance (engine 0.8.0). */
+    readonly credits: CreditsClient;
+    /** W9.3 — the AI route: OpenAI / Anthropic / Google on the owner's key. */
+    readonly ai: AiClient;
     constructor(options: GemmeinOptions);
     /**
      * Your app's data — `g.collection<{ title: string }>("notes")`. The
@@ -382,6 +386,93 @@ export declare class AccountClient {
      */
     delete(): Promise<unknown>;
 }
+export type AiProvider = "openai" | "anthropic" | "google";
+export type AiChatOptions = {
+    /** Which configured provider answers. Optional when exactly one key is
+     *  set; refused `provider_required` (400) when it is ambiguous. */
+    provider?: AiProvider;
+    /** Abort the call — the stream closes; a call that dies mid-stream is
+     *  not refunded. */
+    signal?: AbortSignal;
+};
+/** `spendCredits`'s answer: `spent` is the amount taken (0 on a deduped
+ *  repeat); `event` is the ledger line — the same one on a repeat. */
+export type SpendCreditsResult = {
+    ok: true;
+    spent: number;
+    deduped: boolean;
+    balance: {
+        before: number;
+        after: number;
+    };
+    event: {
+        id: string;
+        reason: string | null;
+        actor: string;
+    };
+};
+/** The signed-in person's own credits — so an app can draw its own meter. */
+export declare class CreditsClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    /**
+     * The balance RIGHT NOW, server-resolved — the number that refuses at
+     * zero, never client math. Session required (`session_required`, 401).
+     *
+     *   const { balance } = await g.credits.balance();
+     */
+    balance(): Promise<{
+        balance: number;
+    }>;
+}
+/**
+ * The AI route. `chat` takes the provider's own request body — exactly what
+ * you would POST to OpenAI's /v1/chat/completions, Anthropic's /v1/messages
+ * or Google's generateContent — and answers with the fetch `Response`
+ * untouched, streaming intact (SSE stays SSE). Gemmein spends one credit,
+ * adds the owner's key, forwards, and passes status and bytes back.
+ * Response headers: `x-gemmein-credits-remaining` on every answer that
+ * passed the spend; `x-gemmein-credit: refunded` when the provider failed
+ * before its first byte.
+ */
+export declare class AiClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    /**
+     *   const res = await g.ai.chat({ model: "gpt-4o-mini", messages, stream: true });
+     *   for await (const chunk of res.body) { … }
+     *
+     * Browser sessions only — a server key is refused (`scope_denied`, 403).
+     * Refusals, all `GemmeinError`: `session_required` (401) ·
+     * `credits_exhausted` (402 — the message carries the balance; show your
+     * own "buy more" door, which is a product checkout) · `ai_not_configured`
+     * (409 — the owner has set no key) · `provider_required` (400) ·
+     * `model_not_allowed` (403 — the owner's models list) · `ai_capped`
+     * (429 — 20 calls a minute per person; `err.resetAt`) ·
+     * `payload_too_large` (413 — 256 KB) · `provider_unreachable` (502,
+     * before the first byte, refunded). Those are GEMMEIN's refusals. The
+     * PROVIDER's own answer — 2xx or not — is returned as it came: an answer
+     * that carries `x-gemmein-credits-remaining` (or `x-gemmein-credit`)
+     * passed the spend, so its status and body are the provider's; read
+     * `res.ok` / `res.status` yourself (a provider 4xx before the first byte
+     * is refunded, header `x-gemmein-credit: refunded`).
+     */
+    chat(body: Record<string, unknown>, options?: AiChatOptions): Promise<Response>;
+    /**
+     * The non-streaming convenience: one call, one string. Pass a body that
+     * does NOT stream (`stream` unset or false); the provider's JSON answer is
+     * read whole and the text is lifted out per provider — OpenAI
+     * `choices[0].message.content`, Anthropic `content[].text` joined,
+     * Google `candidates[0].content.parts[].text` joined. An answer with no
+     * text in any of those places throws `invalid_response` (status 0). A
+     * provider's own non-2xx throws `provider_error` with the provider's
+     * status and the provider's message (the owner's key masked to its
+     * hint if the provider echoed it).
+     *
+     *   const answer = await g.ai.text({ model: "claude-sonnet-4-5", max_tokens: 400, messages });
+     */
+    text(body: Record<string, unknown>, options?: AiChatOptions): Promise<string>;
+}
 export declare class StorageClient {
     private readonly config;
     constructor(config: ClientConfig);
@@ -562,9 +653,11 @@ export type Grant = {
 /**
  * What a person holds RIGHT NOW — never what they pay. `access` is the
  * union of live grants' keys; `grants` lists those live grants (revoked
- * and expired ones are gone, not flagged). `credits` is a reserved slot:
- * it is `null` today because consumable credits are not shipped — don't
- * design around them until this type says otherwise.
+ * and expired ones are gone, not flagged). `credits` is `{ balance }` —
+ * filled from engine 0.8.0 (W9.3): the person's credit balance, floored
+ * at 0, the same number `g.credits.balance()` answers and the one the AI
+ * route and `spendCredits` refuse against. An engine before 0.8.0 answers
+ * `null` here — read it as "not carried", never as zero.
  */
 export type Holdings = {
     access: string[];
@@ -760,6 +853,38 @@ export declare class GemmeinServer {
         grant: Grant;
         holdings: Holdings;
     }>;
+    /**
+     * W9.3 — spend a person's credits from YOUR server, with a reason:
+     *
+     *   const { balance } = await g.spendCredits(personId, {
+     *     amount: 5,                       // default 1; 1..10,000 per call
+     *     reason: "render:4k",             // what the owner reads in the ledger
+     *     key: `render:${jobId}`,          // your retry key — a repeat is deduped
+     *   });
+     *   // { ok: true, spent: 5, deduped: false, balance: { before: 20, after: 15 },
+     *   //   event: { id: "cev_…", reason: "render:4k", actor: "<your key's name>" } }
+     *
+     * ONE conditional update, floored at 0: the spend succeeds whole or not at
+     * all, and `402 credits_exhausted` says "this person has {balance} credits
+     * — the spend needs {amount}". Pass `key` when the caller can retry — the
+     * same key answers the first spend again with `deduped: true`, `spent: 0`,
+     * the same `event` and the balance untouched. The key is scoped to the
+     * person: one order id reused for two people charges both. Credits come
+     * from a pack they bought, a comp in the back office, or a relay; a key
+     * cannot mint them.
+     *
+     * Needs the key's "Spend a person's credits" box ticked by your human.
+     * Refusals: `capability_required` (403 — "this key can't spend credits —
+     * mint a key with 'Spend a person's credits' ticked") ·
+     * `credits_exhausted` (402) · `person_not_found` (404) · `invalid_amount` /
+     * `invalid_reason` / `invalid_key` (400) · `dedupe_conflict` (409 — the
+     * key already names a different movement).
+     */
+    spendCredits(personId: string, input: {
+        amount?: number;
+        reason: string;
+        key?: string;
+    }): Promise<SpendCreditsResult>;
     /**
      * End one grant — the reversibility law in one call:
      *

package/dist/index.d.ts

@@ -120,13 +120,13 @@ export type AuthSession = {
  *  second module). `scripts/sync-version.mjs` rewrites the literal from
  *  package.json before every build (`prebuild`), and a test pins the two
  *  equal, so a bump can never ship with a stale header. */
-export declare const SDK_VERSION = "0.6.0";
+export declare const SDK_VERSION = "0.7.0";
 /** W9.1 / CLIENT-INFO-1: every request the SDK makes to Gemmein carries
  *  `x-client-info: gemmein-sdk/<version>`. The server records it on the
  *  secret-key usage ledger ("last seen from gemmein-sdk/0.5.0"), so a
  *  misbehaving integration can be attributed to an SDK version from day
  *  one. It is a report, not a proof — any caller can set it. */
-export declare const CLIENT_INFO = "gemmein-sdk/0.6.0";
+export declare const CLIENT_INFO = "gemmein-sdk/0.7.0";
 export declare class GemmeinError extends Error {
     readonly status: number;
     readonly code: string;
@@ -183,6 +183,10 @@ export declare class Gemmein {
     readonly purchases: PurchasesClient;
     readonly account: AccountClient;
     readonly files: FilesClient;
+    /** W9.3 — the signed-in person's own credit balance (engine 0.8.0). */
+    readonly credits: CreditsClient;
+    /** W9.3 — the AI route: OpenAI / Anthropic / Google on the owner's key. */
+    readonly ai: AiClient;
     constructor(options: GemmeinOptions);
     /**
      * Your app's data — `g.collection<{ title: string }>("notes")`. The
@@ -382,6 +386,93 @@ export declare class AccountClient {
      */
     delete(): Promise<unknown>;
 }
+export type AiProvider = "openai" | "anthropic" | "google";
+export type AiChatOptions = {
+    /** Which configured provider answers. Optional when exactly one key is
+     *  set; refused `provider_required` (400) when it is ambiguous. */
+    provider?: AiProvider;
+    /** Abort the call — the stream closes; a call that dies mid-stream is
+     *  not refunded. */
+    signal?: AbortSignal;
+};
+/** `spendCredits`'s answer: `spent` is the amount taken (0 on a deduped
+ *  repeat); `event` is the ledger line — the same one on a repeat. */
+export type SpendCreditsResult = {
+    ok: true;
+    spent: number;
+    deduped: boolean;
+    balance: {
+        before: number;
+        after: number;
+    };
+    event: {
+        id: string;
+        reason: string | null;
+        actor: string;
+    };
+};
+/** The signed-in person's own credits — so an app can draw its own meter. */
+export declare class CreditsClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    /**
+     * The balance RIGHT NOW, server-resolved — the number that refuses at
+     * zero, never client math. Session required (`session_required`, 401).
+     *
+     *   const { balance } = await g.credits.balance();
+     */
+    balance(): Promise<{
+        balance: number;
+    }>;
+}
+/**
+ * The AI route. `chat` takes the provider's own request body — exactly what
+ * you would POST to OpenAI's /v1/chat/completions, Anthropic's /v1/messages
+ * or Google's generateContent — and answers with the fetch `Response`
+ * untouched, streaming intact (SSE stays SSE). Gemmein spends one credit,
+ * adds the owner's key, forwards, and passes status and bytes back.
+ * Response headers: `x-gemmein-credits-remaining` on every answer that
+ * passed the spend; `x-gemmein-credit: refunded` when the provider failed
+ * before its first byte.
+ */
+export declare class AiClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    /**
+     *   const res = await g.ai.chat({ model: "gpt-4o-mini", messages, stream: true });
+     *   for await (const chunk of res.body) { … }
+     *
+     * Browser sessions only — a server key is refused (`scope_denied`, 403).
+     * Refusals, all `GemmeinError`: `session_required` (401) ·
+     * `credits_exhausted` (402 — the message carries the balance; show your
+     * own "buy more" door, which is a product checkout) · `ai_not_configured`
+     * (409 — the owner has set no key) · `provider_required` (400) ·
+     * `model_not_allowed` (403 — the owner's models list) · `ai_capped`
+     * (429 — 20 calls a minute per person; `err.resetAt`) ·
+     * `payload_too_large` (413 — 256 KB) · `provider_unreachable` (502,
+     * before the first byte, refunded). Those are GEMMEIN's refusals. The
+     * PROVIDER's own answer — 2xx or not — is returned as it came: an answer
+     * that carries `x-gemmein-credits-remaining` (or `x-gemmein-credit`)
+     * passed the spend, so its status and body are the provider's; read
+     * `res.ok` / `res.status` yourself (a provider 4xx before the first byte
+     * is refunded, header `x-gemmein-credit: refunded`).
+     */
+    chat(body: Record<string, unknown>, options?: AiChatOptions): Promise<Response>;
+    /**
+     * The non-streaming convenience: one call, one string. Pass a body that
+     * does NOT stream (`stream` unset or false); the provider's JSON answer is
+     * read whole and the text is lifted out per provider — OpenAI
+     * `choices[0].message.content`, Anthropic `content[].text` joined,
+     * Google `candidates[0].content.parts[].text` joined. An answer with no
+     * text in any of those places throws `invalid_response` (status 0). A
+     * provider's own non-2xx throws `provider_error` with the provider's
+     * status and the provider's message (the owner's key masked to its
+     * hint if the provider echoed it).
+     *
+     *   const answer = await g.ai.text({ model: "claude-sonnet-4-5", max_tokens: 400, messages });
+     */
+    text(body: Record<string, unknown>, options?: AiChatOptions): Promise<string>;
+}
 export declare class StorageClient {
     private readonly config;
     constructor(config: ClientConfig);
@@ -562,9 +653,11 @@ export type Grant = {
 /**
  * What a person holds RIGHT NOW — never what they pay. `access` is the
  * union of live grants' keys; `grants` lists those live grants (revoked
- * and expired ones are gone, not flagged). `credits` is a reserved slot:
- * it is `null` today because consumable credits are not shipped — don't
- * design around them until this type says otherwise.
+ * and expired ones are gone, not flagged). `credits` is `{ balance }` —
+ * filled from engine 0.8.0 (W9.3): the person's credit balance, floored
+ * at 0, the same number `g.credits.balance()` answers and the one the AI
+ * route and `spendCredits` refuse against. An engine before 0.8.0 answers
+ * `null` here — read it as "not carried", never as zero.
  */
 export type Holdings = {
     access: string[];
@@ -760,6 +853,38 @@ export declare class GemmeinServer {
         grant: Grant;
         holdings: Holdings;
     }>;
+    /**
+     * W9.3 — spend a person's credits from YOUR server, with a reason:
+     *
+     *   const { balance } = await g.spendCredits(personId, {
+     *     amount: 5,                       // default 1; 1..10,000 per call
+     *     reason: "render:4k",             // what the owner reads in the ledger
+     *     key: `render:${jobId}`,          // your retry key — a repeat is deduped
+     *   });
+     *   // { ok: true, spent: 5, deduped: false, balance: { before: 20, after: 15 },
+     *   //   event: { id: "cev_…", reason: "render:4k", actor: "<your key's name>" } }
+     *
+     * ONE conditional update, floored at 0: the spend succeeds whole or not at
+     * all, and `402 credits_exhausted` says "this person has {balance} credits
+     * — the spend needs {amount}". Pass `key` when the caller can retry — the
+     * same key answers the first spend again with `deduped: true`, `spent: 0`,
+     * the same `event` and the balance untouched. The key is scoped to the
+     * person: one order id reused for two people charges both. Credits come
+     * from a pack they bought, a comp in the back office, or a relay; a key
+     * cannot mint them.
+     *
+     * Needs the key's "Spend a person's credits" box ticked by your human.
+     * Refusals: `capability_required` (403 — "this key can't spend credits —
+     * mint a key with 'Spend a person's credits' ticked") ·
+     * `credits_exhausted` (402) · `person_not_found` (404) · `invalid_amount` /
+     * `invalid_reason` / `invalid_key` (400) · `dedupe_conflict` (409 — the
+     * key already names a different movement).
+     */
+    spendCredits(personId: string, input: {
+        amount?: number;
+        reason: string;
+        key?: string;
+    }): Promise<SpendCreditsResult>;
     /**
      * End one grant — the reversibility law in one call:
      *

package/dist/index.js

@@ -4,7 +4,7 @@
  *  second module). `scripts/sync-version.mjs` rewrites the literal from
  *  package.json before every build (`prebuild`), and a test pins the two
  *  equal, so a bump can never ship with a stale header. */
-export const SDK_VERSION = "0.6.0"; // synced from package.json — do not edit by hand
+export const SDK_VERSION = "0.7.0"; // synced from package.json — do not edit by hand
 /** W9.1 / CLIENT-INFO-1: every request the SDK makes to Gemmein carries
  *  `x-client-info: gemmein-sdk/<version>`. The server records it on the
  *  secret-key usage ledger ("last seen from gemmein-sdk/0.5.0"), so a
@@ -116,6 +116,8 @@ export class Gemmein {
         this.purchases = new PurchasesClient(config);
         this.account = new AccountClient(config);
         this.files = new FilesClient(config);
+        this.credits = new CreditsClient(config);
+        this.ai = new AiClient(config);
     }
     /**
      * Your app's data — `g.collection<{ title: string }>("notes")`. The
@@ -357,6 +359,167 @@ export class AccountClient {
         return result;
     }
 }
+/** The signed-in person's own credits — so an app can draw its own meter. */
+export class CreditsClient {
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * The balance RIGHT NOW, server-resolved — the number that refuses at
+     * zero, never client math. Session required (`session_required`, 401).
+     *
+     *   const { balance } = await g.credits.balance();
+     */
+    async balance() {
+        return runtimeRequest(this.config, "/auth/credits");
+    }
+}
+/**
+ * The AI route. `chat` takes the provider's own request body — exactly what
+ * you would POST to OpenAI's /v1/chat/completions, Anthropic's /v1/messages
+ * or Google's generateContent — and answers with the fetch `Response`
+ * untouched, streaming intact (SSE stays SSE). Gemmein spends one credit,
+ * adds the owner's key, forwards, and passes status and bytes back.
+ * Response headers: `x-gemmein-credits-remaining` on every answer that
+ * passed the spend; `x-gemmein-credit: refunded` when the provider failed
+ * before its first byte.
+ */
+export class AiClient {
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     *   const res = await g.ai.chat({ model: "gpt-4o-mini", messages, stream: true });
+     *   for await (const chunk of res.body) { … }
+     *
+     * Browser sessions only — a server key is refused (`scope_denied`, 403).
+     * Refusals, all `GemmeinError`: `session_required` (401) ·
+     * `credits_exhausted` (402 — the message carries the balance; show your
+     * own "buy more" door, which is a product checkout) · `ai_not_configured`
+     * (409 — the owner has set no key) · `provider_required` (400) ·
+     * `model_not_allowed` (403 — the owner's models list) · `ai_capped`
+     * (429 — 20 calls a minute per person; `err.resetAt`) ·
+     * `payload_too_large` (413 — 256 KB) · `provider_unreachable` (502,
+     * before the first byte, refunded). Those are GEMMEIN's refusals. The
+     * PROVIDER's own answer — 2xx or not — is returned as it came: an answer
+     * that carries `x-gemmein-credits-remaining` (or `x-gemmein-credit`)
+     * passed the spend, so its status and body are the provider's; read
+     * `res.ok` / `res.status` yourself (a provider 4xx before the first byte
+     * is refunded, header `x-gemmein-credit: refunded`).
+     */
+    async chat(body, options = {}) {
+        const payload = options.provider ? { provider: options.provider, ...body } : body;
+        const response = await fetch(new URL("/ai/chat", this.config.apiUrl), {
+            method: "POST",
+            body: JSON.stringify(payload),
+            headers: await runtimeHeaders(this.config, { "content-type": "application/json" }),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        if (!response.ok) {
+            if (isForwardedAnswer(response)) {
+                // Past the spend: the provider answered. `provider_unreachable` is
+                // the one Gemmein refusal written after the spend (it carries the
+                // refund header) — peek without consuming so it stays typed.
+                const peek = (await response.clone().json().catch(() => null));
+                if (peek?.code !== "provider_unreachable")
+                    return response;
+            }
+            const errorBody = await readErrorBody(response);
+            if (errorBody.code === "auth_expired")
+                await this.config.tokenStore.clear();
+            throw new GemmeinError({ status: response.status, ...errorBody });
+        }
+        return response;
+    }
+    /**
+     * The non-streaming convenience: one call, one string. Pass a body that
+     * does NOT stream (`stream` unset or false); the provider's JSON answer is
+     * read whole and the text is lifted out per provider — OpenAI
+     * `choices[0].message.content`, Anthropic `content[].text` joined,
+     * Google `candidates[0].content.parts[].text` joined. An answer with no
+     * text in any of those places throws `invalid_response` (status 0). A
+     * provider's own non-2xx throws `provider_error` with the provider's
+     * status and the provider's message (the owner's key masked to its
+     * hint if the provider echoed it).
+     *
+     *   const answer = await g.ai.text({ model: "claude-sonnet-4-5", max_tokens: 400, messages });
+     */
+    async text(body, options = {}) {
+        const response = await this.chat(body, options);
+        if (!response.ok) {
+            throw new GemmeinError({
+                status: response.status,
+                code: "provider_error",
+                message: await providerErrorMessage(response),
+            });
+        }
+        const data = (await response.json());
+        const text = extractAiText(data);
+        if (text === null) {
+            throw new GemmeinError({
+                status: 0,
+                code: "invalid_response",
+                message: "the provider answered without any text — for a streaming body use g.ai.chat() and read the stream",
+            });
+        }
+        return text;
+    }
+}
+/** An answer that passed the spend: the engine stamps the balance (and, on
+ *  a refund, `x-gemmein-credit`) only after the credit moved — a refusal
+ *  before the spend carries neither. */
+function isForwardedAnswer(response) {
+    return response.headers.has("x-gemmein-credits-remaining") || response.headers.has("x-gemmein-credit");
+}
+/** The provider's own reason, whichever shape it used — OpenAI, Anthropic
+ *  and Google all nest it as `error.message`; anything else is the text. */
+async function providerErrorMessage(response) {
+    const text = await response.text().catch(() => "");
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === "object") {
+            const nested = typeof parsed.error === "object" && parsed.error !== null ? parsed.error.message : parsed.error;
+            const message = typeof nested === "string" ? nested : typeof parsed.message === "string" ? parsed.message : null;
+            if (message)
+                return message;
+        }
+    }
+    catch {
+        // not JSON — the text is the reason
+    }
+    return text.trim().slice(0, 500) || `the provider answered ${response.status}`;
+}
+/** The per-provider lift, by shape (a provider's answer is unmistakable). */
+function extractAiText(data) {
+    if (!data || typeof data !== "object")
+        return null;
+    const d = data;
+    // OpenAI: choices[0].message.content (a string, or content parts)
+    if (Array.isArray(d.choices)) {
+        const message = d.choices[0]?.message;
+        const content = message?.content;
+        if (typeof content === "string")
+            return content;
+        if (Array.isArray(content))
+            return joinTextParts(content);
+        return null;
+    }
+    // Anthropic: content[] blocks, the text ones joined
+    if (Array.isArray(d.content))
+        return joinTextParts(d.content);
+    // Google: candidates[0].content.parts[].text joined
+    if (Array.isArray(d.candidates)) {
+        const parts = d.candidates[0]?.content?.parts;
+        return Array.isArray(parts) ? joinTextParts(parts) : null;
+    }
+    return null;
+}
+function joinTextParts(parts) {
+    const texts = parts
+        .map((p) => (p && typeof p === "object" && typeof p.text === "string" ? p.text : null))
+        .filter((t) => t !== null);
+    return texts.length > 0 ? texts.join("") : null;
+}
 function isSessionResponse(value) {
     return (typeof value === "object" &&
         value !== null &&
@@ -935,6 +1098,43 @@ export class GemmeinServer {
             }),
         });
     }
+    /**
+     * W9.3 — spend a person's credits from YOUR server, with a reason:
+     *
+     *   const { balance } = await g.spendCredits(personId, {
+     *     amount: 5,                       // default 1; 1..10,000 per call
+     *     reason: "render:4k",             // what the owner reads in the ledger
+     *     key: `render:${jobId}`,          // your retry key — a repeat is deduped
+     *   });
+     *   // { ok: true, spent: 5, deduped: false, balance: { before: 20, after: 15 },
+     *   //   event: { id: "cev_…", reason: "render:4k", actor: "<your key's name>" } }
+     *
+     * ONE conditional update, floored at 0: the spend succeeds whole or not at
+     * all, and `402 credits_exhausted` says "this person has {balance} credits
+     * — the spend needs {amount}". Pass `key` when the caller can retry — the
+     * same key answers the first spend again with `deduped: true`, `spent: 0`,
+     * the same `event` and the balance untouched. The key is scoped to the
+     * person: one order id reused for two people charges both. Credits come
+     * from a pack they bought, a comp in the back office, or a relay; a key
+     * cannot mint them.
+     *
+     * Needs the key's "Spend a person's credits" box ticked by your human.
+     * Refusals: `capability_required` (403 — "this key can't spend credits —
+     * mint a key with 'Spend a person's credits' ticked") ·
+     * `credits_exhausted` (402) · `person_not_found` (404) · `invalid_amount` /
+     * `invalid_reason` / `invalid_key` (400) · `dedupe_conflict` (409 — the
+     * key already names a different movement).
+     */
+    async spendCredits(personId, input) {
+        return this.gate(`/server/people/${encodeURIComponent(personId)}/credits/spend`, {
+            method: "POST",
+            body: JSON.stringify({
+                ...(input.amount !== undefined ? { amount: input.amount } : {}),
+                reason: input.reason,
+                ...(input.key !== undefined ? { key: input.key } : {}),
+            }),
+        });
+    }
     /**
      * End one grant — the reversibility law in one call:
      *