@gemmein/sdk 0.4.3 → 0.4.5

package/REFERENCE.md

@@ -21,8 +21,10 @@ The browser client. `appKey` is your public `pk_...` key. `options` (optional):
 
 ### `gemmeinServer(secretKey, options?) → GemmeinServer`
 Server-only client for a `sk_...` secret key — **never ship this to the
-browser.** Exposes read/update on collections without a signed-in user, plus
-`testSession()` for CI self-tests (dev environments only — see **Reaffirm**).
+browser.** Exposes read/update on collections without a signed-in user,
+`notify()` to email one of your app's own verified people (see **Notify**),
+plus `testSession()` for CI self-tests (dev environments only — see
+**Reaffirm**).
 
 The client has two layers. **Your app's collections** — `g.collection(name)`
 (the canonical spelling; `g.storage.collection(name)` is the same client). And
@@ -88,10 +90,11 @@ certain the collection exists yet.
 |--------|-----------|---------|
 | `create` | `(data: T, options?: { key?: string; for?: string; published?: boolean })` | `Promise<GemmeinRecord<T>>` |
 | `list` | `(options?: ListOptions)` | `Promise<ListResult<T>>` |
+| `watch` | `(onChange: (delta: { records; deleted; initial }) => void, options?: { every?: number; where?; search?; limit? })` | `{ stop(): void }` — see **Live data** |
 | `get` | `(id: string, options?: { expand?: string[] })` | `Promise<GemmeinRecord<T>>` |
 | `update` | `(id: string, data: Partial<T> \| { field: { increment\|decrement, floor?, ceiling? } }, options?: { ifVersion?: number; published?: boolean })` | `Promise<GemmeinRecord<T>>` |
 | `delete` | `(id: string)` | `Promise<void>` |
-| `upload` | `(file: Blob \| File, options?: { name?: string })` | `Promise<{ id: string; ref: FileRef; contentType: string; sizeBytes: number }>` |
+| `upload` | `(file: Blob \| File, options?: { name?: string; contentType?: string; for?: string })` | `Promise<{ id: string; ref: FileRef; contentType: string; sizeBytes: number }>` |
 
 ### Files
 
@@ -126,6 +129,29 @@ immediately; a link already issued works until it expires, and a download that
 started before expiry may finish after it. Controlled delivery, not DRM —
 nothing takes back a file someone already downloaded.
 
+**What uploads take.** Images — JPEG, PNG, WebP, GIF, HEIC — and documents —
+PDF, ZIP, EPUB — at **25 MB per file**; nothing else (no video, audio, SVG,
+HTML or office files — zip an office file). The server checks the actual
+bytes, not the filename. A document always **downloads** (served as an
+attachment; it never opens inside the page) — link it with
+`{ intent: "download" }` — and pass `contentType` to `upload()` when a Blob
+doesn't carry its own type.
+
+**Handing a file to one person.** On `addressed`/`direct` collections,
+`upload(file, { for: userId })` stamps that person as the file's audience at
+birth — immutable, and only they (and you, the owner) can ever `link()` it.
+That's how a direct message carries an attachment. A field holding file
+references is learned as a **file field** — image or document, from the real
+uploads. The file law is UNIVERSAL: on every rule, locked or not, any
+top-level field value matching the ref grammar must name a real file you
+could read — a made-up ref is refused (`unknown_file`). Once the shape is
+sealed, the field's class is law too: the wrong kind teaches on the wire
+(`invalid_shape`, the message names which kind the field takes); before the
+seal, learning owns class (seen-both widens to "any"). A stored ref whose
+file was later deleted refuses the same way on re-write — clear the field
+(`null`) or upload a fresh file. Refs inside `list`/`json` values aren't
+judged at write; they still grant nothing at read.
+
 ```ts
 type GemmeinRecord<T> = {
   id: string;
@@ -144,7 +170,11 @@ type GemmeinRecord<T> = {
   existing?: true;             // present only when a keyed create returned YOUR existing record
 };
 
-type ListResult<T> = { records: GemmeinRecord<T>[]; cursor?: string; hasMore: boolean };
+type ListResult<T> = {
+  records: GemmeinRecord<T>[]; cursor?: string; hasMore: boolean;
+  deleted?: string[];   // on a `since` read: ids deleted after that instant — your rule scope only
+  watermark?: string;   // pass as the next `since`; paging a plain list in full, adopt the FIRST page's
+};
 
 type ListOptions = {
   limit?: number;
@@ -153,6 +183,8 @@ type ListOptions = {
   cursor?: string;                   // from a previous ListResult
   search?: string;                   // free-text across data
   expand?: string[];                 // link fields to embed (≤3), only on community/shared/direct
+  since?: string;                    // everything changed OR deleted after this instant, oldest first
+                                     // — the previous answer's watermark; incompatible with sort
 };
 ```
 
@@ -162,6 +194,19 @@ recipient id on `addressed`/`direct`. `published: false` = draft on a public
 rule. `ifVersion` = optimistic concurrency. Atomic counters go in *value*
 position: `update(id, { stock: { decrement: 1, floor: 0 } })`. `expand` throws
 on `private`/`public_read`/`admin_write` (no link shape) — join in memory there.
+`since` fixes the order (oldest change first) — pairing it with `sort` is a 400
+`invalid_since`. Deltas are at-least-once: apply by id.
+
+### Live data — `watch()`
+
+`watch(onChange, { every? })` keeps a list fresh by polling `list({ since })`
+— every 10 s by default, clamped to 5 s–300 s. `onChange` receives
+`{ records, deleted, initial }`: the first call is the full list
+(`initial: true`); every later call only what changed or was deleted. It
+sleeps while the tab is hidden and resyncs in full on return, backs off on
+rate limits (honouring `resetAt`), never overlaps its own requests, and stops
+itself on 401/403. Returns `{ stop() }` — call it when the view unmounts.
+Never hand-roll a polling loop; this is the sanctioned one.
 
 ---
 
@@ -172,6 +217,7 @@ on `private`/`public_read`/`admin_write` (no link shape) — join in memory ther
 | `subscriptions.mine` | `()` | `Promise<{ plan: string; status: "active" \| "cancelled" } \| null>` |
 | `subscriptions.checkout` | `(plan?: string)` | `Promise<{ url: string; plan: string }>` — **navigates the browser to Stripe** and resolves the url |
 | `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 |
 
 Plans are `g.subscriptions`; one-off things are `g.payments`. `checkout` and
 `buy` self-navigate via `window.location` — just `await` them on the click;
@@ -181,6 +227,32 @@ gate one-off fulfilment on the receipt record, never the redirect.
 
 ---
 
+## Notify — `gemmeinServer(sk).notify(personId, input)`
+
+Your app's **server** emails one of its **own verified people** — by person
+id, never an address. A missing, cross-environment, or suspended id is one
+`404 not_a_customer` on purpose: existence is never leaked.
+
+`input`: `{ subject: string; text: string; kind?: "event" | "account"; key?: string }`
+→ `Promise<{ sent: boolean; deduped?: boolean; recorded?: boolean; id: string | null; threadId: string | null; replyRail?: boolean }>`
+(`recorded: false` means the email went but Inbox recording failed — reported
+honestly, not hidden.)
+
+- `kind: "event"` (the default) — order shipped, booking confirmed. Capped at
+  **5 per person per day** so a bug can never flood an inbox, and 200 per app
+  per hour (`resetAt` rides the 429). `kind: "account"` — sign-in, access,
+  billing trouble — is exempt from the per-person cap (a security notice never
+  loses to order emails), same hourly app cap.
+- `key` makes the send at-most-once through retries: a delivered send answers
+  idempotently (`deduped: true`); a concurrent twin gets `409 in_flight` —
+  retry in a moment.
+- Plain text only — this is a notification, not a campaign. Every email
+  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.
+
+---
+
 ## Reaffirm — prove your app's boundaries in CI
 
 Gemmein enforces the rules **server-side**, so your frontend is never the source
@@ -288,17 +360,21 @@ Branch on `err.code`. The stable codes:
 | `conflict` | a keyed create / floor / stale `ifVersion` | it's the mechanism — tell the user it's taken |
 | `html_not_allowed` | HTML in a community/addressed/direct field | store plain text |
 | `invalid_publish` | `{ published }` on a non-public rule | drop it |
-| `invalid_shape` | field not in a locked (live) collection's shape | ask the owner to add it |
+| `invalid_shape` | field not in a locked (live) collection's shape — or a file field given the wrong kind (the message names which) | ask the owner to add it / send the kind the field takes |
+| `unknown_file` | a ref-shaped value points at a file that doesn't exist or isn't yours to hand — every rule, every write | fix the ref — never invent one |
+| `invalid_since` | `since` isn't a strict ISO 8601 timestamp, or came with `sort` | pass the previous answer's watermark; drop `sort` |
+| `not_a_customer` (404) | `notify()`'s recipient isn't a verified person of this app and environment | fix the person id — one code on purpose |
+| `in_flight` (409) | a `notify()` with the same `key` is sending right now | retry in a moment — a delivered send answers idempotently |
 | `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 |
-| `invalid_file_content` | uploaded bytes aren't the claimed image type | send the real image |
+| `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 |
 | `plan_not_purchasable` | tried to check out the free default plan | nothing to buy — gate on the paid plan's name |
 | `invalid_expand` | `expand` on a field/rule with no link shape | join in memory instead (private/public_read/admin_write have no links) |
 | `scope_denied` | secret key used outside its dashboard-configured scope (or on auth/management routes) | scope the key to that collection, or use the right surface |
-| `unsupported_file_type` (415) | upload isn't one of the allowed image types | send JPEG/PNG/WebP/GIF/HEIC |
+| `unsupported_file_type` (415) | upload isn't an allowed type | images (JPEG/PNG/WebP/GIF/HEIC) or documents (PDF/ZIP/EPUB) |
 | `invalid_key` | a keyed create's `key` breaks the charset/length law | 1-120 chars of letters, numbers, `: _ . @ / -` |
 | `invalid_secret_key` (client-side) | `gemmeinServer()` got a missing/`pk_` key | pass the `sk_` key from a server env var |
 | `authentication_required` (401) | checkout/subscription/pay without a signed-in user | sign the user in first |

package/dist/index.cjs

@@ -671,6 +671,12 @@ class CollectionClient {
      * Pass `{ name }` so the download carries a real filename, and
      * `{ contentType }` when the Blob has no type of its own.
      *
+     * W7.4 — `{ for: userId }` names ONE other person who may read this file
+     * (addressed and direct collections only — the rules where recipients
+     * exist). The attachment on a direct message: upload with
+     * `{ for: recipientId }`, store the ref in the record you send them, and
+     * their `g.files.link(ref)` works. Without `for`, only you can link it.
+     *
      * There is deliberately no `url` here. A URL that outlives a refund is the
      * bug this replaced.
      */
@@ -682,7 +688,7 @@ class CollectionClient {
         // Step 1: Get presigned upload URL
         const presign = await this.request("/upload", {
             method: "POST",
-            body: JSON.stringify({ name, size: file.size, contentType }),
+            body: JSON.stringify({ name, size: file.size, contentType, ...(options?.for ? { for: options.for } : {}) }),
         });
         // Step 2: Upload directly to S3 via presigned POST
         const form = new FormData();

package/dist/index.d.cts

@@ -500,12 +500,19 @@ export declare class CollectionClient<T extends Record<string, unknown> = Record
      * Pass `{ name }` so the download carries a real filename, and
      * `{ contentType }` when the Blob has no type of its own.
      *
+     * W7.4 — `{ for: userId }` names ONE other person who may read this file
+     * (addressed and direct collections only — the rules where recipients
+     * exist). The attachment on a direct message: upload with
+     * `{ for: recipientId }`, store the ref in the record you send them, and
+     * their `g.files.link(ref)` works. Without `for`, only you can link it.
+     *
      * There is deliberately no `url` here. A URL that outlives a refund is the
      * bug this replaced.
      */
     upload(file: Blob | File, options?: {
         name?: string;
         contentType?: string;
+        for?: string;
     }): Promise<{
         id: string;
         ref: FileRef;

package/dist/index.d.ts

@@ -500,12 +500,19 @@ export declare class CollectionClient<T extends Record<string, unknown> = Record
      * Pass `{ name }` so the download carries a real filename, and
      * `{ contentType }` when the Blob has no type of its own.
      *
+     * W7.4 — `{ for: userId }` names ONE other person who may read this file
+     * (addressed and direct collections only — the rules where recipients
+     * exist). The attachment on a direct message: upload with
+     * `{ for: recipientId }`, store the ref in the record you send them, and
+     * their `g.files.link(ref)` works. Without `for`, only you can link it.
+     *
      * There is deliberately no `url` here. A URL that outlives a refund is the
      * bug this replaced.
      */
     upload(file: Blob | File, options?: {
         name?: string;
         contentType?: string;
+        for?: string;
     }): Promise<{
         id: string;
         ref: FileRef;

package/dist/index.js

@@ -655,6 +655,12 @@ export class CollectionClient {
      * Pass `{ name }` so the download carries a real filename, and
      * `{ contentType }` when the Blob has no type of its own.
      *
+     * W7.4 — `{ for: userId }` names ONE other person who may read this file
+     * (addressed and direct collections only — the rules where recipients
+     * exist). The attachment on a direct message: upload with
+     * `{ for: recipientId }`, store the ref in the record you send them, and
+     * their `g.files.link(ref)` works. Without `for`, only you can link it.
+     *
      * There is deliberately no `url` here. A URL that outlives a refund is the
      * bug this replaced.
      */
@@ -666,7 +672,7 @@ export class CollectionClient {
         // Step 1: Get presigned upload URL
         const presign = await this.request("/upload", {
             method: "POST",
-            body: JSON.stringify({ name, size: file.size, contentType }),
+            body: JSON.stringify({ name, size: file.size, contentType, ...(options?.for ? { for: options.for } : {}) }),
         });
         // Step 2: Upload directly to S3 via presigned POST
         const form = new FormData();

package/llms.txt

@@ -291,7 +291,7 @@ go-live. Everything else is yours.
 - Images & files: NEVER base64 into record data and NEVER wire up your own
   storage bucket — uploads are built in:
   `const file = await g.collection("posts").upload(blob, { name })`
-  → `{ id, ref, contentType, sizeBytes }`. Store `file.ref` (`"file:01K…"`)
+  → `{ id, ref, contentType, sizeBytes }`. Store `file.ref` (`"file:9f2c…"` — a UUID form)
   in a record field like any text — that's how a record "has" an image or
   a document.
   Store the REFERENCE, never a URL: a reference never expires and grants
@@ -318,14 +318,32 @@ go-live. Everything else is yours.
   the console shows by name).
   Honest bound: revoking access stops NEW links immediately; a link already
   issued works until it expires. Gemmein controls delivery, it can't take
-  back a file someone already downloaded.
+  back a file someone already downloaded. A file can name ONE other reader:
+  `upload(blob, { for: userId })` (addressed/direct collections only) — the
+  direct message's attachment; the recipient's `files.link` works, everyone
+  else's still refuses. Without `for`, only the uploader can link it —
+  including in a client portal, where the OWNER hands a client a document
+  from the dashboard (attach it on the client's record there).
 - 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. A live shape is sealed and cannot take new fields — stop, tell
-  your human which field you needed, and send only the fields the shape
-  already has. Never rename fields to dodge it.
+  live it locks. Field kinds the shape learns: text, number, yes/no, list,
+  link (a stored record id), json, and FILE — a field that held an
+  upload()'s ref learns as a file field — and WHICH class (an image field
+  vs a document field, from what you actually uploaded). The file law is
+  UNIVERSAL: on every rule, locked or not, any top-level field value
+  matching the ref grammar must name a real, confirmed file of this app
+  that the writer may read — a made-up or foreign ref is refused ("file
+  not found", 400 unknown_file). Never invent a ref. (Refs inside list or
+  json values aren't judged at write — they still grant nothing at read.)
+  If a stored ref's file was later deleted, re-sending it refuses the same
+  way: clear the field (null) or upload a fresh file. Once sealed, class
+  is law too: a ZIP into a profile photo field is refused with the teach;
+  before the seal, what you upload is what the field learns. A 400 invalid_shape means the field isn't in the locked
+  shape or the value doesn't fit its kind. A live shape is sealed and
+  cannot take new fields — stop, tell your human which field you needed,
+  and send only the fields the shape already has. Never rename fields to
+  dodge it.
 - 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "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",
@@ -53,4 +53,4 @@
   "bugs": {
     "email": "hello@gemmein.com"
   }
-}
+}