@gemmein/sdk 0.3.1 → 0.4.1

package/README.md

@@ -263,6 +263,8 @@ try {
     err.status   // HTTP status
     err.message  // human-readable, includes what to do next
     err.resetAt  // rate limits: when to retry
+    err.requires // 403 entitlement_required: the plan/product key this
+                 // collection asks for — show your upgrade screen
   }
 }
 ```
@@ -279,6 +281,7 @@ try {
 | `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`. |
+| `entitlement_required` | 403 | Signed in, but not on a plan (or holding a product) this collection is unlocked by. `err.requires` carries that plan's key (`access:pro` for a plan named pro). The one 403 that succeeds later: show your upgrade screen, send them to checkout, retry after they hold it. |
 | `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.

package/REFERENCE.md

@@ -271,6 +271,7 @@ class GemmeinError extends Error {
   code: string;       // branch on this
   message: string;    // render this — reads correctly for users
   resetAt?: string;   // present on 429 — wait until then, retry
+  requires?: string;  // present on 403 entitlement_required — the plan/product key it asks for
 }
 ```
 
@@ -281,6 +282,7 @@ Branch on `err.code`. The stable codes:
 | `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 |
+| `entitlement_required` | 403 — signed in, but not on a plan (or holding a product) this collection is unlocked by; `err.requires` is that plan's key (`access:<slug of its name>`) | show your upgrade screen and send them to checkout — the one 403 that succeeds later |
 | `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 |

package/dist/index.cjs

@@ -10,6 +10,7 @@ class GemmeinError extends Error {
         this.status = input.status;
         this.code = input.code;
         this.resetAt = input.resetAt;
+        this.requires = input.requires;
     }
 }
 exports.GemmeinError = GemmeinError;
@@ -223,6 +224,13 @@ class PurchasesClient {
      * applied — `status` is "paid", "part_refunded" or "refunded", and
      * `refundedMinor` is how much has come back. Throws GemmeinError (401) when
      * nobody is signed in.
+     *
+     * W4.1b: a purchase whose product delivers something carries `delivery` —
+     * `{ type: "gemmein_file", file }` (resolve the ref with
+     * `g.files.link(file, { intent: "download" })`; the purchase itself is the
+     * authorization, re-checked on every mint, and a full refund cuts it off)
+     * or `{ type: "external_url", url }` (a plain handover). A refunded
+     * purchase never carries delivery.
      */
     async mine() {
         const result = (await runtimeRequest(this.config, "/auth/purchases"));
@@ -242,8 +250,13 @@ exports.PurchasesClient = PurchasesClient;
  * are, what the collection's rule says, whether the file is yours, and whether
  * you still hold whatever the collection requires.
  *
- * That is why the same app code keeps working when a collection later changes
- * from public to private — and why a refund actually takes a download away.
+ * That is why the same app code keeps working across collections, and why a
+ * refund takes away a download the buyer had not yet resolved. Two honest
+ * bounds: an already-issued link keeps working until it expires (minutes),
+ * and a file uploaded while its collection was public keeps its permanent
+ * URL even if the rule is later tightened — new uploads seal, old ones are
+ * moved only by an owner reseal. Sell access with the rule set from the
+ * start, not tightened afterwards.
  *
  * Don't store what this returns. Store the reference and call this again.
  */
@@ -622,12 +635,10 @@ class ServerCollectionClient {
         if (response.status === 204)
             return undefined;
         if (!response.ok) {
-            const body = await response.json().catch(() => ({ code: "request_failed", message: `Request failed: ${response.status}` }));
-            throw new GemmeinError({
-                status: response.status,
-                code: body.code ?? "request_failed",
-                message: body.message ?? `Request failed: ${response.status}`,
-            });
+            // One parser for every refusal body, so a 403 entitlement_required on a
+            // collection surfaces `requires` exactly as it does on the runtime
+            // clients (the docs promise err.requires on BOTH paths).
+            throw new GemmeinError({ status: response.status, ...(await readErrorBody(response)) });
         }
         return response.json();
     }
@@ -645,12 +656,7 @@ async function handleResponse(response, config) {
         if (errorBody.code === "invalid_app_key" || errorBody.code === "missing_app_key") {
             errorBody.message += " — get your app key from the Setup page at https://app.gemmein.com (sign in with an email code, free, no card)";
         }
-        throw new GemmeinError({
-            status: response.status,
-            code: errorBody.code,
-            message: errorBody.message,
-            resetAt: errorBody.resetAt
-        });
+        throw new GemmeinError({ status: response.status, ...errorBody });
     }
     return response.json();
 }
@@ -658,19 +664,19 @@ async function readErrorBody(response) {
     try {
         const value = await response.json();
         if (typeof value === "object" && value !== null) {
-            const code = typeof value.code === "string"
-                ? value.code
-                : typeof value.error === "string"
-                    ? value.error
+            const body = value;
+            const code = typeof body.code === "string" ? body.code
+                : typeof body.error === "string" ? body.error
                     : "request_failed";
+            const str = (v) => (typeof v === "string" ? v : undefined);
+            // ENTITLE-10: `requires` is the one key the 403 names (the lock's
+            // first). Copied only when the server sent it as a string — never
+            // invented client-side, and nothing else from the body is surfaced.
             return {
                 code,
-                message: typeof value.message === "string"
-                    ? value.message
-                    : `Gemmein request failed: ${response.status}`,
-                resetAt: typeof value.resetAt === "string"
-                    ? value.resetAt
-                    : undefined
+                message: str(body.message) ?? `Gemmein request failed: ${response.status}`,
+                resetAt: str(body.resetAt),
+                requires: str(body.requires)
             };
         }
     }

package/dist/index.d.cts

@@ -104,12 +104,23 @@ export type AuthSession = {
 export declare class GemmeinError extends Error {
     readonly status: number;
     readonly code: string;
+    /** Present on 429 — when the limit resets; wait until then and retry. */
     readonly resetAt?: string;
+    /**
+     * Present on `403 entitlement_required` — the plan/product key this
+     * collection asks for (keys are minted from plan names: `access:<slug>`;
+     * the console shows the plan by name). Show your upgrade screen and send
+     * the customer to checkout; the call succeeds once they hold it. A
+     * collection unlocked by several plans names ONE key here — offer your
+     * plans by name through checkout, the server never hands out the list.
+     */
+    readonly requires?: string;
     constructor(input: {
         status: number;
         code: string;
         message: string;
         resetAt?: string;
+        requires?: string;
     });
 }
 export declare class MemoryTokenStore implements TokenStore {
@@ -207,6 +218,13 @@ export declare class PurchasesClient {
      * applied — `status` is "paid", "part_refunded" or "refunded", and
      * `refundedMinor` is how much has come back. Throws GemmeinError (401) when
      * nobody is signed in.
+     *
+     * W4.1b: a purchase whose product delivers something carries `delivery` —
+     * `{ type: "gemmein_file", file }` (resolve the ref with
+     * `g.files.link(file, { intent: "download" })`; the purchase itself is the
+     * authorization, re-checked on every mint, and a full refund cuts it off)
+     * or `{ type: "external_url", url }` (a plain handover). A refunded
+     * purchase never carries delivery.
      */
     mine(): Promise<Array<{
         item: string;
@@ -217,6 +235,13 @@ export declare class PurchasesClient {
         status: "paid" | "part_refunded" | "refunded";
         grants: string[];
         paidAt: string;
+        delivery?: {
+            type: "gemmein_file";
+            file: string;
+        } | {
+            type: "external_url";
+            url: string;
+        };
     }>>;
 }
 /**
@@ -242,8 +267,13 @@ export type FileRef = string & {
  * are, what the collection's rule says, whether the file is yours, and whether
  * you still hold whatever the collection requires.
  *
- * That is why the same app code keeps working when a collection later changes
- * from public to private — and why a refund actually takes a download away.
+ * That is why the same app code keeps working across collections, and why a
+ * refund takes away a download the buyer had not yet resolved. Two honest
+ * bounds: an already-issued link keeps working until it expires (minutes),
+ * and a file uploaded while its collection was public keeps its permanent
+ * URL even if the rule is later tightened — new uploads seal, old ones are
+ * moved only by an owner reseal. Sell access with the rule set from the
+ * start, not tightened afterwards.
  *
  * Don't store what this returns. Store the reference and call this again.
  */

package/dist/index.d.ts

@@ -104,12 +104,23 @@ export type AuthSession = {
 export declare class GemmeinError extends Error {
     readonly status: number;
     readonly code: string;
+    /** Present on 429 — when the limit resets; wait until then and retry. */
     readonly resetAt?: string;
+    /**
+     * Present on `403 entitlement_required` — the plan/product key this
+     * collection asks for (keys are minted from plan names: `access:<slug>`;
+     * the console shows the plan by name). Show your upgrade screen and send
+     * the customer to checkout; the call succeeds once they hold it. A
+     * collection unlocked by several plans names ONE key here — offer your
+     * plans by name through checkout, the server never hands out the list.
+     */
+    readonly requires?: string;
     constructor(input: {
         status: number;
         code: string;
         message: string;
         resetAt?: string;
+        requires?: string;
     });
 }
 export declare class MemoryTokenStore implements TokenStore {
@@ -207,6 +218,13 @@ export declare class PurchasesClient {
      * applied — `status` is "paid", "part_refunded" or "refunded", and
      * `refundedMinor` is how much has come back. Throws GemmeinError (401) when
      * nobody is signed in.
+     *
+     * W4.1b: a purchase whose product delivers something carries `delivery` —
+     * `{ type: "gemmein_file", file }` (resolve the ref with
+     * `g.files.link(file, { intent: "download" })`; the purchase itself is the
+     * authorization, re-checked on every mint, and a full refund cuts it off)
+     * or `{ type: "external_url", url }` (a plain handover). A refunded
+     * purchase never carries delivery.
      */
     mine(): Promise<Array<{
         item: string;
@@ -217,6 +235,13 @@ export declare class PurchasesClient {
         status: "paid" | "part_refunded" | "refunded";
         grants: string[];
         paidAt: string;
+        delivery?: {
+            type: "gemmein_file";
+            file: string;
+        } | {
+            type: "external_url";
+            url: string;
+        };
     }>>;
 }
 /**
@@ -242,8 +267,13 @@ export type FileRef = string & {
  * are, what the collection's rule says, whether the file is yours, and whether
  * you still hold whatever the collection requires.
  *
- * That is why the same app code keeps working when a collection later changes
- * from public to private — and why a refund actually takes a download away.
+ * That is why the same app code keeps working across collections, and why a
+ * refund takes away a download the buyer had not yet resolved. Two honest
+ * bounds: an already-issued link keeps working until it expires (minutes),
+ * and a file uploaded while its collection was public keeps its permanent
+ * URL even if the rule is later tightened — new uploads seal, old ones are
+ * moved only by an owner reseal. Sell access with the rule set from the
+ * start, not tightened afterwards.
  *
  * Don't store what this returns. Store the reference and call this again.
  */

package/dist/index.js

@@ -5,6 +5,7 @@ export class GemmeinError extends Error {
         this.status = input.status;
         this.code = input.code;
         this.resetAt = input.resetAt;
+        this.requires = input.requires;
     }
 }
 export class MemoryTokenStore {
@@ -213,6 +214,13 @@ export class PurchasesClient {
      * applied — `status` is "paid", "part_refunded" or "refunded", and
      * `refundedMinor` is how much has come back. Throws GemmeinError (401) when
      * nobody is signed in.
+     *
+     * W4.1b: a purchase whose product delivers something carries `delivery` —
+     * `{ type: "gemmein_file", file }` (resolve the ref with
+     * `g.files.link(file, { intent: "download" })`; the purchase itself is the
+     * authorization, re-checked on every mint, and a full refund cuts it off)
+     * or `{ type: "external_url", url }` (a plain handover). A refunded
+     * purchase never carries delivery.
      */
     async mine() {
         const result = (await runtimeRequest(this.config, "/auth/purchases"));
@@ -231,8 +239,13 @@ export class PurchasesClient {
  * are, what the collection's rule says, whether the file is yours, and whether
  * you still hold whatever the collection requires.
  *
- * That is why the same app code keeps working when a collection later changes
- * from public to private — and why a refund actually takes a download away.
+ * That is why the same app code keeps working across collections, and why a
+ * refund takes away a download the buyer had not yet resolved. Two honest
+ * bounds: an already-issued link keeps working until it expires (minutes),
+ * and a file uploaded while its collection was public keeps its permanent
+ * URL even if the rule is later tightened — new uploads seal, old ones are
+ * moved only by an owner reseal. Sell access with the rule set from the
+ * start, not tightened afterwards.
  *
  * Don't store what this returns. Store the reference and call this again.
  */
@@ -604,12 +617,10 @@ class ServerCollectionClient {
         if (response.status === 204)
             return undefined;
         if (!response.ok) {
-            const body = await response.json().catch(() => ({ code: "request_failed", message: `Request failed: ${response.status}` }));
-            throw new GemmeinError({
-                status: response.status,
-                code: body.code ?? "request_failed",
-                message: body.message ?? `Request failed: ${response.status}`,
-            });
+            // One parser for every refusal body, so a 403 entitlement_required on a
+            // collection surfaces `requires` exactly as it does on the runtime
+            // clients (the docs promise err.requires on BOTH paths).
+            throw new GemmeinError({ status: response.status, ...(await readErrorBody(response)) });
         }
         return response.json();
     }
@@ -627,12 +638,7 @@ async function handleResponse(response, config) {
         if (errorBody.code === "invalid_app_key" || errorBody.code === "missing_app_key") {
             errorBody.message += " — get your app key from the Setup page at https://app.gemmein.com (sign in with an email code, free, no card)";
         }
-        throw new GemmeinError({
-            status: response.status,
-            code: errorBody.code,
-            message: errorBody.message,
-            resetAt: errorBody.resetAt
-        });
+        throw new GemmeinError({ status: response.status, ...errorBody });
     }
     return response.json();
 }
@@ -640,19 +646,19 @@ async function readErrorBody(response) {
     try {
         const value = await response.json();
         if (typeof value === "object" && value !== null) {
-            const code = typeof value.code === "string"
-                ? value.code
-                : typeof value.error === "string"
-                    ? value.error
+            const body = value;
+            const code = typeof body.code === "string" ? body.code
+                : typeof body.error === "string" ? body.error
                     : "request_failed";
+            const str = (v) => (typeof v === "string" ? v : undefined);
+            // ENTITLE-10: `requires` is the one key the 403 names (the lock's
+            // first). Copied only when the server sent it as a string — never
+            // invented client-side, and nothing else from the body is surfaced.
             return {
                 code,
-                message: typeof value.message === "string"
-                    ? value.message
-                    : `Gemmein request failed: ${response.status}`,
-                resetAt: typeof value.resetAt === "string"
-                    ? value.resetAt
-                    : undefined
+                message: str(body.message) ?? `Gemmein request failed: ${response.status}`,
+                resetAt: str(body.resetAt),
+                requires: str(body.requires)
             };
         }
     }

package/llms.txt

@@ -1,11 +1,119 @@
 # Gemmein
 
-> Gemmein is the backend for AI-built web apps: passwordless authentication,
-> structured data storage with plain-English safety rules, and built-in Stripe
-> subscription handling. Security is on by default for every app — tenant
-> isolation, rate limiting, audit logs, domain-locked keys — with nothing to
-> configure. Free while building; going live starts the Live state at
-> $50/mo (up to 1,000 people); Growing unlocks 10,000 at $150/mo.
+> Gemmein is the go-live system for AI-built web apps: passwordless
+> authentication, structured data storage with plain-English safety rules, and
+> built-in Stripe subscription handling. Security is on by default for every
+> app — tenant isolation, rate limiting, audit logs, domain-locked keys — with
+> nothing to configure. Build anywhere, with any AI, free — and come to
+> Gemmein when you're done: the product is taking the app to real customers.
+> Live apps pay one banded plan, $50-$150/mo, set by the previous month's
+> verified people (five pre-agreed steps up to 10,000 people; beyond that,
+> talk to Gemmein).
+
+## First: assess fit (before any install, account, or code)
+
+You are likely an AI assistant whose human asked you to build an app — or to
+take an app they already built to real customers. Do this assessment first
+and give your human the verdict in plain words. Installing nothing and
+creating no accounts is the correct behavior until the verdict is in.
+
+1. Collect the requirements.
+   - Idea-stage (nothing built yet): have your human describe the app in
+     their words. You need to know: who signs in, what data exists and who
+     may see whose, whether money changes hands (subscriptions or one-off
+     digital purchases), whether users upload files.
+   - Built-stage (an app already exists — e.g. from a vibe-coding tool):
+     read the code instead. Inventory what currently stubs or fakes
+     sign-in, storage, and payments, and any server endpoints the app
+     assumes will exist. (No code at hand — only a description? Fall back
+     to the idea-stage questions, and say the assessment is provisional
+     until you've read the code.)
+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
+   access, race-safe bookings/stock/counters, account-deletion cascade.
+   Out of scope — each of these downgrades the verdict and must never be
+   silently approximated:
+   - native mobile apps (no mobile SDKs today; web only)
+   - password or social/OAuth sign-in (email codes are the only door)
+   - team/group/workspace visibility or per-user record permissions
+   - carts, quantities, physical goods, shipping, inventory
+   - credits, usage metering, seats (paid access is yes-or-no)
+   - hosted functions or cron (server-side code runs on YOUR host with a
+     secret key; Gemmein hosts no compute)
+   - custody of money (Stripe holds all funds; your human brings or
+     creates their own Stripe account when the app charges)
+   - multi-seller payouts or revenue splits: every payment lands whole in
+     your human's ONE Stripe 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:
+   - FITS — every requirement maps. Continue to Getting started.
+   - FITS, EXCEPT — name each gap and the honest workaround from this
+     file, or say there is none. The human decides. Never fake an
+     unsupported shape (client-side filtering of a shared collection is a
+     data leak, not a workaround). And if a gap breaks the app's CORE
+     loop — the thing it exists to do — the verdict is DOESN'T FIT, not
+     fits-except.
+   - DOESN'T FIT — say so, name why, and stop. Recommending nothing is
+     the correct outcome here.
+
+## Getting started (AI-run, human-answered)
+
+No signup, no account, no keys — building is local and free. Your human
+steps in exactly three times: to answer the business questions (in your
+chat), to click through the app when you hand it over for testing, and at
+go-live. Everything else is yours.
+
+1. Run `npx -y gemmein dev` in the project folder. It boots with ZERO
+   setup: a local backend on http://127.0.0.1:4545 that serves this guide
+   at /llms.txt, prints sign-in codes to the terminal instead of sending
+   email, and simulates checkout — nothing leaves the machine.
+2. Ask YOUR HUMAN the business questions — their answers in their words,
+   never your guesses: the app's name; the email THEY own it with; one
+   honest sentence on what it does; whether it charges money; whether it
+   serves people in the EU/UK; whether users sign in; whether they upload
+   images. Write the answers to `gemmein/gemmein.config.json`:
+
+   {
+     "app": "Beatstall",
+     "owner": "you@example.com",
+     "product": "producers sell beats; buyers stream previews and download purchases",
+     "sells": "one-off",
+     "gdpr": true,
+     "accounts": true,
+     "uploads": true
+   }
+
+   Exactly these keys: app (string) · owner (email) · product (one
+   sentence) · sells ("no" | "subscriptions" | "one-off" | "both") ·
+   gdpr / accounts / uploads (true/false). Optional: port (number) moves
+   the local runtime off 4545.
+
+   Then restart dev (Ctrl-C, `npx gemmein dev` — takes seconds, data
+   survives in gemmein/.data/). The runtime becomes their app.
+3. Build against the local runtime with the app key the boot card prints
+   (`pk_local_…`) — the SDK is `npm install @gemmein/sdk` (REFERENCE.md
+   and the reaffirm.mjs harness ship inside that package), same rules as
+   the cloud. The first write to a collection that doesn't exist yet
+   starts the safety-rule conversation in the dev terminal; choose from
+   the seven rules below based on your human's business answers, and
+   record why. Running dev in the background with no terminal to answer
+   in (the normal agent setup)? Use the command doors instead — they work
+   from any second terminal while dev runs, and take piped input:
+   `npx gemmein collection add <name>` (the rule dialog) and
+   `npx gemmein payments setup` (plans/products). `npx gemmein --help`
+   lists the rest.
+4. Hand over for testing — the human moment mid-build: they click through
+   the app, and their sign-in codes print in the dev terminal, so tell
+   them where to look.
+5. Done building? `npx gemmein check` reads the project and says what's
+   ready and what go-live still needs. Then `npx gemmein sync` — THIS is
+   the moment your human signs up (free) at app.gemmein.com and pastes two
+   dev keys — and `npx gemmein go-live` walks the rest: plans, Payment
+   Links, the live flip. A card enters at go-live, never before.
 
 ## What it is
 
@@ -27,10 +135,13 @@
   `auth_expired` once, then the SDK clears it — just retry or re-auth).
   `g.auth.currentUser()` is safe to call on page load and never throws for
   session state.
-- Data: records live in collections. Collections are created by YOUR HUMAN in
-  their dashboard (app.gemmein.com → data → "+ New collection"), never by you
-  or the SDK. Best practice: at planning time, list the collections your app
-  will need and ask your human up front, and pass your intent whenever a
+- Data: records live in collections. In the cloud, collections are created by
+  YOUR HUMAN in their dashboard (app.gemmein.com → data → "+ New collection"),
+  never by you or the SDK; in local dev (`npx gemmein dev`) they're born from
+  the terminal's rule conversation or a dropped declaration file, and
+  `npx gemmein sync` creates them in the cloud app's dev environment from
+  those local declarations. Best practice: at planning time, list the collections your
+  app will need and ask your human up front, and pass your intent whenever a
   collection might not exist yet —
   `g.collection("bookings", { intent: "students reserve slots; each sees only their own" })`
   — so the missing-collection conversation reaches your human with your
@@ -52,7 +163,11 @@
   - `community` — readable without signing in, any signed-in user posts and
     edits their OWN records (right for multi-author blogs, public boards,
     user profiles). Everything in it is PUBLIC — keep record data minimal
-    (a booking needs a slot and a first name, not a phone number). Community
+    (a booking needs a slot and a first name, not a phone number). Whether
+    even a first name belongs in public is a HUMAN decision: for sensitive
+    audiences (children, health, anything private by nature) ask your
+    human before defaulting to a public rule — a non-public rule usually
+    fits. Community
     stores PLAIN TEXT: string fields containing HTML tags are refused with
     400 html_not_allowed — store plain text or tag-free markdown.
   - `addressed` — the app sends to one user: the OWNER creates records
@@ -128,7 +243,8 @@
   the image type it claimed (usually a renamed file); send the real image,
   don't retry. A 403 from `link()` means the customer isn't allowed this
   file right now — signed out, not theirs, or an entitlement they no longer
-  hold (`entitlement_required` names the key).
+  hold (`entitlement_required` — `err.requires` is the plan's key, the one
+  the console shows by name).
   Honest bound: revoking access stops NEW links immediately; a link already
   issued works until it expires. Gemmein controls delivery, it can't take
   back a file someone already downloaded.
@@ -147,8 +263,14 @@
   - Uniqueness: `create(data, { key: "slot:2026-07-15T15:00" })` — derive the
     key from the thing that must be unique; the second writer gets 409, your
     own retry gets your existing record back (`existing: true`), deleting
-    frees the key. Never find-then-create — that races. Keys are 1-120 chars
-    of letters, numbers, and `: _ . @ / -` only.
+    frees the key. Keys are unique across the WHOLE collection — every
+    writer, every recipient, under every safety rule (live records only) —
+    so a claim is race-proof even in `direct`/`addressed`. Never
+    find-then-create — that races. Keys are 1-120 chars of letters,
+    numbers, and `: _ . @ / -` only. A claimed key holds until its record
+    is deleted: if a claim must be PAID to stick (book then pay), expiring
+    unpaid claims is your app's job — the owner deletes them from their
+    dashboard, or your own server does with a secret key; there is no cron.
   - Limited stock (N units anyone can buy): claim units with keyed creates —
     try `create({...}, { key: "unit:item42:1" })`, on conflict try `:2` … `:N`;
     all taken = sold out. Race-proof under every safety rule.
@@ -185,23 +307,32 @@
   arriving out of order resolve to the newest. The app reads
   `await g.subscriptions.mine()` → `{ plan, status }` or null, and gates features
   with `sub?.plan === "pro"`.
-- Paid ACCESS (entitlements): a collection can require a key — your human
-  sets `requires: "access:pro"` in its settings — and the engine refuses
-  anyone without it, on every operation, under all seven rules. Keys are
-  granted by money: a plan or product lists what it unlocks (e.g.
-  `access:pro, access:exports`), the paid webhook grants those keys, and a
-  refund or cancellation revokes exactly what it granted — nothing else.
+- Paid ACCESS (entitlements): a collection can be locked to a plan or
+  product — your human picks it BY NAME in the "Unlocked by" row on the
+  Collections page (several allowed; any one of them opens it) — and the
+  engine refuses customers without it, under all seven rules. (Server
+  secret keys and the owner's console are exempt by design; link/expand
+  silently hide gated records rather than naming them.) Every plan and
+  product carries its own key, `access:<slug of its name>` (plan "pro" →
+  `access:pro`); the paid webhook grants that key, and a FULL refund or a
+  cancellation revokes exactly what it granted — nothing else. A partial
+  refund leaves access in place.
   Owners also grant and revoke by hand (trials, comps, support). Effective
   access is the UNION of a customer's live grants. A signed-in customer
-  without the key gets `403 entitlement_required` naming it — show your
-  upgrade screen and send them to checkout; never retry. Proof surfaces:
-  `await g.purchases.mine()` (everything they paid for, refunds applied,
-  with the `grants` each purchase carries) and `await g.subscriptions.mine()`.
+  without access gets `403 entitlement_required`: `err.requires` is the
+  plan's key (the console shows the plan by name; the key is `access:<slug>`).
+  A collection unlocked by several plans (OR) still names ONE key — offer
+  your plans by name through checkout, never a key list. Show your upgrade
+  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.
 - 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
-  things. The builder adds products (name + Stripe Payment Link) on the
+  things. Selling a SERVICE session this way (tutoring, coaching, a
+  consultation) is fine — nothing ships; the recorded purchase is the
+  proof the session was paid for. The builder adds products (name + Stripe Payment Link) on the
   same Payments page. The app calls
   `await g.payments.buy("beat")` — or, when one product covers many items (license
   tiers over a catalog), names the item:
@@ -210,14 +341,19 @@
   item note can never change what's paid). Gemmein records every completed
   payment itself — `await g.purchases.mine()` is the buyer's proof:
   { item, kind, status: "paid"|"part_refunded"|"refunded", amountMinor,
-  currency, refundedMinor, grants, paidAt }. A receipts collection (rule
-  `addressed`) is OPTIONAL — add one when you want receipts as records the
-  app renders; only the buyer and the owner read them. Delivery: attach
-  the thing to the product — a sealed Gemmein file (the receipt carries a
-  `file:` ref; resolve it per reader with `g.files.link`, which re-checks
-  access on every mint) or an external `deliveryUrl` (a plain handover:
-  Gemmein controls who is TOLD, not who can use it). Gate fulfilment on
-  the purchase or the entitlement it granted, never on the redirect coming
+  currency, refundedMinor, grants, paidAt, delivery? }. Selling a FILE (a
+  beat, an ebook, a sample pack — pdf, zip, epub, mp3, wav, m4a or an
+  image, up to 100MB): the founder attaches it directly on the product
+  card — upload, right there, no receipts collection required. The buyer's
+  purchase carries `delivery: { type: "gemmein_file", file }`; resolve the
+  ref with `g.files.link(file, { intent: "download" })`. The purchase IS
+  the authorization, re-checked on every mint: a refund cuts the file off
+  the moment it lands, a partial refund does not, and a saved ref or an
+  expired URL grants nothing on its own. A receipts collection (rule
+  `addressed`) remains OPTIONAL, for proof records only. External
+  `delivery: { type: "external_url" }` is a plain handover: Gemmein
+  controls who is TOLD, not who can use it. Gate fulfilment on the
+  purchase or the entitlement it granted, never on the redirect coming
   back — redirects can be faked; the record comes from Stripe's signed
   webhook. NO carts, NO quantities — one product per checkout by design; a
   cart is N checkouts or one bundled product. 404 unknown_product lists
@@ -314,25 +450,33 @@ front of a user.
 
 Add a probe whenever you add a feature. You reaffirm **because** Gemmein
 enforces — never because these checks are the enforcement. A ready-to-edit
-`reaffirm.mjs` ships inside this npm package (next to this file and
+`reaffirm.mjs` ships inside the `@gemmein/sdk` npm package (next to this file and
 REFERENCE.md) — copy it out, name your collections, run it in CI.
 
-## Pricing (current, Pricing Model v1 — states, not plans)
+## Pricing (current, v4 — one banded plan)
 
 - Development is free indefinitely — no card at signup, unlimited
   collections, the full security model included.
-- Going live starts the Live state: $50/mo, up to 1,000 people and 10 GB
-  of file storage (a person = a unique enabled end-user identity on the
-  live app).
-- Growing: $150/mo, up to 10,000 people and 50 GB — unlocked from the
-  dashboard when the product outgrows Live; down as easily as up.
+- Going live starts the one Live plan: a monthly price that moves within a
+  pre-agreed band, set by the PREVIOUS calendar month's verified people
+  (a person = a unique end-user identity that verified a sign-in to the
+  live app that month; failed or refused attempts never count):
+  - up to 1,000 people → $50/mo · up to 2,500 → $75 · up to 5,000 → $100
+    · up to 7,500 → $125 · up to 10,000 → $150 (the cap — never exceeded
+    without a separate individual agreement).
+- Capacity follows people automatically; owners can HOLD at their current
+  band from the dashboard (bill and capacity both freeze until released).
+  When people fall, the price follows down from the next month.
 - Beyond 10,000 people: talk to Gemmein (hello@gemmein.com) — scale is
   priced as a relationship, not a checkout.
 - Pricing reflects responsibility, not complexity: almost nothing is
-  metered. Safe limits exist purely as safety rails against runaway
-  scripts, are never billed, and real users never notice them. Hitting a
-  limit never breaks the app outright — there is grace, and the owner is
-  told.
+  metered. Safe limits exist as safety rails against runaway scripts and
+  are never billed. Ceilings follow the app's verified people — they grow
+  automatically as the business grows, with generous floors so a small app
+  never starts at a wall. Hitting a limit returns a clear coded error
+  (`usage_limit_exceeded`; monthly counters carry `resetAt`, storage
+  responds to deleting files), and the dashboard's usage page shows what
+  is binding.
 
 ## Facts for citation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "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.",
   "license": "MIT",
   "type": "module",