@gemmein/sdk 0.5.0 → 0.7.0

package/REFERENCE.md

@@ -27,9 +27,9 @@ 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()`, for code of yours running on your own host (see **Server
-gate**) — plus `testSession()` for CI self-tests (dev environments only —
-see **Reaffirm**).
+`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**).
 
 The client has two layers. **Your app's collections** — `g.collection(name)`
 (the canonical spelling; `g.storage.collection(name)` is the same client). And
@@ -184,7 +184,7 @@ type ListResult<T> = {
 };
 
 type ListOptions = {
-  limit?: number;
+  limit?: number;                    // 25 by default, 100 at most — a larger ask is refused (400 invalid_limit); page with cursor
   sort?: "newest" | "oldest" | "updated";
   where?: Record<string, unknown>;   // exact-match on data fields (and link fields)
   cursor?: string;                   // from a previous ListResult
@@ -271,11 +271,160 @@ honestly, not hidden.)
 
 ---
 
-## Server gate — `gemmeinServer(sk).verifySession` / `holdings` / `grantAccess` / `revokeAccess`
+## 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
+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 one per
+  call (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. 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.
+
+| 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 |
+
+- `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`). 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>`.
+- 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`),
+  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 }]
+}, { provider: "openai" })
+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 }] })
+```
+
+| code | status | meaning · do |
+|------|--------|--------------|
+| `credits_exhausted` | 402 | The person's balance is 0 — the message carries it. 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 |
+| `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 |
+| `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_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,
 anywhere — asks Gemmein the only three questions it has: *who is this person,
-what do they hold, change what they hold.*
+what do they hold, change what they hold* — and, when the person has never
+signed in, it can create them by email first.
 
 | Method | Signature | Returns |
 |--------|-----------|---------|
@@ -283,18 +432,19 @@ what do they hold, change what they hold.*
 | `holdings` | `(personId)` | `Promise<{ ok: true, person: { id, email, role, suspended }, holdings: Holdings }>` — for the paths with no token in hand. A **suspended** person is returned, flagged `suspended: true`, with their holdings; `verifySession` refuses them |
 | `grantAccess` | `(personId, { entitlement, source?, expiresAt?, reason? })` | `Promise<{ ok: true, grant: Grant, holdings: Holdings }>` (201) — `holdings` is the state **after**; the owner's audit row carries before→after and the key's name |
 | `revokeAccess` | `(personId, grantId, { reason? }?)` | `Promise<{ ok: true, grant: Grant, holdings: Holdings }>` — the returned grant carries `revokedAt` |
+| `invitePerson` | `(email)` | `Promise<{ person: InvitedPerson, created: boolean }>` — create a person by email **before they sign in** (201 `created: true`), or find them (200 `created: false`); idempotent, case-insensitive, one id. `InvitedPerson = { id, email, role, invited, suspended }` — `invited` stays true until their first sign-in; a suspended person is returned flagged. The one server call that takes an email |
 
 ```ts
 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 = {
   id: string
   entitlement: string              // "access:<slug>" — the plan's or product's own key
-  source: "subscription" | "purchase" | "manual" | "trial" | "promotion" | "migration"
+  source: "subscription" | "purchase" | "manual" | "trial" | "promotion" | "migration" | "relay"
   startsAt: string
   expiresAt: string | null
   revokedAt?: string | null        // present on the grant revokeAccess returns
@@ -307,16 +457,29 @@ type Grant = {
 - **One call per request.** `verifySession` answers identity *and* holdings
   together — don't call it twice, and don't cache the answer past the request.
 - **Holdings, not billing.** The gate never returns subscription status,
-  amounts, Stripe ids, or a grant's `sourceId` — the source **kind** only. Gate
+  amounts, Stripe ids, or a grant's `sourceId` — the source **kind** only
+  (`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.
-- **Two capabilities, ticked by the human.** `verifySession` needs neither.
+- **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"** — plain-English checkboxes
-  the owner ticks when minting the key. Existing keys have both off, so nothing
-  in production changes.
+  `revokeAccess` need **"Grant and revoke access"**; `invitePerson` needs
+  **"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,
+  address the record, notify them; their first sign-in lands on a ready
+  account. The address is trimmed and lowercased; the person's row shows
+  "Invited · hasn't signed in yet" in the owner's dashboard until they sign
+  in, and is not counted in the people band before then. 500 invite calls per
+  app per day — a fetch of an existing person is a call too.
 - **Manual sources only.** `source` ∈ `manual | trial | promotion | migration`
-  (default `manual`). Purchases and subscriptions come only from Stripe — a key
-  cannot mint paid access. A key *may* end a payment-made grant (the same as the
+  (default `manual`). Purchases and subscriptions come from the built-in Stripe
+  path; a payment from any other provider that signs its webhooks drives access
+  through a relay (source `relay`). A key cannot mint paid access. A key *may* end a payment-made grant (the same as the
   dashboard's "end this access"); the payment itself is untouched.
 - **One grant, one reason.** `reason` (≤ 200 chars) is what the owner reads in
   their logs and is never edited. `sourceId` is minted per call, so two calls
@@ -339,8 +502,10 @@ 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" ticked (purchases still come only from Stripe) |
-| `invalid_source` | 400 | `purchase` / `subscription` asked for by hand — refused; those come only from Stripe |
+| `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 |
 | `invalid_entitlement` | 400 | Not a valid `access:<slug>` key — or drop the key and pass the plan's or product's own NAME, which the gate resolves for you |
 | `unknown_plan` | 400 | No plan or product by that name — the owner adds it on the Payments page. (Checkout's `unknown_plan` is a **404**; the gate's is a **400** — it is a bad argument to a write, not a missing resource) |
 | `grant_not_found` | 404 | Not this person's grant, in this app and environment — re-read `holdings` |
@@ -348,8 +513,203 @@ 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 four routes — the message lists them all |
-| `method_not_allowed` | 405 | The right route, the wrong verb: `verifySession`, `grantAccess` and `revokeAccess` are POST, `holdings` is GET |
+| `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 |
+
+---
+
+## Relays — `gemmein/relays/<name>.json`
+
+Route, map, authorise, never compute. A relay is one trigger — a
+provider's webhook arriving, a clock, a record changing — and one to ten of
+Gemmein's **own** verbs, run in order: write a record, grant or revoke access,
+email the person, call your URL. Gemmein runs no code of yours inside one;
+compute lives on your host, behind `call_url`. The definition is a JSON file
+your AI writes; the owner's dashboard shows it read-only with its receiver URL,
+its secrets (shown once), every event with each action's result, and a replay
+button. There is no SDK method: the surface is the file and the dashboard.
+Stripe stays built in; any provider that signs its webhooks — GoCardless, Paddle,
+Lemon Squeezy among them — drives access the same way through a relay, and the
+founder keeps their provider. This chapter is the full depth; `llms.txt` carries
+the card, the worked example and one pointer here.
+
+### The definition
+
+```jsonc
+{
+  "name": "gocardless-paid",             // ^[a-z][a-z0-9-]{1,62}$ — the file name AND the receiver URL's last segment
+  "trigger": { ... },                    // exactly one: receiver | schedule | data_change
+  "actions": [ ... ]                     // 1 to 10, run in order
+}
+```
+
+Unknown fields are refused **by name**, one sentence per problem
+(`invalid_definition`). A trigger's `kind` cannot change after creation —
+delete and create instead.
+
+### Triggers
+
+**`receiver`** — `POST /hooks/<appId>/<name>`, provider-agnostic.
+
+```jsonc
+{
+  "kind": "receiver",
+  "verify": { "scheme": "hmac_sha256_header", "header": "Webhook-Signature" },
+  "map": { "event_id": "events.0.id", "event_type": "events.0.action", "person_email": "events.0.details.customer_email" },
+  "when": { "event_type": "confirmed" }
+}
+```
+
+| `verify.scheme` | fields | what is checked |
+|---|---|---|
+| `hmac_sha256_header` | `header`, `timestampHeader?`, `toleranceSeconds?` (default and maximum 300), `encoding?: "hex" \| "base64"` (default hex) | HMAC-SHA256 of the raw body with the receiver secret; when `timestampHeader` is named, of `<timestamp>.<body>` inside the window. GoCardless: header `Webhook-Signature`, hex, raw body |
+| `stripe` | — | the `stripe-signature` header (`t=`/`v1=`), 5-minute window |
+| `svix` | — | `svix-id` / `svix-timestamp` / `svix-signature`, 5-minute window |
+| `shared_token` | `header?` (default `x-webhook-token`), `query?` (default `token`) | the token matches in either place — a query token travels in URLs, prefer the header |
+
+- **Secrets.** Minted by Gemmein at create (`rcv_…`), shown once, never readable
+  again; rotate mints a new one. A provider that only shows its own secret
+  (Stripe, svix senders) is stored through rotate with a `value`.
+- **`map`** — up to 20 names, each a dotted path into the body
+  (`events.0.details.customer_email`; prototype names are never followed).
+  `event_id` is the dedupe key: a repeat answers `{ received: true,
+  duplicate: true, eventId }` and runs nothing; without it the body's hash
+  deduplicates within the same UTC day. `event_type` is what `when` usually
+  reads. `person_email` names the person: created-or-fetched through the same
+  door as `invitePerson` (same daily cap, shown as invited until first sign-in,
+  audited with the relay as the actor). Every other name rides into
+  templates as `{{mapped.<name>}}`.
+- **`when`** — exact string match on the **mapped** fields; its keys must be in
+  the map. A non-match answers 200 `{ received: true, ignored: "when" }` and
+  records no event, so a typo in `when` reads as the provider never calling.
+  Test with a real event first.
+- **Answers.** 200 `{ received: true, eventId }` only once the event row is
+  stored — the row is the acknowledgement.
+
+| code | status | meaning |
+|---|---|---|
+| `unknown_receiver` | 404 | no receiver relay with this name on this app — a deleted one no longer receives, a paused one still does |
+| `bad_signature` | 401 | the signature did not verify against this receiver's secret — check the secret and the header the scheme expects |
+| `body_too_large` | 413 | over 256 KB |
+| `invalid_json` | 400 | the body is not JSON |
+| `receiver_capped` | 429 | more than 120 verified events in a minute for this app; `resetAt` says when. Unverified traffic never spends this budget |
+| `not_recorded` | 503 | the event could not be stored — nothing ran; send it again |
+
+The URL names no environment: the secret decides which environment's
+relay receives, so development and production may share a name, each
+with its own secret. Renaming a relay renames its URL.
+
+**`schedule`** — `{ "kind": "schedule", "every": "1d", "at": "09:00" }`.
+`every` ∈ `15m | 30m | 1h | 6h | 12h | 1d`; `at` is `HH:MM` UTC and only with
+`1d`. One tick per period; a relay created mid-period first fires next
+period; after a gap the most recent missed period runs late and older missed
+periods land as dead rows you can replay. A schedule has no person, so
+`grant_access`, `revoke_access`, `email_person` and `to: "person"` are refused
+on it at validation.
+
+**`data_change`** — `{ "kind": "data_change", "collection": "bookings", "on": ["created"], "where": { "status": "won" } }`.
+`on` ⊆ `created | updated | deleted`; `where` is an exact match on the record's
+data fields (server-managed fields are refused). Fires for writes from your
+app, the dashboard's editor and Stripe receipts, at most once per write per
+relay; never for the runner's own writes (the loop guard) and never for
+an account erasure. A `call_url` that writes back through the SDK does fire —
+a loop through your host is yours to avoid. A definition change applies within
+5 s. The person is the record's owner, else its recipient; an app-owned record
+has none and person actions on it record `skipped`. **Authorisation law:** a
+`where` on a field the signed-in user can write is a self-service grant —
+authorise on fields they cannot set, or from a receiver.
+
+### Actions
+
+| type | fields | notes |
+|---|---|---|
+| `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 |
+| `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 |
+
+**The `call_url` contract.** Gemmein POSTs JSON:
+
+```jsonc
+{
+  "id": "<event id>",                       // the same id on every retry and replay
+  "relay": { "id": "...", "name": "gocardless-paid" },
+  "trigger": "receiver",                    // receiver | schedule | data_change
+  "event": { ... },                         // the stored payload: { event, mapped } | { record, previous? } | { tick }
+  "person": { "id": "...", "email": "..." } | null,
+  "results": [ ... ]                        // the actions that ran before this one
+}
+```
+
+Headers: `content-type: application/json`, `user-agent: Gemmein-Relays/1`,
+`X-Gemmein-Signature: t=<unix seconds>,v1=<hex>` where `v1` is the HMAC-SHA256
+of `<t>.<body>` with the relay's signing secret (`asig_…`, shown once at
+create, rotatable). Verify over the raw body, in constant time. 2xx is done; a
+redirect is a failure and is never followed; 10 s timeout; the status and the
+first 4 KB of the answer are kept on the event. **Not idempotent on Gemmein's
+side:** every retry and replay POSTs the same `id` — deduplicate on it. The
+whole event rides in the body, so the URL receives private data.
+
+```js
+import { createHmac, timingSafeEqual } from "node:crypto";
+const [t, v1] = req.headers["x-gemmein-signature"].split(",").map((part) => part.slice(part.indexOf("=") + 1));
+const expected = createHmac("sha256", process.env.GEMMEIN_SIGNING_SECRET).update(`${t}.${rawBody}`).digest("hex");
+const ok = expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
+```
+
+Egress refusals arrive as the action's error, naming the rule: `https_only`,
+`ip_literal`, `own_host`, `unresolvable`, `private_address`.
+
+### Templates
+
+In string values only — `write_record.data`, `email_person.subject` / `text`,
+`grant_access.reason`; 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}}`.
+A path that names nothing renders empty and adds a warning to the event;
+objects render as JSON. No expressions, no filters.
+
+### Lifecycle
+
+Every trigger lands as a durable event row **before** any action runs.
+`queued → running → done`, or `failed` with retries at 1m, 5m, 30m, 2h, 8h,
+16h (seven attempts in all), then `dead`: the owner gets the
+`relay_failed` alert (on by default, switchable) and a replay button that
+resets the count. A definition-level failure (a suspended person, a missing
+collection, an unknown entitlement) is dead on the first attempt. Actions stop
+at the first failure; a retry or replay runs every action again, and
+`write_record`, `grant_access`, `revoke_access` and `email_person` each find
+their own earlier work and record `skipped` — `call_url` POSTs again. Events
+are kept 30 days. A paused relay still records receiver events and record
+changes (they wait for resume); schedule ticks during a pause are not
+recorded. Every run is one audit row with per-action before→after; every grant,
+email and record a relay makes is attributed to the relay by name.
+
+### Console codes
+
+| code | status | meaning |
+|---|---|---|
+| `invalid_definition` | 400 | one sentence naming the field, why, and what to do |
+| `relay_capped` | 400 | 20 relays in this environment — delete one, or fold two into one |
+| `name_taken` | 409 | a relay with this name exists in this environment |
+| `version_conflict` | 409 | the definition moved since it was read — re-read and reapply |
+| `not_replayable` | 409 | replay applies to a dead, failed or done event; a queued or running one is already on its way |
+| `unknown_environment` | 400 | the environment does not belong to this app |
+| `not_found` | 404 | no relay or event with this id in this app and environment |
+
+**Current limits:** 20 relays per environment, 10 actions each, 120
+events per minute, 32 KB stored per event (a larger body is truncated with a
+flag; `mapped` survives), events kept 30 days. Limits are raised on request:
+hello@gemmein.com.
+
+**Both rails.** `gemmein dev` runs receivers (the boot card prints each
+receiver's local URL), schedules and data changes with the same runner and
+prints `RELAY · <name> · <trigger> · <n actions> · ok|failed`;
+`npx gemmein sync` carries the files to the cloud app's development
+environment with the collections — contract, never data; the cloud mints its
+own secrets.
 
 ---
 
@@ -439,6 +799,7 @@ Branch on `err.code`. The gate's own codes (`session_invalid`,
 | `invalid_shape` | field not in a locked (live) collection's shape — or a file field given the wrong kind (the message names which) | after the field exists in development, one promote run adds it (the owner answers blank or a default) — until then send only the fields the shape has / send the kind the field takes |
 | `unknown_file` | a ref-shaped value points at a file that doesn't exist or isn't yours to hand — every rule, every write | fix the ref — never invent one |
 | `invalid_since` | `since` isn't a strict ISO 8601 timestamp, or came with `sort` | pass the previous answer's watermark; drop `sort` |
+| `invalid_limit` | `limit` isn't a whole number from 1 to 100 (the message says so: "limit must be between 1 and 100") | ask for at most 100 and page with `cursor` — nothing is clamped for you |
 | `not_a_customer` (404) | `notify()`'s recipient isn't a verified person of this app and environment | fix the person id — one code on purpose |
 | `in_flight` (409) | a `notify()` with the same `key` is sending right now | retry in a moment — a delivered send answers idempotently |
 | `invalid_audience` | `for` isn't a user of this app | fix the recipient id |
@@ -451,10 +812,26 @@ 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 |
 | `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).