@gemmein/sdk 0.4.1 → 0.4.3

package/dist/index.cjs

@@ -439,11 +439,185 @@ class CollectionClient {
             query.set("search", options.search);
         if (options.expand && options.expand.length > 0)
             query.set("expand", options.expand.join(","));
+        if (options.since !== undefined)
+            query.set("since", options.since instanceof Date ? options.since.toISOString() : options.since);
         // NOT query.size — absent on Node <19.8 / older browsers, where
         // `undefined > 0` would silently drop every filter.
         const qs = query.toString();
         return this.request(qs ? `?${qs}` : "");
     }
+    /**
+     * W7.2 — live-enough, honestly. Explicitly POLLING: a full list first,
+     * then "what changed?" every `every` ms (default 10s, floor 5s) through
+     * exactly the same permission gate as list(). Nothing is pushed.
+     *
+     *   const w = g.collection("orders").watch(({ records, deleted, initial }) => {
+     *     // initial=true: REPLACE your state — records IS the full current
+     *     // set, and replacing is what clears anything removed while you
+     *     // weren't looking. initial=false: upsert records by id (a change
+     *     // can arrive twice, never be missed); remove ids in `deleted`.
+     *   });
+     *   // later: w.stop()
+     *
+     * In a browser it sleeps while the tab is hidden and does a full resync on
+     * return (that resync is also how a record erased outright — not deleted
+     * by the app, erased — leaves the screen). On errors it backs off,
+     * doubling up to 60s, and honours a rate limit's reset time. One watch per
+     * page is the intended shape — share its result, don't stack watchers.
+     */
+    watch(onChange, options = {}) {
+        const asked = options.every;
+        const every = Math.max(5000, Math.min(300000, Number.isFinite(asked) ? asked : 10000));
+        const base = { where: options.where, search: options.search, limit: options.limit ?? 100 };
+        let stopped = false;
+        let timer;
+        let delayMs = every;
+        let watermark;
+        // One tick at a time. A visibility flip mid-tick sets resyncPending
+        // instead of racing a second loop into existence (each raced loop would
+        // have doubled the poll rate forever).
+        let inFlight = false;
+        let resyncPending = false;
+        const page = async (since) => {
+            const records = [];
+            const deleted = [];
+            let cursor;
+            let mark;
+            do {
+                const result = await this.list({ ...base, cursor, ...(since !== undefined ? { since } : {}) });
+                records.push(...result.records);
+                if (result.deleted)
+                    deleted.push(...result.deleted);
+                cursor = result.hasMore ? result.cursor : undefined;
+                if (since === undefined) {
+                    // Full sync: keep the FIRST page's watermark — anything written
+                    // while later pages stream must redeliver on the next poll, not
+                    // fall below an end-of-paging mark and vanish.
+                    mark = mark ?? result.watermark;
+                }
+                else if (!result.hasMore) {
+                    mark = result.watermark;
+                }
+            } while (cursor && !stopped);
+            return { records, deleted, mark };
+        };
+        const tick = async (resync) => {
+            if (stopped || inFlight)
+                return;
+            inFlight = true;
+            let delivery;
+            try {
+                const doResync = resync || resyncPending;
+                resyncPending = false;
+                const { records, deleted, mark } = await page(doResync ? undefined : watermark);
+                if (stopped) {
+                    inFlight = false;
+                    return;
+                }
+                if (mark !== undefined)
+                    watermark = mark;
+                delayMs = every;
+                if (doResync || records.length > 0 || deleted.length > 0) {
+                    delivery = { records, deleted, initial: doResync };
+                }
+            }
+            catch (err) {
+                if (stopped) {
+                    inFlight = false;
+                    return;
+                }
+                // An auth refusal is not transient: a signed-out or unentitled
+                // watcher polling forever writes a denied-audit row per attempt on
+                // the server (audit finding #8). Stop; a fresh watch() after
+                // sign-in starts clean.
+                if (err instanceof GemmeinError && (err.status === 401 || err.status === 403)) {
+                    inFlight = false;
+                    stopped = true;
+                    if (timer !== undefined) {
+                        clearTimeout(timer);
+                        timer = undefined;
+                    }
+                    if (typeof document !== "undefined") {
+                        document.removeEventListener("visibilitychange", onVisibility);
+                    }
+                    if (typeof console !== "undefined")
+                        console.warn(`gemmein watch stopped: ${err.code} — start a new watch after signing in`);
+                    return;
+                }
+                // Back off; a rate limit says exactly when to come back.
+                delayMs = Math.min(Math.max(delayMs * 2, every), 60000);
+                if (err instanceof GemmeinError && err.resetAt) {
+                    const wait = new Date(err.resetAt).getTime() - Date.now();
+                    if (Number.isFinite(wait) && wait > delayMs)
+                        delayMs = Math.min(wait, 300000);
+                }
+            }
+            inFlight = false;
+            if (delivery) {
+                // The app's callback runs OUTSIDE the wire handling: its exceptions
+                // are its own bugs, never a reason to back off or mangle the loop.
+                try {
+                    onChange(delivery);
+                }
+                catch { /* the app's error, not the wire's */ }
+            }
+            schedule();
+        };
+        const hidden = () => typeof document !== "undefined" && document.visibilityState === "hidden";
+        const schedule = () => {
+            if (stopped || hidden() || timer !== undefined)
+                return;
+            timer = setTimeout(() => { timer = undefined; void tick(false); }, delayMs);
+            // In Node a live timer pins the process open; a watcher should never
+            // be the reason a script can't exit.
+            timer.unref?.();
+        };
+        const onVisibility = () => {
+            if (stopped)
+                return;
+            if (hidden()) {
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                    timer = undefined;
+                }
+            }
+            else {
+                // Waking resyncs in full — the cheap answer to "what did I miss?",
+                // including anything erased while the tab slept. If a tick is mid
+                // flight, flag it rather than racing a second loop.
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                    timer = undefined;
+                }
+                delayMs = every;
+                if (inFlight) {
+                    resyncPending = true;
+                    return;
+                }
+                void tick(true);
+            }
+        };
+        if (typeof document !== "undefined") {
+            document.addEventListener("visibilitychange", onVisibility);
+        }
+        // Born hidden: wait for the tab — the visibility handler runs the first
+        // sync when the user actually looks.
+        if (!hidden())
+            void tick(true);
+        else
+            resyncPending = true;
+        return {
+            stop: () => {
+                stopped = true;
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                timer = undefined;
+                if (typeof document !== "undefined") {
+                    document.removeEventListener("visibilitychange", onVisibility);
+                }
+            },
+        };
+    }
     async get(id, options = {}) {
         const qs = options.expand && options.expand.length > 0 ? `?expand=${encodeURIComponent(options.expand.join(","))}` : "";
         return this.request(`/${encodeURIComponent(id)}${qs}`);
@@ -491,15 +665,24 @@ class CollectionClient {
      *   // later, to render:
      *   const { url } = await g.files.link(record.poster)
      *
+     * Images (JPEG/PNG/WebP/GIF/HEIC) and documents (PDF/ZIP/EPUB), 25 MB per
+     * file. A document always downloads — it is served as an attachment and
+     * never opens inside your page — so link it with `{ intent: "download" }`.
+     * Pass `{ name }` so the download carries a real filename, and
+     * `{ contentType }` when the Blob has no type of its own.
+     *
      * There is deliberately no `url` here. A URL that outlives a refund is the
      * bug this replaced.
      */
     async upload(file, options) {
         const name = options?.name ?? (file instanceof File ? file.name : "upload");
+        // A Blob built from bytes has type "" — `contentType` names it. The
+        // server proves the bytes either way.
+        const contentType = options?.contentType ?? file.type;
         // Step 1: Get presigned upload URL
         const presign = await this.request("/upload", {
             method: "POST",
-            body: JSON.stringify({ name, size: file.size, contentType: file.type }),
+            body: JSON.stringify({ name, size: file.size, contentType }),
         });
         // Step 2: Upload directly to S3 via presigned POST
         const form = new FormData();
@@ -588,6 +771,45 @@ class GemmeinServer {
         }
         return response.json();
     }
+    /**
+     * W7.3 — tell one of YOUR OWN people that something happened, by email:
+     *
+     *   await g.notify(order.ownerUserId, {
+     *     subject: "Your order shipped",
+     *     text: "Order #142 left the warehouse today.",
+     *     key: "order-142-shipped",          // optional: retries can't double-send
+     *   });
+     *
+     * A person id, never an email address — the recipient must be a verified
+     * user of this app (their address comes from the server's own record).
+     * Plain text (an account-context footer is added). The email is branded
+     * as your app; the send appears in your dashboard Inbox, and a customer's
+     * reply lands there too once your domain's receiving is verified — the
+     * response's `replyRail` says which is true. This is for EVENTS, not
+     * campaigns: event-class sends
+     * are capped at about 5 per person per day (429 notify_capped, with
+     * resetAt). Pass `kind: "account"` for account activity — a new sign-in,
+     * an access change, a billing problem — which skips the per-person cap
+     * (a security notice must never lose to five order emails); misusing it
+     * for campaigns is visible in your own audit trail.
+     */
+    async notify(personId, input) {
+        const response = await fetch(new URL("/server/notify", this.apiUrl), {
+            method: "POST",
+            headers: { "x-app-key": this.secretKey, "content-type": "application/json" },
+            body: JSON.stringify({ personId, subject: input.subject, text: input.text, ...(input.kind ? { kind: input.kind } : {}), ...(input.key ? { key: input.key } : {}) }),
+        });
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({ code: "request_failed", message: `Request failed: ${response.status}` }));
+            throw new GemmeinError({
+                status: response.status,
+                code: body.code ?? "request_failed",
+                message: body.message ?? `Request failed: ${response.status}`,
+                resetAt: typeof body.resetAt === "string" ? body.resetAt : undefined,
+            });
+        }
+        return response.json();
+    }
 }
 exports.GemmeinServer = GemmeinServer;
 class ServerCollectionClient {
@@ -613,6 +835,8 @@ class ServerCollectionClient {
             query.set("search", options.search);
         if (options.expand && options.expand.length > 0)
             query.set("expand", options.expand.join(","));
+        if (options.since !== undefined)
+            query.set("since", options.since instanceof Date ? options.since.toISOString() : options.since);
         // NOT query.size — absent on Node <19.8 / older browsers, where
         // `undefined > 0` would silently drop every filter.
         const qs = query.toString();

package/dist/index.d.cts

@@ -65,6 +65,15 @@ export type ListResult<T extends Record<string, unknown> = Record<string, unknow
     records: GemmeinRecord<T>[];
     cursor?: string;
     hasMore: boolean;
+    /** W7.2: on a delta read (`since`), ids of records deleted after that
+     * instant — ids only, and only ones your rule scope admitted. */
+    deleted?: string[];
+    /** The instant to pass as the next `since`. On a plain list it rides
+     * every page (adopt the FIRST page's when you page a full sync); on a
+     * delta it rides only the final page. Deliberately lags the server clock
+     * ~2s, so a change can be delivered twice but never silently missed —
+     * apply records by id. */
+    watermark?: string;
 };
 export type ListOptions = {
     limit?: number;
@@ -78,6 +87,10 @@ export type ListOptions = {
     /** SHAPE-1: link fields to embed (up to 3) — each expanded record is only
      * what YOU could have read directly; unreadable/deleted targets are null. */
     expand?: string[];
+    /** W7.2: everything changed OR deleted after this instant, oldest change
+     * first. Pass the `watermark` from the previous answer. Incompatible with
+     * `sort` (delta order is fixed). */
+    since?: string | Date;
 };
 /**
  * Answer to "who is signed in right now?". `authenticated: false` simply
@@ -414,6 +427,37 @@ export declare class CollectionClient<T extends Record<string, unknown> = Record
      * an object, not a bare array.
      */
     list(options?: ListOptions): Promise<ListResult<T>>;
+    /**
+     * W7.2 — live-enough, honestly. Explicitly POLLING: a full list first,
+     * then "what changed?" every `every` ms (default 10s, floor 5s) through
+     * exactly the same permission gate as list(). Nothing is pushed.
+     *
+     *   const w = g.collection("orders").watch(({ records, deleted, initial }) => {
+     *     // initial=true: REPLACE your state — records IS the full current
+     *     // set, and replacing is what clears anything removed while you
+     *     // weren't looking. initial=false: upsert records by id (a change
+     *     // can arrive twice, never be missed); remove ids in `deleted`.
+     *   });
+     *   // later: w.stop()
+     *
+     * In a browser it sleeps while the tab is hidden and does a full resync on
+     * return (that resync is also how a record erased outright — not deleted
+     * by the app, erased — leaves the screen). On errors it backs off,
+     * doubling up to 60s, and honours a rate limit's reset time. One watch per
+     * page is the intended shape — share its result, don't stack watchers.
+     */
+    watch(onChange: (delta: {
+        records: GemmeinRecord<T>[];
+        deleted: string[];
+        initial: boolean;
+    }) => void, options?: {
+        every?: number;
+        where?: Record<string, unknown>;
+        search?: string;
+        limit?: number;
+    }): {
+        stop(): void;
+    };
     get(id: string, options?: {
         expand?: string[];
     }): Promise<GemmeinRecord<T>>;
@@ -450,11 +494,18 @@ export declare class CollectionClient<T extends Record<string, unknown> = Record
      *   // later, to render:
      *   const { url } = await g.files.link(record.poster)
      *
+     * Images (JPEG/PNG/WebP/GIF/HEIC) and documents (PDF/ZIP/EPUB), 25 MB per
+     * file. A document always downloads — it is served as an attachment and
+     * never opens inside your page — so link it with `{ intent: "download" }`.
+     * Pass `{ name }` so the download carries a real filename, and
+     * `{ contentType }` when the Blob has no type of its own.
+     *
      * 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;
     }): Promise<{
         id: string;
         ref: FileRef;
@@ -489,6 +540,41 @@ export declare class GemmeinServer {
             role: string;
         };
     }>;
+    /**
+     * W7.3 — tell one of YOUR OWN people that something happened, by email:
+     *
+     *   await g.notify(order.ownerUserId, {
+     *     subject: "Your order shipped",
+     *     text: "Order #142 left the warehouse today.",
+     *     key: "order-142-shipped",          // optional: retries can't double-send
+     *   });
+     *
+     * A person id, never an email address — the recipient must be a verified
+     * user of this app (their address comes from the server's own record).
+     * Plain text (an account-context footer is added). The email is branded
+     * as your app; the send appears in your dashboard Inbox, and a customer's
+     * reply lands there too once your domain's receiving is verified — the
+     * response's `replyRail` says which is true. This is for EVENTS, not
+     * campaigns: event-class sends
+     * are capped at about 5 per person per day (429 notify_capped, with
+     * resetAt). Pass `kind: "account"` for account activity — a new sign-in,
+     * an access change, a billing problem — which skips the per-person cap
+     * (a security notice must never lose to five order emails); misusing it
+     * for campaigns is visible in your own audit trail.
+     */
+    notify(personId: string, input: {
+        subject: string;
+        text: string;
+        kind?: "event" | "account";
+        key?: string;
+    }): Promise<{
+        sent: boolean;
+        deduped?: boolean;
+        id: string | null;
+        threadId: string | null;
+        replyRail?: boolean;
+        recorded?: boolean;
+    }>;
 }
 declare class ServerCollectionClient {
     private readonly apiUrl;
@@ -503,6 +589,7 @@ declare class ServerCollectionClient {
         cursor?: string;
         search?: string;
         expand?: string[];
+        since?: string | Date;
     }): Promise<unknown>;
     update(id: string, data: Record<string, unknown>): Promise<unknown>;
     private request;

package/dist/index.d.ts

@@ -65,6 +65,15 @@ export type ListResult<T extends Record<string, unknown> = Record<string, unknow
     records: GemmeinRecord<T>[];
     cursor?: string;
     hasMore: boolean;
+    /** W7.2: on a delta read (`since`), ids of records deleted after that
+     * instant — ids only, and only ones your rule scope admitted. */
+    deleted?: string[];
+    /** The instant to pass as the next `since`. On a plain list it rides
+     * every page (adopt the FIRST page's when you page a full sync); on a
+     * delta it rides only the final page. Deliberately lags the server clock
+     * ~2s, so a change can be delivered twice but never silently missed —
+     * apply records by id. */
+    watermark?: string;
 };
 export type ListOptions = {
     limit?: number;
@@ -78,6 +87,10 @@ export type ListOptions = {
     /** SHAPE-1: link fields to embed (up to 3) — each expanded record is only
      * what YOU could have read directly; unreadable/deleted targets are null. */
     expand?: string[];
+    /** W7.2: everything changed OR deleted after this instant, oldest change
+     * first. Pass the `watermark` from the previous answer. Incompatible with
+     * `sort` (delta order is fixed). */
+    since?: string | Date;
 };
 /**
  * Answer to "who is signed in right now?". `authenticated: false` simply
@@ -414,6 +427,37 @@ export declare class CollectionClient<T extends Record<string, unknown> = Record
      * an object, not a bare array.
      */
     list(options?: ListOptions): Promise<ListResult<T>>;
+    /**
+     * W7.2 — live-enough, honestly. Explicitly POLLING: a full list first,
+     * then "what changed?" every `every` ms (default 10s, floor 5s) through
+     * exactly the same permission gate as list(). Nothing is pushed.
+     *
+     *   const w = g.collection("orders").watch(({ records, deleted, initial }) => {
+     *     // initial=true: REPLACE your state — records IS the full current
+     *     // set, and replacing is what clears anything removed while you
+     *     // weren't looking. initial=false: upsert records by id (a change
+     *     // can arrive twice, never be missed); remove ids in `deleted`.
+     *   });
+     *   // later: w.stop()
+     *
+     * In a browser it sleeps while the tab is hidden and does a full resync on
+     * return (that resync is also how a record erased outright — not deleted
+     * by the app, erased — leaves the screen). On errors it backs off,
+     * doubling up to 60s, and honours a rate limit's reset time. One watch per
+     * page is the intended shape — share its result, don't stack watchers.
+     */
+    watch(onChange: (delta: {
+        records: GemmeinRecord<T>[];
+        deleted: string[];
+        initial: boolean;
+    }) => void, options?: {
+        every?: number;
+        where?: Record<string, unknown>;
+        search?: string;
+        limit?: number;
+    }): {
+        stop(): void;
+    };
     get(id: string, options?: {
         expand?: string[];
     }): Promise<GemmeinRecord<T>>;
@@ -450,11 +494,18 @@ export declare class CollectionClient<T extends Record<string, unknown> = Record
      *   // later, to render:
      *   const { url } = await g.files.link(record.poster)
      *
+     * Images (JPEG/PNG/WebP/GIF/HEIC) and documents (PDF/ZIP/EPUB), 25 MB per
+     * file. A document always downloads — it is served as an attachment and
+     * never opens inside your page — so link it with `{ intent: "download" }`.
+     * Pass `{ name }` so the download carries a real filename, and
+     * `{ contentType }` when the Blob has no type of its own.
+     *
      * 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;
     }): Promise<{
         id: string;
         ref: FileRef;
@@ -489,6 +540,41 @@ export declare class GemmeinServer {
             role: string;
         };
     }>;
+    /**
+     * W7.3 — tell one of YOUR OWN people that something happened, by email:
+     *
+     *   await g.notify(order.ownerUserId, {
+     *     subject: "Your order shipped",
+     *     text: "Order #142 left the warehouse today.",
+     *     key: "order-142-shipped",          // optional: retries can't double-send
+     *   });
+     *
+     * A person id, never an email address — the recipient must be a verified
+     * user of this app (their address comes from the server's own record).
+     * Plain text (an account-context footer is added). The email is branded
+     * as your app; the send appears in your dashboard Inbox, and a customer's
+     * reply lands there too once your domain's receiving is verified — the
+     * response's `replyRail` says which is true. This is for EVENTS, not
+     * campaigns: event-class sends
+     * are capped at about 5 per person per day (429 notify_capped, with
+     * resetAt). Pass `kind: "account"` for account activity — a new sign-in,
+     * an access change, a billing problem — which skips the per-person cap
+     * (a security notice must never lose to five order emails); misusing it
+     * for campaigns is visible in your own audit trail.
+     */
+    notify(personId: string, input: {
+        subject: string;
+        text: string;
+        kind?: "event" | "account";
+        key?: string;
+    }): Promise<{
+        sent: boolean;
+        deduped?: boolean;
+        id: string | null;
+        threadId: string | null;
+        replyRail?: boolean;
+        recorded?: boolean;
+    }>;
 }
 declare class ServerCollectionClient {
     private readonly apiUrl;
@@ -503,6 +589,7 @@ declare class ServerCollectionClient {
         cursor?: string;
         search?: string;
         expand?: string[];
+        since?: string | Date;
     }): Promise<unknown>;
     update(id: string, data: Record<string, unknown>): Promise<unknown>;
     private request;

package/dist/index.js

@@ -423,11 +423,185 @@ export class CollectionClient {
             query.set("search", options.search);
         if (options.expand && options.expand.length > 0)
             query.set("expand", options.expand.join(","));
+        if (options.since !== undefined)
+            query.set("since", options.since instanceof Date ? options.since.toISOString() : options.since);
         // NOT query.size — absent on Node <19.8 / older browsers, where
         // `undefined > 0` would silently drop every filter.
         const qs = query.toString();
         return this.request(qs ? `?${qs}` : "");
     }
+    /**
+     * W7.2 — live-enough, honestly. Explicitly POLLING: a full list first,
+     * then "what changed?" every `every` ms (default 10s, floor 5s) through
+     * exactly the same permission gate as list(). Nothing is pushed.
+     *
+     *   const w = g.collection("orders").watch(({ records, deleted, initial }) => {
+     *     // initial=true: REPLACE your state — records IS the full current
+     *     // set, and replacing is what clears anything removed while you
+     *     // weren't looking. initial=false: upsert records by id (a change
+     *     // can arrive twice, never be missed); remove ids in `deleted`.
+     *   });
+     *   // later: w.stop()
+     *
+     * In a browser it sleeps while the tab is hidden and does a full resync on
+     * return (that resync is also how a record erased outright — not deleted
+     * by the app, erased — leaves the screen). On errors it backs off,
+     * doubling up to 60s, and honours a rate limit's reset time. One watch per
+     * page is the intended shape — share its result, don't stack watchers.
+     */
+    watch(onChange, options = {}) {
+        const asked = options.every;
+        const every = Math.max(5000, Math.min(300000, Number.isFinite(asked) ? asked : 10000));
+        const base = { where: options.where, search: options.search, limit: options.limit ?? 100 };
+        let stopped = false;
+        let timer;
+        let delayMs = every;
+        let watermark;
+        // One tick at a time. A visibility flip mid-tick sets resyncPending
+        // instead of racing a second loop into existence (each raced loop would
+        // have doubled the poll rate forever).
+        let inFlight = false;
+        let resyncPending = false;
+        const page = async (since) => {
+            const records = [];
+            const deleted = [];
+            let cursor;
+            let mark;
+            do {
+                const result = await this.list({ ...base, cursor, ...(since !== undefined ? { since } : {}) });
+                records.push(...result.records);
+                if (result.deleted)
+                    deleted.push(...result.deleted);
+                cursor = result.hasMore ? result.cursor : undefined;
+                if (since === undefined) {
+                    // Full sync: keep the FIRST page's watermark — anything written
+                    // while later pages stream must redeliver on the next poll, not
+                    // fall below an end-of-paging mark and vanish.
+                    mark = mark ?? result.watermark;
+                }
+                else if (!result.hasMore) {
+                    mark = result.watermark;
+                }
+            } while (cursor && !stopped);
+            return { records, deleted, mark };
+        };
+        const tick = async (resync) => {
+            if (stopped || inFlight)
+                return;
+            inFlight = true;
+            let delivery;
+            try {
+                const doResync = resync || resyncPending;
+                resyncPending = false;
+                const { records, deleted, mark } = await page(doResync ? undefined : watermark);
+                if (stopped) {
+                    inFlight = false;
+                    return;
+                }
+                if (mark !== undefined)
+                    watermark = mark;
+                delayMs = every;
+                if (doResync || records.length > 0 || deleted.length > 0) {
+                    delivery = { records, deleted, initial: doResync };
+                }
+            }
+            catch (err) {
+                if (stopped) {
+                    inFlight = false;
+                    return;
+                }
+                // An auth refusal is not transient: a signed-out or unentitled
+                // watcher polling forever writes a denied-audit row per attempt on
+                // the server (audit finding #8). Stop; a fresh watch() after
+                // sign-in starts clean.
+                if (err instanceof GemmeinError && (err.status === 401 || err.status === 403)) {
+                    inFlight = false;
+                    stopped = true;
+                    if (timer !== undefined) {
+                        clearTimeout(timer);
+                        timer = undefined;
+                    }
+                    if (typeof document !== "undefined") {
+                        document.removeEventListener("visibilitychange", onVisibility);
+                    }
+                    if (typeof console !== "undefined")
+                        console.warn(`gemmein watch stopped: ${err.code} — start a new watch after signing in`);
+                    return;
+                }
+                // Back off; a rate limit says exactly when to come back.
+                delayMs = Math.min(Math.max(delayMs * 2, every), 60000);
+                if (err instanceof GemmeinError && err.resetAt) {
+                    const wait = new Date(err.resetAt).getTime() - Date.now();
+                    if (Number.isFinite(wait) && wait > delayMs)
+                        delayMs = Math.min(wait, 300000);
+                }
+            }
+            inFlight = false;
+            if (delivery) {
+                // The app's callback runs OUTSIDE the wire handling: its exceptions
+                // are its own bugs, never a reason to back off or mangle the loop.
+                try {
+                    onChange(delivery);
+                }
+                catch { /* the app's error, not the wire's */ }
+            }
+            schedule();
+        };
+        const hidden = () => typeof document !== "undefined" && document.visibilityState === "hidden";
+        const schedule = () => {
+            if (stopped || hidden() || timer !== undefined)
+                return;
+            timer = setTimeout(() => { timer = undefined; void tick(false); }, delayMs);
+            // In Node a live timer pins the process open; a watcher should never
+            // be the reason a script can't exit.
+            timer.unref?.();
+        };
+        const onVisibility = () => {
+            if (stopped)
+                return;
+            if (hidden()) {
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                    timer = undefined;
+                }
+            }
+            else {
+                // Waking resyncs in full — the cheap answer to "what did I miss?",
+                // including anything erased while the tab slept. If a tick is mid
+                // flight, flag it rather than racing a second loop.
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                    timer = undefined;
+                }
+                delayMs = every;
+                if (inFlight) {
+                    resyncPending = true;
+                    return;
+                }
+                void tick(true);
+            }
+        };
+        if (typeof document !== "undefined") {
+            document.addEventListener("visibilitychange", onVisibility);
+        }
+        // Born hidden: wait for the tab — the visibility handler runs the first
+        // sync when the user actually looks.
+        if (!hidden())
+            void tick(true);
+        else
+            resyncPending = true;
+        return {
+            stop: () => {
+                stopped = true;
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                timer = undefined;
+                if (typeof document !== "undefined") {
+                    document.removeEventListener("visibilitychange", onVisibility);
+                }
+            },
+        };
+    }
     async get(id, options = {}) {
         const qs = options.expand && options.expand.length > 0 ? `?expand=${encodeURIComponent(options.expand.join(","))}` : "";
         return this.request(`/${encodeURIComponent(id)}${qs}`);
@@ -475,15 +649,24 @@ export class CollectionClient {
      *   // later, to render:
      *   const { url } = await g.files.link(record.poster)
      *
+     * Images (JPEG/PNG/WebP/GIF/HEIC) and documents (PDF/ZIP/EPUB), 25 MB per
+     * file. A document always downloads — it is served as an attachment and
+     * never opens inside your page — so link it with `{ intent: "download" }`.
+     * Pass `{ name }` so the download carries a real filename, and
+     * `{ contentType }` when the Blob has no type of its own.
+     *
      * There is deliberately no `url` here. A URL that outlives a refund is the
      * bug this replaced.
      */
     async upload(file, options) {
         const name = options?.name ?? (file instanceof File ? file.name : "upload");
+        // A Blob built from bytes has type "" — `contentType` names it. The
+        // server proves the bytes either way.
+        const contentType = options?.contentType ?? file.type;
         // Step 1: Get presigned upload URL
         const presign = await this.request("/upload", {
             method: "POST",
-            body: JSON.stringify({ name, size: file.size, contentType: file.type }),
+            body: JSON.stringify({ name, size: file.size, contentType }),
         });
         // Step 2: Upload directly to S3 via presigned POST
         const form = new FormData();
@@ -571,6 +754,45 @@ export class GemmeinServer {
         }
         return response.json();
     }
+    /**
+     * W7.3 — tell one of YOUR OWN people that something happened, by email:
+     *
+     *   await g.notify(order.ownerUserId, {
+     *     subject: "Your order shipped",
+     *     text: "Order #142 left the warehouse today.",
+     *     key: "order-142-shipped",          // optional: retries can't double-send
+     *   });
+     *
+     * A person id, never an email address — the recipient must be a verified
+     * user of this app (their address comes from the server's own record).
+     * Plain text (an account-context footer is added). The email is branded
+     * as your app; the send appears in your dashboard Inbox, and a customer's
+     * reply lands there too once your domain's receiving is verified — the
+     * response's `replyRail` says which is true. This is for EVENTS, not
+     * campaigns: event-class sends
+     * are capped at about 5 per person per day (429 notify_capped, with
+     * resetAt). Pass `kind: "account"` for account activity — a new sign-in,
+     * an access change, a billing problem — which skips the per-person cap
+     * (a security notice must never lose to five order emails); misusing it
+     * for campaigns is visible in your own audit trail.
+     */
+    async notify(personId, input) {
+        const response = await fetch(new URL("/server/notify", this.apiUrl), {
+            method: "POST",
+            headers: { "x-app-key": this.secretKey, "content-type": "application/json" },
+            body: JSON.stringify({ personId, subject: input.subject, text: input.text, ...(input.kind ? { kind: input.kind } : {}), ...(input.key ? { key: input.key } : {}) }),
+        });
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({ code: "request_failed", message: `Request failed: ${response.status}` }));
+            throw new GemmeinError({
+                status: response.status,
+                code: body.code ?? "request_failed",
+                message: body.message ?? `Request failed: ${response.status}`,
+                resetAt: typeof body.resetAt === "string" ? body.resetAt : undefined,
+            });
+        }
+        return response.json();
+    }
 }
 class ServerCollectionClient {
     constructor(apiUrl, secretKey, name) {
@@ -595,6 +817,8 @@ class ServerCollectionClient {
             query.set("search", options.search);
         if (options.expand && options.expand.length > 0)
             query.set("expand", options.expand.join(","));
+        if (options.since !== undefined)
+            query.set("since", options.since instanceof Date ? options.since.toISOString() : options.since);
         // NOT query.size — absent on Node <19.8 / older browsers, where
         // `undefined > 0` would silently drop every filter.
         const qs = query.toString();

package/llms.txt

@@ -140,7 +140,14 @@ go-live. Everything else is yours.
   never by you or the SDK; in local dev (`npx gemmein dev`) they're born from
   the terminal's rule conversation or a dropped declaration file, and
   `npx gemmein sync` creates them in the cloud app's dev environment from
-  those local declarations. Best practice: at planning time, list the collections your
+  those local declarations. A declaration is `gemmein/collections/<name>.json`:
+  `{ "rule": "shared", "means": "<why, in your human's words>" }`, plus an
+  optional `"unlockedBy": ["pro"]` — plan or product NAMES from
+  gemmein/payments.json (never access keys) — which is the console's
+  "Unlocked by": the local engine refuses members without one of them
+  (403 entitlement_required) the moment the file lands, and sync carries
+  it to the cloud app. An unknown name is refused out loud in the dev
+  terminal and the collection is not created. Best practice: at planning time, list the collections your
   app will need and ask your human up front, and pass your intent whenever a
   collection might not exist yet —
   `g.collection("bookings", { intent: "students reserve slots; each sees only their own" })`
@@ -183,9 +190,9 @@ go-live. Everything else is yours.
     as private or encrypted chat.
   Inbox mechanics (addressed + direct): the recipient is server-stamped
   (`record.audienceUserId`) — never a data field; user ids come from
-  records' ownerUserId or the owner's admin views. Reading is plain
-  `.list({ sort: "newest" })` — poll on window focus plus a gentle ~60s
-  interval, never a tight loop. Track read-state in the user's own private
+  records' ownerUserId or the owner's admin views. For a live-feeling inbox
+  (or any live list) use `.watch()` — see "Live data" below — never a tight
+  loop of your own. Track read-state in the user's own private
   collection. Both rules store plain text like community. Errors teach the
   fix: 400 invalid_audience (recipient isn't a user of this app), 403
   reply_only (this collection only allows replying to someone who wrote to
@@ -207,7 +214,64 @@ go-live. Everything else is yours.
   `record.title`). `ownerUserId` and the rest are server-derived and
   read-only: never store your own userId/role/owner fields inside `data`.
   `.list()` returns `{ records, hasMore }` (an object, not an array) and
-  accepts `{ limit, sort: "newest"|"oldest"|"updated", where, search, cursor }`.
+  accepts `{ limit, sort: "newest"|"oldest"|"updated", where, search, cursor,
+  since }`.
+- 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:
+
+      const w = g.collection("orders").watch(({ records, deleted, initial }) => {
+        // initial=true → REPLACE your state with `records` (it IS the full
+        // current set — replacing is what clears anything removed while you
+        // weren't looking). initial=false → upsert `records` BY ID and drop
+        // ids in `deleted`.
+      });
+      // when the view unmounts: w.stop()
+
+  Every 10s by default (`{ every: ms }`, floor 5s) it asks "what changed?" —
+  a near-free answer when nothing did. It sleeps while the tab is hidden and
+  refreshes fully on return. Apply records by id: a change can be delivered
+  twice, never silently missed. One watch per page, shared — don't stack a
+  watcher per component, and never wrap it in your own setInterval. Under
+  the hood it's `list({ since })`: pass the previous answer's `watermark` as
+  `since` and you get records changed or deleted after it (ids in
+  `deleted`), oldest first — same permissions as any read. `since` can't
+  combine with `sort`. A record erased by the platform (data erasure, not an
+  app delete) doesn't appear in `deleted` — the replace-on-initial refresh
+  on tab-return is what clears it. Watching with `where`/`search`: deletions
+  always come through, but a record EDITED so it stops matching your filter
+  isn't reported (it isn't deleted) — it clears on the next tab-return
+  refresh. Watch suits lists you'd actually render (up to a few thousand
+  records); it re-reads the full list on every tab return.
+- Telling a customer something happened ("order shipped", "booking
+  confirmed", "new reply") is built in — your SERVER calls it with a
+  secret key; there is no SMTP, no email service to wire, and it cannot
+  be called from the browser:
+
+      import { gemmeinServer } from "@gemmein/sdk";
+      const g = gemmeinServer(process.env.GEMMEIN_SECRET_KEY);
+      await g.notify(order.ownerUserId, {
+        subject: "Your order shipped",
+        text: "Order #142 left the warehouse today.",
+        key: "order-142-shipped",   // retries can't double-send
+      });
+
+  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
+  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
+  write. The response's `replyRail: true|false` states which is true right
+  now. This is for EVENTS, not campaigns:
+  about 5 event-class sends per person per day (429 notify_capped with
+  resetAt says when). Account activity — a new sign-in, an access change,
+  a billing problem — passes `kind: "account"`, which skips the per-person
+  cap (a security notice never loses to five order emails); misusing it
+  for campaigns shows in your own audit trail. In `gemmein dev` the send
+  prints in the terminal (NOTIFY · …) instead of mailing.
 - Linking records (author on a post, product on an order): store the other
   record's id in a field (`authorProfileId: profile.id`) — in collections
   users write (community, shared, direct) the server learns it's a link;
@@ -228,7 +292,8 @@ go-live. Everything else is yours.
   storage bucket — uploads are built in:
   `const file = await g.collection("posts").upload(blob, { name })`
   → `{ id, ref, contentType, sizeBytes }`. Store `file.ref` (`"file:01K…"`)
-  in a record field like any text — that's how a record "has" an image.
+  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
   nothing on its own.
   To show or download it: `const { url } = await g.files.link(record.photo)`
@@ -236,12 +301,18 @@ go-live. Everything else is yours.
   rather than a preview. Files in a collection anyone can read get a
   permanent link; every other file gets one that expires in a couple of
   minutes, so call `link()` when you render, don't store what it returns.
-  Upload permission follows the collection's WRITE rule; images only
-  (JPEG/PNG/WebP/GIF/HEIC). Oversized files are refused loudly (413
+  Upload permission follows the collection's WRITE rule. Images (JPEG/PNG/
+  WebP/GIF/HEIC) and documents (PDF/ZIP/EPUB), 25 MB per file; nothing
+  else (no video, audio, SVG, HTML or office files — zip an office file).
+  Images render with `<img>`; a document always DOWNLOADS (served as an
+  attachment under the `name` you gave upload() — it never opens inside
+  your page), so link documents with `{ intent: "download" }`. A Blob you
+  built from bytes has no type: pass `{ contentType: "application/pdf" }`
+  to upload(), or a 415 says "none declared". Oversized files are refused loudly (413
   file_too_large — the message says the cap). The server checks the actual
   bytes at confirm — a 400 invalid_file_content means the file isn't really
-  the image type it claimed (usually a renamed file); send the real image,
-  don't retry. A 403 from `link()` means the customer isn't allowed this
+  the type it claimed (usually a renamed file); send the real file, don't
+  retry. A 403 from `link()` means the customer isn't allowed this
   file right now — signed out, not theirs, or an entitlement they no longer
   hold (`entitlement_required` — `err.requires` is the plan's key, the one
   the console shows by name).
@@ -309,7 +380,11 @@ go-live. Everything else is yours.
   with `sub?.plan === "pro"`.
 - Paid ACCESS (entitlements): a collection can be locked to a plan or
   product — your human picks it BY NAME in the "Unlocked by" row on the
-  Collections page (several allowed; any one of them opens it) — and the
+  Collections page (several allowed; any one of them opens it), or, in
+  local dev, you write the same thing as `"unlockedBy": ["pro"]` in
+  gemmein/collections/<name>.json (names, never keys; `npx gemmein check`
+  checks that the lock holds and names collections left open while the app
+  sells something) — and the
   engine refuses customers without it, under all seven rules. (Server
   secret keys and the owner's console are exempt by design; link/expand
   silently hide gated records rather than naming them.) Every plan and
@@ -473,10 +548,15 @@ REFERENCE.md) — copy it out, name your collections, run it in CI.
   metered. Safe limits exist as safety rails against runaway scripts and
   are never billed. Ceilings follow the app's verified people — they grow
   automatically as the business grows, with generous floors so a small app
-  never starts at a wall. Hitting a limit returns a clear coded error
-  (`usage_limit_exceeded`; monthly counters carry `resetAt`, storage
-  responds to deleting files), and the dashboard's usage page shows what
-  is binding.
+  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
+  for the month, and next month's bill follows the band their people land
+  in. Storage is the one thing that can fill — files are accepted up to
+  twice the storage ceiling, then uploads return `usage_limit_exceeded`
+  (no `resetAt`; storage frees when files are deleted). The per-IP and
+  per-email rate limits underneath are safety rails, not ceilings, and
+  still answer 429 with `resetAt`. The dashboard's usage page shows what
+  crossed this month.
 
 ## Facts for citation
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.4.1",
-  "description": "Gemmein SDK — passwordless auth, safe storage, and Stripe-driven record flips for AI-built apps. Small enough that one prompt teaches the whole API.",
+  "version": "0.4.3",
+  "description": "Gemmein SDK \u2014 passwordless auth, safe storage, and Stripe-driven record flips for AI-built apps. Small enough that one prompt teaches the whole API.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -53,4 +53,4 @@
   "bugs": {
     "email": "hello@gemmein.com"
   }
-}
+}