@classytic/arc-notifications 0.9.0 → 0.10.0

package/README.md

@@ -129,6 +129,21 @@ sseHub.onConnect((userId, orgId) => backfill.onConnect(userId, orgId)); // debou
   badge's axis). Both stay host-owned in the repository.
 - All realtime is **best-effort on top of the durable feed** — a dead socket never
   fails a request or a send; clients converge via `GET /notifications/`.
+- **Cursor replay.** Pass the client's last-seen time on connect —
+  `backfill.onConnect(userId, orgId, { since: req.headers['last-event-id'] })` — and
+  a repository that also implements `listSince(org, user, since, limit)` replays the
+  gap, including rows an earlier connection received but dropped; they merge with the
+  claimed rows into the same single bulk event.
+- **List envelope and verbs.** `inAppFeedResource({ listEnvelope: 'offset' })` answers
+  repo-core's `OffsetPaginationResult` (`feedListResult` is the same conversion);
+  `{ actions: true }` also mounts `markRead` / `markAllRead` as arc action-router verbs.
+- **One push per recipient.** The package calls `port.push` once per recipient and event
+  and never publishes on a bus itself. If your port forwards frames onto an event bus,
+  give each frame its own correlation id (it is a transport hop, not a second publish of
+  one logical event), or arc's dev duplicate-publish detector will warn on every
+  multi-recipient notification.
+- **Clock.** `createUnreadCountCache({ clock })` and
+  `createRepositoryDeliveryLog(repo, { clock })` take a `{ now(): Date }`.
 
 ### 5. Durable dispatch — crash-safe bulk sends (10k+)
 

package/dist/index.d.mts

@@ -1,11 +1,11 @@
-import { BaseChannel, ChannelConfig, DeliveryLog, DeliveryLogEntry, NotificationPayload, NotificationService, NotificationServiceConfig, QueueAdapter, Recipient, SendResult, TemplateResolver } from "@classytic/notifications";
-import { JobDefinition, JobDispatcher } from "@classytic/arc/integrations/jobs";
 import { ArcModule, EventHandlerDefinition } from "@classytic/arc/factory";
+import { BaseChannel, ChannelConfig, DeliveryLog, DeliveryLogEntry, DispatchResult, NotificationPayload, NotificationService, NotificationServiceConfig, QueueAdapter, Recipient, SendResult, TemplateResolver } from "@classytic/notifications";
+import { JobDefinition, JobDispatcher } from "@classytic/arc/integrations/jobs";
 import { PermissionCheck } from "@classytic/arc/permissions";
+import { OffsetPaginationResult } from "@classytic/repo-core/pagination";
 import { FastifyInstance, FastifyRequest } from "fastify";
 import { DomainEvent } from "@classytic/primitives/events";
 import { RepositoryLike } from "@classytic/repo-core/adapter";
-//#region src/inApp.d.ts
 /**
  * In-app notification content — the shared seam between a `notifyOn` trigger's
  * declarative `inApp` template and the channels that deliver it (the DB feed
@@ -23,7 +23,7 @@ import { RepositoryLike } from "@classytic/repo-core/adapter";
  * in-app convention; the email template layer keeps its own `${var}` engine.
  */
 /** Reserved `payload.data` key carrying the rendered in-app content. */
-declare const INAPP_DATA_KEY = "__inApp";
+export declare const INAPP_DATA_KEY = "__inApp";
 /**
  * Host realtime transport — push an event to one user within a tenant.
  * The transport itself (connection registry, heartbeats, the `/stream`
@@ -59,11 +59,21 @@ interface InAppContent {
   readonly priority: InAppPriority;
 }
 /** Render a trigger's in-app template against event data + priority. */
-declare function renderInApp(template: InAppTemplate, vars: Record<string, unknown>, priority?: InAppPriority): InAppContent;
+export declare function renderInApp(template: InAppTemplate, vars: Record<string, unknown>, priority?: InAppPriority): InAppContent;
 /** Read the rendered in-app content a trigger parked on the send payload's data. */
-declare function readInAppContent(data: Record<string, unknown> | undefined): InAppContent | null;
-//#endregion
-//#region src/inAppFeed.d.ts
+export declare function readInAppContent(data: Record<string, unknown> | undefined): InAppContent | null;
+/**
+ * The notification clock — one seam so every "now" the in-app feed, the reconnect backfill
+ * and the delivery log stamp goes through a single injectable source.
+ *
+ * Structural on purpose: a host's own `Clock` (`{ now(): Date }`) satisfies it with no
+ * adapter, and a test passes a frozen or stepped one to make unread-cache expiry, ordering
+ * and `timestamp` stamps deterministic. The default is real time.
+ */
+interface NotificationClock {
+  now(): Date;
+}
+export declare const systemNotificationClock: NotificationClock;
 /** A feed row the {@link InAppChannel} writes and this resource reads. */
 interface InAppFeedRow {
   readonly organizationId: string;
@@ -124,6 +134,18 @@ interface InAppFeedRepository<TRow = unknown> {
    * the debounce window) from double-toasting the same rows.
    */
   claimUndelivered?(organizationId: string, userId: string, limit: number): Promise<TRow[]>;
+  /**
+   * OPTIONAL — rows created AFTER `since`, oldest first, WITHOUT claiming them. Powers the
+   * cursor flavour of reconnect backfill (`onConnect(user, org, { since })`): a client that
+   * remembers the time of its last event (SSE `Last-Event-ID`) replays exactly the gap,
+   * including rows an earlier connection already received but dropped before rendering.
+   */
+  listSince?(organizationId: string, userId: string, since: Date, limit: number): Promise<TRow[]>;
+  /**
+   * OPTIONAL — stamp one row delivered (a live push reached a client), so the next
+   * reconnect does not re-send it. `false` when not found / not owned.
+   */
+  markDelivered?(organizationId: string, userId: string, id: string): Promise<boolean>;
   /**
    * OPTIONAL — delete one row (user dismissed it for good); `false` when not
    * found / not owned. When implemented, the feed resource registers
@@ -168,13 +190,15 @@ interface CreateUnreadCountCacheOptions {
   readonly ttlMs?: number;
   /** Entry cap — oldest entries evicted past it (bounds memory). Default 10_000. */
   readonly maxEntries?: number;
+  /** Source of "now" for entry freshness. Default real time. */
+  readonly clock?: NotificationClock;
 }
 /**
  * In-process TTL cache for unread counts. Per-process: invalidations don't
  * cross workers, so a multi-process host either accepts up-to-TTL staleness on
  * the other workers or brings a Redis-backed {@link UnreadCountCache}.
  */
-declare function createUnreadCountCache(options?: CreateUnreadCountCacheOptions): UnreadCountCache;
+export declare function createUnreadCountCache(options?: CreateUnreadCountCacheOptions): UnreadCountCache;
 /** The current user + tenant, resolved off a request by the host. */
 interface InAppFeedScope {
   readonly userId: string;
@@ -206,10 +230,31 @@ interface InAppFeedResourceOptions {
    * instance with `InAppChannel` so new-row writes invalidate too.
    */
   readonly unreadCache?: UnreadCountCache;
+  /**
+   * Shape of `GET <prefix>/`. `"native"` (default) answers the port's `{ data, pagination }`
+   * page untouched; `"offset"` answers repo-core's canonical `OffsetPaginationResult` (see
+   * {@link feedListResult}) for a host whose every other list is that shape.
+   */
+  readonly listEnvelope?: "native" | "offset";
+  /**
+   * Also mount `markRead` (`POST /:id/action`) and `markAllRead` (`POST /action`) as arc
+   * action-router verbs ({@link FEED_ACTION_VERBS}, camelCase), beside the `PATCH` routes.
+   * Same handlers, same cache invalidation and cross-tab read-sync. Default false.
+   */
+  readonly actions?: boolean;
 }
-declare function inAppFeedResource(options: InAppFeedResourceOptions): import("@classytic/arc").ResourceDefinition<import("@classytic/arc").AnyRecord>;
-//#endregion
-//#region src/backfill.d.ts
+/** The action-router verbs {@link InAppFeedResourceOptions.actions} mounts. */
+export declare const FEED_ACTION_VERBS: {
+  readonly markRead: "markRead";
+  readonly markAllRead: "markAllRead";
+};
+/**
+ * A feed page in repo-core's canonical offset envelope. Pure and exported so a host that
+ * builds its own list route (or asserts the envelope in a test) converts the same way the
+ * resource does. `hasNext`/`hasPrev` follow from the page arithmetic the port already did.
+ */
+export declare function feedListResult<TRow>(page: InAppFeedPage<TRow>): OffsetPaginationResult<TRow>;
+export declare function inAppFeedResource(options: InAppFeedResourceOptions): import("@classytic/arc").ResourceDefinition<import("@classytic/arc").AnyRecord>;
 interface InAppBackfillOptions {
   /** Feed repository — MUST implement the optional `claimUndelivered`. */
   readonly repository: InAppFeedRepository;
@@ -224,15 +269,18 @@ interface InAppBackfillOptions {
   /** Claim/push failure sink (backfill is best-effort). Default: swallow. */
   readonly onError?: (error: unknown) => void;
 }
+/** Per-connection hints for {@link InAppBackfill.onConnect}. */
+interface InAppBackfillConnect {
+  /** Replay rows created after this instant (a `Last-Event-ID` / `since` cursor). */
+  readonly since?: Date | string | number | undefined;
+}
 interface InAppBackfill {
   /** Call from the host's SSE/WS connection handler. Sync, never throws. */
-  onConnect(userId: string, organizationId: string): void;
+  onConnect(userId: string, organizationId: string, connect?: InAppBackfillConnect): void;
   /** Cancel pending debounces (graceful shutdown / tests). */
   close(): void;
 }
-declare function createInAppBackfill(options: InAppBackfillOptions): InAppBackfill;
-//#endregion
-//#region src/triggerOverride.d.ts
+export declare function createInAppBackfill(options: InAppBackfillOptions): InAppBackfill;
 /**
  * Notification trigger OVERRIDES — the admin-editable half of the registry.
  *
@@ -299,7 +347,7 @@ declare function createInAppBackfill(options: InAppBackfillOptions): InAppBackfi
  * 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";
+export 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
@@ -390,7 +438,7 @@ interface CreateCachedTriggerOverrideStoreOptions {
  * any mutation so an operator's change applies within one save rather than one
  * TTL window.
  */
-declare function createCachedTriggerOverrideStore(load: TriggerOverrideLoader, options?: CreateCachedTriggerOverrideStoreOptions): TriggerOverrideStore & {
+export declare function createCachedTriggerOverrideStore(load: TriggerOverrideLoader, options?: CreateCachedTriggerOverrideStoreOptions): TriggerOverrideStore & {
   invalidate: () => void;
 };
 /**
@@ -435,7 +483,7 @@ interface CodeTriggerDefaults {
    */
   sourceChannels?: readonly string[] | undefined;
 }
-declare function resolveEffectiveSettings(triggerType: string, organizationId: string | null, rows: readonly NotificationTriggerOverrideDoc[], defaults: CodeTriggerDefaults): EffectiveTriggerSettings;
+export declare function resolveEffectiveSettings(triggerType: string, organizationId: string | null, rows: readonly NotificationTriggerOverrideDoc[], defaults: CodeTriggerDefaults): EffectiveTriggerSettings;
 /**
  * Why a notification was not delivered.
  *
@@ -476,9 +524,7 @@ type NotificationDecision = {
  * 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
+export declare function evaluateSourceChannel(sourceChannels: string[] | null | undefined, sourceChannel: string | undefined): NotificationDecision;
 /**
  * Which channels a deployment can deliver on.
  *
@@ -509,9 +555,206 @@ interface NotificationChannelCatalog {
  *   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
+export declare function createNotificationChannelCatalog(connectorChannels?: readonly string[]): NotificationChannelCatalog;
+/** `YYYY-MM-DD`. */
+type CivilDateString = string;
+/** True for a real calendar date in `YYYY-MM-DD` form. */
+export declare function isCivilDateString(value: unknown): value is CivilDateString;
+/** `date` moved by `days` (negative = earlier). */
+export declare function addCivilDays(date: CivilDateString, days: number): CivilDateString;
+/** Whole days from `a` to `b` (`b - a`). */
+export declare function civilDaysBetween(a: CivilDateString, b: CivilDateString): number;
+/** When a rule fires, relative to the item's date. */
+interface DateRuleSchedule {
+  /**
+   * Days from the date to the FIRST occurrence: negative = before (`-30` = 30 days
+   * before), `0` = on the day, positive = after (`1` = the day after: "overdue").
+   */
+  readonly offsetDays: number;
+  /** Fire again every N days after the first occurrence while the item stays open. Omit = once. */
+  readonly repeatEveryDays?: number;
+  /** Bounds on repetition. Without it a repeating rule runs until the item is no longer open. */
+  readonly until?: {
+    /** Total occurrences, the first included. */
+    readonly occurrences?: number;
+    /** No occurrence after `date + offsetDays` (relative to the item's date, like `offsetDays`). */
+    readonly offsetDays?: number;
+  };
+}
+/**
+ * One admin-defined date rule. `TAudience` is the host's audience selector — this
+ * package never interprets it; it is handed to the host's `resolveAudience`.
+ */
+interface DateRule<TAudience = unknown> {
+  /** Stable id: part of every ledger key, so it must not change for the life of the rule. */
+  readonly id: string;
+  /** Default true. */
+  readonly enabled?: boolean;
+  /** A registered {@link DateRuleSource} key. */
+  readonly source: string;
+  /** One of that source's `dateFields`. */
+  readonly dateField: string;
+  readonly schedule: DateRuleSchedule;
+  readonly audience: TAudience;
+  /** Restrict to these channel names. Omit = every channel that applies. */
+  readonly channels?: readonly string[];
+  /**
+   * Template id / notification kind (the feed row's type). Default
+   * `<source>.<dateField>`. With a template resolver configured on the service it
+   * also names the email template.
+   */
+  readonly template?: string;
+  /** In-app copy with `{var}` placeholders resolved against the item's `data`. */
+  readonly inApp?: InAppTemplate;
+  readonly priority?: InAppPriority;
+  /** Scope passed to the source; `null`/absent = every organization the source serves. */
+  readonly organizationId?: string | null;
+}
+/** One record a source reports, with the date the rule's `dateField` names. */
+interface DateRuleItem {
+  /** Stable record id (part of the ledger key). */
+  readonly id: string;
+  /** The `dateField` value, `YYYY-MM-DD`. */
+  readonly date: CivilDateString;
+  /** Template variables (and anything the host's audience resolver needs). */
+  readonly data: Record<string, unknown>;
+  /** The business document, for the delivery log's per-document history. */
+  readonly subject?: {
+    readonly sourceModel: string;
+    readonly sourceId: string;
+  };
+  readonly organizationId?: string;
+}
+interface DateRuleSourceQuery {
+  readonly dateField: string;
+  /** Inclusive lower bound; absent = unbounded (an open-ended repeating rule). */
+  readonly from?: CivilDateString;
+  /** Inclusive upper bound. */
+  readonly to: CivilDateString;
+  readonly organizationId?: string | null;
+}
+/**
+ * A host record type that carries dates. Registered by the host (one per record
+ * type); the admin screen lists them through {@link DateRuleEngine.catalog}.
+ */
+interface DateRuleSource {
+  readonly key: string;
+  readonly label?: string;
+  readonly dateFields: ReadonlyArray<{
+    readonly key: string;
+    readonly label?: string;
+  }>;
+  /** Template variables items carry, as a hint for rule authors (`{employeeName}`). */
+  readonly variables?: readonly string[];
+  /**
+   * OPEN items whose `dateField` lies in `[from, to]`. "Open" is the source's call:
+   * an item that no longer needs reminding must not be returned.
+   */
+  find(query: DateRuleSourceQuery): Promise<readonly DateRuleItem[]> | AsyncIterable<DateRuleItem>;
+}
+type DateRuleAudienceResolver<TAudience = unknown> = (audience: TAudience, context: {
+  readonly rule: DateRule<TAudience>;
+  readonly item: DateRuleItem;
+  readonly occurrence: DateRuleOccurrence;
+}) => readonly Recipient[] | null | undefined | Promise<readonly Recipient[] | null | undefined>;
+/**
+ * "Has this occurrence fired?" — claimed BEFORE dispatch, released on failure so the
+ * next sweep retries. Back it with a unique index in production; the memory ledger
+ * is for tests and single-process dev.
+ */
+interface DateRuleLedger {
+  /** `true` when this call claimed the key (first time), `false` when already claimed. */
+  claim(key: string, info: DateRuleLedgerEntry): Promise<boolean>;
+  /** Undo a claim whose dispatch failed. */
+  release(key: string): Promise<void>;
+}
+interface DateRuleLedgerEntry {
+  readonly ruleId: string;
+  readonly itemId: string;
+  readonly occurrenceOn: CivilDateString;
+  readonly index: number;
+  readonly sweptOn: CivilDateString;
+}
+export declare function createMemoryDateRuleLedger(): DateRuleLedger & {
+  keys(): string[];
+};
+interface DateRuleOccurrence {
+  /** 0-based occurrence index. */
+  readonly index: number;
+  /** The civil date this occurrence is scheduled for. */
+  readonly on: CivilDateString;
+}
+/** Problems with a schedule, as messages; empty = valid. */
+export declare function validateDateRuleSchedule(schedule: DateRuleSchedule): string[];
+/**
+ * The occurrence of `schedule` for an item dated `date` that a sweep on `today`
+ * should send, or `null`. The latest occurrence on or before `today` is due when it
+ * is at most `graceDays` old — so a missed sweep catches up, but a rule created
+ * today does not replay years of history.
+ */
+export declare function dueOccurrence(schedule: DateRuleSchedule, date: CivilDateString, today: CivilDateString, graceDays?: number): DateRuleOccurrence | null;
+/** The `[from, to]` range of item dates a sweep on `today` must ask a source for. */
+export declare function dateRuleWindow(schedule: DateRuleSchedule, today: CivilDateString, graceDays?: number): {
+  from?: CivilDateString;
+  to: CivilDateString;
+};
+interface DateRuleEngineOptions<TAudience = unknown> {
+  readonly sources: Iterable<DateRuleSource>;
+  /** The rules to evaluate (admin-created rows); disabled rows are skipped. */
+  readonly rules: () => readonly DateRule<TAudience>[] | Promise<readonly DateRule<TAudience>[]>;
+  readonly resolveAudience: DateRuleAudienceResolver<TAudience>;
+  /** The notification service (read per sweep, so a module export can back it). */
+  readonly service: () => NotificationService;
+  /** Default: an in-memory ledger (single process, lost on restart). */
+  readonly ledger?: DateRuleLedger;
+  /** How many days late an occurrence may still be sent (missed sweeps). Default 0. */
+  readonly graceDays?: number;
+  /** Extra send data per item (e.g. email `subject`/`text` rendered from the rule's copy). */
+  readonly data?: (rule: DateRule<TAudience>, item: DateRuleItem) => Record<string, unknown>;
+  /** A rule or item failed; the sweep continues. */
+  readonly onError?: (err: unknown, context: {
+    readonly ruleId: string;
+    readonly itemId?: string;
+  }) => void;
+}
+interface DateRuleSweepResult {
+  readonly date: CivilDateString;
+  /** Enabled rules evaluated. */
+  readonly rules: number;
+  /** Items whose occurrence was due. */
+  readonly due: number;
+  /** Occurrences dispatched by this sweep. */
+  readonly fired: number;
+  /** Occurrences already claimed (an earlier sweep, another replica). */
+  readonly duplicates: number;
+  /** Occurrences with nobody to tell. */
+  readonly noRecipients: number;
+  readonly failed: number;
+}
+interface DateRuleCatalogEntry {
+  readonly key: string;
+  readonly label: string;
+  readonly dateFields: ReadonlyArray<{
+    readonly key: string;
+    readonly label: string;
+  }>;
+  readonly variables: readonly string[];
+}
+interface DateRuleEngine<TAudience = unknown> {
+  /** Evaluate every enabled rule for the civil date `today`. */
+  sweep(today: CivilDateString): Promise<DateRuleSweepResult>;
+  /** Items a rule would notify on `today` (no claims, no sends): the admin "preview". */
+  preview(rule: DateRule<TAudience>, today: CivilDateString): Promise<Array<DateRuleItem & {
+    occurrence: DateRuleOccurrence;
+  }>>;
+  /** Registered sources for the rule editor. */
+  catalog(): DateRuleCatalogEntry[];
+  /** Problems with a rule against the registered sources, as messages; empty = valid. */
+  validate(rule: Pick<DateRule<TAudience>, "source" | "dateField" | "schedule">): string[];
+}
+/** Ledger key of one occurrence. */
+export declare const dateRuleOccurrenceKey: (ruleId: string, itemId: string, on: CivilDateString) => string;
+export declare function createDateRuleEngine<TAudience = unknown>(options: DateRuleEngineOptions<TAudience>): DateRuleEngine<TAudience>;
 /** One draftable template row — the shape be-prod's EmailTemplate model proved. */
 interface StoredTemplate {
   readonly key: string;
@@ -547,9 +790,7 @@ interface DbFirstTemplateResolver {
   /** Drop one key (after a draft is saved) or the whole cache. */
   invalidate(key?: string): void;
 }
-declare function createDbFirstResolver(options: DbFirstResolverOptions): DbFirstTemplateResolver;
-//#endregion
-//#region src/inAppChannel.d.ts
+export declare function createDbFirstResolver(options: DbFirstResolverOptions): DbFirstTemplateResolver;
 interface InAppChannelConfig extends ChannelConfig {
   /** Feed store the channel writes rows to (host-owned persistence). */
   readonly repository: InAppFeedRepository;
@@ -571,7 +812,7 @@ interface InAppChannelConfig extends ChannelConfig {
    */
   readonly unreadCache?: UnreadCountCache;
 }
-declare class InAppChannel extends BaseChannel<InAppChannelConfig> {
+export declare class InAppChannel extends BaseChannel<InAppChannelConfig> {
   private readonly repository;
   private readonly port;
   private readonly eventName;
@@ -582,8 +823,6 @@ declare class InAppChannel extends BaseChannel<InAppChannelConfig> {
   send(payload: NotificationPayload): Promise<SendResult>;
   private orgOf;
 }
-//#endregion
-//#region src/jobsQueue.d.ts
 interface NotificationsJobOptions {
   /** Job/queue name registered with `jobsPlugin`. Default "notifications". */
   readonly name?: string;
@@ -619,9 +858,7 @@ interface NotificationsJob {
  * `enqueue`/`getJob`/`size` through `fastify.jobs`, keying `enqueue` on
  * `idempotencyKey` so crash-recovery / at-least-once redelivery dedupes.
  */
-declare function notificationsJob(options?: NotificationsJobOptions): NotificationsJob;
-//#endregion
-//#region src/module.d.ts
+export declare function notificationsJob(options?: NotificationsJobOptions): NotificationsJob;
 /**
  * Resolve a trigger's host-typed `audience` selector to concrete recipients —
  * the shared seam so branch-role → members (or team → users, tenant → admins)
@@ -728,13 +965,13 @@ declare module "fastify" {
     notifications?: NotificationService;
   }
 }
-declare function notificationsModule(config: NotificationsModuleConfig): ArcModule<NotificationService>;
+export declare function notificationsModule(config: NotificationsModuleConfig): ArcModule<NotificationService>;
 /**
  * Triggers as arc `eventHandlers` — what `notifyOn` subscribes, exported so a BRIDGE module can own
  * the triggers for one producer (`dependsOn: [producer, "notifications"]`) and vanish with it.
  * `service` is read per dispatch, so a bridge can resolve it from the notifications module's export.
  */
-declare function notifyTriggerHandlers(options: {
+export declare function notifyTriggerHandlers(options: {
   /** Handler-name prefix; arc rejects duplicate handler names across the module graph. */
   readonly name: string;
   readonly service: () => NotificationService;
@@ -742,11 +979,9 @@ declare function notifyTriggerHandlers(options: {
   readonly recipientResolver?: RecipientResolver;
 }): EventHandlerDefinition[];
 /** One event → N sends. Exported for direct unit testing. */
-declare function dispatchTrigger(service: NotificationService, trigger: NotifyTrigger, event: DomainEvent, opts?: {
+export declare function dispatchTrigger(service: NotificationService, trigger: NotifyTrigger, event: DomainEvent, opts?: {
   recipientResolver?: RecipientResolver;
 }): Promise<void>;
-//#endregion
-//#region src/repositoryDeliveryLog.d.ts
 type EntryStatus = DeliveryLogEntry["status"];
 /** The persisted document shape (also what the resource/UI reads). */
 interface DeliveryLogDoc {
@@ -774,21 +1009,54 @@ interface DeliveryLogDoc {
     readonly sourceModel: string;
     readonly sourceId: string;
   };
+  /**
+   * The authored rule (an admin-defined trigger) that produced this delivery, when there
+   * is one. A top-level column — not a `metadata` key — so a store can index it and
+   * {@link RepositoryDeliveryLog.listByRule} is a keyed read.
+   */
+  readonly ruleId?: string;
+  /** Host-typed columns stored verbatim beside the package's own. Never read by the package. */
+  readonly extraFields?: Record<string, unknown>;
 }
-interface RepositoryDeliveryLogOptions {
+interface RepositoryDeliveryLogOptions<TExtra extends Record<string, unknown> = Record<string, unknown>> {
   /** Cap for `query()` when the caller gives no limit. Default 100. */
   readonly defaultLimit?: number;
+  /** Source of the entry `timestamp`. Default real time. */
+  readonly clock?: NotificationClock;
+  /**
+   * Which authored rule a send belongs to. Default: `payload.metadata.ruleId` when it is a
+   * non-empty string. A host whose rule id rides elsewhere (an event name such as
+   * `notify.rule.<id>`) supplies its own resolver.
+   */
+  readonly ruleId?: (payload: NotificationPayload) => string | undefined;
+  /** Host-typed columns to persist on the entry (`DeliveryLogDoc.extraFields`). */
+  readonly extraFields?: (payload: NotificationPayload, dispatch: DispatchResult) => TExtra | undefined;
+}
+/** A delivery entry with the rule and host columns the plain `DeliveryLogEntry` has no slot for. */
+type RuleDeliveryLogEntry<TExtra extends Record<string, unknown> = Record<string, unknown>> = DeliveryLogEntry & {
+  readonly ruleId?: string;
+  readonly extraFields?: TExtra;
+};
+interface DeliveryLogByRuleQuery {
+  /** Cap on rows returned. Falls back to the log's `defaultLimit`. */
+  readonly limit?: number;
+  readonly status?: EntryStatus;
+  readonly after?: Date;
+  readonly before?: Date;
+}
+/** The kernel `DeliveryLog` plus the per-rule read. Assignable wherever a `DeliveryLog` is. */
+interface RepositoryDeliveryLog<TExtra extends Record<string, unknown> = Record<string, unknown>> extends DeliveryLog {
+  /** Newest-first deliveries of ONE authored rule. */
+  listByRule(ruleId: string, query?: DeliveryLogByRuleQuery): Promise<RuleDeliveryLogEntry<TExtra>[]>;
 }
-declare function createRepositoryDeliveryLog(repository: RepositoryLike, options?: RepositoryDeliveryLogOptions): DeliveryLog;
-//#endregion
-//#region src/sseChannel.d.ts
+export declare function createRepositoryDeliveryLog<TExtra extends Record<string, unknown> = Record<string, unknown>>(repository: RepositoryLike, options?: RepositoryDeliveryLogOptions<TExtra>): RepositoryDeliveryLog<TExtra>;
 interface SseChannelConfig extends ChannelConfig {
   /** Host realtime transport (be-prod's SSE manager, a WS hub, ...). */
   readonly port: RealtimePushPort;
   /** SSE event name pushed to the client. Default "notification". */
   readonly eventName?: string;
 }
-declare class SseChannel extends BaseChannel<SseChannelConfig> {
+export declare class SseChannel extends BaseChannel<SseChannelConfig> {
   private readonly port;
   private readonly eventName;
   constructor(config: SseChannelConfig);
@@ -796,8 +1064,6 @@ declare class SseChannel extends BaseChannel<SseChannelConfig> {
   send(payload: NotificationPayload): Promise<SendResult>;
   private orgOf;
 }
-//#endregion
-//#region src/templatesResource.d.ts
 /** Code-defined template map (same shape `createSimpleResolver` accepts). */
 type CodeTemplates = Record<string, {
   readonly subject?: string;
@@ -824,9 +1090,7 @@ interface TemplatesResourceOptions {
   /** Tenant field. Default `false` — templates are company-wide (be-prod convention). */
   readonly tenantField?: string | false;
 }
-declare function templatesResource(options: TemplatesResourceOptions): import("@classytic/arc").ResourceDefinition<unknown>;
-//#endregion
-//#region src/triggerAuthoring.d.ts
+export declare function templatesResource(options: TemplatesResourceOptions): import("@classytic/arc").ResourceDefinition<unknown>;
 /** Who a trigger targets. */
 type NotificationAudienceType = "staff" | "customer";
 /** Direct contact for a customer-facing notification. */
@@ -946,8 +1210,6 @@ interface NotificationTrigger {
    */
   extract: (payload: Record<string, any>) => NotificationExtractResult | null;
 }
-//#endregion
-//#region src/triggerAdapter.d.ts
 /**
  * `entityType` → the `extract` variable holding that entity's id.
  *
@@ -955,7 +1217,7 @@ interface NotificationTrigger {
  * 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>;
+export declare const DEFAULT_ENTITY_ID_VARS: Record<string, string>;
 interface TriggerAdapterOptions {
   /**
    * Extra `entityType` → id-variable mappings, merged over the defaults.
@@ -1051,14 +1313,14 @@ interface TriggerOverrideResolution {
  * 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;
+export 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[];
+export declare function toNotifyTriggers(triggers: readonly NotificationTrigger[], options?: TriggerAdapterOptions): NotifyTrigger[];
 /**
  * First trigger registered for an event.
  *
@@ -1067,20 +1329,18 @@ declare function toNotifyTriggers(triggers: readonly NotificationTrigger[], opti
  * 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;
+export 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[];
+export 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[];
+export 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
+export declare function getRecipientMatrix(triggers: readonly NotificationTrigger[]): Record<string, string[]>;
 /**
  * One trigger as an operator sees it, with the CODE defaults an override replaces.
  *
@@ -1121,5 +1381,4 @@ interface TriggerCatalogEntry {
  * 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, notifyTriggerHandlers, readInAppContent, renderInApp, resolveEffectiveSettings, templatesResource, toNotifyTrigger, toNotifyTriggers };
+export type { CivilDateString, CodeTemplates, CodeTriggerDefaults, CreateCachedTriggerOverrideStoreOptions, CreateUnreadCountCacheOptions, DateRule, DateRuleAudienceResolver, DateRuleCatalogEntry, DateRuleEngine, DateRuleEngineOptions, DateRuleItem, DateRuleLedger, DateRuleLedgerEntry, DateRuleOccurrence, DateRuleSchedule, DateRuleSource, DateRuleSourceQuery, DateRuleSweepResult, DbFirstResolverOptions, DbFirstTemplateResolver, DeliveryLogByRuleQuery, DeliveryLogDoc, EffectiveTriggerSettings, InAppBackfill, InAppBackfillConnect, InAppBackfillOptions, InAppChannelConfig, InAppContent, InAppFeedListOptions, InAppFeedPage, InAppFeedRepository, InAppFeedResourceOptions, InAppFeedRow, InAppFeedScope, InAppPriority, InAppTemplate, NotificationAudienceType, NotificationChannel, NotificationChannelCatalog, NotificationClock, NotificationDecision, NotificationExtractResult, NotificationRecipientContact, NotificationSkipReason, NotificationTrigger, NotificationTriggerOverrideDoc, NotificationsJob, NotificationsJobOptions, NotificationsModuleConfig, NotifyTrigger, RealtimePushPort, RecipientResolver, RepositoryDeliveryLog, RepositoryDeliveryLogOptions, RuleDeliveryLogEntry, SseChannelConfig, StoredTemplate, TemplateStore, TemplatesResourceOptions, TriggerAdapterOptions, TriggerCatalogEntry, TriggerCatalogPort, TriggerOverrideLoader, TriggerOverrideResolution, TriggerOverrideStore, UnreadCountCache };