@gemmein/sdk 0.9.0 → 0.10.0

package/llms.txt

@@ -7,8 +7,9 @@
 > nothing to configure. Build anywhere, with any AI, free — and come to
 > Gemmein when you're done: the product is taking the app to real customers.
 > Live apps pay one banded plan, $50-$150/mo, set by the previous month's
-> verified people (five pre-agreed steps up to 10,000 people; beyond that,
-> talk to Gemmein).
+> active people — a person counts once a month, on their first signed-in
+> request, on web and mobile alike (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
@@ -47,7 +48,9 @@ creating no accounts is the correct behavior until the verdict is in.
    access, race-safe bookings/stock/counters, account-deletion cascade.
    Out of scope — each of these downgrades the verdict and must never be
    silently approximated:
-   - native mobile apps (no mobile SDKs today; web only)
+   - Android or iOS written natively in Kotlin or Java (the mobile SDKs
+     are `@gemmein/sdk/expo` for Expo and React Native, and `GemmeinSwift`
+     for Apple platforms — see Mobile)
    - password or social/OAuth sign-in (email codes are the only door)
    - team/group/workspace visibility or per-user record permissions:
      Gemmein is owner-run by design — one owner and their customers,
@@ -238,7 +241,9 @@ 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.
+- Scope: web apps (TypeScript/JavaScript SDK) and phone apps — Expo and
+  React Native through `@gemmein/sdk/expo`, Apple platforms through the
+  `GemmeinSwift` package (iOS 17+, macOS 14+). See Mobile.
 - 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.
@@ -341,7 +346,8 @@ contents.
   `.list()` returns `{ records, hasMore }` (an object, not an array) and
   accepts `{ limit, sort: "newest"|"oldest"|"updated", where, search, cursor,
   since }`. limit is 25 by default and 100 at most; a larger ask is refused
-  with invalid_limit — page with cursor.
+  with invalid_limit — page with cursor. A record's data is at most 32 KB
+  (413 payload_too_large); files go through uploads, never inline.
 - Live data (dashboards, feeds, inboxes): nothing is pushed — BY DESIGN
   (pushed data is where other platforms leak; every Gemmein read passes the
   permission check). Instead, polling is built in and cheap:
@@ -385,8 +391,15 @@ contents.
   A person id, NEVER an email address — the recipient must be a verified
   user of your app (404 not_a_customer otherwise; the address comes from
   the server's own record). Plain text; a short "you have an account with
-  {your app}" footer is added for you. The email is branded as your app
-  (your verified domain when you have one). Every send appears in your
+  {your app}" footer is added for you. notify sends only from YOUR verified
+  sender domain: until one is verified on the Domains page the send is
+  refused (409 sender_domain_required) — nothing leaves, nothing is
+  recorded, no cap is spent, and the same key sends once you verify. If
+  your provider refuses that address at send time the call fails
+  (502 send_failed) and is safe to retry; it is never quietly re-sent from
+  a Gemmein address. Sign-in codes are the one email Gemmein sends on your
+  behalf before a domain is verified, as "<App name> (via Gemmein)".
+  Every send appears in your
   dashboard Inbox as a conversation; a customer's REPLY lands there too
   once your domain's receiving is verified (the Domains page) — before
   that the mail has no reply path, so if you expect answers, say where to
@@ -439,7 +452,7 @@ contents.
   purchases and subscriptions come from the built-in Stripe path, and
   another provider's payment grants through a relay (source `relay`). Every /server/*
   call a resolved secret key makes, ok or refused, lands in that key's
-  usage ledger on the owner's Keys page (a rejected or publishable key
+  usage ledger on the owner's Secret keys page (a rejected or publishable key
   can't be attributed, so it reaches only the request log); refusals also
   write one activity row per key, route and code each hour. In `gemmein
   dev` the local key already holds both capabilities, and the usage read
@@ -499,7 +512,7 @@ contents.
   person or open access; something should run on a clock and write a
   record or ping your URL.
   Not when: the work computes or reshapes data (that is your function);
-  one event should email many people (a broadcast, planned); a schedule
+  one event should email many people (a relay addresses one person); a schedule
   must address a person (not yet); you already use Stripe for the money —
   the built-in Stripe path already grants access and writes receipts, and
   a relay adds nothing there.
@@ -534,8 +547,18 @@ contents.
   - receiver — a provider's signed webhook at `POST /hooks/<appId>/<name>`;
     `verify` names the scheme (hmac_sha256_header | stripe | svix |
     shared_token), `map` names dotted paths into the body (`event_id`
-    dedupes, `person_email` resolves the person, the rest ride as
+    dedupes, ONE person key resolves the person, the rest ride as
     `{{mapped.<name>}}`), `when` is an exact match on mapped fields.
+    A map names the person ONE way: person_email (their address, which
+    invites someone who has never signed in), person_id (a gemmein person
+    id) or person_token (the store account token their app filed with a
+    store). Two of them in one map is refused at save — the id and the
+    token could name different people, and the event would land on
+    whichever was tried first. Only `person_email` creates a person;
+    `person_id` and `person_token` are read-only lookups, because a value a
+    third party chose that matches nothing names no human at all. A key
+    that resolves to nobody records the event, answers 200 and reports
+    `person_not_found` naming the KEY that was tried, never its value.
   - schedule — `every` 15m | 30m | 1h | 6h | 12h | 1d, `at: "HH:MM"` UTC
     with 1d; one tick per period; no person, so person actions are refused.
   - data_change — `collection`, `on` ⊆ created | updated | deleted, optional
@@ -548,7 +571,10 @@ contents.
   - revoke_access { entitlement } — ends every live grant of it.
   - grant_credits { amount (1..10,000), reason? } — adds to the person's
     balance, once per event; the ledger line reads "relay: <reason>".
-  - email_person { subject, text, kind? } — rides notify's caps.
+  - email_person { subject, text, kind? } — rides notify's caps, and notify's
+    sender law: it goes only from your verified sender domain. Until one is
+    verified the action alone is refused sender_domain_required and the event
+    records it; nothing is sent via Gemmein.
   - call_url { url } — https, signed POST (`X-Gemmein-Signature`), 10 s; the
     same `id` on every retry and replay — your URL deduplicates on it.
   - fulfil_product { product, ref? } — product is a name on the Payments
@@ -594,6 +620,78 @@ contents.
   A template that names nothing is recorded as a warning on the relay
   event — read it on the Relays page before trusting a ref.
 
+  THE STORE ROAD (RevenueCat) — the three templates the Relays room offers,
+  and the way an App Store or Play Store purchase reaches Gemmein. It is
+  THREE relays, not one: `when` matches one exact value per field, so an
+  event-type SET cannot be written. Each relay has its own URL and its own
+  secret, which goes in RevenueCat's Authorization header field
+  (`shared_token` reads the `authorization` header).
+
+  The PURCHASE relay carries no `when` — a product names exactly one relay
+  as the road it is sold on, so the three purchase events cannot be split
+  across three relays — and its only guard is therefore the RevenueCat
+  integration itself, which you narrow to INITIAL_PURCHASE, RENEWAL and
+  NON_RENEWING_PURCHASE and nothing else.
+
+  The two REVOKING relays each carry their own `when` —
+  `{ "event_type": "EXPIRATION" }` and `{ "event_type": "CANCELLATION" }` —
+  because `revoke_access` is authorised by no road at all. Without the
+  filter, a purchase posted to a revoke relay by a mis-pasted URL or a
+  widened integration would take away the access it had just granted. The
+  guard is the RELAY'S OWN, in Gemmein, whatever a third party's console is
+  configured to send; an event a `when` does not match answers 200 and is
+  not even recorded.
+
+  The person is named by `person_token`: the app hands RevenueCat the
+  person's `storeAccountToken` as the app user id, so neither the gemmein
+  person id nor the address enters a third party's ledger. On the Payments
+  page, set the product's "How it's sold" to the purchase relay — that is
+  what lets it grant a purchase.
+
+      {
+        "name": "revenuecat-purchase",
+        "trigger": {
+          "kind": "receiver",
+          "verify": { "scheme": "shared_token", "header": "authorization" },
+          "map": {
+            "event_id": "event.id",
+            "event_type": "event.type",
+            "person_token": "event.app_user_id",
+            "product_id": "event.product_id",
+            "store": "event.store",
+            "transaction_id": "event.transaction_id"
+          }
+        },
+        "actions": [
+          { "type": "fulfil_product", "product": "Pro", "ref": "{{mapped.transaction_id}}" }
+        ]
+      }
+
+      {
+        "name": "revenuecat-expiration",
+        "trigger": {
+          "kind": "receiver",
+          "verify": { "scheme": "shared_token", "header": "authorization" },
+          "map": {
+            "event_id": "event.id",
+            "event_type": "event.type",
+            "person_token": "event.app_user_id",
+            "product_id": "event.product_id",
+            "store": "event.store"
+          },
+          "when": { "event_type": "EXPIRATION" }
+        },
+        "actions": [
+          { "type": "revoke_access", "entitlement": "access:pro" }
+        ]
+      }
+
+  The cancellation twin is the same definition with the name
+  `revenuecat-cancellation` and `"when": { "event_type": "CANCELLATION" }`.
+  A subscription that is cancelled and then expires sends both, and the
+  second one finds nothing left to take — said out loud on the event row,
+  never a failure.
+
   The refund twin swaps the trigger's `when` to
   `{ "event_type": "refunded" }` and the action to `refund_product`.
   `g.payments.buy` on a product sold this way answers 409
@@ -764,8 +862,14 @@ contents.
   engine refuses customers without it, under all seven rules. (Server
   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
+  product carries its own key, DERIVED from its name the first time it is
+  saved: `access:` + the name lowercased, with every run of anything that
+  is not a letter or a digit turned into ONE dash, trimmed at both ends
+  (plan "pro" → `access:pro`; product "Pro Max" → `access:pro-max`; "Deep
+  Research!" → `access:deep-research`). It is minted ONCE and stored, so a
+  later rename keeps the key and nothing a customer holds moves. Never
+  build the key yourself from a name you have in hand — pass the NAME and
+  let the server resolve it. The paid webhook grants that key, and a FULL refund or a
   cancellation revokes exactly what it granted — nothing else. A partial
   refund leaves access in place.
   Owners also grant and revoke by hand (trials, comps, support). Effective
@@ -958,13 +1062,15 @@ contents.
   — label, credits, requires, enabled, recordCalls — and the file's values
   for those apply ONCE, at creation; after that the dashboard's stand. A
   tool edited in the dashboard since the last sync is not silently
-  overwritten: sync asks, per tool. On the local rail a tool saves without
-  a provider key or a model allowlist; the cloud checks both at save: a
-  tool on a provider with no key on the AI tools page is refused
-  `provider_not_configured` (409), and a pinned `model` outside that
-  provider's allowed models on the AI tools page is refused `invalid_tool`
-  (400 — the message lists what is allowed). The tool's NAME is the file
-  name and is fixed once created.
+  overwritten: sync asks, per tool. A tool can be defined before its
+  provider key exists: the save takes on both rails, the console shows the
+  tool as waiting on a key, and runs are refused `ai_not_configured` (409)
+  until the key is pasted on the AI tools page — after which the same tool
+  runs, with no further step. When the key is there, a pinned `model`
+  outside that provider's allowed models on the AI tools page is refused
+  `invalid_tool` (400 — the message lists what is allowed); with no key
+  there is no allowed list, and the pin is taken as it stands. The tool's
+  NAME is the file name and is fixed once created.
   Also true of the route itself: `sk_` is refused; it does not choose
   models, cache, summarise, moderate, or reshape the request or the
   answer; it does not refund a call that dies mid-stream, or one the
@@ -1012,6 +1118,14 @@ contents.
   read that as the cloud's answer. A call that names no tool runs as the
   default tool: one credit, your configured provider, any allowed model —
   behind the same switch.
+  THE ORDER THE ROUTE REFUSES IN, so you know which code a call actually
+  meets: session → rate → body size → the named tool (unknown_tool,
+  tool_disabled, entitlement_required) → the provider (provider_required,
+  ai_not_configured) → raw_calls_off → the model → the spend
+  (credits_exhausted). So a raw call to a provider with no key answers
+  ai_not_configured, not raw_calls_off; a raw call naming a tool that does
+  not exist answers unknown_tool; and no refusal above the spend has cost a
+  credit.
 
       const res = await g.ai.chat({ model: "gpt-4o-mini", stream: true,
         messages: [{ role: "user", content: text }] })   // raw: needs the switch
@@ -1025,13 +1139,13 @@ contents.
   this environment) · tool_disabled (403 — the owner switched it off)
   · entitlement_required (403 — the message names the plan or product
   it needs) · model_pinned (403 — the tool's model is fixed; leave
-  `model` out of the body) · provider_not_configured (409 — creating a
-  tool: add that provider's key first) · too_many_tools (409 — 50
+  `model` out of the body) · too_many_tools (409 — 50
   tools per environment) · invalid_tool (400 — creating or updating a
   tool with a bad field) · credits_exhausted (402 — the message names
   the tool, its price and the balance, singular for 1; show the pack)
-  · ai_not_configured (409 — no
-  key set; the owner pastes one) · provider_required (400 — more than
+  · ai_not_configured (409 — no key
+  set for the tool's provider; a tool may be defined before its key, and
+  runs the moment the owner pastes one) · provider_required (400 — more than
   one key set; name `provider`) · model_not_allowed (403 — the owner's
   allowlist names what is allowed, for a tool with no pinned model) ·
   ai_capped (429 — 20 per person per minute; wait for `resetAt`) ·
@@ -1061,11 +1175,140 @@ contents.
   no pinned model (the AI tools page's test call uses the first); every
   `/ai/chat` call counts toward the app's api_requests band like any
   other request; a provider that echoes the key in a refusal reaches
-  you as `***<hint>`. The owner's Usage room counts the calls; the
+  you as `***<hint>`. The owner's Usage & billing page counts the calls; the
   provider bills the tokens on the owner's own account. `gemmein dev`
   answers a fake provider without a key (header `x-gemmein-ai: fake`),
   so the loop runs locally; set GEMMEIN_AI_KEY_OPENAI / _ANTHROPIC /
   _GOOGLE there for a real call.
+- Mobile — Expo / React Native and Swift.
+  A phone app is the SAME contract as a browser app: the PUBLIC KEY
+  identifies the app, the SESSION authorises the person, and VERIFIED
+  DOMAINS are a browser control that is not checked for an app — an app
+  sends no Origin, so nothing is being verified there. Ordinary API
+  authentication does not establish app integrity: the app key ships inside
+  the binary, so build as though any request could come from anywhere and
+  let the session and the server's rules decide, exactly as on the web.
+  See https://docs.gemmein.com/mobile
+  What it is: the same Gemmein contract from an Expo app
+  (`@gemmein/sdk/expo` — the same npm package, a second entry point) or a
+  Swift app (`GemmeinSwift`, iOS 17+ / macOS 14+, the same method names).
+  Does: sign in by email code; the app's own collections, private records
+  included; sealed files and `files.link`; credits; AI tools; the STORE
+  ACCOUNT TOKEN — `currentUser().storeAccountToken`, the name to hand
+  RevenueCat as its app user id; sign out everywhere, the remedy for a
+  stolen phone, run by the owner from the console on that person's page;
+  secure persistence — the iOS Keychain / Android Keystore through
+  `expo-secure-store`, the Keychain through `KeychainTokenStore` in Swift —
+  so the app relaunches still signed in.
+  Does not: Google or Apple sign-in (email codes are the only door, on
+  every platform); store billing inside Gemmein (Gemmein never talks to the
+  App Store or Play — a store purchase reaches it through RevenueCat's
+  webhook into a relay); broadcast (one event acts on one person).
+  Needs something else when: the person buys a STORE product → RevenueCat
+  plus the three relay templates (THE STORE ROAD, under Relays); your
+  sign-in codes should come from YOUR domain → verify a sender domain on
+  the Domains page, the same setup as for a web app; until then the code
+  email — the one email Gemmein sends on your behalf, and the only one —
+  arrives from Gemmein's shared address as "<App name> (via Gemmein)"; they buy on
+  the WEB, or the goods are not the store's → Stripe, the built-in path;
+  your app needs more sign-in codes than the two bounds allow → they are
+  abuse bounds, never a growth ceiling: 3 per address and 20 per IP per app,
+  each per 15 minutes, and how many sign-in emails an app sends in a day is
+  never capped; the store cannot keep the session (expo-secure-store not
+  installed, an unsigned simulator build with no keychain access group, or
+  a browser refusing the localStorage write)
+  → sign-in throws `secure_store_unavailable` rather than reporting a
+  session the app will lose; catch it and rebuild the client with a
+  `MemoryTokenStore`, which keeps the session for the life of the process.
+  Example — Expo:
+
+      import { createExpoGemmein } from "@gemmein/sdk/expo";
+      import { AppState, Platform } from "react-native";
+
+      export const g = createExpoGemmein(
+        { appKey: "pk_live_...", apiUrl: "http://127.0.0.1:4545" },  // apiUrl: local engine only
+        { AppState, Platform },
+      );
+
+      await g.auth.sendEmailCode(email);
+      await g.auth.verifyEmailCode({ email, code });
+      const { records } = await g.collection("notes").list({ limit: 20 });
+
+      const me = await g.auth.currentUser();
+      if (me.authenticated && me.storeAccountToken) {
+        // RevenueCat must know the buyer by this name
+        await Purchases.configure({ apiKey: RC_KEY, appUserID: me.storeAccountToken });
+        // already configured? Purchases.logIn(me.storeAccountToken)
+      }
+
+  The SECOND argument is the modules, and every key in it is optional:
+  `{ SecureStore, AppState, Platform, FileSystem, fetch }` — pass none and
+  the entry resolves `expo-secure-store`, `react-native`, `expo-file-system`
+  and `expo/fetch` lazily on first use; pass your own (an app's static
+  imports, a test's fakes) and they win, with no dynamic resolution at all.
+  Pass `Platform` and the client header reads `expo-ios` / `expo-android` /
+  `expo-web`; without it it reads `expo` — a report either way, never a
+  proof. Install the peers in the app, not the monorepo:
+  `npx expo install expo-secure-store expo-file-system`.
+  Example — Swift:
+
+      import GemmeinSwift
+
+      let g = try Gemmein(appKey: "pk_live_...")   // KeychainTokenStore by default
+
+      try await g.auth.sendEmailCode(email)
+      _ = try await g.auth.verifyEmailCode(email: email, code: code)
+      let page = try await g.collection("notes").list(ListOptions(limit: 20))
+
+      if let token = try await g.auth.currentUser().storeAccountToken {
+          Purchases.configure(withAPIKey: rcKey, appUserID: token)
+      }
+
+  Codes a phone meets most (the last one a browser meets too):
+  `network_unreachable`
+  (client-side, status 0 — the request never reached Gemmein; the message
+  names the host, `err.cause` carries the transport's own error, and a call
+  cancelled with `{ signal }` is not this) · `upload_input_unsupported`
+  (client-side, status 0 — `@gemmein/sdk/expo` `upload()` was handed a
+  picker's `{ uri }` and `expo-file-system` is not installed) ·
+  `token_too_large` (client-side, status 0 — a value over 2,048 bytes was
+  handed to the device secure store; a session token is far smaller, so
+  store the token, not the session payload) · `secure_store_unavailable`
+  (client-side, status 0 — the token store could not KEEP the session, on
+  ALL THREE of the SDK's stores: `expo-secure-store` is not installed or the
+  device refused the write, with the device's own error on `err.cause`; in
+  Swift the Keychain refused and the OSStatus is in the message, `-34018`
+  being an unsigned build with no keychain access group; and in a BROWSER
+  `BrowserTokenStore` throws it when `localStorage.setItem` is refused —
+  private mode past its quota, site data blocked, a sandboxed iframe. Reads
+  and clears stay lenient everywhere — an unreadable store means signed out.
+  The session is real, so an app can catch this one code and rebuild its
+  client with a `MemoryTokenStore`). `denied` (401 on
+  an anonymous read of a private collection) and `ai_not_configured` (409)
+  read the same as on the web.
+  Facts a phone build needs. A store purchase's credits arrive when
+  RevenueCat's webhook reaches the relay, which is AFTER the store's own
+  confirmation — show the pack as ARRIVING until the balance reads back,
+  never as failed. Uploads are sniffed from the bytes at confirm against
+  the file allow-list (images, PDF, ZIP, EPUB), so a `text/plain` blob is
+  refused `415 unsupported_file_type`. Point the app at a local engine with
+  `apiUrl` — it is an option on `createExpoGemmein`'s FIRST argument, beside
+  `appKey`, and `apiURL:` on Swift's `Gemmein(appKey:apiURL:)`. An iOS
+  simulator shares the Mac's network stack and reaches the engine at
+  `http://127.0.0.1:<port>`; an Android emulator reaches it at
+  `http://10.0.2.2:<port>` — `127.0.0.1`, inside the emulator, is
+  the emulator. `gemmein dev` binds `127.0.0.1`, which a simulator and a
+  current Android emulator both reach as it is. A REAL phone on the same
+  wifi does not, and neither does a second computer — serve those with
+  `npx gemmein dev --host 0.0.0.0`, an opt-in wider bind that prints its
+  own warning: reachable from every device on your network, and the
+  engine holds your app's data, its local server key and any AI provider
+  key in your shell. Presigned upload URLs and file links are always
+  re-addressed to the host the request arrived on, whichever bind is in
+  use, so a file the device uploads is a file it can fetch back. The
+  pricing unit does not change on a phone:
+  a person counts once a month, on their first signed-in request, on web
+  and mobile alike.
 - 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
@@ -1074,8 +1317,10 @@ contents.
   reaches every reader's network tab (silent-until-breach). `published` is
   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.
+  non-public rule is 400 invalid_publish — the OPTION works only on the two
+  public rules. The FIELD is on every record the engine returns, whatever
+  the rule: a private record reads `published: true`, and it is not
+  writable there — read it, never branch a private collection on it.
 - 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
@@ -1115,7 +1360,10 @@ contents.
   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;
+  conversation, customer replies land, and the owner writes to a customer
+  themselves — that mail leaves their own verified sender domain too, and
+  until one is verified the composer is refused sender_domain_required;
+  holding the billing band;
   running a relay: an inbound webhook from any provider that
   signs its calls, a schedule, or a record change → write a record,
   grant or revoke access, grant credits, fulfil or refund a product,
@@ -1127,7 +1375,7 @@ contents.
   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. A secret key can be SCOPED in the
-  dashboard's Keys room to particular collections, and to read-only or
+  dashboard's Secret keys page 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
@@ -1150,10 +1398,19 @@ rule. The specifics:
   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
+  `{ authenticated: true, userId, email, storeAccountToken? }` 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`.
+- `storeAccountToken` on that answer is the opaque per-person name to hand
+  a store: RevenueCat's app user id, Apple's `appAccountToken`, Google's
+  `obfuscatedExternalAccountId`. It is minted on the first `currentUser()`
+  call, stable for the life of the person, correlated to nothing, and gone
+  when they are erased. Hand a store THAT — never `userId`, never the
+  address: a value inside a third party's ledger is outside the erasure
+  cascade. An engine that does not carry one leaves the field absent; read
+  that as "not carried", never as "no account".
 - `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
@@ -1162,6 +1419,35 @@ rule. The specifics:
   is no `signOut`.
 - Errors throw a `GemmeinError` with `.status`, `.code`, `.message`, and
   `.resetAt` (on 429). Branch on **`err.code`**; render `err.message`.
+- A request that never reached Gemmein — no connection, an offline device, an
+  `apiUrl` pointing at nothing — throws a `GemmeinError` too:
+  `network_unreachable`, status 0, its message naming the host and
+  `err.cause` carrying the transport's own error. "The server said no" and
+  "the server was never reached" are different problems: branch on them
+  separately, and keep the app usable for the second. A call cancelled with
+  `{ signal }` is neither — it stays an `AbortError`.
+- `await g.auth.logout()` is idempotent: a session the owner already ended
+  everywhere resolves rather than throwing, because the session being gone is
+  what logout asked for. The stored token is cleared either way.
+- `gemmein(pk, options?)` takes `apiUrl`, `tokenStore`, and the three a
+  non-browser runtime needs: `fetch` (used for EVERY request this client
+  makes, in place of `globalThis.fetch`), `visibility`
+  (`{ isHidden(): boolean; onChange(cb): () => void }`, where `watch()`
+  learns the app went to the background, in place of
+  `document.visibilityState`) and `platform` (a tag appended to the
+  `x-client-info` header — `gemmein-sdk/<version> expo-ios`, cleaned and
+  capped to 64 characters). `createExpoGemmein` from `@gemmein/sdk/expo`
+  fills all four in for a phone, and every one of them is overridable.
+  `GemmeinSwift` is the Swift package: `Gemmein(appKey:)`, the same method
+  names, `KeychainTokenStore` by default. The DEFAULT store in a browser is
+  `BrowserTokenStore` (localStorage, keyed per app key), and a store that
+  cannot KEEP the session throws `secure_store_unavailable` out of
+  `verifyEmailCode` on all three — reads and clears stay lenient.
+- On Expo, `createExpoGemmein` from `@gemmein/sdk/expo` accepts a picker's
+  `{ uri, name, type, size }` in `upload()` and turns it into an
+  `expo-file-system` `File` first — install `expo-file-system` beside
+  `expo-secure-store`, or that one call throws
+  `upload_input_unsupported`. A `Blob` or a `File` needs neither.
 - `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
@@ -1207,9 +1493,9 @@ enforces — never because these checks are the enforcement.
 - Development is free indefinitely — no card at signup, unlimited
   collections, the full security model included.
 - Going live starts the one Live plan: a monthly price that moves within a
-  pre-agreed band, set by the PREVIOUS calendar month's verified people
-  (a person = a unique end-user identity that verified a sign-in to the
-  live app that month; failed or refused attempts never count):
+  pre-agreed band, set by the PREVIOUS calendar month's active people
+  (a person counts once a month, on their first signed-in request, on web
+  and mobile alike; anonymous use never counts):
   - up to 1,000 people → $50/mo · up to 2,500 → $75 · up to 5,000 → $100
     · up to 7,500 → $125 · up to 10,000 → $150 (the cap — never exceeded
     without a separate individual agreement).
@@ -1220,7 +1506,7 @@ enforces — never because these checks are the enforcement.
   priced as a relationship, not a checkout.
 - Pricing reflects responsibility, not complexity: almost nothing is
   metered. Safe limits exist as safety rails against runaway scripts and
-  are never billed. Ceilings follow the app's verified people — they grow
+  are never billed. Ceilings follow the app's active people — they grow
   automatically as the business grows, with generous floors so a small app
   never starts at a wall. Reaching a ceiling never stops your app: sign-ins,
   writes and API requests keep working past it, the founder is told once

package/migrations/README.md

@@ -34,3 +34,4 @@ the same surface gets its own file.
 |------|-------|--------------------|
 | [`list-limit-refusal.md`](./list-limit-refusal.md) | 0.6.0 | 0.6.0 |
 | [`raw-calls-off.md`](./raw-calls-off.md) | 0.9.0 | 0.9.0 |
+| [`secure-store-set-throws.md`](./secure-store-set-throws.md) | 0.10.0 | 0.10.0 |

package/migrations/secure-store-set-throws.md

@@ -0,0 +1,75 @@
+# A token store that cannot keep the session says so
+
+```
+Since: 0.10.0
+Action required by: 0.10.0
+```
+
+## What changed
+
+Before 0.10.0 a token store that could not write swallowed the failure.
+`auth.verifyEmailCode()` resolved, the app believed it was signed in, and the
+session was gone on the next read — the app reported itself signed out with
+nothing anywhere saying why.
+
+From 0.10.0 `tokenStore.set()` THROWS a `GemmeinError` with code
+`secure_store_unavailable` (status 0) when the store refuses the write, and
+`auth.verifyEmailCode()` carries it to the caller. The law is all three
+stores:
+
+- `SecureStoreTokenStore` (`@gemmein/sdk/expo`) — `expo-secure-store` missing
+  or refusing (an unsigned simulator build has no keychain access group).
+- `BrowserTokenStore` — a refused `localStorage` write: Safari private mode
+  past its quota, a browser set to block site data, a sandboxed iframe whose
+  access throws.
+- `KeychainTokenStore` (`GemmeinSwift`) — the same, with the OSStatus and
+  `SecCopyErrorMessageString`'s words for it in the sentence.
+
+The device's or browser's own error is on `err.cause`. `get()` and `clear()`
+are unchanged and stay lenient: an unreadable store means signed out, which
+every app already handles, and a crash at launch is worse than a sign-in
+screen. `MemoryTokenStore.set()` never throws. The existing `token_too_large`
+refusal is unchanged.
+
+## Who is affected
+
+Apps that call `auth.verifyEmailCode()` (or any call that stores a session)
+in a place where the store may refuse the write, and that RELIED on the old
+silence to keep running: a kiosk browser, an embedded or sandboxed iframe, a
+private-mode visitor, an unsigned simulator or ad-hoc mobile build. An app in
+an ordinary browser tab or a signed app sees no difference — nothing that
+stored the token before throws now.
+
+## What to do
+
+Catch the one code and rebuild the client with a `MemoryTokenStore`. The
+session is real either way — the server minted it — so an app that would
+rather run than stop can carry it in memory: sign-in works, and ends with the
+process.
+
+```ts
+import { gemmein, MemoryTokenStore, GemmeinError } from "@gemmein/sdk";
+
+let g = gemmein({ appKey });
+try {
+  await g.auth.verifyEmailCode(email, code);
+} catch (err) {
+  if (err instanceof GemmeinError && err.code === "secure_store_unavailable") {
+    // This session will not survive a reload. Say so, or carry on knowingly.
+    g = gemmein({ appKey, tokenStore: new MemoryTokenStore() });
+    await g.auth.verifyEmailCode(email, code);
+  } else {
+    throw err;
+  }
+}
+```
+
+An app that knows it runs where nothing can be stored passes
+`tokenStore: new MemoryTokenStore()` from the start and never sees the code.
+
+## How to tell
+
+`err.code === "secure_store_unavailable"` on the SDK (status 0, no HTTP
+response — the request succeeded; the STORE refused), with the store's own
+throw on `err.cause` and the fix in the message. In `GemmeinSwift` the same
+case is a thrown `GemmeinError` whose message carries the keychain's OSStatus.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.9.0",
+  "version": "0.10.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",
@@ -13,6 +13,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./expo": {
+      "types": "./dist/expo.d.ts",
+      "import": "./dist/expo.js",
+      "require": "./dist/expo.cjs"
+    },
     "./llms.txt": "./llms.txt",
     "./REFERENCE.md": "./REFERENCE.md",
     "./reaffirm.mjs": "./reaffirm.mjs",
@@ -27,6 +32,22 @@
     "reaffirm.mjs"
   ],
   "sideEffects": false,
+  "peerDependencies": {
+    "expo": "*",
+    "expo-secure-store": "*",
+    "react-native": "*"
+  },
+  "peerDependenciesMeta": {
+    "expo": {
+      "optional": true
+    },
+    "expo-secure-store": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=20"
   },
@@ -49,7 +70,7 @@
   "scripts": {
     "version:sync": "node scripts/sync-version.mjs",
     "prebuild": "node scripts/sync-version.mjs",
-    "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",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsc -p tsconfig.cjs.json && mv dist/cjs/index.js dist/index.cjs && mv dist/cjs/expo.js dist/expo.cjs && rm -rf dist/cjs && sed -i.bak 's#\"./index.js\"#\"./index.cjs\"#g' dist/expo.cjs && rm -f dist/expo.cjs.bak && cp dist/index.d.ts dist/index.d.cts && cp dist/expo.d.ts dist/expo.d.cts",
     "prepack": "npm run build",
     "prepublishOnly": "npm run build"
   },