@classytic/arc-notifications 0.3.0 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Classytic LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -197,3 +197,7 @@ direct queue dependency.
 
 Generalized from be-prod's production `shared/notifications` (db-first resolver) +
 `resources/notifications` (email-template model, admin resource, event-trigger registry).
+
+## Trademark
+
+MIT-licensed code. "Classytic"/"arc" names + logos are trademarks of Classytic LLC — see [TRADEMARK.md](TRADEMARK.md).

package/dist/index.d.mts

@@ -130,6 +130,23 @@ interface InAppFeedRepository<TRow = unknown> {
    * `DELETE /:id`. Hard vs soft delete is the host's call.
    */
   delete?(organizationId: string, userId: string, id: string): Promise<boolean>;
+  /**
+   * OPTIONAL — delete every ALREADY-READ row for this user; returns the count.
+   * When implemented, the feed resource registers `DELETE /read`.
+   *
+   * Read-only by design, and that is the whole safety property: an unread row
+   * is one the user has not seen, so a "clear" that removed it would destroy
+   * the notification instead of dismissing it — silently, since nothing can
+   * report a message nobody read. Odoo's garbage collector draws the same line
+   * (it vacuums SENT notifications and keeps failures), and per-row `delete`
+   * remains available for deliberately discarding something unread.
+   *
+   * This exists because `markAllRead` is not a clear: it greys the list and
+   * leaves every row in place, so an operator who wants an empty inbox has no
+   * verb at all — the state they are asking for is unreachable one row at a
+   * time.
+   */
+  deleteRead?(organizationId: string, userId: string): Promise<number>;
 }
 /**
  * Cache seam for the unread badge count — the hottest query in the system
@@ -215,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 {
@@ -363,6 +630,24 @@ interface NotifyTrigger<TPayload = unknown> {
   readonly priority?: InAppPriority;
   /** Template variables. Default: the event payload (when object-shaped). */
   readonly data?: (event: DomainEvent<TPayload>) => Record<string, unknown> | Promise<Record<string, unknown>>;
+  /**
+   * The BUSINESS DOCUMENT this trigger's notifications are about, extracted
+   * from the event — `{ sourceModel, sourceId }`.
+   *
+   * Belongs HERE, beside `recipient` and `data`, for the same reason they do:
+   * the notification control centre splits ownership so that CODE owns the
+   * event and its extraction while the DATABASE owns channels and recipients.
+   * Which document an event concerns is a fact about the event's shape, so it
+   * is code — an operator cannot configure it and must never have to.
+   *
+   * Omit for events that concern no single document (a segment broadcast). A
+   * fabricated subject is worse than none: it makes a document's send history
+   * show messages that were never about it.
+   */
+  readonly subject?: (event: DomainEvent<TPayload>) => {
+    sourceModel: string;
+    sourceId: string;
+  } | undefined;
   /**
    * Dedup key for at-least-once transports. Default:
    * `meta.idempotencyKey ?? "<type>:<meta.id>"`, suffixed per recipient on
@@ -372,12 +657,24 @@ interface NotifyTrigger<TPayload = unknown> {
   /** Compose-time kill switch (env-gated triggers). Default true. */
   readonly enabled?: boolean;
 }
-interface NotificationsModuleConfig extends Omit<NotificationServiceConfig, "queue"> {
+interface NotificationsModuleConfig extends Omit<NotificationServiceConfig, "queue" | "channels"> {
+  /**
+   * The channels to dispatch through — a value, or a FUNCTION resolved at bootstrap.
+   *
+   * The function form exists for the same reason `queue`'s does: a channel can be expensive to
+   * build. A host wiring a provider-backed channel has to construct a hub, a credential vault and
+   * a repository to do it, and passing the built array means all of that runs while the module
+   * GRAPH is being composed — before arc has validated it, for a module the deployment may still
+   * reject. In be-prod that registered a mongoose model and derived an AES key at composition.
+   *
+   * Resolved inside `bootstrap`, where the service is constructed anyway, so nothing else moves.
+   */
+  readonly channels?: NotificationServiceConfig["channels"] | ((fastify: FastifyInstance) => NotificationServiceConfig["channels"] | Promise<NotificationServiceConfig["channels"]>);
   /** Module name (registry + export-map key). Default "notifications". */
   readonly name?: string;
   /** Bring-your-own service — skips construction; service config fields ignored. */
   readonly service?: NotificationService;
-  /** Declarative event → notification triggers, wired in `afterResources`. */
+  /** Declarative event → notification triggers, contributed as `eventHandlers`. */
   readonly notifyOn?: readonly NotifyTrigger[];
   /**
    * Resolves a trigger's `audience` selector to recipients (the shared
@@ -422,6 +719,15 @@ interface DeliveryLogDoc {
   readonly status: EntryStatus;
   readonly duration: number;
   readonly metadata?: Record<string, unknown>;
+  /**
+   * The business document this delivery concerned. A STORE MUST INDEX IT —
+   * this field exists precisely so "every message about invoice X" is a keyed
+   * read rather than a scan of the unindexed `metadata` blob.
+   */
+  readonly subject?: {
+    readonly sourceModel: string;
+    readonly sourceId: string;
+  };
 }
 interface RepositoryDeliveryLogOptions {
   /** Cap for `query()` when the caller gives no limit. Default 100. */
@@ -474,4 +780,282 @@ interface TemplatesResourceOptions {
 }
 declare function templatesResource(options: TemplatesResourceOptions): import("@classytic/arc").ResourceDefinition<unknown>;
 //#endregion
-export { type CodeTemplates, type CreateUnreadCountCacheOptions, type DbFirstResolverOptions, type DbFirstTemplateResolver, type DeliveryLogDoc, 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, type NotificationsJob, type NotificationsJobOptions, type NotificationsModuleConfig, type NotifyTrigger, type RealtimePushPort, type RecipientResolver, type RepositoryDeliveryLogOptions, SseChannel, type SseChannelConfig, type StoredTemplate, type TemplateStore, type TemplatesResourceOptions, type UnreadCountCache, createDbFirstResolver, createInAppBackfill, createRepositoryDeliveryLog, createUnreadCountCache, dispatchTrigger, inAppFeedResource, notificationsJob, notificationsModule, readInAppContent, renderInApp, templatesResource };
+//#region src/triggerAuthoring.d.ts
+/** Who a trigger targets. */
+type NotificationAudienceType = "staff" | "customer";
+/** Direct contact for a customer-facing notification. */
+interface NotificationRecipientContact {
+  email?: string;
+  phone?: string;
+  name?: string;
+}
+/** What `extract` returns: the scope, the template variables, and the target. */
+interface NotificationExtractResult {
+  organizationId: string;
+  variables: Record<string, string>;
+  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.
+ *
+ * Adding a notification is adding one of these to the host's registry — nothing
+ * else to touch.
+ */
+interface NotificationTrigger {
+  /** Arc event name to subscribe to (e.g. `'order:created'`). */
+  event: string;
+  /**
+   * Notification kind — the feed type AND the email template id. Defaults to
+   * the event name.
+   *
+   * Two triggers MAY share an event (an informational alert plus an escalation);
+   * distinct `type` values are what keep them independently filterable.
+   */
+  type?: string;
+  /** In-app template. `{variable}` placeholders resolve against `extract`'s variables. */
+  template: {
+    title: string;
+    message: string;
+    /** Frontend route, with `{variable}` placeholders. */
+    link?: string;
+    /** Entity kind, for badge/icon grouping and entity-id derivation. */
+    entityType?: string;
+  };
+  /**
+   * Roles that receive this notification. `'*'` = all branch members.
+   * Ignored when `audienceType` is `'customer'` — that target comes from
+   * `extract`'s `recipient`.
+   */
+  recipients: string[];
+  /**
+   * `'staff'` (default) resolves branch members by `recipients` roles.
+   * `'customer'` targets the direct contact `extract` returns, with NO staff
+   * lookup and NO in-app feed row (buyers are not dashboard users).
+   */
+  audienceType?: NotificationAudienceType;
+  priority?: "low" | "normal" | "high";
+  /**
+   * 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.
+   *
+   * Returning `null` SKIPS the notification — this is the filter seam. A
+   * trigger that subscribes to a broad event (`order:payment.state_updated`)
+   * and only wants one case (`chargeStatus === 'failed'`) expresses that here,
+   * rather than notifying on every state change.
+   */
+  extract: (payload: Record<string, any>) => NotificationExtractResult | null;
+}
+//#endregion
+//#region src/triggerAdapter.d.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`.
+ */
+declare const DEFAULT_ENTITY_ID_VARS: Record<string, string>;
+interface TriggerAdapterOptions {
+  /**
+   * Extra `entityType` → id-variable mappings, merged over the defaults.
+   *
+   * An unmapped `entityType` simply yields no `entityId` — the notification
+   * 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
+   * event's organization.
+   *
+   * ## Why expansion rather than one trigger with dynamic channels
+   *
+   * `NotifyTrigger.channels` is a STATIC `readonly string[]` — arc resolves it
+   * at registration, not per dispatch. So "this scope wants order alerts on
+   * WhatsApp but not email" cannot be expressed by mutating one trigger's
+   * channel list at send time. It CAN be expressed as separate triggers, each
+   * restricted to one channel, each skipping when that channel is off for the
+   * scope — `audience` IS a per-event async function, which is the seam that
+   * makes this possible without changing arc.
+   *
+   * The cost is N subscriptions per trigger instead of one, and `extract` runs
+   * per channel. `extract` is pure and cheap by contract (the adapter already
+   * calls it twice per dispatch), so this trades a little fan-out for a control
+   * an operator can actually use.
+   *
+   * OMITTED = unchanged behaviour: one trigger, static channels from the
+   * 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.
+ *
+ * Just the store. The ORGANIZATION comes from the trigger's own `extract`
+ * (`ex.organizationId`) rather than a second resolver here — `extract` is
+ * already the one place that knows how a given event carries its scope, and a
+ * parallel answer would be a second place to get it wrong.
+ */
+interface TriggerOverrideResolution {
+  store: TriggerOverrideStore;
+}
+/**
+ * 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).
+ */
+declare function toNotifyTrigger(t: NotificationTrigger, options?: TriggerAdapterOptions): NotifyTrigger;
+/**
+ * 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.
+ */
+declare function toNotifyTriggers(triggers: readonly NotificationTrigger[], options?: TriggerAdapterOptions): NotifyTrigger[];
+/**
+ * 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`.
+ */
+declare function getTriggerByEvent(triggers: readonly NotificationTrigger[], event: string): NotificationTrigger | undefined;
+/** Every trigger registered for an event, in registration order. */
+declare function getTriggersByEvent(triggers: readonly NotificationTrigger[], event: string): NotificationTrigger[];
+/** Distinct event names the registry subscribes to (for docs / admin UI). */
+declare function getRegisteredEvents(triggers: readonly NotificationTrigger[]): string[];
+/**
+ * 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.
+ */
+declare function getRecipientMatrix(triggers: readonly NotificationTrigger[]): Record<string, string[]>;
+//#endregion
+//#region src/triggerCatalog.d.ts
+/**
+ * One trigger as an operator sees it, with the CODE defaults an override replaces.
+ *
+ * Deliberately not the internal trigger shape: `extract` is a function and cannot
+ * cross the wire, and a UI has no use for it. What a settings screen needs is the
+ * identity, a human label, and the defaults so it can show "customised" against
+ * "default" without guessing.
+ */
+interface TriggerCatalogEntry {
+  /**
+   * The override key — a trigger's `type`, falling back to its `event`.
+   *
+   * This is the same identifier `toNotifyTrigger` uses as the template id, so a row
+   * created from this screen addresses the trigger the dispatch path will look up. A
+   * settings UI keyed on anything else would write rows nothing reads.
+   */
+  triggerType: string;
+  /** The domain event it listens to, shown so an operator can trace cause to effect. */
+  event: string;
+  /** Human label. Falls back to `triggerType` when the host supplies none. */
+  label: string;
+  /** Optional grouping for the UI ("Orders", "Inventory"). */
+  group?: string;
+  /** Code-default recipient roles, replaced by an override's `recipients`. */
+  defaultRecipients: string[];
+  /** Code-default channels, replaced by an override's `channels`. */
+  defaultChannels: NotificationChannel[];
+  /** Code-default copy, overridable per scope. */
+  defaultTitle?: string;
+  defaultMessage?: string;
+}
+/**
+ * Host-supplied catalog reader.
+ *
+ * Optional on the resource: a deployment that does not expose its catalog simply has
+ * no `/catalog` route, and the settings screen says so rather than showing an empty
+ * matrix. Never defaulted to `() => []` — that would turn "not exposed" into "nothing
+ * exists", which is the silent-empty failure this file exists to avoid.
+ */
+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 };