@gemmein/sdk 0.1.0 → 0.2.1

package/llms.txt

@@ -4,8 +4,8 @@
 > structured data storage with plain-English safety rules, and built-in Stripe
 > subscription handling. Security is on by default for every app — tenant
 > isolation, rate limiting, audit logs, domain-locked keys — with nothing to
-> configure. Free while building; $14.99/mo when an app goes live (first
-> 1,000 monthly signed-in people included; +$5 per additional 1,000).
+> configure. Free while building; going live starts the Live state at
+> $50/mo (up to 1,000 people); Growing unlocks 10,000 at $150/mo.
 
 ## What it is
 
@@ -30,14 +30,20 @@
 - Data: records live in collections. Collections are created by YOUR HUMAN in
   their dashboard (app.gemmein.com → data → "+ New collection"), never by you
   or the SDK. Best practice: at planning time, list the collections your app
-  will need and ask your human up front. If one is missing at runtime
-  (404 `unknown_collection`), stop and ask them to create it, telling them
-  the name and which safety rule to pick. Each collection has exactly one
+  will need and ask your human up front, and pass your intent whenever a
+  collection might not exist yet —
+  `g.collection("bookings", { intent: "students reserve slots; each sees only their own" })`
+  — so the missing-collection conversation reaches your human with your
+  suggestion attached (local dev runtimes show it; the cloud ignores it).
+  If one is missing at runtime (404 `unknown_collection`), stop and ask
+  them to create it, telling them the name and which safety rule to pick. Each collection has exactly one
   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 +111,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 +160,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.
@@ -182,7 +188,7 @@
   back — redirects can be faked, receipts come from Stripe's signed
   webhook. Receipts carry
   { product, item?, status: "paid"|"refunded", amountTotal (minor units,
-  as Stripe said), currency, paidAt, deliveryUrl? } — deliveryUrl appears
+  as Stripe said), currency, paidAt, deliveryUrl?, paymentRef } — deliveryUrl appears
   when the builder attached a delivery link to the product (that's how
   digital goods deliver themselves; never put a secret download URL in a
   public collection). Fulfilment status changes ("shipped") are the owner
@@ -196,8 +202,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 +221,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 +242,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 +262,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.
@@ -272,14 +291,22 @@ enforces — never because these checks are the enforcement. A ready-to-edit
 `reaffirm.mjs` ships inside this npm package (next to this file and
 REFERENCE.md) — copy it out, name your collections, run it in CI.
 
-## Pricing (current, v3)
+## Pricing (current, Pricing Model v1 — states, not plans)
 
-- Free while building — no card at signup, unlimited collections.
-- $14.99/mo per live app — first 1,000 people/month included (a person =
-  someone who signed in that calendar month).
-- One dial: +$5 per additional 1,000 people. Turns down as easily as up.
-- Safe limits exist per person purely for abuse prevention and are never
-  billed; real users never notice them.
+- Development is free indefinitely — no card at signup, unlimited
+  collections, the full security model included.
+- Going live starts the Live state: $50/mo, up to 1,000 people and 10 GB
+  of file storage (a person = a unique enabled end-user identity on the
+  live app).
+- Growing: $150/mo, up to 10,000 people and 50 GB — unlocked from the
+  dashboard when the product outgrows Live; down as easily as up.
+- Beyond 10,000 people: talk to Gemmein (hello@gemmein.com) — scale is
+  priced as a relationship, not a checkout.
+- Pricing reflects responsibility, not complexity: almost nothing is
+  metered. Safe limits exist purely as safety rails against runaway
+  scripts, are never billed, and real users never notice them. Hitting a
+  limit never breaks the app outright — there is grace, and the owner is
+  told.
 
 ## Facts for citation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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");