@better-forge/notify 0.0.0-stage → 0.1.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @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/alertPolicy.d.ts

@@ -0,0 +1,41 @@
+import type { QuietHoursPolicy } from '@better-forge/contracts';
+export declare function isValidTimezone(timezone: string): boolean;
+/** Minutes elapsed since local midnight in `timezone` at the given instant. */
+export declare function localMinutes(at: number, timezone: string): number;
+/** True when `at` falls inside the channel's quiet window. Windows where end <= start wrap midnight. */
+export declare function isWithinQuietHours(policy: QuietHoursPolicy, at: number): boolean;
+/** The instant the current quiet window ends. Only meaningful while `isWithinQuietHours` holds. */
+export declare function quietHoursEndAt(policy: QuietHoursPolicy, at: number): number;
+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 declare const DEFAULT_ALERT_POLICY: AlertPolicy;
+/**
+ * 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 declare function createAlertPolicy(options: {
+    minSourcesKey: string;
+}): {
+    normalizeAlertPolicy: (input: unknown) => AlertPolicy;
+    parseAlertPolicy: (stored: string | null | undefined) => AlertPolicy;
+    toWire: (policy: AlertPolicy) => {
+        quietHours: QuietHoursPolicy;
+        throttle: ThrottlePolicy;
+        grouping: Record<string, unknown>;
+    };
+};
+//# sourceMappingURL=alertPolicy.d.ts.map

package/dist/alertPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alertPolicy.d.ts","sourceRoot":"","sources":["../src/alertPolicy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAQ/D,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOzD;AAWD,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKjE;AAQD,wGAAwG;AACxG,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,gBAAgB,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAOhF;AAED,mGAAmG;AACnG,wBAAgB,eAAe,CAAC,MAAM,EAAE,gBAAgB,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAQ5E;AAsBD,MAAM,WAAW,cAAc;IAAG,OAAO,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE;AAC9F,MAAM,WAAW,cAAc;IAAG,OAAO,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE;AAC/F,MAAM,WAAW,WAAW;IAAG,UAAU,EAAE,gBAAgB,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAA;CAAE;AAEjH,eAAO,MAAM,oBAAoB,EAAE,WAIlC,CAAA;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE;kCAE7B,OAAO,KAAG,WAAW;+BA+BxB,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,WAAW;qBAUjD,WAAW,KAAG;QAAE,UAAU,EAAE,gBAAgB,CAAC;QAAC,QAAQ,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE;EASpI"}

package/dist/alertPolicy.js

@@ -0,0 +1,137 @@
+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();
+export function isValidTimezone(timezone) {
+    try {
+        new Intl.DateTimeFormat('en-GB', { timeZone: timezone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function formatter(timezone) {
+    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, timezone) {
+    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) {
+    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, at) {
+    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, at) {
+    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) {
+    return value && typeof value === 'object' ? value : {};
+}
+function asBool(value, fallback) {
+    if (typeof value === 'boolean')
+        return value;
+    if (value === 1 || value === 0)
+        return value === 1;
+    return fallback;
+}
+function asInt(value, min, max, fallback) {
+    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, fallback) {
+    return typeof value === 'string' && TIME_PATTERN.test(value) ? value : fallback;
+}
+export const DEFAULT_ALERT_POLICY = {
+    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) {
+    /** Coerces untrusted input (API body or stored JSON) into a complete, in-range policy. */
+    function normalizeAlertPolicy(input) {
+        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) {
+        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) {
+        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 };
+}
+//# sourceMappingURL=alertPolicy.js.map

package/dist/alertPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alertPolicy.js","sourceRoot":"","sources":["../src/alertPolicy.ts"],"names":[],"mappings":"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"}

package/dist/channelInput.d.ts

@@ -0,0 +1,34 @@
+import type { NotificationChannelType } from '@better-forge/contracts';
+export declare const CHANNEL_TYPES: readonly NotificationChannelType[];
+/** Telegram needs a chat and a token, direct or from the vault; an edited mask is not a token. */
+export declare function telegramConfigError(config: unknown): string | null;
+/** ntfy needs a topic; the server defaults to ntfy.sh and the access token is optional. */
+export declare function ntfyConfigError(config: unknown): string | null;
+/** Pushover needs a user or group key and an application token, direct or from the vault. */
+export declare function pushoverConfigError(config: unknown): string | null;
+/** The first problem with a channel's config that depends on its type, or null. */
+export declare function channelConfigError(type: string, config: unknown): string | 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 declare const TEMPLATE_KEYS: Record<NotificationChannelType, readonly string[]>;
+/** What is wrong with the `eventOverrides` of a channel's config, or null. */
+export declare function eventOverridesError(type: string, config: unknown): string | 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 declare function configForEvent(type: string, config: Record<string, unknown>, event: string | undefined, wording?: EventWording): Record<string, unknown>;
+//# sourceMappingURL=channelInput.d.ts.map

package/dist/channelInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channelInput.d.ts","sourceRoot":"","sources":["../src/channelInput.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAA;AAGtE,eAAO,MAAM,aAAa,EAAE,SAAS,uBAAuB,EAAsF,CAAA;AAuBlJ,kGAAkG;AAClG,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAIlE;AAID,2FAA2F;AAC3F,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAoB9D;AAED,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAIlE;AAED,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAW/E;AAED;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,uBAAuB,EAAE,SAAS,MAAM,EAAE,CAS5E,CAAA;AAMD,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAgBhF;AAED,iHAAiH;AACjH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAA;AAE5F,iIAAiI;AACjI,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,QAAQ,CAAC,EAAE,cAAc,CAAA;CAC1B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBxJ"}

package/dist/channelInput.js

@@ -0,0 +1,156 @@
+import { placeholderInAuthority } from './template.js';
+export const CHANNEL_TYPES = ['email', 'webhook', 'discord', 'teams', 'slack', 'telegram', 'ntfy', 'pushover'];
+function asConfig(config) {
+    return (config && typeof config === 'object' ? config : {});
+}
+const isText = (value) => 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, key, label, missing) {
+    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) {
+    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) {
+    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;
+        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) {
+    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, config) {
+    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 = {
+    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, config) {
+    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] ?? [];
+    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 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, config, event, wording) {
+    const keys = TEMPLATE_KEYS[type] ?? [];
+    const own = !wording || event === undefined || wording.ownEvents.includes(event);
+    const all = config['eventOverrides'];
+    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;
+}
+//# sourceMappingURL=channelInput.js.map

package/dist/channelInput.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channelInput.js","sourceRoot":"","sources":["../src/channelInput.ts"],"names":[],"mappings":"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"}

package/dist/channelSecrets.d.ts

@@ -0,0 +1,8 @@
+import type { SecretField } from '@better-forge/vault';
+export declare const CHANNEL_SECRETS: Readonly<Record<string, readonly SecretField[]>>;
+/**
+ * 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 declare const CHANNEL_DESTINATIONS: readonly (readonly string[])[];
+//# sourceMappingURL=channelSecrets.d.ts.map

package/dist/channelSecrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channelSecrets.d.ts","sourceRoot":"","sources":["../src/channelSecrets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAKtD,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC,CAQ5E,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAA6B,CAAA"}

package/dist/channelSecrets.js

@@ -0,0 +1,17 @@
+/** Which parts of a channel's configuration are secrets, by channel type. */
+const WEBHOOK_URL_SECRET = [{ path: ['webhookUrl'] }];
+export const CHANNEL_SECRETS = {
+    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 = [['url'], ['serverUrl']];
+//# sourceMappingURL=channelSecrets.js.map

package/dist/channelSecrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channelSecrets.js","sourceRoot":"","sources":["../src/channelSecrets.ts"],"names":[],"mappings":"AAEA,6EAA6E;AAC7E,MAAM,kBAAkB,GAA2B,CAAC,EAAE,IAAI,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAA;AAE7E,MAAM,CAAC,MAAM,eAAe,GAAqD;IAC/E,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC;IACjC,KAAK,EAAE,kBAAkB;IACzB,OAAO,EAAE,kBAAkB;IAC3B,KAAK,EAAE,kBAAkB;IACzB,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC9C,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC7C,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;CAC/C,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAmC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,CAAA"}

package/dist/engine.d.ts

@@ -0,0 +1,68 @@
+import type { VaultRef } from '@better-forge/contracts';
+import type { SqliteDatabase } from '@better-forge/db';
+import type { NotifyTables } from './tables.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>;
+}
+/**
+ * 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 declare function createNotifyEngine(options: NotifyEngineOptions): {
+    plan: (channel: ChannelRow, vars: Record<string, string>, details: DeliveryDetails) => Promise<number | null>;
+    dispatch: (channel: ChannelRow, vars: Record<string, string>, details: DeliveryDetails) => Promise<void>;
+    sendDirect: (channel: ChannelRow, vars: Record<string, string>, details: DeliveryDetails) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    attemptDelivery: (deliveryId: number, now?: number) => Promise<void>;
+    flushGroups: (now?: number) => Promise<number>;
+    processDue: (now?: number) => Promise<number>;
+    retryDelivery: (deliveryId: number) => Promise<boolean>;
+    purgeOldDeliveries: (now?: number) => Promise<void>;
+    hasOpenAlert: (sourceId: number) => Promise<boolean>;
+    isSmtpConfigured: () => Promise<boolean>;
+    sendSmtpMail: (message: SmtpMessage) => Promise<void>;
+};
+export type NotifyEngine = ReturnType<typeof createNotifyEngine>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAiC,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAEtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAG/C,MAAM,MAAM,UAAU,GAAG,YAAY,CAAC,sBAAsB,CAAC,CAAC,cAAc,CAAC,CAAA;AAC7E,MAAM,MAAM,WAAW,GAAG,YAAY,CAAC,wBAAwB,CAAC,CAAC,cAAc,CAAC,CAAA;AAEhF,yFAAyF;AACzF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,cAAc,CAAA;IAClB,MAAM,EAAE,YAAY,CAAA;IACpB,kGAAkG;IAClG,aAAa,EAAE,MAAM,CAAA;IACrB,kFAAkF;IAClF,MAAM,EAAE;QACN,sFAAsF;QACtF,KAAK,EAAE,MAAM,CAAA;QACb,gGAAgG;QAChG,QAAQ,EAAE,MAAM,CAAA;QAChB,kCAAkC;QAClC,SAAS,EAAE,MAAM,CAAA;KAClB,CAAA;IACD,6EAA6E;IAC7E,OAAO,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7E,yHAAyH;IACzH,MAAM,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,EAAE,GAAG,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;IAClG,mFAAmF;IACnF,aAAa,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAClE;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,qGAAqG;IACrG,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAiBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB;oBA4QhC,UAAU,QAAQ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,eAAe,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;wBAgBvF,UAAU,QAAQ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,WAAW,eAAe,KAAG,OAAO,CAAC,IAAI,CAAC;0BAOxG,UAAU,QACb,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,WACnB,eAAe,KACvB,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;kCA/PZ,MAAM,mBAAqB,OAAO,CAAC,IAAI,CAAC;mCAoI3C,OAAO,CAAC,MAAM,CAAC;kCAqDV,OAAO,CAAC,MAAM,CAAC;gCASnB,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;0CAYb,OAAO,CAAC,IAAI,CAAC;6BAK5B,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;4BAqD5B,OAAO,CAAC,OAAO,CAAC;4BAMd,WAAW,KAAG,OAAO,CAAC,IAAI,CAAC;EA2CjE;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAA"}