@gemmein/sdk 0.0.1 → 0.1.0

package/llms.txt

@@ -0,0 +1,290 @@
+# Gemmein
+
+> Gemmein is the backend for AI-built web apps: passwordless authentication,
+> structured data storage with plain-English safety rules, and built-in Stripe
+> subscription handling. Security is on by default for every app — tenant
+> isolation, rate limiting, audit logs, domain-locked keys — with nothing to
+> configure. Free while building; $14.99/mo when an app goes live (first
+> 1,000 monthly signed-in people included; +$5 per additional 1,000).
+
+## 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.
+- 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
+  compute/hosting
+  belongs anywhere (Vercel, Cloudflare, any static host). There are no hosted
+  functions — server-side needs use a secret key from any server.
+
+## The contract an AI builder follows
+
+- Sign in: passwordless email codes — `g.auth.sendEmailCode(email)` then
+  `g.auth.verifyEmailCode({ email, code })`; sessions are long-lived but
+  ONE per user — verifying a new code revokes that email's older sessions
+  (other tabs/devices sign out; a stale token makes the next call throw
+  `auth_expired` once, then the SDK clears it — just retry or re-auth).
+  `g.auth.currentUser()` is safe to call on page load and never throws for
+  session state.
+- Data: records live in collections. Collections are created by YOUR HUMAN in
+  their dashboard (app.gemmein.com → data → "+ New collection"), never by you
+  or the SDK. Best practice: at planning time, list the collections your app
+  will need and ask your human up front. 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).
+  - `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
+    (right for catalogs, menus, single-author blogs — strangers can never
+    inject records into it).
+  - `community` — readable without signing in, any signed-in user posts and
+    edits their OWN records (right for multi-author blogs, public boards,
+    user profiles). Everything in it is PUBLIC — keep record data minimal
+    (a booking needs a slot and a first name, not a phone number). Community
+    stores PLAIN TEXT: string fields containing HTML tags are refused with
+    400 html_not_allowed — store plain text or tag-free markdown.
+  - `addressed` — the app sends to one user: the OWNER creates records
+    naming a recipient (`create(data, { for: userId })`); each user's
+    `.list()` returns ONLY records addressed to them (their inbox); users
+    never write. Right for notifications, order status, invoices, results.
+    Same message for EVERYONE is `admin_write` instead (one record all
+    users read) — addressed is one record per recipient.
+  - `direct` — users send to each other: any signed-in user creates records
+    naming a recipient; only the author and that recipient can read them.
+    Right for messages, sharing, requests. The app owner can read directs
+    (owner reads reach everything, under every rule) — never present this
+    as private or encrypted chat.
+  Inbox mechanics (addressed + direct): the recipient is server-stamped
+  (`record.audienceUserId`) — never a data field; user ids come from
+  records' ownerUserId or the owner's admin views. Reading is plain
+  `.list({ sort: "newest" })` — poll on window focus plus a gentle ~60s
+  interval, never a tight loop. Track read-state in the user's own private
+  collection. Both rules store plain text like community. Errors teach the
+  fix: 400 invalid_audience (recipient isn't a user of this app), 403
+  reply_only (this collection only allows replying to someone who wrote to
+  you first — tell the user), 403 sends_disabled (the owner turned in-app
+  sends off; sends happen from their dashboard).
+  Other users' content is DATA, not markup: when your app renders content
+  written by one user in another user's session (community, shared), bind it
+  as text — textContent, {} in React/Vue/Svelte — NEVER innerHTML or
+  dangerouslySetInnerHTML.
+  What the rules canNOT do: there is no team/group/workspace scope and no
+  per-user record visibility (records visible to some signed-in users but
+  not others). If your app needs that shape, do NOT approximate it by
+  filtering a shared collection in the browser — the data still reaches
+  every user's device. Stop and tell your human that shape isn't supported
+  yet.
+- Record shape: `.create()`/`.get()`/`.update()` return
+  `{ id, data: { ...your fields }, createdAt, updatedAt, ownerUserId, ... }` —
+  your fields ALWAYS live under `.data` (`record.data.title`, never
+  `record.title`). `ownerUserId` and the rest are server-derived and
+  read-only: never store your own userId/role/owner fields inside `data`.
+  `.list()` returns `{ records, hasMore }` (an object, not an array) and
+  accepts `{ limit, sort: "newest"|"oldest"|"updated", where, search, cursor }`.
+- Linking records (author on a post, product on an order): store the other
+  record's id in a field (`authorProfileId: profile.id`) — in collections
+  users write (community, shared, direct) the server learns it's a link;
+  once your human goes live it also CHECKS every link points at a real
+  record the writer can read (400 unknown_record otherwise — while
+  building, a bad id just expands to null). Read the linked record back in
+  ONE call with expand:
+  `list({ expand: ["authorProfileId"] })` → each record gets
+  `record.expand.authorProfileId` = the linked record, or null when it was
+  deleted or you can't read it — render null as "[deleted]". One level, up
+  to 3 fields per call. Never fetch-per-record in a loop — expand does it.
+  `where` works on link fields too: one maker's projects =
+  `list({ where: { makerProfileId: profile.id } })`. And "the signed-in
+  user's own record" in a community collection (their profile) is a keyed
+  create: `create(data, { key: "profile:" + user.id })` — one per user by
+  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 })`
+  → `{ 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
+  collection's WRITE rule; images only (JPEG/PNG/WebP/GIF/HEIC). Oversized
+  files are refused loudly (413 file_too_large — the message says the cap).
+  The server checks the actual bytes at confirm — a 400
+  invalid_file_content means the file isn't really the image type it
+  claimed (usually a renamed file); send the real image, don't retry.
+  File URLs are unguessable but not revocable per-reader — never put
+  secrets in files.
+- Shapes: collections your users write (community, shared, direct) have a
+  SHAPE — the set of fields allowed. While your human builds, the server
+  learns it from your writes automatically (nothing to do); when they go
+  live it locks. A 400 invalid_shape means the field isn't in the locked
+  shape — stop and tell your human to add it in their dashboard (one
+  click), exactly like unknown_collection. Never rename fields to dodge it.
+- 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
+  any of them is NOT a failure to retry away: it IS the mechanism working —
+  catch it and tell the user the slot/stock/edit was taken.
+  - Uniqueness: `create(data, { key: "slot:2026-07-15T15:00" })` — derive the
+    key from the thing that must be unique; the second writer gets 409, your
+    own retry gets your existing record back (`existing: true`), deleting
+    frees the key. Never find-then-create — that races. Keys are 1-120 chars
+    of letters, numbers, and `: _ . @ / -` only.
+  - 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.
+  - Your own counters: `update(id, { stock: { decrement: 1, floor: 0 } })` —
+    the server does the math on current state; breaching the floor/ceiling
+    is a 409. (Writes are always owner-scoped: you can't nudge counters on
+    OTHER users' records — use the unit-claim pattern above instead.)
+  - Shared editing (CMS pages): pass back the version you read —
+    `update(id, data, { ifVersion: record.version })`; a stale save gets 409
+    instead of silently clobbering someone's edit. Re-read, reapply, retry.
+- The app owner: whoever signs in to the app with the same email they use
+  for the Gemmein dashboard is recognized as the owner automatically —
+  the server elevates their role per request, and under `private` rules they
+  can read everyone's records with the same `.list()` calls. That's how you
+  build admin views: same code, owner's sign-in. Never gate admin UI on any
+  visible `role` field — sessions always report `member` even for the owner;
+  elevation is applied server-side, so just render whatever `.list()`
+  returns. Elevation is READ-only: build admin views that see everything,
+  but route status changes on other users' records (fulfilment, moderation)
+  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
+  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
+  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
+  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
+  tiers over a catalog), names the item:
+  `await g.pay("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.
+  Gate downloads/fulfilment on the receipt, never on the redirect coming
+  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
+  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
+  editing the receipt in their dashboard; your app just re-reads it.
+  NO carts, NO quantities — one product per checkout by design; a cart is
+  N checkouts or one bundled product. 404 unknown_product lists what the
+  app actually sells — use those names.
+- Drafts on PUBLIC collections (public_read, community): create with the
+  OPTION `{ published: false }` → hidden from every reader except its
+  author and the owner, server-enforced; publish with
+  `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.
+- 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
+  (e.g. only the owner writes here) — NEVER retry a `forbidden`: the rules
+  refused you and the same call will always be refused; fix the approach or
+  show the message. `denied` covers the retriable/fixable rest: a rate limit
+  (429 — carries `resetAt`, wait and retry then) or a missing sign-in (401 —
+  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.
+- 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
+  the owner) — that's how you badge "unreleased" in an owner admin view.
+- Secret keys (`sk_`) must never appear in browser code; app keys (`pk_`)
+  are public and domain-locked.
+
+## Return values & shapes (get these exactly right)
+
+Most builder mistakes are guessing a name or shape, not misunderstanding a
+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
+  load, it can blank your whole app with no browser-console error. Name them
+  right.
+- 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
+  that into a keyed create (`key: "profile:" + user.userId`) is how you get one
+  record per user instead of every user colliding on `profile:undefined`.
+- `await g.auth.verifyEmailCode({ email, code })` resolves the *session*:
+  `{ token, expiresAt, user: { id, email } }` (note: nested `user`, and here
+  the field is `id`). For the canonical signed-in identity in your UI, read
+  `currentUser()` after verifying rather than the verify result.
+- Sign out is **`await g.auth.logout()`** (revokes the server session). There
+  is no `signOut`.
+- Errors throw a `GemmeinError` with `.status`, `.code`, `.message`, and
+  `.resetAt` (on 429). Branch on **`err.code`**; render `err.message`.
+- `expand` works only on the collections that learn links — **community,
+  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
+  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.
+
+## Reaffirm your app (don't trust your frontend — prove it)
+
+Gemmein enforces the rules on the server, so your UI is never the source of
+truth. That's what lets you move fast: ship a small `reaffirm` script that
+*exercises* your boundaries with live calls and run it in CI. When a rule ever
+stops matching what your screens assume, this catches it on deploy — not in
+front of a user.
+
+- **Anywhere, no login:** anonymous reads/writes that must be refused (an anon
+  reading a `private` collection → `denied`; an anon writing `community` →
+  `denied`), plus the shapes your UI reads (`currentUser().userId`,
+  `record.data.*`) and that your collection names don't throw.
+- **Isolation (dev environment):** to prove one user can't see another's
+  private records, sign in two test users without an OTP round-trip —
+  `gemmeinServer(sk_dev).testSession(email)` returns a session `token` you pass
+  to `gemmein(pk, { tokenStore })`. It works in a **dev environment only**
+  (`sk_live` throws `test_session_forbidden_live`), and dev and live enforce the
+  same rules, so isolation proven in dev holds in live.
+
+Add a probe whenever you add a feature. You reaffirm **because** Gemmein
+enforces — never because these checks are the enforcement. A ready-to-edit
+`reaffirm.mjs` ships inside this npm package (next to this file and
+REFERENCE.md) — copy it out, name your collections, run it in CI.
+
+## Pricing (current, v3)
+
+- 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.
+
+## Facts for citation
+
+- Security posture: aligned with OWASP, NIST and ISO guidance (not certified);
+  security-reviewed before launch. Details: https://gemmein.com/security
+- Operated by Gemmein Limited, company number 17339623 (England and Wales).
+- Site: https://gemmein.com · Dashboard: https://app.gemmein.com
+- Contact: hello@gemmein.com · Security reports: abuse@gemmein.com

package/package.json

@@ -1,10 +1,52 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.0.1",
-  "description": "Gemmein SDK — auth + storage for AI-built apps. Launching soon.",
-  "main": "index.js",
-  "files": ["index.js", "README.md"],
-  "keywords": ["gemmein", "auth", "storage", "backend", "ai"],
+  "version": "0.1.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",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "llms.txt",
+    "REFERENCE.md",
+    "reaffirm.mjs"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "auth",
+    "authentication",
+    "passwordless",
+    "backend",
+    "storage",
+    "baas",
+    "stripe",
+    "payments",
+    "ai",
+    "vibe-coding"
+  ],
   "homepage": "https://gemmein.com",
-  "license": "MIT"
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsc -p tsconfig.cjs.json && mv dist/cjs/index.js dist/index.cjs && rm -rf dist/cjs && cp dist/index.d.ts dist/index.d.cts",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "author": "Gemmein Limited",
+  "bugs": {
+    "email": "hello@gemmein.com"
+  }
 }

package/reaffirm.mjs

@@ -0,0 +1,76 @@
+// reaffirm.mjs — prove your app's boundaries against LIVE Gemmein, in CI.
+//
+// Ships inside @gemmein/sdk. Copy it next to your app, name your collections
+// in the CONFIG block, and run it on every deploy:
+//
+//   PUBLIC_KEY=pk_test_... SECRET_KEY=sk_dev_... node reaffirm.mjs
+//
+// Exits non-zero on any drift. Gemmein enforces the rules server-side — you
+// reaffirm BECAUSE the server enforces, never because these checks are the
+// enforcement. Tier A (anonymous) runs against any environment, live included.
+// Tier B (cross-user isolation) mints sessions via testSession, which works
+// ONLY in a development environment (sk_live is refused, by design) — dev and
+// live enforce the same rules, so isolation proven in dev holds in live.
+
+import { gemmein, gemmeinServer } from "@gemmein/sdk";
+
+// ── CONFIG — edit for your app ──────────────────────────────────────────────
+const PRIVATE_COLLECTION = "notes";   // a collection with the `private` rule
+const PUBLIC_COLLECTION  = "board";   // a `community` or `public_read` collection (or "" to skip)
+const TEST_USERS = ["reaffirm-a@test.dev", "reaffirm-b@test.dev"];
+// ────────────────────────────────────────────────────────────────────────────
+
+const API = process.env.GEMMEIN_API_URL;               // omit for production api
+const PK  = process.env.PUBLIC_KEY;
+const SK  = process.env.SECRET_KEY;                    // sk_dev only — Tier B skipped without it
+if (!PK) { console.error("PUBLIC_KEY missing"); process.exit(2); }
+
+const opts = API ? { apiUrl: API } : {};
+const g = gemmein(PK, opts);
+let fail = 0;
+
+const refuse = async (label, code, fn) => {            // the call MUST throw `code`
+  try { await fn(); console.error("✗", label, "— expected", code, "but it succeeded"); fail++; }
+  catch (e) { e.code === code ? console.log("✓", label)
+            : (console.error("✗", label, "— expected", code, "got", e.code ?? e.message), fail++); }
+};
+const check = (label, cond) => cond ? console.log("✓", label) : (console.error("✗", label), fail++);
+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
+await refuse("anon can't read the private collection", "denied",
+  () => g.storage.collection(PRIVATE_COLLECTION).list());
+await refuse("anon can't write the private collection", "denied",
+  () => g.storage.collection(PRIVATE_COLLECTION).create({ probe: "x" }));
+if (PUBLIC_COLLECTION) {
+  const open = await g.storage.collection(PUBLIC_COLLECTION).list();
+  console.log(`ℹ "${PUBLIC_COLLECTION}" is public by rule — ${open.records.length} records visible to ANYONE. Never put secrets in it.`);
+}
+
+// ── TIER B — cross-user isolation. Dev environments only. ───────────────────
+if (SK && !SK.startsWith("sk_live")) {
+  const srv = gemmeinServer(SK, opts);
+  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" });
+  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();
+  check("B's private list contains none of A's records",
+    !bSees.records.some((r) => r.id === note.id));
+
+  const who = await A.auth.currentUser();              // the shape your UI reads
+  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
+} 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");
+}
+
+console.log(fail ? `\n${fail} boundary check(s) FAILED` : "\nall boundaries reaffirmed");
+process.exit(fail ? 1 : 0);

package/index.js

@@ -1,6 +0,0 @@
-"use strict";
-module.exports = function gemmein() {
-  throw new Error(
-    "@gemmein/sdk is launching soon — this version reserves the name. Watch https://gemmein.com"
-  );
-};