@gemmein/sdk 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Changelog — @gemmein/sdk
+
+All notable changes to the SDK are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+semver. A change that asks something of your app has a note in
+[`migrations/`](./migrations/README.md) naming the version it arrived in
+and the version by which the action is required.
+
+The SDK and the local engine (`@gemmein/cli`) share a minor version from
+0.6.0 / 0.7.0 onward: a feature that lands in one lands in the other in
+the same release.
+
+## [Unreleased]
+
+## [0.6.0] — 2026-09-04
+
+### Changed
+- `list({ limit })` is honoured or refused, never clamped: a `limit`
+  outside 1..100 answers 400 `invalid_limit` ("limit must be between 1 and
+  100"). The default stays 25 and the maximum 100. Apps that asked for more
+  than 100 and read the first page as the whole set now get the refusal —
+  page with `cursor`. See `migrations/list-limit-refusal.md`.
+- `verifyEmailCode` throws `GemmeinError` with code `invalid_response`
+  (status 0) when a 200 answer carries no session token, where it threw a
+  bare `Error` before. Every error the SDK raises is now a `GemmeinError`.
+- `engines.node` is `>=20`. Node 18 reached end of life in April 2025; the
+  SDK is built and tested on 20 and 22.
+
+### Added
+- Relays. One JSON file, `gemmein/relays/<name>.json`: a trigger (a
+  provider's signed webhook at `POST /hooks/<appId>/<name>`, a schedule, or a
+  record change) and one to ten of Gemmein's own verbs (write a record, grant
+  or revoke access, email the person, call your URL), run in order with
+  retries and a replay button in the dashboard. No SDK method: the surface is
+  the file and the dashboard. `REFERENCE.md` carries the definition, the
+  triggers, the actions, the `call_url` contract and its signature header,
+  the templates, the lifecycle and the codes; `llms.txt` carries the
+  GoCardless worked example. A `call_url` that writes back through the SDK
+  fires `data_change` like any write. Stripe stays built in; any provider that
+  signs its webhooks drives access the same way.
+- `GrantSource` gains `relay`: a grant a relay's `grant_access`
+  wrote. `holdings` and `verifySession` list it by kind like the other six;
+  `ManualGrantSource` is unchanged — no key can mint it.
+- `gemmeinServer(...).invitePerson(email)` creates a person by email before
+  they sign in, or returns the one that exists (`{ person, created }`, type
+  `InvitedPerson`). Behind the third key capability, "Create a person by
+  email before they sign in". Refusals: `invalid_email`, `invite_capped`
+  (500 accepted calls per app per day, raised on request). An invited person
+  shows as invited on the person page until their first sign-in and is not
+  counted in the people band (the billable unit) until then.
+- Every request carries `x-client-info: gemmein-sdk/<version>`. The Keys
+  page shows the SDK build behind a key's most recent call ("Last seen
+  from gemmein-sdk/0.6.0, as reported"). `SDK_VERSION` and `CLIENT_INFO`
+  are exported.
+- `CHANGELOG.md` and `migrations/` ship in the package.
+
+## [0.5.0] — 2026-09-03
+
+### Added
+- The server gate on `gemmeinServer(sk)`: `verifySession(token)`,
+  `holdings(personId)`, `grantAccess(personId, { entitlement, reason? })`,
+  `revokeAccess(personId, grantId, { reason? })`. Grant and revoke require
+  the key's `grantAccess` capability (minted on the Keys page).
+- Exported types `Holdings`, `Grant`, `GatePerson`, `GrantSource`,
+  `ManualGrantSource`.
+
+## [0.4.7] — 2026-09-02
+
+### Changed
+- Documentation-only release. The packaged `llms.txt` and `REFERENCE.md`
+  carry the W5 teaching: a promote run carries new fields as well as new
+  collections.
+
+## [0.4.6] — 2026-08-26
+
+### Changed
+- `reaffirm.mjs` runs the 16-probe harness; its teachings are rewritten.
+
+## [0.4.5] — 2026-08-26
+
+### Changed
+- Documentation-only release. `REFERENCE.md` catches up with documents,
+  `since`, `watch()`, `notify()`, the file laws and `purchases.mine()`.
+
+## [0.4.4] — 2026-08-26
+
+### Added
+- `upload(file, { for })` addresses a file to one person; the file-kind
+  (image or document) and file-class teaching.
+
+## [0.4.3] — 2026-08-25
+
+### Added
+- `gemmeinServer(sk).notify(personId, { subject, text, kind?, key? })`.
+
+### Changed
+- `watch()` stops on an auth-terminal answer instead of retrying it.
+
+## [0.4.2] — 2026-08-25
+
+### Added
+- `list({ since })` with `ListResult.deleted` and `ListResult.watermark`;
+  `watch()` on a collection.
+
+## [0.4.1] — 2026-08-22
+
+### Added
+- `GemmeinError.requires` (and `requiresAny`) on 403 `entitlement_required`,
+  on both the collection path and the runtime clients.
+
+## [0.4.0] — 2026-07-30
+
+### Changed
+- A product's file lives on the product card and the purchase is the
+  authorisation to read it.
+
+## [0.3.2] — 2026-07-29
+
+### Fixed
+- The wave-audit fixes for the 0.3 line.
+
+## [0.3.1] — 2026-07-29
+
+### Changed
+- Documentation: the guide teaches paid access.
+
+## [0.3.0] — 2026-07-29
+
+### Added
+- The file reference contract: records store references, files resolve
+  through the SDK.
+
+## [0.2.1] — 2026-07-22
+
+### Changed
+- Documentation-only refresh.
+
+## [0.2.0] — 2026-07-22
+
+### Changed
+- Two-layer shape: `g.collection(name)` plus the self-service primitives.
+
+## [0.1.0] — 2026-07-11
+
+### Added
+- First published release: built `dist`, persistent sessions, journey
+  signposts.

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()`, 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,12 @@ honestly, not hidden.)
 
 ---
 
-## Server gate — `gemmeinServer(sk).verifySession` / `holdings` / `grantAccess` / `revokeAccess`
+## 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,6 +284,7 @@ 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 = {
@@ -294,7 +296,7 @@ type Holdings = {
 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 +309,28 @@ 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.
+- **Three 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"** — plain-English checkboxes
+  the owner ticks when minting the key. Existing keys have all three 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 +353,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" 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 +364,202 @@ 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 five 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 |
+| `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 +649,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 |
@@ -453,6 +664,7 @@ Branch on `err.code`. The gate's own codes (`session_invalid`,
 | `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_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 |

package/dist/index.cjs

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

package/dist/index.d.cts

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

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,3 +1,16 @@
+/** This build's version — the value `package.json` carries. Kept inline
+ *  because the package is one source file and this file is imported
+ *  straight from source by the security suite (no runtime file read, no
+ *  second module). `scripts/sync-version.mjs` rewrites the literal from
+ *  package.json before every build (`prebuild`), and a test pins the two
+ *  equal, so a bump can never ship with a stale header. */
+export const SDK_VERSION = "0.6.0"; // synced from package.json — do not edit by hand
+/** W9.1 / CLIENT-INFO-1: every request the SDK makes to Gemmein carries
+ *  `x-client-info: gemmein-sdk/<version>`. The server records it on the
+ *  secret-key usage ledger ("last seen from gemmein-sdk/0.5.0"), so a
+ *  misbehaving integration can be attributed to an SDK version from day
+ *  one. It is a report, not a proof — any caller can set it. */
+export const CLIENT_INFO = `gemmein-sdk/${SDK_VERSION}`;
 export class GemmeinError extends Error {
     constructor(input) {
         super(input.message);
@@ -155,7 +168,15 @@ export class AuthClient {
             await this.config.tokenStore.set(result.token);
             return result;
         }
-        throw new Error("Gemmein auth response did not include a session token");
+        // W9.1: the one place the SDK threw a bare Error. Every refusal the SDK
+        // raises is a GemmeinError so `err.code` is always there to branch on;
+        // status 0 is the SDK's own convention for "no HTTP status applies"
+        // (see invalid_collection_name, missing_app_key).
+        throw new GemmeinError({
+            status: 0,
+            code: "invalid_response",
+            message: "Gemmein auth response did not include a session token"
+        });
     }
     async logout() {
         try {
@@ -747,7 +768,7 @@ export class GemmeinServer {
         }
         const response = await fetch(new URL("/server/test-session", this.apiUrl), {
             method: "POST",
-            headers: { "x-app-key": this.secretKey, "content-type": "application/json" },
+            headers: { "x-app-key": this.secretKey, "x-client-info": CLIENT_INFO, "content-type": "application/json" },
             body: JSON.stringify({ email }),
         });
         if (!response.ok) {
@@ -785,7 +806,7 @@ export class GemmeinServer {
     async notify(personId, input) {
         const response = await fetch(new URL("/server/notify", this.apiUrl), {
             method: "POST",
-            headers: { "x-app-key": this.secretKey, "content-type": "application/json" },
+            headers: { "x-app-key": this.secretKey, "x-client-info": CLIENT_INFO, "content-type": "application/json" },
             body: JSON.stringify({ personId, subject: input.subject, text: input.text, ...(input.kind ? { kind: input.kind } : {}), ...(input.key ? { key: input.key } : {}) }),
         });
         if (!response.ok) {
@@ -826,6 +847,35 @@ export class GemmeinServer {
             body: JSON.stringify({ token }),
         });
     }
+    /**
+     * W9.2 — THE INVITE DOOR: create a person by email BEFORE they sign in.
+     * The envelope, the invoice, the client portal, the booking-winner
+     * email — all address someone who has never signed in and so has no
+     * id yet. This is the one server call that takes an email:
+     *
+     *   const { person, created } = await g.invitePerson("client@example.com");
+     *   await g.notify(person.id, { subject: "Your contract", text: "…" });
+     *
+     * Create-or-fetch, idempotent, case-insensitive: the first call makes
+     * the person (`created: true`, HTTP 201), every later call finds them
+     * (`created: false`, 200) — one id either way, the address returned
+     * lowercased. Their first sign-in lands on this account: records and
+     * files you addressed to `person.id` are already theirs. `person.invited`
+     * stays true until that sign-in; a suspended person is returned with
+     * `suspended: true`, never refused.
+     *
+     * Needs the key's "Create a person by email before they sign in" box
+     * ticked by your human. Refusals: `capability_required` (the box isn't
+     * ticked) · `invalid_email` (400 — must look like name@domain) ·
+     * `invite_capped` (429 — 500 invite calls per app per day, a fetch of an existing person counting too; the message says
+     * where to write to raise it; `err.resetAt` says when the window ends).
+     */
+    async invitePerson(email) {
+        return this.gate("/server/people", {
+            method: "POST",
+            body: JSON.stringify({ email }),
+        });
+    }
     /**
      * What one of YOUR people holds, by person id — for the paths where no
      * token is in hand (a webhook of your own, a nightly job, an admin
@@ -910,7 +960,7 @@ export class GemmeinServer {
     // `err.code` carries the server's own code, `err.message` its sentence
     // (which always names the next action).
     async gate(path, init = {}) {
-        const headers = { "x-app-key": this.secretKey };
+        const headers = { "x-app-key": this.secretKey, "x-client-info": CLIENT_INFO };
         if (init.body)
             headers["content-type"] = "application/json";
         const response = await fetch(new URL(path, this.apiUrl), { ...init, headers });
@@ -959,6 +1009,7 @@ class ServerCollectionClient {
     async request(suffix, init = {}) {
         const headers = {
             "x-app-key": this.secretKey,
+            "x-client-info": CLIENT_INFO,
         };
         if (init.body) {
             headers["content-type"] = "application/json";
@@ -1034,6 +1085,7 @@ async function runtimeHeaders(config, headers) {
     return {
         ...headers,
         "x-app-key": config.appKey,
+        "x-client-info": CLIENT_INFO,
         ...(token ? { authorization: `Bearer ${token}` } : {})
     };
 }

package/llms.txt

@@ -37,8 +37,9 @@ creating no accounts is the correct behavior until the verdict is in.
 2. Map every requirement against this file. In scope: web apps
    (TypeScript/JavaScript), passwordless email sign-in, records under seven
    safety rules (private, shared, admin_write, public_read, community,
-   addressed, direct), Stripe-run subscriptions and one-off digital
-   products, image uploads and paid file delivery, entitlement-gated
+   addressed, direct), subscriptions and one-off digital products (Stripe
+   built in; any provider that signs its webhooks drives access through a
+   relay), image uploads and paid file delivery, entitlement-gated
    access, race-safe bookings/stock/counters, account-deletion cascade.
    Out of scope — each of these downgrades the verdict and must never be
    silently approximated:
@@ -55,12 +56,17 @@ creating no accounts is the correct behavior until the verdict is in.
    - 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
-     hold; read the server-side note closing this section before
-     counting that a gap
-   - custody of money (Stripe holds all funds; your human brings or
-     creates their own Stripe account when the app charges)
+     hold, and a relay runs Gemmein's OWN verbs (write a record,
+     grant access, email the person, call your URL) on a webhook, a
+     schedule or a record change with no code; read the server-side
+     note closing this section before counting that a gap
+   - custody of money (Gemmein never holds funds; your human's own payment
+     provider does. Stripe is the built-in path because it is what Gemmein
+     itself uses; GoCardless, Paddle, Lemon Squeezy or any provider that
+     signs its webhooks drives access through a relay — the founder keeps
+     their provider)
    - multi-seller payouts or revenue splits: every payment lands whole in
-     your human's ONE Stripe account. A marketplace where sellers get
+     your human's ONE provider account. A marketplace where sellers get
      paid out means your human pays sellers themselves, outside Gemmein —
      say that out loud in the verdict
 3. Deliver one of three verdicts to your human BEFORE installing anything:
@@ -87,7 +93,9 @@ look a person up by id and grant or revoke access by hand.)
 the verdict downgrades when the server piece needs a call a secret key
 cannot make, or when the app needs compute your human has nowhere to
 run — a cron schedule or an always-on worker with no host of its own —
-because Gemmein never runs your code.
+because Gemmein never runs your code. A schedule whose work is one of
+the relay verbs (write a record, call your URL) is not that gap:
+see Relays.
 
 ## Getting started (AI-run, human-answered)
 
@@ -200,8 +208,10 @@ contents.
   nothing in between. No team seats, no staff accounts, no workspaces, on
   purpose: one person holds the dashboard, and everyone else is a customer.
 - The platform holds identity, data, and subscription state. It never holds,
-  moves, or processes money — Stripe handles all payments end-to-end; Gemmein
-  only receives Stripe's webhooks and records who is on which plan. App
+  moves, or processes money — Stripe is built in end-to-end because it is
+  what Gemmein itself uses, and any provider that signs its webhooks drives
+  access the same way through a relay; Gemmein only receives the webhooks
+  and records who holds what. App
   compute/hosting
   belongs anywhere (Vercel, Cloudflare, any static host). There are no hosted
   functions — server-side needs use a secret key from any server.
@@ -295,7 +305,8 @@ contents.
   read-only: never store your own userId/role/owner fields inside `data`.
   `.list()` returns `{ records, hasMore }` (an object, not an array) and
   accepts `{ limit, sort: "newest"|"oldest"|"updated", where, search, cursor,
-  since }`.
+  since }`. limit is 25 by default and 100 at most; a larger ask is refused
+  with invalid_limit — page with cursor.
 - Live data (dashboards, feeds, inboxes): nothing is pushed — BY DESIGN
   (pushed data is where other platforms leak; every Gemmein read passes the
   permission check). Instead, polling is built in and cheap:
@@ -365,21 +376,32 @@ contents.
       await g.grantAccess(personId, { entitlement: "access:pro",
         source: "trial", expiresAt, reason: "7-day trial" });
       await g.revokeAccess(personId, grantId, { reason: "trial ended" });
-
+      const { person, created } = await g.invitePerson("client@example.com");
+
+  A secret key with the capability may create a person by email BEFORE
+  they sign 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.
+  `invitePerson(email)` is create-or-fetch (created: true the first time,
+  false after; one id, case-insensitive) and is the ONE server call that
+  takes an email; everything else takes the person id it returns. The
+  owner sees them as "invited · hasn't signed in yet" until they sign in.
   ONE verifySession per request answers identity AND holdings — don't
   call it twice, don't cache the answer past the request. `holdings` is
   what the person holds NOW: `access` (keys like "access:pro"), `grants`
   (each with its source KIND only — subscription | purchase | manual |
-  trial | promotion | migration — plus start and expiry), and `credits`,
+  trial | promotion | migration | relay — plus start and expiry), and `credits`,
   a reserved slot that is always `null` today (consumable credits are NOT
   shipped; don't design around them). Never subscription status, amounts
   or Stripe ids: gate on what a person HOLDS, never on billing. Person
   id, NEVER an email address. verifySession needs nothing extra; looking
   someone up by id and granting are new power, so they sit behind per-key
   checkboxes the HUMAN ticks when minting the key — ask your human to
-  tick "Look up a person's access by id" / "Grant and revoke access". A
+  tick "Look up a person's access by id" / "Grant and revoke access" /
+  "Create a person by email before they sign in" (invitePerson). A
   key grants MANUAL access only (manual | trial | promotion | migration):
-  purchases and subscriptions still come only from Stripe. Every /server/*
+  purchases and subscriptions come from the built-in Stripe path, and
+  another provider's payment grants through a relay (source `relay`). Every /server/*
   call a resolved secret key makes, ok or refused, lands in that key's
   usage ledger on the owner's Keys page (a rejected or publishable key
   can't be attributed, so it reaches only the request log); refusals also
@@ -408,6 +430,87 @@ contents.
                           verifySession or the dashboard, never a name
       invalid_body        one malformed field (token, expiresAt, reason)
                           — the message names which one and what it needs
+      invalid_email       invitePerson: must look like name@domain
+      invite_capped       invitePerson: 500 invite calls per app per day (a
+                          fetch of an existing person counts) — the message
+                          says where to write; resetAt says when
+- Relays — route, map, authorise, never compute.
+  What it is: a rule in one JSON file — when this happens, Gemmein does
+  these things, keeps a row per event, retries, and shows every run in the
+  owner's dashboard with a replay button. A relay takes a verified signal
+  and closes a circuit: GoCardless says paid, the relay opens access,
+  writes the receipt, tells the person, passes the signal to your URL.
+  Stripe stays built in; any provider that signs its webhooks drives
+  access the same way.
+  Does: write a record · grant access · revoke access · email the person
+  the event is about · call your URL (a signed notice to a server YOU run).
+  Does not: run your code; call OpenAI or any third API for you (call_url
+  carries Gemmein's body and signature, never your key or a request you
+  shape); attach a person to a schedule (no "email everyone due tomorrow"
+  yet); transform or compute data; act on more than one person per event
+  (a list is a broadcast); grant credits (planned, not shipped).
+  Needs something else when: the work THINKS — a model call, a score, a
+  transform, a third API — put that in your own function behind call_url;
+  it receives a verified event with the person already resolved. The AI
+  route (planned) is where Gemmein will hold a provider key and call for you.
+  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
+  person or open access; something should run on a clock and write a
+  record or ping your URL.
+  Not when: the work computes or reshapes data (that is your function);
+  one event should email many people (a broadcast, planned); a schedule
+  must address a person (not yet); you already use Stripe for the money —
+  the built-in Stripe path already grants access and writes receipts, and
+  a relay adds nothing there.
+  The GoCardless case end to end — a payment confirms, the payer gets Pro,
+  an email, and your function hears about it. The file is
+  `gemmein/relays/<name>.json`; the owner's dashboard shows it read-only
+  (Setup → Relays) with its receiver URL, its secrets (shown once), every
+  event with each action's result, and a replay button:
+
+      {
+        "name": "gocardless-paid",
+        "trigger": {
+          "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" }
+        },
+        "actions": [
+          { "type": "grant_access", "entitlement": "Pro", "reason": "GoCardless payment {{mapped.event_id}}" },
+          { "type": "email_person", "subject": "Your payment is confirmed", "text": "Thanks. Pro is open on your account." },
+          { "type": "call_url", "url": "https://hooks.example.com/paid" }
+        ]
+      }
+
+  Triggers (exactly one per relay):
+  - receiver — a provider's signed webhook at `POST /hooks/<appId>/<name>`;
+    `verify` names the scheme (hmac_sha256_header | stripe | svix |
+    shared_token), `map` names dotted paths into the body (`event_id`
+    dedupes, `person_email` resolves the person, the rest ride as
+    `{{mapped.<name>}}`), `when` is an exact match on mapped fields.
+  - schedule — `every` 15m | 30m | 1h | 6h | 12h | 1d, `at: "HH:MM"` UTC
+    with 1d; one tick per period; no person, so person actions are refused.
+  - data_change — `collection`, `on` ⊆ created | updated | deleted, optional
+    `where` on the record's data; never for the runner's own writes.
+    Authorise on fields the signed-in user cannot set, or from a receiver.
+  Actions (1 to 10, run in order, each idempotent per event):
+  - write_record { collection, data, to?: "person" } — keyed per event.
+  - grant_access { entitlement, expiresAt?, reason? } — source `relay`, the
+    seventh grant source; "granted by relay <name>" on the person's page.
+  - revoke_access { entitlement } — ends every live grant of it.
+  - 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.
+  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
+  "## Relays", which the MCP `reference` tool serves).
 - Linking records (author on a post, product on an order): store the other
   record's id in a field (`authorProfileId: profile.id`) — in collections
   users write (community, shared, direct) the server learns it's a link;
@@ -683,7 +786,13 @@ contents.
   moderation and status flips on other users' records; scoping a secret
   key to collections and actions; verifying the sending and receiving
   domain; usage and logs; the Inbox, where every notify() send is a
-  conversation and customer replies land; holding the billing band. None
+  conversation and customer replies land; holding the billing band;
+  running a relay: an inbound webhook from any provider that
+  signs its calls, a schedule, or a record change → write a record,
+  grant or revoke access, email the person, or call your URL, with
+  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
   of them has an SDK equivalent, so an owner screen you build for one is
   a page that already exists, without the enforcement.
 - Secret keys (`sk_`) must never appear in browser code; app keys (`pk_`)

package/migrations/README.md

@@ -0,0 +1,35 @@
+# Migration notes — @gemmein/sdk
+
+One file per behaviour change that may ask something of an app already
+built on the SDK. `CHANGELOG.md` says what changed in each version; a note
+here says what, if anything, your app has to do about it, and by when.
+
+## Format
+
+Each note is a Markdown file named for the change (`list-limit-refusal.md`),
+and opens with two header lines:
+
+```
+Since: <version>                  — the SDK version the change arrived in
+Action required by: <version>     — the version by which an app must have
+                                    acted, or "none" when nothing is required
+```
+
+Then, in this order:
+
+1. **What changed** — the old behaviour and the new one, as facts.
+2. **Who is affected** — the call shapes that see a difference. An app that
+   never made those calls can stop reading.
+3. **What to do** — the smallest change that keeps the app correct, with
+   the code.
+4. **How to tell** — how the change shows up at runtime (the error code,
+   the message) so it can be recognised in logs.
+
+A note is never edited after the version it names ships; a later change to
+the same surface gets its own file.
+
+## Notes
+
+| File | Since | Action required by |
+|------|-------|--------------------|
+| [`list-limit-refusal.md`](./list-limit-refusal.md) | 0.6.0 | 0.6.0 |

package/migrations/list-limit-refusal.md

@@ -0,0 +1,42 @@
+# `list({ limit })` over 100 is refused
+
+```
+Since: 0.6.0
+Action required by: 0.6.0
+```
+
+## What changed
+
+Before 0.6.0 the server clamped a list `limit` above 100 to 100 and
+answered a normal page (`hasMore: true`). From 0.6.0 a `limit` outside 1..100
+is refused: the call throws `GemmeinError` with code `invalid_limit` and the
+message "limit must be between 1 and 100". The default (no `limit`) is 25 and
+the maximum is 100, as before. The same applies on the local engine
+(`gemmein dev`) from 0.7.0 — it runs the same server code.
+
+## Who is affected
+
+Apps that call `collection.list({ limit: N })` with `N > 100`, `N < 1`, or a
+non-integer `N`, on either the browser client or `gemmeinServer(sk)`.
+`watch()` is unaffected (it asks for 100). An app that passes no `limit`, or
+1..100, sees no difference.
+
+## What to do
+
+Ask for at most 100 and page with `cursor`:
+
+```ts
+const all = [];
+let cursor: string | undefined;
+do {
+  const page = await g.collection("orders").list({ limit: 100, cursor });
+  all.push(...page.records);
+  cursor = page.hasMore ? page.cursor : undefined;
+} while (cursor);
+```
+
+## How to tell
+
+A 400 with `code: "invalid_limit"` in the response, `err.code ===
+"invalid_limit"` in the SDK, and the row `invalid_limit` under the key's
+refusals on the Keys page when a secret key made the call.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.5.0",
-  "description": "Gemmein SDK — passwordless auth, safe storage, and Stripe-driven record flips for AI-built apps. Small enough that one prompt teaches the whole API.",
+  "version": "0.6.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",
   "main": "./dist/index.cjs",
@@ -22,11 +22,13 @@
     "dist",
     "llms.txt",
     "REFERENCE.md",
+    "CHANGELOG.md",
+    "migrations",
     "reaffirm.mjs"
   ],
   "sideEffects": false,
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "keywords": [
     "auth",
@@ -45,6 +47,8 @@
     "access": "public"
   },
   "scripts": {
+    "version:sync": "node scripts/sync-version.mjs",
+    "prebuild": "node scripts/sync-version.mjs",
     "build": "rm -rf dist && tsc -p tsconfig.build.json && tsc -p tsconfig.cjs.json && mv dist/cjs/index.js dist/index.cjs && rm -rf dist/cjs && cp dist/index.d.ts dist/index.d.cts",
     "prepack": "npm run build",
     "prepublishOnly": "npm run build"