@better-forge/notify 0.0.0-stage → 0.1.0

package/src/engine.ts

@@ -0,0 +1,423 @@
+import { and, asc, desc, eq, gt, gte, inArray, isNotNull, like, lt, lte, ne, sql } from 'drizzle-orm'
+import type { NotificationSuppressionReason, VaultRef } from '@better-forge/contracts'
+import type { SqliteDatabase } from '@better-forge/db'
+import { createAlertPolicy, isWithinQuietHours, quietHoursEndAt, type AlertPolicy } from './alertPolicy.js'
+import type { NotifyTables } from './tables.js'
+import { MAX_DELIVERY_ATTEMPTS, RETRY_DELAYS_MS } from './template.js'
+
+export type ChannelRow = NotifyTables['notificationChannels']['$inferSelect']
+export type DeliveryRow = NotifyTables['notificationDeliveries']['$inferSelect']
+
+/** What a delivery is about. A delivery without a source (a test, a digest) has none. */
+export interface DeliveryDetails {
+  sourceId: number | null
+  sourceName: string
+  eventType: string
+}
+
+export interface NotifyEngineOptions {
+  db: SqliteDatabase
+  tables: NotifyTables
+  /** Stored name of the grouping threshold in a channel's alert policy; see `createAlertPolicy`. */
+  minSourcesKey: string
+  /** The event types the application raises that alert hygiene treats specially. */
+  events: {
+    /** Rate-capped per source; the only event a quiet-hours or throttle rule can drop. */
+    alert: string
+    /** Closes an alert. Together with `alert` it tells whether a source still has an alert open. */
+    recovery: string
+    /** Never folded into a digest. */
+    ungrouped: string
+  }
+  /** Sends one delivery's variables through the channel. Throws on failure. */
+  deliver: (channel: ChannelRow, vars: Record<string, string>) => Promise<void>
+  /** The notification that stands in for several single-source events: its variables and the name it is recorded under. */
+  digest: (rows: DeliveryRow[], now: number) => { vars: Record<string, string>; sourceName: string }
+  /** Resolves a vault reference to its secret fields (used for SMTP credentials). */
+  resolveSecret: (ref: VaultRef) => Promise<Record<string, string>>
+}
+
+export interface SmtpMessage {
+  to: string
+  subject: string
+  text: string
+  /** Sent alongside `text` as multipart/alternative; clients that cannot render HTML show the text. */
+  html?: string
+  headers?: Record<string, string>
+}
+
+type DeliveryVariant =
+  | { status: 'pending'; releaseAt?: number; groupKey?: string | null }
+  | { status: 'suppressed'; reason: NotificationSuppressionReason }
+
+interface DeliveryPlan {
+  /** When the delivery may first be attempted. */
+  releaseAt: number
+  /** Digest window this delivery belongs to, or null when it stands alone. */
+  groupKey: string | null
+  suppressionReason: NotificationSuppressionReason | null
+}
+
+/** Delivery history older than this is purged. */
+const DELIVERY_RETENTION_MS = 180 * 24 * 60 * 60 * 1000
+
+/**
+ * The delivery engine: records every notification, applies the channel's alert hygiene, sends with retries, folds
+ * bursts into digests and sends SMTP mail. Locks and in-flight sets live in the returned closure, so two engines
+ * never share state.
+ */
+export function createNotifyEngine(options: NotifyEngineOptions) {
+  const { db, deliver, resolveSecret } = options
+  const { notificationChannels, notificationDeliveries, notificationDeliveryAttempts, smtpSettings } = options.tables
+  const { parseAlertPolicy } = createAlertPolicy({ minSourcesKey: options.minSourcesKey })
+  const activeDeliveries = new Set<number>()
+
+  /**
+   * Writes one delivery row. A pending row is picked up for sending at `releaseAt`; a suppressed row
+   * records an event that alert hygiene dropped, so the history still shows what was not sent.
+   */
+  async function insertDelivery(
+    channel: ChannelRow,
+    vars: Record<string, string>,
+    details: DeliveryDetails,
+    variant: DeliveryVariant,
+  ): Promise<number> {
+    const now = Date.now()
+    const [delivery] = await db.insert(notificationDeliveries).values({
+      channelId: channel.id,
+      channelName: channel.name,
+      channelType: channel.type,
+      sourceId: details.sourceId,
+      sourceName: details.sourceName,
+      eventType: details.eventType,
+      status: variant.status,
+      targetStatus: vars['status'] ?? 'unknown',
+      previousStatus: vars['previous_status'] ?? 'unknown',
+      variables: JSON.stringify(vars),
+      attemptCount: 0,
+      maxAttempts: MAX_DELIVERY_ATTEMPTS,
+      ...(variant.status === 'pending'
+        ? { nextAttemptAt: variant.releaseAt ?? now, groupKey: variant.groupKey ?? null }
+        : { nextAttemptAt: null, suppressionReason: variant.reason }),
+      createdAt: now,
+      updatedAt: now,
+    }).returning({ id: notificationDeliveries.id })
+    return delivery!.id
+  }
+
+  async function attemptDelivery(deliveryId: number, now = Date.now()): Promise<void> {
+    if (activeDeliveries.has(deliveryId)) return
+    activeDeliveries.add(deliveryId)
+    try {
+      const delivery = (await db.select().from(notificationDeliveries).where(eq(notificationDeliveries.id, deliveryId)))[0]
+      if (!delivery || delivery.status === 'delivered' || delivery.attemptCount >= delivery.maxAttempts) return
+      const channel = (await db.select().from(notificationChannels).where(eq(notificationChannels.id, delivery.channelId)))[0]
+      const attemptNumber = delivery.attemptCount + 1
+      const startedAt = Date.now()
+      try {
+        if (!channel) throw new Error('Notification channel no longer exists')
+        if (channel.enabled !== 1) throw new Error('Notification channel is disabled')
+        await deliver(channel, JSON.parse(delivery.variables) as Record<string, string>)
+        const completedAt = Date.now()
+        await db.insert(notificationDeliveryAttempts).values({ deliveryId, attemptNumber, status: 'delivered', error: null, startedAt, completedAt })
+        await db.update(notificationDeliveries).set({
+          status: 'delivered', attemptCount: attemptNumber, nextAttemptAt: null,
+          lastAttemptAt: completedAt, deliveredAt: completedAt, lastError: null, updatedAt: completedAt,
+        }).where(eq(notificationDeliveries.id, deliveryId))
+      } catch (error) {
+        const completedAt = Date.now()
+        const message = error instanceof Error ? error.message : String(error)
+        const exhausted = attemptNumber >= delivery.maxAttempts
+        const delay = RETRY_DELAYS_MS[Math.min(attemptNumber - 1, RETRY_DELAYS_MS.length - 1)]!
+        await db.insert(notificationDeliveryAttempts).values({ deliveryId, attemptNumber, status: 'failed', error: message, startedAt, completedAt })
+        await db.update(notificationDeliveries).set({
+          status: exhausted ? 'failed' : 'pending', attemptCount: attemptNumber,
+          nextAttemptAt: exhausted ? null : now + delay, lastAttemptAt: completedAt,
+          lastError: message, updatedAt: completedAt,
+        }).where(eq(notificationDeliveries.id, deliveryId))
+        console.error(`[notifier] Delivery ${deliveryId}, attempt ${attemptNumber} failed: ${message}`)
+      }
+    } finally { activeDeliveries.delete(deliveryId) }
+  }
+
+  // ── Alert hygiene: rate caps, quiet hours and digest windows ───────────────
+
+  /** Alerts already sent or queued for this source on this channel inside the throttle window. */
+  async function countRecentAlerts(channelId: number, sourceId: number, windowStart: number): Promise<number> {
+    const [row] = await db.select({ count: sql<number>`count(*)` }).from(notificationDeliveries).where(and(
+      eq(notificationDeliveries.channelId, channelId),
+      eq(notificationDeliveries.sourceId, sourceId),
+      eq(notificationDeliveries.eventType, options.events.alert),
+      ne(notificationDeliveries.status, 'suppressed'),
+      gte(notificationDeliveries.createdAt, windowStart),
+    ))
+    return row?.count ?? 0
+  }
+
+  /** The digest window this channel already has open, so a burst lands in a single group. */
+  async function findOpenGroup(channelId: number, eventType: string, now: number): Promise<{ groupKey: string; releaseAt: number } | null> {
+    const [row] = await db.select({ groupKey: notificationDeliveries.groupKey, releaseAt: notificationDeliveries.nextAttemptAt })
+      .from(notificationDeliveries)
+      .where(and(
+        eq(notificationDeliveries.channelId, channelId),
+        eq(notificationDeliveries.status, 'pending'),
+        like(notificationDeliveries.groupKey, `ch${channelId}:${eventType}:w%`),
+        gt(notificationDeliveries.nextAttemptAt, now),
+      ))
+      .orderBy(asc(notificationDeliveries.nextAttemptAt))
+      .limit(1)
+    return row?.groupKey && row.releaseAt !== null ? { groupKey: row.groupKey, releaseAt: row.releaseAt } : null
+  }
+
+  /**
+   * Applies a channel's alert hygiene to one event. Order matters: the rate cap runs first so a
+   * throttled alert never holds a digest window open, then quiet hours decide whether the event is
+   * dropped or held, then grouping decides which digest it joins.
+   */
+  async function planDelivery(
+    channel: ChannelRow,
+    policy: AlertPolicy,
+    details: DeliveryDetails,
+    now: number,
+  ): Promise<DeliveryPlan> {
+    // Recoveries are never throttled — the all-clear must always get through.
+    if (policy.throttle.enabled && details.eventType === options.events.alert && details.sourceId !== null) {
+      const windowStart = now - policy.throttle.windowMinutes * 60_000
+      const recent = await countRecentAlerts(channel.id, details.sourceId, windowStart)
+      if (recent >= policy.throttle.maxAlerts) return { releaseAt: now, groupKey: null, suppressionReason: 'throttled' }
+    }
+
+    let releaseAt = now
+    let quietUntil: number | null = null
+    if (isWithinQuietHours(policy.quietHours, now)) {
+      if (policy.quietHours.mode === 'suppress') return { releaseAt: now, groupKey: null, suppressionReason: 'quiet-hours' }
+      quietUntil = quietHoursEndAt(policy.quietHours, now)
+      releaseAt = Math.max(releaseAt, quietUntil)
+    }
+
+    let groupKey: string | null = null
+    if (policy.grouping.enabled && details.eventType !== options.events.ungrouped) {
+      if (quietUntil !== null) {
+        // Everything held for the same quiet window is released at once — digest it as one message.
+        groupKey = `ch${channel.id}:${details.eventType}:q${quietUntil}`
+      } else {
+        const open = await findOpenGroup(channel.id, details.eventType, now)
+        if (open) {
+          groupKey = open.groupKey
+          releaseAt = Math.max(releaseAt, open.releaseAt)
+        } else {
+          groupKey = `ch${channel.id}:${details.eventType}:w${now}`
+          releaseAt = Math.max(releaseAt, now + policy.grouping.windowSeconds * 1000)
+        }
+      }
+    }
+
+    return { releaseAt, groupKey, suppressionReason: null }
+  }
+
+  /**
+   * Planning reads a channel's recent deliveries and then writes one. Two events for the same
+   * channel must not interleave across those awaits, or a burst — precisely what grouping exists
+   * for — would open one digest window per source, and a rate cap would be counted from a stale
+   * total. Sending happens outside the lock so a slow endpoint never stalls the queue.
+   */
+  const channelLocks = new Map<number, Promise<unknown>>()
+
+  function withChannelLock<T>(channelId: number, work: () => Promise<T>): Promise<T> {
+    const previous = channelLocks.get(channelId) ?? Promise.resolve()
+    const next = previous.then(work, work)
+    channelLocks.set(channelId, next.catch(() => undefined))
+    return next
+  }
+
+  /**
+   * Collapses every due digest window into a single notification. A window that did not reach
+   * `minSources` distinct sources is simply released as ordinary individual deliveries, so
+   * grouping costs at most `windowSeconds` of latency and never swallows a lone alert.
+   */
+  let flushChain: Promise<unknown> = Promise.resolve()
+
+  function flushGroups(now = Date.now()): Promise<number> {
+    // The retry worker fires every 30s without awaiting the previous pass; overlapping flushes
+    // would each turn the same window into its own digest.
+    const run = () => flushDueGroups(now)
+    const next = flushChain.then(run, run)
+    flushChain = next.catch(() => undefined)
+    return next
+  }
+
+  async function flushDueGroups(now: number): Promise<number> {
+    const pending = await db.select().from(notificationDeliveries).where(and(
+      eq(notificationDeliveries.status, 'pending'),
+      isNotNull(notificationDeliveries.groupKey),
+      lte(notificationDeliveries.nextAttemptAt, now),
+    )).orderBy(asc(notificationDeliveries.createdAt))
+    if (pending.length === 0) return 0
+
+    const groups = new Map<string, DeliveryRow[]>()
+    for (const row of pending) {
+      const bucket = groups.get(row.groupKey!)
+      if (bucket) bucket.push(row)
+      else groups.set(row.groupKey!, [row])
+    }
+
+    let digests = 0
+    for (const rows of groups.values()) {
+      const ids = rows.map((row) => row.id)
+      const channel = (await db.select().from(notificationChannels).where(eq(notificationChannels.id, rows[0]!.channelId)))[0]
+      const policy = channel ? parseAlertPolicy(channel.alertPolicy) : null
+      const distinctSources = new Set(rows.map((row) => row.sourceId ?? -row.id)).size
+
+      if (!channel || !policy?.grouping.enabled || distinctSources < policy.grouping.minSources) {
+        // Not a burst — or grouping was switched off mid-window. Send them individually.
+        await db.update(notificationDeliveries).set({ groupKey: null, updatedAt: now })
+          .where(inArray(notificationDeliveries.id, ids))
+        continue
+      }
+
+      const { vars, sourceName } = options.digest(rows, now)
+      // Retire the members first: a crash between the two writes must not let both forms go out.
+      await db.update(notificationDeliveries).set({
+        status: 'suppressed', suppressionReason: 'grouped', nextAttemptAt: null, updatedAt: now,
+      }).where(inArray(notificationDeliveries.id, ids))
+      await insertDelivery(channel, vars, {
+        sourceId: null,
+        sourceName,
+        eventType: rows[0]!.eventType,
+      }, { status: 'pending', releaseAt: now })
+      digests++
+    }
+    return digests
+  }
+
+  async function processDue(now = Date.now()): Promise<number> {
+    await flushGroups(now)
+    const due = await db.select({ id: notificationDeliveries.id }).from(notificationDeliveries).where(
+      and(eq(notificationDeliveries.status, 'pending'), lte(notificationDeliveries.nextAttemptAt, now)),
+    )
+    await Promise.allSettled(due.map((delivery) => attemptDelivery(delivery.id, now)))
+    return due.length
+  }
+
+  async function retryDelivery(deliveryId: number): Promise<boolean> {
+    const delivery = (await db.select().from(notificationDeliveries).where(eq(notificationDeliveries.id, deliveryId)))[0]
+    if (!delivery || delivery.status !== 'failed') return false
+    const now = Date.now()
+    await db.update(notificationDeliveries).set({
+      status: 'pending', maxAttempts: delivery.attemptCount + MAX_DELIVERY_ATTEMPTS,
+      nextAttemptAt: now, deliveredAt: null, lastError: null, updatedAt: now,
+    }).where(eq(notificationDeliveries.id, deliveryId))
+    await attemptDelivery(deliveryId, now)
+    return true
+  }
+
+  async function purgeOldDeliveries(now = Date.now()): Promise<void> {
+    await db.delete(notificationDeliveries).where(lt(notificationDeliveries.createdAt, now - DELIVERY_RETENTION_MS))
+  }
+
+  /** True when the latest alert-or-recovery event recorded for this source is an alert. */
+  async function hasOpenAlert(sourceId: number): Promise<boolean> {
+    // Suppressed rows count: an alert that quiet hours or a digest swallowed was still raised.
+    const [last] = await db.select({ eventType: notificationDeliveries.eventType }).from(notificationDeliveries)
+      .where(and(
+        eq(notificationDeliveries.sourceId, sourceId),
+        inArray(notificationDeliveries.eventType, [options.events.alert, options.events.recovery]),
+      ))
+      .orderBy(desc(notificationDeliveries.id))
+      .limit(1)
+    return last?.eventType === options.events.alert
+  }
+
+  /**
+   * Plans one event for one channel under its lock and records it. Resolves to the delivery to send right away, or
+   * null when nothing is to be sent now (suppressed, or held for quiet hours or a digest window). Recording is
+   * separate from sending so a caller can record every channel's delivery in its own transaction and send afterwards:
+   * a recorded delivery that was never sent is picked up by `processDue`.
+   */
+  async function plan(channel: ChannelRow, vars: Record<string, string>, details: DeliveryDetails): Promise<number | null> {
+    return withChannelLock(channel.id, async () => {
+      const now = Date.now()
+      const delivery = await planDelivery(channel, parseAlertPolicy(channel.alertPolicy), details, now)
+
+      if (delivery.suppressionReason) {
+        await insertDelivery(channel, vars, details, { status: 'suppressed', reason: delivery.suppressionReason })
+        return null
+      }
+
+      const deliveryId = await insertDelivery(channel, vars, details, { status: 'pending', releaseAt: delivery.releaseAt, groupKey: delivery.groupKey })
+      return delivery.releaseAt <= now ? deliveryId : null
+    })
+  }
+
+  /** Plans one event for one channel and sends it right away when nothing holds it back. */
+  async function dispatch(channel: ChannelRow, vars: Record<string, string>, details: DeliveryDetails): Promise<void> {
+    const sendNow = await plan(channel, vars, details)
+    if (sendNow !== null) await attemptDelivery(sendNow)
+  }
+
+  /** Records a delivery that bypasses alert hygiene and sends it at once; resolves to the outcome. */
+  async function sendDirect(
+    channel: ChannelRow,
+    vars: Record<string, string>,
+    details: DeliveryDetails,
+  ): Promise<{ ok: true } | { ok: false; error: string }> {
+    const deliveryId = await insertDelivery(channel, vars, details, { status: 'pending' })
+    await attemptDelivery(deliveryId)
+    const delivery = (await db.select().from(notificationDeliveries).where(eq(notificationDeliveries.id, deliveryId)))[0]!
+    return delivery.status === 'delivered' ? { ok: true } : { ok: false, error: delivery.lastError ?? 'Delivery failed' }
+  }
+
+  // ── SMTP ───────────────────────────────────────────────────────────────────
+
+  async function isSmtpConfigured(): Promise<boolean> {
+    const smtp = (await db.select({ host: smtpSettings.host }).from(smtpSettings))[0]
+    return !!smtp?.host
+  }
+
+  /** Sends one message through the configured SMTP server. Throws when SMTP is not set up. */
+  async function sendSmtpMail(message: SmtpMessage): Promise<void> {
+    const smtp = (await db.select().from(smtpSettings))[0]
+    if (!smtp?.host) throw new Error('SMTP not configured')
+
+    let smtpUser = smtp.user
+    let smtpPass = smtp.password
+    if (smtp.vaultConfig) {
+      const ref = JSON.parse(smtp.vaultConfig) as VaultRef
+      const creds = await resolveSecret(ref)
+      smtpUser = creds['username'] ?? creds['user'] ?? smtpUser
+      smtpPass = creds['password'] ?? creds['value'] ?? smtpPass
+      // A vault reference means sign-in was intended; without a user nodemailer would skip auth silently.
+      if (!smtpUser) throw new Error('SMTP vault secret has no username: use a User / Password secret or map a username in a JSON secret')
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const nodemailer: any = await import('nodemailer')
+    const nm = nodemailer.default ?? nodemailer
+    const transporter = nm.createTransport({
+      host: smtp.host,
+      port: smtp.port,
+      secure: !!smtp.secure,
+      auth: smtpUser ? { user: smtpUser, pass: smtpPass } : undefined,
+    })
+
+    const from = smtp.fromAddress
+      ? `"${smtp.fromName}" <${smtp.fromAddress}>`
+      : smtp.fromName
+
+    await transporter.sendMail({
+      from,
+      to: message.to,
+      subject: message.subject,
+      text: message.text,
+      ...(message.html ? { html: message.html } : {}),
+      ...(message.headers ? { headers: message.headers } : {}),
+    })
+  }
+
+  return {
+    plan, dispatch, sendDirect, attemptDelivery, flushGroups, processDue, retryDelivery, purgeOldDeliveries, hasOpenAlert,
+    isSmtpConfigured, sendSmtpMail,
+  }
+}
+
+export type NotifyEngine = ReturnType<typeof createNotifyEngine>

package/src/index.ts

@@ -0,0 +1,16 @@
+export { CHANNEL_TYPES, TEMPLATE_KEYS, channelConfigError, configForEvent, eventOverridesError, type DefaultWording, type EventWording, ntfyConfigError, pushoverConfigError, telegramConfigError } from './channelInput.js'
+export { CHANNEL_DESTINATIONS, CHANNEL_SECRETS } from './channelSecrets.js'
+export {
+  createAlertPolicy, DEFAULT_ALERT_POLICY, isValidTimezone, isWithinQuietHours, localMinutes, quietHoursEndAt,
+  type AlertPolicy, type GroupingPolicy, type ThrottlePolicy,
+} from './alertPolicy.js'
+export { createNotifyDbModule, notifyMigrations } from './migrations.js'
+export { defineNotifyTables, type NotifyTableOptions, type NotifyTables } from './tables.js'
+export { buildWebhookRequest, escapeJsonString, placeholderInAuthority, MAX_DELIVERY_ATTEMPTS, RETRY_DELAYS_MS, substituteVars } from './template.js'
+export {
+  createNotifyEngine, type ChannelRow, type DeliveryDetails, type DeliveryRow, type NotifyEngine, type NotifyEngineOptions, type SmtpMessage,
+} from './engine.js'
+export { readableTimestamp, renderSegments, type Notice, type NoticeFact, type NoticeSegment, type NoticeSeverity } from './notice.js'
+export { createTransports, type TransportChannel, type TransportOptions, type Transports } from './transports.js'
+export { createNotifyRoutes, type KeyResult, type NotifyRoutesOptions } from './routes.js'
+export { createDeliveryWorker, type DeliveryWorkerOptions, type WorkerTask } from './worker.js'

package/src/migrations.ts

@@ -0,0 +1,88 @@
+import type { DbModule, MigrationStep } from '@better-forge/db'
+import { defineNotifyTables, type NotifyTableOptions } from './tables.js'
+
+/** Notification channels, their delivery history and SMTP settings. Steps run in this order. */
+export function notifyMigrations(options: Pick<NotifyTableOptions, 'sourceIdColumn' | 'sourceNameColumn' | 'smtpFromName'>): readonly MigrationStep[] {
+  const { sourceIdColumn, sourceNameColumn, smtpFromName } = options
+  return [
+    { kind: 'exec', sql: `
+CREATE TABLE IF NOT EXISTS notification_channels (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL,
+  type TEXT NOT NULL,
+  config TEXT NOT NULL DEFAULT '{}',
+  enabled INTEGER NOT NULL DEFAULT 1,
+  notify_on_recovery INTEGER NOT NULL DEFAULT 0,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+` },
+    { kind: 'exec', sql: `
+CREATE TABLE IF NOT EXISTS notification_deliveries (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  channel_id INTEGER NOT NULL,
+  channel_name TEXT NOT NULL,
+  channel_type TEXT NOT NULL,
+  ${sourceIdColumn} INTEGER,
+  ${sourceNameColumn} TEXT NOT NULL,
+  event_type TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending',
+  target_status TEXT NOT NULL,
+  previous_status TEXT NOT NULL,
+  variables TEXT NOT NULL,
+  attempt_count INTEGER NOT NULL DEFAULT 0,
+  max_attempts INTEGER NOT NULL DEFAULT 3,
+  next_attempt_at INTEGER,
+  last_attempt_at INTEGER,
+  delivered_at INTEGER,
+  last_error TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_notification_deliveries_status_next ON notification_deliveries(status, next_attempt_at);
+CREATE INDEX IF NOT EXISTS idx_notification_deliveries_created ON notification_deliveries(created_at);
+` },
+    { kind: 'exec', sql: `
+CREATE TABLE IF NOT EXISTS notification_delivery_attempts (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  delivery_id INTEGER NOT NULL,
+  attempt_number INTEGER NOT NULL,
+  status TEXT NOT NULL,
+  error TEXT,
+  started_at INTEGER NOT NULL,
+  completed_at INTEGER NOT NULL,
+  FOREIGN KEY (delivery_id) REFERENCES notification_deliveries(id) ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS idx_notification_delivery_attempts_delivery ON notification_delivery_attempts(delivery_id, attempt_number);
+` },
+    { kind: 'exec', sql: `
+CREATE TABLE IF NOT EXISTS smtp_settings (
+  id INTEGER PRIMARY KEY,
+  host TEXT NOT NULL DEFAULT '',
+  port INTEGER NOT NULL DEFAULT 587,
+  secure INTEGER NOT NULL DEFAULT 0,
+  user TEXT NOT NULL DEFAULT '',
+  password TEXT NOT NULL DEFAULT '',
+  from_address TEXT NOT NULL DEFAULT '',
+  from_name TEXT NOT NULL DEFAULT '${smtpFromName}',
+  updated_at INTEGER NOT NULL
+);
+` },
+    { kind: 'column', sql: `ALTER TABLE smtp_settings ADD COLUMN vault_config TEXT`, desc: 'smtp_settings.vault_config' },
+    { kind: 'column', sql: `ALTER TABLE notification_channels ADD COLUMN alert_policy TEXT NOT NULL DEFAULT '{}'`, desc: 'notification_channels.alert_policy' },
+    // SQLite cannot add a UNIQUE column. The application fills the keys of existing rows and then adds the unique index.
+    { kind: 'column', sql: `ALTER TABLE notification_channels ADD COLUMN key TEXT NOT NULL DEFAULT ''`, desc: 'notification_channels.key' },
+    { kind: 'column', sql: `ALTER TABLE notification_deliveries ADD COLUMN suppression_reason TEXT`, desc: 'notification_deliveries.suppression_reason' },
+    { kind: 'column', sql: `ALTER TABLE notification_deliveries ADD COLUMN group_key TEXT`, desc: 'notification_deliveries.group_key' },
+    { kind: 'exec', sql: `CREATE INDEX IF NOT EXISTS idx_notification_deliveries_group ON notification_deliveries(group_key, status)` },
+    { kind: 'exec', sql: `CREATE INDEX IF NOT EXISTS idx_notification_deliveries_throttle ON notification_deliveries(channel_id, ${sourceIdColumn}, event_type, created_at)` },
+  ]
+}
+
+/**
+ * The notification tables and their migrations, for the application's list of database modules. The unique index on
+ * the channel \`key\` and the column that backs it are created by the application, once existing rows were given a key.
+ */
+export function createNotifyDbModule(options: NotifyTableOptions) {
+  return { id: 'notify', tables: defineNotifyTables(options), migrations: notifyMigrations(options) } satisfies DbModule
+}

package/src/notice.ts

@@ -0,0 +1,68 @@
+/** How serious an event is; the rich channels paint it in a colour family and the push channels map it to a priority. */
+export type NoticeSeverity = 'critical' | 'warning' | 'ok'
+
+/**
+ * A piece of a headline. Plain text stays as written; a `subject` (what the event is about) and a `state` (what became
+ * of it) are the parts a channel emphasises in its own markup. A `kind` names what sort of thing the subject is
+ * ("Server"), which a channel may leave out where its title is already crowded.
+ */
+export type NoticeSegment = string | { kind: string } | { subject: string } | { state: string }
+
+export interface NoticeFact {
+  label: string
+  value: string
+  /** The label for channels that have room for a longer one. */
+  fullLabel?: string
+}
+
+/**
+ * What the channels say about one event, independent of the application that raised it. The application builds it
+ * from its own variables; every channel turns it into its own payload.
+ */
+export interface Notice {
+  severity: NoticeSeverity
+  headline: NoticeSegment[]
+  /** The line under the headline in channels that have one. */
+  subtitle: NoticeSegment[]
+  facts: NoticeFact[]
+  /** The error or details of the event, shown after the facts. */
+  detail?: { label: string; value: string }
+  /** When the event happened, as an ISO instant (anything else is shown as is). */
+  at: string
+  /** Names `at` in the footer ("Checked at"). */
+  atLabel: string
+}
+
+/** How a channel writes the emphasised segments of a headline. */
+export interface SegmentMarkup {
+  /** Applied to every text segment, emphasised or not. */
+  text?: (value: string) => string
+  /** Defaults to writing the kind as plain text. */
+  kind?: (value: string) => string
+  subject: (value: string) => string
+  state: (value: string) => string
+}
+
+export function renderSegments(segments: NoticeSegment[], markup: SegmentMarkup): string {
+  const text = markup.text ?? ((value: string) => value)
+  return segments.map((segment) => {
+    if (typeof segment === 'string') return text(segment)
+    if ('kind' in segment) return markup.kind ? markup.kind(text(segment.kind)) : text(segment.kind)
+    if ('subject' in segment) return markup.subject(text(segment.subject))
+    return markup.state(text(segment.state))
+  }).join('')
+}
+
+const plainMarkup: SegmentMarkup = { subject: (value) => value, state: (value) => value }
+
+/** A headline without any markup. */
+export function plainSegments(segments: NoticeSegment[]): string {
+  return renderSegments(segments, plainMarkup)
+}
+
+/** "2026-10-09T17:00:22.988Z" → "2026-10-09 17:00:22 UTC"; anything that is not an ISO instant is shown as is. */
+export function readableTimestamp(iso: string | undefined): string {
+  if (!iso) return 'unknown'
+  const match = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2})(?:\.\d+)?Z$/.exec(iso)
+  return match ? `${match[1]} ${match[2]} UTC` : iso
+}