@classytic/arc-notifications 0.3.0 → 0.5.0

package/dist/index.mjs

@@ -2,7 +2,6 @@ import { BaseChannel, NotificationService, createSimpleResolver } from "@classyt
 import { defineResource } from "@classytic/arc";
 import { NotFoundError } from "@classytic/arc/utils";
 import { defineJob } from "@classytic/arc/integrations/jobs";
-import { subscribeWithBoundary } from "@classytic/arc/events";
 import { defineModule } from "@classytic/arc/factory";
 //#region src/backfill.ts
 function createInAppBackfill(options) {
@@ -39,6 +38,233 @@ function createInAppBackfill(options) {
 	};
 }
 //#endregion
+//#region src/triggerOverride.ts
+/**
+* Notification trigger OVERRIDES — the admin-editable half of the registry.
+*
+* ## The split, and why it is not "make triggers DB rows"
+*
+* A `NotificationTrigger` carries two very different kinds of thing:
+*
+* | stays CODE | becomes DATA |
+* |---|---|
+* | `event` — what to subscribe to | `enabled` — does this fire here at all |
+* | `extract` — a typed function: filters the event and pulls variables | `recipients` — which roles get told |
+* | | `channels` — in-app / email / whatsapp / sms |
+* | | `template` — the copy an operator wants to reword |
+*
+* `extract` is the reason the whole registry cannot become rows. It decides
+* whether a broad event is even relevant (`chargeStatus === 'failed'`) and maps
+* a payload to variables — expressing that as data means shipping an evaluator,
+* which is a code-execution surface in the notification path. Odoo draws the
+* same line: `base.automation` rows hold the trigger and the filter, while the
+* action BODY is Python in `ir.actions.server`.
+*
+* So the code registry is the CATALOG (what this deployment is capable of
+* announcing) and these rows are the CONFIGURATION (what a given scope has
+* actually turned on, to whom, over which channel).
+*
+* ## Scoped per ORGANIZATION, with an app-wide fallback
+*
+* `organizationId: null` is the app-wide default; a row with an organization id
+* overrides it for that scope only. Absence of a row means "use the code
+* default" — a fresh deployment behaves exactly as its registry declares, and
+* turning the feature on requires an operator to actually decide something.
+*
+* ## Kit-less by design
+*
+* This package carries NO database dependency (see `repositoryDeliveryLog` /
+* `templatesResource` — the same posture). This file owns the ROW SHAPE, the
+* store PORT, the TTL-cached store wrapper over a load port, and the effective-
+* settings RESOLUTION. The persistence binding (a mongoose model and its
+* indexes, in the product layer) supplies `load`.
+*/
+/**
+* A channel is a NAME, not a member of a closed set.
+*
+* ## Why this is open, and was wrong closed
+*
+* This was `["in-app", "email", "whatsapp", "sms"] as const`, so the framework
+* enumerated every channel any product could ever deliver on. Adding Telegram —
+* a provider the `@classytic/social` kernel already implements and the
+* integrations hub can already register at runtime — required editing this
+* framework package, its authoring shape, its adapter, then rebuilding and
+* re-copying it into every host. An integration that is DATA everywhere else
+* (registered provider → catalog entry → credential form → connection row) hit
+* one hardcoded array and became a code change.
+*
+* That is a policy literal in the framework layer: `arc-notifications` is the
+* generic MECHANISM (dispatch an event to channels) and has no business knowing
+* which channels a product sells. The product layer owns the catalog.
+*
+* `in-app` is the ONE exception and stays named, because the framework itself
+* implements it (`InAppChannel` writes the dashboard feed) — it is a mechanism,
+* not a connector.
+*
+* The available set now arrives as DATA: `TriggerAdapterOptions.availableChannels`,
+* which a host fills from its integrations registry. A channel nobody registered
+* is simply not offered, instead of being unrepresentable.
+*/
+const IN_APP_CHANNEL = "in-app";
+/**
+* TTL-cached {@link TriggerOverrideStore} over a load port.
+*
+* `invalidate()` exists for the write path: the admin resource calls it after
+* any mutation so an operator's change applies within one save rather than one
+* TTL window.
+*/
+function createCachedTriggerOverrideStore(load, options = {}) {
+	const ttlMs = options.ttlMs ?? 3e4;
+	const cache = /* @__PURE__ */ new Map();
+	return {
+		async forOrganization(organizationId) {
+			const key = organizationId ?? "__company__";
+			const hit = cache.get(key);
+			if (hit && Date.now() - hit.at < ttlMs) return hit.rows;
+			const rows = await load(organizationId);
+			cache.set(key, {
+				at: Date.now(),
+				rows
+			});
+			return rows;
+		},
+		/** Call after a write so an admin sees their change immediately. */
+		invalidate() {
+			cache.clear();
+		}
+	};
+}
+function resolveEffectiveSettings(triggerType, organizationId, rows, defaults) {
+	const mine = rows.filter((r) => r.triggerType === triggerType);
+	const scoped = organizationId ? mine.find((r) => r.organizationId === organizationId) : void 0;
+	const appWide = mine.find((r) => r.organizationId == null);
+	/**
+	* `??` throughout, and the field it actually protects is `enabled`.
+	*
+	* An earlier version of this comment claimed `||` would swallow an EMPTY
+	* recipients array. It would not — `[]` is truthy in JS — and a falsification
+	* proved it: swapping the operator on `recipients` changed nothing. The real
+	* hazard is `enabled: false`, where `false || true` silently re-enables a
+	* trigger an operator deliberately switched off. That one IS falsifiable, and
+	* the trigger-override test fails when the operator is swapped.
+	*
+	* Recorded rather than quietly corrected: a comment asserting a guarantee the
+	* code does not have is the same defect as a guard that cannot fail, and the
+	* next reader would have "protected" the wrong line.
+	*/
+	const pick = (key) => scoped?.[key] ?? appWide?.[key] ?? void 0;
+	const enabled = pick("enabled") ?? true;
+	const recipients = pick("recipients") ?? defaults.recipients;
+	const channels = pick("channels") ?? defaults.channels;
+	const title = pick("title") ?? defaults.title;
+	const message = pick("message") ?? defaults.message;
+	const priority = pick("priority") ?? defaults.priority;
+	return {
+		enabled,
+		recipients,
+		channels,
+		sourceChannels: pick("sourceChannels") ?? null,
+		title,
+		message,
+		...priority ? { priority } : {}
+	};
+}
+/**
+* Does this event's origin satisfy the trigger's source-channel restriction?
+*
+* Three outcomes, all named — the whole point of this function.
+*
+* ## Why `unknown` SKIPS rather than delivers
+*
+* An earlier design delivered when the event carried no `sourceChannel`, citing
+* "absence of an answer is not a negative answer". That misreads the rule: it
+* forbids treating unknown as a NEGATIVE, it does not license treating it as a
+* POSITIVE. Against a restrictive filter, delivering an event of unknown origin
+* silently violates an operator who explicitly selected `['web']` — a general
+* default overriding a specific instruction, which is the defect class this
+* codebase exists to design against.
+*
+* The cost of each mistake is not symmetric either. Deliver-on-unknown leaks
+* alerts an operator switched off and cannot see; skip-on-unknown withholds an
+* alert AND emits `source_channel_unknown`, which is visible. Prefer the failure
+* that reports itself.
+*
+* Unrestricted triggers are unaffected: `null` short-circuits before the origin
+* is ever consulted, so an event with no `sourceChannel` under no restriction
+* still delivers.
+*/
+function evaluateSourceChannel(sourceChannels, sourceChannel) {
+	if (sourceChannels == null) return { decision: "deliver" };
+	if (!sourceChannel) return {
+		decision: "skip",
+		reason: "source_channel_unknown"
+	};
+	return sourceChannels.includes(sourceChannel) ? { decision: "deliver" } : {
+		decision: "skip",
+		reason: "source_channel_mismatch"
+	};
+}
+//#endregion
+//#region src/channelCatalog.ts
+/**
+* The NOTIFICATION CHANNEL CATALOG — which channels this deployment can deliver on.
+*
+* ## Why this exists as one concept
+*
+* Three places need the same answer and each used to hardcode its own list:
+*
+* | place | old form | what it broke |
+* |---|---|---|
+* | trigger adapter | `["email","whatsapp","sms"]` | a registered provider was never offered in trigger settings |
+* | override API schema | `enum: [...NOTIFICATION_CHANNELS]` | saving an unlisted channel returned 400 |
+* | override mongoose schema | `enum: [...]` | and the write was rejected too |
+*
+* So a connector could exist in the integrations hub, appear in its catalog,
+* accept credentials — and still be impossible to enable on a notification,
+* because three separate literals disagreed with the registry. Adding one meant
+* editing a framework package, a product schema and a database enum, then
+* rebuilding and re-copying both packages into every host.
+*
+* A catalog is DATA. The deployment that registers providers is the only thing
+* that knows which exist, so it builds this once and hands it to everything that
+* asks. Adding a channel becomes: register the provider. Nothing else.
+*
+* ## What this is NOT
+*
+* Not a registry of HOW to deliver — that is the channel implementation, which
+* lives in the product layer (`@spinekit/integrations` builds hub-backed
+* channels from connected providers). This answers only "is `telegram` a thing
+* here, and what is the full set?", which is what validation and UI need.
+*
+* ## Why validation still exists
+*
+* Dropping the enums without replacing them would let a typo (`whatapp`) save
+* cleanly and then silently never deliver — the exact failure mode the closed
+* union was clumsily preventing. So the check moved to the BOUNDARY, where the
+* live catalog is known, rather than being deleted.
+*/
+/**
+* Build a catalog from the connector channel names a deployment has registered.
+*
+* `in-app` is added automatically and cannot be omitted — the framework
+* implements that channel itself (`InAppChannel` writes the dashboard feed), so
+* it is always deliverable and is not a connector a host could fail to register.
+*
+* @param connectorChannels service names from the host's integrations registry
+*   (`'email'`, `'whatsapp'`, `'telegram'`, …). Blank entries are dropped rather
+*   than stored, so a misconfigured provider cannot introduce an unusable ""
+*   channel that validation would then accept.
+*/
+function createNotificationChannelCatalog(connectorChannels = []) {
+	const names = [IN_APP_CHANNEL, ...connectorChannels.map((c) => c.trim()).filter((c) => c.length > 0)];
+	const unique = [...new Set(names)];
+	const lookup = new Set(unique);
+	return {
+		list: () => unique,
+		has: (channel) => lookup.has(channel)
+	};
+}
+//#endregion
 //#region src/dbFirstResolver.ts
 /**
 * DB-first template resolver — generalized from be-prod's proven
@@ -108,7 +334,7 @@ function createDbFirstResolver(options) {
 /** Reserved `payload.data` key carrying the rendered in-app content. */
 const INAPP_DATA_KEY = "__inApp";
 /** `{var}` interpolation — unknown keys are left as-is (visible, not silently blanked). */
-function interpolate(template, vars) {
+function interpolate$1(template, vars) {
 	return template.replace(/\{(\w+)\}/g, (_, key) => {
 		const v = vars[key];
 		return v === void 0 || v === null ? `{${key}}` : String(v);
@@ -117,11 +343,11 @@ function interpolate(template, vars) {
 /** Render a trigger's in-app template against event data + priority. */
 function renderInApp(template, vars, priority = "normal") {
 	return {
-		title: interpolate(template.title, vars),
-		message: interpolate(template.message, vars),
-		...template.link !== void 0 ? { link: interpolate(template.link, vars) } : {},
-		...template.entityType !== void 0 ? { entityType: interpolate(template.entityType, vars) } : {},
-		...template.entityId !== void 0 ? { entityId: interpolate(template.entityId, vars) } : {},
+		title: interpolate$1(template.title, vars),
+		message: interpolate$1(template.message, vars),
+		...template.link !== void 0 ? { link: interpolate$1(template.link, vars) } : {},
+		...template.entityType !== void 0 ? { entityType: interpolate$1(template.entityType, vars) } : {},
+		...template.entityId !== void 0 ? { entityId: interpolate$1(template.entityId, vars) } : {},
 		priority
 	};
 }
@@ -303,7 +529,6 @@ function inAppFeedResource(options) {
 				method: "GET",
 				path: "/",
 				permissions,
-				raw: true,
 				summary: "List my notifications (newest first, paginated)",
 				schema: { querystring: {
 					type: "object",
@@ -325,7 +550,7 @@ function inAppFeedResource(options) {
 					},
 					additionalProperties: true
 				} },
-				handler: async (req, reply) => {
+				rawHandler: async (req, reply) => {
 					const { userId, organizationId } = resolveScope(req);
 					const q = req.query ?? {};
 					const result = await repository.listForUser(organizationId, userId, {
@@ -341,9 +566,8 @@ function inAppFeedResource(options) {
 				method: "GET",
 				path: "/unread-count",
 				permissions,
-				raw: true,
 				summary: "Unread notification count (badge)",
-				handler: async (req, reply) => {
+				rawHandler: async (req, reply) => {
 					const { userId, organizationId } = resolveScope(req);
 					if (unreadCache) {
 						const cached = await unreadCache.get(organizationId, userId);
@@ -360,9 +584,8 @@ function inAppFeedResource(options) {
 				method: "PATCH",
 				path: "/:id/read",
 				permissions,
-				raw: true,
 				summary: "Mark a single notification read",
-				handler: async (req, reply) => {
+				rawHandler: async (req, reply) => {
 					const scope = resolveScope(req);
 					const id = req.params.id;
 					const updated = await repository.markRead(scope.organizationId, scope.userId, id);
@@ -375,9 +598,8 @@ function inAppFeedResource(options) {
 				method: "PATCH",
 				path: "/read-all",
 				permissions,
-				raw: true,
 				summary: "Mark all my notifications read",
-				handler: async (req, reply) => {
+				rawHandler: async (req, reply) => {
 					const scope = resolveScope(req);
 					const modifiedCount = await repository.markAllRead(scope.organizationId, scope.userId);
 					await afterReadStateChange(scope, {
@@ -387,13 +609,27 @@ function inAppFeedResource(options) {
 					return reply.send({ modifiedCount });
 				}
 			},
+			...typeof repository.deleteRead === "function" ? [{
+				method: "DELETE",
+				path: "/read",
+				permissions,
+				summary: "Delete all my already-read notifications",
+				rawHandler: async (_req, reply) => {
+					const scope = resolveScope(_req);
+					const deletedCount = await repository.deleteRead(scope.organizationId, scope.userId);
+					await afterReadStateChange(scope, {
+						deletedCount,
+						clearedRead: true
+					});
+					return reply.send({ deletedCount });
+				}
+			}] : [],
 			...typeof repository.delete === "function" ? [{
 				method: "DELETE",
 				path: "/:id",
 				permissions,
-				raw: true,
 				summary: "Delete (dismiss) a notification",
-				handler: async (req, reply) => {
+				rawHandler: async (req, reply) => {
 					const scope = resolveScope(req);
 					const id = req.params.id;
 					if (!await repository.delete(scope.organizationId, scope.userId, id)) throw new NotFoundError("Notification");
@@ -487,7 +723,7 @@ function notificationsJob(options = {}) {
 			ref.processor = processor;
 		},
 		async getJob(id) {
-			const status = await dispatcher.getStatus(id);
+			const status = await dispatcher.getStatus(name, id);
 			if (!status) return null;
 			const created = new Date(status.timestamp ?? Date.now());
 			return {
@@ -550,41 +786,45 @@ function notificationsJob(options = {}) {
 * const svc = getModuleExports<NotificationService>(app, "notifications");
 * ```
 *
-* Triggers subscribe through arc's `subscribeWithBoundary` — handler failures
-* are logged and swallowed (fire-and-forget, matching arc's event gotcha), and
+* 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, ...serviceConfig } = config;
+	const { name = "notifications", service: provided, notifyOn = [], decorate = "notifications", queue, recipientResolver, channels, ...serviceConfig } = config;
 	let service;
-	const unsubscribes = [];
 	return defineModule({
 		name,
-		bootstrap(fastify) {
+		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;
 		},
-		async afterResources(fastify) {
+		eventHandlers: (fastify) => {
 			const triggers = notifyOn.filter((t) => t.enabled !== false);
-			if (triggers.length === 0) return;
-			const bus = fastify;
-			if (!bus.events) throw new Error(`[arc-notifications] module "${name}" declares ${triggers.length} notifyOn trigger(s) but \`fastify.events\` is not decorated — register arc's eventPlugin (or drop notifyOn).`);
-			for (const trigger of triggers) {
-				const unsubscribe = await subscribeWithBoundary(bus, trigger.event, async (event) => dispatchTrigger(service, trigger, event, { ...recipientResolver ? { recipientResolver } : {} }), { name: `arc-notifications:${trigger.event}` });
-				unsubscribes.push(unsubscribe);
-			}
+			if (triggers.length === 0) return [];
 			fastify.log.debug(`[arc-notifications] ${triggers.length} trigger(s) subscribed`);
-		},
-		async onClose() {
-			for (const unsubscribe of unsubscribes) unsubscribe();
-			unsubscribes.length = 0;
+			return triggers.map((trigger, index) => ({
+				name: `${name}:${trigger.event}#${index}`,
+				event: trigger.event,
+				boundary: true,
+				handler: async (event) => dispatchTrigger(service, trigger, event, { ...recipientResolver ? { recipientResolver } : {} })
+			}));
 		}
 	});
 }
@@ -609,6 +849,7 @@ async function dispatchTrigger(service, trigger, event, opts) {
 	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,
@@ -616,9 +857,25 @@ async function dispatchTrigger(service, trigger, event, opts) {
 			data: sendData,
 			...trigger.channels ? { channels: [...trigger.channels] } : {},
 			...idempotencyKey !== void 0 ? { idempotencyKey } : {},
+			...subject ? { subject } : {},
 			metadata: {
 				source: "arc-notifications",
-				eventId: event.meta.id
+				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 } : {}
 			}
 		});
 	}
@@ -642,7 +899,8 @@ function toEntry(doc) {
 		results: doc.results ?? [],
 		status: doc.status,
 		duration: doc.duration ?? 0,
-		...doc.metadata ? { metadata: doc.metadata } : {}
+		...doc.metadata ? { metadata: doc.metadata } : {},
+		...doc.subject ? { subject: { ...doc.subject } } : {}
 	};
 }
 function createRepositoryDeliveryLog(repository, options = {}) {
@@ -658,7 +916,8 @@ function createRepositoryDeliveryLog(repository, options = {}) {
 				results: dispatch.results,
 				status: deriveStatus(dispatch),
 				duration: dispatch.duration,
-				...payload.metadata ? { metadata: payload.metadata } : {}
+				...payload.metadata ? { metadata: payload.metadata } : {},
+				...payload.subject ? { subject: payload.subject } : {}
 			};
 			await repository.create(doc);
 		},
@@ -668,6 +927,21 @@ function createRepositoryDeliveryLog(repository, options = {}) {
 			if (filter.recipientEmail) equality.recipientEmail = filter.recipientEmail;
 			if (filter.event) equality.event = filter.event;
 			if (filter.status) equality.status = filter.status;
+			/**
+			* Pushed into the EQUALITY filter, not the in-memory pass below.
+			*
+			* The post-fetch filters (`after`/`before`/`channel`) narrow a page that
+			* was already limited — acceptable for a range or an array membership.
+			* Subject is different: it is the primary way a document screen reads its
+			* own history, so filtering it in memory would fetch `limit` rows of
+			* OTHER documents' deliveries and return however few happened to match —
+			* an empty send history for an invoice that was definitely emailed.
+			* Dotted paths so the store's compound index is usable.
+			*/
+			if (filter.subject) {
+				equality["subject.sourceModel"] = filter.subject.sourceModel;
+				equality["subject.sourceId"] = filter.subject.sourceId;
+			}
 			const limit = filter.limit ?? defaultLimit;
 			const result = await repository.getAll({
 				filter: equality,
@@ -853,4 +1127,298 @@ function templatesResource(options) {
 	});
 }
 //#endregion
-export { INAPP_DATA_KEY, InAppChannel, SseChannel, createDbFirstResolver, createInAppBackfill, createRepositoryDeliveryLog, createUnreadCountCache, dispatchTrigger, inAppFeedResource, notificationsJob, notificationsModule, readInAppContent, renderInApp, templatesResource };
+//#region src/triggerAdapter.ts
+/**
+* `entityType` → the `extract` variable holding that entity's id.
+*
+* The in-app row wants an `entityId` for deep-linking and badge grouping, but
+* the variable it lives under is named per entity. This is the default
+* commerce mapping; a host with its own entity kinds passes `entityIdVars`.
+*/
+const DEFAULT_ENTITY_ID_VARS = {
+	order: "orderId",
+	transfer: "transferId",
+	product: "productId"
+};
+/**
+* Adapt one authoring trigger to one module trigger.
+*
+* Note `extract` is invoked separately by `audience` and by `data`. The module
+* calls both per dispatch, so an `extract` with side effects would run them
+* twice — keep extractors pure (every one in practice is a payload reshape).
+*/
+function toNotifyTrigger(t, options = {}) {
+	const type = t.type ?? t.event;
+	const entityIdVars = {
+		...DEFAULT_ENTITY_ID_VARS,
+		...options.entityIdVars
+	};
+	const entityVar = t.template.entityType ? entityIdVars[t.template.entityType] : void 0;
+	const channels = declaredChannels(t);
+	return {
+		event: t.event,
+		template: type,
+		...t.priority ? { priority: t.priority } : {},
+		channels,
+		/**
+		* Dedup on the SUBJECT, not on the delivery.
+		*
+		* The module's default is `meta.idempotencyKey ?? "<type>:<meta.id>"`, and
+		* `meta.id` is a fresh uuid per publish — so a redelivered or re-published
+		* event yields a DIFFERENT key and dedup can never engage. Delivery here is
+		* at-least-once by contract (be-prod's own engine docblock: "direct
+		* post-commit publish + relay … every consumer must be idempotent"), and one
+		* order genuinely produced two `customer:order.placed` publishes, so every
+		* channel fired twice. Two identical emails read as a mail-client quirk; two
+		* Telegram messages are what finally made it visible.
+		*
+		* Keyed on `<type>:<entityId>` because the notification is ABOUT that entity
+		* — "order X was placed" is one fact however many times its event is
+		* delivered. `entityVar` is the same variable the in-app row deep-links with,
+		* so this needs no per-trigger configuration and applies to every trigger
+		* that names an `entityType`.
+		*
+		* Returns `undefined` when there is no entity id, which falls back to the
+		* module default. A broadcast with no subject has nothing stable to dedupe on,
+		* and inventing a key there would collapse legitimately distinct sends.
+		*/
+		...entityVar ? { idempotencyKey: (e) => {
+			const id = t.extract(e.payload ?? {})?.variables?.[entityVar];
+			return id === void 0 || id === null || id === "" ? void 0 : `${type}:${String(id)}`;
+		} } : {},
+		audience: (e) => {
+			const ex = t.extract(e.payload ?? {});
+			if (!ex) return null;
+			if (t.audienceType === "customer") {
+				if (!ex.recipient) return null;
+				return {
+					recipient: ex.recipient,
+					organizationId: ex.organizationId
+				};
+			}
+			return {
+				roles: t.recipients,
+				organizationId: ex.organizationId,
+				...ex.triggeredBy ? { excludeUserId: ex.triggeredBy } : {}
+			};
+		},
+		data: (e) => {
+			const vars = t.extract(e.payload ?? {})?.variables ?? {};
+			return {
+				...vars,
+				...copyFor(t, vars)
+			};
+		},
+		inApp: {
+			title: t.template.title,
+			message: t.template.message,
+			...t.template.link ? { link: t.template.link } : {},
+			...t.template.entityType ? { entityType: t.template.entityType } : {},
+			...entityVar ? { entityId: `{${entityVar}}` } : {}
+		}
+	};
+}
+/**
+* `{placeholder}` interpolation over a trigger's own copy.
+*
+* The same substitution `InAppChannel` performs on `inApp.title`/`message` —
+* lifted here so EVERY channel can have the text, not just the one this package
+* implements. Unknown placeholders are left verbatim rather than blanked: a
+* literal `{orderNumber}` in a message is a visible bug someone fixes, while an
+* empty gap reads as intentional copy.
+*/
+function interpolate(template, vars) {
+	return template.replace(/\{(\w+)\}/g, (whole, key) => {
+		const v = vars[key];
+		return v === void 0 || v === null ? whole : String(v);
+	});
+}
+/**
+* The notification's rendered copy, under RESERVED keys.
+*
+* Connector channels (WhatsApp, Telegram, SMS, …) receive only `payload.data`,
+* and until now that held nothing but the trigger's extracted variables — the
+* copy lived in `inApp`, which only the in-app channel reads. Email was the sole
+* exception because a host supplies a separate template resolver for it. So every
+* other channel was structurally incapable of rendering a message, and skipped
+* with "empty body" no matter how well it was configured.
+*
+* Prefixed (`notification*`) so a trigger free to name its own variables cannot
+* collide with them — a trigger with a `title` variable would otherwise silently
+* overwrite the copy, or be overwritten by it.
+*
+* These are the CODE defaults. Per-scope copy overrides are resolved in the
+* gated variant's `audience`, which is async, while `data` is sync — so an
+* operator's custom wording reaches the in-app row and email today, and wiring it
+* through to connectors needs the kernel to allow an async `data`.
+*/
+function copyFor(t, vars) {
+	const out = {};
+	if (t.template.title) out.notificationTitle = interpolate(t.template.title, vars);
+	if (t.template.message) out.notificationMessage = interpolate(t.template.message, vars);
+	return out;
+}
+/**
+* The channel set a trigger declares in CODE — its default before any override.
+*
+* `in-app` is prepended for a staff audience because the FRAMEWORK implements
+* that channel; every other name comes from the trigger's own `channels` list,
+* so a product can deliver on anything its integrations hub has registered
+* without this package knowing the name.
+*/
+function declaredChannels(t) {
+	return [...t.audienceType === "customer" ? [] : [IN_APP_CHANNEL], ...t.channels ?? []];
+}
+/**
+* Every channel an override could ever turn ON for this trigger.
+*
+* The union of the declared set and the configurable ones, because a scope may
+* enable a channel the code never flagged — that is the point of the control
+* centre. A customer-audience trigger stays out of `in-app`: buyers are not
+* dashboard users, so a feed row for them is one nobody can read, and no
+* override should be able to create it.
+*/
+function candidateChannels(t, catalog) {
+	/**
+	* The CONFIGURABLE set comes from the CATALOG, never a literal here.
+	*
+	* It was `["email", "whatsapp", "sms"]` — the framework listing the product's
+	* connectors, which is why registering a provider in the hub could never reach
+	* an operator's trigger settings. The catalog is built by the deployment that
+	* knows what it registered, so a connector that exists is offered and one that
+	* does not is absent, with no edit in this package.
+	*
+	* Falling back to the trigger's own declaration keeps a caller that supplies
+	* no catalog working: the degradation is "no NEW channels offered", never
+	* "no channels at all".
+	*/
+	const configurable = (catalog?.list() ?? t.channels ?? []).filter((c) => c !== IN_APP_CHANNEL);
+	const unique = [...new Set(configurable)];
+	/**
+	* A customer audience never gets `in-app`: buyers are not dashboard users, so
+	* a feed row for them is one nobody can read, and no override may create it.
+	*/
+	return t.audienceType === "customer" ? unique : [IN_APP_CHANNEL, ...unique];
+}
+/**
+* One module trigger per CHANNEL, each gated on the stored settings.
+*
+* The gate lives in `audience` because that is the only per-event async seam
+* arc gives a trigger, and returning `null` there is already the module's
+* documented "skip" — the same mechanism `extract` uses to filter a broad event.
+*/
+function toGatedNotifyTriggers(t, options, overrides) {
+	const type = t.type ?? t.event;
+	const base = toNotifyTrigger(t, options);
+	const defaults = {
+		recipients: t.recipients,
+		channels: declaredChannels(t),
+		title: t.template.title,
+		message: t.template.message,
+		...t.priority ? { priority: t.priority } : {}
+	};
+	return candidateChannels(t, options.catalog).map((channel) => ({
+		...base,
+		channels: [channel],
+		audience: async (e) => {
+			const ex = t.extract(e.payload ?? {});
+			if (!ex) return null;
+			const rows = await overrides.store.forOrganization(ex.organizationId ?? null);
+			const eff = resolveEffectiveSettings(type, ex.organizationId ?? null, rows, defaults);
+			/**
+			* Report a skip so it is COUNTABLE, then skip.
+			*
+			* A bare `return null` erases why, and "suppressed because the operator
+			* scoped this to web" then looks identical to "the trigger never fired"
+			* and to "recipient resolution came back empty". That indistinguishability
+			* is how a staff-notification regression stayed invisible once already.
+			*
+			* Counters only — this package never PERSISTS a decision. A row per
+			* skipped (event x trigger x channel) would out-write real deliveries, and
+			* storage is product persistence, not framework mechanism.
+			*
+			* Fired once per CHANNEL, because that is the granularity this loop runs
+			* at: a two-channel trigger suppressed for one event reports twice. That
+			* is right for delivery accounting and over-counts for "how many events
+			* were suppressed", so the channel is included and the consumer aggregates.
+			*/
+			const skip = (reason) => {
+				options.onDecision?.({
+					triggerType: type,
+					channel,
+					reason,
+					organizationId: ex.organizationId ?? null
+				});
+				return null;
+			};
+			if (!eff.enabled) return skip("disabled");
+			/**
+			* The source-channel gate — e.g. "staff alerts for web orders only".
+			*
+			* Placed AFTER `enabled` and BEFORE the channel-membership test on
+			* purpose: `enabled: false` is the operator's broadest statement and
+			* should win, while channel membership is fan-out bookkeeping rather than
+			* a decision about this event.
+			*/
+			const originDecision = evaluateSourceChannel(eff.sourceChannels, ex.sourceChannel);
+			if (originDecision.decision === "skip") return skip(originDecision.reason);
+			if (!eff.channels.includes(channel)) return null;
+			if (t.audienceType === "customer") {
+				if (!ex.recipient) return null;
+				return {
+					recipient: ex.recipient,
+					organizationId: ex.organizationId
+				};
+			}
+			if (eff.recipients.length === 0) return skip("no_recipients");
+			return {
+				roles: eff.recipients,
+				organizationId: ex.organizationId,
+				...ex.triggeredBy ? { excludeUserId: ex.triggeredBy } : {}
+			};
+		}
+	}));
+}
+/**
+* Adapt a whole registry — what a host assigns to the module's `notifyOn`.
+*
+* With `options.overrides`, each trigger becomes one entry per channel, gated on
+* the admin's stored settings. Without it, the mapping is 1:1 and unchanged.
+*/
+function toNotifyTriggers(triggers, options = {}) {
+	const { overrides } = options;
+	if (!overrides) return triggers.map((t) => toNotifyTrigger(t, options));
+	return triggers.flatMap((t) => toGatedNotifyTriggers(t, options, overrides));
+}
+/**
+* First trigger registered for an event.
+*
+* CAVEAT: an event may carry more than one trigger (an informational alert and
+* an escalation to a different role set both listen to `stock:low`). This
+* returns only the first. For anything that must see all of them — a docs page,
+* an admin matrix, a dispatch count — use `getTriggersByEvent`.
+*/
+function getTriggerByEvent(triggers, event) {
+	return triggers.find((t) => t.event === event);
+}
+/** Every trigger registered for an event, in registration order. */
+function getTriggersByEvent(triggers, event) {
+	return triggers.filter((t) => t.event === event);
+}
+/** Distinct event names the registry subscribes to (for docs / admin UI). */
+function getRegisteredEvents(triggers) {
+	return [...new Set(triggers.map((t) => t.event))];
+}
+/**
+* Notification kind → recipient roles (for the admin UI).
+*
+* Keyed by `type ?? event`, so two triggers sharing an event stay distinct
+* rows — which is exactly why they carry different `type`s.
+*/
+function getRecipientMatrix(triggers) {
+	const matrix = {};
+	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 };