@marktiderman/genesis-notifications 0.0.0-stage → 0.1.0

package/src/server/email-render.ts

@@ -0,0 +1,90 @@
+/**
+ * What an email says, and the checks every one passes: subjects and names on
+ * one line, addresses well formed, every value escaped in the default body.
+ */
+import type { RenderedText } from "../core/registry";
+import type { NotificationBrand } from "../core/types";
+
+export interface EmailContent {
+  subject: string;
+  html: string;
+  text: string;
+}
+
+export interface EmailTemplateContext {
+  type: string;
+  category: string;
+  /** The notification's `data`. */
+  data: Record<string, unknown>;
+  /** What the registry's render says (title, body, url): a starting point. */
+  text: RenderedText;
+  recipient: { email: string; name: string | null };
+  /** The caller's brand over the tenant's default. */
+  brand: NotificationBrand;
+  tenantId: string | null;
+  transactional: boolean;
+  /**
+   * Put this where the secret link goes (`href={secretLink}`): the runner
+   * swaps in the real link at send time, so the stored render never holds it.
+   * Null when the type has none.
+   */
+  secretLink: string | null;
+  /** The signed one-click unsubscribe link, for the footer. Null for transactional mail. */
+  unsubscribeUrl: string | null;
+  /** The app's absolute link for `text.url`, when `appUrl` is set. */
+  url: string | null;
+}
+
+/** A type's email: React Email (`@marktiderman/genesis-notifications/email`), or any HTML. */
+export type EmailTemplate = (context: EmailTemplateContext) => EmailContent | Promise<EmailContent>;
+
+export function escapeHtml(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+/** A header value on one line: control characters and line separators become spaces; cut to `max`. */
+export function headerSafe(text: string, max = 200): string {
+  // eslint-disable-next-line no-control-regex
+  const flat = text.replace(/[\u0000-\u001f\u007f\u2028\u2029]+/g, " ").replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+/** A bare address safe as a header value. */
+export function isSafeAddress(value: unknown): value is string {
+  // eslint-disable-next-line no-control-regex
+  return typeof value === "string" && value.length <= 254 && /^[^\s@<>,;:"()[\]\\]+@[^\s@<>,;:"()[\]\\]+\.[^\s@<>,;:"()[\]\\]+$/.test(value) && !/[\u0000-\u001f\u007f]/.test(value);
+}
+
+/** A display name with nothing that could break out of the From header (or need quoting): no quotes, brackets, ":", ";", "@", "," or "\\". */
+export function displayName(name: string): string {
+  return headerSafe(name.replace(/["<>()[\]:;@,\\]/g, ""), 100);
+}
+
+/** The default email when a type has no template: its title, body and a button, every value escaped. */
+export const defaultEmailTemplate: EmailTemplate = (ctx) => {
+  const title = ctx.text.title;
+  const body = ctx.text.body ?? "";
+  const link = ctx.secretLink ?? ctx.url;
+  const accent = typeof ctx.brand.color === "string" && /^#[0-9a-fA-F]{3,8}$/.test(ctx.brand.color) ? ctx.brand.color : "#111827";
+  const from = ctx.brand.name ? escapeHtml(ctx.brand.name) : "";
+  const p = "font-family:sans-serif;font-size:15px;line-height:1.5;margin:0 0 16px;color:#111827";
+  const html =
+    `<!doctype html><html><body style="margin:0;padding:24px;background:#f9fafb">` +
+    `<div style="max-width:560px;margin:0 auto;background:#ffffff;border-radius:8px;padding:24px">` +
+    (from ? `<p style="${p};font-weight:600;color:${accent}">${from}</p>` : "") +
+    `<p style="${p};font-size:18px;font-weight:600">${escapeHtml(title)}</p>` +
+    (body ? `<p style="${p};white-space:pre-wrap">${escapeHtml(body)}</p>` : "") +
+    (link ? `<p style="${p}"><a href="${escapeHtml(link)}" style="display:inline-block;background:${accent};color:#ffffff;padding:10px 16px;border-radius:6px;text-decoration:none">Open</a></p>` : "") +
+    (ctx.unsubscribeUrl ? `<p style="${p};font-size:12px;color:#6b7280"><a href="${escapeHtml(ctx.unsubscribeUrl)}" style="color:#6b7280">Unsubscribe</a> from these emails.</p>` : "") +
+    `</div></body></html>`;
+  const text = [from, title, body, link ?? "", ctx.unsubscribeUrl ? `Unsubscribe: ${ctx.unsubscribeUrl}` : ""].filter(Boolean).join("\n\n");
+  return { subject: title, html, text };
+};
+
+/** JSON with sorted keys: the same bytes however a database reordered them. */
+export function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const entries = Object.entries(value as Record<string, unknown>).filter(([, v]) => v !== undefined).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+}

package/src/server/errors.ts

@@ -0,0 +1,61 @@
+/**
+ * A send failure with a message that is safe to store and log (a status and
+ * a provider's error code, never content, an address or a secret). The
+ * runner turns it into a retry or a failure.
+ */
+export class SendError extends Error {
+  override name = "SendError";
+  readonly retryable: boolean;
+  readonly retryAfterSeconds: number | undefined;
+  readonly status: number | undefined;
+  constructor(message: string, options: { retryable?: boolean; retryAfterSeconds?: number; status?: number } = {}) {
+    super(message.slice(0, 500));
+    this.retryable = options.retryable ?? false;
+    this.retryAfterSeconds = options.retryAfterSeconds;
+    this.status = options.status;
+  }
+}
+
+/** Whether an HTTP status is worth retrying unchanged: 408, 425, 429 and 5xx. */
+export function isRetryableStatus(status: number): boolean {
+  return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+
+/** Seconds from a Retry-After header (delta-seconds or an HTTP date), else `fallback`. 1 s to a day. */
+export function retryAfterSeconds(header: string | null | undefined, fallback = 60, now = Date.now()): number {
+  const clamp = (s: number) => Math.min(86_400, Math.max(1, s));
+  const value = header?.trim();
+  if (value && /^\d+$/.test(value)) return clamp(Number(value));
+  if (value && /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(value)) {
+    const at = Date.parse(value);
+    if (Number.isFinite(at)) return clamp(Math.ceil((at - now) / 1000));
+  }
+  return fallback;
+}
+
+/** Every request gives up after this long. */
+export const REQUEST_TIMEOUT_MS = 10_000;
+
+export interface HttpDeps {
+  /** Default the global `fetch`. */
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+}
+
+/** `fetch` with a timeout, and the caller's abort signal too. */
+export async function timedFetch(deps: HttpDeps, url: string, init: RequestInit, signal?: AbortSignal): Promise<Response> {
+  const f = deps.fetch ?? fetch;
+  const timeout = AbortSignal.timeout(deps.timeoutMs ?? REQUEST_TIMEOUT_MS);
+  const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+  try {
+    return await f(url, { ...init, signal: combined });
+  } catch (error) {
+    const name = (error as { name?: string } | null)?.name;
+    throw new SendError(name === "TimeoutError" || name === "AbortError" ? "Timed out" : "Network error", { retryable: true });
+  }
+}
+
+/** Reads and drops a body we won't use (some runtimes leak a connection otherwise). */
+export function discard(response: Response): void {
+  response.body?.cancel().catch(() => {});
+}

package/src/server/expo.ts

@@ -0,0 +1,133 @@
+/**
+ * Expo's push service: https://docs.expo.dev/push-notifications/sending-notifications/
+ *
+ *   POST /--/api/v2/push/send          up to 100 messages; one ticket each, in order
+ *   POST /--/api/v2/push/getReceipts   up to 1000 ticket ids; a receipt for each one ready
+ *
+ * Nothing here logs; an error names a status or Expo's error code, never a
+ * token or a message.
+ */
+import { SendError, discard, isRetryableStatus, retryAfterSeconds, timedFetch, type HttpDeps } from "./errors";
+
+export const EXPO_SEND_URL = "https://exp.host/--/api/v2/push/send";
+export const EXPO_RECEIPTS_URL = "https://exp.host/--/api/v2/push/getReceipts";
+/** Expo takes up to 100 messages per send. */
+export const EXPO_SEND_BATCH = 100;
+/** And up to 1000 ticket ids per receipts request. */
+export const EXPO_RECEIPTS_BATCH = 1000;
+
+/** One message for Expo. */
+export interface PushMessage {
+  to: string;
+  title?: string;
+  subtitle?: string;
+  body?: string;
+  /** Reaches the app (`notification.request.content.data`): ids and the link, never content. */
+  data?: Record<string, string | number | boolean | null>;
+  sound?: "default" | null;
+  badge?: number;
+  /** Android: the notification channel (one per category). */
+  channelId?: string;
+  /** The device category whose actions it shows (Reply, Mark as read). */
+  categoryId?: string;
+  /** iOS: groups notifications on the lock screen (a conversation). */
+  threadId?: string;
+  /** Replaces an earlier one with the same id, in transit (and on screen on iOS). */
+  collapseId?: string;
+  /** Android: replaces one already on screen with the same tag. */
+  tag?: string;
+  ttl?: number;
+  priority?: "default" | "normal" | "high";
+  /** iOS: lets the app's Notification Service Extension change it (rich push). */
+  mutableContent?: boolean;
+}
+
+export type PushTicket = { status: "ok"; id: string } | { status: "error"; code: string };
+export type PushReceipt = { status: "ok" } | { status: "error"; code: string };
+
+/** Sends pushes and reads receipts; `expoPushProvider` is the built-in one. */
+export interface PushProvider {
+  readonly name: string;
+  /** At most `EXPO_SEND_BATCH` messages; one ticket per message, in order. Throws a `SendError` when the request failed. */
+  send(messages: readonly PushMessage[], options?: { signal?: AbortSignal }): Promise<PushTicket[]>;
+  /** Receipts for at most `EXPO_RECEIPTS_BATCH` tickets; ids with none yet are left out. */
+  receipts(ids: readonly string[], options?: { signal?: AbortSignal }): Promise<Record<string, PushReceipt>>;
+}
+
+export interface ExpoOptions extends HttpDeps {
+  /** Expo's access token, for "Enhanced Security for Push Notifications" (turn it on). */
+  accessToken?: string;
+  sendUrl?: string;
+  receiptsUrl?: string;
+}
+
+/** An Expo error code (`DeviceNotRegistered`), safe to store; anything else is `Unknown`. */
+export function expoErrorCode(value: { details?: { error?: unknown } } | undefined): string {
+  const code = value?.details?.error;
+  return typeof code === "string" && /^[A-Za-z_]{1,64}$/.test(code) ? code : "Unknown";
+}
+
+/** Expo refused the request itself (a 4xx other than 429): resend its messages one by one. */
+export function refusedOutright(error: unknown): boolean {
+  return error instanceof SendError && error.status !== undefined && error.status >= 400 && error.status < 500 && error.status !== 429;
+}
+
+/**
+ * Expo's push service as a `PushProvider`.
+ *
+ * @stability Beta
+ */
+export function expoPushProvider(options: ExpoOptions = {}): PushProvider {
+  const headers = {
+    accept: "application/json",
+    "content-type": "application/json",
+    ...(options.accessToken ? { authorization: `Bearer ${options.accessToken}` } : {}),
+  };
+  async function post(url: string, body: unknown, signal?: AbortSignal): Promise<unknown> {
+    const response = await timedFetch(options, url, { method: "POST", headers, body: JSON.stringify(body) }, signal);
+    if (!response.ok) {
+      // The body of an error is never read: it can echo the request back.
+      const retryAfter = response.status === 429 ? retryAfterSeconds(response.headers.get("retry-after"), 30) : undefined;
+      discard(response);
+      throw new SendError(`Expo push answered HTTP ${response.status}`, {
+        retryable: isRetryableStatus(response.status),
+        status: response.status,
+        ...(retryAfter !== undefined ? { retryAfterSeconds: retryAfter } : {}),
+      });
+    }
+    try {
+      return await response.json();
+    } catch {
+      throw new SendError("Expo push answered with something that isn't JSON", { retryable: true });
+    }
+  }
+  return {
+    name: "expo",
+    async send(messages, { signal } = {}) {
+      if (messages.length > EXPO_SEND_BATCH) throw new Error(`expoPushProvider: at most ${EXPO_SEND_BATCH} messages`);
+      if (messages.length === 0) return [];
+      const json = (await post(options.sendUrl ?? EXPO_SEND_URL, messages, signal)) as { data?: unknown };
+      const tickets = Array.isArray(json?.data) ? (json.data as { status?: string; id?: unknown; details?: { error?: unknown } }[]) : [];
+      // A short or malformed answer: the messages without a ticket failed, never "sent".
+      return messages.map((_, i): PushTicket => {
+        const t = tickets[i];
+        if (t?.status === "ok" && typeof t.id === "string" && t.id.length > 0 && t.id.length <= 128) return { status: "ok", id: t.id };
+        if (t?.status === "error") return { status: "error", code: expoErrorCode(t) };
+        return { status: "error", code: "NoTicket" };
+      });
+    },
+    async receipts(ids, { signal } = {}) {
+      if (ids.length > EXPO_RECEIPTS_BATCH) throw new Error(`expoPushProvider: at most ${EXPO_RECEIPTS_BATCH} ids`);
+      if (ids.length === 0) return {};
+      const json = (await post(options.receiptsUrl ?? EXPO_RECEIPTS_URL, { ids }, signal)) as { data?: unknown };
+      const data = json?.data && typeof json.data === "object" && !Array.isArray(json.data) ? (json.data as Record<string, { status?: string; details?: { error?: unknown } }>) : {};
+      const out: Record<string, PushReceipt> = {};
+      for (const id of ids) {
+        const r = data[id];
+        if (r?.status === "ok") out[id] = { status: "ok" };
+        else if (r?.status === "error") out[id] = { status: "error", code: expoErrorCode(r) };
+      }
+      return out;
+    },
+  };
+}

package/src/server/handler.ts

@@ -0,0 +1,127 @@
+/**
+ * `createNotificationsHandler`: the notifier's HTTP surface, as a
+ * `(Request) => Promise<Response>` for an Edge Function, a worker or any
+ * server with Fetch API requests. Matched by the path's last segments, so
+ * it mounts under any prefix:
+ *
+ *   POST …/run                 send what is due        (Authorization: Bearer <cronSecret>)
+ *   POST …/receipts            check push receipts     (Authorization: Bearer <cronSecret>)
+ *   POST …/webhooks/resend     bounces, complaints, deliveries (Svix-signed)
+ *   GET  …/unsubscribe?t=…     a page with one button (GET never unsubscribes: link scanners follow links)
+ *   POST …/unsubscribe?t=…     unsubscribes; RFC 8058 one-click posts `List-Unsubscribe=One-Click` here
+ *
+ * Answers carry counts and statuses only.
+ */
+import { timingSafeEqual } from "./crypto";
+import { escapeHtml } from "./email-render";
+import type { NotificationRunner } from "./runner";
+import type { NotificationStore } from "./store";
+import { verifyUnsubscribeToken } from "./unsubscribe";
+import { emailEventOf, verifyResendWebhook } from "./webhook";
+
+export interface NotificationsHandlerOptions {
+  runner: NotificationRunner;
+  store: NotificationStore;
+  /** The bearer secret a scheduler sends to /run and /receipts (32 characters or more). */
+  cronSecret: string;
+  /** The unsubscribe signing secret (the runner's `email.unsubscribe.secret`). */
+  unsubscribeSecret?: string;
+  /** Resend's webhook signing secret (`whsec_…`). */
+  resendWebhookSecret?: string;
+  /** Words on the unsubscribe page. */
+  copy?: Partial<{ title: string; confirm: string; button: string; done: string; invalid: string }>;
+  log?: (message: string) => void;
+}
+
+const COPY = {
+  title: "Unsubscribe",
+  confirm: "Stop getting these emails?",
+  button: "Unsubscribe",
+  done: "You're unsubscribed. You won't get these emails any more.",
+  invalid: "This link isn't valid any more.",
+};
+
+function page(title: string, body: string, status = 200): Response {
+  const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="robots" content="noindex"><title>${escapeHtml(title)}</title></head><body style="font-family:sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem;line-height:1.5">${body}</body></html>`;
+  return new Response(html, { status, headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", "referrer-policy": "no-referrer" } });
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json", "cache-control": "no-store" } });
+}
+
+/**
+ * The handler.
+ *
+ * @stability Beta
+ */
+export function createNotificationsHandler(options: NotificationsHandlerOptions): (request: Request) => Promise<Response> {
+  if (!options.cronSecret || options.cronSecret.length < 32) throw new Error("createNotificationsHandler: cronSecret must be at least 32 characters");
+  const copy = { ...COPY, ...options.copy };
+  const enc = new TextEncoder();
+  const authorized = (request: Request) => {
+    const header = request.headers.get("authorization") ?? "";
+    const given = header.startsWith("Bearer ") ? header.slice(7) : "";
+    return timingSafeEqual(enc.encode(given), enc.encode(options.cronSecret));
+  };
+  const log = (m: string) => {
+    try {
+      options.log?.(m);
+    } catch {
+      // ignored
+    }
+  };
+
+  return async (request) => {
+    const url = new URL(request.url);
+    const path = url.pathname.replace(/\/+$/, "");
+    try {
+      if (path.endsWith("/run") || path.endsWith("/receipts")) {
+        if (request.method !== "POST") return json({ error: "method_not_allowed" }, 405);
+        if (!authorized(request)) return json({ error: "unauthorized" }, 401);
+        if (path.endsWith("/run")) return json({ ok: true, ...(await options.runner.run({ signal: request.signal })) });
+        return json({ ok: true, ...(await options.runner.checkReceipts({ signal: request.signal })) });
+      }
+
+      if (path.endsWith("/webhooks/resend")) {
+        if (request.method !== "POST") return json({ error: "method_not_allowed" }, 405);
+        if (!options.resendWebhookSecret) return json({ error: "not_configured" }, 404);
+        const body = await request.text();
+        if (body.length > 256_000 || !(await verifyResendWebhook(options.resendWebhookSecret, request.headers, body))) return json({ error: "bad_signature" }, 401);
+        let payload: unknown;
+        try {
+          payload = JSON.parse(body);
+        } catch {
+          return json({ error: "bad_json" }, 400);
+        }
+        const event = emailEventOf(payload);
+        if (!event) return json({ ok: true, ignored: true });
+        const ours = await options.store.emailEvent(event.providerId, event.event, event.permanent);
+        return json({ ok: true, ours });
+      }
+
+      if (path.endsWith("/unsubscribe")) {
+        if (!options.unsubscribeSecret) return page(copy.title, `<p>${escapeHtml(copy.invalid)}</p>`, 404);
+        const token = url.searchParams.get("t") ?? "";
+        const claims = await verifyUnsubscribeToken(options.unsubscribeSecret, token);
+        if (!claims) return page(copy.title, `<p>${escapeHtml(copy.invalid)}</p>`, 400);
+        if (request.method === "GET") {
+          // Relative: behind a gateway (Supabase's /functions/v1) the function doesn't see its public path.
+          const action = `?t=${encodeURIComponent(token)}`;
+          return page(
+            copy.title,
+            `<h1 style="font-size:1.25rem">${escapeHtml(copy.confirm)}</h1><form method="post" action="${escapeHtml(action)}"><input type="hidden" name="List-Unsubscribe" value="One-Click"><button type="submit" style="font-size:1rem;padding:.5rem 1rem">${escapeHtml(copy.button)}</button></form>`,
+          );
+        }
+        if (request.method !== "POST") return json({ error: "method_not_allowed" }, 405);
+        await options.store.unsubscribe(claims.userId ?? null, claims.userId ? null : (claims.emailHash ?? null), claims.category, claims.tenantId ?? null);
+        return page(copy.title, `<p>${escapeHtml(copy.done)}</p>`);
+      }
+
+      return json({ error: "not_found" }, 404);
+    } catch (error) {
+      log(`notifications handler: ${error instanceof Error ? error.name : "error"} on ${path.split("/").slice(-1)[0]}`);
+      return json({ error: "server_error" }, 500);
+    }
+  };
+}

package/src/server/index.ts

@@ -0,0 +1,57 @@
+/**
+ * `@marktiderman/genesis-notifications/server`: `notify()`, the runner that
+ * sends what it queued (Expo push, Resend email), the HTTP handler (cron,
+ * webhooks, one-click unsubscribe), `resolveSecretLink` and the sender
+ * domain check. Runs wherever `fetch` and WebCrypto do (Node 20+, Deno,
+ * workers). Never import it into a browser or app bundle: it is for the
+ * service role.
+ *
+ * @packageDocumentation
+ */
+export { notify, cancelNotification, syncNotificationTypes, type CancelInput, type NotifyOptions } from "./notify";
+export {
+  supabaseNotificationStore,
+  NotificationStoreError,
+  type ClaimedDevice,
+  type ClaimedJob,
+  type NotificationStore,
+  type PushTicketRow,
+  type RenderedEmail,
+  type RpcClient,
+  type SenderIdentity,
+  type SettleOutcome,
+} from "./store";
+export { createNotificationRunner, type EmailOptions, type NotificationRunner, type NotificationRunnerOptions } from "./runner";
+export { createNotificationsHandler, type NotificationsHandlerOptions } from "./handler";
+export {
+  expoPushProvider,
+  expoErrorCode,
+  refusedOutright,
+  EXPO_RECEIPTS_BATCH,
+  EXPO_RECEIPTS_URL,
+  EXPO_SEND_BATCH,
+  EXPO_SEND_URL,
+  type ExpoOptions,
+  type PushMessage,
+  type PushProvider,
+  type PushReceipt,
+  type PushTicket,
+} from "./expo";
+export { createRateLimiter, type RateLimiter, type RateLimiterOptions } from "./rate";
+export { resendProvider, RESEND_API, RESEND_DEFAULT_PER_SECOND, type EmailMessage, type EmailProvider, type EmailSendResult, type ResendOptions } from "./resend";
+export { resolveSecretLink, SecretLinkError, SECRET_LINK_PLACEHOLDER, type SecretLinkRef, type SecretLinks } from "./secret-links";
+export { createUnsubscribeToken, verifyUnsubscribeToken, unsubscribeHeaders, emailHash, type UnsubscribeClaims } from "./unsubscribe";
+export { verifyResendWebhook, emailEventOf, WEBHOOK_TOLERANCE_SECONDS } from "./webhook";
+export { checkSenderDomain, isReservedDomain, senderOwnershipRecord, SENDER_OWNERSHIP_HOST, type DomainCheck, type DomainCheckOptions } from "./dns";
+export {
+  canonicalJson,
+  defaultEmailTemplate,
+  displayName,
+  escapeHtml,
+  headerSafe,
+  isSafeAddress,
+  type EmailContent,
+  type EmailTemplate,
+  type EmailTemplateContext,
+} from "./email-render";
+export { SendError, isRetryableStatus, retryAfterSeconds, REQUEST_TIMEOUT_MS, type HttpDeps } from "./errors";

package/src/server/notify.ts

@@ -0,0 +1,100 @@
+/**
+ * `notify()`: what a domain calls, from its server. It checks the input
+ * (the registry knows the type, the recipients are well formed, `data`
+ * holds no secret) and calls `genesis_notify`, which decides channels from
+ * preferences and queues the sends. A domain's own SQL can call
+ * `genesis_notify` directly with the same arguments.
+ */
+import type { NotificationRegistry } from "../core/registry";
+import type { NotifyInput, NotifyResult, Recipient } from "../core/types";
+import { assertNoSecrets, recipientsToJson } from "../core/validate";
+import { NotificationStoreError, type RpcClient } from "./store";
+
+export interface NotifyOptions {
+  /** Checks the type against the registry before the database does. */
+  registry?: NotificationRegistry;
+}
+
+/**
+ * Queue a notification for each recipient. Resolves one result per recipient
+ * that exists (a deleted login is left out); the same idempotency key again
+ * (for the same type and tenant) resolves `created: false` and sends nothing more.
+ *
+ * @stability Beta
+ */
+export async function notify<K extends string>(client: RpcClient, input: NotifyInput<K>, options: NotifyOptions = {}): Promise<NotifyResult[]> {
+  const t = options.registry?.type(input.type);
+  if (input.secret !== undefined && t && !t.secretLink) throw new Error(`notify: type ${input.type} carries no secret link`);
+  // A one-time secret is one person's: never copied onto another recipient's email.
+  if (input.secret !== undefined && input.recipients.length !== 1) throw new Error("notify: a secret goes to exactly one recipient");
+  if (!input.idempotencyKey || input.idempotencyKey.length > 200) throw new Error("notify: an idempotency key of 1 to 200 characters is required");
+  assertNoSecrets(input.data);
+  if (input.badge !== undefined && (!Number.isInteger(input.badge) || input.badge < 0)) throw new Error("notify: badge is a whole number, 0 or more");
+  const { data, error } = await client.rpc("genesis_notify", {
+    p_type: input.type,
+    p_recipients: recipientsToJson(input.recipients),
+    p_data: input.data ?? {},
+    p_idempotency_key: input.idempotencyKey,
+    p_thread_key: input.threadKey ?? null,
+    p_collapse_key: input.collapseKey ?? null,
+    p_badge: input.badge ?? null,
+    p_tenant_id: input.tenantId ?? null,
+    p_brand: input.brand ?? null,
+    p_secret: input.secret ?? null,
+  });
+  if (error) throw new NotificationStoreError("genesis_notify", error.code ?? null);
+  return ((data as { notification_id: string; recipient_key: string; created: boolean }[] | null) ?? []).map((r) => ({
+    notificationId: r.notification_id,
+    recipientKey: r.recipient_key,
+    created: r.created,
+  }));
+}
+
+export interface CancelInput {
+  /** The type the notifications were made with: a key is a domain's, per type. */
+  type: string;
+  /** The key the notifications were made with. */
+  idempotencyKey: string;
+  /** The tenant they were made for. Default: those made with no tenant (never another tenant's). */
+  tenantId?: string | null;
+  /** Only these recipients (as `notify()` takes them). Default: everyone the key reached. */
+  recipients?: readonly Recipient[];
+  /** Archive the feed rows too. Default false. */
+  archive?: boolean;
+}
+
+/**
+ * Stop what hasn't gone out for a type, tenant and idempotency key (a release
+ * rolled back, an event undone): every pending send job is marked cancelled
+ * and never claimed. A job already sent is left alone; one being sent right
+ * now ends cancelled unless that attempt goes through (it is never retried).
+ * With `archive`, the feed rows are archived too.
+ *
+ * @stability Beta
+ */
+export async function cancelNotification(client: RpcClient, input: CancelInput): Promise<{ cancelled: number; archived: number }> {
+  if (!input.type) throw new Error("cancelNotification: a type is required");
+  if (!input.idempotencyKey || input.idempotencyKey.length > 200) throw new Error("cancelNotification: an idempotency key of 1 to 200 characters is required");
+  const { data, error } = await client.rpc("genesis_notifications_cancel", {
+    p_type: input.type,
+    p_idempotency_key: input.idempotencyKey,
+    p_tenant_id: input.tenantId ?? null,
+    p_recipients: input.recipients ? recipientsToJson(input.recipients) : null,
+    p_archive: input.archive ?? false,
+  });
+  if (error) throw new NotificationStoreError("genesis_notifications_cancel", error.code ?? null);
+  const row = (Array.isArray(data) ? data[0] : data) as { cancelled?: number; archived?: number } | undefined;
+  return { cancelled: Number(row?.cancelled ?? 0), archived: Number(row?.archived ?? 0) };
+}
+
+/**
+ * Mirror the registry into `notification_types` (run it on deploy, or the
+ * server's first request): types left out are retired, never deleted.
+ *
+ * @stability Beta
+ */
+export async function syncNotificationTypes(client: RpcClient, registry: NotificationRegistry): Promise<number> {
+  const { data, error } = await client.rpc("genesis_notifications_sync_types", { p_rows: registry.toTypeRows() });
+  if (error) throw new NotificationStoreError("genesis_notifications_sync_types", error.code ?? null);
+  return Number(data ?? 0);
+}

package/src/server/rate.ts

@@ -0,0 +1,47 @@
+/**
+ * A request pacer: at most `perSecond` requests start in any second, spaced
+ * evenly, however many callers wait at once. Each provider instance has its
+ * own; two runners running at once each keep to it, so set it for that.
+ */
+export interface RateLimiter {
+  /** Resolves when the caller may start its request; rejects if `signal` aborts first. */
+  acquire(signal?: AbortSignal): Promise<void>;
+}
+
+export interface RateLimiterOptions {
+  perSecond: number;
+  now?: () => number;
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+
+function defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(signal.reason ?? new Error("Aborted"));
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new Error("Aborted"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/** @stability Beta */
+export function createRateLimiter(options: RateLimiterOptions): RateLimiter {
+  if (!(options.perSecond > 0) || !Number.isFinite(options.perSecond)) throw new Error("createRateLimiter: perSecond must be a positive number");
+  const gap = 1000 / options.perSecond;
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? defaultSleep;
+  let next = 0;
+  return {
+    async acquire(signal) {
+      const at = Math.max(now(), next);
+      next = at + gap;
+      const wait = at - now();
+      if (wait > 0) await sleep(wait, signal);
+    },
+  };
+}