@gemmein/sdk 0.4.2 → 0.4.4

package/dist/index.cjs

@@ -526,6 +526,24 @@ class CollectionClient {
                     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) {
@@ -653,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.
      */
@@ -664,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();
@@ -753,6 +777,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 {

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;
@@ -540,6 +547,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;

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;
@@ -540,6 +547,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;

package/dist/index.js

@@ -510,6 +510,24 @@ export class CollectionClient {
                     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) {
@@ -637,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.
      */
@@ -648,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();
@@ -736,6 +760,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) {

package/llms.txt

@@ -243,6 +243,35 @@ go-live. Everything else is yours.
   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;
@@ -262,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
@@ -289,14 +318,27 @@ 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). Once locked, the
+  field accepts only a reference to a real, confirmed file of this app
+  that the writer may read, of the right class — a ZIP into a profile
+  photo field is refused with the teach, as is a made-up or foreign ref
+  ("file not found"). 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.2",
+  "version": "0.4.4",
   "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",