@better-forge/notify 0.0.0-stage → 0.1.0

package/dist/worker.js

@@ -0,0 +1,38 @@
+import cron from 'node-cron';
+/**
+ * Sends the deliveries that came due (retries and digests) every 30 seconds and purges old history daily. Does not
+ * wait for a pass to finish before the next one is due; the engine takes care of overlapping passes.
+ */
+export function createDeliveryWorker(options) {
+    let retryTask = null;
+    let purgeTask = null;
+    const tasks = (list) => {
+        for (const task of list)
+            task.run().catch((error) => console.error(task.failure, error));
+    };
+    function start() {
+        if (retryTask || purgeTask)
+            return;
+        retryTask = cron.schedule('*/30 * * * * *', () => {
+            tasks([
+                { failure: '[notifier] Retry worker failed:', run: () => options.engine.processDue() },
+                ...(options.retryTasks ?? []),
+            ]);
+        });
+        purgeTask = cron.schedule('0 3 * * *', () => {
+            tasks([
+                { failure: '[notifier] Delivery history purge failed:', run: () => options.engine.purgeOldDeliveries() },
+                ...(options.purgeTasks ?? []),
+            ]);
+        });
+        console.log(`${options.logPrefix ?? '[notifier]'} Retry worker started`);
+    }
+    function stop() {
+        retryTask?.destroy();
+        purgeTask?.destroy();
+        retryTask = null;
+        purgeTask = null;
+    }
+    return { start, stop };
+}
+//# sourceMappingURL=worker.js.map

package/dist/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAAA,OAAO,IAA4B,MAAM,WAAW,CAAA;AAoBpD;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAA8B;IACjE,IAAI,SAAS,GAAyB,IAAI,CAAA;IAC1C,IAAI,SAAS,GAAyB,IAAI,CAAA;IAE1C,MAAM,KAAK,GAAG,CAAC,IAA2B,EAAE,EAAE;QAC5C,KAAK,MAAM,IAAI,IAAI,IAAI;YAAE,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAA;IAC1F,CAAC,CAAA;IAED,SAAS,KAAK;QACZ,IAAI,SAAS,IAAI,SAAS;YAAE,OAAM;QAClC,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;YAC/C,KAAK,CAAC;gBACJ,EAAE,OAAO,EAAE,iCAAiC,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE;gBACtF,GAAG,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC;aAC9B,CAAC,CAAA;QACJ,CAAC,CAAC,CAAA;QACF,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;YAC1C,KAAK,CAAC;gBACJ,EAAE,OAAO,EAAE,2CAA2C,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,EAAE;gBACxG,GAAG,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC;aAC9B,CAAC,CAAA;QACJ,CAAC,CAAC,CAAA;QACF,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,SAAS,IAAI,YAAY,uBAAuB,CAAC,CAAA;IAC1E,CAAC;IAED,SAAS,IAAI;QACX,SAAS,EAAE,OAAO,EAAE,CAAA;QACpB,SAAS,EAAE,OAAO,EAAE,CAAA;QACpB,SAAS,GAAG,IAAI,CAAA;QAChB,SAAS,GAAG,IAAI,CAAA;IAClB,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;AACxB,CAAC"}

package/package.json

@@ -1,6 +1,59 @@
-{
-  "name": "@better-forge/notify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "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"
+  }
+}

package/src/alertPolicy.ts

@@ -0,0 +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 }
+}

package/src/channelInput.ts

@@ -0,0 +1,153 @@
+import type { NotificationChannelType } from '@better-forge/contracts'
+import { placeholderInAuthority } from './template.js'
+
+export const CHANNEL_TYPES: readonly NotificationChannelType[] = ['email', 'webhook', 'discord', 'teams', 'slack', 'telegram', 'ntfy', 'pushover']
+
+type TokenConfig = { vault?: { vaultId?: unknown; secretId?: unknown }; [key: string]: unknown }
+
+function asConfig(config: unknown): TokenConfig {
+  return (config && typeof config === 'object' ? config : {}) as TokenConfig
+}
+
+const isText = (value: unknown): value is string => typeof value === 'string' && value.trim() !== ''
+
+/**
+ * A credential is a vault reference or a direct token; an edited mask is not a token. A missing one is reported
+ * as `missing`, or accepted when `missing` is null (a public ntfy topic needs none).
+ */
+function credentialError(c: TokenConfig, key: string, label: string, missing: string | null): string | null {
+  if (c.vault) return Number.isInteger(c.vault.vaultId) && Number.isInteger(c.vault.secretId) && Number(c.vault.secretId) > 0 ? null : `Pick a vault secret for the ${label}`
+  const token = c[key]
+  if (token === undefined || token === null || token === '') return missing
+  if (typeof token !== 'string') return `The ${label} must be text`
+  if (!token.trim()) return missing
+  return token.includes('•') ? `Paste the full ${label} to replace the stored one` : null
+}
+
+/** Telegram needs a chat and a token, direct or from the vault; an edited mask is not a token. */
+export function telegramConfigError(config: unknown): string | null {
+  const c = asConfig(config)
+  if (!isText(c['chatId'])) return 'Telegram needs a Chat ID'
+  return credentialError(c, 'botToken', 'bot token', 'Telegram needs a Bot Token')
+}
+
+const NTFY_TOPIC = /^[A-Za-z0-9_-]{1,64}$/
+
+/** ntfy needs a topic; the server defaults to ntfy.sh and the access token is optional. */
+export function ntfyConfigError(config: unknown): string | null {
+  const c = asConfig(config)
+  if (!isText(c['topic']) || !NTFY_TOPIC.test(c['topic'].trim())) return 'ntfy needs a topic of up to 64 letters, digits, "-" or "_"'
+  const server = c['serverUrl']
+  if (server !== undefined && server !== null && server !== '') {
+    if (typeof server !== 'string') return 'Server URL must be text'
+    let url: URL
+    try {
+      url = new URL(server)
+    } catch {
+      return 'Server URL is not a valid URL'
+    }
+    if (!/^https?:$/.test(url.protocol)) return 'Server URL must start with http:// or https://'
+    // The URL is not a masked field, so it must not carry a login, and a query would end up in the middle of the publish URL.
+    if (url.username || url.password || url.search || url.hash) return 'Server URL must not contain a login, query or fragment'
+  }
+  const problem = credentialError(c, 'accessToken', 'access token', null)
+  if (problem) return problem
+  // A token goes into a header; a character that cannot be sent there makes every delivery fail.
+  return typeof c['accessToken'] === 'string' && c['accessToken'] && !c.vault && !/^[\x21-\x7e•]+$/.test(c['accessToken']) ? 'The access token contains characters that cannot be sent in a header' : null
+}
+
+/** Pushover needs a user or group key and an application token, direct or from the vault. */
+export function pushoverConfigError(config: unknown): string | null {
+  const c = asConfig(config)
+  if (!isText(c['userKey'])) return 'Pushover needs a User Key'
+  return credentialError(c, 'appToken', 'application token', 'Pushover needs an Application Token')
+}
+
+/** The first problem with a channel's config that depends on its type, or null. */
+export function channelConfigError(type: string, config: unknown): string | null {
+  const overridesProblem = eventOverridesError(type, config)
+  if (overridesProblem) return overridesProblem
+  if (type === 'telegram') return telegramConfigError(config)
+  if (type === 'ntfy') return ntfyConfigError(config)
+  if (type === 'pushover') return pushoverConfigError(config)
+  if (type === 'webhook') {
+    const url = asConfig(config)['url']
+    if (typeof url === 'string' && placeholderInAuthority(url)) return 'A placeholder cannot be part of the host of the URL'
+  }
+  return null
+}
+
+/**
+ * The fields of a channel that word a message, per type. A channel may carry its own wording for one kind of event
+ * (`eventOverrides`, keyed by the event type) made of these fields only; the destination and the credentials always
+ * come from the channel itself, so an override can never send a message somewhere else.
+ */
+export const TEMPLATE_KEYS: Record<NotificationChannelType, readonly string[]> = {
+  email: ['subject', 'body'],
+  webhook: ['body'],
+  discord: ['content'],
+  teams: ['summary'],
+  slack: ['text'],
+  telegram: ['text'],
+  ntfy: ['text'],
+  pushover: ['text'],
+}
+
+const MAX_OVERRIDE_TEXT = 10_000
+const MAX_OVERRIDE_EVENTS = 8
+const EVENT_KEY = /^[a-z_]{1,32}$/
+
+/** What is wrong with the `eventOverrides` of a channel's config, or null. */
+export function eventOverridesError(type: string, config: unknown): string | null {
+  const overrides = asConfig(config)['eventOverrides']
+  if (overrides === undefined) return null
+  if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)) return 'eventOverrides must be an object'
+  const events = Object.entries(overrides)
+  if (events.length > MAX_OVERRIDE_EVENTS) return `eventOverrides can hold at most ${MAX_OVERRIDE_EVENTS} events`
+  const allowed = TEMPLATE_KEYS[type as NotificationChannelType] ?? []
+  for (const [event, fields] of events) {
+    if (!EVENT_KEY.test(event) || event in Object.prototype || event === 'prototype') return `eventOverrides has an invalid event name "${event}"`
+    if (!fields || typeof fields !== 'object' || Array.isArray(fields)) return `eventOverrides.${event} must be an object`
+    for (const [field, value] of Object.entries(fields)) {
+      if (!allowed.includes(field)) return `eventOverrides.${event}.${field} is not a message field of a ${type} channel (${allowed.join(', ')})`
+      if (typeof value !== 'string' || value.length > MAX_OVERRIDE_TEXT) return `eventOverrides.${event}.${field} must be text of up to ${MAX_OVERRIDE_TEXT} characters`
+    }
+  }
+  return null
+}
+
+/** The wording a kind of event has when its channel has none of its own: by channel type, then message field. */
+export type DefaultWording = Record<string, Partial<Record<string, Record<string, string>>>>
+
+/** How a channel words each kind of event: its own message fields for `ownEvents`, its override or the default for any other. */
+export interface EventWording {
+  ownEvents: readonly string[]
+  defaults?: DefaultWording
+}
+
+/**
+ * The config a message of the given kind of event is sent with. The channel's own message fields word the kinds in
+ * `wording.ownEvents`. Any other kind is worded by what the channel has for it (`eventOverrides`), and by the default
+ * for the fields it has nothing for, never by the channel's own fields, which were written for something else. A field
+ * left without wording is sent in the channel's standard form. Without `wording`, every kind uses the channel's own
+ * fields and an override only replaces some of them.
+ */
+export function configForEvent(type: string, config: Record<string, unknown>, event: string | undefined, wording?: EventWording): Record<string, unknown> {
+  const keys = TEMPLATE_KEYS[type as NotificationChannelType] ?? []
+  const own = !wording || event === undefined || wording.ownEvents.includes(event)
+  const all = config['eventOverrides'] as Record<string, Record<string, unknown>> | undefined
+  const overrides = event && all && typeof all === 'object' && Object.hasOwn(all, event) ? all[event] : undefined
+  const fields = overrides && typeof overrides === 'object' ? overrides : {}
+  const defaults = own ? {} : wording.defaults?.[event!]?.[type] ?? {}
+  if (own && !overrides) return config
+
+  const merged = { ...config }
+  for (const key of keys) {
+    if (!own) delete merged[key]
+    const text = fields[key] !== undefined && fields[key] !== '' ? fields[key] : defaults[key]
+    if (typeof text === 'string' && text !== '') merged[key] = text
+  }
+  // A request without a body cannot carry one, and the form drops it too.
+  if (type === 'webhook' && /^(GET|HEAD)$/i.test(String(merged['method'] ?? 'POST'))) delete merged['body']
+  return merged
+}

package/src/channelSecrets.ts

@@ -0,0 +1,20 @@
+import type { SecretField } from '@better-forge/vault'
+
+/** Which parts of a channel's configuration are secrets, by channel type. */
+const WEBHOOK_URL_SECRET: readonly SecretField[] = [{ path: ['webhookUrl'] }]
+
+export const CHANNEL_SECRETS: Readonly<Record<string, readonly SecretField[]>> = {
+  webhook: [{ mapAt: ['headers'] }],
+  slack: WEBHOOK_URL_SECRET,
+  discord: WEBHOOK_URL_SECRET,
+  teams: WEBHOOK_URL_SECRET,
+  telegram: [{ path: ['botToken'], tail: true }],
+  ntfy: [{ path: ['accessToken'], tail: true }],
+  pushover: [{ path: ['appToken'], tail: true }],
+}
+
+/**
+ * Where a channel's secret ends up. Keeping a stored secret while this changes would let whoever edits the channel
+ * send it to a host of their choosing, so the secret must be entered again.
+ */
+export const CHANNEL_DESTINATIONS: readonly (readonly string[])[] = [['url'], ['serverUrl']]