@gemmein/sdk 0.4.7 → 0.6.0

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) {
@@ -799,6 +820,155 @@ export class GemmeinServer {
         }
         return response.json();
     }
+    /**
+     * THE GATE — your compute, our answer. Gemmein runs no code of yours;
+     * your own function runs anywhere and asks the only three questions it
+     * has: who is this person, what do they hold, change what they hold.
+     *
+     *   const { person, holdings } = await g.verifySession(token);
+     *   if (!holdings.access.includes("access:pro")) return deny();
+     *
+     * ONE call per request answers identity AND holdings — don't call it
+     * twice, and don't cache the answer past the request. Verify needs no
+     * capability on the key (the caller already holds the person's token)
+     * and never touches the session: no extension, no last-seen.
+     *
+     * Refusals (`err.code`): `session_invalid` (no session matches this
+     * token — the person signs in again; never reuse tokens across
+     * people) · `session_expired` · `session_revoked` (a newer sign-in,
+     * a sign-out, or the owner) — all three send the person back to
+     * sign-in · `person_suspended` (the owner suspended them; access is
+     * off until the owner reactivates them in the dashboard) ·
+     * `invalid_body` (token missing, not a string, or over 512 chars).
+     */
+    async verifySession(token) {
+        return this.gate("/server/verify-session", {
+            method: "POST",
+            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
+     * screen you built). A person id, NEVER an email address: ids come
+     * from `verifySession` or the dashboard.
+     *
+     * A suspended person is RETURNED, with `suspended: true`, alongside
+     * their holdings — your function may need to say so. The gate itself
+     * (`verifySession`) refuses them.
+     *
+     * Refusals: `capability_required` — this key can't look up people by
+     * id; ask your human to mint a key with "Look up a person's access by
+     * id" ticked, or use `verifySession` with the person's own token ·
+     * `person_not_found` (404 — no person with this id in this app and
+     * environment; existence is never leaked).
+     */
+    async holdings(personId) {
+        return this.gate(`/server/people/${encodeURIComponent(personId)}/holdings`);
+    }
+    /**
+     * Give a person access by hand — a trial, a promotion, an apology, a
+     * migration from your old system:
+     *
+     *   await g.grantAccess(personId, {
+     *     entitlement: "access:pro",     // or the plan's NAME, e.g. "Pro"
+     *     source: "trial",
+     *     expiresAt: "2026-10-01T00:00:00.000Z",
+     *     reason: "7-day trial from the onboarding flow",
+     *   });
+     *
+     * MANUAL sources only. Purchases and subscriptions come only from
+     * Stripe — a key cannot mint paid access, by design. `reason` is up to
+     * 200 characters, is never edited afterwards, and is what the owner
+     * reads in their logs; write it for them.
+     *
+     * `sourceId` is minted per call, so two calls make TWO grants (each
+     * with its own one reason) — call it once, and keep your own retry
+     * key if the caller can retry.
+     *
+     * Returns the new grant and the holdings AFTER it; the owner's audit
+     * row carries before→after and the key's name.
+     *
+     * Refusals: `capability_required` — this key can't grant access; ask
+     * your human to mint a key with "Grant and revoke access" ticked ·
+     * `invalid_source` (purchase/subscription refused) ·
+     * `invalid_entitlement` / `unknown_plan` (no plan or product by that
+     * name — the owner adds it on the Payments page) · `person_not_found`.
+     */
+    async grantAccess(personId, input) {
+        return this.gate(`/server/people/${encodeURIComponent(personId)}/grants`, {
+            method: "POST",
+            body: JSON.stringify({
+                entitlement: input.entitlement,
+                ...(input.source ? { source: input.source } : {}),
+                ...(input.expiresAt ? { expiresAt: input.expiresAt } : {}),
+                ...(input.reason ? { reason: input.reason } : {}),
+            }),
+        });
+    }
+    /**
+     * End one grant — the reversibility law in one call:
+     *
+     *   await g.revokeAccess(personId, grant.id, { reason: "trial ended" });
+     *
+     * A grant ends ONCE: `revokedAt` is set and never edited, so a second
+     * call is `409 already_revoked`, not a silent no-op. A key MAY end a
+     * grant that a payment created (the same as the owner's "end this
+     * access" button) — the payment itself is untouched, and the audit row
+     * says so.
+     *
+     * Returns the revoked grant and the holdings after it.
+     *
+     * Refusals: `capability_required` (same ticked box as granting) ·
+     * `grant_not_found` (404 — not this person's grant, in this app and
+     * environment; existence is never leaked) · `already_revoked` (409).
+     */
+    async revokeAccess(personId, grantId, input = {}) {
+        return this.gate(`/server/people/${encodeURIComponent(personId)}/grants/${encodeURIComponent(grantId)}/revoke`, { method: "POST", body: JSON.stringify({ ...(input.reason ? { reason: input.reason } : {}) }) });
+    }
+    // One request path for the four gate calls, so every refusal reaches
+    // the caller through the SAME typed error the rest of the SDK throws —
+    // `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, "x-client-info": CLIENT_INFO };
+        if (init.body)
+            headers["content-type"] = "application/json";
+        const response = await fetch(new URL(path, this.apiUrl), { ...init, headers });
+        if (!response.ok) {
+            throw new GemmeinError({ status: response.status, ...(await readErrorBody(response)) });
+        }
+        return response.json();
+    }
 }
 class ServerCollectionClient {
     constructor(apiUrl, secretKey, name) {
@@ -839,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";
@@ -914,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:
@@ -49,13 +50,23 @@ creating no accounts is the correct behavior until the verdict is in.
      nothing in between — so an app whose CORE loop needs teams, roles
      or seats DOESN'T FIT
    - carts, quantities, physical goods, shipping, inventory
-   - credits, usage metering, seats (paid access is yes-or-no)
-   - hosted functions or cron: Gemmein runs no code of yours — but 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)
+   - credits or usage metering TODAY (paid access is yes-or-no; consumable
+     credits are planned, not shipped — don't design around them yet, and
+     never sell a "credit pack" until this file says the ledger exists)
+   - 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, 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:
@@ -74,13 +85,17 @@ code on your human's OWN host — Vercel, a VPS, anywhere — holding a
 secret key already reads and updates collections and sends event emails
 with `notify()`. (A secret key sees PAST the safety rules — every
 customer's records — which is why it never touches a browser. It cannot
-create or delete records, verify a session, or read one customer's
-plan: those are the signed-in customer's own calls, or the dashboard's.)
+create or delete records: those are the signed-in customer's own calls,
+or the dashboard's. It CAN verify a session token and read what that
+person holds — the gate — and, when your human ticks the box on the key,
+look a person up by id and grant or revoke access by hand.)
 "This app needs a server-side piece" is therefore not a gap by itself:
 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)
 
@@ -193,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.
@@ -288,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:
@@ -345,6 +363,154 @@ contents.
   cap (a security notice never loses to five order emails); misusing it
   for campaigns shows in your own audit trail. In `gemmein dev` the send
   prints in the terminal (NOTIFY · …) instead of mailing.
+- Your compute, our gate: when code of yours must run elsewhere (a model
+  call, a PDF render, a nightly job), Gemmein hosts none of it — your own
+  function runs anywhere and asks Gemmein its only three questions: who is
+  this person, what do they hold, change what they hold.
+
+      import { gemmeinServer } from "@gemmein/sdk";
+      const g = gemmeinServer(process.env.GEMMEIN_SECRET_KEY);
+      const { person, holdings } = await g.verifySession(token);
+      if (!holdings.access.includes("access:pro")) return deny();
+      await g.holdings(personId);                    // no token in hand
+      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 | 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" /
+  "Create a person by email before they sign in" (invitePerson). A
+  key grants MANUAL access only (manual | trial | promotion | migration):
+  purchases and subscriptions come from the built-in Stripe path, and
+  another provider's payment grants through a relay (source `relay`). Every /server/*
+  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
+  write one activity row per key, route and code each hour. In `gemmein
+  dev` the local key already holds both capabilities, and the usage read
+  is cloud-only — the local runtime never mounts the console. The
+  refusals, and what to do:
+      session_invalid     no session matches this token — the person must
+                          sign in again; never reuse tokens across people
+      session_expired     the session ended — back to sign-in
+      session_revoked     newer sign-in, sign-out, or the owner — sign-in
+      person_suspended    the owner suspended them — access is off until
+                          the owner reactivates them in the dashboard
+      person_not_found    no person with this id in this app and env —
+                          ids come from verifySession or the dashboard
+      capability_required the box isn't ticked on this key — ask your
+                          human to mint one with it ticked
+      unknown_plan        no plan or product by that name — the owner
+                          adds it on the Payments page
+      grant_not_found     not this person's grant here — re-read holdings
+      already_revoked     a grant ends once — it is already ended
+      invalid_source      purchase/subscription asked for by hand — use
+                          manual | trial | promotion | migration instead
+      invalid_id          a prototype name (__proto__, constructor) was
+                          sent as a person or grant id — ids come from
+                          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;
@@ -509,7 +675,40 @@ contents.
   screen and send them to checkout; retry only after they hold one. Proof surfaces: `await g.purchases.mine()`
   (everything they paid for, refunds applied, with the `grants` each purchase
   carries) and `await g.subscriptions.mine()`.
-  NO credits, NO usage limits, NO seats — access is yes-or-no by design.
+  NO credits or usage limits YET — access is yes-or-no today. Consumable
+  credits (buy a pack, spend atomically, a zero floor) are planned, not
+  shipped: until this file teaches them, a "100 credit pack" is NOT a
+  pattern (the webhook can only SET a number, so a second pack erases the
+  first). NO seats, by design — not coming.
+- Two FAMILIES of grant, and the line between them is law. Every grant is
+  one key + one reason + a start + maybe an end, never edited (an extension
+  is a NEW grant). PURCHASE-TIED (`subscription`, `purchase`): written only
+  by Stripe's signed webhook when money arrives — never by the owner's
+  hand, never by your app; a subscription grant ends on cancellation or
+  lapse, a purchase grant on a FULL refund (partial leaves it); the only
+  grants that count as revenue. Revoking one by hand stops the access and
+  refunds nothing. BY-HAND (`manual`, `trial`, `promotion`, plus
+  `migration` for customers imported from elsewhere): the owner writes them
+  from a customer's page — plan or product BY NAME, optional end date, a
+  reason — and they end on that date or when revoked; never revenue; a
+  refund never touches them. Effective access is the union of both
+  families. WHEN A REFUND MEETS ACCESS, THE OWNER DECIDES: the platform
+  revokes only on events that plainly mean it (subscription cancelled or
+  lapsed; one-off purchase refunded IN FULL). A partial refund leaves
+  access; a refund on a subscription invoice touches no access at all
+  (grants are revoked by purchase reference, subscriptions by customer).
+  A cancel-at-period-end keeps access until the period ends. If the owner
+  wants access gone NOW, they cancel the subscription immediately in
+  Stripe or revoke by hand on the customer's page — both audited; every
+  refund the webhook chose not to act on is written to the activity view.
+  Tell your human this when they ask "I refunded them, why can they still
+  get in" — never write refund logic in the app. Your app sees purchases (`g.purchases.mine()`, each with its
+  `grants`) and the subscription (`g.subscriptions.mine()`) — by-hand
+  grants are NOT listed to the app; a gated read simply succeeds. So never
+  rebuild the paywall client-side from what you can list: let the server
+  refuse and show the upgrade prompt on `entitlement_required`. "Give X a
+  free month" is a trial grant on their customer page, never code — ask
+  your human.
 - Selling THINGS (one-off purchases — a beat, an ebook, a course; DIGITAL
   access only — physical goods, shipping, inventory and carts are out of
   scope, said out loud): plans are for subscriptions; products are for
@@ -587,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.4.7",
-  "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"