@gemmein/sdk 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -1,8 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GemmeinServer = exports.CollectionClient = exports.StorageClient = exports.AccountClient = exports.PaymentsClient = exports.SubscriptionsClient = exports.FilesClient = exports.PurchasesClient = exports.AuthClient = exports.Gemmein = exports.BrowserTokenStore = exports.MemoryTokenStore = exports.GemmeinError = void 0;
+exports.GemmeinServer = exports.CollectionClient = exports.StorageClient = exports.AiClient = exports.CreditsClient = exports.AccountClient = exports.PaymentsClient = exports.SubscriptionsClient = exports.FilesClient = exports.PurchasesClient = exports.AuthClient = exports.Gemmein = exports.BrowserTokenStore = exports.MemoryTokenStore = exports.GemmeinError = exports.CLIENT_INFO = exports.SDK_VERSION = void 0;
 exports.gemmein = gemmein;
 exports.gemmeinServer = gemmeinServer;
+/** This build's version — the value `package.json` carries. Kept inline
+ *  because the package is one source file and this file is imported
+ *  straight from source by the security suite (no runtime file read, no
+ *  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. */
+exports.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
+ *  misbehaving integration can be attributed to an SDK version from day
+ *  one. It is a report, not a proof — any caller can set it. */
+exports.CLIENT_INFO = `gemmein-sdk/${exports.SDK_VERSION}`;
 class GemmeinError extends Error {
     constructor(input) {
         super(input.message);
@@ -111,6 +124,8 @@ 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
@@ -164,7 +179,15 @@ class AuthClient {
             await this.config.tokenStore.set(result.token);
             return result;
         }
-        throw new Error("Gemmein auth response did not include a session token");
+        // W9.1: the one place the SDK threw a bare Error. Every refusal the SDK
+        // raises is a GemmeinError so `err.code` is always there to branch on;
+        // status 0 is the SDK's own convention for "no HTTP status applies"
+        // (see invalid_collection_name, missing_app_key).
+        throw new GemmeinError({
+            status: 0,
+            code: "invalid_response",
+            message: "Gemmein auth response did not include a session token"
+        });
     }
     async logout() {
         try {
@@ -351,6 +374,169 @@ class AccountClient {
     }
 }
 exports.AccountClient = AccountClient;
+/** The signed-in person's own credits — so an app can draw its own meter. */
+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");
+    }
+}
+exports.CreditsClient = CreditsClient;
+/**
+ * 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.
+ */
+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;
+    }
+}
+exports.AiClient = AiClient;
+/** 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 &&
@@ -764,7 +950,7 @@ class GemmeinServer {
         }
         const response = await fetch(new URL("/server/test-session", this.apiUrl), {
             method: "POST",
-            headers: { "x-app-key": this.secretKey, "content-type": "application/json" },
+            headers: { "x-app-key": this.secretKey, "x-client-info": exports.CLIENT_INFO, "content-type": "application/json" },
             body: JSON.stringify({ email }),
         });
         if (!response.ok) {
@@ -802,7 +988,7 @@ class GemmeinServer {
     async notify(personId, input) {
         const response = await fetch(new URL("/server/notify", this.apiUrl), {
             method: "POST",
-            headers: { "x-app-key": this.secretKey, "content-type": "application/json" },
+            headers: { "x-app-key": this.secretKey, "x-client-info": exports.CLIENT_INFO, "content-type": "application/json" },
             body: JSON.stringify({ personId, subject: input.subject, text: input.text, ...(input.kind ? { kind: input.kind } : {}), ...(input.key ? { key: input.key } : {}) }),
         });
         if (!response.ok) {
@@ -843,6 +1029,35 @@ class GemmeinServer {
             body: JSON.stringify({ token }),
         });
     }
+    /**
+     * W9.2 — THE INVITE DOOR: create a person by email BEFORE they sign in.
+     * The envelope, the invoice, the client portal, the booking-winner
+     * email — all address someone who has never signed in and so has no
+     * id yet. This is the one server call that takes an email:
+     *
+     *   const { person, created } = await g.invitePerson("client@example.com");
+     *   await g.notify(person.id, { subject: "Your contract", text: "…" });
+     *
+     * Create-or-fetch, idempotent, case-insensitive: the first call makes
+     * the person (`created: true`, HTTP 201), every later call finds them
+     * (`created: false`, 200) — one id either way, the address returned
+     * lowercased. Their first sign-in lands on this account: records and
+     * files you addressed to `person.id` are already theirs. `person.invited`
+     * stays true until that sign-in; a suspended person is returned with
+     * `suspended: true`, never refused.
+     *
+     * Needs the key's "Create a person by email before they sign in" box
+     * ticked by your human. Refusals: `capability_required` (the box isn't
+     * ticked) · `invalid_email` (400 — must look like name@domain) ·
+     * `invite_capped` (429 — 500 invite calls per app per day, a fetch of an existing person counting too; the message says
+     * where to write to raise it; `err.resetAt` says when the window ends).
+     */
+    async invitePerson(email) {
+        return this.gate("/server/people", {
+            method: "POST",
+            body: JSON.stringify({ email }),
+        });
+    }
     /**
      * What one of YOUR people holds, by person id — for the paths where no
      * token is in hand (a webhook of your own, a nightly job, an admin
@@ -902,6 +1117,43 @@ 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:
      *
@@ -927,7 +1179,7 @@ class GemmeinServer {
     // `err.code` carries the server's own code, `err.message` its sentence
     // (which always names the next action).
     async gate(path, init = {}) {
-        const headers = { "x-app-key": this.secretKey };
+        const headers = { "x-app-key": this.secretKey, "x-client-info": exports.CLIENT_INFO };
         if (init.body)
             headers["content-type"] = "application/json";
         const response = await fetch(new URL(path, this.apiUrl), { ...init, headers });
@@ -977,6 +1229,7 @@ class ServerCollectionClient {
     async request(suffix, init = {}) {
         const headers = {
             "x-app-key": this.secretKey,
+            "x-client-info": exports.CLIENT_INFO,
         };
         if (init.body) {
             headers["content-type"] = "application/json";
@@ -1052,6 +1305,7 @@ async function runtimeHeaders(config, headers) {
     return {
         ...headers,
         "x-app-key": config.appKey,
+        "x-client-info": exports.CLIENT_INFO,
         ...(token ? { authorization: `Bearer ${token}` } : {})
     };
 }

package/dist/index.d.cts

@@ -114,6 +114,19 @@ export type AuthSession = {
         email: string;
     };
 };
+/** This build's version — the value `package.json` carries. Kept inline
+ *  because the package is one source file and this file is imported
+ *  straight from source by the security suite (no runtime file read, no
+ *  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.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.7.0";
 export declare class GemmeinError extends Error {
     readonly status: number;
     readonly code: string;
@@ -170,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
@@ -369,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);
@@ -529,7 +633,7 @@ export type GemmeinServerOptions = {
  * Where a grant came from — the KIND only. The gate never returns the
  * source's id, an amount, or anything from Stripe.
  */
-export type GrantSource = "subscription" | "purchase" | "manual" | "trial" | "promotion" | "migration";
+export type GrantSource = "subscription" | "purchase" | "manual" | "trial" | "promotion" | "migration" | "relay";
 /**
  * The sources a secret key may create by hand. `purchase` and
  * `subscription` are deliberately absent: money-made access comes only
@@ -549,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[];
@@ -565,6 +671,16 @@ export type GatePerson = {
     email: string;
     role: string;
 };
+/**
+ * W9.2 — the person `invitePerson` returns. `invited` is true until they
+ * sign in for the first time; `suspended` is the owner's switch (a
+ * suspended person is returned, never refused — `verifySession` is what
+ * refuses them).
+ */
+export type InvitedPerson = GatePerson & {
+    invited: boolean;
+    suspended: boolean;
+};
 export declare class GemmeinServer {
     private readonly apiUrl;
     private readonly secretKey;
@@ -648,6 +764,33 @@ export declare class GemmeinServer {
         person: GatePerson;
         holdings: Holdings;
     }>;
+    /**
+     * W9.2 — THE INVITE DOOR: create a person by email BEFORE they sign in.
+     * The envelope, the invoice, the client portal, the booking-winner
+     * email — all address someone who has never signed in and so has no
+     * id yet. This is the one server call that takes an email:
+     *
+     *   const { person, created } = await g.invitePerson("client@example.com");
+     *   await g.notify(person.id, { subject: "Your contract", text: "…" });
+     *
+     * Create-or-fetch, idempotent, case-insensitive: the first call makes
+     * the person (`created: true`, HTTP 201), every later call finds them
+     * (`created: false`, 200) — one id either way, the address returned
+     * lowercased. Their first sign-in lands on this account: records and
+     * files you addressed to `person.id` are already theirs. `person.invited`
+     * stays true until that sign-in; a suspended person is returned with
+     * `suspended: true`, never refused.
+     *
+     * Needs the key's "Create a person by email before they sign in" box
+     * ticked by your human. Refusals: `capability_required` (the box isn't
+     * ticked) · `invalid_email` (400 — must look like name@domain) ·
+     * `invite_capped` (429 — 500 invite calls per app per day, a fetch of an existing person counting too; the message says
+     * where to write to raise it; `err.resetAt` says when the window ends).
+     */
+    invitePerson(email: string): Promise<{
+        person: InvitedPerson;
+        created: boolean;
+    }>;
     /**
      * What one of YOUR people holds, by person id — for the paths where no
      * token is in hand (a webhook of your own, a nightly job, an admin
@@ -710,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:
      *