@classytic/arc-notifications 0.8.0 → 0.9.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { BaseChannel, ChannelConfig, DeliveryLog, DeliveryLogEntry, NotificationPayload, NotificationService, NotificationServiceConfig, QueueAdapter, Recipient, SendResult, TemplateResolver } from "@classytic/notifications";
 import { JobDefinition, JobDispatcher } from "@classytic/arc/integrations/jobs";
-import { ArcModule } from "@classytic/arc/factory";
+import { ArcModule, EventHandlerDefinition } from "@classytic/arc/factory";
 import { PermissionCheck } from "@classytic/arc/permissions";
 import { FastifyInstance, FastifyRequest } from "fastify";
 import { DomainEvent } from "@classytic/primitives/events";
@@ -339,6 +339,18 @@ interface NotificationTriggerOverrideDoc {
    * answer is a host-supplied predicate, never an expression DSL.
    */
   sourceChannels?: string[] | null;
+  /**
+   * Literal addresses to notify IN ADDITION to the role recipients.
+   *
+   * `recipients` holds ROLES, which only reaches people who hold an account.
+   * The person who wants order mail — an owner, an accountant, a shared
+   * ops@ inbox — often has no dashboard login at all, so a role list cannot
+   * express them.
+   *
+   * ADDITIVE, never a replacement: adding an address must not silence the staff
+   * feed, which is what substituting for `recipients` would do.
+   */
+  recipientEmails?: string[] | null;
   /** Copy overrides. Unset fields fall back to the code template. */
   title?: string | null;
   message?: string | null;
@@ -395,6 +407,8 @@ interface EffectiveTriggerSettings {
   channels: NotificationChannel[];
   /** `null` = unrestricted. See {@link NotificationTriggerOverrideDoc.sourceChannels}. */
   sourceChannels: string[] | null;
+  /** Extra literal addresses, ADDED to the role recipients. `[]` when none. */
+  recipientEmails: string[];
   title: string;
   message: string;
   priority?: "low" | "normal" | "high" | undefined;
@@ -405,6 +419,21 @@ interface CodeTriggerDefaults {
   title: string;
   message: string;
   priority?: "low" | "normal" | "high" | undefined;
+  /**
+   * The trigger's OWN origin restriction — `null`/absent means unrestricted.
+   *
+   * Every other field here is a code default an operator's row REPLACES. This
+   * one was the exception: the merge below hardcoded `?? null`, so a deployment
+   * could not state "a new-order alert is for web orders, not for the till" and
+   * every deployment shipped unscoped until someone hand-configured the UI.
+   *
+   * That matters most where it is least visible. A branch runs several
+   * registers, and unscoped means every counter sale fans out to every staff
+   * role on every one of them — resolved, written to the feed, and attempted on
+   * each connector, all before the response. The cashier who rang the sale is
+   * already looking at it.
+   */
+  sourceChannels?: readonly string[] | undefined;
 }
 declare function resolveEffectiveSettings(triggerType: string, organizationId: string | null, rows: readonly NotificationTriggerOverrideDoc[], defaults: CodeTriggerDefaults): EffectiveTriggerSettings;
 /**
@@ -700,6 +729,18 @@ declare module "fastify" {
   }
 }
 declare function notificationsModule(config: NotificationsModuleConfig): ArcModule<NotificationService>;
+/**
+ * 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.
+ */
+declare function notifyTriggerHandlers(options: {
+  /** Handler-name prefix; arc rejects duplicate handler names across the module graph. */
+  readonly name: string;
+  readonly service: () => NotificationService;
+  readonly triggers: readonly NotifyTrigger[];
+  readonly recipientResolver?: RecipientResolver;
+}): EventHandlerDefinition[];
 /** One event → N sends. Exported for direct unit testing. */
 declare function dispatchTrigger(service: NotificationService, trigger: NotifyTrigger, event: DomainEvent, opts?: {
   recipientResolver?: RecipientResolver;
@@ -719,6 +760,11 @@ interface DeliveryLogDoc {
   readonly status: EntryStatus;
   readonly duration: number;
   readonly metadata?: Record<string, unknown>;
+  /**
+   * The organization the delivery belongs to — top-level so a store can index it and a
+   * reader can scope on it. `null` = company-wide (no organization named).
+   */
+  readonly organizationId?: string | null;
   /**
    * The business document this delivery concerned. A STORE MUST INDEX IT —
    * this field exists precisely so "every message about invoice X" is a keyed
@@ -872,6 +918,24 @@ interface NotificationTrigger {
    * boot.
    */
   channels?: readonly NotificationChannel[];
+  /**
+   * Restrict this trigger to events ORIGINATING from these sources — the
+   * deployment's own sales channels (`web` / `pos` / `marketplace`), NOT the
+   * delivery channels above. Two adjacent fields, two vocabularies.
+   *
+   * Absent = unrestricted, which is the historical behaviour and stays the
+   * default. An operator's stored setting REPLACES this, so declaring one
+   * narrows the out-of-the-box noise without taking the choice away.
+   *
+   * State it for any staff alert whose event can originate at a till: a branch
+   * runs several registers, and unscoped means every counter sale is resolved,
+   * written to the feed and attempted on every connector — before the response —
+   * to tell staff about a sale the cashier is already looking at.
+   *
+   * Never `[]`. Empty means "match nothing", which silences the trigger while
+   * looking like a filter; `enabled: false` is how you say that.
+   */
+  sourceChannels?: readonly string[];
   /**
    * Pull dispatch variables out of the event payload.
    *
@@ -1058,4 +1122,4 @@ interface TriggerCatalogEntry {
  */
 type TriggerCatalogPort = () => ReadonlyArray<TriggerCatalogEntry> | Promise<ReadonlyArray<TriggerCatalogEntry>>;
 //#endregion
-export { type CodeTemplates, type CodeTriggerDefaults, type CreateCachedTriggerOverrideStoreOptions, type CreateUnreadCountCacheOptions, DEFAULT_ENTITY_ID_VARS, type DbFirstResolverOptions, type DbFirstTemplateResolver, type DeliveryLogDoc, type EffectiveTriggerSettings, INAPP_DATA_KEY, IN_APP_CHANNEL, type InAppBackfill, type InAppBackfillOptions, InAppChannel, type InAppChannelConfig, type InAppContent, type InAppFeedListOptions, type InAppFeedPage, type InAppFeedRepository, type InAppFeedResourceOptions, type InAppFeedRow, type InAppFeedScope, type InAppPriority, type InAppTemplate, type NotificationAudienceType, type NotificationChannel, type NotificationChannelCatalog, type NotificationDecision, type NotificationExtractResult, type NotificationRecipientContact, type NotificationSkipReason, type NotificationTrigger, type NotificationTriggerOverrideDoc, type NotificationsJob, type NotificationsJobOptions, type NotificationsModuleConfig, type NotifyTrigger, type RealtimePushPort, type RecipientResolver, type RepositoryDeliveryLogOptions, SseChannel, type SseChannelConfig, type StoredTemplate, type TemplateStore, type TemplatesResourceOptions, type TriggerAdapterOptions, type TriggerCatalogEntry, type TriggerCatalogPort, type TriggerOverrideLoader, type TriggerOverrideResolution, type TriggerOverrideStore, type UnreadCountCache, createCachedTriggerOverrideStore, createDbFirstResolver, createInAppBackfill, createNotificationChannelCatalog, createRepositoryDeliveryLog, createUnreadCountCache, dispatchTrigger, evaluateSourceChannel, getRecipientMatrix, getRegisteredEvents, getTriggerByEvent, getTriggersByEvent, inAppFeedResource, notificationsJob, notificationsModule, readInAppContent, renderInApp, resolveEffectiveSettings, templatesResource, toNotifyTrigger, toNotifyTriggers };
+export { type CodeTemplates, type CodeTriggerDefaults, type CreateCachedTriggerOverrideStoreOptions, type CreateUnreadCountCacheOptions, DEFAULT_ENTITY_ID_VARS, type DbFirstResolverOptions, type DbFirstTemplateResolver, type DeliveryLogDoc, type EffectiveTriggerSettings, INAPP_DATA_KEY, IN_APP_CHANNEL, type InAppBackfill, type InAppBackfillOptions, InAppChannel, type InAppChannelConfig, type InAppContent, type InAppFeedListOptions, type InAppFeedPage, type InAppFeedRepository, type InAppFeedResourceOptions, type InAppFeedRow, type InAppFeedScope, type InAppPriority, type InAppTemplate, type NotificationAudienceType, type NotificationChannel, type NotificationChannelCatalog, type NotificationDecision, type NotificationExtractResult, type NotificationRecipientContact, type NotificationSkipReason, type NotificationTrigger, type NotificationTriggerOverrideDoc, type NotificationsJob, type NotificationsJobOptions, type NotificationsModuleConfig, type NotifyTrigger, type RealtimePushPort, type RecipientResolver, type RepositoryDeliveryLogOptions, SseChannel, type SseChannelConfig, type StoredTemplate, type TemplateStore, type TemplatesResourceOptions, type TriggerAdapterOptions, type TriggerCatalogEntry, type TriggerCatalogPort, type TriggerOverrideLoader, type TriggerOverrideResolution, type TriggerOverrideStore, type UnreadCountCache, createCachedTriggerOverrideStore, createDbFirstResolver, createInAppBackfill, createNotificationChannelCatalog, createRepositoryDeliveryLog, createUnreadCountCache, dispatchTrigger, evaluateSourceChannel, getRecipientMatrix, getRegisteredEvents, getTriggerByEvent, getTriggersByEvent, inAppFeedResource, notificationsJob, notificationsModule, notifyTriggerHandlers, readInAppContent, renderInApp, resolveEffectiveSettings, templatesResource, toNotifyTrigger, toNotifyTriggers };

package/dist/index.mjs

@@ -164,11 +164,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 } : {}
@@ -838,18 +863,31 @@ function notificationsModule(config) {
 			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 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) {
@@ -875,13 +913,21 @@ function resolveAudience(resolver, audience, event) {
 	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;
@@ -908,6 +954,7 @@ async function dispatchTrigger(service, trigger, event, opts) {
 			metadata: {
 				source: "arc-notifications",
 				eventId: event.meta.id,
+				...organizationId !== void 0 ? { organizationId } : {},
 				/**
 				* The NOTIFICATION OCCURRENCE — `baseKey` BEFORE the per-recipient suffix.
 				*
@@ -947,9 +994,17 @@ 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;
 	return {
@@ -964,7 +1019,8 @@ 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)
 			};
 			await repository.create(doc);
 		},
@@ -1398,7 +1454,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 +1530,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 } : {}
 			};
 		}
@@ -1524,4 +1591,4 @@ function getRecipientMatrix(triggers) {
 	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, INAPP_DATA_KEY, IN_APP_CHANNEL, InAppChannel, SseChannel, createCachedTriggerOverrideStore, createDbFirstResolver, createInAppBackfill, createNotificationChannelCatalog, createRepositoryDeliveryLog, createUnreadCountCache, dispatchTrigger, evaluateSourceChannel, getRecipientMatrix, getRegisteredEvents, getTriggerByEvent, getTriggersByEvent, inAppFeedResource, notificationsJob, notificationsModule, notifyTriggerHandlers, readInAppContent, renderInApp, resolveEffectiveSettings, templatesResource, toNotifyTrigger, toNotifyTriggers };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc-notifications",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Notifications module for @classytic/arc — domain events → multi-channel notifications via @classytic/notifications, with DB-draftable templates, repo-backed delivery log, and a templates resource",
   "type": "module",
   "exports": {
@@ -29,10 +29,10 @@
     "prepublishOnly": "node ../../scripts/prepublish-gate.mjs"
   },
   "peerDependencies": {
-    "@classytic/arc": ">=2.40.0",
-    "@classytic/notifications": ">=2.5.0",
-    "@classytic/primitives": ">=0.27.0",
-    "@classytic/repo-core": ">=0.27.1"
+    "@classytic/arc": ">=2.43.0",
+    "@classytic/notifications": ">=2.6.0",
+    "@classytic/primitives": ">=0.31.0",
+    "@classytic/repo-core": ">=0.31.0"
   },
   "keywords": [
     "arc",