@gemmein/sdk 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -12,6 +12,49 @@ the same release.
 
 ## [Unreleased]
 
+## [0.8.0] — 2026-09-05
+
+### Products are provider-neutral (engine 0.9.0, sdk 0.8.0, mcp 0.5.0)
+
+A product is sold one of three ways, set on the Payments page ("How it's
+sold" in the console, `sold` in the CLI): via a Stripe Payment Link, via a
+relay (any provider whose webhook the founder maps — GoCardless, Lemon
+Squeezy, Paddle, bank transfer), or not yet (defined, its grants and
+credits known, no road wired). Two new relay actions carry the relay
+road: `fulfil_product { product, ref? }` grants the product's key and
+credits to the event's person and writes the receipt, exactly as a
+Stripe purchase does; `refund_product { product, ref? }` takes them
+back. Both are idempotent on `ref`. `g.payments.buy` on a product sold
+via a relay or not yet answers 409 `product_not_sellable`; saving a
+relay action or a product's relay road against a relay that does not
+exist in this environment answers 400 `relay_missing`.
+
+### The AI tool primitive (engine 0.9.0, sdk 0.8.0, mcp 0.5.0)
+
+The AI route now runs named, priced tools instead of one flat rate. An
+owner creates an `ai_tools` row (console Tools table, or `PUT
+/internal/ai/tools`; the CLI's `gemmein ai tools` lists, sets and removes
+them, and the local rail reads `gemmein/ai/tools/<name>.json`) — a slug,
+a label, a provider, an optional pinned model, a credit price (1 to
+10,000), an optional `requires` entitlement key, and optional bounds
+(`maxBodyBytes`, `maxOutputTokens`, `stream`). `g.ai.chat` and `g.ai.text`
+take a new `tool` option naming one; a call with no `tool` runs as the
+**default tool** — one credit, the app's configured provider, any allowed
+model — so every existing integration keeps working unchanged. Up to 50
+tools per environment.
+
+New codes: `unknown_tool` (404 — no tool by that name), `tool_disabled`
+(403 — the owner switched it off), `entitlement_required` (403 — the
+message names the plan or product the tool requires), `model_pinned`
+(403 — the tool's model is fixed; leave `model` out of the body),
+`provider_not_configured` (409 — creating a tool on a provider with no
+key set), `too_many_tools` (409 — 50 tools per environment) and
+`invalid_tool` (400 — a bad field creating or updating a tool).
+
+A response from a named tool now carries `x-gemmein-tool` — the tool's slug —
+alongside `x-gemmein-credits-remaining`. `x-gemmein-tool` names the tool;
+absent on the implicit default.
+
 ## [0.7.0] — 2026-09-04
 
 ### Credits and the AI route

package/REFERENCE.md

@@ -238,6 +238,16 @@ Plans are `g.subscriptions`; one-off things are `g.payments`. `checkout` and
 don't also redirect to the returned `url`, and never build a Stripe URL
 yourself. Gate features on `(await g.subscriptions.mine())?.plan === "pro"`;
 gate one-off fulfilment on the receipt record, never the redirect.
+
+A product is sold one of three ways, set on the Payments page: **via a
+Stripe Payment Link** (`buy` navigates there); **via a relay** — any
+provider whose webhook the founder maps (GoCardless, Lemon Squeezy,
+Paddle, bank transfer) fulfils it with the `fulfil_product` relay
+action, and refunds it with `refund_product`; or **not yet** — the
+product is defined, its grants and credits are known, no road wired.
+`buy` on a product sold via a relay or not yet answers 409
+`product_not_sellable`. The price always comes from the provider — the
+Payment Link or the relay — never the app.
 By-hand grants (trial, promotion, a support comp) are not listed to the
 app — a gated read simply succeeds — so never rebuild the paywall from
 `mine()`; let the server refuse with `entitlement_required`. The two grant
@@ -274,7 +284,7 @@ honestly, not hidden.)
 ## Credits — `g.credits` / `gemmeinServer(sk).spendCredits`
 
 A balance your customers hold and your product spends: a pack they buy, a
-comp the owner gives, a call that costs one. Credits are a **quantity beside
+comp the owner gives, an AI tool call priced in credits. Credits are a **quantity beside
 access**, never access itself — a locked collection still asks for the
 entitlement, whatever the balance. The ledger adds at every purchase, grant
 and refund, subtracts at every spend, and never goes below zero: a spend
@@ -302,8 +312,9 @@ Where credits come from, and where they go:
   ledger lines and the credits the person spent in the last 30 days.
 - **A relay** adds with `grant_credits { amount (1..10,000), reason? }` — see
   **Relays**.
-- **Your server** spends with `spendCredits`; **the AI route** spends one per
-  call (see **AI**). Nothing spends from the browser.
+- **Your server** spends with `spendCredits`; **the AI route** spends the
+  credits the owner set for the named tool, one by default (see **AI**).
+  Nothing spends from the browser.
 - Spend lines are kept 90 days on the cloud rail; purchases, grants and
   clawbacks are kept. A balance carries at most 1,000,000,000. Account
   erasure removes the person's balance and ledger.
@@ -345,22 +356,43 @@ connected.
 ## AI — `g.ai.chat` / `g.ai.text`
 
 Your app talks to **OpenAI, Anthropic or Google** through Gemmein, on the
-**owner's own provider key**, which never reaches the browser. The owner
-pastes the key once in the dashboard's Keys room; it is write-only from then
-on. A signed-in person's request costs **one credit**, spent before the
-request is forwarded; the provider bills the tokens on the owner's own
-account. The route forwards the provider's own request body as sent — minus
-the `provider` field, and for Google minus `model` and `stream`, which ride
-the URL — adds the provider's auth headers, `content-type` and `accept`, and
-passes the status and the bytes straight back — a stream stays a stream. It does not choose models, cache, summarise,
-moderate or reshape anything, and it is for the browser only: a server key is
-refused (`403 scope_denied`) — a server calls the provider directly.
+**owner's own provider key**, which never reaches the browser, through a
+**named AI tool** — a slug the owner prices in credits, pins a model or
+provider to, and gates behind an entitlement, from the dashboard's Tools
+page or a local `gemmein/ai/tools/<name>.json` file. Removing a tool is a
+step-up action, like removing a key. A call that names no
+`tool` runs as the **default tool**: one credit, the app's configured
+provider, any allowed model — every existing integration that never passed
+`tool` keeps working unchanged. The owner pastes each provider key once in
+the dashboard's Keys room; it is write-only from then on. The route
+forwards the provider's own request body as sent — minus the `provider`
+field, and for Google minus `model` and `stream`, which ride the URL — adds
+the provider's auth headers, `content-type` and `accept`, and passes the
+status and the bytes straight back — a stream stays a stream. It does not
+choose models, cache, summarise, moderate or reshape anything, and it is for
+the browser only: a server key is refused (`403 scope_denied`) — a server
+calls the provider directly.
 
 | Method | Signature | Returns |
 |--------|-----------|---------|
-| `ai.chat` | `(body: object, options?: { provider?: "openai" \| "anthropic" \| "google"; signal?: AbortSignal })` | `Promise<Response>` — the fetch `Response`, untouched: the provider's status, headers and body, streaming intact. A non-2xx from the provider is returned as-is (not thrown) — an answer carrying `x-gemmein-credits-remaining` passed the spend and is the provider's; a Gemmein refusal throws `GemmeinError` |
-| `ai.text` | `(body: object, options?)` | `Promise<string>` — a non-stream call collected to one string, whichever provider answered (openai `choices[0].message.content`; anthropic `content[].text` joined; google `candidates[0].content.parts[].text` joined); a provider's non-2xx throws `provider_error` with the provider's status and message |
-
+| `ai.chat` | `(body: object, options?: { tool?: string; provider?: "openai" \| "anthropic" \| "google"; signal?: AbortSignal })` | `Promise<Response>` — the fetch `Response`, untouched: the provider's status, headers and body, streaming intact. A non-2xx from the provider is returned as-is (not thrown) — an answer carrying `x-gemmein-credits-remaining` passed the spend and is the provider's; a Gemmein refusal throws `GemmeinError` |
+| `ai.text` | `(body: object, options?: { tool?: string; provider?: …; signal?: AbortSignal })` | `Promise<string>` — a non-stream call collected to one string, whichever provider answered (openai `choices[0].message.content`; anthropic `content[].text` joined; google `candidates[0].content.parts[].text` joined); a provider's non-2xx throws `provider_error` with the provider's status and message |
+
+- `tool` names an `ai_tools` row by its slug; omit it for the default tool.
+  An unknown name is `404 unknown_tool`; a tool the owner switched off is
+  `403 tool_disabled`; a tool gated with `requires` refuses a person who
+  lacks that entitlement with `403 entitlement_required` (the message names
+  the plan or product). A tool with a pinned `model` refuses a body that
+  sets one with `403 model_pinned`; a tool with no pinned model follows the
+  allowlist rule below. A tool's own `bounds.maxBodyBytes` (≤ 262,144)
+  replaces the default 256 KB cap. `bounds.maxOutputTokens` is a ceiling: a
+  larger or absent value in the body becomes the bound; a smaller one stays.
+  It reaches the provider as ONE field, never two: the ceiling is written
+  onto the field the body already used, and a second spelling of the same
+  ceiling is folded away, so a browser cannot buy more output by naming the
+  field the route was not watching. A body that names none is sent the
+  current field — `max_completion_tokens` on OpenAI, `max_tokens` on
+  Anthropic, `generationConfig.maxOutputTokens` on Google.
 - `body` is exactly what the provider documents for its chat endpoint —
   OpenAI chat completions, Anthropic messages, Google generateContent. Its
   `model` field, when present, must match `^[A-Za-z0-9._:-]{1,80}$`; Google
@@ -368,19 +400,24 @@ refused (`403 scope_denied`) — a server calls the provider directly.
   20 — the Keys room's test call uses the first), any other answers
   `403 model_not_allowed`.
 - `provider` is optional when one key is configured and required when more
-  than one is (`400 provider_required`). No key at all is
-  `409 ai_not_configured`. `?provider=` and `?stream=1` on the URL do what
-  the body fields do.
-- Two response headers from Gemmein on every answer that passed the spend:
-  `x-gemmein-credits-remaining` (the balance after this call) and, on a
-  refund, `x-gemmein-credit: refunded`.
-- **The refund rule.** A credit is refunded only when the provider fails
-  before its first byte (a non-2xx, or `502 provider_unreachable`). A stream
-  that dies after the first byte is not refunded; hanging up early does not
-  refund. A provider that echoes the key in a refusal reaches the app as
-  `***<hint>`.
+  than one is (`400 provider_required`); a named tool fixes its own
+  provider, and a `provider` in the body or `?provider=` that disagrees with
+  it is `400 invalid_body`. No key at all is `409 ai_not_configured`.
+  `?provider=` and `?stream=1` on the URL do what the body fields do.
+- Response headers from Gemmein. `x-gemmein-credits-remaining` (the balance
+  after this call) rides every answer that passed the spend.
+  `x-gemmein-credit` reads `refunded`, and is there only when the credits
+  came back. `x-gemmein-ai` reads `fake`, and is there only on the local
+  engine's rehearsal answer. `x-gemmein-tool` names the tool; absent on the
+  implicit default.
+- **The refund rule.** The tool's credits are refunded only when the
+  provider fails before its first byte (a non-2xx, or
+  `502 provider_unreachable`). A stream that dies after the first byte is
+  not refunded; hanging up early does not refund. A provider that echoes
+  the key in a refusal reaches the app as `***<hint>`.
 - Limits: 20 calls per person per minute (`429 ai_capped`, `resetAt`), 256 KB
-  body (`413 payload_too_large`) nested at most 32 levels (`400 invalid_body`),
+  body by default (`413 payload_too_large`, unless a tool sets a smaller
+  `bounds.maxBodyBytes`) nested at most 32 levels (`400 invalid_body`),
   170 s in all and, on a stream, 10 s to the first response headers. Every
   `/ai/chat` call counts toward the app's `api_requests` band like any other
   request.
@@ -389,24 +426,31 @@ refused (`403 scope_denied`) — a server calls the provider directly.
 const res = await g.ai.chat({
   model: "gpt-4o-mini", stream: true,
   messages: [{ role: "user", content: text }]
-}, { provider: "openai" })
+}, { tool: "deep-research" })
 for await (const chunk of res.body) render(chunk)      // the provider's SSE, byte for byte
 
-const answer = await g.ai.text({ model: "gpt-4o-mini", messages: [{ role: "user", content: text }] })
+const answer = await g.ai.text({ messages: [{ role: "user", content: text }] }, { tool: "deep-research" })
 ```
 
 | code | status | meaning · do |
 |------|--------|--------------|
-| `credits_exhausted` | 402 | The person's balance is 0 — the message carries it. Show the pack |
+| `unknown_tool` | 404 | No AI tool by this name in this environment — check the slug or the environment |
+| `tool_disabled` | 403 | The owner switched this tool off — turn it on, or use another |
+| `entitlement_required` | 403 | The tool's `requires` names a plan or product this person lacks — the message names it |
+| `model_pinned` | 403 | This tool's model is fixed — leave `model` out of the body |
+| `provider_not_configured` | 409 | Creating or updating a tool: no key is set for that provider yet — add one on the Keys page first |
+| `too_many_tools` | 409 | This environment already holds 50 AI tools — delete one before adding another |
+| `invalid_tool` | 400 | Creating or updating a tool with a bad field — the message names which one and its rule |
+| `credits_exhausted` | 402 | The person's balance is below the tool's price — the message names the tool, the price and the balance ("Deep Research costs 20 credits. You have 7.", singular for 1). Show the pack |
 | `ai_not_configured` | 409 | No provider key on this app and environment — the owner pastes one in the Keys room |
 | `provider_required` | 400 | More than one provider key is set — pass `provider` |
-| `model_not_allowed` | 403 | The owner's allowlist names the models this app may call; the message lists them |
+| `model_not_allowed` | 403 | The owner's allowlist names the models this app may call; the message lists them (only for a tool with no pinned model) |
 | `ai_capped` | 429 | 20 calls per person per minute — wait for `resetAt` |
-| `payload_too_large` | 413 | The body is over 256 KB — shorten the conversation you send |
-| `invalid_body` | 400 | The body must be the provider's JSON request object, nested at most 32 levels |
+| `payload_too_large` | 413 | The body is over the cap (256 KB, or the tool's own `bounds.maxBodyBytes`) — shorten the conversation you send |
+| `invalid_body` | 400 | The body must be the provider's JSON request object, nested at most 32 levels; or a named tool's own provider was contradicted |
 | `session_required` | 401 | No signed-in person — sign in first |
 | `scope_denied` | 403 | A secret key called the route — the route is for the browser; a server calls the provider directly |
-| `provider_unreachable` | 502 | The provider did not answer before the first byte — nothing was charged (the credit is refunded); retry |
+| `provider_unreachable` | 502 | The provider did not answer before the first byte — nothing was charged (the tool's credits are refunded); retry |
 | `provider_error` | the provider's | `g.ai.text` only (client-side): the provider's own non-2xx, its message in `err.message` |
 | `ai_test_capped` | 429 | The Keys room's test call — one a minute per app |
 
@@ -627,6 +671,8 @@ authorise on fields they cannot set, or from a receiver.
 | `grant_access` | `entitlement` (plan or product **name**, or `access:<slug>`), `expiresAt?` (`"30d"`, `"12h"`, `"2w"` or an ISO date), `reason?` (≤ 200, templated) | source `relay`, the seventh grant source; skipped when this event already granted |
 | `grant_credits` | `amount` (1..10,000), `reason?` (≤ 200, templated) | adds to the person's credit balance, once per event (a replay finds its own row); the ledger line reads "relay: <reason>"; a relay adds and never spends |
 | `revoke_access` | `entitlement` | ends every live grant of that entitlement the person holds; skipped when none |
+| `fulfil_product` | `product` (name, 1-40 chars), `ref?` (≤ 200, templated) | grants the product's key and credits to the event's person and writes the receipt, exactly as a Stripe purchase does; idempotent on `ref` (an absent `ref` → `rly:<eventId>`; a `ref` you wrote that names nothing on the event is refused, never replaced); a ref must be the provider's unique payment identifier; a ref already used by another purchase is refused and audited; the product's road must be this relay. The relay road binds by name: renaming or deleting the relay stops fulfilment until a relay with that name exists again; the product card shows it. |
+| `refund_product` | `product` (name, 1-40 chars), `ref?` (≤ 200, templated) | takes back what `fulfil_product` under the same `ref` granted; `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; idempotent on `ref` |
 | `email_person` | `subject` (≤ 300), `text` (≤ 10,000), `kind?: "event" \| "account"` | rides `notify()`'s caps (200 per app per hour, 5 event sends per person per day) and the owner's sends switch; deduped per event |
 | `call_url` | `url` | https only, no template in the URL, no IP literal, never a gemmein.com host, no credentials in the URL; `gemmein dev` allows http to localhost |
 
@@ -665,11 +711,16 @@ Egress refusals arrive as the action's error, naming the rule: `https_only`,
 ### Templates
 
 In string values only — `write_record.data`, `email_person.subject` / `text`,
-`grant_access.reason`; never in `call_url.url` or an `entitlement`:
+`grant_access.reason`, `fulfil_product.ref` / `refund_product.ref`; never in
+`call_url.url` or an `entitlement`:
 `{{event.a.b}}` (the raw body), `{{mapped.x}}`, `{{record.data.x}}`,
 `{{record.id}}`, `{{person.email}}`, `{{person.id}}`, `{{tick.periodStart}}`.
+Mapped fields ride into templates as `{{mapped.<name>}}`; `{{event.<path>}}`
+reads the raw payload.
 A path that names nothing renders empty and adds a warning to the event;
-objects render as JSON. No expressions, no filters.
+objects render as JSON. No expressions, no filters. The one place an empty
+render is a refusal rather than a blank is a `ref` you wrote on
+`fulfil_product` / `refund_product`.
 
 ### Lifecycle
 
@@ -823,6 +874,8 @@ Branch on `err.code`. The gate's own codes (`session_invalid`,
 | `invalid_response` (client-side, status 0) | the server answered 200 to `verifyEmailCode` without a session token — a proxy or mock in the path, not Gemmein | check `apiUrl` and anything rewriting responses; the call is safe to retry |
 | `authentication_required` (401) | checkout/subscription/pay without a signed-in user | sign the user in first |
 | `plan_has_no_link` (409) | the paid plan has no Payment Link pasted yet | ask the owner to paste it in their dashboard |
+| `product_not_sellable` (409) | `g.payments.buy` on a product sold via a relay or not yet — there is no Payment Link to open | tell the buyer how the product is sold, or ask the owner to wire a road |
+| `relay_missing` (400) | saving a relay action (or a product's `sold.relay`) names a relay that does not exist in this environment | create that relay first, or name one that exists |
 | `account_suspended` (403) | the app owner's account is suspended (billing) | the owner fixes payment at app.gemmein.com |
 | `credits_exhausted` (402) | the person's balance is below the spend — the message carries the balance ("this person has {balance} credits — the spend needs {amount}") | show the pack; never retry the same spend |
 | `ai_not_configured` (409) | no provider key on this app and environment | the owner pastes one in the Keys room |

package/dist/index.cjs

@@ -9,7 +9,7 @@ exports.gemmeinServer = gemmeinServer;
  *  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
+exports.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
@@ -394,8 +394,10 @@ 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.
+ * 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.
@@ -416,16 +418,24 @@ class AiClient {
      * `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`).
+     * 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 response = await fetch(new URL("/ai/chat", this.config.apiUrl), {
+        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" }),

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.7.0";
+export declare const SDK_VERSION = "0.8.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 const CLIENT_INFO = "gemmein-sdk/0.8.0";
 export declare class GemmeinError extends Error {
     readonly status: number;
     readonly code: string;
@@ -389,8 +389,15 @@ export declare class AccountClient {
 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. */
+     *  set; refused `provider_required` (400) when it is ambiguous. Refused
+     *  `invalid_body` when `tool` is also set and disagrees with the named
+     *  tool's own provider — leave `provider` out when you pass `tool`. */
     provider?: AiProvider;
+    /** W9.3b: a named AI tool (owner-configured in the console — credits,
+     *  gate and provider/model are the tool's, not this call's). Sent as
+     *  `?tool=`, never in the body. Omitted → the implicit default tool: one
+     *  credit, any allowed model, no gate. */
+    tool?: string;
     /** Abort the call — the stream closes; a call that dies mid-stream is
      *  not refunded. */
     signal?: AbortSignal;
@@ -429,8 +436,10 @@ export declare class 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.
+ * 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.
@@ -450,12 +459,17 @@ export declare class AiClient {
      * `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`).
+     * 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.
      */
     chat(body: Record<string, unknown>, options?: AiChatOptions): Promise<Response>;
     /**

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.7.0";
+export declare const SDK_VERSION = "0.8.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 const CLIENT_INFO = "gemmein-sdk/0.8.0";
 export declare class GemmeinError extends Error {
     readonly status: number;
     readonly code: string;
@@ -389,8 +389,15 @@ export declare class AccountClient {
 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. */
+     *  set; refused `provider_required` (400) when it is ambiguous. Refused
+     *  `invalid_body` when `tool` is also set and disagrees with the named
+     *  tool's own provider — leave `provider` out when you pass `tool`. */
     provider?: AiProvider;
+    /** W9.3b: a named AI tool (owner-configured in the console — credits,
+     *  gate and provider/model are the tool's, not this call's). Sent as
+     *  `?tool=`, never in the body. Omitted → the implicit default tool: one
+     *  credit, any allowed model, no gate. */
+    tool?: string;
     /** Abort the call — the stream closes; a call that dies mid-stream is
      *  not refunded. */
     signal?: AbortSignal;
@@ -429,8 +436,10 @@ export declare class 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.
+ * 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.
@@ -450,12 +459,17 @@ export declare class AiClient {
      * `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`).
+     * 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.
      */
     chat(body: Record<string, unknown>, options?: AiChatOptions): Promise<Response>;
     /**

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.7.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
@@ -378,8 +378,10 @@ export class 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.
+ * 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.
@@ -400,16 +402,24 @@ export class AiClient {
      * `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`).
+     * 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 response = await fetch(new URL("/ai/chat", this.config.apiUrl), {
+        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" }),

package/llms.txt

@@ -41,7 +41,8 @@ creating no accounts is the correct behavior until the verdict is in.
    built in; any provider that signs its webhooks drives access through a
    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 one credit per call (see The AI route),
+   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
@@ -56,7 +57,8 @@ creating no accounts is the correct behavior until the verdict is in.
    - 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 a model call is one credit
+     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
@@ -448,8 +450,8 @@ contents.
   Stripe stays built in; any provider that signs its webhooks drives
   access the same way.
   Does: write a record · grant access · revoke access · grant credits ·
-  email the person the event is about · call your URL (a signed notice to
-  a server YOU run).
+  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"
@@ -460,7 +462,8 @@ contents.
   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 is where Gemmein holds your provider key and makes a chat call for
-  a signed-in person at one credit each — see The AI route.
+  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
@@ -517,6 +520,54 @@ contents.
   - 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
@@ -645,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
@@ -723,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
@@ -751,9 +819,10 @@ contents.
   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, a call that costs one.
+  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 one per call;
+  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
@@ -801,70 +870,111 @@ contents.
   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.
+  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: your human pastes their provider key once in the dashboard's
-  Keys room (write-only: never shown again, never in the app's code); a
-  signed-in person's chat request reaches the provider through Gemmein and
-  costs one credit.
-  Does: takes the provider's OWN request body from a signed-in person,
-  spends one credit, forwards the body as sent — minus the `provider`
-  field, and for Google minus `model` and `stream`, which ride the URL —
-  with the key, content-type and accept added, passes the provider's
-  status and bytes straight back (a stream stays a stream), and refunds
-  the credit only when the provider fails before its first byte.
-  Does not: choose models, cache, summarise, moderate, or reshape the
-  request or the answer; run from a server key (`sk_` is refused); reach
-  any host but the three; price by token (one credit per call, whatever
-  the length); refund a call that dies mid-stream, or one the caller
-  abandons before the headers (hanging up early does not refund).
-  Needs something else when: 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
-  (the provider directly, from your server); the provider is not on the
-  list (write to hello@gemmein.com).
-  The case: "a chat app where each message costs one credit 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:
+  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 }]
-      }, { provider: "openai" })   // provider is optional when one key is set
+      }, { 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-credit: refunded  (a failure before the first byte)
+      //              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({ model: "gpt-4o-mini",
-        messages: [{ role: "user", content: text }] })
+      const answer = await g.ai.text({ messages: [{ role: "user",
+        content: text }] }, { tool: "deep-research" })
 
-  Branch on `err.code`: credits_exhausted (402 — the message carries the
-  balance; 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) · ai_capped (429 — 20 per person per minute; wait for
-  `resetAt`) · payload_too_large (413 — 256 KB) · invalid_body (400 — the
-  body must be the provider's JSON object, nested at most 32 levels) ·
-  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: 1 credit per call · 20/min/person · 256 KB
-  · 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; the owner may list up to 20 allowed models (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.
+  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
@@ -914,8 +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, grant credits, 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.7.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",