@gemmein/sdk 0.6.0 → 0.8.0

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.8.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,177 @@ 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 a credit,
+ * adds the owner's key, forwards, and passes status and bytes back. Pass
+ * `tool` (W9.3b) to run a named, owner-priced-and-gated operation instead
+ * of the implicit default (one credit, any allowed model, no gate).
+ * 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). W9.3b, `tool` only: `unknown_tool`
+     * (404 — no tool by that name in this environment) · `tool_disabled`
+     * (403) · `entitlement_required` (403 — the message names the plan or
+     * product that unlocks it) · `model_pinned` (403 — the tool's model is
+     * fixed; leave `model` out of the body). 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` 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`). `x-gemmein-tool` names the tool; absent
+     * on the implicit default.
+     */
+    async chat(body, options = {}) {
+        const payload = options.provider ? { provider: options.provider, ...body } : body;
+        const url = new URL("/ai/chat", this.config.apiUrl);
+        if (options.tool)
+            url.searchParams.set("tool", options.tool);
+        const response = await fetch(url, {
+            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 +1108,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:
      *

package/llms.txt

@@ -39,7 +39,11 @@ creating no accounts is the correct behavior until the verdict is in.
    safety rules (private, shared, admin_write, public_read, community,
    addressed, direct), subscriptions and one-off digital products (Stripe
    built in; any provider that signs its webhooks drives access through a
-   relay), image uploads and paid file delivery, entitlement-gated
+   relay), consumable credits (buy a pack, spend atomically, a zero
+   floor — see Credits), a chat call to OpenAI, Anthropic or Google on
+   the founder's own key, at the credits the owner set for that tool
+   (one by default — see The AI route),
+   image uploads and paid file delivery, entitlement-gated
    access, race-safe bookings/stock/counters, account-deletion cascade.
    Out of scope — each of these downgrades the verdict and must never be
    silently approximated:
@@ -50,9 +54,11 @@ creating no accounts is the correct behavior until the verdict is in.
      nothing in between — so an app whose CORE loop needs teams, roles
      or seats DOESN'T FIT
    - carts, quantities, physical goods, shipping, inventory
-   - credits or usage metering TODAY (paid access is yes-or-no; consumable
-     credits are planned, not shipped — don't design around them yet, and
-     never sell a "credit pack" until this file says the ledger exists)
+   - usage-based INVOICING (a bill after the fact, by token or by minute):
+     not shipped. Credits ARE — consumable credits: buy a pack, spend
+     atomically, a zero floor — see Credits; a "100 credit pack" is a
+     product with Grants credits = 100, and an AI tool call costs what
+     the owner priced that tool at (one credit by default)
    - seats (owner-run: not coming)
    - hosted functions or cron: Gemmein runs no code of yours — but your
      own function anywhere asks Gemmein who a person is and what they
@@ -391,14 +397,15 @@ contents.
   what the person holds NOW: `access` (keys like "access:pro"), `grants`
   (each with its source KIND only — subscription | purchase | manual |
   trial | promotion | migration | relay — plus start and expiry), and `credits`,
-  a reserved slot that is always `null` today (consumable credits are NOT
-  shipped; don't design around them). Never subscription status, amounts
+  `{ balance }` — how many credits the person holds now (engine 0.8.0 and
+  later; `null` from an older local engine). Never subscription status, amounts
   or Stripe ids: gate on what a person HOLDS, never on billing. Person
   id, NEVER an email address. verifySession needs nothing extra; looking
   someone up by id and granting are new power, so they sit behind per-key
   checkboxes the HUMAN ticks when minting the key — ask your human to
   tick "Look up a person's access by id" / "Grant and revoke access" /
-  "Create a person by email before they sign in" (invitePerson). A
+  "Create a person by email before they sign in" (invitePerson) /
+  "Spend a person's credits" (spendCredits). A
   key grants MANUAL access only (manual | trial | promotion | migration):
   purchases and subscriptions come from the built-in Stripe path, and
   another provider's payment grants through a relay (source `relay`). Every /server/*
@@ -442,17 +449,21 @@ contents.
   writes the receipt, tells the person, passes the signal to your URL.
   Stripe stays built in; any provider that signs its webhooks drives
   access the same way.
-  Does: write a record · grant access · revoke access · email the person
-  the event is about · call your URL (a signed notice to a server YOU run).
+  Does: write a record · grant access · revoke access · grant credits ·
+  fulfil or refund a product · email the person the event is about · call
+  your URL (a signed notice to a server YOU run).
   Does not: run your code; call OpenAI or any third API for you (call_url
   carries Gemmein's body and signature, never your key or a request you
   shape); attach a person to a schedule (no "email everyone due tomorrow"
   yet); transform or compute data; act on more than one person per event
-  (a list is a broadcast); grant credits (planned, not shipped).
+  (a list is a broadcast); spend credits (a spend is your server's or the
+  AI route's — a relay only adds).
   Needs something else when: the work THINKS — a model call, a score, a
   transform, a third API — put that in your own function behind call_url;
   it receives a verified event with the person already resolved. The AI
-  route (planned) is where Gemmein will hold a provider key and call for you.
+  route is where Gemmein holds your provider key and makes a chat call for
+  a signed-in person at the tool's credit price (one by default) — see
+  The AI route.
   Use a relay when: a provider other than Stripe signs a webhook that
   should change access or write a record (GoCardless, Paddle, Lemon
   Squeezy, a form or signature tool); a record change should tell the
@@ -504,9 +515,59 @@ contents.
   - grant_access { entitlement, expiresAt?, reason? } — source `relay`, the
     seventh grant source; "granted by relay <name>" on the person's page.
   - revoke_access { entitlement } — ends every live grant of it.
+  - grant_credits { amount (1..10,000), reason? } — adds to the person's
+    balance, once per event; the ledger line reads "relay: <reason>".
   - email_person { subject, text, kind? } — rides notify's caps.
   - call_url { url } — https, signed POST (`X-Gemmein-Signature`), 10 s; the
     same `id` on every retry and replay — your URL deduplicates on it.
+  - fulfil_product { product, ref? } — product is a name on the Payments
+    page; ref is the provider's payment reference.
+  - refund_product { product, ref? } — the refund twin.
+  fulfil_product grants the product's key and credits to the event's
+  person and writes the receipt, exactly as a Stripe purchase does;
+  refund_product takes them back. Both are idempotent on ref: a ref must
+  be the provider's unique payment identifier; a ref already used by
+  another purchase is refused and audited. A ref you wrote that names
+  nothing on the event is refused, never replaced: only an absent ref
+  falls back to rly:<eventId>. The relay road binds by name for
+  FULFILMENT: renaming or deleting the relay stops fulfilment until a
+  relay with that name exists again; the product card shows it.
+  refund_product may run from any relay in the environment; it refunds
+  only a purchase a relay fulfilled, for the event's person and the
+  product it names. This is how
+  a product sold via a relay (How it's sold = a relay's name, not a
+  Stripe Payment Link) gets fulfilled — a provider without Payment Links
+  (GoCardless, Lemon Squeezy, Paddle, bank transfer) confirms a payment,
+  the relay fulfils the product:
+
+      {
+        "name": "gocardless-paid",
+        "trigger": {
+          "kind": "receiver",
+          "verify": { "scheme": "shared_token" },
+          "map": {
+            "event_id": "events.0.id",
+            "event_type": "events.0.action",
+            "person_email": "events.0.details.customer_email",
+            "payment_id": "events.0.links.payment"
+          },
+          "when": { "event_type": "confirmed" }
+        },
+        "actions": [
+          { "type": "fulfil_product", "product": "Starter pack", "ref": "{{mapped.payment_id}}" }
+        ]
+      }
+
+  Mapped fields ride into templates as {{mapped.<name>}}; {{event.<path>}}
+  reads the raw payload.
+  A template that names nothing is recorded as a warning on the relay
+  event — read it on the Relays page before trusting a ref.
+
+  The refund twin swaps the trigger's `when` to
+  `{ "event_type": "refunded" }` and the action to `refund_product`.
+  `g.payments.buy` on a product sold this way answers 409
+  `product_not_sellable`; saving a relay action against a relay name that
+  does not exist in this environment answers 400 `relay_missing`.
   Full depth — every verify scheme, the map and when grammar, the call_url
   contract and signature, every refusal code, the limits and both rails:
   https://docs.gemmein.com/relays (the same chapter is REFERENCE.md
@@ -635,6 +696,17 @@ contents.
   returns. Elevation is READ-only: build admin views that see everything,
   but route status changes on other users' records (fulfilment, moderation)
   to your human's Gemmein dashboard — they click the record there.
+- Products — a capability card.
+  What it is: A named thing you sell once: a download, a licence, a
+  credit pack.
+  Does: Grants its key and its credits on purchase; writes the buyer's
+  receipt; a full refund takes both back.
+  Does not: Does not set a price — the provider does. Does not sell
+  subscriptions (those are plans).
+  Needs something else when: You sell through a provider without a
+  Payment Link → a relay with fulfil_product; you meter by usage →
+  credits spent per AI tool.
+  Example: "Starter pack", 100 credits, sold via a GoCardless relay.
 - Payments: the builder names plans in the dashboard, pastes one Stripe
   signing secret, and pastes each paid plan's Stripe Payment Link there too.
   The app's ONLY checkout job is `await g.subscriptions.checkout("pro")` on the upgrade
@@ -675,11 +747,10 @@ contents.
   screen and send them to checkout; retry only after they hold one. Proof surfaces: `await g.purchases.mine()`
   (everything they paid for, refunds applied, with the `grants` each purchase
   carries) and `await g.subscriptions.mine()`.
-  NO credits or usage limits YET — access is yes-or-no today. Consumable
-  credits (buy a pack, spend atomically, a zero floor) are planned, not
-  shipped: until this file teaches them, a "100 credit pack" is NOT a
-  pattern (the webhook can only SET a number, so a second pack erases the
-  first). NO seats, by design — not coming.
+  Access is yes-or-no. A QUANTITY beside it is credits — buy a pack, spend
+  atomically, a zero floor (see Credits): a "100 credit pack" is a product
+  with Grants credits = 100, and the ledger ADDS at every purchase, so a
+  second pack makes 200. NO seats, by design — not coming.
 - Two FAMILIES of grant, and the line between them is law. Every grant is
   one key + one reason + a start + maybe an end, never edited (an extension
   is a NEW grant). PURCHASE-TIED (`subscription`, `purchase`): written only
@@ -714,13 +785,19 @@ contents.
   scope, said out loud): plans are for subscriptions; products are for
   things. Selling a SERVICE session this way (tutoring, coaching, a
   consultation) is fine — nothing ships; the recorded purchase is the
-  proof the session was paid for. The builder adds products (name + Stripe Payment Link) on the
-  same Payments page. The app calls
+  proof the session was paid for. The builder adds products on the same
+  Payments page and sets how each is sold: a Stripe Payment Link, a relay
+  (any provider whose webhook the founder maps — GoCardless, Lemon
+  Squeezy, Paddle, bank transfer — fulfils it with `fulfil_product`), or
+  not yet (the product is defined, its grants and credits are known, no
+  road wired). The app calls
   `await g.payments.buy("beat")` — or, when one product covers many items (license
   tiers over a catalog), names the item:
   `await g.payments.buy("premium license", { item: "beat_37" })` (display text
-  only; the PRICE always comes from the product's Payment Link, so the
-  item note can never change what's paid). Gemmein records every completed
+  only; the PRICE always comes from the provider — the Payment Link or
+  the relay — so the item note can never change what's paid). A product
+  sold via a relay or not yet has no Payment Link to open:
+  `g.payments.buy` answers 409 `product_not_sellable`. Gemmein records every completed
   payment itself — `await g.purchases.mine()` is the buyer's proof:
   { item, kind, status: "paid"|"part_refunded"|"refunded", amountMinor,
   currency, refundedMinor, grants, paidAt, delivery? }. Selling a FILE (a
@@ -740,6 +817,164 @@ contents.
   webhook. NO carts, NO quantities — one product per checkout by design; a
   cart is N checkouts or one bundled product. 404 unknown_product lists
   what the app actually sells — use those names.
+- Credits — a quantity beside access. See https://docs.gemmein.com/credits
+  What it is: a balance your customers hold and your product spends — a
+  pack they buy, a comp you give, an AI tool call priced in credits.
+  Does: a product grants credits at purchase (its Grants credits field);
+  your server spends them with a reason; the AI route spends the credits
+  the owner set for the named tool, one by default;
+  a relay grants them; the owner's dashboard shows the balance and the
+  ledger and comps by hand. Every movement is one ledger line.
+  Does not: expire; go negative (floor 0 — a spend past the balance is
+  refused whole, never partly); price by token; open access (that is an
+  entitlement — a person with 500 credits and no plan is still refused by
+  a locked collection); count seats or quotas; spend from the browser.
+  Needs something else when: access should switch on with a plan (an
+  entitlement — see Paid ACCESS); you bill by usage after the fact (not
+  shipped — sell packs up front); the spend must happen in the browser
+  (it never does: your server, a relay or the AI route moves credits).
+  The case: "sell a 100-credit pack and let each chat cost one". The pack
+  is a product on the Payments page with Grants credits = 100 (the
+  product's `grantsCredits`); each purchase ADDS 100 to the buyer's
+  balance (two packs make 200), and a FULL refund claws back what is still
+  unspent, floor 0. The app reads the balance to show it:
+
+      const { balance } = await g.credits.balance()   // browser, signed in
+
+  Your server spends by person id, with a reason and a key, so a retry
+  never spends twice (the key needs "Spend a person's credits" ticked):
+
+      const r = await gemmeinServer(sk).spendCredits(person.id, {
+        amount: 1, reason: "export", key: `export:${jobId}`
+      })
+      // { ok: true, spent: 1, deduped: false, balance: { before: 12, after: 11 },
+      //   event: { id: "cev_…", reason: "export", actor: "<the key's name>" } }
+      // the same key again: spent: 0, deduped: true, the same event, nothing moved
+      // 402 credits_exhausted — "this person has 0 credits — the spend needs 1"
+
+  `holdings.credits` is `{ balance }` on verifySession and holdings, so one
+  verify answers who, what they hold AND how many. Numbers: no expiry ·
+  floor 0 · a balance carries at most 1,000,000,000 · a pack 1..1,000,000 ·
+  a server spend 1..10,000 per call · a comp ≤100,000 · a relay grant
+  1..10,000 · spend lines kept 90 days on the cloud rail (purchases, grants
+  and clawbacks are kept). Facts: a purchase by an email that has never
+  signed in creates the person and credits them; your `key` is scoped to
+  the person and namespaced (`srv:`), so one order id reused for two people
+  charges both and rotating the secret key never re-charges; a full refund
+  claws back what THAT purchase's ledger row granted, whatever the product
+  says today; the owner's page lists the newest 50 non-spend lines and the
+  credits the person spent in the last 30 days. Codes: `credits_exhausted`
+  (402 — carries the balance; show the pack, never retry the spend) ·
+  `capability_required` (403) · `person_not_found` (404) · `invalid_amount`
+  / `invalid_reason` / `invalid_key` (400) · `dedupe_conflict` (409 — the
+  key already names a different movement) · `credits_ceiling` (409 — the
+  balance would pass 1,000,000,000; nothing added).
+- The AI route — your app talks to OpenAI, Anthropic or Google through
+  Gemmein, on YOUR provider key, which never reaches the browser, through
+  a named AI tool your human prices and gates in the dashboard (or the
+  local `gemmein/ai/tools/<name>.json` file). Removing a tool is a
+  step-up action, like removing a key.
+  See https://docs.gemmein.com/ai
+  What it is: A named AI operation you price in credits and gate by
+  access.
+  Does: Runs on your provider key with the model and limits you set;
+  spends the tool's credits before the call and refunds them if the
+  provider fails before answering.
+  Does not: Does not price by token, does not let the browser set a
+  price or a model the tool pins, does not run from a server key.
+  Needs something else when: You want a plan-dependent price for the
+  same operation → make two tools and gate each; you meter something
+  that is not an AI call → spendCredits from your server.
+  Example: "Deep Research", openai, 20 credits, requires
+  access:pro-max — a tool file at `gemmein/ai/tools/deep-research.json`:
+
+      {
+        "label": "Deep Research",
+        "provider": "openai",
+        "credits": 20,
+        "requires": "access:pro-max"
+      }
+
+  On the local rail a tool saves without a Keys-page allowlist or a
+  configured key; the cloud refuses both at save.
+  Also true of the route itself: `sk_` is refused; it does not choose
+  models, cache, summarise, moderate, or reshape the request or the
+  answer; it does not refund a call that dies mid-stream, or one the
+  caller abandons before the headers (hanging up early does not
+  refund). Your SERVER makes the model call → call the provider
+  directly with your key (the gate still answers who they are and what
+  they hold). The call is not a chat call → embeddings, images, audio
+  go to the provider directly, from your server. The provider is not on
+  the list → write to hello@gemmein.com.
+  A call that names no tool runs as the default tool: one credit, your
+  configured provider, any allowed model.
+  A person who lacks the entitlement sees "Deep Research requires Pro
+  Max."; one short of the price sees "Deep Research costs 20 credits.
+  You have 7."; the ledger line reads "20 credits spent · Deep Research
+  · 87 remaining."
+  The case: "a chat app where each message costs the credits the owner
+  set for that tool — one by default — and my OpenAI key stays
+  private". The body is exactly what the provider documents for its
+  chat endpoint; `g.ai.chat` returns the fetch Response untouched:
+
+      const res = await g.ai.chat({
+        model: "gpt-4o-mini", stream: true,
+        messages: [{ role: "user", content: text }]
+      }, { tool: "deep-research" })   // tool is optional — leaving it
+                                       // out runs the default tool
+      // res.status and res.body are the provider's own (SSE stays SSE) —
+      // a provider 4xx/5xx comes back the same way: read res.ok; only
+      // Gemmein's own refusals throw
+      // res.headers: x-gemmein-credits-remaining: 41
+      //              x-gemmein-tool: deep-research  (names the tool;
+      //              absent on the implicit default)
+      //              x-gemmein-credit: refunded  (only when the credits
+      //              came back — a failure before the first byte)
+
+  For a non-stream answer as one string, whichever provider answered (a
+  provider non-2xx throws `provider_error` with its status and message):
+
+      const answer = await g.ai.text({ messages: [{ role: "user",
+        content: text }] }, { tool: "deep-research" })
+
+  Branch on `err.code`: unknown_tool (404 — no tool by that name in
+  this environment) · tool_disabled (403 — the owner switched it off)
+  · entitlement_required (403 — the message names the plan or product
+  it needs) · model_pinned (403 — the tool's model is fixed; leave
+  `model` out of the body) · provider_not_configured (409 — creating a
+  tool: add that provider's key first) · too_many_tools (409 — 50
+  tools per environment) · invalid_tool (400 — creating or updating a
+  tool with a bad field) · credits_exhausted (402 — the message names
+  the tool, its price and the balance, singular for 1; show the pack)
+  · ai_not_configured (409 — no
+  key set; the owner pastes one) · provider_required (400 — more than
+  one key set; name `provider`) · model_not_allowed (403 — the owner's
+  allowlist names what is allowed, for a tool with no pinned model) ·
+  ai_capped (429 — 20 per person per minute; wait for `resetAt`) ·
+  payload_too_large (413 — 256 KB, unless the tool sets a smaller
+  cap) · invalid_body (400 — the body must be the provider's JSON
+  object, nested at most 32 levels; a `?provider=` that disagrees with
+  a named tool's provider is refused the same way) · session_required
+  (401 — sign in first) · scope_denied (403 — a server key; the route
+  is for the browser) · provider_unreachable (502 — no answer before
+  the first byte; the credit is refunded; retry) · provider_error
+  (`g.ai.text` only — the provider's own non-2xx, its status and
+  message). Numbers: the credits the owner set for that tool, one by
+  default · ≤ 50 tools per environment · name ≤ 40 chars · label ≤ 60
+  chars · 20/min/person · 256 KB (a tool may set a smaller
+  `bounds.maxBodyBytes`, up to 262,144) · 170 s in all, and on a
+  stream 10 s to the first response headers.
+  Facts: `?provider=` and `?stream=1` on the URL do what the body
+  fields do (a named tool's own provider always wins); the owner may
+  list up to 20 allowed models for the default tool and any tool with
+  no pinned model (the Keys room's test call uses the first); every
+  `/ai/chat` call counts toward the app's api_requests band like any
+  other request; a provider that echoes the key in a refusal reaches
+  you as `***<hint>`. The owner's Usage room counts the calls; the
+  provider bills the tokens on the owner's own account. `gemmein dev`
+  answers a fake provider without a key (header `x-gemmein-ai: fake`),
+  so the loop runs locally; set GEMMEIN_AI_KEY_OPENAI / _ANTHROPIC /
+  _GOOGLE there for a real call.
 - Drafts on PUBLIC collections (public_read, community): create with the
   OPTION `{ published: false }` → hidden from every reader except its
   author and the owner, server-enforced; publish with
@@ -789,7 +1024,8 @@ contents.
   conversation and customer replies land; holding the billing band;
   running a relay: an inbound webhook from any provider that
   signs its calls, a schedule, or a record change → write a record,
-  grant or revoke access, email the person, or call your URL, with
+  grant or revoke access, grant credits, fulfil or refund a product,
+  email the person, or call your URL, with
   retries and a replay button (the definition is a file you write —
   see Relays — and the dashboard is where it is read, paused,
   replayed and its secrets rotated). None

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Gemmein SDK \u2014 passwordless auth, safe storage, and Stripe-driven record flips for AI-built apps. Small enough that one prompt teaches the whole API.",
   "license": "MIT",
   "type": "module",