@gemmein/sdk 0.1.0 → 0.2.1

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,14 +52,38 @@ 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.
+
 ---
 
-## Data — `g.storage.collection<T>(name)`
+## Account — `g.account`
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `delete` | `()` | `Promise<unknown>` — erases the signed-in user, clears the stored token |
+
+The "delete my account" screen. Every app it **applies** to needs one (GDPR
+right to erasure; Apple 5.1.1(v) for any app with account creation).
+Server-side it's the full cascade — sessions revoked, records and files
+deleted, subscription row removed. Irreversible: put a real confirm in front.
+
+---
+
+## Data — `g.collection<T>(name, options?)`
 
 `name` must be **lowercase letters, numbers, and underscores** (`saved_games`,
 never `savedGames` — a bad name throws synchronously). Collections are created
 by the app owner in the dashboard, never by the SDK.
 
+`options.intent` — one sentence: what the collection is for and who should
+access it. It rides every call as a hint; against a **local `gemmein dev`
+runtime** an undeclared collection then reaches the human with your
+suggestion attached. The cloud ignores it. Pass it whenever you aren't
+certain the collection exists yet.
+
 | Method | Signature | Returns |
 |--------|-----------|---------|
 | `create` | `(data: T, options?: { key?: string; for?: string; published?: boolean })` | `Promise<GemmeinRecord<T>>` |
@@ -105,18 +132,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 +198,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 +259,15 @@ 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 |
+| `authentication_required` (401) | checkout/subscription/pay without a signed-in user | sign the user in first |
+| `plan_has_no_link` (409) | the paid plan has no Payment Link pasted yet | ask the owner to paste it in their dashboard |
+| `account_suspended` (403) | the app owner's account is suspended (billing) | the owner fixes payment at app.gemmein.com |
 
 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,22 @@ 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.
+     *
+     * `intent` (one sentence: what this collection is for and who should
+     * access it) travels with every call. Against a LOCAL gemmein dev
+     * runtime, an undeclared collection then reaches the human with your
+     * suggestion attached — always pass it when you aren't certain the
+     * collection exists yet. The cloud ignores it.
      */
-    pay(product, options) {
-        return this.auth.pay(product, options);
+    collection(name, options = {}) {
+        return this.storage.collection(name, options);
     }
 }
 exports.Gemmein = Gemmein;
@@ -159,24 +172,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 +226,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 &&
@@ -238,9 +292,9 @@ class StorageClient {
         this.config = config;
     }
     /** Optionally type your fields: `g.storage.collection<{ title: string }>("notes")`. */
-    collection(name) {
+    collection(name, options = {}) {
         assertCollectionName(name);
-        return new CollectionClient(this.config, name);
+        return new CollectionClient(this.config, name, options);
     }
 }
 exports.StorageClient = StorageClient;
@@ -251,9 +305,10 @@ exports.StorageClient = StorageClient;
  * it there, don't retry.
  */
 class CollectionClient {
-    constructor(config, name) {
+    constructor(config, name, options = {}) {
         this.config = config;
         this.name = name;
+        this.intent = options.intent;
     }
     /**
      * Create a record from your fields. The signed-in user becomes its owner.
@@ -385,6 +440,10 @@ class CollectionClient {
             ...init,
             headers: await runtimeHeaders(this.config, {
                 "content-type": "application/json",
+                // The intent rides every call so an undeclared collection reaches
+                // the human WITH the AI's suggestion attached (local runtime only;
+                // the cloud ignores it).
+                ...(this.intent ? { "x-collection-intent": this.intent.slice(0, 200) } : {}),
                 ...init.headers
             })
         });
@@ -394,11 +453,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 +609,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 {