@12-apps/notifications 1.0.0

package/src/server/dispatch.ts

@@ -0,0 +1,298 @@
+import type {
+  DeliveryStatus,
+  NotificationChannel,
+  NotificationContent,
+  NotificationLogger,
+  TransportRecipient,
+} from '../types';
+
+import type {
+  NotificationContactDirectory,
+  NotificationDeliveryRow,
+  NotificationsDb,
+  NotificationsDbProvider,
+} from './db';
+import type { PushSubscriptionStore } from './push-subscriptions';
+import type { TransportRegistry } from './transports/registry';
+
+/**
+ * Handing a delivery to its transport, and the retry sweep that re-hands the
+ * ones that did not make it (12-15).
+ *
+ * ## Every send is CLAIMED first
+ *
+ * A dispatcher never sends a row it merely READ. It moves the row `QUEUED →
+ * SENDING` with one conditional `updateMany` whose `where` carries the
+ * precondition, and sends only when that statement reports `count === 1`:
+ *
+ *     updateMany({ where: { id, status: 'QUEUED' }, data: { status: 'SENDING' } })
+ *
+ * The database decides the winner, in one statement, so two dispatchers racing
+ * the same delivery produce exactly one provider call. The version this replaced
+ * read the QUEUED rows, called `transport.send`, and only then wrote `SENT` —
+ * with nothing marking the row taken in between, which is a read-validate-write
+ * with a network round trip in the window. It needed no crash to double-send: a
+ * sweep whose backlog outlived its own cron interval overlapped itself, and
+ * every row the first run had not yet reached was sent twice. On SMS and
+ * WhatsApp that is a second billed message to a real phone.
+ *
+ * A single-threaded fake cannot tell the two implementations apart, which is why
+ * the concurrency contracts are pinned against real SQL in
+ * `harness/backend/tests/notifications-pipeline.test.ts` as well as against the
+ * in-memory seam.
+ *
+ * ## Nothing is retried forever
+ *
+ * Each claim increments `attempts` — at CLAIM time, so a dispatcher that dies
+ * mid-send still spends one — and the `maxAttempts`-th failure writes `DEAD`
+ * instead of `FAILED`. A `DEAD` row is terminal: no sweep selects it again.
+ * Without a ceiling a permanently invalid destination is a billed provider call
+ * on every sweep for the life of the row, and the sweep's working set only ever
+ * grows.
+ *
+ * ## The sweep is bounded and cannot un-send
+ *
+ * It selects on `updatedAt` (never `createdAt`), takes at most `take` rows, and
+ * re-queues each one with the same conditional-update shape — status pinned to
+ * what was read, plus the staleness predicate. A row another dispatcher has
+ * already moved fails that predicate, so a committed `SENT` can never be dragged
+ * back to `QUEUED`.
+ */
+
+/** Claims a delivery gets before it is DEAD. Overridable per mount. */
+export const DEFAULT_MAX_DELIVERY_ATTEMPTS = 5;
+
+/** Rows one sweep may take. Bounds a run to well inside a cron interval. */
+export const DEFAULT_SWEEP_TAKE = 200;
+
+/** Default staleness cutoff: a row that has not moved in five minutes. */
+export const DEFAULT_SWEEP_CUTOFF_MS = 5 * 60_000;
+
+/**
+ * The statuses a sweep may return to QUEUED, once stale.
+ *
+ * `SENDING` is in the list because that is what a dispatcher that died mid-send
+ * leaves behind, and it is safe precisely because of the cutoff: a SENDING row
+ * younger than the cutoff belongs to a dispatcher that is still working.
+ * `SENT` and `DEAD` are absent, and that is the whole point of them.
+ */
+const RETRYABLE: DeliveryStatus[] = ['FAILED', 'QUEUED', 'SENDING'];
+
+/** What dispatch needs from the mount. */
+export interface NotificationDispatchDeps {
+  db: NotificationsDbProvider;
+  transports: TransportRegistry;
+  pushSubscriptions: PushSubscriptionStore;
+  contacts: NotificationContactDirectory;
+  logger: NotificationLogger;
+  maxAttempts: number;
+}
+
+/** Load the recipient's destinations once, for every transport's gate. */
+export async function loadRecipient(
+  deps: NotificationDispatchDeps,
+  userId: string,
+): Promise<TransportRecipient | null> {
+  const contact = await deps.contacts.getContact(userId);
+  if (!contact) return null;
+  return {
+    userId,
+    email: contact.email,
+    phone: contact.phone,
+    pushSubscriptionCount: await deps.pushSubscriptions.count(userId),
+  };
+}
+
+/** The stored inbox row, back as the agnostic content a formatter takes. */
+function contentOf(notification: {
+  title: string;
+  body: string;
+  link: string | null;
+  data: unknown;
+}): NotificationContent {
+  return {
+    title: notification.title,
+    body: notification.body,
+    ...(notification.link !== null ? { link: notification.link } : {}),
+    data: (notification.data ?? {}) as Record<string, unknown>,
+  };
+}
+
+const messageOf = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+/** Record the outcome of a claimed send — terminal once the ceiling is hit. */
+async function settle(
+  deps: NotificationDispatchDeps,
+  client: NotificationsDb,
+  delivery: NotificationDeliveryRow,
+  error: unknown,
+): Promise<void> {
+  // `attempts` was read BEFORE this claim incremented it, so `+ 1` is the
+  // attempt that just failed.
+  const spent = delivery.attempts + 1;
+  const terminal = spent >= deps.maxAttempts;
+  await client.notificationDelivery.update({
+    where: { id: delivery.id },
+    data: {
+      status: terminal ? 'DEAD' : 'FAILED',
+      error: terminal ? `${messageOf(error)} (gave up after ${spent} attempts)` : messageOf(error),
+    },
+  });
+}
+
+/**
+ * Claim one delivery and, if we won it, send it.
+ *
+ * Resolves whether a provider call was made, which is what the sweep counts —
+ * "dispatched" must mean sends attempted, not rows looked at.
+ */
+async function sendClaimed(
+  deps: NotificationDispatchDeps,
+  client: NotificationsDb,
+  delivery: NotificationDeliveryRow,
+  content: NotificationContent,
+  recipient: TransportRecipient,
+): Promise<boolean> {
+  const claimed = await client.notificationDelivery.updateMany({
+    where: { id: delivery.id, status: 'QUEUED' },
+    data: { status: 'SENDING', attempts: { increment: 1 } },
+  });
+  // Someone else moved it between our read and here. They own the send now.
+  if (claimed.count !== 1) return false;
+
+  const transport = deps.transports.get(delivery.channel as NotificationChannel);
+  try {
+    if (!transport) throw new Error(`No transport declared for ${delivery.channel}.`);
+    await transport.send(transport.format(content) as never, recipient);
+    await client.notificationDelivery.update({
+      where: { id: delivery.id },
+      data: { status: 'SENT', sentAt: new Date(), error: null },
+    });
+  } catch (error) {
+    await settle(deps, client, delivery, error);
+  }
+  return true;
+}
+
+/**
+ * The recipient no longer exists, so no channel will ever reach them.
+ *
+ * The rows are marked DEAD rather than left QUEUED: `getContact` returning null
+ * is the host saying "no such person" (the same answer `notify` throws on), and
+ * a QUEUED row for a deleted account is a row every sweep, forever, picks up and
+ * cannot deliver.
+ */
+async function abandonUnreachable(
+  deps: NotificationDispatchDeps,
+  client: NotificationsDb,
+  queued: readonly NotificationDeliveryRow[],
+  userId: string,
+): Promise<void> {
+  deps.logger.error(
+    `[notifications] no contact for user ${userId}: ${queued.length} delivery row(s) marked DEAD`,
+  );
+  for (const delivery of queued) {
+    await client.notificationDelivery.update({
+      where: { id: delivery.id },
+      data: { status: 'DEAD', error: 'The contact directory no longer knows this recipient.' },
+    });
+  }
+}
+
+/**
+ * Send every still-QUEUED delivery of one notification, claiming each one first.
+ *
+ * Safe to call repeatedly and safe to call concurrently: SENT, SENDING and DEAD
+ * rows are not selected, and of two callers that both read the same QUEUED row
+ * only one wins the claim.
+ */
+export async function dispatchOne(
+  deps: NotificationDispatchDeps,
+  notificationId: string,
+): Promise<number> {
+  const client = await deps.db();
+  const notification = await client.notification.findUnique({ where: { id: notificationId } });
+  if (!notification) return 0;
+  const queued = await client.notificationDelivery.findMany({
+    where: { notificationId, status: 'QUEUED' },
+  });
+  if (queued.length === 0) return 0;
+
+  const recipient = await loadRecipient(deps, notification.userId);
+  if (!recipient) {
+    await abandonUnreachable(deps, client, queued, notification.userId);
+    return 0;
+  }
+
+  const content = contentOf(notification);
+  // Sequential on purpose: one recipient's channels (2–4 sends) gain little
+  // from parallelism, and providers rate-limit per sender anyway.
+  let sent = 0;
+  for (const delivery of queued) {
+    if (await sendClaimed(deps, client, delivery, content, recipient)) sent += 1;
+  }
+  return sent;
+}
+
+/**
+ * Return one stale row to QUEUED, or report that somebody else got there first.
+ *
+ * The `where` is the guard, and every clause of it is load-bearing: `status`
+ * pinned to the value we READ means a row that has since been SENT is not
+ * dragged back (the unguarded version matched on `id` alone and reverted
+ * committed sends, leaving a row claiming QUEUED with a `sent_at`), and
+ * `updatedAt < cutoff` means a row a concurrent sweep already re-queued — whose
+ * `updated_at` is now — is not re-queued a second time.
+ */
+async function requeue(
+  client: NotificationsDb,
+  row: NotificationDeliveryRow,
+  cutoff: Date,
+): Promise<boolean> {
+  const moved = await client.notificationDelivery.updateMany({
+    where: { id: row.id, status: row.status as DeliveryStatus, updatedAt: { lt: cutoff } },
+    data: { status: 'QUEUED' },
+  });
+  return moved.count === 1;
+}
+
+/**
+ * Retry sweep for a cron/admin trigger: re-dispatch deliveries that have not
+ * moved in `olderThanMs`.
+ *
+ * BOUNDED by `take`, deliberately. Unbounded, a 2 000-row outage backlog is a
+ * single run that takes minutes of sequential provider round trips — outliving
+ * its own cron interval, so the next tick starts while it is still working. The
+ * claim makes that overlap harmless; the bound makes it rare.
+ */
+export async function drainPending(
+  deps: NotificationDispatchDeps,
+  olderThanMs: number,
+  take: number,
+): Promise<{ dispatched: number }> {
+  const client = await deps.db();
+  const cutoff = new Date(Date.now() - olderThanMs);
+  const stale = await client.notificationDelivery.findMany({
+    where: { status: { in: RETRYABLE }, updatedAt: { lt: cutoff } },
+    orderBy: { updatedAt: 'asc' },
+    take,
+  });
+
+  const notificationIds = new Set<string>();
+  for (const row of stale) {
+    if (await requeue(client, row, cutoff)) notificationIds.add(row.notificationId);
+  }
+
+  let dispatched = 0;
+  for (const id of notificationIds) {
+    // Isolated per notification: an unreachable host seam on one of them must
+    // not cost every later row in the batch its retry.
+    try {
+      dispatched += await dispatchOne(deps, id);
+    } catch (error) {
+      deps.logger.error(`[notifications] sweep failed to dispatch ${id}:`, error);
+    }
+  }
+  return { dispatched };
+}

package/src/server/inbox.ts

@@ -0,0 +1,155 @@
+import { inboxWire, type ListNotificationsResult } from '../wire';
+
+import type {
+  NotificationDelegate,
+  NotificationPageAfter,
+  NotificationsDbProvider,
+  NotificationWhere,
+} from './db';
+
+/**
+ * Notification-centre inbox reads/writes. Every function is scoped to the
+ * OWNER's `userId` — a caller can only ever see or touch their own rows (the
+ * route layer supplies the authenticated user's id, never a client value).
+ * Soft-deleted rows (`deletedAt` set) are excluded from every read and can
+ * never be resurrected by mark-read.
+ */
+
+export interface ListNotificationsInput {
+  /** `unread` narrows to unread rows; default lists all non-deleted. */
+  filter?: 'all' | 'unread';
+  /**
+   * Cursor = the `id` of the last item of the previous page. Resolved to a
+   * KEYSET position, so a row the user soft-deleted between the two requests —
+   * routinely the bottom one, since that is the row with the delete button —
+   * still anchors the next page instead of costing it a row. Owner-checked: an
+   * id that is not the caller's names no position and answers an empty page.
+   */
+  cursor?: string;
+  /** Page size (server-clamped 1..100, default 20). */
+  limit?: number;
+}
+
+const DEFAULT_PAGE = 20;
+const MAX_PAGE = 100;
+
+export interface NotificationInboxStore {
+  list(userId: string, input?: ListNotificationsInput): Promise<ListNotificationsResult>;
+  unreadCount(userId: string): Promise<number>;
+  markRead(userId: string, ids: readonly string[]): Promise<number>;
+  markAllRead(userId: string): Promise<number>;
+  softDelete(userId: string, ids: readonly string[]): Promise<number>;
+}
+
+/**
+ * Resolve a cursor into a keyset anchor, or refuse it.
+ *
+ * OWNERSHIP-CHECKED, which the positional cursor never was: `cursor` is a raw
+ * client value, and while the `where` kept the ROWS the caller's own, the
+ * anchor's position leaked the `created_at` of whatever row the id named.
+ * `undefined` here means "this cursor names no position in your list" and the
+ * caller answers an empty page — the anchor is not `deletedAt`-filtered, so the
+ * only way to reach that is a foreign or invented id.
+ */
+async function resolveAnchor(
+  notifications: NotificationDelegate,
+  userId: string,
+  cursor: string,
+): Promise<NotificationPageAfter | undefined> {
+  const anchor = await notifications.findUnique({ where: { id: cursor } });
+  if (!anchor || anchor.userId !== userId) return undefined;
+  return { createdAt: anchor.createdAt, id: anchor.id };
+}
+
+/** The whole read filter for one page: owner, live, filter, page boundary. */
+function pageWhere(
+  userId: string,
+  filter: ListNotificationsInput['filter'],
+  anchor: NotificationPageAfter | undefined,
+): NotificationWhere {
+  return {
+    userId,
+    deletedAt: null,
+    ...(filter === 'unread' ? { readAt: null } : {}),
+    // `(createdAt, id) < (anchor.createdAt, anchor.id)`, as a portable `where`.
+    ...(anchor
+      ? {
+          OR: [
+            { createdAt: { lt: anchor.createdAt } },
+            { createdAt: anchor.createdAt, id: { lt: anchor.id } },
+          ] as NonNullable<NotificationWhere['OR']>,
+        }
+      : {}),
+  };
+}
+
+export function createInboxStore(db: NotificationsDbProvider): NotificationInboxStore {
+  return {
+    /** The owner's inbox, newest first, keyset-paginated, deleted excluded. */
+    async list(userId, input = {}) {
+      const client = await db();
+      const limit = Math.min(Math.max(input.limit ?? DEFAULT_PAGE, 1), MAX_PAGE);
+      const anchor = input.cursor
+        ? await resolveAnchor(client.notification, userId, input.cursor)
+        : undefined;
+      if (input.cursor && !anchor) return { items: [], nextCursor: null };
+      const rows = await client.notification.findMany({
+        where: pageWhere(userId, input.filter, anchor),
+        // `id` tie-breaks equal timestamps so pages never skip/repeat.
+        orderBy: [{ createdAt: 'desc' }, { id: 'desc' }],
+        take: limit + 1,
+      });
+      const page = rows.slice(0, limit);
+      return {
+        items: page.map(inboxWire),
+        nextCursor: rows.length > limit ? (page[page.length - 1]?.id ?? null) : null,
+      };
+    },
+
+    /** Unread badge count (non-deleted, unread). */
+    async unreadCount(userId) {
+      const client = await db();
+      return client.notification.count({ where: { userId, deletedAt: null, readAt: null } });
+    },
+
+    /**
+     * Mark specific notifications read. Only the owner's own, still-unread,
+     * non-deleted rows are touched — foreign or already-read ids are silently
+     * ignored (idempotent). Returns how many rows flipped.
+     */
+    async markRead(userId, ids) {
+      if (ids.length === 0) return 0;
+      const client = await db();
+      const result = await client.notification.updateMany({
+        where: { id: { in: [...ids] }, userId, deletedAt: null, readAt: null },
+        data: { readAt: new Date() },
+      });
+      return result.count;
+    },
+
+    /** Mark every unread notification of the owner read ("mark all"). */
+    async markAllRead(userId) {
+      const client = await db();
+      const result = await client.notification.updateMany({
+        where: { userId, deletedAt: null, readAt: null },
+        data: { readAt: new Date() },
+      });
+      return result.count;
+    },
+
+    /**
+     * Soft-delete notifications (single or bulk): stamps `deletedAt` so the
+     * rows drop out of every list/count forever, while the delivery audit
+     * trail under them survives. Owner-scoped and idempotent like mark-read.
+     */
+    async softDelete(userId, ids) {
+      if (ids.length === 0) return 0;
+      const client = await db();
+      const result = await client.notification.updateMany({
+        where: { id: { in: [...ids] }, userId, deletedAt: null },
+        data: { deletedAt: new Date() },
+      });
+      return result.count;
+    },
+  };
+}

package/src/server/index.ts

@@ -0,0 +1,115 @@
+/**
+ * `@12-apps/notifications/server` — the host-mounted backend half (12-15).
+ *
+ * Server-only: the transports reach for `Buffer` and the network. Everything a
+ * browser also needs (types, the preference policy, the wire shape, the copy)
+ * lives in the root entry and is re-exported by neither half, so the two can
+ * never drift into two vocabularies.
+ */
+
+export {
+  createApiNotifications,
+  type ApiNotifications,
+  type NotificationsServerConfig,
+} from './create-api-notifications';
+
+export {
+  NotificationsApiError,
+  foldApiError,
+  ok,
+  type NotificationsActor,
+  type NotificationsRequest,
+  type NotificationsResponse,
+  type NotificationsRoute,
+} from './context';
+
+export type {
+  NotificationContactDirectory,
+  NotificationCreateData,
+  NotificationDelegate,
+  NotificationDeliveryDelegate,
+  NotificationDeliveryRow,
+  NotificationDeliveryWhere,
+  NotificationPageAfter,
+  NotificationPreferenceDelegate,
+  NotificationPreferenceRow,
+  NotificationWhere,
+  NotificationsDb,
+  NotificationsDbClient,
+  NotificationsDbProvider,
+  PushSubscriptionDelegate,
+  PushSubscriptionRow,
+} from './db';
+
+export type { ListNotificationsInput, NotificationInboxStore } from './inbox';
+export type { NotificationPreferenceStore } from './preferences';
+export type { PushSubscriptionInput, PushSubscriptionStore } from './push-subscriptions';
+
+export type {
+  CommittedNotification,
+  NotificationChannelPolicy,
+  NotificationCommittedListener,
+  NotificationDispatchScheduler,
+  NotificationRouter,
+  NotifyOptions,
+  NotifyResult,
+} from './router';
+
+export type {
+  NotificationAudienceDirectory,
+  NotifyByPermission,
+  PermissionNotificationResult,
+  PermissionNotificationSkip,
+} from './by-permission';
+
+export {
+  NotificationProviderError,
+  absoluteLink,
+  type DriverDeclarationBase,
+  type FetchImpl,
+} from './transports/drivers';
+
+export {
+  createTransportRegistry,
+  type ExtraDrivers,
+  type TransportDeclaration,
+  type TransportRegistry,
+} from './transports/registry';
+
+export {
+  EMAIL_DRIVERS,
+  emailTransport,
+  formatEmail,
+  type EmailDriver,
+  type EmailDriverDeclaration,
+  type EmailMessage,
+} from './transports/email';
+
+export {
+  SMS_DRIVERS,
+  formatSms,
+  smsTransport,
+  type SmsDriver,
+  type SmsDriverDeclaration,
+  type SmsMessage,
+} from './transports/sms';
+
+export {
+  WHATSAPP_DRIVERS,
+  formatWhatsApp,
+  whatsAppTransport,
+  type WhatsAppDriver,
+  type WhatsAppDriverDeclaration,
+  type WhatsAppMessage,
+} from './transports/whatsapp';
+
+export {
+  WEB_PUSH_DRIVERS,
+  formatWebPush,
+  webPushTransport,
+  type WebPushDriverDeclaration,
+  type WebPushMessage,
+  type WebPushSender,
+  type WebPushSubscription,
+  type WebPushSubscriptionSource,
+} from './transports/web-push';

package/src/server/preferences.ts

@@ -0,0 +1,103 @@
+import {
+  DEFAULT_CHANNEL_ROW,
+  enabledChannelsOf,
+  mergeChoices,
+  mergeStoredRow,
+  type ChannelMatrix,
+  type ChannelRow,
+} from '../preferences-core';
+import type {
+  NotificationCategory,
+  NotificationChannel,
+  NotificationTaxonomy,
+} from '../types';
+
+import type { NotificationsDbProvider } from './db';
+
+/**
+ * Per-user channel preferences: which transport channels may carry each
+ * notification category to a user. The inbox is NOT gated here — it is always
+ * on.
+ *
+ * The POLICY (defaults, coercion, merge) lives in `../preferences-core.ts`;
+ * this is the storage over it, and the split is what lets the react half render
+ * the same defaults before the first read lands.
+ */
+
+export interface NotificationPreferenceStore {
+  /** The user's full matrix, defaults merged in. */
+  get(userId: string): Promise<ChannelMatrix>;
+  /** Persist explicit choices for any subset of categories/toggles. */
+  save(
+    userId: string,
+    input: Partial<Record<NotificationCategory, Partial<ChannelRow>>>,
+  ): Promise<void>;
+  /** The channels enabled for one (user, category) — the router's gate. */
+  enabledChannels(
+    userId: string,
+    category: NotificationCategory,
+  ): Promise<NotificationChannel[]>;
+}
+
+export function createPreferenceStore(
+  db: NotificationsDbProvider,
+  taxonomy: NotificationTaxonomy,
+  channelDefaults: Partial<ChannelRow> = {},
+): NotificationPreferenceStore {
+  const defaultRow: ChannelRow = { ...DEFAULT_CHANNEL_ROW, ...channelDefaults };
+  const known = new Set(taxonomy.categories);
+
+  return {
+    async get(userId) {
+      const client = await db();
+      const rows = await client.notificationPreference.findMany({ where: { userId } });
+      const stored = new Map(rows.map((row) => [row.category, row.channels]));
+      return Object.fromEntries(
+        taxonomy.categories.map((category) => [
+          category,
+          // A category with no row, or a row missing a channel key, falls back
+          // to the defaults — so a NEW channel ships without a data migration.
+          mergeStoredRow(stored.get(category), defaultRow),
+        ]),
+      ) as ChannelMatrix;
+    },
+
+    /**
+     * Only the categories present on `input` are written; within a category,
+     * the toggles are merged over the user's CURRENT effective row (their
+     * stored choices, or the defaults when none) — so a single-toggle save
+     * (how the settings UI writes) never resets the category's other channels
+     * back to their defaults.
+     *
+     * A category outside the taxonomy is IGNORED rather than stored: the DB
+     * CHECK would reject it anyway, and a 500 from a stale client's extra key
+     * would fail the whole save including the toggle the user did flip.
+     */
+    async save(userId, input) {
+      const client = await db();
+      for (const [category, choices] of Object.entries(input)) {
+        if (!choices || !known.has(category)) continue;
+        const existing = await client.notificationPreference.findUnique({
+          where: { userId_category: { userId, category } },
+        });
+        const current = existing ? mergeStoredRow(existing.channels, defaultRow) : defaultRow;
+        const channels = mergeChoices(current, choices);
+        await client.notificationPreference.upsert({
+          where: { userId_category: { userId, category } },
+          create: { userId, category, channels },
+          update: { channels },
+        });
+      }
+    },
+
+    async enabledChannels(userId, category) {
+      const client = await db();
+      const row = await client.notificationPreference.findUnique({
+        where: { userId_category: { userId, category } },
+      });
+      return enabledChannelsOf(
+        row ? mergeStoredRow(row.channels, defaultRow) : defaultRow,
+      );
+    },
+  };
+}