@classytic/arc-notifications 0.8.0 → 0.10.0

package/dist/index.mjs

@@ -1,21 +1,31 @@
 import { createTtlMemo } from "@classytic/repo-core/cache";
+import { scopedValue } from "@classytic/arc/context";
+import { defineModule } from "@classytic/arc/factory";
 import { BaseChannel, NotificationService, createSimpleResolver } from "@classytic/notifications";
 import { defineResource } from "@classytic/arc";
 import { NotFoundError } from "@classytic/arc/utils";
 import { defineJob } from "@classytic/arc/integrations/jobs";
-import { scopedValue } from "@classytic/arc/context";
-import { defineModule } from "@classytic/arc/factory";
-//#region src/backfill.ts
+// src/backfill.ts
+const rowId = (row) => {
+	const r = row;
+	const id = r?.id ?? r?._id;
+	return id === void 0 || id === null ? void 0 : String(id);
+};
 function createInAppBackfill(options) {
 	const { repository, port, eventName = "notification:backfill", limit = 100, onError } = options;
 	const debounceMs = options.debounceMs ?? 2e3;
 	if (typeof repository.claimUndelivered !== "function") throw new Error("createInAppBackfill requires a repository implementing claimUndelivered() (atomic fetch-undelivered-and-mark-delivered). Add it to your feed repository, or skip backfill and let clients refetch GET /notifications/ on connect.");
 	const claimUndelivered = repository.claimUndelivered.bind(repository);
 	const pending = /* @__PURE__ */ new Map();
+	const sinces = /* @__PURE__ */ new Map();
+	const listSince = repository.listSince?.bind(repository);
 	let closed = false;
-	const run = async (userId, organizationId) => {
+	const run = async (userId, organizationId, since) => {
 		try {
-			const rows = await claimUndelivered(organizationId, userId, limit);
+			const claimed = await claimUndelivered(organizationId, userId, limit);
+			const replayed = since && listSince ? await listSince(organizationId, userId, since, limit) : [];
+			const seen = new Set(replayed.map(rowId));
+			const rows = [...replayed, ...claimed.filter((row) => !seen.has(rowId(row)))];
 			if (!rows.length || closed) return;
 			await port.push(userId, organizationId, eventName, { notifications: rows });
 		} catch (error) {
@@ -23,24 +33,31 @@ function createInAppBackfill(options) {
 		}
 	};
 	return {
-		onConnect(userId, organizationId) {
+		onConnect(userId, organizationId, connect) {
 			if (closed) return;
 			const key = `${organizationId} ${userId}`;
+			const since = connect?.since === void 0 ? void 0 : new Date(connect.since);
+			if (since && !Number.isNaN(since.getTime())) {
+				const earlier = sinces.get(key);
+				if (!earlier || since < earlier) sinces.set(key, since);
+			}
 			if (pending.has(key)) return;
 			pending.set(key, setTimeout(() => {
 				pending.delete(key);
-				run(userId, organizationId);
+				const replayFrom = sinces.get(key);
+				sinces.delete(key);
+				run(userId, organizationId, replayFrom);
 			}, debounceMs));
 		},
 		close() {
 			closed = true;
 			for (const timer of pending.values()) clearTimeout(timer);
 			pending.clear();
+			sinces.clear();
 		}
 	};
 }
-//#endregion
-//#region src/triggerOverride.ts
+// src/triggerOverride.ts
 /**
 * Notification trigger OVERRIDES — the admin-editable half of the registry.
 *
@@ -164,11 +181,36 @@ function resolveEffectiveSettings(triggerType, organizationId, rows, defaults) {
 	const title = pick("title") ?? defaults.title;
 	const message = pick("message") ?? defaults.message;
 	const priority = pick("priority") ?? defaults.priority;
+	/**
+	* Operator row, then the trigger's own default, then unrestricted — the same
+	* ladder every field above uses. It used to stop at `?? null`, discarding a
+	* code default that therefore could not be written at all.
+	*
+	* `?? null`, never `?? []` — the two must stay distinguishable all the way
+	* through. `null` means unrestricted; `[]` would mean "match nothing", and
+	* collapsing one into the other is exactly the widening this field prevents.
+	* A `null` stored by an operator is a deliberate "every source", and it wins
+	* over the code default precisely because they set it.
+	*/
+	/**
+	* PRESENCE, not `??` — the one field where a stored `null` is a decision.
+	*
+	* `pick` collapses `null` into "absent", which is right for every other
+	* setting and wrong here: `null` means "every source", and an operator who
+	* opens a filter must not have it re-narrowed by the code default on the next
+	* read. That is Rule 1 — a default is the fallback for an UNSET value, never
+	* an override of an explicit one.
+	*
+	* Scoped row wins over app-wide, same precedence as `pick`.
+	*/
+	const rowWithField = [scoped, appWide].find((r) => r && "sourceChannels" in r);
+	const sourceChannels = rowWithField ? rowWithField.sourceChannels ?? null : defaults.sourceChannels ? [...defaults.sourceChannels] : null;
 	return {
 		enabled,
 		recipients,
+		recipientEmails: pick("recipientEmails") ?? [],
 		channels,
-		sourceChannels: pick("sourceChannels") ?? null,
+		sourceChannels,
 		title,
 		message,
 		...priority ? { priority } : {}
@@ -209,8 +251,7 @@ function evaluateSourceChannel(sourceChannels, sourceChannel) {
 		reason: "source_channel_mismatch"
 	};
 }
-//#endregion
-//#region src/channelCatalog.ts
+// src/channelCatalog.ts
 /**
 * The NOTIFICATION CHANNEL CATALOG — which channels this deployment can deliver on.
 *
@@ -269,49 +310,9 @@ function createNotificationChannelCatalog(connectorChannels = []) {
 		has: (channel) => lookup.has(channel)
 	};
 }
-//#endregion
-//#region src/dbFirstResolver.ts
-/**
-* DB-first template resolver — generalized from be-prod's proven
-* `createDbFirstResolver` (shared/notifications). Templates are DRAFTABLE at
-* runtime: an active DB row for a template key wins; anything else falls back
-* to the code-defined resolver, so a bad draft can never take sends down.
-*
-* Storage-agnostic: `TemplateStore` is a one-method structural port
-* (`getByKey`) satisfied by any kit repository or hand-rolled lookup.
-*/
-function createDbFirstResolver(options) {
-	const { store, fallback, cacheTtlMs = 6e4, escape: escapeHtml = true, onError } = options;
-	/**
-	* Single-flight memo: one event's channel expansions resolve the same key in
-	* the same tick, and a `null` row (no draft) is an answer worth keeping. A
-	* store failure rejects every waiter and caches nothing.
-	*/
-	const lookup = createTtlMemo((key) => store.getByKey(key), { ttlMs: cacheTtlMs });
-	const resolver = (async (templateId, data) => {
-		let doc = null;
-		try {
-			doc = await lookup.get(templateId);
-		} catch (err) {
-			onError?.(err, templateId);
-			if (!fallback) throw err;
-			doc = null;
-		}
-		if (doc && doc.isActive !== false) return createSimpleResolver({ [templateId]: {
-			...doc.subject !== void 0 ? { subject: doc.subject } : {},
-			...doc.html !== void 0 ? { html: doc.html } : {},
-			...doc.text !== void 0 ? { text: doc.text } : {}
-		} }, { escape: escapeHtml })(templateId, data);
-		if (!fallback) throw new Error(`[arc-notifications] template "${templateId}" has no active store row and no fallback resolver is configured.`);
-		return fallback(templateId, data);
-	});
-	resolver.invalidate = (key) => {
-		lookup.invalidate(key);
-	};
-	return resolver;
-}
-//#endregion
-//#region src/inApp.ts
+// src/clock.ts
+const systemNotificationClock = { now: () => /* @__PURE__ */ new Date() };
+// src/inApp.ts
 /**
 * In-app notification content — the shared seam between a `notifyOn` trigger's
 * declarative `inApp` template and the channels that deliver it (the DB feed
@@ -381,8 +382,468 @@ function readInAppContent(data) {
 	if (typeof c.title !== "string" || typeof c.message !== "string") return null;
 	return c;
 }
-//#endregion
-//#region src/inAppChannel.ts
+// src/module.ts
+/**
+* `notificationsModule` — the blessed seam from arc domain events to
+* user-facing notifications.
+*
+* Every arc app used to re-derive the same wiring: build a
+* NotificationService, subscribe `app.events`, map event payloads to
+* recipients, thread idempotency for at-least-once transports. This module is
+* that wiring, once:
+*
+* ```ts
+* const app = await createApp({
+*   modules: [
+*     notificationsModule({
+*       channels: [new EmailChannel({ from, transport })],
+*       templates: createDbFirstResolver({ store, fallback }),
+*       notifyOn: [{
+*         event: "approval.requested",
+*         template: "approval-requested",
+*         recipient: (e) => directory.contact(e.payload.approverId),
+*         data: (e) => ({ title: e.payload.title }),
+*       }],
+*     }),
+*   ],
+* });
+* app.notifications?.send({ ... });                       // decorated service
+* const svc = getModuleExports<NotificationService>(app, "notifications");
+* ```
+*
+* Triggers are contributed through arc's `eventHandlers` module arm (2.24), so
+* arc owns subscription ordering AND teardown: it unsubscribes every handler at
+* shutdown BEFORE any module `onClose` runs, while the service and its queue
+* are still alive. A hand-rolled `afterResources` subscribe cannot promise that
+* — its own `onClose` races the modules it depends on.
+*
+* Each handler declares `boundary: true`, so arc contains failures — logged and
+* swallowed (fire-and-forget, matching arc's event gotcha), because a template
+* or channel failure must not block the transport ack and DLQ the event. And
+* `idempotencyKey` defaults from event identity because Redis Streams are
+* at-least-once: redelivery must not double-send.
+*/
+function notificationsModule(config) {
+	const { name = "notifications", service: provided, notifyOn = [], decorate = "notifications", queue, recipientResolver, channels, ...serviceConfig } = config;
+	let service;
+	return defineModule({
+		name,
+		async bootstrap(fastify) {
+			const resolvedQueue = typeof queue === "function" ? queue(fastify) : queue;
+			const resolvedChannels = typeof channels === "function" ? await channels(fastify) : channels;
+			service = provided ?? new NotificationService({
+				...serviceConfig,
+				...resolvedChannels ? { channels: resolvedChannels } : {},
+				...resolvedQueue ? { queue: resolvedQueue } : {}
+			});
+			if (!resolvedQueue && !provided && notifyOn.some((t) => t.enabled !== false)) fastify.log.warn(`[arc-notifications] module "${name}" wires notifyOn trigger(s) with NO durable queue — sends run on the in-memory queue and are lost on restart / not shared across instances. Wire \`queue: (f) => notificationsJob(...).toQueueAdapter(f.jobs)\` (with arc's jobsPlugin) for durability.`);
+			if (decorate !== false && !(decorate in fastify)) fastify.decorate(decorate, service);
+			return service;
+		},
+		eventHandlers: (fastify) => {
+			const handlers = notifyTriggerHandlers({
+				name,
+				service: () => service,
+				triggers: notifyOn,
+				...recipientResolver ? { recipientResolver } : {}
+			});
+			if (handlers.length > 0) fastify.log.debug(`[arc-notifications] ${handlers.length} trigger(s) subscribed`);
+			return handlers;
+		}
+	});
+}
+/**
+* Triggers as arc `eventHandlers` — what `notifyOn` subscribes, exported so a BRIDGE module can own
+* the triggers for one producer (`dependsOn: [producer, "notifications"]`) and vanish with it.
+* `service` is read per dispatch, so a bridge can resolve it from the notifications module's export.
+*/
+function notifyTriggerHandlers(options) {
+	const { name, service, recipientResolver } = options;
+	return options.triggers.filter((t) => t.enabled !== false).map((trigger, index) => ({
+		name: `${name}:${trigger.event}#${index}`,
+		event: trigger.event,
+		boundary: true,
+		handler: async (event) => dispatchTrigger(service(), trigger, event, recipientResolver ? { recipientResolver } : {})
+	}));
+}
+const audienceSlot = Symbol("arc-notifications.resolvedAudience");
+/** Content key for an audience — key order must not fragment the memo. */
+function audienceKey(audience) {
+	return JSON.stringify(audience, (_k, v) => v !== null && typeof v === "object" && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a < b ? -1 : 1)) : v);
+}
+/**
+* Resolve an audience ONCE per dispatch, shared by every expansion that asks.
+*
+* The resolver is a database read in every real host (members by role, then
+* users for contact); N channel expansions of one trigger hand it the same
+* audience. Keyed on CONTENT, so two triggers asking the same question share
+* too. A rejected resolution is dropped so the next expansion retries.
+* Outside a work scope nothing is shared.
+*/
+function resolveAudience(resolver, audience, event) {
+	const memo = scopedValue(audienceSlot, () => /* @__PURE__ */ new Map());
+	if (!memo) return Promise.resolve(resolver(audience, event));
+	const key = audienceKey(audience);
+	const pending = memo.get(key);
+	if (pending) return pending;
+	const created = Promise.resolve(resolver(audience, event));
+	memo.set(key, created);
+	created.catch(() => memo.delete(key));
+	return created;
+}
+/** The `organizationId` an audience names (`{ roles, organizationId, … }`), when it names one. */
+function audienceOrganization(audience) {
+	if (audience === null || typeof audience !== "object") return void 0;
+	const org = audience.organizationId;
+	return typeof org === "string" && org !== "" ? org : void 0;
+}
+/** One event → N sends. Exported for direct unit testing. */
+async function dispatchTrigger(service, trigger, event, opts) {
+	let resolved;
+	let organizationId;
+	if (trigger.recipient) resolved = await trigger.recipient(event);
+	else if (trigger.audience) {
+		const audience = await trigger.audience(event);
+		if (audience === null || audience === void 0) return;
+		organizationId = audienceOrganization(audience);
+		resolved = opts?.recipientResolver ? await resolveAudience(opts.recipientResolver, audience, event) : void 0;
+	}
+	if (!resolved) return;
+	const recipients = Array.isArray(resolved) ? resolved : [resolved];
+	if (recipients.length === 0) return;
+	const payload = event.payload;
+	const data = await trigger.data?.(event) ?? (payload !== null && typeof payload === "object" && !Array.isArray(payload) ? payload : {});
+	const sendData = trigger.inApp ? {
+		...data,
+		[INAPP_DATA_KEY]: renderInApp(trigger.inApp, data, trigger.priority)
+	} : data;
+	const baseKey = trigger.idempotencyKey ? trigger.idempotencyKey(event) : event.meta.idempotencyKey ?? `${event.type}:${event.meta.id}`;
+	for (const [index, recipient] of recipients.entries()) {
+		const idempotencyKey = baseKey === void 0 ? void 0 : recipients.length === 1 ? baseKey : `${baseKey}:${recipient.id ?? recipient.email ?? index}`;
+		const subject = trigger.subject?.(event);
+		await service.send({
+			event: event.type,
+			template: trigger.template ?? event.type,
+			recipient,
+			data: sendData,
+			...trigger.channels ? { channels: [...trigger.channels] } : {},
+			...idempotencyKey !== void 0 ? { idempotencyKey } : {},
+			...subject ? { subject } : {},
+			metadata: {
+				source: "arc-notifications",
+				eventId: event.meta.id,
+				...organizationId !== void 0 ? { organizationId } : {},
+				/**
+				* The NOTIFICATION OCCURRENCE — `baseKey` BEFORE the per-recipient suffix.
+				*
+				* Stated here because only the dispatcher knows it. A channel that has to
+				* infer "is this the same notification?" from the payload gets it wrong in
+				* both directions, and both were shipped: keying on the event TYPE
+				* suppressed every order after the first, and keying on `meta.id`
+				* (absent when a host re-publishes an enriched event) deduped nothing and
+				* sent the ops group two copies of every alert.
+				*
+				* Unique per occurrence, IDENTICAL across that occurrence's recipient
+				* fan-out — which is exactly the distinction a destination-collapsing
+				* channel needs and cannot derive for itself.
+				*/
+				...baseKey !== void 0 ? { notificationId: baseKey } : {}
+			}
+		});
+	}
+}
+// src/dateRules.ts
+const CIVIL = /^(\d{4})-(\d{2})-(\d{2})$/;
+const DAY_MS = 864e5;
+/** True for a real calendar date in `YYYY-MM-DD` form. */
+function isCivilDateString(value) {
+	if (typeof value !== "string") return false;
+	const m = CIVIL.exec(value);
+	if (!m) return false;
+	return new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]))).toISOString().slice(0, 10) === value;
+}
+function toDayNumber(value) {
+	if (!isCivilDateString(value)) throw new TypeError(`not a civil date (YYYY-MM-DD): ${value}`);
+	return Date.parse(`${value}T00:00:00Z`) / DAY_MS;
+}
+function fromDayNumber(day) {
+	return (/* @__PURE__ */ new Date(day * DAY_MS)).toISOString().slice(0, 10);
+}
+/** `date` moved by `days` (negative = earlier). */
+function addCivilDays(date, days) {
+	return fromDayNumber(toDayNumber(date) + days);
+}
+/** Whole days from `a` to `b` (`b - a`). */
+function civilDaysBetween(a, b) {
+	return toDayNumber(b) - toDayNumber(a);
+}
+function createMemoryDateRuleLedger() {
+	const claimed = /* @__PURE__ */ new Set();
+	return {
+		async claim(key) {
+			if (claimed.has(key)) return false;
+			claimed.add(key);
+			return true;
+		},
+		async release(key) {
+			claimed.delete(key);
+		},
+		keys: () => [...claimed]
+	};
+}
+/** Problems with a schedule, as messages; empty = valid. */
+function validateDateRuleSchedule(schedule) {
+	const problems = [];
+	if (!Number.isInteger(schedule.offsetDays)) problems.push("offsetDays must be a whole number of days");
+	if (schedule.repeatEveryDays !== void 0 && (!Number.isInteger(schedule.repeatEveryDays) || schedule.repeatEveryDays < 1)) problems.push("repeatEveryDays must be a whole number of days, at least 1");
+	const until = schedule.until;
+	if (until?.occurrences !== void 0 && (!Number.isInteger(until.occurrences) || until.occurrences < 1)) problems.push("until.occurrences must be at least 1");
+	if (until?.offsetDays !== void 0) {
+		if (!Number.isInteger(until.offsetDays)) problems.push("until.offsetDays must be a whole number of days");
+		else if (until.offsetDays < schedule.offsetDays) problems.push("until.offsetDays cannot be before offsetDays");
+	}
+	if (until && schedule.repeatEveryDays === void 0) problems.push("until applies only to a repeating rule");
+	return problems;
+}
+/**
+* The occurrence of `schedule` for an item dated `date` that a sweep on `today`
+* should send, or `null`. The latest occurrence on or before `today` is due when it
+* is at most `graceDays` old — so a missed sweep catches up, but a rule created
+* today does not replay years of history.
+*/
+function dueOccurrence(schedule, date, today, graceDays = 0) {
+	const first = addCivilDays(date, schedule.offsetDays);
+	const elapsed = civilDaysBetween(first, today);
+	if (elapsed < 0) return null;
+	const every = schedule.repeatEveryDays;
+	let index = every ? Math.floor(elapsed / every) : 0;
+	if (every) {
+		const max = schedule.until?.occurrences;
+		if (max !== void 0 && index > max - 1) index = max - 1;
+		const lastOffset = schedule.until?.offsetDays;
+		if (lastOffset !== void 0) {
+			const cap = Math.floor((lastOffset - schedule.offsetDays) / every);
+			if (index > cap) index = cap;
+		}
+	}
+	const on = addCivilDays(first, every ? index * every : 0);
+	return civilDaysBetween(on, today) <= graceDays ? {
+		index,
+		on
+	} : null;
+}
+/** The `[from, to]` range of item dates a sweep on `today` must ask a source for. */
+function dateRuleWindow(schedule, today, graceDays = 0) {
+	const to = addCivilDays(today, -schedule.offsetDays);
+	if (!schedule.repeatEveryDays) return {
+		from: addCivilDays(to, -graceDays),
+		to
+	};
+	const every = schedule.repeatEveryDays;
+	const spans = [];
+	if (schedule.until?.occurrences !== void 0) spans.push((schedule.until.occurrences - 1) * every);
+	if (schedule.until?.offsetDays !== void 0) spans.push(schedule.until.offsetDays - schedule.offsetDays);
+	if (spans.length === 0) return { to };
+	return {
+		from: addCivilDays(to, -(Math.min(...spans) + graceDays)),
+		to
+	};
+}
+/** Ledger key of one occurrence. */
+const dateRuleOccurrenceKey = (ruleId, itemId, on) => `daterule:${ruleId}:${itemId}:${on}`;
+async function collect(found) {
+	if (Symbol.asyncIterator in found) {
+		const out = [];
+		for await (const item of found) out.push(item);
+		return out;
+	}
+	return [...await found];
+}
+function createDateRuleEngine(options) {
+	const sources = /* @__PURE__ */ new Map();
+	for (const s of options.sources) {
+		if (sources.has(s.key)) throw new Error(`[arc-notifications] duplicate date-rule source "${s.key}"`);
+		sources.set(s.key, s);
+	}
+	const ledger = options.ledger ?? createMemoryDateRuleLedger();
+	const graceDays = options.graceDays ?? 0;
+	const validate = (rule) => {
+		const problems = validateDateRuleSchedule(rule.schedule);
+		const source = sources.get(rule.source);
+		if (!source) problems.unshift(`unknown source "${rule.source}"`);
+		else if (!source.dateFields.some((f) => f.key === rule.dateField)) problems.unshift(`source "${rule.source}" has no date field "${rule.dateField}"`);
+		return problems;
+	};
+	/** Items due for `rule` on `today`, each with its occurrence. */
+	const dueItems = async (rule, today) => {
+		const source = sources.get(rule.source);
+		if (!source) throw new Error(`unknown date-rule source "${rule.source}"`);
+		const window = dateRuleWindow(rule.schedule, today, graceDays);
+		const items = await collect(source.find({
+			dateField: rule.dateField,
+			...window.from !== void 0 ? { from: window.from } : {},
+			to: window.to,
+			...rule.organizationId !== void 0 ? { organizationId: rule.organizationId } : {}
+		}));
+		const out = [];
+		for (const item of items) {
+			if (!isCivilDateString(item.date)) continue;
+			const occurrence = dueOccurrence(rule.schedule, item.date, today, graceDays);
+			if (occurrence) out.push({
+				...item,
+				occurrence
+			});
+		}
+		return out;
+	};
+	const sweep = async (today) => {
+		if (!isCivilDateString(today)) throw new TypeError(`sweep date must be YYYY-MM-DD: ${today}`);
+		const rules = (await options.rules()).filter((r) => r.enabled !== false);
+		let due = 0;
+		let fired = 0;
+		let duplicates = 0;
+		let noRecipients = 0;
+		let failed = 0;
+		for (const rule of rules) {
+			let items;
+			try {
+				const problems = validate(rule);
+				if (problems.length > 0) throw new Error(`invalid date rule: ${problems.join("; ")}`);
+				items = await dueItems(rule, today);
+			} catch (err) {
+				failed++;
+				options.onError?.(err, { ruleId: rule.id });
+				continue;
+			}
+			for (const item of items) {
+				due++;
+				const { occurrence } = item;
+				const key = dateRuleOccurrenceKey(rule.id, item.id, occurrence.on);
+				if (!await ledger.claim(key, {
+					ruleId: rule.id,
+					itemId: item.id,
+					occurrenceOn: occurrence.on,
+					index: occurrence.index,
+					sweptOn: today
+				})) {
+					duplicates++;
+					continue;
+				}
+				try {
+					const recipients = await options.resolveAudience(rule.audience, {
+						rule,
+						item,
+						occurrence
+					});
+					if (!recipients || recipients.length === 0) {
+						noRecipients++;
+						continue;
+					}
+					const type = rule.template ?? `${rule.source}.${rule.dateField}`;
+					const data = {
+						...item.data,
+						dueOn: item.date,
+						occurrenceOn: occurrence.on,
+						occurrence: occurrence.index + 1,
+						daysFromDate: civilDaysBetween(item.date, today),
+						...options.data?.(rule, item) ?? {}
+					};
+					const event = {
+						type,
+						payload: data,
+						meta: {
+							id: key,
+							timestamp: /* @__PURE__ */ new Date(),
+							idempotencyKey: key
+						}
+					};
+					await dispatchTrigger(options.service(), {
+						event: type,
+						template: type,
+						recipient: () => recipients,
+						data: () => data,
+						...rule.channels ? { channels: rule.channels } : {},
+						...rule.inApp ? { inApp: rule.inApp } : {},
+						...rule.priority ? { priority: rule.priority } : {},
+						...item.subject ? { subject: () => item.subject } : {}
+					}, event);
+					fired++;
+				} catch (err) {
+					failed++;
+					await ledger.release(key).catch(() => void 0);
+					options.onError?.(err, {
+						ruleId: rule.id,
+						itemId: item.id
+					});
+				}
+			}
+		}
+		return {
+			date: today,
+			rules: rules.length,
+			due,
+			fired,
+			duplicates,
+			noRecipients,
+			failed
+		};
+	};
+	return {
+		sweep,
+		preview: (rule, today) => dueItems(rule, today),
+		catalog: () => [...sources.values()].map((s) => ({
+			key: s.key,
+			label: s.label ?? s.key,
+			dateFields: s.dateFields.map((f) => ({
+				key: f.key,
+				label: f.label ?? f.key
+			})),
+			variables: [...s.variables ?? []]
+		})),
+		validate
+	};
+}
+// src/dbFirstResolver.ts
+/**
+* DB-first template resolver — generalized from be-prod's proven
+* `createDbFirstResolver` (shared/notifications). Templates are DRAFTABLE at
+* runtime: an active DB row for a template key wins; anything else falls back
+* to the code-defined resolver, so a bad draft can never take sends down.
+*
+* Storage-agnostic: `TemplateStore` is a one-method structural port
+* (`getByKey`) satisfied by any kit repository or hand-rolled lookup.
+*/
+function createDbFirstResolver(options) {
+	const { store, fallback, cacheTtlMs = 6e4, escape: escapeHtml = true, onError } = options;
+	/**
+	* Single-flight memo: one event's channel expansions resolve the same key in
+	* the same tick, and a `null` row (no draft) is an answer worth keeping. A
+	* store failure rejects every waiter and caches nothing.
+	*/
+	const lookup = createTtlMemo((key) => store.getByKey(key), { ttlMs: cacheTtlMs });
+	const resolver = (async (templateId, data) => {
+		let doc = null;
+		try {
+			doc = await lookup.get(templateId);
+		} catch (err) {
+			onError?.(err, templateId);
+			if (!fallback) throw err;
+			doc = null;
+		}
+		if (doc && doc.isActive !== false) return createSimpleResolver({ [templateId]: {
+			...doc.subject !== void 0 ? { subject: doc.subject } : {},
+			...doc.html !== void 0 ? { html: doc.html } : {},
+			...doc.text !== void 0 ? { text: doc.text } : {}
+		} }, { escape: escapeHtml })(templateId, data);
+		if (!fallback) throw new Error(`[arc-notifications] template "${templateId}" has no active store row and no fallback resolver is configured.`);
+		return fallback(templateId, data);
+	});
+	resolver.invalidate = (key) => {
+		lookup.invalidate(key);
+	};
+	return resolver;
+}
+// src/inAppChannel.ts
 var InAppChannel = class extends BaseChannel {
 	repository;
 	port;
@@ -476,8 +937,7 @@ var InAppChannel = class extends BaseChannel {
 		return typeof org === "string" && org ? org : void 0;
 	}
 };
-//#endregion
-//#region src/inAppFeed.ts
+// src/inAppFeed.ts
 /**
 * `inAppFeedResource` — the user-facing notification inbox as a normal arc
 * resource. Generalized from be-prod's `notification.resource`: a per-user,
@@ -498,6 +958,7 @@ var InAppChannel = class extends BaseChannel {
 */
 function createUnreadCountCache(options = {}) {
 	const { ttlMs = 3e4, maxEntries = 1e4 } = options;
+	const clock = options.clock ?? systemNotificationClock;
 	const entries = /* @__PURE__ */ new Map();
 	const keyOf = (organizationId, userId) => `${organizationId}\u0000${userId}`;
 	return {
@@ -505,7 +966,7 @@ function createUnreadCountCache(options = {}) {
 			const key = keyOf(organizationId, userId);
 			const entry = entries.get(key);
 			if (!entry) return void 0;
-			if (entry.expiresAt <= Date.now()) {
+			if (entry.expiresAt <= clock.now().getTime()) {
 				entries.delete(key);
 				return;
 			}
@@ -518,7 +979,7 @@ function createUnreadCountCache(options = {}) {
 			}
 			entries.set(keyOf(organizationId, userId), {
 				count,
-				expiresAt: Date.now() + ttlMs
+				expiresAt: clock.now().getTime() + ttlMs
 			});
 		},
 		invalidate(organizationId, userId) {
@@ -526,12 +987,36 @@ function createUnreadCountCache(options = {}) {
 		}
 	};
 }
+/** The action-router verbs {@link InAppFeedResourceOptions.actions} mounts. */
+const FEED_ACTION_VERBS = {
+	markRead: "markRead",
+	markAllRead: "markAllRead"
+};
+/**
+* A feed page in repo-core's canonical offset envelope. Pure and exported so a host that
+* builds its own list route (or asserts the envelope in a test) converts the same way the
+* resource does. `hasNext`/`hasPrev` follow from the page arithmetic the port already did.
+*/
+function feedListResult(page) {
+	const { page: current, limit, total, totalPages } = page.pagination;
+	return {
+		method: "offset",
+		data: page.data,
+		page: current,
+		limit,
+		total,
+		pages: totalPages,
+		hasNext: current < totalPages,
+		hasPrev: current > 1
+	};
+}
 function toInt(value, fallback) {
 	const n = Number(value);
 	return Number.isInteger(n) && n > 0 ? n : fallback;
 }
 function inAppFeedResource(options) {
 	const { repository, resolveScope, permissions, name = "in-app-notification", prefix = "/notifications", maxLimit = 50, port, readSyncEventName = "notification:read", unreadCache } = options;
+	const envelope = options.listEnvelope ?? "native";
 	/** Fire-and-forget: read-sync + cache invalidation must never fail a request. */
 	const afterReadStateChange = async (scope, data) => {
 		try {
@@ -581,7 +1066,7 @@ function inAppFeedResource(options) {
 						unreadOnly: q.unreadOnly === "true",
 						...typeof q.type === "string" && q.type ? { type: q.type } : {}
 					});
-					return reply.send(result);
+					return reply.send(envelope === "offset" ? feedListResult(result) : result);
 				}
 			},
 			{
@@ -662,11 +1147,41 @@ function inAppFeedResource(options) {
 					return reply.send({ deleted: true });
 				}
 			}] : []
-		]
+		],
+		...options.actions ? { actions: {
+			[FEED_ACTION_VERBS.markRead]: {
+				permissions,
+				description: "Mark one of my notifications read",
+				target: {
+					scope: "handler",
+					reason: "feed rows are looked up by (organization, user, id) in the repository"
+				},
+				handler: async (id, _data, req) => {
+					const scope = resolveScope(req);
+					const updated = await repository.markRead(scope.organizationId, scope.userId, id);
+					if (!updated) throw new NotFoundError("Notification");
+					await afterReadStateChange(scope, { id });
+					return updated;
+				}
+			},
+			[FEED_ACTION_VERBS.markAllRead]: {
+				permissions,
+				id: false,
+				description: "Mark all my notifications read",
+				handler: async (_id, _data, req) => {
+					const scope = resolveScope(req);
+					const modifiedCount = await repository.markAllRead(scope.organizationId, scope.userId);
+					await afterReadStateChange(scope, {
+						all: true,
+						modifiedCount
+					});
+					return { modifiedCount };
+				}
+			}
+		} } : {}
 	});
 }
-//#endregion
-//#region src/jobsQueue.ts
+// src/jobsQueue.ts
 /**
 * `fastify.jobs` bridge — reuse arc's job subsystem instead of standing up a
 * second one.
@@ -778,157 +1293,7 @@ function notificationsJob(options = {}) {
 		toQueueAdapter
 	};
 }
-//#endregion
-//#region src/module.ts
-/**
-* `notificationsModule` — the blessed seam from arc domain events to
-* user-facing notifications.
-*
-* Every arc app used to re-derive the same wiring: build a
-* NotificationService, subscribe `app.events`, map event payloads to
-* recipients, thread idempotency for at-least-once transports. This module is
-* that wiring, once:
-*
-* ```ts
-* const app = await createApp({
-*   modules: [
-*     notificationsModule({
-*       channels: [new EmailChannel({ from, transport })],
-*       templates: createDbFirstResolver({ store, fallback }),
-*       notifyOn: [{
-*         event: "approval.requested",
-*         template: "approval-requested",
-*         recipient: (e) => directory.contact(e.payload.approverId),
-*         data: (e) => ({ title: e.payload.title }),
-*       }],
-*     }),
-*   ],
-* });
-* app.notifications?.send({ ... });                       // decorated service
-* const svc = getModuleExports<NotificationService>(app, "notifications");
-* ```
-*
-* Triggers are contributed through arc's `eventHandlers` module arm (2.24), so
-* arc owns subscription ordering AND teardown: it unsubscribes every handler at
-* shutdown BEFORE any module `onClose` runs, while the service and its queue
-* are still alive. A hand-rolled `afterResources` subscribe cannot promise that
-* — its own `onClose` races the modules it depends on.
-*
-* Each handler declares `boundary: true`, so arc contains failures — logged and
-* swallowed (fire-and-forget, matching arc's event gotcha), because a template
-* or channel failure must not block the transport ack and DLQ the event. And
-* `idempotencyKey` defaults from event identity because Redis Streams are
-* at-least-once: redelivery must not double-send.
-*/
-function notificationsModule(config) {
-	const { name = "notifications", service: provided, notifyOn = [], decorate = "notifications", queue, recipientResolver, channels, ...serviceConfig } = config;
-	let service;
-	return defineModule({
-		name,
-		async bootstrap(fastify) {
-			const resolvedQueue = typeof queue === "function" ? queue(fastify) : queue;
-			const resolvedChannels = typeof channels === "function" ? await channels(fastify) : channels;
-			service = provided ?? new NotificationService({
-				...serviceConfig,
-				...resolvedChannels ? { channels: resolvedChannels } : {},
-				...resolvedQueue ? { queue: resolvedQueue } : {}
-			});
-			if (!resolvedQueue && !provided && notifyOn.some((t) => t.enabled !== false)) fastify.log.warn(`[arc-notifications] module "${name}" wires notifyOn trigger(s) with NO durable queue — sends run on the in-memory queue and are lost on restart / not shared across instances. Wire \`queue: (f) => notificationsJob(...).toQueueAdapter(f.jobs)\` (with arc's jobsPlugin) for durability.`);
-			if (decorate !== false && !(decorate in fastify)) fastify.decorate(decorate, service);
-			return service;
-		},
-		eventHandlers: (fastify) => {
-			const triggers = notifyOn.filter((t) => t.enabled !== false);
-			if (triggers.length === 0) return [];
-			fastify.log.debug(`[arc-notifications] ${triggers.length} trigger(s) subscribed`);
-			return triggers.map((trigger, index) => ({
-				name: `${name}:${trigger.event}#${index}`,
-				event: trigger.event,
-				boundary: true,
-				handler: async (event) => dispatchTrigger(service, trigger, event, { ...recipientResolver ? { recipientResolver } : {} })
-			}));
-		}
-	});
-}
-const audienceSlot = Symbol("arc-notifications.resolvedAudience");
-/** Content key for an audience — key order must not fragment the memo. */
-function audienceKey(audience) {
-	return JSON.stringify(audience, (_k, v) => v !== null && typeof v === "object" && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a < b ? -1 : 1)) : v);
-}
-/**
-* Resolve an audience ONCE per dispatch, shared by every expansion that asks.
-*
-* The resolver is a database read in every real host (members by role, then
-* users for contact); N channel expansions of one trigger hand it the same
-* audience. Keyed on CONTENT, so two triggers asking the same question share
-* too. A rejected resolution is dropped so the next expansion retries.
-* Outside a work scope nothing is shared.
-*/
-function resolveAudience(resolver, audience, event) {
-	const memo = scopedValue(audienceSlot, () => /* @__PURE__ */ new Map());
-	if (!memo) return Promise.resolve(resolver(audience, event));
-	const key = audienceKey(audience);
-	const pending = memo.get(key);
-	if (pending) return pending;
-	const created = Promise.resolve(resolver(audience, event));
-	memo.set(key, created);
-	created.catch(() => memo.delete(key));
-	return created;
-}
-/** One event → N sends. Exported for direct unit testing. */
-async function dispatchTrigger(service, trigger, event, opts) {
-	let resolved;
-	if (trigger.recipient) resolved = await trigger.recipient(event);
-	else if (trigger.audience) {
-		const audience = await trigger.audience(event);
-		if (audience === null || audience === void 0) return;
-		resolved = opts?.recipientResolver ? await resolveAudience(opts.recipientResolver, audience, event) : void 0;
-	}
-	if (!resolved) return;
-	const recipients = Array.isArray(resolved) ? resolved : [resolved];
-	if (recipients.length === 0) return;
-	const payload = event.payload;
-	const data = await trigger.data?.(event) ?? (payload !== null && typeof payload === "object" && !Array.isArray(payload) ? payload : {});
-	const sendData = trigger.inApp ? {
-		...data,
-		[INAPP_DATA_KEY]: renderInApp(trigger.inApp, data, trigger.priority)
-	} : data;
-	const baseKey = trigger.idempotencyKey ? trigger.idempotencyKey(event) : event.meta.idempotencyKey ?? `${event.type}:${event.meta.id}`;
-	for (const [index, recipient] of recipients.entries()) {
-		const idempotencyKey = baseKey === void 0 ? void 0 : recipients.length === 1 ? baseKey : `${baseKey}:${recipient.id ?? recipient.email ?? index}`;
-		const subject = trigger.subject?.(event);
-		await service.send({
-			event: event.type,
-			template: trigger.template ?? event.type,
-			recipient,
-			data: sendData,
-			...trigger.channels ? { channels: [...trigger.channels] } : {},
-			...idempotencyKey !== void 0 ? { idempotencyKey } : {},
-			...subject ? { subject } : {},
-			metadata: {
-				source: "arc-notifications",
-				eventId: event.meta.id,
-				/**
-				* The NOTIFICATION OCCURRENCE — `baseKey` BEFORE the per-recipient suffix.
-				*
-				* Stated here because only the dispatcher knows it. A channel that has to
-				* infer "is this the same notification?" from the payload gets it wrong in
-				* both directions, and both were shipped: keying on the event TYPE
-				* suppressed every order after the first, and keying on `meta.id`
-				* (absent when a host re-publishes an enriched event) deduped nothing and
-				* sent the ops group two copies of every alert.
-				*
-				* Unique per occurrence, IDENTICAL across that occurrence's recipient
-				* fan-out — which is exactly the distinction a destination-collapsing
-				* channel needs and cannot derive for itself.
-				*/
-				...baseKey !== void 0 ? { notificationId: baseKey } : {}
-			}
-		});
-	}
-}
-//#endregion
-//#region src/repositoryDeliveryLog.ts
+// src/repositoryDeliveryLog.ts
 function deriveStatus(dispatch) {
 	if (dispatch.sent > 0 && dispatch.failed === 0) return "delivered";
 	if (dispatch.sent > 0 && dispatch.failed > 0) return "partial";
@@ -947,15 +1312,30 @@ function toEntry(doc) {
 		status: doc.status,
 		duration: doc.duration ?? 0,
 		...doc.metadata ? { metadata: doc.metadata } : {},
-		...doc.subject ? { subject: { ...doc.subject } } : {}
+		...doc.subject ? { subject: { ...doc.subject } } : {},
+		...doc.organizationId ? { organizationId: doc.organizationId } : {}
 	};
 }
+/** The payload's organization: its own metadata first, then the recipient's resolver stamp. */
+function organizationOf(payload) {
+	const fromPayload = payload.metadata?.organizationId;
+	if (typeof fromPayload === "string" && fromPayload !== "") return fromPayload;
+	const fromRecipient = payload.recipient.metadata?.organizationId;
+	return typeof fromRecipient === "string" && fromRecipient !== "" ? fromRecipient : null;
+}
 function createRepositoryDeliveryLog(repository, options = {}) {
 	const { defaultLimit = 100 } = options;
+	const clock = options.clock ?? systemNotificationClock;
+	const resolveRuleId = options.ruleId ?? ((payload) => {
+		const fromMetadata = payload.metadata?.ruleId;
+		return typeof fromMetadata === "string" && fromMetadata !== "" ? fromMetadata : void 0;
+	});
 	return {
 		async record(payload, dispatch) {
+			const ruleId = resolveRuleId(payload);
+			const extraFields = options.extraFields?.(payload, dispatch);
 			const doc = {
-				timestamp: /* @__PURE__ */ new Date(),
+				timestamp: clock.now(),
 				event: payload.event,
 				...payload.recipient.id ? { recipientId: payload.recipient.id } : {},
 				...payload.recipient.email ? { recipientEmail: payload.recipient.email } : {},
@@ -964,7 +1344,10 @@ function createRepositoryDeliveryLog(repository, options = {}) {
 				status: deriveStatus(dispatch),
 				duration: dispatch.duration,
 				...payload.metadata ? { metadata: payload.metadata } : {},
-				...payload.subject ? { subject: payload.subject } : {}
+				...payload.subject ? { subject: payload.subject } : {},
+				organizationId: organizationOf(payload),
+				...ruleId ? { ruleId } : {},
+				...extraFields ? { extraFields } : {}
 			};
 			await repository.create(doc);
 		},
@@ -992,6 +1375,7 @@ function createRepositoryDeliveryLog(repository, options = {}) {
 			const limit = filter.limit ?? defaultLimit;
 			const result = await repository.getAll({
 				filter: equality,
+				filters: equality,
 				limit
 			}, void 0);
 			let entries = (Array.isArray(result) ? result : result.data ?? []).map((r) => toEntry(r));
@@ -1001,14 +1385,36 @@ function createRepositoryDeliveryLog(repository, options = {}) {
 			if (channel) entries = entries.filter((e) => e.channels.includes(channel));
 			return entries.slice(0, limit);
 		},
+		async listByRule(ruleId, filter = {}) {
+			const equality = { ruleId };
+			if (filter.status) equality.status = filter.status;
+			const limit = filter.limit ?? defaultLimit;
+			const result = await repository.getAll({
+				filter: equality,
+				filters: equality,
+				sort: { timestamp: -1 },
+				limit
+			}, void 0);
+			let entries = (Array.isArray(result) ? result : result.data ?? []).map((r) => {
+				const doc = r;
+				return {
+					...toEntry(doc),
+					...doc.ruleId ? { ruleId: doc.ruleId } : {},
+					...doc.extraFields ? { extraFields: doc.extraFields } : {}
+				};
+			});
+			if (filter.after) entries = entries.filter((e) => e.timestamp >= filter.after);
+			if (filter.before) entries = entries.filter((e) => e.timestamp <= filter.before);
+			entries.sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime());
+			return entries.slice(0, limit);
+		},
 		async get(id) {
 			const doc = await repository.getById(id);
 			return doc ? toEntry(doc) : null;
 		}
 	};
 }
-//#endregion
-//#region src/sseChannel.ts
+// src/sseChannel.ts
 var SseChannel = class extends BaseChannel {
 	port;
 	eventName;
@@ -1068,8 +1474,7 @@ var SseChannel = class extends BaseChannel {
 		return typeof org === "string" && org ? org : void 0;
 	}
 };
-//#endregion
-//#region src/templatesResource.ts
+// src/templatesResource.ts
 /**
 * `templatesResource` — DB-draftable notification templates as a normal arc
 * resource. Generalized from be-prod's email-template resource: admins draft
@@ -1173,8 +1578,7 @@ function templatesResource(options) {
 		}]
 	});
 }
-//#endregion
-//#region src/triggerAdapter.ts
+// src/triggerAdapter.ts
 /**
 * Trigger registry → `notifyOn` config.
 *
@@ -1398,7 +1802,8 @@ function toGatedNotifyTriggers(t, options, overrides) {
 		channels: declaredChannels(t),
 		title: t.template.title,
 		message: t.template.message,
-		...t.priority ? { priority: t.priority } : {}
+		...t.priority ? { priority: t.priority } : {},
+		...t.sourceChannels ? { sourceChannels: t.sourceChannels } : {}
 	};
 	/**
 	* The effective settings resolve ONCE per event per trigger, shared by every
@@ -1473,10 +1878,20 @@ function toGatedNotifyTriggers(t, options, overrides) {
 					organizationId: ex.organizationId
 				};
 			}
-			if (eff.recipients.length === 0) return skip("no_recipients");
+			/**
+			* An operator who cleared the list means nobody — skip rather than
+			* dispatching to an empty audience the resolver would widen.
+			*
+			* Literal addresses count as an audience. Someone who wants order mail at
+			* `ops@` and nowhere else clears the roles and types the address; treating
+			* that as "no recipients" would silence exactly the configuration they
+			* just built, and report it as their own doing.
+			*/
+			if (eff.recipients.length === 0 && eff.recipientEmails.length === 0) return skip("no_recipients");
 			return {
 				roles: eff.recipients,
 				organizationId: ex.organizationId,
+				...eff.recipientEmails.length > 0 ? { recipientEmails: eff.recipientEmails } : {},
 				...ex.triggeredBy ? { excludeUserId: ex.triggeredBy } : {}
 			};
 		}
@@ -1523,5 +1938,4 @@ function getRecipientMatrix(triggers) {
 	for (const t of triggers) matrix[t.type ?? t.event] = t.recipients;
 	return matrix;
 }
-//#endregion
-export { DEFAULT_ENTITY_ID_VARS, INAPP_DATA_KEY, IN_APP_CHANNEL, InAppChannel, SseChannel, createCachedTriggerOverrideStore, createDbFirstResolver, createInAppBackfill, createNotificationChannelCatalog, createRepositoryDeliveryLog, createUnreadCountCache, dispatchTrigger, evaluateSourceChannel, getRecipientMatrix, getRegisteredEvents, getTriggerByEvent, getTriggersByEvent, inAppFeedResource, notificationsJob, notificationsModule, readInAppContent, renderInApp, resolveEffectiveSettings, templatesResource, toNotifyTrigger, toNotifyTriggers };
+export { DEFAULT_ENTITY_ID_VARS, FEED_ACTION_VERBS, INAPP_DATA_KEY, IN_APP_CHANNEL, InAppChannel, SseChannel, addCivilDays, civilDaysBetween, createCachedTriggerOverrideStore, createDateRuleEngine, createDbFirstResolver, createInAppBackfill, createMemoryDateRuleLedger, createNotificationChannelCatalog, createRepositoryDeliveryLog, createUnreadCountCache, dateRuleOccurrenceKey, dateRuleWindow, dispatchTrigger, dueOccurrence, evaluateSourceChannel, feedListResult, getRecipientMatrix, getRegisteredEvents, getTriggerByEvent, getTriggersByEvent, inAppFeedResource, isCivilDateString, notificationsJob, notificationsModule, notifyTriggerHandlers, readInAppContent, renderInApp, resolveEffectiveSettings, systemNotificationClock, templatesResource, toNotifyTrigger, toNotifyTriggers, validateDateRuleSchedule };