@classytic/arc-notifications 0.4.0 → 0.5.0

package/dist/index.d.mts

@@ -232,6 +232,256 @@ interface InAppBackfill {
 }
 declare function createInAppBackfill(options: InAppBackfillOptions): InAppBackfill;
 //#endregion
+//#region src/triggerOverride.d.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.
+ */
+declare const IN_APP_CHANNEL = "in-app";
+/**
+ * Open by design — see above. Kept as a named alias rather than inlining
+ * `string` so the intent reads at every call site and a future narrowing has one
+ * place to happen.
+ */
+type NotificationChannel = string;
+interface NotificationTriggerOverrideDoc {
+  /**
+   * The trigger's `type` (falling back to its `event`) — the same key
+   * `toNotifyTrigger` uses as the template id, so a row is addressable by the
+   * identifier an admin already sees in the catalog.
+   */
+  triggerType: string;
+  /** `null` = app-wide default; an organization id overrides it for that scope. */
+  organizationId?: string | null;
+  /** `false` silences the trigger entirely for this scope. */
+  enabled?: boolean;
+  /** Replaces the code trigger's roles. Empty array = nobody (use `enabled` to silence). */
+  recipients?: string[] | null;
+  /** Replaces the code trigger's channel set. */
+  channels?: NotificationChannel[] | null;
+  /**
+   * Restrict this trigger to events ORIGINATING from these sources.
+   *
+   * Deliberately generic: this package must not learn a product's vocabulary.
+   * A commerce host means "web / pos / marketplace" and labels the field "Sales
+   * channel" in its UI; another product could mean "api / import / manual". The
+   * framework only compares `NotificationExtractResult.sourceChannel` against
+   * this list.
+   *
+   * `null` / absent = **every source** — today's behaviour, so an untouched
+   * deployment is unaffected. `[]` is NOT "every source"; it is rejected at the
+   * API boundary, because an empty allow-list that reads as "any" is a filter
+   * that silently widens. To silence a trigger, use `enabled: false`.
+   *
+   * NOT a condition language. If an allow-list ever proves insufficient the
+   * answer is a host-supplied predicate, never an expression DSL.
+   */
+  sourceChannels?: string[] | null;
+  /** Copy overrides. Unset fields fall back to the code template. */
+  title?: string | null;
+  message?: string | null;
+  priority?: "low" | "normal" | "high" | null;
+  updatedBy?: string | null;
+}
+/** The reader the resolver needs. Structural, so a host can pass a cache or a fake. */
+interface TriggerOverrideStore {
+  /**
+   * Every override that could apply to `organizationId` — its scope rows AND
+   * the app-wide (`null`) rows. Returning both in one read is deliberate:
+   * resolving a fallback with a second query per event would put a round trip on
+   * the notification path.
+   */
+  forOrganization(organizationId: string | null): Promise<NotificationTriggerOverrideDoc[]>;
+}
+/**
+ * The persistence PORT the cached store wraps — "give me every row that could
+ * apply to this scope" (its own rows and the `null` app-wide rows, one read).
+ */
+type TriggerOverrideLoader = (organizationId: string | null) => Promise<NotificationTriggerOverrideDoc[]>;
+interface CreateCachedTriggerOverrideStoreOptions {
+  /**
+   * Cache TTL in ms. Default 30s.
+   *
+   * These rows change when an admin edits a form — rarely — but they are read on
+   * EVERY notifiable event, so an uncached store puts a query in front of every
+   * order. 30s bounds how long a change takes to take effect without making the
+   * hot path pay for a lookup that almost never differs.
+   */
+  ttlMs?: number;
+}
+/**
+ * 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.
+ */
+declare function createCachedTriggerOverrideStore(load: TriggerOverrideLoader, options?: CreateCachedTriggerOverrideStoreOptions): TriggerOverrideStore & {
+  invalidate: () => void;
+};
+/**
+ * The EFFECTIVE settings for one trigger in one scope.
+ *
+ * Precedence is scope → app-wide → code default, and each FIELD resolves
+ * independently: a scope that only overrode `channels` still inherits the
+ * app-wide `recipients`. Whole-row precedence would force an admin to restate
+ * every field to change one, and restating is how two settings silently drift.
+ */
+interface EffectiveTriggerSettings {
+  enabled: boolean;
+  recipients: string[];
+  channels: NotificationChannel[];
+  /** `null` = unrestricted. See {@link NotificationTriggerOverrideDoc.sourceChannels}. */
+  sourceChannels: string[] | null;
+  title: string;
+  message: string;
+  priority?: "low" | "normal" | "high" | undefined;
+}
+interface CodeTriggerDefaults {
+  recipients: string[];
+  channels: NotificationChannel[];
+  title: string;
+  message: string;
+  priority?: "low" | "normal" | "high" | undefined;
+}
+declare function resolveEffectiveSettings(triggerType: string, organizationId: string | null, rows: readonly NotificationTriggerOverrideDoc[], defaults: CodeTriggerDefaults): EffectiveTriggerSettings;
+/**
+ * Why a notification was not delivered.
+ *
+ * A CLOSED set, and it lives here rather than in each host: left to hosts every
+ * one invents its own vocabulary and none of it is comparable. Emitting these as
+ * counters is database-agnostic and stays inside this package's remit — PERSISTING
+ * them is product persistence and belongs to the spine, which is why nothing here
+ * writes a row.
+ */
+type NotificationSkipReason = "disabled" | "source_channel_mismatch" | "source_channel_unknown" | "no_recipients" | "trigger_condition_unmet";
+type NotificationDecision = {
+  decision: "deliver";
+} | {
+  decision: "skip";
+  reason: NotificationSkipReason;
+};
+/**
+ * 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.
+ */
+declare function evaluateSourceChannel(sourceChannels: string[] | null | undefined, sourceChannel: string | undefined): NotificationDecision;
+//#endregion
+//#region src/channelCatalog.d.ts
+/**
+ * Which channels a deployment can deliver on.
+ *
+ * An interface rather than a bare array so a host may back it with something
+ * live (its integrations registry) without every consumer re-deriving the set,
+ * and so `has()` is one implementation instead of an `includes` at each site.
+ */
+interface NotificationChannelCatalog {
+  /**
+   * Every deliverable channel, `in-app` first.
+   *
+   * Ordered and de-duplicated, because this drives a UI: an operator seeing
+   * channels reorder between screens has no way to tell that from a bug.
+   */
+  list(): readonly NotificationChannel[];
+  /** Is this a channel this deployment can actually deliver on? */
+  has(channel: string): boolean;
+}
+/**
+ * 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.
+ */
+declare function createNotificationChannelCatalog(connectorChannels?: readonly string[]): NotificationChannelCatalog;
+//#endregion
 //#region src/dbFirstResolver.d.ts
 /** One draftable template row — the shape be-prod's EmailTemplate model proved. */
 interface StoredTemplate {
@@ -531,24 +781,6 @@ interface TemplatesResourceOptions {
 declare function templatesResource(options: TemplatesResourceOptions): import("@classytic/arc").ResourceDefinition<unknown>;
 //#endregion
 //#region src/triggerAuthoring.d.ts
-/**
- * Notification trigger contract — the readable DSL a host writes its registry in.
- *
- * This module owns the MECHANISM (subscription, dispatch, channel fan-out) and its
- * `NotifyTrigger` is the shape the dispatcher consumes. That shape is
- * dispatch-oriented: audience resolvers, data extractors, channel arrays. Writing
- * forty of them by hand is how a registry stops being readable.
- *
- * `NotificationTrigger` is the AUTHORING shape — one flat entry per notification,
- * saying what fires, who gets it, and what it says. `toNotifyTriggers` in
- * `./triggerAdapter.js` converts one to the other.
- *
- * Moved here from `@spinekit/core/notifications` (2026-08-14): the previous home
- * declared a structural mirror of `NotifyTrigger` to avoid depending on this
- * package — a re-declared provider type, and once narrower than its subject
- * (sync-only `audience`), which silently foreclosed valid implementations. Living
- * beside the owner, the mirror is unnecessary and the compiler checks the real seam.
- */
 /** Who a trigger targets. */
 type NotificationAudienceType = "staff" | "customer";
 /** Direct contact for a customer-facing notification. */
@@ -564,6 +796,21 @@ interface NotificationExtractResult {
   triggeredBy?: string;
   /** Direct contact for `audienceType: 'customer'`. */
   recipient?: NotificationRecipientContact;
+  /**
+   * Where the triggering document ORIGINATED — matched against an override's
+   * `sourceChannels` allow-list.
+   *
+   * Deliberately an opaque string: this package must not learn a product's
+   * vocabulary. A commerce host passes its order channel (`'web'`, `'pos'`);
+   * another product might pass `'api'` or `'import'`.
+   *
+   * Omitting it is safe for an UNRESTRICTED trigger (the common case — the
+   * allow-list is consulted only when one is set). But a trigger an operator
+   * HAS restricted will skip with `source_channel_unknown` rather than deliver,
+   * because widening an explicit restriction is worse than withholding one
+   * alert visibly. So: if a trigger could ever be scoped, populate this.
+   */
+  sourceChannel?: string;
 }
 /**
  * One notification, declared.
@@ -604,12 +851,27 @@ interface NotificationTrigger {
    */
   audienceType?: NotificationAudienceType;
   priority?: "low" | "normal" | "high";
-  /** Fan out to the connected email provider. */
-  sendEmail?: boolean;
-  /** Fan out to the connected WhatsApp provider. */
-  sendWhatsapp?: boolean;
-  /** Fan out to the connected SMS provider. */
-  sendSms?: boolean;
+  /**
+   * Connector channels this trigger fans out to, by NAME — `['email',
+   * 'whatsapp']`, `['telegram']`, whatever the deployment has registered.
+   *
+   * This replaced three booleans (`sendEmail` / `sendWhatsapp` / `sendSms`).
+   * One flag per channel meant the framework enumerated the product's connector
+   * catalog, so adding a channel the integrations hub could already register at
+   * runtime was a framework edit plus a rebuild in every host — see the note on
+   * {@link NotificationChannel}.
+   *
+   * `in-app` is NOT listed here. A staff-audience trigger always gets the
+   * dashboard feed (the framework implements that channel itself); a
+   * `customer` audience never does, because buyers are not dashboard users.
+   *
+   * A name here that the deployment has not connected simply never delivers —
+   * the hub-backed channel resolves nothing and reports `skipped` with a reason.
+   * That is deliberate: a trigger may declare an aspiration the operator has not
+   * wired yet, and it must be visible in the delivery log rather than refused at
+   * boot.
+   */
+  channels?: readonly NotificationChannel[];
   /**
    * Pull dispatch variables out of the event payload.
    *
@@ -621,132 +883,6 @@ interface NotificationTrigger {
   extract: (payload: Record<string, any>) => NotificationExtractResult | null;
 }
 //#endregion
-//#region src/triggerOverride.d.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`.
- */
-/** The channels a trigger can be routed to. `in-app` is the dashboard feed. */
-declare const NOTIFICATION_CHANNELS: readonly ["in-app", "email", "whatsapp", "sms"];
-type NotificationChannel = (typeof NOTIFICATION_CHANNELS)[number];
-interface NotificationTriggerOverrideDoc {
-  /**
-   * The trigger's `type` (falling back to its `event`) — the same key
-   * `toNotifyTrigger` uses as the template id, so a row is addressable by the
-   * identifier an admin already sees in the catalog.
-   */
-  triggerType: string;
-  /** `null` = app-wide default; an organization id overrides it for that scope. */
-  organizationId?: string | null;
-  /** `false` silences the trigger entirely for this scope. */
-  enabled?: boolean;
-  /** Replaces the code trigger's roles. Empty array = nobody (use `enabled` to silence). */
-  recipients?: string[] | null;
-  /** Replaces the code trigger's channel set. */
-  channels?: NotificationChannel[] | null;
-  /** Copy overrides. Unset fields fall back to the code template. */
-  title?: string | null;
-  message?: string | null;
-  priority?: "low" | "normal" | "high" | null;
-  updatedBy?: string | null;
-}
-/** The reader the resolver needs. Structural, so a host can pass a cache or a fake. */
-interface TriggerOverrideStore {
-  /**
-   * Every override that could apply to `organizationId` — its scope rows AND
-   * the app-wide (`null`) rows. Returning both in one read is deliberate:
-   * resolving a fallback with a second query per event would put a round trip on
-   * the notification path.
-   */
-  forOrganization(organizationId: string | null): Promise<NotificationTriggerOverrideDoc[]>;
-}
-/**
- * The persistence PORT the cached store wraps — "give me every row that could
- * apply to this scope" (its own rows and the `null` app-wide rows, one read).
- */
-type TriggerOverrideLoader = (organizationId: string | null) => Promise<NotificationTriggerOverrideDoc[]>;
-interface CreateCachedTriggerOverrideStoreOptions {
-  /**
-   * Cache TTL in ms. Default 30s.
-   *
-   * These rows change when an admin edits a form — rarely — but they are read on
-   * EVERY notifiable event, so an uncached store puts a query in front of every
-   * order. 30s bounds how long a change takes to take effect without making the
-   * hot path pay for a lookup that almost never differs.
-   */
-  ttlMs?: number;
-}
-/**
- * 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.
- */
-declare function createCachedTriggerOverrideStore(load: TriggerOverrideLoader, options?: CreateCachedTriggerOverrideStoreOptions): TriggerOverrideStore & {
-  invalidate: () => void;
-};
-/**
- * The EFFECTIVE settings for one trigger in one scope.
- *
- * Precedence is scope → app-wide → code default, and each FIELD resolves
- * independently: a scope that only overrode `channels` still inherits the
- * app-wide `recipients`. Whole-row precedence would force an admin to restate
- * every field to change one, and restating is how two settings silently drift.
- */
-interface EffectiveTriggerSettings {
-  enabled: boolean;
-  recipients: string[];
-  channels: NotificationChannel[];
-  title: string;
-  message: string;
-  priority?: "low" | "normal" | "high" | undefined;
-}
-interface CodeTriggerDefaults {
-  recipients: string[];
-  channels: NotificationChannel[];
-  title: string;
-  message: string;
-  priority?: "low" | "normal" | "high" | undefined;
-}
-declare function resolveEffectiveSettings(triggerType: string, organizationId: string | null, rows: readonly NotificationTriggerOverrideDoc[], defaults: CodeTriggerDefaults): EffectiveTriggerSettings;
-//#endregion
 //#region src/triggerAdapter.d.ts
 /**
  * `entityType` → the `extract` variable holding that entity's id.
@@ -764,6 +900,37 @@ interface TriggerAdapterOptions {
    * still delivers, it just has nothing to deep-link to.
    */
   entityIdVars?: Record<string, string>;
+  /**
+   * Observe a notification that was NOT delivered, and why.
+   *
+   * Optional and side-effect-free by default: a host that wires nothing gets
+   * today's behaviour exactly. Wire it to a metrics counter — `triggerType` and
+   * `reason` are both closed sets, so cardinality stays bounded.
+   *
+   * ## Counters, not rows
+   *
+   * This intentionally hands over a value rather than writing anything. A row
+   * per skipped (event x trigger x channel) would out-write real deliveries —
+   * every POS order multiplied by every candidate trigger and channel — to
+   * answer a question no operator has asked. And persistence is product
+   * concern: this package is database-agnostic and must stay that way.
+   *
+   * ## Why it exists at all
+   *
+   * Without it a skip is a bare `null`, and "the operator scoped this to web"
+   * is indistinguishable from "the trigger never matched" and from "recipient
+   * resolution returned empty". A misconfigured scope then silently stops
+   * alerts with nothing to look at.
+   *
+   * Must not throw: it runs on the dispatch path. Failures here are the host's
+   * to contain.
+   */
+  onDecision?: (decision: {
+    triggerType: string;
+    channel: NotificationChannel;
+    reason: NotificationSkipReason;
+    organizationId: string | null;
+  }) => void;
   /**
    * ADMIN OVERRIDES — when supplied, each trigger expands into one module
    * trigger PER CHANNEL, and every one is gated on the stored settings for the
@@ -785,10 +952,22 @@ interface TriggerAdapterOptions {
    * an operator can actually use.
    *
    * OMITTED = unchanged behaviour: one trigger, static channels from the
-   * `sendEmail`/`sendWhatsapp`/`sendSms` flags. Every existing host keeps its
-   * exact current dispatch until it opts in.
+   * trigger's own `channels` list. Every existing host keeps its exact current
+   * dispatch until it opts in.
    */
   overrides?: TriggerOverrideResolution;
+  /**
+   * Which channels this deployment can deliver on — see {@link NotificationChannelCatalog}.
+   *
+   * A host builds it once from its integrations registry and passes the SAME
+   * instance here and to the override resource, so trigger settings offer
+   * exactly what validation accepts. Registering a provider is then the only
+   * step to gain a channel.
+   *
+   * Omitted, each trigger falls back to the channels it declares in code — so
+   * the worst case is "no new channels offered", never "no channels".
+   */
+  catalog?: NotificationChannelCatalog;
 }
 /**
  * How the adapter reaches stored settings for the organization on an event.
@@ -879,4 +1058,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, 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, NOTIFICATION_CHANNELS, type NotificationAudienceType, type NotificationChannel, type NotificationExtractResult, type NotificationRecipientContact, 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, createRepositoryDeliveryLog, createUnreadCountCache, dispatchTrigger, 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, readInAppContent, renderInApp, resolveEffectiveSettings, templatesResource, toNotifyTrigger, toNotifyTriggers };

package/dist/index.mjs

@@ -38,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
@@ -107,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);
@@ -116,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
 	};
 }
@@ -633,7 +860,22 @@ async function dispatchTrigger(service, trigger, event, opts) {
 			...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 } : {}
 			}
 		});
 	}
@@ -885,117 +1127,6 @@ function templatesResource(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`.
-*/
-/** The channels a trigger can be routed to. `in-app` is the dashboard feed. */
-const NOTIFICATION_CHANNELS = [
-	"in-app",
-	"email",
-	"whatsapp",
-	"sms"
-];
-/**
-* 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,
-		title,
-		message,
-		...priority ? { priority } : {}
-	};
-}
-//#endregion
 //#region src/triggerAdapter.ts
 /**
 * `entityType` → the `extract` variable holding that entity's id.
@@ -1023,15 +1154,38 @@ function toNotifyTrigger(t, options = {}) {
 		...options.entityIdVars
 	};
 	const entityVar = t.template.entityType ? entityIdVars[t.template.entityType] : void 0;
-	const channels = t.audienceType === "customer" ? [] : ["in-app"];
-	if (t.sendEmail) channels.push("email");
-	if (t.sendWhatsapp) channels.push("whatsapp");
-	if (t.sendSms) channels.push("sms");
+	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;
@@ -1048,7 +1202,13 @@ function toNotifyTrigger(t, options = {}) {
 				...ex.triggeredBy ? { excludeUserId: ex.triggeredBy } : {}
 			};
 		},
-		data: (e) => t.extract(e.payload ?? {})?.variables ?? {},
+		data: (e) => {
+			const vars = t.extract(e.payload ?? {})?.variables ?? {};
+			return {
+				...vars,
+				...copyFor(t, vars)
+			};
+		},
 		inApp: {
 			title: t.template.title,
 			message: t.template.message,
@@ -1058,13 +1218,56 @@ function toNotifyTrigger(t, options = {}) {
 		}
 	};
 }
-/** The channel set a trigger declares in CODE — its default before any override. */
+/**
+* `{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) {
-	const channels = t.audienceType === "customer" ? [] : ["in-app"];
-	if (t.sendEmail) channels.push("email");
-	if (t.sendWhatsapp) channels.push("whatsapp");
-	if (t.sendSms) channels.push("sms");
-	return channels;
+	return [...t.audienceType === "customer" ? [] : [IN_APP_CHANNEL], ...t.channels ?? []];
 }
 /**
 * Every channel an override could ever turn ON for this trigger.
@@ -1075,13 +1278,27 @@ function declaredChannels(t) {
 * 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) {
-	const configurable = [
-		"email",
-		"whatsapp",
-		"sms"
-	];
-	return t.audienceType === "customer" ? configurable : ["in-app", ...configurable];
+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.
@@ -1100,7 +1317,7 @@ function toGatedNotifyTriggers(t, options, overrides) {
 		message: t.template.message,
 		...t.priority ? { priority: t.priority } : {}
 	};
-	return candidateChannels(t).map((channel) => ({
+	return candidateChannels(t, options.catalog).map((channel) => ({
 		...base,
 		channels: [channel],
 		audience: async (e) => {
@@ -1108,7 +1325,43 @@ function toGatedNotifyTriggers(t, options, overrides) {
 			if (!ex) return null;
 			const rows = await overrides.store.forOrganization(ex.organizationId ?? null);
 			const eff = resolveEffectiveSettings(type, ex.organizationId ?? null, rows, defaults);
-			if (!eff.enabled) return null;
+			/**
+			* 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;
@@ -1117,7 +1370,7 @@ function toGatedNotifyTriggers(t, options, overrides) {
 					organizationId: ex.organizationId
 				};
 			}
-			if (eff.recipients.length === 0) return null;
+			if (eff.recipients.length === 0) return skip("no_recipients");
 			return {
 				roles: eff.recipients,
 				organizationId: ex.organizationId,
@@ -1168,4 +1421,4 @@ function getRecipientMatrix(triggers) {
 	return matrix;
 }
 //#endregion
-export { DEFAULT_ENTITY_ID_VARS, INAPP_DATA_KEY, InAppChannel, NOTIFICATION_CHANNELS, SseChannel, createCachedTriggerOverrideStore, createDbFirstResolver, createInAppBackfill, createRepositoryDeliveryLog, createUnreadCountCache, dispatchTrigger, 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, readInAppContent, renderInApp, resolveEffectiveSettings, templatesResource, toNotifyTrigger, toNotifyTriggers };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc-notifications",
-  "version": "0.4.0",
+  "version": "0.5.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": {