@better-forge/notify 0.1.0 → 0.1.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 BetterStatusPage contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 BetterStatusPage contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,11 +1,11 @@
-# @better-forge/notify
-
-Notification channels, delivery history, retries and alert hygiene.
-
-- `createNotifyEngine` records every notification, applies a channel's quiet hours, rate cap and digest window, sends with retries and sends SMTP mail. The application injects the sender, the digest wording, the names of the events hygiene treats specially and the secret resolver.
-- `createTransports` holds the senders for email, webhook, Discord, Teams, Slack, Telegram, ntfy and Pushover. The rich channels format a neutral `Notice` (severity, headline segments, facts, detail, time) that the application builds from its own event.
-- `createNotifyRoutes` makes the admin routes: delivery history and retry, channel management with secret masking, and SMTP settings. The application injects audit, identity, secret masking, the vault-use guard, the names its API uses for what a notification is about, and the test sends.
-- `createDeliveryWorker` sends the deliveries that came due every 30 seconds and purges old history daily, and runs the extra tasks the application adds to those ticks.
-- `defineNotifyTables` / `createNotifyDbModule` define the tables and their migrations; the application passes the names of the columns that identify what a delivery is about.
-
-Depends on: `@better-forge/db`, `@better-forge/contracts`, `@better-forge/vault`, `@better-forge/audit`.
+# @better-forge/notify
+
+Notification channels, delivery history, retries and alert hygiene.
+
+- `createNotifyEngine` records every notification, applies a channel's quiet hours, rate cap and digest window, sends with retries and sends SMTP mail. The application injects the sender, the digest wording, the names of the events hygiene treats specially and the secret resolver.
+- `createTransports` holds the senders for email, webhook, Discord, Teams, Slack, Telegram, ntfy and Pushover. The rich channels format a neutral `Notice` (severity, headline segments, facts, detail, time) that the application builds from its own event.
+- `createNotifyRoutes` makes the admin routes: delivery history and retry, channel management with secret masking, and SMTP settings. The application injects audit, identity, secret masking, the vault-use guard, the names its API uses for what a notification is about, and the test sends.
+- `createDeliveryWorker` sends the deliveries that came due every 30 seconds and purges old history daily, and runs the extra tasks the application adds to those ticks.
+- `defineNotifyTables` / `createNotifyDbModule` define the tables and their migrations; the application passes the names of the columns that identify what a delivery is about.
+
+Depends on: `@better-forge/db`, `@better-forge/contracts`, `@better-forge/vault`, `@better-forge/audit`.

package/dist/migrations.js

@@ -3,68 +3,68 @@ import { defineNotifyTables } from './tables.js';
 export function notifyMigrations(options) {
     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_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_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 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: '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' },

package/package.json

@@ -1,59 +1,59 @@
-{
-  "name": "@better-forge/notify",
-  "version": "0.1.0",
-  "description": "Notification channels, delivery history, retries and alert hygiene.",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/BElluu/Better-Forge.git",
-    "directory": "packages/notify"
-  },
-  "homepage": "https://github.com/BElluu/Better-Forge/tree/main/packages/notify#readme",
-  "bugs": {
-    "url": "https://github.com/BElluu/Better-Forge/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "dist",
-    "src",
-    "!src/**/*.test.*"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput"
-  },
-  "dependencies": {
-    "nodemailer": "^10.0.13",
-    "node-cron": "^4.6.0",
-    "@better-forge/audit": "0.1.0",
-    "@better-forge/contracts": "0.1.0",
-    "@better-forge/db": "0.1.0",
-    "@better-forge/vault": "0.1.0"
-  },
-  "peerDependencies": {
-    "drizzle-orm": "^0.45.2",
-    "fastify": "^5.3.2"
-  },
-  "devDependencies": {
-    "drizzle-orm": "^0.45.2",
-    "fastify": "^5.3.2",
-    "@types/node": "^26.6.2",
-    "@types/nodemailer": "^8.0.1",
-    "typescript": "^5.7.3"
-  },
-  "engines": {
-    "node": ">=26.10.0"
-  }
-}
+{
+  "name": "@better-forge/notify",
+  "version": "0.1.1",
+  "description": "Notification channels, delivery history, retries and alert hygiene.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BElluu/Better-Forge.git",
+    "directory": "packages/notify"
+  },
+  "homepage": "https://github.com/BElluu/Better-Forge/tree/main/packages/notify#readme",
+  "bugs": {
+    "url": "https://github.com/BElluu/Better-Forge/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.*"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput"
+  },
+  "dependencies": {
+    "nodemailer": "^10.0.13",
+    "node-cron": "^4.6.0",
+    "@better-forge/audit": "0.1.1",
+    "@better-forge/contracts": "0.1.1",
+    "@better-forge/db": "0.1.1",
+    "@better-forge/vault": "0.1.1"
+  },
+  "peerDependencies": {
+    "drizzle-orm": "^0.45.2",
+    "fastify": "^5.3.2"
+  },
+  "devDependencies": {
+    "drizzle-orm": "^0.45.2",
+    "fastify": "^5.3.2",
+    "@types/node": "^26.6.2",
+    "@types/nodemailer": "^8.0.1",
+    "typescript": "^5.7.3"
+  },
+  "engines": {
+    "node": ">=26.10.0"
+  }
+}

package/src/alertPolicy.ts

@@ -1,149 +1,149 @@
-import type { QuietHoursPolicy } from '@better-forge/contracts'
-
-const MINUTE_MS = 60_000
-const DAY_MINUTES = 24 * 60
-const TIME_PATTERN = /^([01]\d|2[0-3]):([0-5]\d)$/
-
-const formatters = new Map<string, Intl.DateTimeFormat>()
-
-export function isValidTimezone(timezone: string): boolean {
-  try {
-    new Intl.DateTimeFormat('en-GB', { timeZone: timezone })
-    return true
-  } catch {
-    return false
-  }
-}
-
-function formatter(timezone: string): Intl.DateTimeFormat {
-  let cached = formatters.get(timezone)
-  if (!cached) {
-    cached = new Intl.DateTimeFormat('en-GB', { timeZone: timezone, hour: '2-digit', minute: '2-digit', hourCycle: 'h23' })
-    formatters.set(timezone, cached)
-  }
-  return cached
-}
-
-/** Minutes elapsed since local midnight in `timezone` at the given instant. */
-export function localMinutes(at: number, timezone: string): number {
-  const parts = formatter(isValidTimezone(timezone) ? timezone : 'UTC').formatToParts(new Date(at))
-  const hour = Number(parts.find((part) => part.type === 'hour')?.value ?? '0')
-  const minute = Number(parts.find((part) => part.type === 'minute')?.value ?? '0')
-  return hour * 60 + minute
-}
-
-function timeToMinutes(value: string): number {
-  const match = TIME_PATTERN.exec(value)
-  if (!match) return 0
-  return Number(match[1]) * 60 + Number(match[2])
-}
-
-/** True when `at` falls inside the channel's quiet window. Windows where end <= start wrap midnight. */
-export function isWithinQuietHours(policy: QuietHoursPolicy, at: number): boolean {
-  if (!policy.enabled) return false
-  const start = timeToMinutes(policy.start)
-  const end = timeToMinutes(policy.end)
-  if (start === end) return false // zero-length window — nothing is ever quiet
-  const now = localMinutes(at, policy.timezone)
-  return start < end ? now >= start && now < end : now >= start || now < end
-}
-
-/** The instant the current quiet window ends. Only meaningful while `isWithinQuietHours` holds. */
-export function quietHoursEndAt(policy: QuietHoursPolicy, at: number): number {
-  const end = timeToMinutes(policy.end)
-  const now = localMinutes(at, policy.timezone)
-  const minutesAhead = (end - now + DAY_MINUTES) % DAY_MINUTES || DAY_MINUTES
-  let candidate = at - (at % MINUTE_MS) + minutesAhead * MINUTE_MS
-  // A DST shift inside the window moves the wall clock under us; nudge forward until it is over.
-  for (let guard = 0; guard < 8 && isWithinQuietHours(policy, candidate); guard++) candidate += 30 * MINUTE_MS
-  return candidate
-}
-
-function asRecord(value: unknown): Record<string, unknown> {
-  return value && typeof value === 'object' ? value as Record<string, unknown> : {}
-}
-
-function asBool(value: unknown, fallback: boolean): boolean {
-  if (typeof value === 'boolean') return value
-  if (value === 1 || value === 0) return value === 1
-  return fallback
-}
-
-function asInt(value: unknown, min: number, max: number, fallback: number): number {
-  const parsed = typeof value === 'number' ? value : Number(value)
-  if (!Number.isFinite(parsed)) return fallback
-  return Math.min(max, Math.max(min, Math.round(parsed)))
-}
-
-function asTime(value: unknown, fallback: string): string {
-  return typeof value === 'string' && TIME_PATTERN.test(value) ? value : fallback
-}
-
-export interface ThrottlePolicy { enabled: boolean; maxAlerts: number; windowMinutes: number }
-export interface GroupingPolicy { enabled: boolean; minSources: number; windowSeconds: number }
-export interface AlertPolicy { quietHours: QuietHoursPolicy; throttle: ThrottlePolicy; grouping: GroupingPolicy }
-
-export const DEFAULT_ALERT_POLICY: AlertPolicy = {
-  quietHours: { enabled: false, start: '22:00', end: '07:00', timezone: 'UTC', mode: 'defer' },
-  throttle: { enabled: false, maxAlerts: 3, windowMinutes: 60 },
-  grouping: { enabled: false, minSources: 3, windowSeconds: 60 },
-}
-
-/**
- * Alert policy parsing for an application that stores and sends the "at least this many sources" setting of the
- * grouping under `minSourcesKey`. The package works on `minSources`; `toWire` gives the stored form back, with the
- * keys in the order they have always been written in.
- */
-export function createAlertPolicy(options: { minSourcesKey: string }) {
-  /** Coerces untrusted input (API body or stored JSON) into a complete, in-range policy. */
-  function normalizeAlertPolicy(input: unknown): AlertPolicy {
-    const raw = asRecord(input)
-    const quiet = asRecord(raw['quietHours'])
-    const throttle = asRecord(raw['throttle'])
-    const grouping = asRecord(raw['grouping'])
-    const timezone = typeof quiet['timezone'] === 'string' && isValidTimezone(quiet['timezone'])
-      ? quiet['timezone']
-      : DEFAULT_ALERT_POLICY.quietHours.timezone
-
-    return {
-      quietHours: {
-        enabled: asBool(quiet['enabled'], DEFAULT_ALERT_POLICY.quietHours.enabled),
-        start: asTime(quiet['start'], DEFAULT_ALERT_POLICY.quietHours.start),
-        end: asTime(quiet['end'], DEFAULT_ALERT_POLICY.quietHours.end),
-        timezone,
-        mode: quiet['mode'] === 'suppress' ? 'suppress' : 'defer',
-      },
-      throttle: {
-        enabled: asBool(throttle['enabled'], DEFAULT_ALERT_POLICY.throttle.enabled),
-        maxAlerts: asInt(throttle['maxAlerts'], 1, 100, DEFAULT_ALERT_POLICY.throttle.maxAlerts),
-        windowMinutes: asInt(throttle['windowMinutes'], 1, 1440, DEFAULT_ALERT_POLICY.throttle.windowMinutes),
-      },
-      grouping: {
-        enabled: asBool(grouping['enabled'], DEFAULT_ALERT_POLICY.grouping.enabled),
-        minSources: asInt(grouping[options.minSourcesKey], 2, 100, DEFAULT_ALERT_POLICY.grouping.minSources),
-        windowSeconds: asInt(grouping['windowSeconds'], 10, 900, DEFAULT_ALERT_POLICY.grouping.windowSeconds),
-      },
-    }
-  }
-
-  /** Reads a channel's stored `alert_policy` column, falling back to defaults on anything unusable. */
-  function parseAlertPolicy(stored: string | null | undefined): AlertPolicy {
-    if (!stored) return normalizeAlertPolicy({})
-    try {
-      return normalizeAlertPolicy(JSON.parse(stored))
-    } catch {
-      return normalizeAlertPolicy({})
-    }
-  }
-
-  /** The form that is stored and sent: `minSources` under the application's key, the other keys in their usual order. */
-  function toWire(policy: AlertPolicy): { quietHours: QuietHoursPolicy; throttle: ThrottlePolicy; grouping: Record<string, unknown> } {
-    return {
-      quietHours: policy.quietHours,
-      throttle: policy.throttle,
-      grouping: { enabled: policy.grouping.enabled, [options.minSourcesKey]: policy.grouping.minSources, windowSeconds: policy.grouping.windowSeconds },
-    }
-  }
-
-  return { normalizeAlertPolicy, parseAlertPolicy, toWire }
-}
+import type { QuietHoursPolicy } from '@better-forge/contracts'
+
+const MINUTE_MS = 60_000
+const DAY_MINUTES = 24 * 60
+const TIME_PATTERN = /^([01]\d|2[0-3]):([0-5]\d)$/
+
+const formatters = new Map<string, Intl.DateTimeFormat>()
+
+export function isValidTimezone(timezone: string): boolean {
+  try {
+    new Intl.DateTimeFormat('en-GB', { timeZone: timezone })
+    return true
+  } catch {
+    return false
+  }
+}
+
+function formatter(timezone: string): Intl.DateTimeFormat {
+  let cached = formatters.get(timezone)
+  if (!cached) {
+    cached = new Intl.DateTimeFormat('en-GB', { timeZone: timezone, hour: '2-digit', minute: '2-digit', hourCycle: 'h23' })
+    formatters.set(timezone, cached)
+  }
+  return cached
+}
+
+/** Minutes elapsed since local midnight in `timezone` at the given instant. */
+export function localMinutes(at: number, timezone: string): number {
+  const parts = formatter(isValidTimezone(timezone) ? timezone : 'UTC').formatToParts(new Date(at))
+  const hour = Number(parts.find((part) => part.type === 'hour')?.value ?? '0')
+  const minute = Number(parts.find((part) => part.type === 'minute')?.value ?? '0')
+  return hour * 60 + minute
+}
+
+function timeToMinutes(value: string): number {
+  const match = TIME_PATTERN.exec(value)
+  if (!match) return 0
+  return Number(match[1]) * 60 + Number(match[2])
+}
+
+/** True when `at` falls inside the channel's quiet window. Windows where end <= start wrap midnight. */
+export function isWithinQuietHours(policy: QuietHoursPolicy, at: number): boolean {
+  if (!policy.enabled) return false
+  const start = timeToMinutes(policy.start)
+  const end = timeToMinutes(policy.end)
+  if (start === end) return false // zero-length window — nothing is ever quiet
+  const now = localMinutes(at, policy.timezone)
+  return start < end ? now >= start && now < end : now >= start || now < end
+}
+
+/** The instant the current quiet window ends. Only meaningful while `isWithinQuietHours` holds. */
+export function quietHoursEndAt(policy: QuietHoursPolicy, at: number): number {
+  const end = timeToMinutes(policy.end)
+  const now = localMinutes(at, policy.timezone)
+  const minutesAhead = (end - now + DAY_MINUTES) % DAY_MINUTES || DAY_MINUTES
+  let candidate = at - (at % MINUTE_MS) + minutesAhead * MINUTE_MS
+  // A DST shift inside the window moves the wall clock under us; nudge forward until it is over.
+  for (let guard = 0; guard < 8 && isWithinQuietHours(policy, candidate); guard++) candidate += 30 * MINUTE_MS
+  return candidate
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' ? value as Record<string, unknown> : {}
+}
+
+function asBool(value: unknown, fallback: boolean): boolean {
+  if (typeof value === 'boolean') return value
+  if (value === 1 || value === 0) return value === 1
+  return fallback
+}
+
+function asInt(value: unknown, min: number, max: number, fallback: number): number {
+  const parsed = typeof value === 'number' ? value : Number(value)
+  if (!Number.isFinite(parsed)) return fallback
+  return Math.min(max, Math.max(min, Math.round(parsed)))
+}
+
+function asTime(value: unknown, fallback: string): string {
+  return typeof value === 'string' && TIME_PATTERN.test(value) ? value : fallback
+}
+
+export interface ThrottlePolicy { enabled: boolean; maxAlerts: number; windowMinutes: number }
+export interface GroupingPolicy { enabled: boolean; minSources: number; windowSeconds: number }
+export interface AlertPolicy { quietHours: QuietHoursPolicy; throttle: ThrottlePolicy; grouping: GroupingPolicy }
+
+export const DEFAULT_ALERT_POLICY: AlertPolicy = {
+  quietHours: { enabled: false, start: '22:00', end: '07:00', timezone: 'UTC', mode: 'defer' },
+  throttle: { enabled: false, maxAlerts: 3, windowMinutes: 60 },
+  grouping: { enabled: false, minSources: 3, windowSeconds: 60 },
+}
+
+/**
+ * Alert policy parsing for an application that stores and sends the "at least this many sources" setting of the
+ * grouping under `minSourcesKey`. The package works on `minSources`; `toWire` gives the stored form back, with the
+ * keys in the order they have always been written in.
+ */
+export function createAlertPolicy(options: { minSourcesKey: string }) {
+  /** Coerces untrusted input (API body or stored JSON) into a complete, in-range policy. */
+  function normalizeAlertPolicy(input: unknown): AlertPolicy {
+    const raw = asRecord(input)
+    const quiet = asRecord(raw['quietHours'])
+    const throttle = asRecord(raw['throttle'])
+    const grouping = asRecord(raw['grouping'])
+    const timezone = typeof quiet['timezone'] === 'string' && isValidTimezone(quiet['timezone'])
+      ? quiet['timezone']
+      : DEFAULT_ALERT_POLICY.quietHours.timezone
+
+    return {
+      quietHours: {
+        enabled: asBool(quiet['enabled'], DEFAULT_ALERT_POLICY.quietHours.enabled),
+        start: asTime(quiet['start'], DEFAULT_ALERT_POLICY.quietHours.start),
+        end: asTime(quiet['end'], DEFAULT_ALERT_POLICY.quietHours.end),
+        timezone,
+        mode: quiet['mode'] === 'suppress' ? 'suppress' : 'defer',
+      },
+      throttle: {
+        enabled: asBool(throttle['enabled'], DEFAULT_ALERT_POLICY.throttle.enabled),
+        maxAlerts: asInt(throttle['maxAlerts'], 1, 100, DEFAULT_ALERT_POLICY.throttle.maxAlerts),
+        windowMinutes: asInt(throttle['windowMinutes'], 1, 1440, DEFAULT_ALERT_POLICY.throttle.windowMinutes),
+      },
+      grouping: {
+        enabled: asBool(grouping['enabled'], DEFAULT_ALERT_POLICY.grouping.enabled),
+        minSources: asInt(grouping[options.minSourcesKey], 2, 100, DEFAULT_ALERT_POLICY.grouping.minSources),
+        windowSeconds: asInt(grouping['windowSeconds'], 10, 900, DEFAULT_ALERT_POLICY.grouping.windowSeconds),
+      },
+    }
+  }
+
+  /** Reads a channel's stored `alert_policy` column, falling back to defaults on anything unusable. */
+  function parseAlertPolicy(stored: string | null | undefined): AlertPolicy {
+    if (!stored) return normalizeAlertPolicy({})
+    try {
+      return normalizeAlertPolicy(JSON.parse(stored))
+    } catch {
+      return normalizeAlertPolicy({})
+    }
+  }
+
+  /** The form that is stored and sent: `minSources` under the application's key, the other keys in their usual order. */
+  function toWire(policy: AlertPolicy): { quietHours: QuietHoursPolicy; throttle: ThrottlePolicy; grouping: Record<string, unknown> } {
+    return {
+      quietHours: policy.quietHours,
+      throttle: policy.throttle,
+      grouping: { enabled: policy.grouping.enabled, [options.minSourcesKey]: policy.grouping.minSources, windowSeconds: policy.grouping.windowSeconds },
+    }
+  }
+
+  return { normalizeAlertPolicy, parseAlertPolicy, toWire }
+}