@gemmein/sdk 0.3.2 → 0.4.2

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"));
@@ -431,11 +439,167 @@ class CollectionClient {
             query.set("search", options.search);
         if (options.expand && options.expand.length > 0)
             query.set("expand", options.expand.join(","));
+        if (options.since !== undefined)
+            query.set("since", options.since instanceof Date ? options.since.toISOString() : options.since);
         // NOT query.size — absent on Node <19.8 / older browsers, where
         // `undefined > 0` would silently drop every filter.
         const qs = query.toString();
         return this.request(qs ? `?${qs}` : "");
     }
+    /**
+     * W7.2 — live-enough, honestly. Explicitly POLLING: a full list first,
+     * then "what changed?" every `every` ms (default 10s, floor 5s) through
+     * exactly the same permission gate as list(). Nothing is pushed.
+     *
+     *   const w = g.collection("orders").watch(({ records, deleted, initial }) => {
+     *     // initial=true: REPLACE your state — records IS the full current
+     *     // set, and replacing is what clears anything removed while you
+     *     // weren't looking. initial=false: upsert records by id (a change
+     *     // can arrive twice, never be missed); remove ids in `deleted`.
+     *   });
+     *   // later: w.stop()
+     *
+     * In a browser it sleeps while the tab is hidden and does a full resync on
+     * return (that resync is also how a record erased outright — not deleted
+     * by the app, erased — leaves the screen). On errors it backs off,
+     * doubling up to 60s, and honours a rate limit's reset time. One watch per
+     * page is the intended shape — share its result, don't stack watchers.
+     */
+    watch(onChange, options = {}) {
+        const asked = options.every;
+        const every = Math.max(5000, Math.min(300000, Number.isFinite(asked) ? asked : 10000));
+        const base = { where: options.where, search: options.search, limit: options.limit ?? 100 };
+        let stopped = false;
+        let timer;
+        let delayMs = every;
+        let watermark;
+        // One tick at a time. A visibility flip mid-tick sets resyncPending
+        // instead of racing a second loop into existence (each raced loop would
+        // have doubled the poll rate forever).
+        let inFlight = false;
+        let resyncPending = false;
+        const page = async (since) => {
+            const records = [];
+            const deleted = [];
+            let cursor;
+            let mark;
+            do {
+                const result = await this.list({ ...base, cursor, ...(since !== undefined ? { since } : {}) });
+                records.push(...result.records);
+                if (result.deleted)
+                    deleted.push(...result.deleted);
+                cursor = result.hasMore ? result.cursor : undefined;
+                if (since === undefined) {
+                    // Full sync: keep the FIRST page's watermark — anything written
+                    // while later pages stream must redeliver on the next poll, not
+                    // fall below an end-of-paging mark and vanish.
+                    mark = mark ?? result.watermark;
+                }
+                else if (!result.hasMore) {
+                    mark = result.watermark;
+                }
+            } while (cursor && !stopped);
+            return { records, deleted, mark };
+        };
+        const tick = async (resync) => {
+            if (stopped || inFlight)
+                return;
+            inFlight = true;
+            let delivery;
+            try {
+                const doResync = resync || resyncPending;
+                resyncPending = false;
+                const { records, deleted, mark } = await page(doResync ? undefined : watermark);
+                if (stopped) {
+                    inFlight = false;
+                    return;
+                }
+                if (mark !== undefined)
+                    watermark = mark;
+                delayMs = every;
+                if (doResync || records.length > 0 || deleted.length > 0) {
+                    delivery = { records, deleted, initial: doResync };
+                }
+            }
+            catch (err) {
+                if (stopped) {
+                    inFlight = false;
+                    return;
+                }
+                // Back off; a rate limit says exactly when to come back.
+                delayMs = Math.min(Math.max(delayMs * 2, every), 60000);
+                if (err instanceof GemmeinError && err.resetAt) {
+                    const wait = new Date(err.resetAt).getTime() - Date.now();
+                    if (Number.isFinite(wait) && wait > delayMs)
+                        delayMs = Math.min(wait, 300000);
+                }
+            }
+            inFlight = false;
+            if (delivery) {
+                // The app's callback runs OUTSIDE the wire handling: its exceptions
+                // are its own bugs, never a reason to back off or mangle the loop.
+                try {
+                    onChange(delivery);
+                }
+                catch { /* the app's error, not the wire's */ }
+            }
+            schedule();
+        };
+        const hidden = () => typeof document !== "undefined" && document.visibilityState === "hidden";
+        const schedule = () => {
+            if (stopped || hidden() || timer !== undefined)
+                return;
+            timer = setTimeout(() => { timer = undefined; void tick(false); }, delayMs);
+            // In Node a live timer pins the process open; a watcher should never
+            // be the reason a script can't exit.
+            timer.unref?.();
+        };
+        const onVisibility = () => {
+            if (stopped)
+                return;
+            if (hidden()) {
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                    timer = undefined;
+                }
+            }
+            else {
+                // Waking resyncs in full — the cheap answer to "what did I miss?",
+                // including anything erased while the tab slept. If a tick is mid
+                // flight, flag it rather than racing a second loop.
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                    timer = undefined;
+                }
+                delayMs = every;
+                if (inFlight) {
+                    resyncPending = true;
+                    return;
+                }
+                void tick(true);
+            }
+        };
+        if (typeof document !== "undefined") {
+            document.addEventListener("visibilitychange", onVisibility);
+        }
+        // Born hidden: wait for the tab — the visibility handler runs the first
+        // sync when the user actually looks.
+        if (!hidden())
+            void tick(true);
+        else
+            resyncPending = true;
+        return {
+            stop: () => {
+                stopped = true;
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                timer = undefined;
+                if (typeof document !== "undefined") {
+                    document.removeEventListener("visibilitychange", onVisibility);
+                }
+            },
+        };
+    }
     async get(id, options = {}) {
         const qs = options.expand && options.expand.length > 0 ? `?expand=${encodeURIComponent(options.expand.join(","))}` : "";
         return this.request(`/${encodeURIComponent(id)}${qs}`);
@@ -483,15 +647,24 @@ class CollectionClient {
      *   // later, to render:
      *   const { url } = await g.files.link(record.poster)
      *
+     * Images (JPEG/PNG/WebP/GIF/HEIC) and documents (PDF/ZIP/EPUB), 25 MB per
+     * file. A document always downloads — it is served as an attachment and
+     * never opens inside your page — so link it with `{ intent: "download" }`.
+     * Pass `{ name }` so the download carries a real filename, and
+     * `{ contentType }` when the Blob has no type of its own.
+     *
      * There is deliberately no `url` here. A URL that outlives a refund is the
      * bug this replaced.
      */
     async upload(file, options) {
         const name = options?.name ?? (file instanceof File ? file.name : "upload");
+        // A Blob built from bytes has type "" — `contentType` names it. The
+        // server proves the bytes either way.
+        const contentType = options?.contentType ?? file.type;
         // Step 1: Get presigned upload URL
         const presign = await this.request("/upload", {
             method: "POST",
-            body: JSON.stringify({ name, size: file.size, contentType: file.type }),
+            body: JSON.stringify({ name, size: file.size, contentType }),
         });
         // Step 2: Upload directly to S3 via presigned POST
         const form = new FormData();
@@ -605,6 +778,8 @@ class ServerCollectionClient {
             query.set("search", options.search);
         if (options.expand && options.expand.length > 0)
             query.set("expand", options.expand.join(","));
+        if (options.since !== undefined)
+            query.set("since", options.since instanceof Date ? options.since.toISOString() : options.since);
         // NOT query.size — absent on Node <19.8 / older browsers, where
         // `undefined > 0` would silently drop every filter.
         const qs = query.toString();
@@ -627,12 +802,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();
     }
@@ -650,12 +823,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();
 }
@@ -663,19 +831,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

@@ -65,6 +65,15 @@ export type ListResult<T extends Record<string, unknown> = Record<string, unknow
     records: GemmeinRecord<T>[];
     cursor?: string;
     hasMore: boolean;
+    /** W7.2: on a delta read (`since`), ids of records deleted after that
+     * instant — ids only, and only ones your rule scope admitted. */
+    deleted?: string[];
+    /** The instant to pass as the next `since`. On a plain list it rides
+     * every page (adopt the FIRST page's when you page a full sync); on a
+     * delta it rides only the final page. Deliberately lags the server clock
+     * ~2s, so a change can be delivered twice but never silently missed —
+     * apply records by id. */
+    watermark?: string;
 };
 export type ListOptions = {
     limit?: number;
@@ -78,6 +87,10 @@ export type ListOptions = {
     /** SHAPE-1: link fields to embed (up to 3) — each expanded record is only
      * what YOU could have read directly; unreadable/deleted targets are null. */
     expand?: string[];
+    /** W7.2: everything changed OR deleted after this instant, oldest change
+     * first. Pass the `watermark` from the previous answer. Incompatible with
+     * `sort` (delta order is fixed). */
+    since?: string | Date;
 };
 /**
  * Answer to "who is signed in right now?". `authenticated: false` simply
@@ -104,12 +117,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 +231,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 +248,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;
+        };
     }>>;
 }
 /**
@@ -389,6 +427,37 @@ export declare class CollectionClient<T extends Record<string, unknown> = Record
      * an object, not a bare array.
      */
     list(options?: ListOptions): Promise<ListResult<T>>;
+    /**
+     * W7.2 — live-enough, honestly. Explicitly POLLING: a full list first,
+     * then "what changed?" every `every` ms (default 10s, floor 5s) through
+     * exactly the same permission gate as list(). Nothing is pushed.
+     *
+     *   const w = g.collection("orders").watch(({ records, deleted, initial }) => {
+     *     // initial=true: REPLACE your state — records IS the full current
+     *     // set, and replacing is what clears anything removed while you
+     *     // weren't looking. initial=false: upsert records by id (a change
+     *     // can arrive twice, never be missed); remove ids in `deleted`.
+     *   });
+     *   // later: w.stop()
+     *
+     * In a browser it sleeps while the tab is hidden and does a full resync on
+     * return (that resync is also how a record erased outright — not deleted
+     * by the app, erased — leaves the screen). On errors it backs off,
+     * doubling up to 60s, and honours a rate limit's reset time. One watch per
+     * page is the intended shape — share its result, don't stack watchers.
+     */
+    watch(onChange: (delta: {
+        records: GemmeinRecord<T>[];
+        deleted: string[];
+        initial: boolean;
+    }) => void, options?: {
+        every?: number;
+        where?: Record<string, unknown>;
+        search?: string;
+        limit?: number;
+    }): {
+        stop(): void;
+    };
     get(id: string, options?: {
         expand?: string[];
     }): Promise<GemmeinRecord<T>>;
@@ -425,11 +494,18 @@ export declare class CollectionClient<T extends Record<string, unknown> = Record
      *   // later, to render:
      *   const { url } = await g.files.link(record.poster)
      *
+     * Images (JPEG/PNG/WebP/GIF/HEIC) and documents (PDF/ZIP/EPUB), 25 MB per
+     * file. A document always downloads — it is served as an attachment and
+     * never opens inside your page — so link it with `{ intent: "download" }`.
+     * Pass `{ name }` so the download carries a real filename, and
+     * `{ contentType }` when the Blob has no type of its own.
+     *
      * There is deliberately no `url` here. A URL that outlives a refund is the
      * bug this replaced.
      */
     upload(file: Blob | File, options?: {
         name?: string;
+        contentType?: string;
     }): Promise<{
         id: string;
         ref: FileRef;
@@ -478,6 +554,7 @@ declare class ServerCollectionClient {
         cursor?: string;
         search?: string;
         expand?: string[];
+        since?: string | Date;
     }): Promise<unknown>;
     update(id: string, data: Record<string, unknown>): Promise<unknown>;
     private request;

package/dist/index.d.ts

@@ -65,6 +65,15 @@ export type ListResult<T extends Record<string, unknown> = Record<string, unknow
     records: GemmeinRecord<T>[];
     cursor?: string;
     hasMore: boolean;
+    /** W7.2: on a delta read (`since`), ids of records deleted after that
+     * instant — ids only, and only ones your rule scope admitted. */
+    deleted?: string[];
+    /** The instant to pass as the next `since`. On a plain list it rides
+     * every page (adopt the FIRST page's when you page a full sync); on a
+     * delta it rides only the final page. Deliberately lags the server clock
+     * ~2s, so a change can be delivered twice but never silently missed —
+     * apply records by id. */
+    watermark?: string;
 };
 export type ListOptions = {
     limit?: number;
@@ -78,6 +87,10 @@ export type ListOptions = {
     /** SHAPE-1: link fields to embed (up to 3) — each expanded record is only
      * what YOU could have read directly; unreadable/deleted targets are null. */
     expand?: string[];
+    /** W7.2: everything changed OR deleted after this instant, oldest change
+     * first. Pass the `watermark` from the previous answer. Incompatible with
+     * `sort` (delta order is fixed). */
+    since?: string | Date;
 };
 /**
  * Answer to "who is signed in right now?". `authenticated: false` simply
@@ -104,12 +117,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 +231,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 +248,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;
+        };
     }>>;
 }
 /**
@@ -389,6 +427,37 @@ export declare class CollectionClient<T extends Record<string, unknown> = Record
      * an object, not a bare array.
      */
     list(options?: ListOptions): Promise<ListResult<T>>;
+    /**
+     * W7.2 — live-enough, honestly. Explicitly POLLING: a full list first,
+     * then "what changed?" every `every` ms (default 10s, floor 5s) through
+     * exactly the same permission gate as list(). Nothing is pushed.
+     *
+     *   const w = g.collection("orders").watch(({ records, deleted, initial }) => {
+     *     // initial=true: REPLACE your state — records IS the full current
+     *     // set, and replacing is what clears anything removed while you
+     *     // weren't looking. initial=false: upsert records by id (a change
+     *     // can arrive twice, never be missed); remove ids in `deleted`.
+     *   });
+     *   // later: w.stop()
+     *
+     * In a browser it sleeps while the tab is hidden and does a full resync on
+     * return (that resync is also how a record erased outright — not deleted
+     * by the app, erased — leaves the screen). On errors it backs off,
+     * doubling up to 60s, and honours a rate limit's reset time. One watch per
+     * page is the intended shape — share its result, don't stack watchers.
+     */
+    watch(onChange: (delta: {
+        records: GemmeinRecord<T>[];
+        deleted: string[];
+        initial: boolean;
+    }) => void, options?: {
+        every?: number;
+        where?: Record<string, unknown>;
+        search?: string;
+        limit?: number;
+    }): {
+        stop(): void;
+    };
     get(id: string, options?: {
         expand?: string[];
     }): Promise<GemmeinRecord<T>>;
@@ -425,11 +494,18 @@ export declare class CollectionClient<T extends Record<string, unknown> = Record
      *   // later, to render:
      *   const { url } = await g.files.link(record.poster)
      *
+     * Images (JPEG/PNG/WebP/GIF/HEIC) and documents (PDF/ZIP/EPUB), 25 MB per
+     * file. A document always downloads — it is served as an attachment and
+     * never opens inside your page — so link it with `{ intent: "download" }`.
+     * Pass `{ name }` so the download carries a real filename, and
+     * `{ contentType }` when the Blob has no type of its own.
+     *
      * There is deliberately no `url` here. A URL that outlives a refund is the
      * bug this replaced.
      */
     upload(file: Blob | File, options?: {
         name?: string;
+        contentType?: string;
     }): Promise<{
         id: string;
         ref: FileRef;
@@ -478,6 +554,7 @@ declare class ServerCollectionClient {
         cursor?: string;
         search?: string;
         expand?: string[];
+        since?: string | Date;
     }): Promise<unknown>;
     update(id: string, data: Record<string, unknown>): Promise<unknown>;
     private request;

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"));
@@ -415,11 +423,167 @@ export class CollectionClient {
             query.set("search", options.search);
         if (options.expand && options.expand.length > 0)
             query.set("expand", options.expand.join(","));
+        if (options.since !== undefined)
+            query.set("since", options.since instanceof Date ? options.since.toISOString() : options.since);
         // NOT query.size — absent on Node <19.8 / older browsers, where
         // `undefined > 0` would silently drop every filter.
         const qs = query.toString();
         return this.request(qs ? `?${qs}` : "");
     }
+    /**
+     * W7.2 — live-enough, honestly. Explicitly POLLING: a full list first,
+     * then "what changed?" every `every` ms (default 10s, floor 5s) through
+     * exactly the same permission gate as list(). Nothing is pushed.
+     *
+     *   const w = g.collection("orders").watch(({ records, deleted, initial }) => {
+     *     // initial=true: REPLACE your state — records IS the full current
+     *     // set, and replacing is what clears anything removed while you
+     *     // weren't looking. initial=false: upsert records by id (a change
+     *     // can arrive twice, never be missed); remove ids in `deleted`.
+     *   });
+     *   // later: w.stop()
+     *
+     * In a browser it sleeps while the tab is hidden and does a full resync on
+     * return (that resync is also how a record erased outright — not deleted
+     * by the app, erased — leaves the screen). On errors it backs off,
+     * doubling up to 60s, and honours a rate limit's reset time. One watch per
+     * page is the intended shape — share its result, don't stack watchers.
+     */
+    watch(onChange, options = {}) {
+        const asked = options.every;
+        const every = Math.max(5000, Math.min(300000, Number.isFinite(asked) ? asked : 10000));
+        const base = { where: options.where, search: options.search, limit: options.limit ?? 100 };
+        let stopped = false;
+        let timer;
+        let delayMs = every;
+        let watermark;
+        // One tick at a time. A visibility flip mid-tick sets resyncPending
+        // instead of racing a second loop into existence (each raced loop would
+        // have doubled the poll rate forever).
+        let inFlight = false;
+        let resyncPending = false;
+        const page = async (since) => {
+            const records = [];
+            const deleted = [];
+            let cursor;
+            let mark;
+            do {
+                const result = await this.list({ ...base, cursor, ...(since !== undefined ? { since } : {}) });
+                records.push(...result.records);
+                if (result.deleted)
+                    deleted.push(...result.deleted);
+                cursor = result.hasMore ? result.cursor : undefined;
+                if (since === undefined) {
+                    // Full sync: keep the FIRST page's watermark — anything written
+                    // while later pages stream must redeliver on the next poll, not
+                    // fall below an end-of-paging mark and vanish.
+                    mark = mark ?? result.watermark;
+                }
+                else if (!result.hasMore) {
+                    mark = result.watermark;
+                }
+            } while (cursor && !stopped);
+            return { records, deleted, mark };
+        };
+        const tick = async (resync) => {
+            if (stopped || inFlight)
+                return;
+            inFlight = true;
+            let delivery;
+            try {
+                const doResync = resync || resyncPending;
+                resyncPending = false;
+                const { records, deleted, mark } = await page(doResync ? undefined : watermark);
+                if (stopped) {
+                    inFlight = false;
+                    return;
+                }
+                if (mark !== undefined)
+                    watermark = mark;
+                delayMs = every;
+                if (doResync || records.length > 0 || deleted.length > 0) {
+                    delivery = { records, deleted, initial: doResync };
+                }
+            }
+            catch (err) {
+                if (stopped) {
+                    inFlight = false;
+                    return;
+                }
+                // Back off; a rate limit says exactly when to come back.
+                delayMs = Math.min(Math.max(delayMs * 2, every), 60000);
+                if (err instanceof GemmeinError && err.resetAt) {
+                    const wait = new Date(err.resetAt).getTime() - Date.now();
+                    if (Number.isFinite(wait) && wait > delayMs)
+                        delayMs = Math.min(wait, 300000);
+                }
+            }
+            inFlight = false;
+            if (delivery) {
+                // The app's callback runs OUTSIDE the wire handling: its exceptions
+                // are its own bugs, never a reason to back off or mangle the loop.
+                try {
+                    onChange(delivery);
+                }
+                catch { /* the app's error, not the wire's */ }
+            }
+            schedule();
+        };
+        const hidden = () => typeof document !== "undefined" && document.visibilityState === "hidden";
+        const schedule = () => {
+            if (stopped || hidden() || timer !== undefined)
+                return;
+            timer = setTimeout(() => { timer = undefined; void tick(false); }, delayMs);
+            // In Node a live timer pins the process open; a watcher should never
+            // be the reason a script can't exit.
+            timer.unref?.();
+        };
+        const onVisibility = () => {
+            if (stopped)
+                return;
+            if (hidden()) {
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                    timer = undefined;
+                }
+            }
+            else {
+                // Waking resyncs in full — the cheap answer to "what did I miss?",
+                // including anything erased while the tab slept. If a tick is mid
+                // flight, flag it rather than racing a second loop.
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                    timer = undefined;
+                }
+                delayMs = every;
+                if (inFlight) {
+                    resyncPending = true;
+                    return;
+                }
+                void tick(true);
+            }
+        };
+        if (typeof document !== "undefined") {
+            document.addEventListener("visibilitychange", onVisibility);
+        }
+        // Born hidden: wait for the tab — the visibility handler runs the first
+        // sync when the user actually looks.
+        if (!hidden())
+            void tick(true);
+        else
+            resyncPending = true;
+        return {
+            stop: () => {
+                stopped = true;
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                timer = undefined;
+                if (typeof document !== "undefined") {
+                    document.removeEventListener("visibilitychange", onVisibility);
+                }
+            },
+        };
+    }
     async get(id, options = {}) {
         const qs = options.expand && options.expand.length > 0 ? `?expand=${encodeURIComponent(options.expand.join(","))}` : "";
         return this.request(`/${encodeURIComponent(id)}${qs}`);
@@ -467,15 +631,24 @@ export class CollectionClient {
      *   // later, to render:
      *   const { url } = await g.files.link(record.poster)
      *
+     * Images (JPEG/PNG/WebP/GIF/HEIC) and documents (PDF/ZIP/EPUB), 25 MB per
+     * file. A document always downloads — it is served as an attachment and
+     * never opens inside your page — so link it with `{ intent: "download" }`.
+     * Pass `{ name }` so the download carries a real filename, and
+     * `{ contentType }` when the Blob has no type of its own.
+     *
      * There is deliberately no `url` here. A URL that outlives a refund is the
      * bug this replaced.
      */
     async upload(file, options) {
         const name = options?.name ?? (file instanceof File ? file.name : "upload");
+        // A Blob built from bytes has type "" — `contentType` names it. The
+        // server proves the bytes either way.
+        const contentType = options?.contentType ?? file.type;
         // Step 1: Get presigned upload URL
         const presign = await this.request("/upload", {
             method: "POST",
-            body: JSON.stringify({ name, size: file.size, contentType: file.type }),
+            body: JSON.stringify({ name, size: file.size, contentType }),
         });
         // Step 2: Upload directly to S3 via presigned POST
         const form = new FormData();
@@ -587,6 +760,8 @@ class ServerCollectionClient {
             query.set("search", options.search);
         if (options.expand && options.expand.length > 0)
             query.set("expand", options.expand.join(","));
+        if (options.since !== undefined)
+            query.set("since", options.since instanceof Date ? options.since.toISOString() : options.since);
         // NOT query.size — absent on Node <19.8 / older browsers, where
         // `undefined > 0` would silently drop every filter.
         const qs = query.toString();
@@ -609,12 +784,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();
     }
@@ -632,12 +805,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();
 }
@@ -645,19 +813,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,20 @@
   `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. A declaration is `gemmein/collections/<name>.json`:
+  `{ "rule": "shared", "means": "<why, in your human's words>" }`, plus an
+  optional `"unlockedBy": ["pro"]` — plan or product NAMES from
+  gemmein/payments.json (never access keys) — which is the console's
+  "Unlocked by": the local engine refuses members without one of them
+  (403 entitlement_required) the moment the file lands, and sync carries
+  it to the cloud app. An unknown name is refused out loud in the dev
+  terminal and the collection is not created. 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 +170,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
@@ -68,9 +190,9 @@
     as private or encrypted chat.
   Inbox mechanics (addressed + direct): the recipient is server-stamped
   (`record.audienceUserId`) — never a data field; user ids come from
-  records' ownerUserId or the owner's admin views. Reading is plain
-  `.list({ sort: "newest" })` — poll on window focus plus a gentle ~60s
-  interval, never a tight loop. Track read-state in the user's own private
+  records' ownerUserId or the owner's admin views. For a live-feeling inbox
+  (or any live list) use `.watch()` — see "Live data" below — never a tight
+  loop of your own. Track read-state in the user's own private
   collection. Both rules store plain text like community. Errors teach the
   fix: 400 invalid_audience (recipient isn't a user of this app), 403
   reply_only (this collection only allows replying to someone who wrote to
@@ -92,7 +214,35 @@
   `record.title`). `ownerUserId` and the rest are server-derived and
   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 }`.
+  accepts `{ limit, sort: "newest"|"oldest"|"updated", where, search, cursor,
+  since }`.
+- 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:
+
+      const w = g.collection("orders").watch(({ records, deleted, initial }) => {
+        // initial=true → REPLACE your state with `records` (it IS the full
+        // current set — replacing is what clears anything removed while you
+        // weren't looking). initial=false → upsert `records` BY ID and drop
+        // ids in `deleted`.
+      });
+      // when the view unmounts: w.stop()
+
+  Every 10s by default (`{ every: ms }`, floor 5s) it asks "what changed?" —
+  a near-free answer when nothing did. It sleeps while the tab is hidden and
+  refreshes fully on return. Apply records by id: a change can be delivered
+  twice, never silently missed. One watch per page, shared — don't stack a
+  watcher per component, and never wrap it in your own setInterval. Under
+  the hood it's `list({ since })`: pass the previous answer's `watermark` as
+  `since` and you get records changed or deleted after it (ids in
+  `deleted`), oldest first — same permissions as any read. `since` can't
+  combine with `sort`. A record erased by the platform (data erasure, not an
+  app delete) doesn't appear in `deleted` — the replace-on-initial refresh
+  on tab-return is what clears it. Watching with `where`/`search`: deletions
+  always come through, but a record EDITED so it stops matching your filter
+  isn't reported (it isn't deleted) — it clears on the next tab-return
+  refresh. Watch suits lists you'd actually render (up to a few thousand
+  records); it re-reads the full list on every tab return.
 - 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;
@@ -113,7 +263,8 @@
   storage bucket — uploads are built in:
   `const file = await g.collection("posts").upload(blob, { name })`
   → `{ id, ref, contentType, sizeBytes }`. Store `file.ref` (`"file:01K…"`)
-  in a record field like any text — that's how a record "has" an image.
+  in a record field like any text — that's how a record "has" an image or
+  a document.
   Store the REFERENCE, never a URL: a reference never expires and grants
   nothing on its own.
   To show or download it: `const { url } = await g.files.link(record.photo)`
@@ -121,14 +272,21 @@
   rather than a preview. Files in a collection anyone can read get a
   permanent link; every other file gets one that expires in a couple of
   minutes, so call `link()` when you render, don't store what it returns.
-  Upload permission follows the collection's WRITE rule; images only
-  (JPEG/PNG/WebP/GIF/HEIC). Oversized files are refused loudly (413
+  Upload permission follows the collection's WRITE rule. Images (JPEG/PNG/
+  WebP/GIF/HEIC) and documents (PDF/ZIP/EPUB), 25 MB per file; nothing
+  else (no video, audio, SVG, HTML or office files — zip an office file).
+  Images render with `<img>`; a document always DOWNLOADS (served as an
+  attachment under the `name` you gave upload() — it never opens inside
+  your page), so link documents with `{ intent: "download" }`. A Blob you
+  built from bytes has no type: pass `{ contentType: "application/pdf" }`
+  to upload(), or a 415 says "none declared". Oversized files are refused loudly (413
   file_too_large — the message says the cap). The server checks the actual
   bytes at confirm — a 400 invalid_file_content means the file isn't really
-  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
+  the type it claimed (usually a renamed file); send the real file, 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 +305,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,26 +349,36 @@
   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 the "Unlocked by" row on its Collections
-  card — 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.) 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
-  FULL refund or a cancellation revokes exactly what it granted — nothing
-  else. A partial refund leaves access in place.
+- 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), or, in
+  local dev, you write the same thing as `"unlockedBy": ["pro"]` in
+  gemmein/collections/<name>.json (names, never keys; `npx gemmein check`
+  checks that the lock holds and names collections left open while the app
+  sells something) — 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:
@@ -213,15 +387,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 for proof — but TODAY it is REQUIRED for file
-  delivery: the file reference only reaches the buyer on the receipt
-  record (its `deliveryFile` field, a `file:` ref — resolve it per reader
-  with `g.files.link`, which re-checks access on every mint). Selling a
-  file? Configure a receipts collection, or the buyer has no way to reach
-  their download. External `deliveryUrl` 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
+  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
@@ -318,25 +496,38 @@ 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. Reaching a ceiling never stops your app: sign-ins,
+  writes and API requests keep working past it, the founder is told once
+  for the month, and next month's bill follows the band their people land
+  in. Storage is the one thing that can fill — files are accepted up to
+  twice the storage ceiling, then uploads return `usage_limit_exceeded`
+  (no `resetAt`; storage frees when files are deleted). The per-IP and
+  per-email rate limits underneath are safety rails, not ceilings, and
+  still answer 429 with `resetAt`. The dashboard's usage page shows what
+  crossed this month.
 
 ## Facts for citation
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.3.2",
-  "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.4.2",
+  "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",
@@ -53,4 +53,4 @@
   "bugs": {
     "email": "hello@gemmein.com"
   }
-}
+}