@gemmein/sdk 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -12,6 +12,126 @@ 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
+
+Credits are a general consumable: a balance your customers hold and your
+product spends. A product carries `grantsCredits` (1..1,000,000) and each
+confirmed purchase adds that many to the buyer's balance, idempotent on the
+payment; a full refund claws back what is still unspent, floor zero. The
+browser reads the balance with `g.credits.balance()`; a server spends with
+`gemmeinServer(sk).spendCredits(personId, { amount?, reason, key? })` behind
+the fourth key capability, "Spend a person's credits" — one atomic
+decrement, refused whole below zero with `402 credits_exhausted` and the
+balance in the message, at-most-once on `key`. `Holdings.credits` is
+`{ balance }` from engine 0.8.0 (the type is unchanged; an older local engine
+still answers `null`). A relay adds with `grant_credits`; the owner comps
+from the person's page. Credits never expire and are never priced by token.
+
+The AI route lets a browser session call OpenAI, Anthropic or Google through
+Gemmein on the owner's own provider key, pasted once in the Keys room and
+write-only from then on. `g.ai.chat(body, { provider?, signal? })` spends one
+credit, forwards the provider's own request body as sent (minus `provider`,
+and for Google `model` and `stream`, which ride the URL) with the auth
+headers, `content-type` and `accept` added, and returns the fetch `Response`
+untouched — the provider's answer, 2xx or not, is yours to read; a stream
+stays a stream. `g.ai.text(body)` collects a non-stream answer to one string
+per provider and throws `provider_error` on a provider's own non-2xx. A
+credit is refunded only when the provider fails before its first byte
+(`x-gemmein-credit: refunded`); a stream that dies mid-way does not refund,
+and hanging up before the headers does not refund. A secret key is refused
+(`403 scope_denied`): a server calls the provider directly. The codes that
+join `GemmeinError`: `credits_exhausted`, `credits_ceiling`,
+`dedupe_conflict`, `invalid_amount`, `invalid_reason`, `invalid_key`,
+`person_not_found`, `capability_required`, `invalid_body`,
+`ai_not_configured`, `provider_required`, `model_not_allowed`, `ai_capped`,
+`payload_too_large`, `session_required`, `scope_denied`,
+`provider_unreachable`, and `provider_error` from `g.ai.text`. `REFERENCE.md`
+carries the Credits and AI chapters; `llms.txt` carries both capability
+cards. `gemmein dev` answers a fake provider without a key and its pay
+simulator honours the `grantsCredits` a product declares in
+`gemmein/payments.json` (`gemmein payments setup` asks for it).
+
+The ledger's laws, stated: a full refund claws back what that purchase's own
+ledger row granted, whatever the product says today; a balance carries at
+most 1,000,000,000 (`credits_ceiling`, nothing added past it); a server
+spend's `key` is scoped to the person, so one order id reused for two people
+charges both and a key that names a different movement is `dedupe_conflict`;
+the person's page shows the credits that person spent in the last 30 days; a
+provider that echoes the key in a refusal reaches the app as `***<hint>`.
+
+### Added
+- `g.credits.balance()` → `GET /auth/credits` → `{ balance }` (session required).
+- `g.ai.chat(body, { provider?, signal? })` → `POST /ai/chat`; answers the
+  fetch `Response` untouched (streaming intact) whenever the answer passed
+  the spend — the provider's own status and body, 2xx or not; Gemmein's
+  refusals throw `GemmeinError` with the engine's code — `credits_exhausted`
+  (402), `ai_not_configured` (409), `provider_required` (400),
+  `model_not_allowed` (403), `ai_capped` (429), `payload_too_large` (413),
+  `invalid_body` (400), `session_required` (401), `scope_denied` (403),
+  `provider_unreachable` (502).
+- `g.ai.text(body, options?)` — the non-streaming answer as a string
+  (OpenAI `choices[0].message.content`; Anthropic `content[].text`;
+  Google `candidates[0].content.parts[].text`); `invalid_response` when
+  no text came back; `provider_error` (the provider's status and message)
+  on a provider's own non-2xx.
+- `gemmeinServer(sk).spendCredits(personId, { amount?, reason, key? })` →
+  `POST /server/people/:id/credits/spend` → `{ ok, spent, deduped,
+  balance: { before, after }, event: { id, reason, actor } }` (a deduped
+  repeat answers `spent: 0` and the same event); needs the key's "Spend a
+  person's credits" capability; `402 credits_exhausted`.
+- `Holdings.credits` is filled (`{ balance }`) from engine 0.8.0 — the
+  type is unchanged.
+- Relays: `grant_credits { amount 1..10,000, reason? }` action, mirrored
+  in `@gemmein/mcp`'s offline validator.
+- Console: the Keys room's AI provider card (set · test · replace ·
+  remove), "Grants credits" on a product, CREDITS + Grant credits + the
+  ledger on a person, the Usage room's "AI calls" row.
+
 ## [0.6.0] — 2026-09-04
 
 ### Changed

package/REFERENCE.md

@@ -27,7 +27,7 @@ that passes `baseUrl` to reach a local or staging server quietly talks to
 production instead. Exposes read/update on collections without a signed-in user,
 `notify()` to email one of your app's own verified people (see **Notify**),
 the gate — `verifySession()` / `holdings()` / `grantAccess()` /
-`revokeAccess()` / `invitePerson()`, for code of yours running on your own
+`revokeAccess()` / `invitePerson()` / `spendCredits()`, for code of yours running on your own
 host (see **Server gate**) — plus `testSession()` for CI self-tests (dev
 environments only — see **Reaffirm**).
 
@@ -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
@@ -271,6 +281,188 @@ 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, 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
+past the balance is refused whole (`402 credits_exhausted`, the balance in
+the message), never partly. No expiry. No per-token pricing.
+
+| Surface | Signature | Returns |
+|---------|-----------|---------|
+| `g.credits.balance` | `()` | `Promise<{ balance: number }>` — the signed-in person's balance now (`401 session_required` without a session) |
+| `gemmeinServer(sk).spendCredits` | `(personId, { amount?: number; reason: string; key?: string })` | `Promise<{ ok: true; spent: number; deduped: boolean; balance: { before: number; after: number }; event: { id, reason, actor } }>` — `amount` defaults to 1 (1..10,000); `reason` ≤ 200 chars is what the owner reads on the person's ledger; `key` makes the spend at-most-once per person (a repeat answers `deduped: true`, `spent: 0`, the same `event`, and moves nothing; one key reused for a second person charges that person). Needs **"Spend a person's credits"** ticked on the key (`403 capability_required` otherwise) |
+| `Holdings.credits` | — | `{ balance: number }` on `verifySession()` and `holdings()` from engine 0.8.0 (`null` from an older local engine) — one verify answers who, what they hold and how many |
+
+Where credits come from, and where they go:
+
+- **A product with `grantsCredits`** (the "Grants credits" field on the
+  Payments page, 1..1,000,000). Each confirmed purchase **adds** that many to
+  the buyer's balance — two packs make double, never a reset — idempotent on
+  the payment. A purchase by an email that has never signed in creates the
+  person and credits them. A **full** refund claws back what that purchase's
+  own ledger row granted — at most what is still unspent, floor 0 — whatever
+  the product says today; a partial refund moves nothing. The purchase, the
+  grant and the clawback are each one ledger line.
+- **The owner's dashboard** comps by hand from the person's page (≤100,000 per
+  action, a note required), and shows the balance, the newest 50 non-spend
+  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 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.
+
+```ts
+// browser — show the balance
+const { balance } = await g.credits.balance()
+
+// server — one export costs one credit; the key makes a retry safe
+const r = await gemmeinServer(process.env.GEMMEIN_SECRET_KEY).spendCredits(person.id, {
+  amount: 1, reason: "export", key: `export:${jobId}`
+})
+// r = { ok: true, spent: 1, deduped: false, balance: { before: 12, after: 11 },
+//       event: { id: "cev_…", reason: "export", actor: "<the key's name>" } }
+// a retry with the same key: { …, spent: 0, deduped: true, event: the same one }
+// GemmeinError 402 credits_exhausted — "this person has 0 credits — the spend needs 1"
+```
+
+| code | status | meaning · do |
+|------|--------|--------------|
+| `credits_exhausted` | 402 | The 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 |
+| `session_required` | 401 | `g.credits.balance()` without a signed-in person — sign in first |
+| `capability_required` | 403 | `spendCredits` on a key without "Spend a person's credits" — mint one with it ticked |
+| `person_not_found` | 404 | No person with this id in this app and environment — ids come from `verifySession` or the dashboard |
+| `invalid_amount` | 400 | `amount` outside 1..10,000 (or not a whole number) |
+| `invalid_reason` | 400 | `reason` missing, not text, or over 200 chars |
+| `invalid_key` | 400 | `key` not text, empty, or over 200 chars |
+| `dedupe_conflict` | 409 | The `key` already names a different movement (another kind, or another person) — a key is one movement; reuse it only to retry that same one |
+| `credits_ceiling` | 409 | A credit that would carry the balance past 1,000,000,000 — nothing was added |
+
+`gemmein dev` keeps the same ledger in memory with snapshot and restore, and
+its pay simulator honours the `grantsCredits` a product declares in
+`gemmein/payments.json` (`gemmein payments setup` asks for it), so the
+buy-then-spend loop runs on your machine before a payment provider is
+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, 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?: { 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
+  needs it (it rides the URL); when the owner lists allowed models (up to
+  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`); 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 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.
+
+```ts
+const res = await g.ai.chat({
+  model: "gpt-4o-mini", stream: true,
+  messages: [{ role: "user", content: text }]
+}, { 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({ messages: [{ role: "user", content: text }] }, { tool: "deep-research" })
+```
+
+| code | status | meaning · do |
+|------|--------|--------------|
+| `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 (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 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 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 |
+
+`gemmein dev` answers a fake provider without a key (header `x-gemmein-ai:
+fake`, an echo stream), so the loop runs locally; set
+`GEMMEIN_AI_KEY_OPENAI`, `GEMMEIN_AI_KEY_ANTHROPIC` or `GEMMEIN_AI_KEY_GOOGLE`
+in the local rail's environment for a real call. The owner's Usage room
+counts AI calls for the last 30 days: spent by the customers' credits, priced
+by the provider — Gemmein meters the calls, the provider bills the tokens.
+
+---
+
 ## Server gate — `gemmeinServer(sk).verifySession` / `holdings` / `grantAccess` / `revokeAccess` / `invitePerson`
 
 Gemmein hosts no compute. **Your own** function — Vercel, a VPS, a cron box,
@@ -290,7 +482,7 @@ signed in, it can create them by email first.
 type Holdings = {
   access: string[]                 // the keys they hold NOW — ["access:pro"]
   grants: Grant[]                  // the LIVE grants behind them (revoked/expired are gone)
-  credits: { balance: number } | null   // reserved — null today; credits are NOT shipped
+  credits: { balance: number } | null   // the balance now (engine 0.8.0+); null from an older local engine — see Credits
 }
 
 type Grant = {
@@ -313,12 +505,13 @@ type Grant = {
   (`relay` is the kind a relay's `grant_access` writes; see
   **Relays**). Gate
   on what a person *holds*, never on what they pay. Person id, never an email.
-- **Three capabilities, ticked by the human.** `verifySession` needs none.
+- **Four capabilities, ticked by the human.** `verifySession` needs none.
   `holdings` needs **"Look up a person's access by id"**; `grantAccess` and
   `revokeAccess` need **"Grant and revoke access"**; `invitePerson` needs
-  **"Create a person by email before they sign in"** — plain-English checkboxes
-  the owner ticks when minting the key. Existing keys have all three off, so
-  nothing in production changes.
+  **"Create a person by email before they sign in"**; `spendCredits` needs
+  **"Spend a person's credits"** — plain-English checkboxes the owner ticks
+  when minting the key. Existing keys have all four off, so nothing in
+  production changes.
 - **The invite door.** `invitePerson(email)` is how your server addresses
   someone who has never signed in — the envelope, the invoice, the client
   portal, the booking-winner email: create the person, hand them the file,
@@ -353,7 +546,7 @@ type Grant = {
 | `session_revoked` | 401 | A newer sign-in, a sign-out, or the owner ended it — send them back to sign-in |
 | `person_suspended` | 403 | The owner suspended this person — access is off until the owner reactivates them in the dashboard |
 | `person_not_found` | 404 | No person with this id in this app and environment — ids come from `verifySession` or the dashboard, never from an email. Existence is never leaked |
-| `capability_required` | 403 | The key's box isn't ticked — mint a key with "Look up a person's access by id" / "Grant and revoke access" / "Create a person by email before they sign in" ticked (purchase and subscription grants come from the built-in Stripe path; another provider's payment grants through a relay) |
+| `capability_required` | 403 | The key's box isn't ticked — mint a key with "Look up a person's access by id" / "Grant and revoke access" / "Create a person by email before they sign in" / "Spend a person's credits" ticked (purchase and subscription grants come from the built-in Stripe path; another provider's payment grants through a relay) |
 | `invalid_email` | 400 | `invitePerson`: the address must look like `name@domain` — trimmed, one `@`, a dotted domain, at most 254 characters, no whitespace |
 | `invite_capped` | 429 | `invitePerson`: this app has made 500 invite calls today — the limit is temporary; write to hello@gemmein.com to raise it. `err.resetAt` says when the window ends |
 | `invalid_source` | 400 | `purchase` / `subscription` asked for by hand — refused; those come from Stripe's signed webhook, and another provider's payment grants through a relay |
@@ -364,7 +557,7 @@ type Grant = {
 | `invalid_body` | 400 | One malformed field, whichever it is — `token` (missing, not a string, over 512 chars), `expiresAt` (unparseable or in the past), `reason` (not text, over 200 chars). Branch on the code, read the **message**: it names the field |
 | `scope_denied` | 403 | Not a secret key — the gate is server-only, never the browser |
 | `invalid_id` | 400 | A prototype name (`__proto__`, `constructor`, `prototype`) was sent as a person id or a grant id. Ids come from `verifySession()` or the dashboard — never from a name |
-| `unknown_route` | 404 | Not one of the gate's five routes — the message lists them all |
+| `unknown_route` | 404 | Not one of the gate's six routes — the message lists them all |
 | `method_not_allowed` | 405 | The right route, the wrong verb: `verifySession`, `grantAccess`, `revokeAccess` and `invitePerson` are POST, `holdings` is GET |
 
 ---
@@ -476,7 +669,10 @@ authorise on fields they cannot set, or from a receiver.
 |---|---|---|
 | `write_record` | `collection`, `data`, `to?: "person"` | keyed per event so a retry never duplicates; written through the same door as your app (plain-text and file laws apply); `to: "person"` addresses it to the event's person and is required on addressed and direct collections; the record is app-owned |
 | `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 |
 
@@ -515,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
 
@@ -662,11 +863,28 @@ Branch on `err.code`. The gate's own codes (`session_invalid`,
 | `invalid_expand` | `expand` on a field/rule with no link shape | join in memory instead (private/public_read/admin_write have no links) |
 | `scope_denied` | secret key used outside its dashboard-configured scope (or on auth/management routes) | scope the key to that collection, or use the right surface |
 | `unsupported_file_type` (415) | upload isn't an allowed type | images (JPEG/PNG/WebP/GIF/HEIC) or documents (PDF/ZIP/EPUB) |
-| `invalid_key` | a keyed create's `key` breaks the charset/length law | 1-120 chars of letters, numbers, `: _ . @ / -` |
+| `invalid_key` | a keyed create's `key` breaks the charset/length law — or `spendCredits`' `key` is not text of up to 200 chars | 1-120 chars of letters, numbers, `: _ . @ / -` (a create); text ≤ 200 (a spend) |
+| `invalid_amount` / `invalid_reason` (400) | `spendCredits`: `amount` outside 1..10,000, or `reason` missing / over 200 chars | fix the field the code names |
+| `dedupe_conflict` (409) | `spendCredits`: the `key` already names a different movement (another kind or another person) | a key is one movement — reuse it only to retry that same one |
+| `credits_ceiling` (409) | a credit would carry the balance past 1,000,000,000 (a comp, a pack, a relay grant) — nothing was added | the balance is at its most |
+| `invalid_body` (400) | on `g.ai.chat`: the body is not the provider's JSON request object, or is nested deeper than 32 levels | send the provider's own request object |
+| `provider_error` (client-side, the provider's status) | `g.ai.text`: the provider answered a non-2xx; `err.message` is the provider's own reason | read it — the credit was refunded when the provider failed before its first byte |
+| `ai_test_capped` (429) | the Keys room's test call — one a minute per app | wait a minute |
 | `invalid_secret_key` (client-side) | `gemmeinServer()` got a missing/`pk_` key | pass the `sk_` key from a server env var |
 | `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 |
+| `provider_required` (400) | more than one provider key is set and the call named none | pass `provider` |
+| `model_not_allowed` (403) | the owner's allowlist does not name this model | use one the message lists |
+| `ai_capped` (429) | 20 AI calls per person per minute | wait for `resetAt` |
+| `payload_too_large` (413) | on `g.ai.chat`: the body is over 256 KB | shorten the conversation you send |
+| `session_required` (401) | `g.ai.chat` / `g.credits.balance` without a signed-in person | sign in first |
+| `scope_denied` (403) | on `g.ai.chat`: 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; the credit is refunded | retry |
 
 Keys: `pk_` (public, domain-locked, browser-safe) vs `sk_` (secret, server only).