@gemmein/sdk 0.0.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gemmein Limited (Company No. 17339623, England and Wales)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,285 @@
 # @gemmein/sdk
 
-The official Gemmein SDK — passwordless auth and safe storage for AI-built apps, small enough to be taught by one prompt.
+The secure backend for AI-built apps: passwordless login, safe data storage, and Stripe-driven payment flips — with the unsafe paths removed by design. No SQL, no security-rules language, no server to configure.
 
-Launching soon. This version reserves the package name.
+## Step 0 — get your app key
 
-- Product: https://gemmein.com
-- Docs: https://docs.gemmein.com
+Every call needs an app key (`pk_...`). Get one in 30 seconds: sign in at **[app.gemmein.com](https://app.gemmein.com)** with an email code (free, no card), and copy the key from the Setup page. The Setup page also gives you a ready-made prompt that teaches this whole SDK to your AI tool.
+
+## Install
+
+```
+npm i @gemmein/sdk
+```
+
+No bundler? The SDK is dependency-free pure ESM — copy `dist/index.js` from the package next to your HTML and `import { gemmein } from "./index.js"` in a `<script type="module">`. Works on any static host.
+
+## Quick start
+
+```js
+import { gemmein } from "@gemmein/sdk"
+
+const g = gemmein("pk_test_...")
+
+// Login — email code, no passwords
+await g.auth.sendEmailCode("user@example.com")
+await g.auth.verifyEmailCode({ email: "user@example.com", code: "12345678" })
+
+// Store data — rules enforced server-side
+await g.collection("tasks").create({ title: "Buy milk", done: false })
+const { records } = await g.collection("tasks").list()
+```
+
+The client has two layers: **your collections** (`g.collection("tasks")` — your app's own data model) and the **business primitives Gemmein runs for you** (`g.auth`, `g.subscriptions`, `g.payments`, `g.account` — self-service surfaces for the signed-in user; managing *other* people's users, subscriptions, and records happens in the owner's dashboard, on purpose).
+
+Sessions persist across page reloads automatically (localStorage in browsers, memory elsewhere — override with `tokenStore` if you need custom persistence). One session per user: verifying a new code revokes that email's older sessions — a stale token throws `auth_expired` once, the SDK clears it, and a retry (or re-auth) recovers.
+
+## Auth
+
+```js
+await g.auth.sendEmailCode("user@example.com")   // sends an 8-digit code
+
+const session = await g.auth.verifyEmailCode({ email: "user@example.com", code: "12345678" })
+// { token, expiresAt, user: { id, email } } — token stored automatically
+
+const user = await g.auth.currentUser()
+// { authenticated: true, userId: "usr_...", email: "user@example.com" }
+
+await g.auth.logout()
+```
+
+### Deleting an account
+
+```js
+await g.account.delete()
+```
+
+Self-service erasure — the "delete my account" screen. Every app it **applies** to needs one (GDPR right to erasure; Apple 5.1.1(v) for any app with account creation). Server-side it's the full cascade: sessions revoked, the user's records and files deleted, their subscription row removed. Irreversible — put a real confirm in front of it.
+
+## Storage
+
+Collections are created by the app owner in the dashboard (app.gemmein.com → data → "+ New collection") — the SDK can't create them. A 404 `unknown_collection` means it doesn't exist yet: ask the app owner to add it (one click) and pick its rule from the table below.
+
+```js
+const tasks = g.collection("tasks")
+
+const task = await tasks.create({ title: "Buy milk", done: false })
+
+// Records come back WRAPPED — your fields live under .data:
+//   { id, data: { title, done }, createdAt, updatedAt }
+// Read task.data.title, NOT task.title. This trips up AI-generated code
+// more than anything else — if your UI shows blanks, this is why.
+console.log(task.id, task.data.title)
+
+// list() returns { records, cursor, hasMore } — records is the array
+const { records } = await tasks.list()
+records.forEach(r => console.log(r.data.title))
+const recent = await tasks.list({ limit: 10, sort: "newest" })
+const filtered = await tasks.list({ where: { done: false } })   // exact-match filters
+const one = await tasks.get("rec_abc123")
+await tasks.update("rec_abc123", { done: true })
+await tasks.delete("rec_abc123")
+
+// Images/files: presigned upload, returns a CDN URL to store in a record
+const file = await tasks.upload(imageBlob, { name: "avatar.png" })
+// { id, url, contentType, sizeBytes }
+```
+
+### Collection rules
+
+Each collection has one rule, set in the dashboard. The server enforces it — your app never implements authorization:
+
+| Rule | Who can read | Who can write | Use case |
+|------|-------------|---------------|----------|
+| `private` | Owner only — plus the app owner/admin, who reads everything | Owner only | User's personal data (tasks, notes, settings) |
+| `shared` | All authenticated users | Each user: own records only | Feeds, communities, team boards |
+| `public_read` | Anyone (no login needed) | App owner only | Catalogs, menus, marketing pages, single-author blogs |
+| `community` | Anyone (no login needed) | Each signed-in user: own records only — plain text | Multi-author blogs, public boards, profiles |
+| `addressed` | Each user: only records addressed to them (owner sees all) | Owner only, naming a recipient | Notifications, invoices, order status |
+| `direct` | Author + the named recipient | Each signed-in user, naming a recipient | Messages, sharing, requests |
+| `admin_write` | All authenticated users | Admin/owner only | App settings, announcements |
+
+**Owner scoping is automatic.** For `private` collections each user only sees their own records; when the signed-in user is the app's owner or admin, reads return every user's records (build your admin screen with the same `list()` calls — no server needed). Don't gate admin UI on any visible `role` field — sessions always report `member`, even for the owner; elevation happens server-side per request, so render whatever `list()` returns. For `shared` collections everyone reads everything but update/delete only touch the caller's own records. Never filter by userId, never set `userId`/`owner`/`role` fields. The server derives them from the session and rejects reserved fields if you try to set them:
+
+`id`, `appId`, `app_id`, `environmentId`, `environment_id`, `userId`, `user_id`, `ownerId`, `ownerUserId`, `owner_user_id`, `tenantId`, `tenant_id`, `role`, `isAdmin`, `is_admin`, `createdAt`, `created_at`, `updatedAt`, `updated_at`, `deletedAt`, `deleted_at`
+
+**User content is data, not markup.** When one user's content renders in another user's session (`community`, `shared`), render it with text bindings — `textContent`, `{}` in React/Vue/Svelte — never `innerHTML`. `community` collections enforce this server-side: any string field containing HTML tags is refused with `400 html_not_allowed`. Store plain text, or markdown written without raw tags.
+
+### Sending to people — inboxes and messages
+
+`addressed` and `direct` records carry a recipient, named on the call you already make:
+
+```js
+// addressed (owner → user): the "Mark shipped" button in your admin view
+await updates.create({ text: "Your order shipped 🎉" }, { for: userId })
+
+// direct (user → user): DMs, sharing, requests
+await messages.create({ text: "hey!" }, { for: otherUserId })
+
+// The reader's side is just list() — the server returns only THEIR inbox:
+const { records } = await updates.list({ sort: "newest", limit: 20 })
+```
+
+The recipient is server-stamped (`record.audienceUserId`) — never a data field. User ids come from records' `ownerUserId` or the owner's admin lists. Rules of the road:
+
+- **Same message for everyone → `admin_write`** (one record all users read). **A specific thing for a specific person → `addressed`** (one record per recipient).
+- Inboxes are poll-or-refresh: `list()` on window focus plus a gentle ~60s interval — never a tight loop. Read-state ("seen") lives in the user's own private collection.
+- `direct` is messaging inside someone's app, and the app owner can read it (owner reads reach everything, under every rule) — never present it as private or encrypted chat.
+- Errors teach the fix: `invalid_audience` (recipient isn't a user of this app), `reply_only` (this collection only allows replying to people who wrote to you first — tell the user), `sends_disabled` (the owner turned sends off; addressed sends then happen in their dashboard).
+- Both rules store plain text like `community` — render other users' content as text, never `innerHTML`.
+
+### Contention — when users race for the same thing
+
+A permission model can't stop two people booking the same 3pm slot. Preconditions can, and each is just an argument on a call you already make. **A 409 `conflict` from any of them is the mechanism working, not an error to retry away** — catch it and tell the user the slot/stock/edit was taken.
+
+```js
+// Uniqueness: derive the key from the thing that must be unique.
+// Second writer → 409. Your own retry → your record back (existing: true).
+// Deleting the record frees the key.
+await bookings.create({ who: email }, { key: "slot:2026-07-15T15:00" })
+
+// Limited stock, N units anyone can buy: claim units with keyed creates —
+// on conflict try the next unit; all taken = sold out. Race-proof under
+// every safety rule (writes on OTHER users' records are never allowed).
+await orders.create({ item: 42 }, { key: "unit:item42:1" })  // then :2 … :N
+
+// Your own counters: the server does the math on current state.
+// Breaching the floor/ceiling → 409, record untouched.
+await products.update(id, { stock: { decrement: 1, floor: 0 } })
+
+// Shared editing: pass back the version you read — a stale save gets 409
+// instead of silently clobbering someone's edit. Re-read, reapply, retry.
+await pages.update(id, { body }, { ifVersion: page.version })
+```
+
+An object in a patch is treated as an atomic op ONLY when its keys are exactly `increment`|`decrement` (+ optional `floor`|`ceiling`), all numbers — anything else is stored as plain data. Keys are 1-120 chars of letters, numbers, and `: _ . @ / -`. Never find-then-create and never compute counters client-side: both race, and both fail only when real users collide.
+
+## Payments (Stripe) — you don't build the webhook
+
+Gemmein hosts your Stripe webhook and manages subscriptions for you: exactly one per customer (case-insensitive on email), created by the payment itself, downgraded to your default plan on cancellation, out-of-order Stripe events resolved to the newest. The app owner names the plans and pastes one Stripe signing secret in the dashboard's **Payments** page — nothing to seed. Your app has exactly two jobs:
+
+```js
+// 1. Send the buyer to checkout — one call, Gemmein does the rest. The app
+//    owner pasted each paid plan's Stripe Payment Link in their dashboard;
+//    g.subscriptions.checkout() picks the right one and wires the signed-in buyer in.
+//    Never build checkout URLs or sessions yourself: raw emails are
+//    silently dropped by Stripe's URL rules, and sessions need a secret
+//    key that must never ship client-side.
+await g.subscriptions.checkout("pro")   // redirects; omit the arg to buy the paid plan
+// GemmeinError codes worth handling: "authentication_required" (sign in
+// first), "plan_has_no_link" (owner hasn't pasted that plan's link yet)
+
+// 2. Gate paid features by reading the managed subscription:
+const sub = await g.subscriptions.mine()   // { plan, status } or null (never paid / payments off)
+if (sub?.plan === "pro") { /* unlock */ }
+```
+
+Do **not** write a webhook handler. Do **not** poll Stripe. Do **not** store plan/subscription state in your own collections — `g.subscriptions.mine()` is the single source of truth, and there is deliberately no client write path to it.
+
+Plan **limits** (note counts, feature caps, seat numbers) are your app's logic — Gemmein only tells you who is on which plan; the dashboard's plan names carry no quotas.
+
+### Selling things (one-off purchases)
+
+Plans are for subscriptions. To sell a **thing** — a poster, a beat, an ebook, a session — the owner adds **products** (name + Stripe Payment Link) on the same Payments page, plus a **receipts** collection (rule `addressed`). Then:
+
+```js
+// One product covering many items (license tiers over a catalog)? Name the
+// item — it's display text on the receipt, the PRICE always comes from the
+// product's Payment Link:
+await g.payments.buy("premium license", { item: "beat_37" })   // redirects
+
+// Fulfilment: the completed payment writes a receipt record ADDRESSED to
+// the buyer — only they (and the owner) can read it. Gate the download on
+// the receipt, never on the redirect coming back (redirects can be faked;
+// receipts can't — they come from Stripe's signed webhook):
+const { records } = await g.collection("receipts").list()
+const paid = records.find(r => r.data.product === "premium license" && r.data.status === "paid")
+if (paid) { /* unlock — paid.data.deliveryUrl holds the download when the owner set one */ }
+```
+
+Receipts carry `{ product, item?, status, amountTotal, currency, paidAt, deliveryUrl?, paymentRef }` in `.data` — `amountTotal` is minor units exactly as Stripe reported, and `paymentRef` is the Stripe payment id the refund flip matches on (read-only; you rarely need it). The owner fulfils orders by editing the receipt from their dashboard (`status: "shipped"`) — your app just reads it. Refunds happen in the owner's Stripe dashboard; if they forward `charge.refunded`, the receipt's status flips to `"refunded"`. A receipt is **app-owned** — its top-level `ownerUserId` is `null` (the webhook wrote it, not a user); it's the `audienceUserId` that scopes it to the buyer.
+
+**No carts, no quantities** — one product per checkout, by design. A "cart" is N checkouts, or one bundled product the owner prices as a bundle. Don't build a cart UI that promises otherwise.
+
+### Drafts on public collections
+
+On `public_read` and `community` collections, `{ published: false }` saves a **draft** the public can't see — server-enforced, the author still sees their own, the owner sees all:
+
+```js
+const post = await notes.create({ title: "wip" }, { published: false })  // hidden
+await notes.update(post.id, {}, { published: true })                     // now live
+```
+
+Read the current state back as a **top-level** field — `record.published` (a boolean), NOT `record.data.published` (same place as `id` and `updatedAt`, not inside your fields). Non-authors only ever receive published records, so you'll only ever see `false` on your own drafts — or on everything, as the owner. That's how you render an "unreleased" badge in an owner-only admin list.
+
+Never fake drafts with a `status` field + client-side filtering on a public collection — the data still reaches every reader's network tab. `published` is an option, not a data field; the server rejects it inside `data`.
+
+## Server-side (API routes, cron jobs)
+
+For trusted server code, use `gemmeinServer` with a scoped secret key (`sk_...`) — created in the dashboard, scoped per collection:
+
+```js
+import { gemmeinServer } from "@gemmein/sdk"
+
+const server = gemmeinServer(process.env.GEMMEIN_SECRET_KEY)
+
+const tasks = await server.collection("tasks").list()
+await server.collection("tasks").update("rec_abc123", { done: true })
+```
+
+Secret keys can only `get`/`list`/`update` the collections you scoped them to — no creates, no deletes, no auth or management access. Never put an `sk_` key in browser code (the SDK throws if you try).
+
+## Errors
+
+Every method throws `GemmeinError`:
+
+```js
+import { GemmeinError } from "@gemmein/sdk"
+
+try {
+  await g.collection("tasks").create({ title: "Test" })
+} catch (err) {
+  if (err instanceof GemmeinError) {
+    err.code     // "auth_expired", "unknown_collection", "scope_denied",
+                 // "not_found" (also when touching a record you don't own —
+                 // existence is never leaked), ...
+    err.status   // HTTP status
+    err.message  // human-readable, includes what to do next
+    err.resetAt  // rate limits: when to retry
+  }
+}
+```
+
+| Code | Status | Meaning |
+|------|--------|---------|
+| `missing_app_key` | 401 | No app key — get one at app.gemmein.com |
+| `invalid_app_key` | 403 | Key not recognized (typo, or wrong environment) |
+| `auth_expired` | 401 | Session expired — SDK auto-clears the token |
+| `unknown_collection` | 404 | Collection doesn't exist — create it in the dashboard |
+| `scope_denied` | 403 | Secret key not scoped for this collection/action |
+| `html_not_allowed` | 400 | Community collections store plain text — remove HTML tags |
+| `invalid_file_content` | 400 | Uploaded bytes aren't the image type they claimed — upload the actual image, not a renamed file |
+| `unknown_product` | 404 | No product by that name — the message lists what the app sells |
+| `invalid_publish` | 400 | `published` is an option on public collections only — not a data field, not for scoped rules |
+| `forbidden` | 403 | The rules refused this — a permission your user doesn't have. **Never retry**: the same call will always be refused. Fix the approach (wrong collection rule, non-admin writing to `admin_write`, secret key out of scope) or show `err.message`. |
+| `denied` | 429 / 401 | The generic refusal for everything retriable or fixable: a rate limit (429 — carries `resetAt`, wait and retry) or a missing sign-in (401 — sign in first via `g.auth.sendEmailCode`). Distinguish by HTTP status; show `err.message`, which reads correctly for each. |
+
+**Branching on error codes:** switch on the *specific named* codes above. The one rule that matters: `forbidden` means stop — retrying can never succeed; `denied` means the request could work later (wait for `resetAt` on 429, sign in on 401). Only rate-limit `denied` carries `resetAt` — that's the reliable signal for a retry-after.
+
+## Keys & environments
+
+| Prefix | Environment | Where it lives |
+|--------|------------|----------------|
+| `pk_test_...` | Development | Frontend code — safe to expose |
+| `pk_live_...` | Production | Frontend code — safe to expose |
+| `sk_dev_...` / `sk_live_...` | Dev / Prod | Server env vars only |
+
+Environments are fully isolated: different data, different users, different collections.
+
+## Management is dashboard-only
+
+Collections, domains, keys, payments config, logs, and usage live in the [dashboard](https://app.gemmein.com) — deliberately not in the SDK, so management credentials can never leak from app code.
+
+---
+
+Gemmein is an early release: the core above is live, security-audited, and safe to build on; the wider feature set rolls out in stages. [gemmein.com](https://gemmein.com) · hello@gemmein.com

package/REFERENCE.md

@@ -0,0 +1,264 @@
+# Gemmein SDK — API Reference
+
+Complete surface of `@gemmein/sdk`, generated from the type definitions.
+This is the **reference** (every method, signature, return shape, error);
+`llms.txt` is the **guide** (how the model works and the safe patterns). Both
+are needed. Draft — feeds docs.gemmein.com.
+
+```ts
+import { gemmein, GemmeinError } from "@gemmein/sdk";
+const g = gemmein("pk_...");        // browser: your public app key (domain-locked, safe to ship)
+```
+
+---
+
+## Setup
+
+### `gemmein(appKey, options?) → Gemmein`
+The browser client. `appKey` is your public `pk_...` key. `options` (optional):
+`{ apiUrl?: string, tokenStore?: TokenStore }`. Throws `GemmeinError`
+(`missing_app_key` / `invalid_app_key`) if the key is absent or an `sk_`.
+
+### `gemmeinServer(secretKey, options?) → GemmeinServer`
+Server-only client for a `sk_...` secret key — **never ship this to the
+browser.** Exposes read/update on collections without a signed-in user, 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
+the **business primitives Gemmein runs for you** — `g.auth`,
+`g.subscriptions`, `g.payments`, `g.account`: self-service surfaces for the
+signed-in user. Managing *other* people's users, subscriptions, and records
+happens in the owner's dashboard, deliberately not in this SDK.
+
+---
+
+## Authentication — `g.auth`
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `sendEmailCode` | `(email: string)` | `Promise<void>` — emails a sign-in code |
+| `verifyEmailCode` | `({ email, code }: { email: string; code: string })` | `Promise<AuthSession>` |
+| `currentUser` | `()` | `Promise<CurrentUser>` — **never throws** for session state; safe on load |
+| `logout` | `()` | `Promise<void>` — revokes the server session **(the method is `logout`, not `signOut`)** |
+
+```ts
+type AuthSession = { token: string; expiresAt: string; user: { id: string; email: string } };
+type CurrentUser =
+  | { authenticated: true;  userId: string; email: string }   // note: userId, NOT id
+  | { authenticated: false; userId?: undefined; email?: undefined };
+```
+`verifyEmailCode` resolves the **session** (`user.id`, nested). `currentUser`
+resolves the **identity** (`userId`, flat). Use `currentUser()` for who's
+signed in. Sessions are one-per-user: verifying a new code revokes older ones.
+
+`currentUser()` answering `{ authenticated: false }` is deliberately silent
+about *why* — signed out, suspended by the owner, and erased all read the
+same, so a moderated user's state never leaks to the client. One signed-out
+screen covers all three.
+
+---
+
+## Account — `g.account`
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `delete` | `()` | `Promise<unknown>` — erases the signed-in user, clears the stored token |
+
+The "delete my account" screen. Every app it **applies** to needs one (GDPR
+right to erasure; Apple 5.1.1(v) for any app with account creation).
+Server-side it's the full cascade — sessions revoked, records and files
+deleted, subscription row removed. Irreversible: put a real confirm in front.
+
+---
+
+## Data — `g.collection<T>(name)`
+
+`name` must be **lowercase letters, numbers, and underscores** (`saved_games`,
+never `savedGames` — a bad name throws synchronously). Collections are created
+by the app owner in the dashboard, never by the SDK.
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `create` | `(data: T, options?: { key?: string; for?: string; published?: boolean })` | `Promise<GemmeinRecord<T>>` |
+| `list` | `(options?: ListOptions)` | `Promise<ListResult<T>>` |
+| `get` | `(id: string, options?: { expand?: string[] })` | `Promise<GemmeinRecord<T>>` |
+| `update` | `(id: string, data: Partial<T> \| { field: { increment\|decrement, floor?, ceiling? } }, options?: { ifVersion?: number; published?: boolean })` | `Promise<GemmeinRecord<T>>` |
+| `delete` | `(id: string)` | `Promise<void>` |
+| `upload` | `(file: Blob \| File, options?: { name?: string })` | `Promise<{ id: string; url: string; contentType: string; sizeBytes: number }>` |
+
+```ts
+type GemmeinRecord<T> = {
+  id: string;
+  data: T;                     // YOUR fields live here (record.data.title, never record.title)
+  createdAt: string;
+  updatedAt: string;
+  ownerUserId: string | null;  // server-set; null for app-owned (receipts, dashboard-created)
+  collectionId: string;
+  appId: string;
+  environmentId: string;
+  version: number;             // +1 per update; pass as { ifVersion } to guard concurrent edits
+  key?: string;                // the create-if-absent key, when one was used
+  audienceUserId?: string;     // recipient on addressed/direct collections (server-stamped)
+  published: boolean;          // top-level, not under .data; only meaningful on public rules
+  expand?: Record<string, GemmeinRecord | null>;  // filled by list/get { expand: [...] }
+  existing?: true;             // present only when a keyed create returned YOUR existing record
+};
+
+type ListResult<T> = { records: GemmeinRecord<T>[]; cursor?: string; hasMore: boolean };
+
+type ListOptions = {
+  limit?: number;
+  sort?: "newest" | "oldest" | "updated";
+  where?: Record<string, unknown>;   // exact-match on data fields (and link fields)
+  cursor?: string;                   // from a previous ListResult
+  search?: string;                   // free-text across data
+  expand?: string[];                 // link fields to embed (≤3), only on community/shared/direct
+};
+```
+
+**Options notes.** `key` = create-if-absent (a second writer gets 409
+`conflict`; your own retry returns the record with `existing: true`). `for` =
+recipient id on `addressed`/`direct`. `published: false` = draft on a public
+rule. `ifVersion` = optimistic concurrency. Atomic counters go in *value*
+position: `update(id, { stock: { decrement: 1, floor: 0 } })`. `expand` throws
+on `private`/`public_read`/`admin_write` (no link shape) — join in memory there.
+
+---
+
+## Payments — `g.subscriptions` / `g.payments`
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `subscriptions.mine` | `()` | `Promise<{ plan: string; status: "active" \| "cancelled" } \| null>` |
+| `subscriptions.checkout` | `(plan?: string)` | `Promise<{ url: string; plan: string }>` — **navigates the browser to Stripe** and resolves the url |
+| `payments.buy` | `(product: string, options?: { item?: string })` | `Promise<{ url: string; product: string; item?: string }>` — **navigates the browser to Stripe** and resolves the url |
+
+Plans are `g.subscriptions`; one-off things are `g.payments`. `checkout` and
+`buy` self-navigate via `window.location` — just `await` them on the click;
+don't also redirect to the returned `url`, and never build a Stripe URL
+yourself. Gate features on `(await g.subscriptions.mine())?.plan === "pro"`;
+gate one-off fulfilment on the receipt record, never the redirect.
+
+---
+
+## Reaffirm — prove your app's boundaries in CI
+
+Gemmein enforces the rules **server-side**, so your frontend is never the source
+of truth. That's exactly why you can move fast: a `reaffirm` script *exercises*
+your boundaries with live calls and fails the build on drift — so if a rule ever
+stopped matching what your UI assumes, you catch it on deploy, not in front of a
+user. You reaffirm **because** Gemmein enforces — never because these checks are
+the enforcement.
+
+Two tiers:
+
+**Tier A — anonymous + shape (zero setup, runs against any environment incl. live).**
+No session needed. Catches the loudest drift: a private collection an anon can
+read, a renamed/mis-cased collection (`collection("savedGames")` throws
+*synchronously*), the error-code contract, and the deliberate reminder that a
+`community`/`public_read` collection is readable by anyone.
+
+**Tier B — cross-user isolation (dev environments only).**
+Proving "user B genuinely can't read user A's private record" needs two real
+sessions. Mint them without an OTP round-trip:
+
+### `gemmeinServer(sk).testSession(email) → { token, expiresAt, user }`
+Mints a **member** session for a test email. **Dev only** — throws
+`test_session_forbidden_live` on an `sk_live` key, and the server refuses it on a
+live environment too (the invariant that keeps it off real user data). Pass the
+returned `token` to `gemmein(pk, { tokenStore })` to act as that user. Dev and
+live enforce the *same* rules, so isolation proven in dev holds in live.
+
+This exact harness ships as **`reaffirm.mjs` inside the npm package** — copy it
+out, edit the CONFIG block, run in CI.
+
+```js
+// reaffirm.mjs — run in CI: `node reaffirm.mjs` (exits non-zero on any drift).
+import { gemmein, gemmeinServer } from "@gemmein/sdk";
+
+const API = process.env.GEMMEIN_API_URL;                 // your dev API url
+const g   = gemmein(process.env.PUBLIC_KEY, { apiUrl: API });
+const srv = gemmeinServer(process.env.SECRET_KEY, { apiUrl: API }); // sk_dev only
+let fail = 0;
+const refuse = async (label, code, fn) => {              // must throw `code`
+  try { await fn(); console.error("✗", label, "— expected", code, "got success"); fail++; }
+  catch (e) { e.code === code ? console.log("✓", label)
+            : (console.error("✗", label, "— got", e.code), fail++); }
+};
+const asUser = (token) => gemmein(process.env.PUBLIC_KEY, {
+  apiUrl: API,
+  tokenStore: { get: async () => token, set: async () => {}, clear: async () => {} },
+});
+
+// ── TIER A: functional + anonymous (no login) ──
+g.collection("private_notes");                   // misnamed → throws HERE, loudly, in CI
+await refuse("anon can't read private",    "denied", () => g.collection("private_notes").list());
+await refuse("anon can't write community", "denied", () => g.collection("board").create({ text: "x" }));
+
+// ── TIER B: cross-user isolation (dev only) ──
+const alice = await srv.testSession("alice@test.dev");
+const bob   = await srv.testSession("bob@test.dev");
+const A = asUser(alice.token), B = asUser(bob.token);
+
+const note = await A.collection("private_notes").create({ text: "alice-secret" });
+await refuse("B can't read A's private note", "not_found", () =>
+  B.collection("private_notes").get(note.id));
+const bobSees = await B.collection("private_notes").list();
+if (bobSees.records.length !== 0) { console.error("✗ B sees A's private records"); fail++; }
+else console.log("✓ B's private list is isolated");
+
+// shape the UI reads (userId, NOT id):
+const who = await A.auth.currentUser();
+if (!who.userId) { console.error("✗ currentUser().userId missing"); fail++; }
+else console.log("✓ currentUser().userId present");
+
+process.exit(fail ? 1 : 0);
+```
+
+Add a probe every time you add a feature. Point the harness at your **dev**
+environment (Tier B needs it); the Tier-A block alone can additionally smoke-test
+live, since it never mints a session.
+
+---
+
+## Errors — `GemmeinError`
+
+Every failed call throws a `GemmeinError`:
+
+```ts
+class GemmeinError extends Error {
+  status: number;     // HTTP status
+  code: string;       // branch on this
+  message: string;    // render this — reads correctly for users
+  resetAt?: string;   // present on 429 — wait until then, retry
+}
+```
+
+Branch on `err.code`. The stable codes:
+
+| code | meaning | do |
+|------|---------|-----|
+| `unknown_collection` | collection doesn't exist | ask the owner to create it — don't retry |
+| `unknown_product` | product not sold | use a name from the list in the message |
+| `forbidden` | the rules refused you (e.g. only the owner writes) | **stop** — the same call always fails |
+| `not_found` | record you can't see (existence not leaked) | treat as absent |
+| `denied` | 401 (sign in first) or 429 (rate limit — see `resetAt`) | re-auth or wait+retry |
+| `conflict` | a keyed create / floor / stale `ifVersion` | it's the mechanism — tell the user it's taken |
+| `html_not_allowed` | HTML in a community/addressed/direct field | store plain text |
+| `invalid_publish` | `{ published }` on a non-public rule | drop it |
+| `invalid_shape` | field not in a locked (live) collection's shape | ask the owner to add it |
+| `invalid_audience` | `for` isn't a user of this app | fix the recipient id |
+| `unknown_record` | a link field points at a missing record (live only) | fix the id |
+| `payload_too_large` / `file_too_large` | over the size cap (message states it) | shrink it |
+| `invalid_file_content` | uploaded bytes aren't the claimed image type | send the real image |
+| `test_session_forbidden_live` | `testSession()` called on a live env / `sk_live` key | reaffirm's Tier B is dev-only — point it at your dev environment |
+| `unknown_plan` | no plan by that name | use a name from the list in the message |
+| `plan_not_purchasable` | tried to check out the free default plan | nothing to buy — gate on the paid plan's name |
+| `invalid_expand` | `expand` on a field/rule with no link shape | join in memory instead (private/public_read/admin_write have no links) |
+| `scope_denied` | secret key used outside its dashboard-configured scope (or on auth/management routes) | scope the key to that collection, or use the right surface |
+| `unsupported_file_type` (415) | upload isn't one of the allowed image types | send JPEG/PNG/WebP/GIF/HEIC |
+| `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 |
+
+Keys: `pk_` (public, domain-locked, browser-safe) vs `sk_` (secret, server only).