@gemmein/sdk 0.4.6 → 0.4.7

package/REFERENCE.md

@@ -79,6 +79,8 @@ deleted, subscription row removed. Irreversible: put a real confirm in front.
 `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.
+Names JavaScript owns (`constructor`, `toString`, `__proto__`…) are refused as
+collection and field names — a plain object inherits them.
 
 `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`
@@ -189,13 +191,20 @@ type ListOptions = {
 ```
 
 **Options notes.** `key` = create-if-absent (a second writer gets 409
-`conflict`; your own retry returns the record with `existing: true`). `for` =
+`conflict`; your own retry returns the record with `existing: true`). The
+retry doubles as the lookup: there is no separate get-by-key call — re-issue
+the same `create()` with the same key to fetch your own record (it counts
+as a write; a re-fetch idiom, not a read path). `for` =
 recipient id on `addressed`/`direct`. `published: false` = draft on a public
 rule. `ifVersion` = optimistic concurrency. Atomic counters go in *value*
 position: `update(id, { stock: { decrement: 1, floor: 0 } })`. `expand` throws
 on `private`/`public_read`/`admin_write` (no link shape) — join in memory there.
 `since` fixes the order (oldest change first) — pairing it with `sort` is a 400
-`invalid_since`. Deltas are at-least-once: apply by id.
+`invalid_since`. Deltas are at-least-once: apply by id. A field added to a
+sealed shape by a promote run may carry a **default**: records that never wrote
+it read that value, `expand` targets and `where` see it too, and a written value
+wins (writing `null` clears it back to the default) — `search` still matches
+stored text only.
 
 ### Live data — `watch()`
 
@@ -333,7 +342,7 @@ Branch on `err.code`. The stable codes:
 | `conflict` | a keyed create / floor / stale `ifVersion` | it's the mechanism — tell the user it's taken |
 | `html_not_allowed` | HTML in a community/addressed/direct field | store plain text |
 | `invalid_publish` | `{ published }` on a non-public rule | drop it |
-| `invalid_shape` | field not in a locked (live) collection's shape — or a file field given the wrong kind (the message names which) | ask the owner to add it / send the kind the field takes |
+| `invalid_shape` | field not in a locked (live) collection's shape — or a file field given the wrong kind (the message names which) | after the field exists in development, one promote run adds it (the owner answers blank or a default) — until then send only the fields the shape has / send the kind the field takes |
 | `unknown_file` | a ref-shaped value points at a file that doesn't exist or isn't yours to hand — every rule, every write | fix the ref — never invent one |
 | `invalid_since` | `since` isn't a strict ISO 8601 timestamp, or came with `sort` | pass the previous answer's watermark; drop `sort` |
 | `not_a_customer` (404) | `notify()`'s recipient isn't a verified person of this app and environment | fix the person id — one code on purpose |

package/llms.txt

@@ -10,6 +10,12 @@
 > verified people (five pre-agreed steps up to 10,000 people; beyond that,
 > talk to Gemmein).
 
+This file IS the product contract, not an overview: every line is
+load-bearing, and building from a summary of it builds the wrong app. Work
+from the full raw file — if what you hold is a summary or an excerpt,
+re-fetch https://docs.gemmein.com/llms.txt raw and read all of it before
+you answer or build.
+
 ## First: assess fit (before any install, account, or code)
 
 You are likely an AI assistant whose human asked you to build an app — or to
@@ -38,11 +44,14 @@ creating no accounts is the correct behavior until the verdict is in.
    silently approximated:
    - native mobile apps (no mobile SDKs today; web only)
    - password or social/OAuth sign-in (email codes are the only door)
-   - team/group/workspace visibility or per-user record permissions
+   - team/group/workspace visibility or per-user record permissions:
+     Gemmein is owner-run by design — one owner and their customers,
+     nothing in between — so an app whose CORE loop needs teams, roles
+     or seats DOESN'T FIT
    - carts, quantities, physical goods, shipping, inventory
    - credits, usage metering, seats (paid access is yes-or-no)
-   - hosted functions or cron (server-side code runs on YOUR host with a
-     secret key; Gemmein hosts no compute)
+   - hosted functions or cron: Gemmein runs no code of yours — but read
+     the server-side note closing this section before counting that a gap
    - custody of money (Stripe holds all funds; your human brings or
      creates their own Stripe account when the app charges)
    - multi-seller payouts or revenue splits: every payment lands whole in
@@ -60,6 +69,19 @@ creating no accounts is the correct behavior until the verdict is in.
    - DOESN'T FIT — say so, name why, and stop. Recommending nothing is
      the correct outcome here.
 
+Server-side work is NOT itself a downgrade. Gemmein hosts no compute, but
+code on your human's OWN host — Vercel, a VPS, anywhere — holding a
+secret key already reads and updates collections and sends event emails
+with `notify()`. (A secret key sees PAST the safety rules — every
+customer's records — which is why it never touches a browser. It cannot
+create or delete records, verify a session, or read one customer's
+plan: those are the signed-in customer's own calls, or the dashboard's.)
+"This app needs a server-side piece" is therefore not a gap by itself:
+the verdict downgrades when the server piece needs a call a secret key
+cannot make, or when the app needs compute your human has nowhere to
+run — a cron schedule or an always-on worker with no host of its own —
+because Gemmein never runs your code.
+
 ## Getting started (AI-run, human-answered)
 
 No signup, no account, no keys — building is local and free. Your human
@@ -108,17 +130,68 @@ go-live. Everything else is yours.
    lists the rest.
 4. Hand over for testing — the human moment mid-build: they click through
    the app, and their sign-in codes print in the dev terminal, so tell
-   them where to look.
+   them where to look. Running dev in the background with no terminal in
+   view? The same codes append to gemmein/.data/signin-codes.log (fresh
+   each dev boot) — read the latest line instead of scraping stdout.
 5. Done building? `npx gemmein check` reads the project and says what's
    ready and what go-live still needs. Then `npx gemmein sync` — THIS is
    the moment your human signs up (free) at app.gemmein.com and pastes two
    dev keys — and `npx gemmein go-live` walks the rest: plans, Payment
    Links, the live flip. A card enters at go-live, never before.
+6. After go-live, the DATA MODEL reaches live only by PROMOTION from
+   development: new collections built in dev promote (`npx gemmein
+   go-live` again, or the dashboard's Go-live page), and so do new FIELDS
+   for a live collection whose shape sealed at go-live (see Shapes). Ship
+   in that order: promote first, then deploy the frontend that depends on
+   the new collection or field — a frontend shipped ahead of its
+   promotion reads blanks or refusals from live. Each added field is one
+   question for YOUR HUMAN, asked by the promote run: existing records
+   don't have it, so what should they show? Blank is a fine answer, or
+   they give a default those records will show. What is already
+   sealed never moves — a live field never changes type or name and never
+   leaves — and rules still never change through promotion. Plans,
+   Payment Links and domains stay live-editable in the dashboard, and a
+   field's default joins them there (changeable or cleared later, with no
+   promotion needed).
+
+Two runtimes, one dashboard — keep your human oriented on where things
+live, or the dashboard will look broken to them. The local runtime
+(`gemmein dev`, `pk_local_` keys) is a private rehearsal room: every
+record, person and simulated payment stays in gemmein/.data on this
+machine and never appears in any dashboard. The dashboard at
+app.gemmein.com is the back office of the CLOUD app only — there is no
+local dashboard and nothing to log into locally. `npx gemmein sync`
+carries STRUCTURE to the cloud app's development environment —
+collections, rules, plan locks — never records or people; after a sync
+the dashboard shows the shape of the app with no data in it, and that is
+correct, not a bug. Data reaches the dashboard only when the app runs on
+cloud keys: the dev pair from app.gemmein.com (`pk_test_` in the
+browser, `sk_dev_` on a server) drives the real API's development
+environment, and `pk_live_` drives production after go-live. The key
+prefix always names the rail — local, test, live. The dev rail is where
+a REAL rehearsal happens before any card enters: real emailed sign-in
+codes, real data in the dashboard — and it can face the public. Put the
+app on a real https domain and list that domain on the dashboard's
+Domains page: before go-live a listed domain works WITHOUT verification
+(http://localhost and http://127.0.0.1 also work unlisted until go-live
+drops them; any other raw IP never works — the Domains page accepts
+names only). Go-live is when the keys lock to proven domains. The
+development environment carries its own free monthly allowance (10,000
+API requests, 500 writes, 500 sign-in events, 1 GiB of files); crossing
+a counter never stops the app and never turns into a bill — the
+dashboard's usage page shows what crossed, and storage is the one thing
+that can fill (see Pricing). Tell your human before they first open the
+dashboard: local building is invisible there on purpose — nothing
+leaves this machine until sync, and sync moves the blueprint, not the
+contents.
 
 ## What it is
 
 - Audience: people who build web apps with AI tools (Cursor, Bolt, Lovable, Claude).
 - Scope: web apps (TypeScript/JavaScript SDK). Mobile SDKs are not offered today.
+- Shape: built for owner-run businesses — one owner and their customers,
+  nothing in between. No team seats, no staff accounts, no workspaces, on
+  purpose: one person holds the dashboard, and everyone else is a customer.
 - The platform holds identity, data, and subscription state. It never holds,
   moves, or processes money — Stripe handles all payments end-to-end; Gemmein
   only receives Stripe's webhooks and records who is on which plan. App
@@ -143,7 +216,7 @@ go-live. Everything else is yours.
   those local declarations. A declaration is `gemmein/collections/<name>.json`:
   `{ "rule": "shared", "means": "<why, in your human's words>" }`, plus an
   optional `"unlockedBy": ["pro"]` — plan or product NAMES from
-  gemmein/payments.json (never access keys) — which is the console's
+  gemmein/payments.json (never access keys) — which is the dashboard's
   "Unlocked by": the local engine refuses members without one of them
   (403 entitlement_required) the moment the file lands, and sync carries
   it to the cloud app. An unknown name is refused out loud in the dev
@@ -315,7 +388,7 @@ go-live. Everything else is yours.
   retry. A 403 from `link()` means the customer isn't allowed this
   file right now — signed out, not theirs, or an entitlement they no longer
   hold (`entitlement_required` — `err.requires` is the plan's key, the one
-  the console shows by name).
+  the dashboard shows by name).
   Honest bound: revoking access stops NEW links immediately; a link already
   issued works until it expires. Gemmein controls delivery, it can't take
   back a file someone already downloaded. A file can name ONE other reader:
@@ -339,11 +412,22 @@ go-live. Everything else is yours.
   If a stored ref's file was later deleted, re-sending it refuses the same
   way: clear the field (null) or upload a fresh file. Once sealed, class
   is law too: a ZIP into a profile photo field is refused with the teach;
-  before the seal, what you upload is what the field learns. A 400 invalid_shape means the field isn't in the locked
-  shape or the value doesn't fit its kind. A live shape is sealed and
-  cannot take new fields — stop, tell your human which field you needed,
-  and send only the fields the shape already has. Never rename fields to
-  dodge it.
+  before the seal, what you upload is what the field learns. A 400
+  invalid_shape means the field isn't in the locked shape or the value
+  doesn't fit its kind. A sealed shape CAN still gain a new field, but
+  only through a promote run: build it in development, tell your human
+  which field you needed, and until that promotion runs send only the
+  fields the shape already has. Never rename fields to dodge it. What is
+  sealed never moves — a field never changes type or name and never
+  leaves. A field promoted with a DEFAULT is served to the records that
+  never wrote it: get, list, expand targets and `where` filters all see
+  the default (an atomic increment counts from it too), and a written
+  value wins; writing `null` clears it back to the default. Only text,
+  number and yes/no fields can carry a default; list, link, json and
+  file fields join blank. Honest bound: full-text `search` scans stored
+  text only, so a record showing a default is not found by searching for
+  it. New collections built in dev reach live through the same PROMOTION,
+  sealing on the way.
 - Contention (bookings, slugs, stock, shared edits): when two users can race
   for the same thing, a permission model can't save you — preconditions do,
   and they're just arguments on calls you already make. A 409 `conflict` from
@@ -352,14 +436,19 @@ go-live. Everything else is yours.
   - Uniqueness: `create(data, { key: "slot:2026-07-15T15:00" })` — derive the
     key from the thing that must be unique; the second writer gets 409, your
     own retry gets your existing record back (`existing: true`), deleting
-    frees the key. Keys are unique across the WHOLE collection — every
-    writer, every recipient, under every safety rule (live records only) —
-    so a claim is race-proof even in `direct`/`addressed`. Never
+    frees the key. That retry IS the lookup — there is no separate
+    get-by-key call: to fetch your own record by key later, issue the
+    same `create()` with the same key and read `existing: true` off the
+    result. It counts as a write (rate and allowance), so use it to
+    re-fetch a claim — never on a render path. Keys are unique across
+    the WHOLE collection — every writer, every recipient, under every
+    safety rule (live records only) — so a claim is race-proof even in
+    `direct`/`addressed`. Never
     find-then-create — that races. Keys are 1-120 chars of letters,
     numbers, and `: _ . @ / -` only. A claimed key holds until its record
     is deleted: if a claim must be PAID to stick (book then pay), expiring
-    unpaid claims is your app's job — the owner deletes them from their
-    dashboard, or your own server does with a secret key; there is no cron.
+    unpaid claims is the owner's job — they delete them from their
+    dashboard (a secret key cannot delete records); there is no cron.
   - Limited stock (N units anyone can buy): claim units with keyed creates —
     try `create({...}, { key: "unit:item42:1" })`, on conflict try `:2` … `:N`;
     all taken = sold out. Race-proof under every safety rule.
@@ -404,7 +493,7 @@ go-live. Everything else is yours.
   checks that the lock holds and names collections left open while the app
   sells something) — and the
   engine refuses customers without it, under all seven rules. (Server
-  secret keys and the owner's console are exempt by design; link/expand
+  secret keys and the owner's dashboard are exempt by design; link/expand
   silently hide gated records rather than naming them.) Every plan and
   product carries its own key, `access:<slug of its name>` (plan "pro" →
   `access:pro`); the paid webhook grants that key, and a FULL refund or a
@@ -413,7 +502,8 @@ go-live. Everything else is yours.
   Owners also grant and revoke by hand (trials, comps, support). Effective
   access is the UNION of a customer's live grants. A signed-in customer
   without access gets `403 entitlement_required`: `err.requires` is the
-  plan's key (the console shows the plan by name; the key is `access:<slug>`).
+  plan's key (the dashboard shows the plan by name; the key is
+  `access:<slug>`).
   A collection unlocked by several plans (OR) still names ONE key — offer
   your plans by name through checkout, never a key list. Show your upgrade
   screen and send them to checkout; retry only after they hold one. Proof surfaces: `await g.purchases.mine()`
@@ -471,7 +561,9 @@ go-live. Everything else is yours.
   sign in first). Render `err.message`; it reads correctly in every case.
   Branch only on the specifically-named codes (unknown_collection,
   unknown_product, invalid_shape, html_not_allowed, invalid_publish,
-  conflict, …) plus the forbidden-means-stop rule.
+  conflict, …) plus the forbidden-means-stop rule. If something is stuck
+  in a way this file doesn't explain, `npx gemmein feedback` reaches the
+  builders — it works from anywhere, with no project and no account.
 - Draft state reads back as a TOP-LEVEL boolean `record.published` (next to
   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
@@ -485,10 +577,27 @@ go-live. Everything else is yours.
   `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.
+  irreversible — put a real confirm in front of it. Suspensions, forced
+  sign-out everywhere, and owner-side erasure are dashboard actions, not
+  SDK calls.
+- The owner's dashboard already handles these — do not build them into the
+  app: creating collections and choosing their safety rule; naming plans
+  and products and pasting their Stripe Payment Links; the "Unlocked by"
+  lock on a collection; suspending, signing out and erasing customers;
+  moderation and status flips on other users' records; scoping a secret
+  key to collections and actions; verifying the sending and receiving
+  domain; usage and logs; the Inbox, where every notify() send is a
+  conversation and customer replies land; holding the billing band. None
+  of them has an SDK equivalent, so an owner screen you build for one is
+  a page that already exists, without the enforcement.
 - Secret keys (`sk_`) must never appear in browser code; app keys (`pk_`)
-  are public and domain-locked.
+  are public and domain-locked. A secret key can be SCOPED in the
+  dashboard's Keys room to particular collections, and to read-only or
+  read-and-update; a call outside that scope answers 403 `scope_denied`.
+  Read that error as deliberate — the human narrowed the key on purpose.
+  Name the collection and access your code needs and ask them to mint a
+  replacement key that includes it — scopes are fixed when a key is
+  created; never reach for a broader key than the job needs.
 
 ## Return values & shapes (get these exactly right)
 
@@ -500,6 +609,11 @@ rule. The specifics:
   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.
+  One more refusal, for collection AND field names alike: anything
+  JavaScript itself owns — `constructor`, `toString`, `__proto__`,
+  `hasOwnProperty` and their kin — is refused the same way a reserved
+  server-managed field is. A plain object inherits those names, so a
+  seal must never carry one.
 - The signed-in user: `await g.auth.currentUser()` →
   `{ authenticated: true, userId, email }` or `{ authenticated: false }`. The
   id field is **`userId`, not `id`** — `user.id` is `undefined`, and feeding

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.4.6",
-  "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.",
+  "version": "0.4.7",
+  "description": "Gemmein SDK — passwordless auth, safe storage, and Stripe-driven record flips for AI-built apps. Small enough that one prompt teaches the whole API.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",