@gemmein/sdk 0.4.2 → 0.4.3

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) {
@@ -753,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 {

package/dist/index.d.cts

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

package/dist/index.d.ts

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

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) {
@@ -736,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) {

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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemmein/sdk",
-  "version": "0.4.2",
+  "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",