@marktiderman/genesis-notifications 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,194 @@
 {
   "name": "@marktiderman/genesis-notifications",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "description": "One notifier for Genesis apps: a domain (chat, forms, sites, support) says who and what; this decides how and when. defineNotifications registers types (category, channels, critical, transactional, device action categories, Android channels); notify() queues them through a security-definer SQL function; the in-app feed is also the outbox; one runner (claim with SKIP LOCKED, retries with jittered backoff, deferrals) sends Expo push (batches of 100, receipts, dead tokens pruned, private previews) and Resend email (rendered once for byte-identical retries, tenant sender identities, RFC 8058 one-click unsubscribe, bounce and complaint suppression); preferences by category and channel with tenant defaults and quiet hours across daylight saving; secret links built at send time; erasure. Hooks for React and React Native, a web bell, feed, preferences matrix and admin views on genesis-ui, a native feed on genesis-ui-native. Part of the Genesis framework.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marktiderman/genesis.git",
+    "directory": "packages/notifications"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "source": "./src/index.ts",
+  "react-native": "./src/index.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-native": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/index.d.ts",
+      "react-native": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./runner": {
+      "types": "./dist/runner.d.ts",
+      "react-native": "./src/runner/index.ts",
+      "import": "./dist/runner.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./email": {
+      "types": "./dist/email.d.ts",
+      "import": "./dist/email.js"
+    },
+    "./supabase": {
+      "types": "./dist/supabase.d.ts",
+      "react-native": "./src/supabase/index.ts",
+      "import": "./dist/supabase.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "react-native": "./src/react/index.tsx",
+      "import": "./dist/react.js"
+    },
+    "./web": {
+      "types": "./dist/web.d.ts",
+      "import": "./dist/web.js"
+    },
+    "./native": {
+      "types": "./dist/native.d.ts",
+      "react-native": "./src/native/index.tsx",
+      "import": "./dist/native.js"
+    },
+    "./blocks": {
+      "types": "./dist/blocks.d.ts",
+      "import": "./dist/blocks.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/__tests__",
+    "migrations",
+    "functions",
+    "README.md"
+  ],
+  "dependencies": {
+    "@marktiderman/genesis-features": "^0.3.0"
+  },
+  "peerDependencies": {
+    "@marktiderman/genesis-native": ">=0.2.0 <1.0.0",
+    "@marktiderman/genesis-ui": "^2.13.0",
+    "@marktiderman/genesis-ui-native": "^2.4.0",
+    "@react-email/components": "^1.0.0",
+    "@tanstack/react-query": "^5.0.0",
+    "lucide-react": "^1.0.0",
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@marktiderman/genesis-native": {
+      "optional": true
+    },
+    "@marktiderman/genesis-ui": {
+      "optional": true
+    },
+    "@marktiderman/genesis-ui-native": {
+      "optional": true
+    },
+    "@react-email/components": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "lucide-react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@marktiderman/genesis-native": "^0.4.0",
+    "@marktiderman/genesis-ui": "^2.13.0",
+    "@marktiderman/genesis-ui-native": "^2.4.0",
+    "@react-email/components": "1.0.12",
+    "@tanstack/react-query": "^5.75.0",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^22",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "happy-dom": "^20.9.0",
+    "lucide-react": "^1.0.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "tsup": "^8.3.0",
+    "typescript": "~6.0.3",
+    "vitest": "^4.1.12"
+  },
+  "genesis": {
+    "blocks": {
+      "notifications": {
+        "feature": {
+          "name": "Notifications",
+          "summary": "One notifier for every domain: the in-app feed, Expo push and Resend email, with preferences by category and channel, quiet hours, retries, receipts and suppression.",
+          "keywords": [
+            "notifications",
+            "push",
+            "email",
+            "inbox",
+            "preferences",
+            "unsubscribe"
+          ],
+          "audience": [
+            "person",
+            "admin"
+          ]
+        },
+        "platforms": [
+          "web",
+          "native",
+          "server"
+        ],
+        "migrations": [
+          {
+            "file": "migrations/0001_genesis_notifications.sql",
+            "test": "migrations/tests/0001_genesis_notifications.test.sql"
+          }
+        ],
+        "functions": [
+          {
+            "dir": "functions/genesis-notifications",
+            "verifyJwt": false,
+            "secrets": [
+              "GENESIS_NOTIFICATIONS_CRON_SECRET",
+              "GENESIS_NOTIFICATIONS_UNSUBSCRIBE_SECRET",
+              "RESEND_API_KEY",
+              "RESEND_WEBHOOK_SECRET",
+              "EXPO_ACCESS_TOKEN"
+            ]
+          }
+        ],
+        "install": [
+          "@tanstack/react-query@^5.0.0"
+        ],
+        "steps": [
+          "Mirror your registry on deploy: syncNotificationTypes(adminClient, notifications) from @marktiderman/genesis-notifications/server.",
+          "Say who administers notifications: replace private.genesis_notifications_admin(uuid, uuid) in a migration of your own, after this one (genesis-notifications README, Admins).",
+          "Deploy functions/genesis-notifications and schedule POST …/run every minute and POST …/receipts every 15 minutes, with GENESIS_NOTIFICATIONS_CRON_SECRET as the bearer token; point Resend's webhook at …/webhooks/resend.",
+          "Coming from genesis-supabase's push migration (0005): stop calling genesis-push-send, and remove its pgTAP test (tests/database/*genesis_push.test.sql): two of its assertions describe the token takeover this migration closes."
+        ]
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup && node ../../scripts/check-exports-resolve.mjs",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/src/blocks.ts

@@ -0,0 +1,42 @@
+/**
+ * The notifications block, as a `defineBlock` declaration: what `genesis add
+ * notifications` installs (the migration and its pgTAP test), the screens it
+ * needs routed, its nav and Settings rows, and what it means for the stores'
+ * privacy forms. Node-safe: no React, no Supabase client.
+ */
+import { defineBlock } from "@marktiderman/genesis-features/blocks";
+
+const PACKAGE = "@marktiderman/genesis-notifications";
+
+/**
+ * Notifications: the feed, push and email for every domain, on one notifier.
+ *
+ * @stability Beta
+ */
+export const notificationsBlock = defineBlock({
+  id: "notifications",
+  platforms: ["web", "native", "server"],
+  contributes: {
+    nav: [{ id: "notifications", label: "Notifications", path: "/notifications", icon: "bell", order: 50 }],
+    settings: [{ id: "notification-preferences", section: "notifications", title: "Notifications", href: "/settings/notifications", testID: "genesis-notifications-settings" }],
+    routes: [
+      { path: "/notifications", description: "The notification feed", signedIn: true },
+      { path: "/settings/notifications", description: "Notification preferences: categories by channel, quiet hours, previews", signedIn: true },
+      { path: "/admin/notifications", description: "Admin: the delivery log, suppressed addresses, send a test", signedIn: true },
+    ],
+    migrations: [{ package: PACKAGE, file: "migrations/0001_genesis_notifications.sql", test: "migrations/tests/0001_genesis_notifications.test.sql" }],
+    privacy: {
+      collects: [
+        { type: "device ID", purposes: ["app functionality"], linked: true, tracking: false },
+        { type: "email address", purposes: ["app functionality"], linked: true, tracking: false },
+      ],
+      notes: [
+        "Keeps each person's notifications (what the app told them), read and archived, until they are pruned or the person is erased.",
+        "Keeps this device's push token against the signed-in person; forgotten on sign-out and account deletion. A token moves to another login only on the same phone, and each move is recorded.",
+        "Keeps notification preferences per person: each category by channel, quiet hours with a time zone, and previews.",
+        "Keeps a short delivery log (status and an error code, no content) and, for addresses that bounced, complained or unsubscribed with no login, a hash of the address.",
+        "Erasing a person deletes their notifications, send jobs, devices and preferences, whether or not they have a login.",
+      ],
+    },
+  },
+});

package/src/core/index.ts

@@ -0,0 +1,43 @@
+/**
+ * `@marktiderman/genesis-notifications/core` (also the package root): the
+ * registry (`defineNotifications`) and the types every part shares. No
+ * dependencies; runs in the browser, React Native, Node and edge runtimes.
+ *
+ * @packageDocumentation
+ */
+export {
+  CHANNELS,
+  IOS_ID_PATTERN,
+  KEY_PATTERN,
+  MAX_EMAIL_DELAY_SECONDS,
+  MESSAGE_ACTIONS,
+  GENESIS_TEST_CATEGORY,
+  GENESIS_TEST_TYPE,
+  NotificationRegistryError,
+  defineNotifications,
+  type Channel,
+  type ChannelImportance,
+  type MatrixRow,
+  type NotificationActionDef,
+  type NotificationActionSetDef,
+  type NotificationCategoryDef,
+  type NotificationData,
+  type NotificationRegistry,
+  type NotificationTypeDef,
+  type NotificationTypeRow,
+  type NotificationsInput,
+  type RenderedText,
+} from "./registry";
+export {
+  DELIVERY_STATUSES,
+  type ChannelChoices,
+  type DeliveryStatus,
+  type EmailRecipient,
+  type NotificationBrand,
+  type NotificationRow,
+  type NotifyInput,
+  type NotifyResult,
+  type Recipient,
+  type UserRecipient,
+} from "./types";
+export { recipientsToJson, assertNoSecrets, SecretInDataError } from "./validate";

package/src/core/registry.ts

@@ -0,0 +1,354 @@
+/**
+ * `defineNotifications`: the one list of what an app notifies people about,
+ * as `defineFeatures` is the list of what it does. Each type names its
+ * category, the channels it may use (and which are on by default), and two
+ * flags: `critical` (preferences can't turn it off) and `transactional` (no
+ * unsubscribe link, no quiet hours, no digest). The registry also defines the
+ * device notification categories (iOS action buttons) and the Android
+ * channels the app makes on the phone.
+ *
+ * It is plain data plus small render functions, so the browser, the phone
+ * and the server import the same list. `toTypeRows()` is what is mirrored
+ * into the database's `notification_types`.
+ */
+
+/** Where a notification can go. `in_app` is the feed. */
+export const CHANNELS = ["in_app", "push", "email"] as const;
+export type Channel = (typeof CHANNELS)[number];
+
+/** Lower case letters, digits, ".", "_" or "-", up to 64 characters: type keys, category ids. */
+export const KEY_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+/** Device category and action ids: Expo asks for no ":" or "-". */
+export const IOS_ID_PATTERN = /^[A-Za-z0-9_]{1,64}$/;
+
+/** Android channel importance (Expo's `AndroidImportance`). */
+export type ChannelImportance = "min" | "low" | "default" | "high" | "max";
+
+export interface NotificationCategoryDef {
+  /** What a person sees in their preferences ("Messages"). */
+  label: string;
+  description?: string;
+  /** Preferences can't turn this category off (account security, say). */
+  critical?: boolean;
+  /** The Android channel made for it (its id is the category id). Default importance `"default"`. */
+  android?: { importance?: ChannelImportance; name?: string };
+}
+
+/** An action button on a notification. */
+export interface NotificationActionDef {
+  id: string;
+  title: string;
+  /** A reply field instead of a plain button. */
+  textInput?: { placeholder?: string; submitTitle?: string };
+  /** Opens the app (default false: the action is handled in the background). */
+  opensApp?: boolean;
+  destructive?: boolean;
+  /** Needs the phone unlocked. */
+  requiresAuth?: boolean;
+}
+
+/** A notification category on the device (iOS's word): the actions a notification shows. */
+export interface NotificationActionSetDef {
+  actions: readonly NotificationActionDef[];
+  /** Shown when the person has hidden previews for the app. */
+  previewPlaceholder?: string;
+}
+
+/** What a notification says, made from its `data`. */
+export interface RenderedText {
+  title: string;
+  body?: string;
+  /** The app path a tap opens (`/messages/42`). */
+  url?: string;
+  /**
+   * Push-only extras, for a type whose app reads more than the link: `ids` always travel
+   * (a Reply action needs the conversation and message), `display` only when previews are
+   * shown (a sender's name and photo for iOS rich push), and `mutableContent` lets the app's
+   * Notification Service Extension run (dropped with hidden previews). Flat values only; the
+   * notifier's own keys (`notification_id`, `type`, `url`, `thread_key`) can't be replaced.
+   */
+  push?: {
+    ids?: Record<string, string | number>;
+    display?: Record<string, string | number>;
+    mutableContent?: boolean;
+  };
+}
+
+/** A notification's `data`: references and display values, never a secret. */
+export type NotificationData = Record<string, unknown>;
+
+export interface NotificationTypeDef<C extends string = string, A extends string = string> {
+  category: C;
+  /**
+   * The channels this type may use, and whether each is on for someone who
+   * never chose: `{ in_app: true, push: true, email: false }` offers email
+   * as an opt-in. A channel left out is never used.
+   */
+  channels: Partial<Record<Channel, boolean>>;
+  /** Preferences can't turn it off: each channel it offers stays as defaulted. */
+  critical?: boolean;
+  /**
+   * Mail the person needs for something they did (a receipt, a reset): no
+   * unsubscribe link, never held by quiet hours or folded into a digest.
+   * Rate caps are the domain's.
+   */
+  transactional?: boolean;
+  /**
+   * Wait this long before emailing, and skip the email if the person read
+   * the notification in the app meanwhile. Default 0 (send at once).
+   */
+  emailDelaySeconds?: number;
+  /** The device category (a key of `actions`) its pushes carry. */
+  actions?: A;
+  /** `"generic"` always sends neutral push text, whatever the person chose. */
+  pushPrivacy?: "default" | "generic";
+  /**
+   * The email holds a secret link (a one-time token). It is never stored in
+   * `data` or pushed: the server builds it at send time with
+   * `resolveSecretLink(type, ref)`.
+   */
+  secretLink?: boolean;
+  /** What the feed and the push say. */
+  render: (data: NotificationData) => RenderedText;
+}
+
+export interface NotificationsInput<
+  C extends Record<string, NotificationCategoryDef>,
+  A extends Record<string, NotificationActionSetDef>,
+  T extends Record<string, NotificationTypeDef<Extract<keyof C, string>, Extract<keyof A, string>>>,
+> {
+  categories: C;
+  actions?: A;
+  types: T;
+  /** Neutral text for hidden previews. Default "New notification". */
+  hiddenPreview?: { title: string; body?: string };
+}
+
+/** One row of `notification_types`, as `genesis_notifications_sync_types` takes it. */
+export interface NotificationTypeRow {
+  key: string;
+  category: string;
+  channels: Partial<Record<Channel, boolean>>;
+  critical: boolean;
+  transactional: boolean;
+  email_delay_seconds: number;
+  secret_link: boolean;
+  push_privacy: "default" | "generic";
+  ios_category: string | null;
+}
+
+export interface MatrixRow {
+  id: string;
+  label: string;
+  description?: string;
+  critical: boolean;
+  /** The channels some type in the category offers, in `CHANNELS` order. */
+  channels: Channel[];
+  /** Each offered channel's default: on when any type in the category has it on. */
+  defaults: Partial<Record<Channel, boolean>>;
+}
+
+export interface NotificationRegistry<
+  C extends Record<string, NotificationCategoryDef> = Record<string, NotificationCategoryDef>,
+  A extends Record<string, NotificationActionSetDef> = Record<string, NotificationActionSetDef>,
+  T extends Record<string, NotificationTypeDef> = Record<string, NotificationTypeDef>,
+> {
+  readonly categories: C;
+  readonly actions: A;
+  readonly types: T;
+  readonly hiddenPreview: { title: string; body?: string };
+  /** The type, or throws: an unknown key is a bug, never dropped quietly. */
+  type(key: string): NotificationTypeDef;
+  has(key: string): boolean;
+  /** Preferences can't turn it off: a critical type, or a type in a critical category. */
+  isCritical(key: string): boolean;
+  /** What the feed and the push say. A render that throws gives the type's key as the title. */
+  render(key: string, data: NotificationData): RenderedText;
+  /** The rows mirrored into `notification_types`. */
+  toTypeRows(): NotificationTypeRow[];
+  /** For a preferences matrix: each category with the channels its types offer. */
+  matrix(): MatrixRow[];
+  /** The device categories to register (`setNotificationCategoryAsync`). */
+  deviceCategories(): { identifier: string; actions: NotificationActionDef[]; previewPlaceholder?: string }[];
+  /** The Android channels, one per category. */
+  androidChannels(): { id: string; name: string; description?: string; importance: ChannelImportance }[];
+}
+
+/** Thrown by `defineNotifications`; lists every problem at once. */
+export class NotificationRegistryError extends Error {
+  constructor(readonly problems: string[]) {
+    super(`Invalid notifications:\n${problems.map((p) => `  - ${p}`).join("\n")}`);
+    this.name = "NotificationRegistryError";
+  }
+}
+
+/** The longest email delay: a week. */
+export const MAX_EMAIL_DELAY_SECONDS = 7 * 24 * 3600;
+
+/**
+ * The notification registry.
+ *
+ * ```ts
+ * export const notifications = defineNotifications({
+ *   categories: { messages: { label: "Messages", android: { importance: "high" } } },
+ *   actions: { message: { actions: [{ id: "reply", title: "Reply", textInput: {} }, { id: "mark_read", title: "Mark as read" }] } },
+ *   types: {
+ *     "chat.message": {
+ *       category: "messages",
+ *       channels: { in_app: true, push: true, email: true },
+ *       emailDelaySeconds: 600,
+ *       actions: "message",
+ *       render: (d) => ({ title: String(d.sender_name), body: String(d.preview), url: `/messages/${d.conversation_id}` }),
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @stability Beta
+ */
+export function defineNotifications<
+  const C extends Record<string, NotificationCategoryDef>,
+  const A extends Record<string, NotificationActionSetDef>,
+  const T extends Record<string, NotificationTypeDef<Extract<keyof C, string>, Extract<keyof A, string>>>,
+>(input: NotificationsInput<C, A, T>): NotificationRegistry<C, A, T> {
+  const problems: string[] = [];
+  const categories = input.categories as C & Record<string, NotificationCategoryDef>;
+  const actions = (input.actions ?? {}) as A & Record<string, NotificationActionSetDef>;
+  const types = input.types as T & Record<string, NotificationTypeDef>;
+  const own = (o: object, k: string) => Object.prototype.hasOwnProperty.call(o, k);
+
+  for (const [id, c] of Object.entries(categories)) {
+    if (!KEY_PATTERN.test(id)) problems.push(`category "${id}": an id is lower case letters, digits, ".", "_" or "-"`);
+    if (!c.label?.trim()) problems.push(`category "${id}": needs a label`);
+  }
+  for (const [id, set] of Object.entries(actions)) {
+    if (!IOS_ID_PATTERN.test(id)) problems.push(`actions "${id}": a device category id is letters, digits or "_" (no ":" or "-")`);
+    const seen = new Set<string>();
+    for (const a of set.actions) {
+      if (!IOS_ID_PATTERN.test(a.id)) problems.push(`actions "${id}": action "${a.id}" is letters, digits or "_"`);
+      if (seen.has(a.id)) problems.push(`actions "${id}": action "${a.id}" appears twice`);
+      seen.add(a.id);
+    }
+    if (set.actions.length === 0 || set.actions.length > 4) problems.push(`actions "${id}": one to four actions`);
+  }
+  for (const [key, t] of Object.entries(types)) {
+    if (!KEY_PATTERN.test(key)) problems.push(`type "${key}": a key is lower case letters, digits, ".", "_" or "-"`);
+    if (!own(categories, t.category)) problems.push(`type "${key}": unknown category "${String(t.category)}"`);
+    const offered = Object.keys(t.channels ?? {});
+    if (offered.length === 0) problems.push(`type "${key}": offers no channel`);
+    for (const ch of offered) if (!(CHANNELS as readonly string[]).includes(ch)) problems.push(`type "${key}": unknown channel "${ch}"`);
+    if (t.actions !== undefined && !own(actions, t.actions)) problems.push(`type "${key}": unknown actions "${String(t.actions)}"`);
+    const delay = t.emailDelaySeconds ?? 0;
+    if (!Number.isInteger(delay) || delay < 0 || delay > MAX_EMAIL_DELAY_SECONDS) {
+      problems.push(`type "${key}": emailDelaySeconds is a whole number from 0 to ${MAX_EMAIL_DELAY_SECONDS}`);
+    }
+    if (delay > 0 && t.channels?.email === undefined) problems.push(`type "${key}": emailDelaySeconds needs the email channel`);
+    if (delay > 0 && t.channels?.in_app === undefined) problems.push(`type "${key}": an email delay skips the mail once read in the app, so it needs the in_app channel`);
+    if (t.secretLink && t.channels?.email === undefined) problems.push(`type "${key}": secretLink is for email, and it offers no email channel`);
+    if (typeof t.render !== "function") problems.push(`type "${key}": needs a render function`);
+  }
+  if (problems.length) throw new NotificationRegistryError(problems);
+
+  const hiddenPreview = input.hiddenPreview ?? { title: "New notification" };
+  const typeOf = (key: string): NotificationTypeDef => {
+    if (!own(types, key)) throw new NotificationRegistryError([`unknown notification type "${key}"`]);
+    return types[key]!;
+  };
+  const isCritical = (key: string) => {
+    const t = typeOf(key);
+    return Boolean(t.critical || categories[t.category]?.critical);
+  };
+
+  return {
+    categories,
+    actions,
+    types,
+    hiddenPreview,
+    type: typeOf,
+    has: (key) => own(types, key),
+    isCritical,
+    render(key, data) {
+      try {
+        const out = typeOf(key).render(data ?? {});
+        return {
+          title: typeof out?.title === "string" && out.title ? out.title : key,
+          ...(typeof out?.body === "string" ? { body: out.body } : {}),
+          ...(typeof out?.url === "string" && out.url ? { url: out.url } : {}),
+          ...(out?.push && typeof out.push === "object" ? { push: out.push } : {}),
+        };
+      } catch {
+        return { title: key };
+      }
+    },
+    toTypeRows() {
+      return Object.entries(types).map(([key, t]) => ({
+        key,
+        category: t.category,
+        channels: { ...t.channels },
+        critical: isCritical(key),
+        transactional: Boolean(t.transactional),
+        email_delay_seconds: t.emailDelaySeconds ?? 0,
+        secret_link: Boolean(t.secretLink),
+        push_privacy: t.pushPrivacy ?? "default",
+        ios_category: t.actions ?? null,
+      }));
+    },
+    matrix() {
+      const rows: MatrixRow[] = [];
+      for (const [id, c] of Object.entries(categories)) {
+        const defaults: Partial<Record<Channel, boolean>> = {};
+        let critical = Boolean(c.critical);
+        for (const [key, t] of Object.entries(types)) {
+          if (t.category !== id) continue;
+          for (const [ch, on] of Object.entries(t.channels) as [Channel, boolean][]) defaults[ch] = Boolean(defaults[ch] || on);
+          if (isCritical(key)) critical = true;
+        }
+        const channels = CHANNELS.filter((ch) => ch in defaults);
+        if (channels.length) rows.push({ id, label: c.label, ...(c.description ? { description: c.description } : {}), critical, channels, defaults });
+      }
+      return rows;
+    },
+    deviceCategories() {
+      return Object.entries(actions).map(([identifier, set]) => ({
+        identifier,
+        actions: [...set.actions],
+        ...(set.previewPlaceholder ? { previewPlaceholder: set.previewPlaceholder } : {}),
+      }));
+    },
+    androidChannels() {
+      return Object.entries(categories).map(([id, c]) => ({
+        id,
+        name: c.android?.name ?? c.label,
+        ...(c.description ? { description: c.description } : {}),
+        importance: c.android?.importance ?? "default",
+      }));
+    },
+  };
+}
+
+/**
+ * The actions a message notification shows: Reply (a text field) and Mark as
+ * read. Put it in `actions` under an id (`message`) and name that id in the
+ * message type's `actions`. A tap on either reaches the push block's
+ * `onResponse`; `notificationAction(response)` gives the action id, the typed
+ * text and the notification id (use it as the reply's client id, so a
+ * retried reply stays one reply).
+ */
+export const MESSAGE_ACTIONS = {
+  actions: [
+    { id: "reply", title: "Reply", textInput: { placeholder: "Message", submitTitle: "Send" } },
+    { id: "mark_read", title: "Mark as read" },
+  ],
+} as const satisfies NotificationActionSetDef;
+
+/** The category and type of Admin -> Send a test (`genesis.test`, which the migration creates). Spread them into your registry. */
+export const GENESIS_TEST_CATEGORY = { genesis: { label: "Tests", description: "Test notifications an admin sends themself." } } as const satisfies Record<string, NotificationCategoryDef>;
+export const GENESIS_TEST_TYPE = {
+  "genesis.test": {
+    category: "genesis",
+    channels: { in_app: true, push: true, email: true },
+    critical: true,
+    transactional: true,
+    render: () => ({ title: "Test notification", body: "If you can read this, this channel works." }),
+  },
+} as const satisfies Record<string, NotificationTypeDef<"genesis">>;