@12-apps/notifications 1.0.0

package/prisma/migrations/20260813140000_add_notification_tables/migration.sql

@@ -0,0 +1,218 @@
+-- @12-apps/notifications (12-15): the four generic notification tables, owned
+-- by the package and copied into a host's migrations folder by its
+-- plugin-migration sync. Runs identically on PostgreSQL + PGlite.
+--
+-- NO foreign keys into host tables (the payments-backend doctrine): `user_id`
+-- and `client_id` are by-value scalars, and the host's own migration may add FK
+-- constraints (recommended: both ON DELETE CASCADE). The relation INTERNAL to
+-- the partial — notification_deliveries -> notifications — IS constrained, with
+-- a cascade, so a purged notification can never leave orphan delivery rows.
+--
+-- `channel` and `status` carry CHECKs: those are the LIBRARY's own closed sets,
+-- and a row outside them is a row no transport can carry. `category` does NOT,
+-- for the reason `@12-apps/rbac` gives for `role`: the category set is host
+-- vocabulary (`categories` on the server config), so a closed set here would be
+-- wrong for every host but the first. A host that wants its own CHECK adds one.
+--
+-- The `status` set is QUEUED | SENDING | SENT | FAILED | DEAD. `SENDING` is the
+-- dispatcher's CLAIM and `DEAD` is terminal (see `src/server/dispatch.ts`), and
+-- both are newer than the first adopters' hand-made tables — which is why the
+-- status CHECK below is DROPPED and re-added rather than guarded by a
+-- `pg_constraint` lookup like the others. An existence guard would find the
+-- three-value constraint an early adopter already has, skip, and leave the claim
+-- rejected at runtime by a CHECK that predates it.
+--
+-- ============================ REPLAY SAFETY ================================
+-- Every statement is guarded, because the first adopters ALREADY HAVE these
+-- tables: future-pay created them by hand before the package existed, so this
+-- migration must be a no-op there and correct on an empty database.
+--
+-- The guards are per COLUMN, not per table. `CREATE TABLE IF NOT EXISTS` alone
+-- is the trap: it skips the whole table, so a host whose table predates a
+-- column silently never gets that column and the failure surfaces later as a
+-- missing-column error in production. So each table is followed by one
+-- `ADD COLUMN IF NOT EXISTS` per column, and every NOT NULL column carries a
+-- DEFAULT — a NOT NULL column with no default cannot be added to a table that
+-- already holds rows.
+--
+-- CHECK constraints have no `IF NOT EXISTS` form, so they are guarded by a
+-- `pg_constraint` lookup instead (plpgsql, which PGlite has) — EXCEPT the
+-- delivery status CHECK, which must CONVERGE rather than be skipped and so is
+-- `DROP CONSTRAINT IF EXISTS` + `ADD`. Same for the sweep's index, which moved
+-- key: `DROP INDEX IF EXISTS` + `CREATE INDEX IF NOT EXISTS`. Both are
+-- idempotent, which is the property replay safety actually needs — "guarded" was
+-- only ever the usual way to get it, and it is the wrong way when the definition
+-- itself has changed under an existing adopter.
+
+-- ---------------------------------------------------------------------------
+-- notifications — the always-on inbox. One row per emit, written before any
+-- transport is consulted.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS "notifications" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "client_id" TEXT,
+    "type" TEXT NOT NULL,
+    "category" TEXT NOT NULL,
+    "title" TEXT NOT NULL,
+    "body" TEXT NOT NULL,
+    "link" TEXT,
+    "data" JSONB NOT NULL DEFAULT '{}',
+    "read_at" TIMESTAMP(3),
+    "deleted_at" TIMESTAMP(3),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "notifications_pkey" PRIMARY KEY ("id")
+);
+
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "user_id" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "client_id" TEXT;
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "type" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "category" TEXT NOT NULL DEFAULT 'system';
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "title" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "body" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "link" TEXT;
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "data" JSONB NOT NULL DEFAULT '{}';
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "read_at" TIMESTAMP(3);
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "deleted_at" TIMESTAMP(3);
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP;
+ALTER TABLE "notifications" ADD COLUMN IF NOT EXISTS "updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP;
+
+-- Inbox list (owner, not-deleted, newest first) + the unread badge count.
+CREATE INDEX IF NOT EXISTS "notifications_user_id_deleted_at_created_at_idx"
+    ON "notifications"("user_id", "deleted_at", "created_at");
+CREATE INDEX IF NOT EXISTS "notifications_user_id_deleted_at_read_at_idx"
+    ON "notifications"("user_id", "deleted_at", "read_at");
+
+-- ---------------------------------------------------------------------------
+-- notification_deliveries — one row per channel the router fanned out to.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS "notification_deliveries" (
+    "id" TEXT NOT NULL,
+    "notification_id" TEXT NOT NULL,
+    "channel" TEXT NOT NULL,
+    "status" TEXT NOT NULL DEFAULT 'QUEUED',
+    "error" TEXT,
+    "attempts" INTEGER NOT NULL DEFAULT 0,
+    "sent_at" TIMESTAMP(3),
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "notification_deliveries_pkey" PRIMARY KEY ("id")
+);
+
+ALTER TABLE "notification_deliveries" ADD COLUMN IF NOT EXISTS "notification_id" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "notification_deliveries" ADD COLUMN IF NOT EXISTS "channel" TEXT NOT NULL DEFAULT 'EMAIL';
+ALTER TABLE "notification_deliveries" ADD COLUMN IF NOT EXISTS "status" TEXT NOT NULL DEFAULT 'QUEUED';
+ALTER TABLE "notification_deliveries" ADD COLUMN IF NOT EXISTS "error" TEXT;
+-- The retry ceiling's counter (12-15). An adopter whose table predates it gets
+-- it at 0, which reads as "never claimed" — the correct starting point for a row
+-- that has, in the new lifecycle's terms, spent no attempts.
+ALTER TABLE "notification_deliveries" ADD COLUMN IF NOT EXISTS "attempts" INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE "notification_deliveries" ADD COLUMN IF NOT EXISTS "sent_at" TIMESTAMP(3);
+ALTER TABLE "notification_deliveries" ADD COLUMN IF NOT EXISTS "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP;
+ALTER TABLE "notification_deliveries" ADD COLUMN IF NOT EXISTS "updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP;
+
+-- The library's own closed sets. A delivery outside them is a delivery no
+-- transport can carry, so the schema refuses it rather than the router.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'notification_deliveries_channel_check'
+  ) THEN
+    ALTER TABLE "notification_deliveries"
+      ADD CONSTRAINT "notification_deliveries_channel_check"
+      CHECK ("channel" IN ('EMAIL', 'SMS', 'WHATSAPP', 'WEB_PUSH'));
+  END IF;
+END $$;
+
+-- The status set, DROP-and-re-ADD rather than guarded (see the header): the
+-- values widened in 12-15, so an adopter already holding a constraint under this
+-- name holds the OLD three, and a guard would keep it — rejecting the claim's
+-- own UPDATE. Idempotent, and re-running it converges rather than accumulating.
+ALTER TABLE "notification_deliveries"
+    DROP CONSTRAINT IF EXISTS "notification_deliveries_status_check";
+ALTER TABLE "notification_deliveries"
+    ADD CONSTRAINT "notification_deliveries_status_check"
+    CHECK ("status" IN ('QUEUED', 'SENDING', 'SENT', 'FAILED', 'DEAD'));
+
+-- Idempotent fan-out: re-dispatching a notification can never duplicate a
+-- channel's delivery row. This is what makes transport sends retry-safe.
+CREATE UNIQUE INDEX IF NOT EXISTS "notification_deliveries_notification_id_channel_key"
+    ON "notification_deliveries"("notification_id", "channel");
+-- Serves the retry sweep, which selects `status IN (…) AND updated_at < cutoff`.
+-- On `updated_at`, not `created_at`: the sweep asks "has this row moved lately",
+-- and `created_at` cannot answer that — a row re-queued a second ago still
+-- carries a `created_at` from days back, so it reads as stale again immediately.
+-- The `(status, created_at)` index this replaces served the earlier, wrong
+-- predicate and is dropped rather than left behind to cost every write.
+DROP INDEX IF EXISTS "notification_deliveries_status_created_at_idx";
+CREATE INDEX IF NOT EXISTS "notification_deliveries_status_updated_at_idx"
+    ON "notification_deliveries"("status", "updated_at");
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'notification_deliveries_notification_id_fkey'
+  ) THEN
+    ALTER TABLE "notification_deliveries"
+      ADD CONSTRAINT "notification_deliveries_notification_id_fkey"
+      FOREIGN KEY ("notification_id") REFERENCES "notifications"("id")
+      ON DELETE CASCADE ON UPDATE CASCADE;
+  END IF;
+END $$;
+
+-- ---------------------------------------------------------------------------
+-- notification_preferences — EXPLICIT choices only; no row means the defaults.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS "notification_preferences" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "category" TEXT NOT NULL,
+    "channels" JSONB NOT NULL DEFAULT '{}',
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "notification_preferences_pkey" PRIMARY KEY ("id")
+);
+
+ALTER TABLE "notification_preferences" ADD COLUMN IF NOT EXISTS "user_id" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "notification_preferences" ADD COLUMN IF NOT EXISTS "category" TEXT NOT NULL DEFAULT 'system';
+ALTER TABLE "notification_preferences" ADD COLUMN IF NOT EXISTS "channels" JSONB NOT NULL DEFAULT '{}';
+ALTER TABLE "notification_preferences" ADD COLUMN IF NOT EXISTS "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP;
+ALTER TABLE "notification_preferences" ADD COLUMN IF NOT EXISTS "updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP;
+
+CREATE UNIQUE INDEX IF NOT EXISTS "notification_preferences_user_id_category_key"
+    ON "notification_preferences"("user_id", "category");
+
+-- ---------------------------------------------------------------------------
+-- push_subscriptions — the Web Push destination, one row per browser.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS "push_subscriptions" (
+    "id" TEXT NOT NULL,
+    "user_id" TEXT NOT NULL,
+    "endpoint" TEXT NOT NULL,
+    "p256dh" TEXT NOT NULL,
+    "auth" TEXT NOT NULL,
+    "user_agent" TEXT,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "push_subscriptions_pkey" PRIMARY KEY ("id")
+);
+
+ALTER TABLE "push_subscriptions" ADD COLUMN IF NOT EXISTS "user_id" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "push_subscriptions" ADD COLUMN IF NOT EXISTS "endpoint" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "push_subscriptions" ADD COLUMN IF NOT EXISTS "p256dh" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "push_subscriptions" ADD COLUMN IF NOT EXISTS "auth" TEXT NOT NULL DEFAULT '';
+ALTER TABLE "push_subscriptions" ADD COLUMN IF NOT EXISTS "user_agent" TEXT;
+ALTER TABLE "push_subscriptions" ADD COLUMN IF NOT EXISTS "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP;
+ALTER TABLE "push_subscriptions" ADD COLUMN IF NOT EXISTS "updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP;
+
+-- The push-service endpoint is globally unique per subscription — registering
+-- the same browser again upserts rather than duplicates.
+CREATE UNIQUE INDEX IF NOT EXISTS "push_subscriptions_endpoint_key"
+    ON "push_subscriptions"("endpoint");
+CREATE INDEX IF NOT EXISTS "push_subscriptions_user_id_idx"
+    ON "push_subscriptions"("user_id");

package/prisma/notifications.prisma

@@ -0,0 +1,141 @@
+// @12-apps/notifications (12-15) — the four models the notification system
+// owns, COPIED into a host's schema folder by
+// `pnpm --filter @12-apps/notifications prisma:sync` (never symlinked: Prisma
+// lstats a migration directory, so a symlinked migration is silently skipped
+// and a green deploy applies no schema).
+//
+// Deliberately NO foreign keys into host tables (the payments-backend
+// doctrine): `user_id` and `client_id` are by-value scalars, and the host's own
+// migration may add FK constraints (recommended: both ON DELETE CASCADE, so a
+// deleted account takes its inbox with it). The relation INTERNAL to the
+// partial — notification_deliveries -> notifications — IS constrained, with a
+// cascade, so a purged notification can never leave orphan delivery rows.
+//
+// Do not edit a synced copy by hand: the next sync reverts it and
+// `prisma:sync:check` goes red in CI.
+
+// One inbox entry — the always-on channel. Written for EVERY emit, before any
+// transport is consulted, which is what makes "the user was told" true even
+// when every provider is down. `type` is an open dot-namespaced set validated
+// by the generator registry at the emit site (deliberately no CHECK, so a new
+// notification type ships without a migration). `category` has NO CHECK either,
+// and for a stronger reason: the category set is HOST vocabulary (`categories`
+// on the server config), so a closed set in the schema would be wrong for every
+// adopter but the first. A host that wants its own taxonomy enforced adds the
+// CHECK in a migration of its own — future-pay does. Only `channel` and `status`
+// on the delivery row are closed here, because those two are the LIBRARY's.
+model Notification {
+  id        String    @id @default(uuid())
+  userId    String    @map("user_id")
+  clientId  String?   @map("client_id")
+  type      String
+  category  String
+  title     String
+  body      String
+  link      String?
+  data      Json      @default("{}")
+  readAt    DateTime? @map("read_at")
+  deletedAt DateTime? @map("deleted_at")
+  createdAt DateTime  @default(now()) @map("created_at")
+  updatedAt DateTime  @updatedAt @map("updated_at")
+
+  deliveries NotificationDelivery[]
+
+  // The inbox list (owner, not-deleted, newest first) and the unread-count
+  // badge (owner, not-deleted, unread) — both single-index scans.
+  @@index([userId, deletedAt, createdAt])
+  @@index([userId, deletedAt, readAt])
+  @@map("notifications")
+}
+
+// Per-channel delivery tracking for one Notification: one row per transport
+// channel the router fanned out to, carrying the channel lifecycle and the
+// provider error when a send fails. `channel` is EMAIL | SMS | WHATSAPP |
+// WEB_PUSH (CHECK in the migration).
+//
+// The lifecycle is QUEUED -> SENDING -> SENT | FAILED | DEAD (String + DB
+// CHECK), and the two states beyond the obvious three each remove a way to send
+// somebody a duplicate paid message:
+//
+//   - SENDING is the CLAIM. A dispatcher moves the row out of QUEUED with one
+//     conditional UPDATE and sends only if it moved exactly one row, so two
+//     dispatchers racing the same delivery make exactly one provider call.
+//     `attempts` is incremented by that same claim.
+//   - DEAD is TERMINAL, reached at the `attempts` ceiling. Without it a
+//     permanently invalid destination is a billed provider call on every sweep
+//     for the life of the row.
+//
+// `@@unique([notificationId, channel])` makes fan-out idempotent — re-dispatching
+// a notification can never enqueue a duplicate delivery. Failures are isolated
+// per row: one channel failing never blocks the inbox record or the others.
+model NotificationDelivery {
+  id             String    @id @default(uuid())
+  notificationId String    @map("notification_id")
+  channel        String
+  status         String    @default("QUEUED")
+  error          String?
+  /// Claims spent on this row. The retry ceiling counts these, not failures, so
+  /// a dispatcher that dies mid-send still spends one and cannot loop forever.
+  attempts       Int       @default(0)
+  sentAt         DateTime? @map("sent_at")
+  createdAt      DateTime  @default(now()) @map("created_at")
+  updatedAt      DateTime  @updatedAt @map("updated_at")
+
+  notification Notification @relation(fields: [notificationId], references: [id], onDelete: Cascade)
+
+  @@unique([notificationId, channel])
+  // Serves the retry sweep: `status IN (…) AND updated_at < cutoff`. On
+  // `updatedAt`, because "stale" is a question about the last write and
+  // `createdAt` cannot answer it — a row re-queued a second ago has an ancient
+  // `created_at` and would read as stale again immediately.
+  @@index([status, updatedAt])
+  @@map("notification_deliveries")
+}
+
+// A user's channel choices for ONE notification category: which of the
+// transport channels may carry notifications of that category to them. One row
+// per (user, category); NO row = the code-level defaults apply (email + web
+// push on, the paid per-message channels off), so the table only ever stores
+// EXPLICIT choices. The inbox is NOT a channel here — it is always on and not
+// preference-gated.
+//
+// `channels` is a JSON map { "EMAIL": true, "SMS": false, … } rather than one
+// boolean column per channel: the channel set is open-ended, and a new
+// transport must not need a schema change — the open/closed rule the whole
+// pipeline is built on. A stored row missing a channel key falls back to that
+// channel's default, which is what makes the arrival of a channel a no-op for
+// every existing row.
+model NotificationPreference {
+  id        String   @id @default(uuid())
+  userId    String   @map("user_id")
+  category  String
+  channels  Json     @default("{}")
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+
+  @@unique([userId, category])
+  @@map("notification_preferences")
+}
+
+// One browser push subscription registered by a user's device — the Web Push
+// transport's destination, exactly as `PushManager.subscribe()` returns it: the
+// push-service `endpoint` (globally unique per subscription, hence @unique —
+// re-registering the same browser upserts rather than duplicates) plus the
+// `p256dh`/`auth` client keys the RFC 8291 payload encryption needs. A user may
+// hold many rows (one per browser/device); the transport sends to all of them.
+// A subscription the push service reports GONE (404/410) is pruned by the
+// transport, so the table self-heals as browsers expire subscriptions.
+model PushSubscription {
+  id        String   @id @default(uuid())
+  userId    String   @map("user_id")
+  endpoint  String   @unique
+  p256dh    String
+  auth      String
+  // Free-form browser/device hint ("Chrome · Linux") for a device list.
+  userAgent String?  @map("user_agent")
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+
+  @@index([userId])
+  @@map("push_subscriptions")
+}

package/scripts/sync-notifications-schema.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/* global console, process */
+/**
+ * Copy this package's Prisma model PARTIAL into the host's schema folder.
+ *
+ *   node scripts/sync-notifications-schema.mjs [--check] [<host-schema-dir>]
+ *
+ * The partial is COPIED, never symlinked (the
+ * prisma-partials-are-copied-never-symlinked doctrine): `turbo prune` copies
+ * only what the dependency graph reaches, so a committed symlink dangles the
+ * moment the owning package is not a declared workspace dependency — and a
+ * SYMLINKED MIGRATION is silently skipped by Prisma (`readdir` +
+ * `isDirectory()` is false for a link), so a green deploy applies no schema.
+ *
+ * Only the schema partial. MIGRATIONS ARE NOT HANDLED HERE — the host discovers
+ * and copies them structurally, by looking for a `prisma/migrations` directory
+ * inside every installed `@12-apps/*` package (see
+ * packages/prisma/scripts/sync-prisma-plugins.mjs in this repo).
+ *
+ * The host package that owns the schema folder MUST also declare this package
+ * as a dependency, so the source of the copy is present in every build context.
+ *
+ * Default host path follows the future-pay layout
+ * (`packages/prisma/prisma/schema/`); another repo passes its own schema folder
+ * as the positional argument, or sets NOTIFICATIONS_HOST_SCHEMA_DIR.
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const LABEL = '[notifications-schema]';
+const RESYNC = 'pnpm --filter @12-apps/notifications prisma:sync';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SOURCE = join(HERE, '../prisma/notifications.prisma');
+
+const args = process.argv.slice(2).filter((arg) => arg !== '--check');
+const check = process.argv.includes('--check');
+const hostSchemaDir =
+  args[0] ??
+  process.env.NOTIFICATIONS_HOST_SCHEMA_DIR ??
+  join(HERE, '../../prisma/prisma/schema');
+const TARGET = join(hostSchemaDir, 'notifications.prisma');
+
+const source = readFileSync(SOURCE, 'utf8');
+const target = existsSync(TARGET) ? readFileSync(TARGET, 'utf8') : null;
+
+if (source === target) {
+  console.log(`${LABEL} in sync.`);
+} else if (check) {
+  console.error(
+    `${LABEL} DRIFT: ${TARGET} does not match the @12-apps/notifications partial. ` +
+      `Run "${RESYNC}" and commit the result.`,
+  );
+  process.exit(1);
+} else {
+  mkdirSync(hostSchemaDir, { recursive: true });
+  copyFileSync(SOURCE, TARGET);
+  console.log(`${LABEL} copied ${SOURCE} -> ${TARGET}.`);
+}

package/src/errors.ts

@@ -0,0 +1,21 @@
+/** Thrown by `notify` when no generator is registered for the event type. */
+export class UnknownNotificationTypeError extends Error {
+  readonly type: string;
+  constructor(type: string) {
+    super(`No notification generator registered for type "${type}".`);
+    this.name = 'UnknownNotificationTypeError';
+    this.type = type;
+    Object.setPrototypeOf(this, UnknownNotificationTypeError.prototype);
+  }
+}
+
+/** Thrown by `notify` when the recipient has no contact record in the host. */
+export class UnknownNotificationRecipientError extends Error {
+  readonly userId: string;
+  constructor(userId: string) {
+    super(`notify(): unknown recipient user "${userId}".`);
+    this.name = 'UnknownNotificationRecipientError';
+    this.userId = userId;
+    Object.setPrototypeOf(this, UnknownNotificationRecipientError.prototype);
+  }
+}

package/src/generators.ts

@@ -0,0 +1,44 @@
+import { UnknownNotificationTypeError } from './errors';
+import type { NotificationGenerator } from './types';
+
+/**
+ * Generator registry: one {@link NotificationGenerator} per event `type`.
+ *
+ * INSTANCE state, not a module-level Map. future-pay's original was
+ * process-wide, which is what a package of loose functions forces; a factory
+ * config does not need it, and one registry per mount is what makes a test (or
+ * a second mount) able to hold its own set without clearing anyone else's.
+ * Domain modules still register from the OUTSIDE — that is the open/closed
+ * seam the whole pipeline is built on — either through the server config's
+ * `generators` array or through `registerGenerator` for a late arrival.
+ */
+export interface NotificationGeneratorRegistry {
+  /** Register (last-wins, so a re-import is idempotent). */
+  register<TPayload>(generator: NotificationGenerator<TPayload>): void;
+  /** Resolve for `type`, throwing {@link UnknownNotificationTypeError}. */
+  resolve(type: string): NotificationGenerator<never>;
+  /** Whether a generator is registered for `type` (emit-site guard). */
+  has(type: string): boolean;
+  /** Every registered type, for diagnostics. */
+  types(): string[];
+}
+
+export function createGeneratorRegistry(
+  initial: readonly NotificationGenerator<never>[] = [],
+): NotificationGeneratorRegistry {
+  const generators = new Map<string, NotificationGenerator<never>>();
+  const registry: NotificationGeneratorRegistry = {
+    register(generator) {
+      generators.set(generator.type, generator as NotificationGenerator<never>);
+    },
+    resolve(type) {
+      const generator = generators.get(type);
+      if (!generator) throw new UnknownNotificationTypeError(type);
+      return generator;
+    },
+    has: (type) => generators.has(type),
+    types: () => [...generators.keys()],
+  };
+  for (const generator of initial) registry.register(generator);
+  return registry;
+}

package/src/hono/index.ts

@@ -0,0 +1,121 @@
+import { Hono } from 'hono';
+import type { Context } from 'hono';
+
+import { messagesOf } from '../messages';
+
+import {
+  createApiNotifications,
+  type ApiNotifications,
+  type NotificationsServerConfig,
+} from '../server/create-api-notifications';
+import type { NotificationsActor } from '../server/context';
+
+/**
+ * `@12-apps/notifications/hono` — the account notification endpoints as a
+ * mountable router.
+ *
+ * The framework-neutral descriptors in `/server` are the contract; this is the
+ * adapter for the framework we happen to use, behind its own subpath with
+ * `hono` as an OPTIONAL peer (the report-builder precedent — a host on Express,
+ * or one that only wants the React surface, never resolves Hono).
+ *
+ * A host writes:
+ *
+ *   const notifications = notificationsRouter({ …config, resolveActor });
+ *   app.route('/api/account', notifications.router);
+ *
+ * and keeps what is genuinely its own: who the caller is. Everything after
+ * that — parsing, status codes, the envelope, the pt-BR copy — is the
+ * package's.
+ */
+
+/**
+ * Resolve the caller. Returning `null` means unauthenticated, which answers 401
+ * before any handler runs.
+ *
+ * Note the 401 is self-guarded HERE rather than assumed from middleware: these
+ * paths sit under an API prefix that a host's page middleware typically does not
+ * match, and an unauthenticated inbox read that fell through would answer
+ * somebody else's rows or none at all — both worse than a 401.
+ */
+export type ResolveNotificationsActor = (
+  c: Context,
+) => Promise<NotificationsActor | null> | NotificationsActor | null;
+
+export interface NotificationsHonoConfig extends NotificationsServerConfig {
+  resolveActor: ResolveNotificationsActor;
+}
+
+export interface NotificationsHono extends ApiNotifications {
+  router: Hono;
+}
+
+/**
+ * Reads the JSON body, tolerating an absent or malformed one — and only when
+ * the caller SAID it was JSON.
+ *
+ * The content-type check is a CSRF speed bump, not a defence (see ADOPTING rule
+ * 13, which names the actual one). `text/plain`, `multipart/form-data` and
+ * `application/x-www-form-urlencoded` are the three types a cross-site `fetch`
+ * or a plain `<form>` can send with NO preflight, so parsing a body regardless
+ * of its type is what lets such a request reach these handlers at all. Refusing
+ * them means a cross-site write has to earn a preflight first, which the browser
+ * will then refuse on its own. The price is nil: every client of this surface,
+ * the packaged one included, sends `application/json`.
+ */
+function saysJson(c: Context): boolean {
+  const type = c.req.header('content-type');
+  if (!type) return false;
+  const mime = (type.split(';')[0] ?? '').trim().toLowerCase();
+  return mime === 'application/json' || mime.endsWith('+json');
+}
+
+async function readBody(c: Context): Promise<unknown> {
+  if (c.req.method === 'GET') return undefined;
+  if (!saysJson(c)) return undefined;
+  try {
+    return await c.req.json();
+  } catch {
+    // A malformed body is the caller's error; the handler's own validation
+    // reports it far better than a parse failure would.
+    return undefined;
+  }
+}
+
+export function notificationsRouter(config: NotificationsHonoConfig): NotificationsHono {
+  const api = createApiNotifications(config);
+  const messages = messagesOf(config);
+  const router = new Hono();
+
+  // Mounted IN DESCRIPTOR ORDER, which any adapter must preserve. Hono resolves
+  // by registration order, so a host route shaped `/notifications/:id` under the
+  // same prefix must be registered AFTER this router or it captures
+  // `/notifications/unread-count`.
+  for (const route of api.routes) {
+    const handler = async (c: Context): Promise<Response> => {
+      const actor = await config.resolveActor(c);
+      if (!actor) return c.json({ error: messages.unauthenticated }, 401);
+
+      const response = await route.handle({
+        actor,
+        params: c.req.param() as Record<string, string | undefined>,
+        query: c.req.query() as Record<string, string | undefined>,
+        body: await readBody(c),
+        headers: { 'user-agent': c.req.header('user-agent') },
+      });
+
+      // A handler that chose NO body means exactly that (204).
+      if (response.body === undefined) return c.body(null, response.status as 204);
+      // The status travels with the body the handler chose; the adapter never
+      // reinterprets either.
+      return c.json(response.body as Record<string, unknown>, response.status as 200);
+    };
+
+    if (route.method === 'GET') router.get(route.path, handler);
+    else if (route.method === 'POST') router.post(route.path, handler);
+    else if (route.method === 'PUT') router.put(route.path, handler);
+    else router.delete(route.path, handler);
+  }
+
+  return { ...api, router };
+}