@gemmein/sdk 0.1.0 → 0.2.0

package/README.md

@@ -26,10 +26,12 @@ await g.auth.sendEmailCode("user@example.com")
 await g.auth.verifyEmailCode({ email: "user@example.com", code: "12345678" })
 
 // Store data — rules enforced server-side
-await g.storage.collection("tasks").create({ title: "Buy milk", done: false })
-const { records } = await g.storage.collection("tasks").list()
+await g.collection("tasks").create({ title: "Buy milk", done: false })
+const { records } = await g.collection("tasks").list()
 ```
 
+The client has two layers: **your collections** (`g.collection("tasks")` — your app's own data model) and the **business primitives Gemmein runs for you** (`g.auth`, `g.subscriptions`, `g.payments`, `g.account` — self-service surfaces for the signed-in user; managing *other* people's users, subscriptions, and records happens in the owner's dashboard, on purpose).
+
 Sessions persist across page reloads automatically (localStorage in browsers, memory elsewhere — override with `tokenStore` if you need custom persistence). One session per user: verifying a new code revokes that email's older sessions — a stale token throws `auth_expired` once, the SDK clears it, and a retry (or re-auth) recovers.
 
 ## Auth
@@ -44,15 +46,22 @@ const user = await g.auth.currentUser()
 // { authenticated: true, userId: "usr_...", email: "user@example.com" }
 
 await g.auth.logout()
-await g.auth.deleteAccount()   // GDPR erasure: revokes sessions, deletes the user's records
 ```
 
+### Deleting an account
+
+```js
+await g.account.delete()
+```
+
+Self-service erasure — the "delete my account" screen. Every app it **applies** to needs one (GDPR right to erasure; Apple 5.1.1(v) for any app with account creation). Server-side it's the full cascade: sessions revoked, the user's records and files deleted, their subscription row removed. Irreversible — put a real confirm in front of it.
+
 ## Storage
 
 Collections are created by the app owner in the dashboard (app.gemmein.com → data → "+ New collection") — the SDK can't create them. A 404 `unknown_collection` means it doesn't exist yet: ask the app owner to add it (one click) and pick its rule from the table below.
 
 ```js
-const tasks = g.storage.collection("tasks")
+const tasks = g.collection("tasks")
 
 const task = await tasks.create({ title: "Buy milk", done: false })
 
@@ -152,20 +161,20 @@ Gemmein hosts your Stripe webhook and manages subscriptions for you: exactly one
 ```js
 // 1. Send the buyer to checkout — one call, Gemmein does the rest. The app
 //    owner pasted each paid plan's Stripe Payment Link in their dashboard;
-//    g.checkout() picks the right one and wires the signed-in buyer in.
+//    g.subscriptions.checkout() picks the right one and wires the signed-in buyer in.
 //    Never build checkout URLs or sessions yourself: raw emails are
 //    silently dropped by Stripe's URL rules, and sessions need a secret
 //    key that must never ship client-side.
-await g.checkout("pro")   // redirects; omit the arg to buy the paid plan
+await g.subscriptions.checkout("pro")   // redirects; omit the arg to buy the paid plan
 // GemmeinError codes worth handling: "authentication_required" (sign in
 // first), "plan_has_no_link" (owner hasn't pasted that plan's link yet)
 
 // 2. Gate paid features by reading the managed subscription:
-const sub = await g.subscription()   // { plan, status } or null (never paid / payments off)
+const sub = await g.subscriptions.mine()   // { plan, status } or null (never paid / payments off)
 if (sub?.plan === "pro") { /* unlock */ }
 ```
 
-Do **not** write a webhook handler. Do **not** poll Stripe. Do **not** store plan/subscription state in your own collections — `g.subscription()` is the single source of truth, and there is deliberately no client write path to it.
+Do **not** write a webhook handler. Do **not** poll Stripe. Do **not** store plan/subscription state in your own collections — `g.subscriptions.mine()` is the single source of truth, and there is deliberately no client write path to it.
 
 Plan **limits** (note counts, feature caps, seat numbers) are your app's logic — Gemmein only tells you who is on which plan; the dashboard's plan names carry no quotas.
 
@@ -177,13 +186,13 @@ Plans are for subscriptions. To sell a **thing** — a poster, a beat, an ebook,
 // One product covering many items (license tiers over a catalog)? Name the
 // item — it's display text on the receipt, the PRICE always comes from the
 // product's Payment Link:
-await g.pay("premium license", { item: "beat_37" })   // redirects
+await g.payments.buy("premium license", { item: "beat_37" })   // redirects
 
 // Fulfilment: the completed payment writes a receipt record ADDRESSED to
 // the buyer — only they (and the owner) can read it. Gate the download on
 // the receipt, never on the redirect coming back (redirects can be faked;
 // receipts can't — they come from Stripe's signed webhook):
-const { records } = await g.storage.collection("receipts").list()
+const { records } = await g.collection("receipts").list()
 const paid = records.find(r => r.data.product === "premium license" && r.data.status === "paid")
 if (paid) { /* unlock — paid.data.deliveryUrl holds the download when the owner set one */ }
 ```
@@ -228,7 +237,7 @@ Every method throws `GemmeinError`:
 import { GemmeinError } from "@gemmein/sdk"
 
 try {
-  await g.storage.collection("tasks").create({ title: "Test" })
+  await g.collection("tasks").create({ title: "Test" })
 } catch (err) {
   if (err instanceof GemmeinError) {
     err.code     // "auth_expired", "unknown_collection", "scope_denied",
@@ -253,7 +262,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`. |
-| `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 — call `g.signIn`). Distinguish by HTTP status; show `err.message`, which reads correctly for each. |
+| `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

@@ -24,8 +24,12 @@ Server-only client for a `sk_...` secret key — **never ship this to the
 browser.** Exposes read/update on collections without a signed-in user, plus
 `testSession()` for CI self-tests (dev environments only — see **Reaffirm**).
 
-The client exposes two namespaces: **`g.auth`** and **`g.storage`**, plus the
-payment shortcuts `g.subscription()`, `g.checkout()`, `g.pay()`.
+The client has two layers. **Your app's collections** — `g.collection(name)`
+(the canonical spelling; `g.storage.collection(name)` is the same client). And
+the **business primitives Gemmein runs for you** — `g.auth`,
+`g.subscriptions`, `g.payments`, `g.account`: self-service surfaces for the
+signed-in user. Managing *other* people's users, subscriptions, and records
+happens in the owner's dashboard, deliberately not in this SDK.
 
 ---
 
@@ -37,7 +41,6 @@ payment shortcuts `g.subscription()`, `g.checkout()`, `g.pay()`.
 | `verifyEmailCode` | `({ email, code }: { email: string; code: string })` | `Promise<AuthSession>` |
 | `currentUser` | `()` | `Promise<CurrentUser>` — **never throws** for session state; safe on load |
 | `logout` | `()` | `Promise<void>` — revokes the server session **(the method is `logout`, not `signOut`)** |
-| `deleteAccount` | `()` | `Promise<unknown>` — erases the signed-in user |
 
 ```ts
 type AuthSession = { token: string; expiresAt: string; user: { id: string; email: string } };
@@ -49,9 +52,27 @@ type CurrentUser =
 resolves the **identity** (`userId`, flat). Use `currentUser()` for who's
 signed in. Sessions are one-per-user: verifying a new code revokes older ones.
 
+`currentUser()` answering `{ authenticated: false }` is deliberately silent
+about *why* — signed out, suspended by the owner, and erased all read the
+same, so a moderated user's state never leaks to the client. One signed-out
+screen covers all three.
+
+---
+
+## Account — `g.account`
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `delete` | `()` | `Promise<unknown>` — erases the signed-in user, clears the stored token |
+
+The "delete my account" screen. Every app it **applies** to needs one (GDPR
+right to erasure; Apple 5.1.1(v) for any app with account creation).
+Server-side it's the full cascade — sessions revoked, records and files
+deleted, subscription row removed. Irreversible: put a real confirm in front.
+
 ---
 
-## Data — `g.storage.collection<T>(name)`
+## Data — `g.collection<T>(name)`
 
 `name` must be **lowercase letters, numbers, and underscores** (`saved_games`,
 never `savedGames` — a bad name throws synchronously). Collections are created
@@ -105,18 +126,19 @@ on `private`/`public_read`/`admin_write` (no link shape) — join in memory ther
 
 ---
 
-## Payments — `g.subscription()` / `g.checkout()` / `g.pay()`
+## Payments — `g.subscriptions` / `g.payments`
 
 | Method | Signature | Returns |
 |--------|-----------|---------|
-| `subscription` | `()` | `Promise<{ plan: string; status: "active" \| "cancelled" } \| null>` |
-| `checkout` | `(plan?: string)` | `Promise<{ url: string; plan: string }>` — **navigates the browser to Stripe** and resolves the url |
-| `pay` | `(product: string, options?: { item?: string })` | `Promise<{ url: string; product: string; item?: string }>` — **navigates the browser to Stripe** and resolves the url |
+| `subscriptions.mine` | `()` | `Promise<{ plan: string; status: "active" \| "cancelled" } \| null>` |
+| `subscriptions.checkout` | `(plan?: string)` | `Promise<{ url: string; plan: string }>` — **navigates the browser to Stripe** and resolves the url |
+| `payments.buy` | `(product: string, options?: { item?: string })` | `Promise<{ url: string; product: string; item?: string }>` — **navigates the browser to Stripe** and resolves the url |
 
-`checkout` and `pay` self-navigate via `window.location` — just `await` them on
-the click; don't also redirect to the returned `url`, and never build a Stripe
-URL yourself. Gate features on `(await g.subscription())?.plan === "pro"`; gate
-one-off fulfilment on the receipt record, never the redirect.
+Plans are `g.subscriptions`; one-off things are `g.payments`. `checkout` and
+`buy` self-navigate via `window.location` — just `await` them on the click;
+don't also redirect to the returned `url`, and never build a Stripe URL
+yourself. Gate features on `(await g.subscriptions.mine())?.plan === "pro"`;
+gate one-off fulfilment on the receipt record, never the redirect.
 
 ---
 
@@ -170,19 +192,19 @@ const asUser = (token) => gemmein(process.env.PUBLIC_KEY, {
 });
 
 // ── TIER A: functional + anonymous (no login) ──
-g.storage.collection("private_notes");                   // misnamed → throws HERE, loudly, in CI
-await refuse("anon can't read private",    "denied", () => g.storage.collection("private_notes").list());
-await refuse("anon can't write community", "denied", () => g.storage.collection("board").create({ text: "x" }));
+g.collection("private_notes");                   // misnamed → throws HERE, loudly, in CI
+await refuse("anon can't read private",    "denied", () => g.collection("private_notes").list());
+await refuse("anon can't write community", "denied", () => g.collection("board").create({ text: "x" }));
 
 // ── TIER B: cross-user isolation (dev only) ──
 const alice = await srv.testSession("alice@test.dev");
 const bob   = await srv.testSession("bob@test.dev");
 const A = asUser(alice.token), B = asUser(bob.token);
 
-const note = await A.storage.collection("private_notes").create({ text: "alice-secret" });
+const note = await A.collection("private_notes").create({ text: "alice-secret" });
 await refuse("B can't read A's private note", "not_found", () =>
-  B.storage.collection("private_notes").get(note.id));
-const bobSees = await B.storage.collection("private_notes").list();
+  B.collection("private_notes").get(note.id));
+const bobSees = await B.collection("private_notes").list();
 if (bobSees.records.length !== 0) { console.error("✗ B sees A's private records"); fail++; }
 else console.log("✓ B's private list is isolated");
 
@@ -231,5 +253,12 @@ Branch on `err.code`. The stable codes:
 | `payload_too_large` / `file_too_large` | over the size cap (message states it) | shrink it |
 | `invalid_file_content` | uploaded bytes aren't the claimed image type | send the real image |
 | `test_session_forbidden_live` | `testSession()` called on a live env / `sk_live` key | reaffirm's Tier B is dev-only — point it at your dev environment |
+| `unknown_plan` | no plan by that name | use a name from the list in the message |
+| `plan_not_purchasable` | tried to check out the free default plan | nothing to buy — gate on the paid plan's name |
+| `invalid_expand` | `expand` on a field/rule with no link shape | join in memory instead (private/public_read/admin_write have no links) |
+| `scope_denied` | secret key used outside its dashboard-configured scope (or on auth/management routes) | scope the key to that collection, or use the right surface |
+| `unsupported_file_type` (415) | upload isn't one of the allowed image types | send JPEG/PNG/WebP/GIF/HEIC |
+| `invalid_key` | a keyed create's `key` breaks the charset/length law | 1-120 chars of letters, numbers, `: _ . @ / -` |
+| `invalid_secret_key` (client-side) | `gemmeinServer()` got a missing/`pk_` key | pass the `sk_` key from a server env var |
 
 Keys: `pk_` (public, domain-locked, browser-safe) vs `sk_` (secret, server only).

package/dist/index.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GemmeinServer = exports.CollectionClient = exports.StorageClient = exports.AuthClient = exports.Gemmein = exports.BrowserTokenStore = exports.MemoryTokenStore = exports.GemmeinError = void 0;
+exports.GemmeinServer = exports.CollectionClient = exports.StorageClient = exports.AccountClient = exports.PaymentsClient = exports.SubscriptionsClient = exports.AuthClient = exports.Gemmein = exports.BrowserTokenStore = exports.MemoryTokenStore = exports.GemmeinError = void 0;
 exports.gemmein = gemmein;
 exports.gemmeinServer = gemmeinServer;
 class GemmeinError extends Error {
@@ -64,9 +64,24 @@ function defaultTokenStore(appKey) {
     catch { /* SSR / Node / storage blocked */ }
     return new MemoryTokenStore();
 }
+/**
+ * The client — two layers:
+ *
+ *  - `g.collection("notes")` — YOUR app's collections. Records, files,
+ *    safety rules. This is where your app's own data model lives.
+ *  - Business primitives Gemmein runs for you: `g.auth` (sign-in),
+ *    `g.subscriptions` (who's on which plan), `g.payments` (one-off
+ *    purchases), `g.account` (the user's own account). These are
+ *    SELF-SERVICE surfaces for the signed-in user — reads and Stripe
+ *    hand-offs, never admin powers. Managing other people's users,
+ *    subscriptions, or records happens in the owner's dashboard
+ *    (app.gemmein.com), on purpose.
+ */
 class Gemmein {
     constructor(options) {
-        if (options.appKey?.startsWith("sk_")) {
+        // A missing key must land on the signpost below, not a TypeError —
+        // gemmein(undefined) is exactly the "env var didn't load" case.
+        if (options?.appKey?.startsWith("sk_")) {
             throw new GemmeinError({
                 status: 0,
                 code: "invalid_app_key",
@@ -74,7 +89,7 @@ class Gemmein {
             });
         }
         // The signpost: an AI building without a key gets routed, not stuck.
-        if (!options.appKey || !options.appKey.startsWith("pk_")) {
+        if (!options?.appKey || !options.appKey.startsWith("pk_")) {
             throw new GemmeinError({
                 status: 0,
                 code: "missing_app_key",
@@ -90,24 +105,16 @@ class Gemmein {
         };
         this.auth = new AuthClient(config);
         this.storage = new StorageClient(config);
-    }
-    /** The signed-in user's subscription — `(await g.subscription())?.plan === "pro"`. */
-    subscription() {
-        return this.auth.subscription();
-    }
-    /** Send the signed-in user to Stripe checkout for a plan — `g.checkout("pro")`. Redirects in browsers. */
-    checkout(plan) {
-        return this.auth.checkout(plan);
+        this.subscriptions = new SubscriptionsClient(config);
+        this.payments = new PaymentsClient(config);
+        this.account = new AccountClient(config);
     }
     /**
-     * Buy a one-off product — `g.pay("poster")`. Redirects in browsers. NOT
-     * for plans/subscriptions (that's `g.checkout`). The optional `item` note
-     * names WHAT is being bought when one product covers many things (e.g. a
-     * license tier across a catalog): `g.pay("premium license", { item: "beat_37" })`
-     * — it lands on the buyer's receipt record for the owner to fulfil.
+     * Your app's data — `g.collection<{ title: string }>("notes")`. The
+     * canonical spelling; `g.storage.collection(name)` is the same client.
      */
-    pay(product, options) {
-        return this.auth.pay(product, options);
+    collection(name) {
+        return this.storage.collection(name);
     }
 }
 exports.Gemmein = Gemmein;
@@ -159,24 +166,52 @@ class AuthClient {
             await this.config.tokenStore.clear();
         }
     }
-    async deleteAccount() {
-        const result = await this.request("/auth/delete-account", { method: "POST" });
-        await this.config.tokenStore.clear();
-        return result;
+    async currentUser() {
+        // Contract: "who am I?" never throws for session state — the server
+        // answers 200 {authenticated:false} for a token it won't honour right
+        // now, same as no token. We deliberately do NOT clear the stored token
+        // here: authenticated:false also covers a SUSPENDED user, whose session
+        // is intact and restored on unsuspend — clearing it would make a
+        // reversible suspension permanently sign them out. A genuinely expired
+        // token is harmless to keep (the next data-plane call 401s and the app
+        // re-auths); logout() and g.account.delete() are the deliberate clears.
+        //
+        // Moderation note: authenticated:false is deliberately SILENT about the
+        // why — signed out, suspended, and erased all read the same here, so a
+        // moderated user's state is never leaked to the client. Build the
+        // signed-out screen for all three.
+        return this.request("/auth/current-user");
+    }
+    request(path, init = {}) {
+        return runtimeRequest(this.config, path, init);
     }
-    async subscription() {
-        // SUBS-1: Gemmein manages the subscription record — one per customer,
-        // created by the payment itself. Read-only: gate features with
-        // `sub?.plan === "pro"`. Null when payments are off or this user has
-        // never paid; throws GemmeinError (401) when nobody is signed in — a
-        // data route, not the never-throw current-user contract. There is no
-        // client write path, by design.
-        const result = (await this.request("/auth/subscription"));
+}
+exports.AuthClient = AuthClient;
+/**
+ * SUBS: the subscription primitive, self-service side. Gemmein keeps
+ * exactly one subscription per customer — created by the payment itself,
+ * updated by Stripe's signed webhooks, overridable by the owner in their
+ * dashboard. The client surface is deliberately read-plus-checkout only:
+ * there is no client write path to plan or status, by design.
+ */
+class SubscriptionsClient {
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * The signed-in user's subscription — gate features with
+     * `(await g.subscriptions.mine())?.plan === "pro"`. Null when payments
+     * are off or this user has never paid; throws GemmeinError (401) when
+     * nobody is signed in — a data route, not the never-throw current-user
+     * contract.
+     */
+    async mine() {
+        const result = (await runtimeRequest(this.config, "/auth/subscription"));
         return result.subscription;
     }
     /**
-     * SUBS-2: start a Stripe checkout for a plan — Gemmein mints the URL with
-     * the signed-in buyer and the plan already wired in (never build checkout
+     * Start a Stripe checkout for a plan — Gemmein mints the URL with the
+     * signed-in buyer and the plan already wired in (never build checkout
      * URLs yourself; raw emails get silently dropped by Stripe's URL rules).
      * In a browser this redirects immediately; it also resolves with the URL
      * (for non-browser callers or custom handling). Requires a signed-in user
@@ -185,48 +220,61 @@ class AuthClient {
      */
     async checkout(plan) {
         const query = plan ? `?plan=${encodeURIComponent(plan)}` : "";
-        const result = (await this.request(`/auth/checkout${query}`));
+        const result = (await runtimeRequest(this.config, `/auth/checkout${query}`));
         if (typeof window !== "undefined" && window.location) {
             window.location.assign(result.url);
         }
         return result;
     }
+}
+exports.SubscriptionsClient = SubscriptionsClient;
+/** The one-off purchase primitive — things, not plans (plans are `g.subscriptions`). */
+class PaymentsClient {
+    constructor(config) {
+        this.config = config;
+    }
     /**
-     * PAY-1: buy a one-off product — same contract as checkout() but for
-     * things, not plans. A completed payment writes a receipt record addressed
-     * to the buyer in the owner's receipts collection; gate downloads/fulfilment
-     * on that receipt, never on the redirect coming back.
+     * Buy a one-off product — `g.payments.buy("poster")`. Redirects in
+     * browsers, and resolves with the URL. The optional `item` note names
+     * WHAT is being bought when one product covers many things (e.g. a
+     * license tier across a catalog):
+     * `g.payments.buy("premium license", { item: "beat_37" })`.
+     * A completed payment writes a receipt record addressed to the buyer in
+     * the owner's receipts collection; gate downloads/fulfilment on that
+     * receipt, never on the redirect coming back.
      */
-    async pay(product, options) {
+    async buy(product, options) {
         const params = new URLSearchParams({ product });
         if (options?.item)
             params.set("item", options.item);
-        const result = (await this.request(`/auth/pay?${params.toString()}`));
+        const result = (await runtimeRequest(this.config, `/auth/pay?${params.toString()}`));
         if (typeof window !== "undefined" && window.location) {
             window.location.assign(result.url);
         }
         return result;
     }
-    async currentUser() {
-        // Contract: "who am I?" never throws for session state — the server
-        // answers 200 {authenticated:false} for a token it won't honour right
-        // now, same as no token. We deliberately do NOT clear the stored token
-        // here: authenticated:false also covers a SUSPENDED user, whose session
-        // is intact and restored on unsuspend — clearing it would make a
-        // reversible suspension permanently sign them out. A genuinely expired
-        // token is harmless to keep (the next data-plane call 401s and the app
-        // re-auths); logout() and deleteAccount() are the deliberate clears.
-        return this.request("/auth/current-user");
+}
+exports.PaymentsClient = PaymentsClient;
+/** The signed-in user's own account — self-service, one deliberate power. */
+class AccountClient {
+    constructor(config) {
+        this.config = config;
     }
-    async request(path, init = {}) {
-        const response = await fetch(new URL(path, this.config.apiUrl), {
-            ...init,
-            headers: await runtimeHeaders(this.config, init.headers)
-        });
-        return handleResponse(response, this.config);
+    /**
+     * Self-service erasure — the "delete my account" screen. Every app it
+     * APPLIES to needs one (GDPR right to erasure; Apple 5.1.1(v) requires it
+     * for any app with account creation). Server-side this is the full
+     * cascade: sessions revoked, the user's records and files deleted, their
+     * subscription row removed. Irreversible — put a real confirm in front
+     * of it.
+     */
+    async delete() {
+        const result = await runtimeRequest(this.config, "/auth/delete-account", { method: "POST" });
+        await this.config.tokenStore.clear();
+        return result;
     }
 }
-exports.AuthClient = AuthClient;
+exports.AccountClient = AccountClient;
 function isSessionResponse(value) {
     return (typeof value === "object" &&
         value !== null &&
@@ -394,11 +442,15 @@ class CollectionClient {
 exports.CollectionClient = CollectionClient;
 class GemmeinServer {
     constructor(options) {
-        if (options.secretKey.startsWith("pk_")) {
+        // Same signpost law as the client: a missing key (env var didn't load)
+        // must be a typed error, never a TypeError.
+        if (!options?.secretKey || !options.secretKey.startsWith("sk_")) {
             throw new GemmeinError({
                 status: 0,
                 code: "invalid_secret_key",
-                message: "Public keys (pk_) must not be used with GemmeinServer — use the Gemmein client SDK instead"
+                message: options?.secretKey?.startsWith("pk_")
+                    ? "Public keys (pk_) must not be used with GemmeinServer — use the Gemmein client SDK instead"
+                    : 'GemmeinServer needs a secret key (it starts with "sk_") — create one in the dashboard at https://app.gemmein.com and pass it from a server env var'
             });
         }
         this.apiUrl = options.apiUrl ?? "https://api.gemmein.com";
@@ -546,6 +598,15 @@ async function readErrorBody(response) {
         message: `Gemmein request failed: ${response.status}`
     };
 }
+// One request path for every runtime client (auth, subscriptions,
+// payments, account) — same headers, same error handling, same signposts.
+async function runtimeRequest(config, path, init = {}) {
+    const response = await fetch(new URL(path, config.apiUrl), {
+        ...init,
+        headers: await runtimeHeaders(config, init.headers)
+    });
+    return handleResponse(response, config);
+}
 async function runtimeHeaders(config, headers) {
     const token = await config.tokenStore.get();
     return {

package/dist/index.d.cts

@@ -125,34 +125,31 @@ export declare class BrowserTokenStore implements TokenStore {
     set(token: string): void;
     clear(): void;
 }
+/**
+ * The client — two layers:
+ *
+ *  - `g.collection("notes")` — YOUR app's collections. Records, files,
+ *    safety rules. This is where your app's own data model lives.
+ *  - Business primitives Gemmein runs for you: `g.auth` (sign-in),
+ *    `g.subscriptions` (who's on which plan), `g.payments` (one-off
+ *    purchases), `g.account` (the user's own account). These are
+ *    SELF-SERVICE surfaces for the signed-in user — reads and Stripe
+ *    hand-offs, never admin powers. Managing other people's users,
+ *    subscriptions, or records happens in the owner's dashboard
+ *    (app.gemmein.com), on purpose.
+ */
 export declare class Gemmein {
     readonly auth: AuthClient;
     readonly storage: StorageClient;
+    readonly subscriptions: SubscriptionsClient;
+    readonly payments: PaymentsClient;
+    readonly account: AccountClient;
     constructor(options: GemmeinOptions);
-    /** The signed-in user's subscription — `(await g.subscription())?.plan === "pro"`. */
-    subscription(): Promise<{
-        plan: string;
-        status: "active" | "cancelled";
-    } | null>;
-    /** Send the signed-in user to Stripe checkout for a plan — `g.checkout("pro")`. Redirects in browsers. */
-    checkout(plan?: string): Promise<{
-        url: string;
-        plan: string;
-    }>;
     /**
-     * Buy a one-off product — `g.pay("poster")`. Redirects in browsers. NOT
-     * for plans/subscriptions (that's `g.checkout`). The optional `item` note
-     * names WHAT is being bought when one product covers many things (e.g. a
-     * license tier across a catalog): `g.pay("premium license", { item: "beat_37" })`
-     * — it lands on the buyer's receipt record for the owner to fulfil.
+     * Your app's data — `g.collection<{ title: string }>("notes")`. The
+     * canonical spelling; `g.storage.collection(name)` is the same client.
      */
-    pay(product: string, options?: {
-        item?: string;
-    }): Promise<{
-        url: string;
-        product: string;
-        item?: string;
-    }>;
+    collection<T extends Record<string, unknown> = Record<string, unknown>>(name: string): CollectionClient<T>;
 }
 export declare function gemmein(appKeyOrOptions: string | GemmeinOptions, options?: Omit<GemmeinOptions, "appKey">): Gemmein;
 export declare function gemmeinServer(secretKeyOrOptions: string | GemmeinServerOptions, options?: Omit<GemmeinServerOptions, "secretKey">): GemmeinServer;
@@ -170,14 +167,33 @@ export declare class AuthClient {
         code: string;
     }): Promise<AuthSession>;
     logout(): Promise<void>;
-    deleteAccount(): Promise<unknown>;
-    subscription(): Promise<{
+    currentUser(): Promise<CurrentUser>;
+    private request;
+}
+/**
+ * SUBS: the subscription primitive, self-service side. Gemmein keeps
+ * exactly one subscription per customer — created by the payment itself,
+ * updated by Stripe's signed webhooks, overridable by the owner in their
+ * dashboard. The client surface is deliberately read-plus-checkout only:
+ * there is no client write path to plan or status, by design.
+ */
+export declare class SubscriptionsClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    /**
+     * The signed-in user's subscription — gate features with
+     * `(await g.subscriptions.mine())?.plan === "pro"`. Null when payments
+     * are off or this user has never paid; throws GemmeinError (401) when
+     * nobody is signed in — a data route, not the never-throw current-user
+     * contract.
+     */
+    mine(): Promise<{
         plan: string;
         status: "active" | "cancelled";
     } | null>;
     /**
-     * SUBS-2: start a Stripe checkout for a plan — Gemmein mints the URL with
-     * the signed-in buyer and the plan already wired in (never build checkout
+     * Start a Stripe checkout for a plan — Gemmein mints the URL with the
+     * signed-in buyer and the plan already wired in (never build checkout
      * URLs yourself; raw emails get silently dropped by Stripe's URL rules).
      * In a browser this redirects immediately; it also resolves with the URL
      * (for non-browser callers or custom handling). Requires a signed-in user
@@ -188,21 +204,42 @@ export declare class AuthClient {
         url: string;
         plan: string;
     }>;
+}
+/** The one-off purchase primitive — things, not plans (plans are `g.subscriptions`). */
+export declare class PaymentsClient {
+    private readonly config;
+    constructor(config: ClientConfig);
     /**
-     * PAY-1: buy a one-off product — same contract as checkout() but for
-     * things, not plans. A completed payment writes a receipt record addressed
-     * to the buyer in the owner's receipts collection; gate downloads/fulfilment
-     * on that receipt, never on the redirect coming back.
+     * Buy a one-off product — `g.payments.buy("poster")`. Redirects in
+     * browsers, and resolves with the URL. The optional `item` note names
+     * WHAT is being bought when one product covers many things (e.g. a
+     * license tier across a catalog):
+     * `g.payments.buy("premium license", { item: "beat_37" })`.
+     * A completed payment writes a receipt record addressed to the buyer in
+     * the owner's receipts collection; gate downloads/fulfilment on that
+     * receipt, never on the redirect coming back.
      */
-    pay(product: string, options?: {
+    buy(product: string, options?: {
         item?: string;
     }): Promise<{
         url: string;
         product: string;
         item?: string;
     }>;
-    currentUser(): Promise<CurrentUser>;
-    private request;
+}
+/** The signed-in user's own account — self-service, one deliberate power. */
+export declare class AccountClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    /**
+     * Self-service erasure — the "delete my account" screen. Every app it
+     * APPLIES to needs one (GDPR right to erasure; Apple 5.1.1(v) requires it
+     * for any app with account creation). Server-side this is the full
+     * cascade: sessions revoked, the user's records and files deleted, their
+     * subscription row removed. Irreversible — put a real confirm in front
+     * of it.
+     */
+    delete(): Promise<unknown>;
 }
 export declare class StorageClient {
     private readonly config;

package/dist/index.d.ts

@@ -125,34 +125,31 @@ export declare class BrowserTokenStore implements TokenStore {
     set(token: string): void;
     clear(): void;
 }
+/**
+ * The client — two layers:
+ *
+ *  - `g.collection("notes")` — YOUR app's collections. Records, files,
+ *    safety rules. This is where your app's own data model lives.
+ *  - Business primitives Gemmein runs for you: `g.auth` (sign-in),
+ *    `g.subscriptions` (who's on which plan), `g.payments` (one-off
+ *    purchases), `g.account` (the user's own account). These are
+ *    SELF-SERVICE surfaces for the signed-in user — reads and Stripe
+ *    hand-offs, never admin powers. Managing other people's users,
+ *    subscriptions, or records happens in the owner's dashboard
+ *    (app.gemmein.com), on purpose.
+ */
 export declare class Gemmein {
     readonly auth: AuthClient;
     readonly storage: StorageClient;
+    readonly subscriptions: SubscriptionsClient;
+    readonly payments: PaymentsClient;
+    readonly account: AccountClient;
     constructor(options: GemmeinOptions);
-    /** The signed-in user's subscription — `(await g.subscription())?.plan === "pro"`. */
-    subscription(): Promise<{
-        plan: string;
-        status: "active" | "cancelled";
-    } | null>;
-    /** Send the signed-in user to Stripe checkout for a plan — `g.checkout("pro")`. Redirects in browsers. */
-    checkout(plan?: string): Promise<{
-        url: string;
-        plan: string;
-    }>;
     /**
-     * Buy a one-off product — `g.pay("poster")`. Redirects in browsers. NOT
-     * for plans/subscriptions (that's `g.checkout`). The optional `item` note
-     * names WHAT is being bought when one product covers many things (e.g. a
-     * license tier across a catalog): `g.pay("premium license", { item: "beat_37" })`
-     * — it lands on the buyer's receipt record for the owner to fulfil.
+     * Your app's data — `g.collection<{ title: string }>("notes")`. The
+     * canonical spelling; `g.storage.collection(name)` is the same client.
      */
-    pay(product: string, options?: {
-        item?: string;
-    }): Promise<{
-        url: string;
-        product: string;
-        item?: string;
-    }>;
+    collection<T extends Record<string, unknown> = Record<string, unknown>>(name: string): CollectionClient<T>;
 }
 export declare function gemmein(appKeyOrOptions: string | GemmeinOptions, options?: Omit<GemmeinOptions, "appKey">): Gemmein;
 export declare function gemmeinServer(secretKeyOrOptions: string | GemmeinServerOptions, options?: Omit<GemmeinServerOptions, "secretKey">): GemmeinServer;
@@ -170,14 +167,33 @@ export declare class AuthClient {
         code: string;
     }): Promise<AuthSession>;
     logout(): Promise<void>;
-    deleteAccount(): Promise<unknown>;
-    subscription(): Promise<{
+    currentUser(): Promise<CurrentUser>;
+    private request;
+}
+/**
+ * SUBS: the subscription primitive, self-service side. Gemmein keeps
+ * exactly one subscription per customer — created by the payment itself,
+ * updated by Stripe's signed webhooks, overridable by the owner in their
+ * dashboard. The client surface is deliberately read-plus-checkout only:
+ * there is no client write path to plan or status, by design.
+ */
+export declare class SubscriptionsClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    /**
+     * The signed-in user's subscription — gate features with
+     * `(await g.subscriptions.mine())?.plan === "pro"`. Null when payments
+     * are off or this user has never paid; throws GemmeinError (401) when
+     * nobody is signed in — a data route, not the never-throw current-user
+     * contract.
+     */
+    mine(): Promise<{
         plan: string;
         status: "active" | "cancelled";
     } | null>;
     /**
-     * SUBS-2: start a Stripe checkout for a plan — Gemmein mints the URL with
-     * the signed-in buyer and the plan already wired in (never build checkout
+     * Start a Stripe checkout for a plan — Gemmein mints the URL with the
+     * signed-in buyer and the plan already wired in (never build checkout
      * URLs yourself; raw emails get silently dropped by Stripe's URL rules).
      * In a browser this redirects immediately; it also resolves with the URL
      * (for non-browser callers or custom handling). Requires a signed-in user
@@ -188,21 +204,42 @@ export declare class AuthClient {
         url: string;
         plan: string;
     }>;
+}
+/** The one-off purchase primitive — things, not plans (plans are `g.subscriptions`). */
+export declare class PaymentsClient {
+    private readonly config;
+    constructor(config: ClientConfig);
     /**
-     * PAY-1: buy a one-off product — same contract as checkout() but for
-     * things, not plans. A completed payment writes a receipt record addressed
-     * to the buyer in the owner's receipts collection; gate downloads/fulfilment
-     * on that receipt, never on the redirect coming back.
+     * Buy a one-off product — `g.payments.buy("poster")`. Redirects in
+     * browsers, and resolves with the URL. The optional `item` note names
+     * WHAT is being bought when one product covers many things (e.g. a
+     * license tier across a catalog):
+     * `g.payments.buy("premium license", { item: "beat_37" })`.
+     * A completed payment writes a receipt record addressed to the buyer in
+     * the owner's receipts collection; gate downloads/fulfilment on that
+     * receipt, never on the redirect coming back.
      */
-    pay(product: string, options?: {
+    buy(product: string, options?: {
         item?: string;
     }): Promise<{
         url: string;
         product: string;
         item?: string;
     }>;
-    currentUser(): Promise<CurrentUser>;
-    private request;
+}
+/** The signed-in user's own account — self-service, one deliberate power. */
+export declare class AccountClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    /**
+     * Self-service erasure — the "delete my account" screen. Every app it
+     * APPLIES to needs one (GDPR right to erasure; Apple 5.1.1(v) requires it
+     * for any app with account creation). Server-side this is the full
+     * cascade: sessions revoked, the user's records and files deleted, their
+     * subscription row removed. Irreversible — put a real confirm in front
+     * of it.
+     */
+    delete(): Promise<unknown>;
 }
 export declare class StorageClient {
     private readonly config;

package/dist/index.js

@@ -56,9 +56,24 @@ function defaultTokenStore(appKey) {
     catch { /* SSR / Node / storage blocked */ }
     return new MemoryTokenStore();
 }
+/**
+ * The client — two layers:
+ *
+ *  - `g.collection("notes")` — YOUR app's collections. Records, files,
+ *    safety rules. This is where your app's own data model lives.
+ *  - Business primitives Gemmein runs for you: `g.auth` (sign-in),
+ *    `g.subscriptions` (who's on which plan), `g.payments` (one-off
+ *    purchases), `g.account` (the user's own account). These are
+ *    SELF-SERVICE surfaces for the signed-in user — reads and Stripe
+ *    hand-offs, never admin powers. Managing other people's users,
+ *    subscriptions, or records happens in the owner's dashboard
+ *    (app.gemmein.com), on purpose.
+ */
 export class Gemmein {
     constructor(options) {
-        if (options.appKey?.startsWith("sk_")) {
+        // A missing key must land on the signpost below, not a TypeError —
+        // gemmein(undefined) is exactly the "env var didn't load" case.
+        if (options?.appKey?.startsWith("sk_")) {
             throw new GemmeinError({
                 status: 0,
                 code: "invalid_app_key",
@@ -66,7 +81,7 @@ export class Gemmein {
             });
         }
         // The signpost: an AI building without a key gets routed, not stuck.
-        if (!options.appKey || !options.appKey.startsWith("pk_")) {
+        if (!options?.appKey || !options.appKey.startsWith("pk_")) {
             throw new GemmeinError({
                 status: 0,
                 code: "missing_app_key",
@@ -82,24 +97,16 @@ export class Gemmein {
         };
         this.auth = new AuthClient(config);
         this.storage = new StorageClient(config);
-    }
-    /** The signed-in user's subscription — `(await g.subscription())?.plan === "pro"`. */
-    subscription() {
-        return this.auth.subscription();
-    }
-    /** Send the signed-in user to Stripe checkout for a plan — `g.checkout("pro")`. Redirects in browsers. */
-    checkout(plan) {
-        return this.auth.checkout(plan);
+        this.subscriptions = new SubscriptionsClient(config);
+        this.payments = new PaymentsClient(config);
+        this.account = new AccountClient(config);
     }
     /**
-     * Buy a one-off product — `g.pay("poster")`. Redirects in browsers. NOT
-     * for plans/subscriptions (that's `g.checkout`). The optional `item` note
-     * names WHAT is being bought when one product covers many things (e.g. a
-     * license tier across a catalog): `g.pay("premium license", { item: "beat_37" })`
-     * — it lands on the buyer's receipt record for the owner to fulfil.
+     * Your app's data — `g.collection<{ title: string }>("notes")`. The
+     * canonical spelling; `g.storage.collection(name)` is the same client.
      */
-    pay(product, options) {
-        return this.auth.pay(product, options);
+    collection(name) {
+        return this.storage.collection(name);
     }
 }
 // Factory forms — what the copied prompts teach. `gemmein("pk_...")` reads
@@ -150,24 +157,51 @@ export class AuthClient {
             await this.config.tokenStore.clear();
         }
     }
-    async deleteAccount() {
-        const result = await this.request("/auth/delete-account", { method: "POST" });
-        await this.config.tokenStore.clear();
-        return result;
+    async currentUser() {
+        // Contract: "who am I?" never throws for session state — the server
+        // answers 200 {authenticated:false} for a token it won't honour right
+        // now, same as no token. We deliberately do NOT clear the stored token
+        // here: authenticated:false also covers a SUSPENDED user, whose session
+        // is intact and restored on unsuspend — clearing it would make a
+        // reversible suspension permanently sign them out. A genuinely expired
+        // token is harmless to keep (the next data-plane call 401s and the app
+        // re-auths); logout() and g.account.delete() are the deliberate clears.
+        //
+        // Moderation note: authenticated:false is deliberately SILENT about the
+        // why — signed out, suspended, and erased all read the same here, so a
+        // moderated user's state is never leaked to the client. Build the
+        // signed-out screen for all three.
+        return this.request("/auth/current-user");
+    }
+    request(path, init = {}) {
+        return runtimeRequest(this.config, path, init);
+    }
+}
+/**
+ * SUBS: the subscription primitive, self-service side. Gemmein keeps
+ * exactly one subscription per customer — created by the payment itself,
+ * updated by Stripe's signed webhooks, overridable by the owner in their
+ * dashboard. The client surface is deliberately read-plus-checkout only:
+ * there is no client write path to plan or status, by design.
+ */
+export class SubscriptionsClient {
+    constructor(config) {
+        this.config = config;
     }
-    async subscription() {
-        // SUBS-1: Gemmein manages the subscription record — one per customer,
-        // created by the payment itself. Read-only: gate features with
-        // `sub?.plan === "pro"`. Null when payments are off or this user has
-        // never paid; throws GemmeinError (401) when nobody is signed in — a
-        // data route, not the never-throw current-user contract. There is no
-        // client write path, by design.
-        const result = (await this.request("/auth/subscription"));
+    /**
+     * The signed-in user's subscription — gate features with
+     * `(await g.subscriptions.mine())?.plan === "pro"`. Null when payments
+     * are off or this user has never paid; throws GemmeinError (401) when
+     * nobody is signed in — a data route, not the never-throw current-user
+     * contract.
+     */
+    async mine() {
+        const result = (await runtimeRequest(this.config, "/auth/subscription"));
         return result.subscription;
     }
     /**
-     * SUBS-2: start a Stripe checkout for a plan — Gemmein mints the URL with
-     * the signed-in buyer and the plan already wired in (never build checkout
+     * Start a Stripe checkout for a plan — Gemmein mints the URL with the
+     * signed-in buyer and the plan already wired in (never build checkout
      * URLs yourself; raw emails get silently dropped by Stripe's URL rules).
      * In a browser this redirects immediately; it also resolves with the URL
      * (for non-browser callers or custom handling). Requires a signed-in user
@@ -176,45 +210,56 @@ export class AuthClient {
      */
     async checkout(plan) {
         const query = plan ? `?plan=${encodeURIComponent(plan)}` : "";
-        const result = (await this.request(`/auth/checkout${query}`));
+        const result = (await runtimeRequest(this.config, `/auth/checkout${query}`));
         if (typeof window !== "undefined" && window.location) {
             window.location.assign(result.url);
         }
         return result;
     }
+}
+/** The one-off purchase primitive — things, not plans (plans are `g.subscriptions`). */
+export class PaymentsClient {
+    constructor(config) {
+        this.config = config;
+    }
     /**
-     * PAY-1: buy a one-off product — same contract as checkout() but for
-     * things, not plans. A completed payment writes a receipt record addressed
-     * to the buyer in the owner's receipts collection; gate downloads/fulfilment
-     * on that receipt, never on the redirect coming back.
+     * Buy a one-off product — `g.payments.buy("poster")`. Redirects in
+     * browsers, and resolves with the URL. The optional `item` note names
+     * WHAT is being bought when one product covers many things (e.g. a
+     * license tier across a catalog):
+     * `g.payments.buy("premium license", { item: "beat_37" })`.
+     * A completed payment writes a receipt record addressed to the buyer in
+     * the owner's receipts collection; gate downloads/fulfilment on that
+     * receipt, never on the redirect coming back.
      */
-    async pay(product, options) {
+    async buy(product, options) {
         const params = new URLSearchParams({ product });
         if (options?.item)
             params.set("item", options.item);
-        const result = (await this.request(`/auth/pay?${params.toString()}`));
+        const result = (await runtimeRequest(this.config, `/auth/pay?${params.toString()}`));
         if (typeof window !== "undefined" && window.location) {
             window.location.assign(result.url);
         }
         return result;
     }
-    async currentUser() {
-        // Contract: "who am I?" never throws for session state — the server
-        // answers 200 {authenticated:false} for a token it won't honour right
-        // now, same as no token. We deliberately do NOT clear the stored token
-        // here: authenticated:false also covers a SUSPENDED user, whose session
-        // is intact and restored on unsuspend — clearing it would make a
-        // reversible suspension permanently sign them out. A genuinely expired
-        // token is harmless to keep (the next data-plane call 401s and the app
-        // re-auths); logout() and deleteAccount() are the deliberate clears.
-        return this.request("/auth/current-user");
+}
+/** The signed-in user's own account — self-service, one deliberate power. */
+export class AccountClient {
+    constructor(config) {
+        this.config = config;
     }
-    async request(path, init = {}) {
-        const response = await fetch(new URL(path, this.config.apiUrl), {
-            ...init,
-            headers: await runtimeHeaders(this.config, init.headers)
-        });
-        return handleResponse(response, this.config);
+    /**
+     * Self-service erasure — the "delete my account" screen. Every app it
+     * APPLIES to needs one (GDPR right to erasure; Apple 5.1.1(v) requires it
+     * for any app with account creation). Server-side this is the full
+     * cascade: sessions revoked, the user's records and files deleted, their
+     * subscription row removed. Irreversible — put a real confirm in front
+     * of it.
+     */
+    async delete() {
+        const result = await runtimeRequest(this.config, "/auth/delete-account", { method: "POST" });
+        await this.config.tokenStore.clear();
+        return result;
     }
 }
 function isSessionResponse(value) {
@@ -382,11 +427,15 @@ export class CollectionClient {
 }
 export class GemmeinServer {
     constructor(options) {
-        if (options.secretKey.startsWith("pk_")) {
+        // Same signpost law as the client: a missing key (env var didn't load)
+        // must be a typed error, never a TypeError.
+        if (!options?.secretKey || !options.secretKey.startsWith("sk_")) {
             throw new GemmeinError({
                 status: 0,
                 code: "invalid_secret_key",
-                message: "Public keys (pk_) must not be used with GemmeinServer — use the Gemmein client SDK instead"
+                message: options?.secretKey?.startsWith("pk_")
+                    ? "Public keys (pk_) must not be used with GemmeinServer — use the Gemmein client SDK instead"
+                    : 'GemmeinServer needs a secret key (it starts with "sk_") — create one in the dashboard at https://app.gemmein.com and pass it from a server env var'
             });
         }
         this.apiUrl = options.apiUrl ?? "https://api.gemmein.com";
@@ -533,6 +582,15 @@ async function readErrorBody(response) {
         message: `Gemmein request failed: ${response.status}`
     };
 }
+// One request path for every runtime client (auth, subscriptions,
+// payments, account) — same headers, same error handling, same signposts.
+async function runtimeRequest(config, path, init = {}) {
+    const response = await fetch(new URL(path, config.apiUrl), {
+        ...init,
+        headers: await runtimeHeaders(config, init.headers)
+    });
+    return handleResponse(response, config);
+}
 async function runtimeHeaders(config, headers) {
     const token = await config.tokenStore.get();
     return {

package/llms.txt

@@ -36,8 +36,10 @@
   safety rule:
   - `private` — each signed-in user sees and edits only their own records
     (right for notes, tasks, anything personal).
-  - `shared` — every signed-in user can read AND write every record (right
-    for a team board everyone edits; WRONG for personal data — it leaks).
+  - `shared` — every signed-in user reads every record and adds their own;
+    each user edits/deletes ONLY the records they created (a non-author
+    write comes back 404, same as any record you can't touch). Right for a
+    team feed everyone posts to; WRONG for personal data — it leaks.
   - `admin_write` — everyone signed in can read, only the owner can write
     (right for announcements and settings your human curates).
   - `public_read` — readable without signing in, ONLY the app owner writes
@@ -105,7 +107,7 @@
   construction, and your own retry returns it.
 - Images & files: NEVER base64 into record data and NEVER wire up your own
   storage bucket — uploads are built in:
-  `const file = await g.storage.collection("posts").upload(blob, { name })`
+  `const file = await g.collection("posts").upload(blob, { name })`
   → `{ id, url, contentType, sizeBytes }`. Store `file.url` in a record
   field like any text (that's also how a record "has" an image — the
   reference pattern, same as links). Upload permission follows the
@@ -154,27 +156,27 @@
   to your human's Gemmein dashboard — they click the record there.
 - Payments: the builder names plans in the dashboard, pastes one Stripe
   signing secret, and pastes each paid plan's Stripe Payment Link there too.
-  The app's ONLY checkout job is `await g.checkout("pro")` on the upgrade
+  The app's ONLY checkout job is `await g.subscriptions.checkout("pro")` on the upgrade
   button — Gemmein sends the signed-in user to the right Stripe checkout
   with the buyer and plan wired in. Never build checkout URLs, sessions, or
   Payment-Link redirects yourself (raw emails get silently dropped by
   Stripe's URL rules, and sessions need a secret key that must never ship
-  client-side). If g.checkout errors with `plan_has_no_link`, ask your human
+  client-side). If g.subscriptions.checkout errors with `plan_has_no_link`, ask your human
   to paste that plan's Payment Link in their dashboard. Plan LIMITS (note
   counts, feature caps) are your app's logic — Gemmein only tells you who is
   on which plan. Gemmein keeps exactly one
   subscription per customer (enforced by the engine, case-insensitive on
   email); cancellations downgrade to the default plan automatically; events
   arriving out of order resolve to the newest. The app reads
-  `await g.subscription()` → `{ plan, status }` or null, and gates features
+  `await g.subscriptions.mine()` → `{ plan, status }` or null, and gates features
   with `sub?.plan === "pro"`.
 - Selling THINGS (one-off purchases — a poster, a beat, an ebook): plans are
   for subscriptions; products are for things. The builder adds products
   (name + Stripe Payment Link) on the same Payments page and picks a
   receipts collection (rule `addressed`). The app calls
-  `await g.pay("poster")` — or, when one product covers many items (license
+  `await g.payments.buy("poster")` — or, when one product covers many items (license
   tiers over a catalog), names the item:
-  `await g.pay("premium license", { item: "beat_37" })` (display text on
+  `await g.payments.buy("premium license", { item: "beat_37" })` (display text on
   the receipt; the PRICE always comes from the product's Payment Link, so
   the item note can never change what's paid). The completed payment writes
   a receipt record ADDRESSED to the buyer: only they and the owner read it.
@@ -196,8 +198,10 @@
   `update(id, {}, { published: true })`. NEVER fake drafts with a status
   field + client-side filtering on a public collection — the data still
   reaches every reader's network tab (silent-until-breach). `published` is
-  an option, not a data field: the server rejects it inside `data`
-  (invalid_publish), and it only exists on the two public rules.
+  an option, not a data field: putting it inside `data` is refused as a
+  reserved server-managed field (403 forbidden), passing the OPTION on a
+  non-public rule is 400 invalid_publish — it only exists on the two
+  public rules.
 - Denials are 404-shaped: touching a record your session can't see returns
   404 not_found, never a 403 that confirms it exists — existence is not
   leaked. A real 403 comes back as code `forbidden` and names a rule problem
@@ -213,6 +217,17 @@
   id/updatedAt), not under `.data`. Non-authors only ever receive published
   records, so you see `false` only on your own drafts (or on everything, as
   the owner) — that's how you badge "unreleased" in an owner admin view.
+- Account lifecycle — the bare-minimum screens a compliant app implements:
+  (1) sign-in (the email-code flow above); (2) a signed-out state — note that
+  `currentUser()` answering `authenticated: false` is deliberately silent
+  about WHY (signed out, suspended by the owner, and erased all read the
+  same; a moderated user's state is never leaked to the client, so one
+  signed-out screen covers all three); (3) a "delete my account" screen —
+  `await g.account.delete()` — for every app it APPLIES to (GDPR right to
+  erasure; Apple 5.1.1(v) for apps with account creation). It's the full
+  server-side cascade (sessions, records, files, subscription row) and
+  irreversible — put a real confirm in front of it. Suspensions, bans, and
+  owner-side erasure are dashboard actions, not SDK calls.
 - Secret keys (`sk_`) must never appear in browser code; app keys (`pk_`)
   are public and domain-locked.
 
@@ -223,7 +238,7 @@ rule. The specifics:
 
 - Collection names are **lowercase letters, numbers, and underscores only**
   (`saved_games`, `user_notes` — never `savedGames`). A bad name throws
-  synchronously from `g.storage.collection(name)`; if you call that at module
+  synchronously from `g.collection(name)`; if you call that at module
   load, it can blank your whole app with no browser-console error. Name them
   right.
 - The signed-in user: `await g.auth.currentUser()` →
@@ -243,7 +258,7 @@ rule. The specifics:
   shared, direct**. Asking to expand a field on a `private`, `public_read`, or
   `admin_write` collection throws (it has no link shape); join those in memory
   instead.
-- `g.checkout(plan)` and `g.pay(product, { item? })` both **navigate the
+- `g.subscriptions.checkout(plan)` and `g.payments.buy(product, { item? })` both **navigate the
   browser to Stripe themselves** (via `window.location`) *and* resolve with
   `{ url, ... }`. Just `await` them on the click — don't also redirect to the
   returned `url` (you'll double-navigate), and don't build the URL yourself.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Gemmein SDK \u2014 passwordless auth, safe storage, and Stripe-driven record flips for AI-built apps. Small enough that one prompt teaches the whole API.",
   "license": "MIT",
   "type": "module",
@@ -12,7 +12,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
-    }
+    },
+    "./llms.txt": "./llms.txt",
+    "./REFERENCE.md": "./REFERENCE.md",
+    "./reaffirm.mjs": "./reaffirm.mjs",
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",

package/reaffirm.mjs

@@ -39,13 +39,13 @@ const asUser = (token) => gemmein(PK, { ...opts, tokenStore: {
   get: async () => token, set: async () => {}, clear: async () => {} } });
 
 // ── TIER A — functional + anonymous. No login; safe against live. ───────────
-g.storage.collection(PRIVATE_COLLECTION);              // a misnamed collection throws HERE, loudly
+g.collection(PRIVATE_COLLECTION);              // a misnamed collection throws HERE, loudly
 await refuse("anon can't read the private collection", "denied",
-  () => g.storage.collection(PRIVATE_COLLECTION).list());
+  () => g.collection(PRIVATE_COLLECTION).list());
 await refuse("anon can't write the private collection", "denied",
-  () => g.storage.collection(PRIVATE_COLLECTION).create({ probe: "x" }));
+  () => g.collection(PRIVATE_COLLECTION).create({ probe: "x" }));
 if (PUBLIC_COLLECTION) {
-  const open = await g.storage.collection(PUBLIC_COLLECTION).list();
+  const open = await g.collection(PUBLIC_COLLECTION).list();
   console.log(`ℹ "${PUBLIC_COLLECTION}" is public by rule — ${open.records.length} records visible to ANYONE. Never put secrets in it.`);
 }
 
@@ -55,10 +55,10 @@ if (SK && !SK.startsWith("sk_live")) {
   const [a, b] = await Promise.all(TEST_USERS.map((e) => srv.testSession(e)));
   const A = asUser(a.token), B = asUser(b.token);
 
-  const note = await A.storage.collection(PRIVATE_COLLECTION).create({ probe: "a-secret" });
+  const note = await A.collection(PRIVATE_COLLECTION).create({ probe: "a-secret" });
   await refuse("B can't read A's private record", "not_found",
-    () => B.storage.collection(PRIVATE_COLLECTION).get(note.id));
-  const bSees = await B.storage.collection(PRIVATE_COLLECTION).list();
+    () => B.collection(PRIVATE_COLLECTION).get(note.id));
+  const bSees = await B.collection(PRIVATE_COLLECTION).list();
   check("B's private list contains none of A's records",
     !bSees.records.some((r) => r.id === note.id));
 
@@ -66,7 +66,7 @@ if (SK && !SK.startsWith("sk_live")) {
   check("currentUser() exposes userId (not id)", !!who.userId);
   check("record fields live under .data", note.data?.probe === "a-secret");
 
-  await A.storage.collection(PRIVATE_COLLECTION).delete(note.id);   // leave dev tidy
+  await A.collection(PRIVATE_COLLECTION).delete(note.id);   // leave dev tidy
 } else {
   console.log(SK ? "· Tier B skipped — sk_live can never mint test sessions (by design)"
                  : "· Tier B skipped — set SECRET_KEY (sk_dev) to prove cross-user isolation");