@gemmein/sdk 0.9.0 → 0.10.0

package/REFERENCE.md

@@ -1,6 +1,8 @@
 # Gemmein SDK — API Reference
 
-Complete surface of `@gemmein/sdk`, generated from the type definitions.
+Complete surface of `@gemmein/sdk`, generated from the type definitions —
+with, beside each JavaScript method, the `GemmeinSwift` signature and return
+type for the same method, and everything `@gemmein/sdk/expo` adds.
 This is the **reference** (every method, signature, return shape, error);
 `llms.txt` is the **guide** (how the model works and the safe patterns). Both
 are needed. Draft — feeds docs.gemmein.com.
@@ -16,9 +18,45 @@ const g = gemmein("pk_...");        // browser: your public app key (domain-lock
 
 ### `gemmein(appKey, options?) → Gemmein`
 The browser client. `appKey` is your public `pk_...` key. `options` (optional):
-`{ apiUrl?: string, tokenStore?: TokenStore }`. Throws `GemmeinError`
+`{ apiUrl?: string, tokenStore?: TokenStore, fetch?: typeof fetch, visibility?: VisibilityHook, platform?: string }`.
+Throws `GemmeinError`
 (`missing_app_key` / `invalid_app_key`) if the key is absent or an `sk_`.
 
+The last three are what a non-browser runtime needs and a browser never passes.
+`fetch` is used for **every** request this client makes, in place of
+`globalThis.fetch`. `visibility`
+(`{ isHidden(): boolean; onChange(cb: () => void): () => void }`) is where
+`watch()` learns the app went to the background, in place of
+`document.visibilityState`; `onChange` returns its own unsubscribe. `platform`
+is appended to the `x-client-info` header — `gemmein-sdk/<version> expo-ios` —
+cleaned and capped to the 64 characters the usage ledger stores.
+
+On Expo, `createExpoGemmein` from `@gemmein/sdk/expo` fills those three in for
+a phone, and turns `upload()`'s picker shape into bytes Expo's fetch will
+send. Every export that entry adds is in **Expo** below.
+
+### `Gemmein(appKey:) → GemmeinSwift.Gemmein`
+The Swift package, for iOS 17+ and macOS 14+, with no dependencies:
+`.package(url: "https://github.com/gemmeinhq/gemmein-swift.git", from: "0.10.0")`.
+The same HTTP contract and the same method names as `@gemmein/sdk`, in Swift
+idiom — `g.auth`, `g.collection(_:)`, `g.files`, `g.subscriptions`,
+`g.payments`, `g.purchases`, `g.account`, `g.credits`, `g.ai`, and
+`GemmeinServer` for Swift that runs on a server.
+
+```swift
+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))
+let me = try await g.auth.currentUser()    // .storeAccountToken for RevenueCat
+```
+
+An `sk_` key is refused here, as in the browser. Every Swift signature sits
+beside its JavaScript twin in the sections below, under **Swift**; the client's
+own initialiser, the shapes that differ, and the session store are in **Swift —
+the package**.
+
 ### `gemmeinServer(secretKey, options?) → GemmeinServer`
 Server-only client for a `sk_...` secret key — **never ship this to the
 browser.** `options` (optional): `{ apiUrl?: string }` — **the option is
@@ -49,12 +87,32 @@ happens in the owner's dashboard, deliberately not in this SDK.
 | `currentUser` | `()` | `Promise<CurrentUser>` — **never throws** for session state; safe on load |
 | `logout` | `()` | `Promise<void>` — revokes the server session **(the method is `logout`, not `signOut`)** |
 
+
+**Swift.** `GemmeinSwift` names the same four methods, with Swift's argument
+labels. Everything that leaves the device is `async throws` and throws
+`GemmeinError`.
+
+| Swift | Signature | Returns |
+|---|---|---|
+| `sendEmailCode(_:)` | `func sendEmailCode(_ email: String) async throws` | `Void` |
+| `verifyEmailCode(email:code:)` | `func verifyEmailCode(email: String, code: String) async throws -> AuthSession` | `AuthSession { token: String, expiresAt: String, user: AuthUser }` |
+| `currentUser()` | `func currentUser() async throws -> CurrentUser` | `CurrentUser { authenticated: Bool, userId: String?, email: String?, storeAccountToken: String? }` — one struct with optionals where JS has a union: read `authenticated` first, then the rest |
+| `logout()` | `func logout() async throws` | `Void` — idempotent |
+
 ```ts
 type AuthSession = { token: string; expiresAt: string; user: { id: string; email: string } };
 type CurrentUser =
-  | { authenticated: true;  userId: string; email: string }   // note: userId, NOT id
-  | { authenticated: false; userId?: undefined; email?: undefined };
+  | { authenticated: true;  userId: string; email: string; storeAccountToken?: string | null }   // note: userId, NOT id
+  | { authenticated: false; userId?: undefined; email?: undefined; storeAccountToken?: undefined };
 ```
+`storeAccountToken` 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` and 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". See
+**Mobile** below.
 `verifyEmailCode` resolves the **session** (`user.id`, nested). `currentUser`
 resolves the **identity** (`userId`, flat). Use `currentUser()` for who's
 signed in. Sessions are one-per-user: verifying a new code revokes older ones.
@@ -72,6 +130,11 @@ screen covers all three.
 |--------|-----------|---------|
 | `delete` | `()` | `Promise<unknown>` — erases the signed-in user, clears the stored token |
 
+
+| Swift | Signature | Returns |
+|---|---|---|
+| `delete()` | `@discardableResult func delete() async throws -> JSONValue?` | `JSONValue?` — the server's body as a `JSONValue?` where JS has `unknown`; `@discardableResult`, so ignoring it is legal |
+
 The "delete my account" screen. Every app it **applies** to needs one (GDPR
 right to erasure; Apple 5.1.1(v) for any app with account creation).
 Server-side it's the full cascade — sessions revoked, records and files
@@ -103,15 +166,46 @@ certain the collection exists yet.
 | `delete` | `(id: string)` | `Promise<void>` |
 | `upload` | `(file: Blob \| File, options?: { name?: string; contentType?: string; for?: string })` | `Promise<{ id: string; ref: FileRef; contentType: string; sizeBytes: number }>` |
 
+
+**Swift.** The same seven methods. Three shapes differ on purpose: a record
+body is `[String: JSONValue]` (a literal needs no ceremony —
+`["title": "Ran", "done": false]` — a variable needs its case,
+`["title": .string(typed)]`); `upload` takes `Data`, not a `Blob`; and `watch`
+is not `async` — it hands back a `Watcher` you end with `stop()`.
+
+| Swift | Signature | Returns |
+|---|---|---|
+| `create(_:key:for:published:)` | `@discardableResult func create(_ data: [String: JSONValue], key: String? = nil, for recipient: String? = nil, published: Bool? = nil) async throws -> GemmeinRecord` | `GemmeinRecord` |
+| `list(_:)` | `func list(_ options: ListOptions = ListOptions()) async throws -> ListResult` | `ListResult { records: [GemmeinRecord], cursor: String?, hasMore: Bool, deleted: [String], watermark: String? }` |
+| `watch(every:where:search:limit:onChange:)` | `func watch(every: TimeInterval? = nil, where filter: [String: JSONValue]? = nil, search: String? = nil, limit: Int? = nil, onChange: @escaping @Sendable (WatchDelta) -> Void) -> Watcher` | `Watcher` — **not `async`**; `watcher.stop()` ends it. `WatchDelta { records: [GemmeinRecord], deleted: [String], initial: Bool }` |
+| `get(_:expand:)` | `func get(_ id: String, expand: [String] = []) async throws -> GemmeinRecord` | `GemmeinRecord` |
+| `update(_:_:ifVersion:published:)` | `@discardableResult func update(_ id: String, _ data: [String: JSONValue], ifVersion: Int? = nil, published: Bool? = nil) async throws -> GemmeinRecord` | `GemmeinRecord` |
+| `delete(_:)` | `func delete(_ id: String) async throws` | `Void` |
+| `upload(_:name:contentType:for:)` | `func upload(_ data: Data, name: String = "upload", contentType: String = "", for recipient: String? = nil) async throws -> UploadedFile` | `UploadedFile { id: String, ref: String, contentType: String, sizeBytes: Int }` — `ref` is `file:<uuid>` |
+
+`ListOptions(limit:sort:where:cursor:search:expand:since:)` — every argument
+optional, `sort` is `ListSort` (`.newest`, `.oldest`, `.updated`), and `where`
+keeps the label `where`, binding a `[String: JSONValue]`. `GemmeinRecord`
+carries `id`, `data: [String: JSONValue]`, `createdAt`, `updatedAt`,
+`ownerUserId: String?`, `collectionId`, `appId`, `environmentId`,
+`version: Int`, `key: String?`, `audienceUserId: String?`, `published: Bool`,
+`expand: [String: GemmeinRecord?]` and `existing: Bool?` — your fields live
+under `data`, read as `note.data["title"]?.string`.
+
 ### Files
 
-`upload()` returns a **reference** (`file:01K…`), not a URL. Store the reference
+`upload()` returns a **reference** (`file:<uuid>`), not a URL. Store the reference
 in your record — it never expires and grants nothing on its own.
 
 | Method | Signature | Returns |
 |--------|-----------|---------|
 | `g.files.link` | `(ref: FileRef \| string, options?: { intent?: "inline" \| "download" })` | `Promise<{ ref, url, expiresAt?, contentType, sizeBytes?, name? }>` |
 
+
+| Swift | Signature | Returns |
+|---|---|---|
+| `g.files.link(_:intent:)` | `func link(_ ref: String, intent: LinkIntent? = nil) async throws -> FileLink` | `FileLink { ref: String, url: String, expiresAt: String?, contentType: String, sizeBytes: Int?, name: String? }` — **`url` is a `String`**, not a `URL`: pass it through `URL(string:)` before handing it to `AsyncImage`. `intent` is `.inline` or `.download` |
+
 ```ts
 const { ref } = await g.collection("films").upload(file)
 await g.collection("films").create({ title, poster: ref })
@@ -172,7 +266,7 @@ type GemmeinRecord<T> = {
   version: number;             // +1 per update; pass as { ifVersion } to guard concurrent edits
   key?: string;                // the create-if-absent key, when one was used
   audienceUserId?: string;     // recipient on addressed/direct collections (server-stamped)
-  published: boolean;          // top-level, not under .data; only meaningful on public rules
+  published: boolean;          // top-level, not under .data; on EVERY record — a private record reads true
   expand?: Record<string, GemmeinRecord | null>;  // filled by list/get { expand: [...] }
   existing?: true;             // present only when a keyed create returned YOUR existing record
 };
@@ -201,7 +295,9 @@ 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*
+rule; the OPTION is refused anywhere else (400 `invalid_publish`), while the
+FIELD comes back on every record — a private record reads `published: true`,
+and it is not writable there. `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
@@ -233,6 +329,17 @@ Never hand-roll a polling loop; this is the sanctioned one.
 | `payments.buy` | `(product: string, options?: { item?: string })` | `Promise<{ url: string; product: string; item?: string }>` — **navigates the browser to Stripe** and resolves the url |
 | `purchases.mine` | `()` | `Promise<Purchase[]>` — the array itself (not wrapped): `{ item, kind, amountMinor, currency, refundedMinor, status, grants, paidAt, delivery? }` — gate one-off fulfilment on this, never the redirect |
 
+
+**Swift.** Nothing navigates: `checkout` and `buy` answer a url and the app
+opens it (`openURL`, `SFSafariViewController`).
+
+| Swift | Signature | Returns |
+|---|---|---|
+| `g.subscriptions.mine()` | `func mine() async throws -> Subscription?` | `Subscription? { plan: String, status: String }` — `nil` when they never paid |
+| `g.subscriptions.checkout(plan:)` | `func checkout(plan: String? = nil) async throws -> CheckoutSession` | `CheckoutSession { url: String, plan: String }` |
+| `g.payments.buy(_:item:)` | `func buy(_ product: String, item: String? = nil) async throws -> PaymentSession` | `PaymentSession { url: String, product: String, item: String? }` |
+| `g.purchases.mine()` | `func mine() async throws -> [Purchase]` | `[Purchase]` — `item`, `kind`, `amountMinor: Int?`, `currency: String?`, `refundedMinor: Int`, `status`, `grants: [String]`, `paidAt`, `delivery: Purchase.Delivery?` (`.gemmeinFile(String)` or `.externalURL(String)` — an enum where JS has a tagged object) |
+
 Plans are `g.subscriptions`; one-off things are `g.payments`. `checkout` and
 `buy` self-navigate via `window.location` — just `await` them on the click;
 don't also redirect to the returned `url`, and never build a Stripe URL
@@ -278,6 +385,14 @@ honestly, not hidden.)
   carries a footer naming why it arrived; replies land in the owner's Inbox
   as a thread (`threadId`), and `replyRail` states honestly whether
   reply-by-email is on. Every send is on the record.
+- **Your domain, or nothing.** `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
+  the provider refuses that address at send time you get `502 send_failed`
+  and can retry; the email is never 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)`.
 
 ---
 
@@ -297,6 +412,12 @@ the message), never partly. No expiry. No per-token pricing.
 | `gemmeinServer(sk).spendCredits` | `(personId, { amount?: number; reason: string; key?: string })` | `Promise<{ ok: true; spent: number; deduped: boolean; balance: { before: number; after: number }; event: { id, reason, actor } }>` — `amount` defaults to 1 (1..10,000); `reason` ≤ 200 chars is what the owner reads on the person's ledger; `key` makes the spend at-most-once per person (a repeat answers `deduped: true`, `spent: 0`, the same `event`, and moves nothing; one key reused for a second person charges that person). Needs **"Spend a person's credits"** ticked on the key (`403 capability_required` otherwise) |
 | `Holdings.credits` | — | `{ balance: number }` on `verifySession()` and `holdings()` from engine 0.8.0 (`null` from an older local engine) — one verify answers who, what they hold and how many |
 
+
+| Swift | Signature | Returns |
+|---|---|---|
+| `g.credits.balance()` | `func balance() async throws -> Int` | **`Int`** — the balance itself, where JS answers `{ balance }`. Read it directly |
+| `gemmeinServer(sk).spendCredits` | `@discardableResult func spendCredits(_ personId: String, amount: Int? = nil, reason: String, key: String? = nil) async throws -> SpendCreditsResult` | `SpendCreditsResult { spent: Int, deduped: Bool, balanceBefore: Int, balanceAfter: Int, event: Event }` — two flat `Int`s where JS nests `balance: { before, after }` |
+
 Where credits come from, and where they go:
 
 - **A product with `grantsCredits`** (the "Grants credits" field on the
@@ -376,6 +497,26 @@ development, sync also writes a tool that exists only in the cloud back to
 A tool's name is fixed once created. Removing a tool is a step-up action, like
 removing a key.
 
+
+**Swift.** `AiResponse` stands where JS returns the fetch `Response`, and
+`run` / `runText` take the label **`inputs:`** —
+`runText("summary", inputs: ["text": .string(body)])`.
+
+| Swift | Signature | Returns |
+|---|---|---|
+| `run(_:inputs:stream:)` | `func run(_ tool: String, inputs: [String: JSONValue] = [:], stream: Bool = false) async throws -> AiResponse` | `AiResponse` — `stream` is a plain `Bool` argument, not an options object |
+| `runText(_:inputs:)` | `func runText(_ tool: String, inputs: [String: JSONValue] = [:]) async throws -> String` | `String` — the label is **`inputs:`** |
+| `calls(limit:before:)` | `func calls(limit: Int? = nil, before: String? = nil) async throws -> AiCallPage` | `AiCallPage { calls: [AiCallRecord], nextCursor: String? }` |
+| `chat(_:provider:tool:)` | `func chat(_ body: [String: JSONValue], provider: AiProvider? = nil, tool: String? = nil) async throws -> AiResponse` | `AiResponse` |
+| `text(_:provider:tool:)` | `func text(_ body: [String: JSONValue], provider: AiProvider? = nil, tool: String? = nil) async throws -> String` | `String` |
+
+`AiResponse` carries `status: Int`, `headers: [String: String]`, `ok: Bool`,
+`creditsRemaining: Int?`, `refunded: Bool`, `tool: String?`, `isFake: Bool`,
+`func data() async throws -> Data`, and two streams —
+`func lines() -> AsyncThrowingStream<String, Error>` and
+`func events() -> AsyncThrowingStream<String, Error>` (the SSE `data:`
+payloads). `AiProvider` is `.openai`, `.anthropic`, `.google`.
+
 **Raw calls are off by default.** `g.ai.chat(body)` — the browser sending
 the provider's own request body — answers `403 raw_calls_off` unless the
 owner switches **raw calls** on for that provider's key on the AI tools page. Behind the switch, the raw route is what it always was: the body is
@@ -502,11 +643,10 @@ const raw = await g.ai.chat({ model: "gpt-4o-mini", stream: true, messages: [{ r
 | `tool_disabled` | 403 | The owner switched this tool off — turn it on, or use another |
 | `entitlement_required` | 403 | The tool's `requires` names a plan or product this person lacks — the message names it |
 | `model_pinned` | 403 | This tool's model is fixed — leave `model` out of the body |
-| `provider_not_configured` | 409 | Creating or updating a tool: no key is set for that provider yet — add one on the AI tools page first |
 | `too_many_tools` | 409 | This environment already holds 50 AI tools — delete one before adding another |
 | `invalid_tool` | 400 | Creating or updating a tool with a bad field — the message names which one and its rule |
 | `credits_exhausted` | 402 | The person's balance is below the tool's price — the message names the tool, the price and the balance ("Deep Research costs 20 credits. You have 7.", singular for 1). Show the pack |
-| `ai_not_configured` | 409 | No provider key on this app and environment — the owner pastes one on the AI tools page |
+| `ai_not_configured` | 409 | No provider key on this app and environment — the owner pastes one on the AI tools page. A tool can be defined before its key exists; it runs the moment the key is pasted, and the console shows it as waiting on one until then |
 | `provider_required` | 400 | More than one provider key is set — pass `provider` |
 | `model_not_allowed` | 403 | The owner's allowlist names the models this app may call; the message lists them (only for a tool with no pinned model) |
 | `ai_capped` | 429 | 20 calls per person per minute — wait for `resetAt` |
@@ -522,7 +662,7 @@ const raw = await g.ai.chat({ model: "gpt-4o-mini", stream: true, messages: [{ r
 `gemmein dev` answers a fake provider without a key (header `x-gemmein-ai:
 fake`, an echo stream), so the loop runs locally; set
 `GEMMEIN_AI_KEY_OPENAI`, `GEMMEIN_AI_KEY_ANTHROPIC` or `GEMMEIN_AI_KEY_GOOGLE`
-in the local rail's environment for a real call. The owner's Usage room
+in the local rail's environment for a real call. The owner's Usage & billing page
 counts AI calls for the last 30 days: spent by the customers' credits, priced
 by the provider — Gemmein meters the calls, the provider bills the tokens.
 
@@ -542,6 +682,32 @@ signed in, it can create them by email first.
 | `grantAccess` | `(personId, { entitlement, source?, expiresAt?, reason? })` | `Promise<{ ok: true, grant: Grant, holdings: Holdings }>` (201) — `holdings` is the state **after**; the owner's audit row carries before→after and the key's name |
 | `revokeAccess` | `(personId, grantId, { reason? }?)` | `Promise<{ ok: true, grant: Grant, holdings: Holdings }>` — the returned grant carries `revokedAt` |
 | `invitePerson` | `(email)` | `Promise<{ person: InvitedPerson, created: boolean }>` — create a person by email **before they sign in** (201 `created: true`), or find them (200 `created: false`); idempotent, case-insensitive, one id. `InvitedPerson = { id, email, role, invited, suspended }` — `invited` stays true until their first sign-in; a suspended person is returned flagged. The one server call that takes an email |
+| `notify` | `(personId, { subject, text, kind?, key? })` | `Promise<{ sent, deduped?, recorded?, id, threadId, replyRail? }>` — email one of your verified people by id; see **Notify** above |
+| `spendCredits` | `(personId, { amount?, reason, key? })` | `Promise<{ ok, spent, deduped, balance: { before, after }, event }>` — one conditional decrement, floored at zero; see **Credits** above |
+| `collection(name).get / .list / .update` | `(as the browser client)` | scoped per collection on the key; no creates, no deletes, no auth access; see **Setup** |
+| `testSession` | `(email)` | `Promise<{ token, expiresAt, user }>` — development only; `sk_live` throws `test_session_forbidden_live`; see **Reaffirm** below |
+
+
+**Swift.** `GemmeinServer` ships in the Swift package for Swift that runs on a
+server. It takes a secret key, and a secret key never belongs in an app bundle
+— `Gemmein` refuses one.
+
+| Swift | Signature | Returns |
+|---|---|---|
+| `verifySession(_:)` | `func verifySession(_ token: String) async throws -> PersonHoldings` | `PersonHoldings { person: GatePerson, holdings: Holdings }` — no `ok` field; a refusal throws |
+| `holdings(_:)` | `func holdings(_ personId: String) async throws -> PersonHoldings` | `PersonHoldings` |
+| `grantAccess(_:entitlement:source:expiresAt:reason:)` | `@discardableResult func grantAccess(_ personId: String, entitlement: String, source: ManualGrantSource? = nil, expiresAt: String? = nil, reason: String? = nil) async throws -> GrantResult` | `GrantResult { grant: Grant, holdings: Holdings }` |
+| `revokeAccess(_:_:reason:)` | `@discardableResult func revokeAccess(_ personId: String, grantId: String, reason: String? = nil) async throws -> GrantResult` | `GrantResult` |
+| `invitePerson(_:)` | `func invitePerson(_ email: String) async throws -> InviteResult` | `InviteResult { person: GatePerson, created: Bool }` |
+| `notify(_:subject:text:kind:key:)` | `@discardableResult func notify(_ personId: String, subject: String, text: String, kind: NotifyKind? = nil, key: String? = nil) async throws -> NotifyResult` | `NotifyResult { sent: Bool, deduped: Bool?, id: String?, threadId: String?, replyRail: Bool?, recorded: Bool? }` — `subject` and `text` are required labels, not an options object |
+| `spendCredits(_:amount:reason:key:)` | see **Credits** above | `SpendCreditsResult` |
+| `collection(_:)` | `func collection(_ name: String) throws -> ServerCollectionClient` | `ServerCollectionClient` — `func get(_ id: String) async throws -> GemmeinRecord`, `func list(_ options: ListOptions = ListOptions()) async throws -> ListResult`, `@discardableResult func update(_ id: String, _ data: [String: JSONValue]) async throws -> GemmeinRecord` |
+| `testSession(_:)` | `func testSession(_ email: String) async throws -> AuthSession` | `AuthSession` — development only |
+
+`GatePerson { id: String, email: String, role: String, suspended: Bool?, invited: Bool? }`,
+`Holdings { access: [String], grants: [Grant], credits: Int? }` — a bare `Int?`
+where JS nests `{ balance }`. `ManualGrantSource` is `.manual`, `.trial`,
+`.promotion`, `.migration`; `NotifyKind` is `.event` or `.account`.
 
 ```ts
 type Holdings = {
@@ -595,7 +761,7 @@ type Grant = {
   make two grants — call it once and keep your own retry key.
 - **Nothing silent, within a stated bound.** Every `/server/*` call a **resolved
   secret key** makes, ok or refused, lands in that key's usage ledger — the owner
-  reads the summary on their Keys page and the full day × route × outcome table in
+  reads the summary on their Secret keys page and the full day × route × outcome table in
   the key's own room. A rejected or publishable (`pk_`) key can't be attributed to a
   key row, so its refusal reaches only the request log. Refusals also write one audit
   row per key, route and code each hour (exact counts stay in the ledger); grants and
@@ -740,7 +906,7 @@ authorise on fields they cannot set, or from a receiver.
 | `revoke_access` | `entitlement` | ends every live grant of that entitlement the person holds; skipped when none |
 | `fulfil_product` | `product` (name, 1-40 chars), `ref?` (≤ 200, templated) | grants the product's key and credits to the event's person and writes the receipt, exactly as a Stripe purchase does; idempotent on `ref` (an absent `ref` → `rly:<eventId>`; a `ref` you wrote that names nothing on the event is refused, never replaced); a ref must be the provider's unique payment identifier; a ref already used by another purchase is refused and audited; the product's road must be this relay. The relay road binds by name: renaming or deleting the relay stops fulfilment until a relay with that name exists again; the product card shows it. |
 | `refund_product` | `product` (name, 1-40 chars), `ref?` (≤ 200, templated) | takes back what `fulfil_product` under the same `ref` granted; `refund_product` may run from any relay in the environment; it refunds only a purchase a relay fulfilled, for the event's person and the product it names; idempotent on `ref` |
-| `email_person` | `subject` (≤ 300), `text` (≤ 10,000), `kind?: "event" \| "account"` | rides `notify()`'s caps (200 per app per hour, 5 event sends per person per day) and the owner's sends switch; deduped per event |
+| `email_person` | `subject` (≤ 300), `text` (≤ 10,000), `kind?: "event" \| "account"` | rides `notify()`'s caps (200 per app per hour, 5 event sends per person per day) and the owner's sends switch; deduped per event; and rides `notify()`'s sender law — it goes only from your verified sender domain, and until one is verified this action alone is refused `sender_domain_required` and the event's result says so. Nothing is sent via Gemmein |
 | `call_url` | `url` | https only, no template in the URL, no IP literal, never a gemmein.com host, no credentials in the URL; `gemmein dev` allows http to localhost |
 
 **The `call_url` contract.** Gemmein POSTs JSON:
@@ -896,6 +1062,102 @@ current. Add a probe whenever you add a feature.
 
 ---
 
+## Swift — the package
+
+`GemmeinSwift` is the same HTTP contract and the same method names as
+`@gemmein/sdk`, in Swift idiom, for iOS 17+ and macOS 14+, with no
+dependencies:
+
+```swift
+.package(url: "https://github.com/gemmeinhq/gemmein-swift.git", from: "0.10.0")
+```
+
+Every method is beside its JavaScript twin in the sections above, under
+**Swift**. Argument labels are as written there; everything that leaves the
+device is `async throws` and throws `GemmeinError`. The parity check
+(`tests/security/sdkParity.test.ts`) holds the two method lists equal and
+`tests/security/docsSwiftReference.test.ts` holds every signature on this page
+to the package's own source, so a signature here is the signature the compiler
+sees.
+
+```swift
+let g = try Gemmein(appKey: "pk_live_…")
+let notes = try g.collection("notes")
+let page = try await notes.list(ListOptions(limit: 20, sort: .newest))
+let note = try await notes.create(["title": .string(typed), "done": false])
+```
+
+### The client
+
+| Swift | Signature | Returns |
+|---|---|---|
+| `Gemmein(appKey:…)` | `init(appKey: String, apiURL: URL = defaultAPIURL, tokenStore: TokenStore? = nil, platform: String? = nil, session: URLSession = .shared) throws` | `Gemmein` — throws `invalid_app_key` on an `sk_`, `missing_app_key` on anything that is not a `pk_` |
+| `g.collection(_:intent:)` | `func collection(_ name: String, intent: String? = nil) throws -> CollectionClient` | `CollectionClient` — `g.storage.collection(_:intent:)` is the same factory, the same signature |
+| `GemmeinServer(secretKey:…)` | `init(secretKey: String, apiURL: URL = defaultAPIURL, session: URLSession = .shared) throws` | `GemmeinServer` — see **Server gate** above |
+
+`apiURL` points at a local `gemmein dev` engine while you build; `tokenStore`
+defaults to `KeychainTokenStore`, so a relaunch keeps the person signed in;
+`platform` defaults to this OS and is appended to `x-client-info`.
+`g.auth`, `g.storage`, `g.subscriptions`, `g.payments`, `g.purchases`,
+`g.account`, `g.files`, `g.credits`, `g.ai` and `g.tokenStore` are `public let`
+properties on `Gemmein`.
+
+### The three shapes that differ from JavaScript
+
+- `credits.balance()` answers a bare **`Int`** — the number itself, not a
+  `{ balance }` wrapper.
+- `files.link(_:)` answers a `FileLink` whose `url` is a **`String`**; pass it
+  through `URL(string:)` before `AsyncImage`.
+- A record body and an AI body are `[String: JSONValue]`. A **literal** needs
+  no ceremony (`["title": "Ran", "done": false, "seats": 4]`); a **variable**
+  needs its case (`["title": .string(typed), "seats": .int(count)]`).
+
+### The session store
+
+`TokenStore` is a protocol — `func get() async -> String?`,
+`func set(_ token: String) async throws`, `func clear() async`.
+`KeychainTokenStore(appKey:)` is the default and `MemoryTokenStore(token:)` is
+there for tests and for the app that catches `secure_store_unavailable`.
+Only `set` throws, on all three of the SDK's stores.
+
+Everything the package throws is a `GemmeinError`
+(`status: Int`, `code: String`, `message: String`, `resetAt: String?`,
+`requires: String?`) — the same table below.
+
+---
+
+## Expo — `@gemmein/sdk/expo`
+
+The same package, a second entry point. `export *` re-exports the whole core
+surface, so an Expo app imports from one place; what follows is everything the
+entry adds. The peers install in the app, not in your monorepo:
+`npx expo install expo-secure-store expo-file-system`.
+
+```ts
+import { createExpoGemmein } from "@gemmein/sdk/expo"
+import { AppState, Platform } from "react-native"
+
+export const g = createExpoGemmein({ appKey: "pk_live_..." }, { AppState, Platform })
+```
+
+| Export | Signature | What it is |
+|---|---|---|
+| `createExpoGemmein` | `(options: GemmeinOptions, modules?: ExpoModules) => Gemmein` | The client. It **is** `Gemmein` — the four seams a phone has, filled in, plus the picker conversion in front of every `upload()`. Anything you pass in `options` wins over the defaults |
+| `SecureStoreTokenStore` | `new SecureStoreTokenStore(appKey: string, secureStore?: SecureStoreModule)` | The `TokenStore` backed by `expo-secure-store` — `get(): Promise<string \| undefined>`, `set(token: string): Promise<void>`, `clear(): Promise<void>`. Keyed `gemmein_session_<first 20 of the app key>`, `WHEN_UNLOCKED_THIS_DEVICE_ONLY`, so the token never rides an iCloud backup. Reads and clears degrade to "signed out"; a refused **write** throws `secure_store_unavailable` |
+| `appStateVisibility` | `(appState?: AppStateModule) => VisibilityHook` | The `visibility` hook `watch()` sleeps on, answered by React Native's `AppState` instead of `document.visibilityState`. Only `"active"` counts as visible; before the module resolves the app is treated as visible |
+| `expoFetch` | `(injected?: typeof fetch) => typeof fetch` | `expo/fetch`, resolved on the first request, `globalThis.fetch` if it is not there. React Native's own fetch is XHR-backed and cannot give a streaming body, which is what `g.ai.chat({ stream: true })` and `g.ai.run(…, { stream: true })` return |
+| `expoPlatformTag` | `(platform?: PlatformModule) => string` | The `platform` string on `x-client-info`: `expo-ios`, `expo-android`, `expo-web`, or `expo` when no `Platform` was passed |
+| `expoUploadPart` | `(file: UploadInput, modules?: ExpoModules) => Promise<UploadInput>` | A picker's `{ uri, name, type, size }` turned into an `expo-file-system` `File`, because Expo's `FormData` refuses a bare picker part. Anything already carrying bytes passes through. Without `expo-file-system` it throws `upload_input_unsupported` |
+| `SECURE_STORE_VALUE_LIMIT` | `2048` | The byte ceiling on a secure-store value. Over it, `set` throws `token_too_large` rather than letting iOS throw a native error the app cannot read |
+| `ExpoModules` | `{ SecureStore?: SecureStoreModule; AppState?: AppStateModule; Platform?: PlatformModule; FileSystem?: FileSystemModule; fetch?: typeof fetch }` | The second argument. Every key optional: pass none and the entry resolves each module lazily on the first call that needs it; pass your own — an app's static imports, a test's fakes — and there is no dynamic resolution at all |
+
+`SecureStoreModule`, `AppStateModule`, `PlatformModule` and `FileSystemModule`
+are the exported types of those four slices — the little of each module this
+entry calls, and nothing more. Nothing is imported from Expo or React Native at
+module load, so the entry resolves in Node too.
+
+---
+
 ## Errors — `GemmeinError`
 
 Every failed call throws a `GemmeinError`:
@@ -935,9 +1197,10 @@ Branch on `err.code`. The gate's own codes (`session_invalid`,
 | `invalid_limit` | `limit` isn't a whole number from 1 to 100 (the message says so: "limit must be between 1 and 100") | ask for at most 100 and page with `cursor` — nothing is clamped for you |
 | `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 |
 | `in_flight` (409) | a `notify()` with the same `key` is sending right now | retry in a moment — a delivered send answers idempotently |
+| `sender_domain_required` (409) | `notify()` (and a relay's `email_person`) with no verified sender domain — your app's mail goes only from your own domain | verify a sender domain on the Domains page, then retry with the same key. Nothing was sent, recorded or capped |
 | `invalid_audience` | `for` isn't a user of this app | fix the recipient id |
 | `unknown_record` | a link field points at a missing record (live only) | fix the id |
-| `payload_too_large` / `file_too_large` | over the size cap (message states it) | shrink it |
+| `payload_too_large` / `file_too_large` | over the size cap (message states it): a record's data over 32 KB, an upload over 25 MB | shrink it — files go through uploads, never inline |
 | `invalid_file_content` | uploaded bytes aren't the claimed type (usually a renamed file) | send the real file |
 | `test_session_forbidden_live` | `testSession()` called on a live env / `sk_live` key | reaffirm's Tier B is dev-only — point it at your dev environment |
 | `unknown_plan` | no plan by that name | use a name from the list in the message |
@@ -955,6 +1218,11 @@ Branch on `err.code`. The gate's own codes (`session_invalid`,
 | `ai_test_capped` (429) | the AI tools page's test call — one a minute per app | wait a minute |
 | `invalid_secret_key` (client-side) | `gemmeinServer()` got a missing/`pk_` key | pass the `sk_` key from a server env var |
 | `invalid_response` (client-side, status 0) | the server answered 200 to `verifyEmailCode` without a session token — a proxy or mock in the path, not Gemmein; or `g.ai.text` / `g.ai.runText` got a non-stream provider answer with no text to lift out | check `apiUrl` and anything rewriting responses; the call is safe to retry — for AI, read the stream with `g.ai.chat` or `g.ai.run` |
+| `network_unreachable` (client-side, status 0) | the request never reached Gemmein — no connection, an offline device, a host that does not resolve, an `apiUrl` pointing at nothing; the message names the host, and `err.cause` carries the fetch's own error. A cancel (`{ signal }`) is not this: it stays an `AbortError` | check the connection and the `apiUrl`; the call is safe to retry. "The server said no" and "the server was never reached" are different problems — branch on them separately |
+| `upload_input_unsupported` (client-side, status 0) | `@gemmein/sdk/expo`: `upload()` was handed a picker's `{ uri }` and `expo-file-system` is not installed, so there is nothing to read the bytes with | `npx expo install expo-file-system`, or pass a `Blob` / an `expo-file-system` `File` |
+| `token_too_large` (client-side, status 0) | `@gemmein/sdk/expo`: a value over 2,048 bytes was handed to the device secure store, which iOS refuses with a native throw the app cannot read | store the token, not the session payload — a Gemmein session token is two orders of magnitude smaller |
+| `secure_store_unavailable` (client-side, status 0) | the token store could not KEEP the session, so sign-in throws rather than handing back a session the next launch will lose. **All three stores.** `BrowserTokenStore` (`@gemmein/sdk`): the browser refused the `localStorage` write — private mode past its quota, site data blocked, a sandboxed iframe. `SecureStoreTokenStore` (`@gemmein/sdk/expo`): `expo-secure-store` is not installed, or the device refused the write. Swift `KeychainTokenStore`: the Keychain refused, and the OSStatus is in the message; `-34018` is an unsigned build with no keychain access group. The store's own error is on `err.cause` (in Swift, in the message). Reads and clears stay lenient on all three — an unreadable store means signed out, never a crash | install `expo-secure-store`, or sign the app (ad-hoc is enough). The session is real — the server minted it — so an app that would rather run than stop catches this one code and rebuilds its client with a `MemoryTokenStore`: signed in until the process ends |
+| `invalid_collection_name` (client-side, status 0) | `g.collection(name)` was given a name outside the grammar: lowercase letters, digits and underscores, starting with a letter, 2-63 characters (`tasks`, `user_notes`). Thrown synchronously, before any request exists — the message echoes what it got | fix the name. A collection that exists but is not reachable is a different code (`unknown_collection`, 404) |
 | `authentication_required` (401) | checkout/subscription/pay without a signed-in user | sign the user in first |
 | `plan_has_no_link` (409) | the paid plan has no Payment Link pasted yet | ask the owner to paste it in their dashboard |
 | `product_not_sellable` (409) | `g.payments.buy` on a product sold via a relay or not yet — there is no Payment Link to open | tell the buyer how the product is sold, or ask the owner to wire a road |
@@ -965,7 +1233,7 @@ Branch on `err.code`. The gate's own codes (`session_invalid`,
 | `provider_required` (400) | more than one provider key is set and the call named none | pass `provider` |
 | `model_not_allowed` (403) | the owner's allowlist does not name this model | use one the message lists |
 | `ai_capped` (429) | 20 AI calls per person per minute | wait for `resetAt` |
-| `payload_too_large` (413) | on `g.ai.chat`: the body is over 256 KB | shorten the conversation you send |
+| `payload_too_large` (413) | on `g.ai.chat`: the body is over 256 KB; on `g.ai.run`: the inputs are over 64 KB; on a record write: the data is over 32 KB | shorten the conversation you send; send less; move files to uploads |
 | `session_required` (401) | `g.ai.chat` / `g.credits.balance` without a signed-in person | sign in first |
 | `scope_denied` (403) | on `g.ai.chat`: a secret key called the route | the route is for the browser — a server calls the provider directly |
 | `provider_unreachable` (502) | the provider did not answer before the first byte; the credit is refunded | retry |