@classytic/arc-notifications 0.1.0

package/README.md

@@ -0,0 +1,152 @@
+# @classytic/arc-notifications
+
+The blessed seam from `@classytic/arc` domain events to `@classytic/notifications`.
+Every arc app used to re-derive the same 40 lines — build a `NotificationService`,
+subscribe `app.events`, map event payloads to recipients, thread idempotency for
+at-least-once transports, expose a template-drafting admin surface. This package
+is that wiring, once.
+
+```bash
+npm i @classytic/arc-notifications @classytic/notifications
+# peers: @classytic/arc >=2.20, @classytic/primitives >=0.9, @classytic/repo-core >=0.7
+```
+
+## Three pieces
+
+### 1. `notificationsModule` — events → notifications
+
+Composed into `createApp({ modules })`. Declarative `notifyOn` triggers subscribe
+arc's event bus through `subscribeWithBoundary` (fire-and-forget; handler failures
+logged, not thrown), with idempotency keys defaulted from event identity so
+at-least-once redelivery never double-sends.
+
+```ts
+import { createApp } from "@classytic/arc/factory";
+import { getModuleExports } from "@classytic/arc/factory";
+import { notificationsModule, createDbFirstResolver } from "@classytic/arc-notifications";
+import { EmailChannel } from "@classytic/notifications";
+
+const app = await createApp({
+  modules: [
+    notificationsModule({
+      channels: [new EmailChannel({ from: "App <no-reply@app.com>", transport: smtp })],
+      templates: createDbFirstResolver({ store: templateStore, fallback: codeTemplates }),
+      notifyOn: [
+        {
+          event: "approval.requested",                        // arc event pattern (wildcards ok)
+          template: "approval-requested",
+          recipient: (e) => directory.contact(e.payload.approverId),
+          data: (e) => ({ title: e.payload.title, link: `/approvals/${e.payload.id}` }),
+          channels: ["email"],
+        },
+      ],
+    }),
+  ],
+});
+
+// service is decorated + exported
+app.notifications?.send({ event: "manual", template: "welcome", recipient: { email }, data: {} });
+const svc = getModuleExports<NotificationService>(app, "notifications");
+```
+
+A `notifyOn` trigger declared without arc's `eventPlugin` registered **fails at
+boot** (not silently at delivery time).
+
+### 2. `createDbFirstResolver` — runtime-draftable templates
+
+Admins draft templates at runtime; an **active** DB row wins over the code-defined
+fallback, and a store outage falls back to code (transactional email never stops).
+60s read-through cache, invalidated by the templates resource on save.
+
+```ts
+const resolver = createDbFirstResolver({
+  store: { getByKey: (key) => templateRepo.getByKey(key) }, // any by-key lookup
+  fallback: createSimpleResolver(codeTemplates),            // from @classytic/notifications
+  cacheTtlMs: 60_000,
+});
+```
+
+### 3. `templatesResource` — the drafting surface
+
+A normal arc resource over any `RepositoryLike` (mongokit / sqlitekit / prismakit /
+custom) — no kit adapter needed. Fail-closed: every op + route takes one `permissions`
+gate. Mounts admin CRUD plus `GET /defaults` (code templates to customize from) and
+`POST /preview` (stateless draft render). Write hooks invalidate the resolver cache so
+a saved draft applies within one request.
+
+```ts
+templatesResource({
+  repository: templateRepo,
+  permissions: platformAdminOnly(),
+  defaults: codeTemplates,
+  resolver, // the createDbFirstResolver instance — its cache is invalidated on save
+});
+```
+
+### 4. Durable dispatch — crash-safe bulk sends (10k+)
+
+The service's default queue is in-memory: a 10k birthday/newsletter send that
+crashes at #4000 loses the rest. **There is one durable path — arc's jobs
+plugin.** arc-notifications does not own a queue; background work in arc goes
+through `@classytic/arc/integrations/jobs` (an `fp()` plugin that decorates
+`fastify.jobs`, owns the BullMQ queues/workers, and adds an arc-level semaphore,
+cron reconciliation, event bridging, dead-letter queues, `GET /jobs/:id/status`,
+and `onClose` teardown). The bridge routes sends through it — so a durable
+notification send reuses the *same* job subsystem the rest of your app already
+runs. No second BullMQ, no second connection pool.
+
+```ts
+import { jobsPlugin } from "@classytic/arc/integrations/jobs";
+import { notificationsJob, notificationsModule, createRepositoryDeliveryLog } from "@classytic/arc-notifications";
+
+const notify = notificationsJob({ concurrency: 5, rateLimit: { max: 10, duration: 1000 } });
+
+await createApp({
+  plugins: async (f) => f.register(jobsPlugin, { connection: redis, jobs: [notify.job] }),
+  modules: [
+    notificationsModule({
+      channels: [new EmailChannel({ from, transport })],
+      queue: (f) => notify.toQueueAdapter(f.jobs),   // resolved at bootstrap — fastify.jobs exists by then
+      deliveryLog: createRepositoryDeliveryLog(deliveryRepo),
+      notifyOn: [ /* ... */ ],
+    }),
+  ],
+});
+```
+
+**Works without Redis** — just don't wire the queue: omit `queue` (and don't
+register `jobsPlugin`) and sends run on the service's in-memory queue. The module
+warns loudly at boot if you declare `notifyOn` triggers without a durable queue, so
+"in-memory in production" is never silent.
+
+**Why a queue, not a workflow engine:** a bulk send is a fan-out, not a multi-step
+workflow. One durable job **per recipient** (never one job for 10k) keyed by
+`idempotencyKey` (→ BullMQ `jobId` via `fastify.jobs`, so crash-recovery redelivery
+is a no-op, not a duplicate). Streamline (a workflow engine) is the right tool only
+when the campaign itself has steps/waits/approval gates — it would then orchestrate
+and delegate the sending to the jobs plugin exactly like this.
+
+**Durability levels:** in-memory → lost on crash (dev only). `fastify.jobs` (BullMQ)
+→ survives app crashes (add Redis AOF for Redis-crash safety). Plus a persistent
+`DeliveryLog` → observable + resumable (query the failed set, re-drive only those).
+
+**Composing with arc's outbox (strongest).** The outbox and the queue are
+*different* layers and compose — they are not merged. Arc's `EventOutbox` guarantees
+the domain *event* survives (transactional same-DB-txn write + relay); the jobs
+queue guarantees the *send* survives. Wire the trigger to an outbox-relayed event and
+the whole chain is at-least-once end to end: `business write + outbox event (one txn)`
+→ `relay → event bus` → `notifyOn fires` → `durable send`. `idempotencyKey` (defaulted
+from event identity) dedupes the at-least-once overlap at both hops.
+
+BullMQ is a peer of arc's jobs plugin, not of arc-notifications — this package has no
+direct queue dependency.
+
+## Design rules
+
+- Channels and stores come from `@classytic/notifications` (peer) — this package
+  adds the arc-native durable `QueueAdapter` and repo-backed `DeliveryLog`, plus the
+  event seam and templates; it never re-exports notifications' channels.
+- One-way dependency: `@classytic/arc` never depends on this package.
+
+Generalized from be-prod's production `shared/notifications` (db-first resolver) +
+`resources/notifications` (email-template model, admin resource, event-trigger registry).

package/dist/index.d.mts

@@ -0,0 +1,187 @@
+import { DeliveryLog, DeliveryLogEntry, NotificationPayload, NotificationService, NotificationServiceConfig, QueueAdapter, Recipient, SendResult, TemplateResolver } from "@classytic/notifications";
+import { JobDefinition, JobDispatcher } from "@classytic/arc/integrations/jobs";
+import { ArcModule } from "@classytic/arc/factory";
+import { DomainEvent } from "@classytic/primitives/events";
+import { FastifyInstance } from "fastify";
+import { RepositoryLike } from "@classytic/repo-core/adapter";
+import { PermissionCheck } from "@classytic/arc/permissions";
+
+//#region src/dbFirstResolver.d.ts
+/** One draftable template row — the shape be-prod's EmailTemplate model proved. */
+interface StoredTemplate {
+  readonly key: string;
+  readonly subject?: string;
+  readonly html?: string;
+  readonly text?: string;
+  /** Inactive rows are ignored (fall back to code templates). Default: active. */
+  readonly isActive?: boolean;
+  readonly [extra: string]: unknown;
+}
+/** Structural store port — any repository with a by-key lookup satisfies it. */
+interface TemplateStore {
+  getByKey(key: string): Promise<StoredTemplate | null>;
+}
+interface DbFirstResolverOptions {
+  readonly store: TemplateStore;
+  /**
+   * Code-defined resolver consulted when the store has no ACTIVE row for the
+   * key, or when the store errors (fail-open — a template-DB outage must not
+   * stop transactional email). Without a fallback, a miss throws.
+   */
+  readonly fallback?: TemplateResolver;
+  /** Read-through cache TTL. Default 60s (be-prod's window). `0` disables. */
+  readonly cacheTtlMs?: number;
+  /** Forwarded to the renderer: HTML-escape interpolated values in `html`. Default true. */
+  readonly escape?: boolean;
+  /** Observe store failures (they otherwise silently fall back). */
+  readonly onError?: (err: unknown, templateId: string) => void;
+}
+/** The resolver, plus cache invalidation for template-resource write hooks. */
+interface DbFirstTemplateResolver {
+  (templateId: string, data: Record<string, unknown>): ReturnType<TemplateResolver> | Promise<Awaited<ReturnType<TemplateResolver>>>;
+  /** 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/jobsQueue.d.ts
+interface NotificationsJobOptions {
+  /** Job/queue name registered with `jobsPlugin`. Default "notifications". */
+  readonly name?: string;
+  /** Retries per send. Default 3 (arc's job default). */
+  readonly retries?: number;
+  /** Worker concurrency (parallel sends). */
+  readonly concurrency?: number;
+  /** Per-worker rate limit — match your ESP tier. */
+  readonly rateLimit?: {
+    max: number;
+    duration: number;
+  };
+  /** Backoff strategy. Default exponential 1000ms. */
+  readonly backoff?: {
+    type: "exponential" | "fixed";
+    delay: number;
+  };
+  /**
+   * arc-level semaphore — max simultaneous handler runs when the constraint is
+   * a downstream resource (ESP connection cap), distinct from BullMQ concurrency.
+   */
+  readonly maxConcurrent?: number;
+}
+interface NotificationsJob {
+  /** Register this with `jobsPlugin({ jobs: [...] })` in the plugins phase. */
+  readonly job: JobDefinition<NotificationPayload>;
+  /** Build the `QueueAdapter` bound to the host's `fastify.jobs`. */
+  toQueueAdapter(dispatcher: JobDispatcher): QueueAdapter;
+}
+/**
+ * Create the notifications job + its `QueueAdapter` factory. The job delegates
+ * to the notification service's processor (attached later); the adapter routes
+ * `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
+interface NotifyTrigger<TPayload = unknown> {
+  /** Event pattern to subscribe (wildcards per arc's `matchEventPattern`). */
+  readonly event: string;
+  /** Template id. Default: the concrete event type. */
+  readonly template?: string;
+  /** Restrict to specific channel names. Omit = all matching channels. */
+  readonly channels?: readonly string[];
+  /**
+   * Map the event to recipient(s). Return `null`/`undefined`/`[]` to skip
+   * (the filter seam — "payment failed only", "opted-in users only", ...).
+   */
+  readonly recipient: (event: DomainEvent<TPayload>) => Recipient | readonly Recipient[] | null | undefined | Promise<Recipient | readonly Recipient[] | null | undefined>;
+  /** Template variables. Default: the event payload (when object-shaped). */
+  readonly data?: (event: DomainEvent<TPayload>) => Record<string, unknown> | Promise<Record<string, unknown>>;
+  /**
+   * Dedup key for at-least-once transports. Default:
+   * `meta.idempotencyKey ?? "<type>:<meta.id>"`, suffixed per recipient on
+   * fan-out. Return `undefined` to disable dedup for this trigger.
+   */
+  readonly idempotencyKey?: (event: DomainEvent<TPayload>) => string | undefined;
+  /** Compose-time kill switch (env-gated triggers). Default true. */
+  readonly enabled?: boolean;
+}
+interface NotificationsModuleConfig extends Omit<NotificationServiceConfig, "queue"> {
+  /** 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`. */
+  readonly notifyOn?: readonly NotifyTrigger[];
+  /** Decorate `fastify.<name>` with the service. Default "notifications"; `false` to skip. */
+  readonly decorate?: string | false;
+  /**
+   * Queue backing. Either a ready `QueueAdapter`, or a resolver that receives
+   * the booted Fastify instance — use the function form for the `fastify.jobs`
+   * bridge (`(f) => notificationsJob(...).toQueueAdapter(f.jobs)`), since
+   * `fastify.jobs` only exists after the plugins phase. Omit for the service's
+   * in-memory default.
+   */
+  readonly queue?: QueueAdapter | ((fastify: FastifyInstance) => QueueAdapter);
+}
+declare module "fastify" {
+  interface FastifyInstance {
+    /** Populated by `notificationsModule` (default `decorate` name). */
+    notifications?: NotificationService;
+  }
+}
+declare function notificationsModule(config: NotificationsModuleConfig): ArcModule<NotificationService>;
+/** One event → N sends. Exported for direct unit testing. */
+declare function dispatchTrigger(service: NotificationService, trigger: NotifyTrigger, event: DomainEvent): Promise<void>;
+//#endregion
+//#region src/repositoryDeliveryLog.d.ts
+type EntryStatus = DeliveryLogEntry["status"];
+/** The persisted document shape (also what the resource/UI reads). */
+interface DeliveryLogDoc {
+  readonly id?: string;
+  readonly timestamp: Date;
+  readonly event: string;
+  readonly recipientId?: string;
+  readonly recipientEmail?: string;
+  readonly channels: string[];
+  readonly results: SendResult[];
+  readonly status: EntryStatus;
+  readonly duration: number;
+  readonly metadata?: Record<string, unknown>;
+}
+interface RepositoryDeliveryLogOptions {
+  /** Cap for `query()` when the caller gives no limit. Default 100. */
+  readonly defaultLimit?: number;
+}
+declare function createRepositoryDeliveryLog(repository: RepositoryLike, options?: RepositoryDeliveryLogOptions): DeliveryLog;
+//#endregion
+//#region src/templatesResource.d.ts
+/** Code-defined template map (same shape `createSimpleResolver` accepts). */
+type CodeTemplates = Record<string, {
+  readonly subject?: string;
+  readonly html?: string;
+  readonly text?: string;
+}>;
+interface TemplatesResourceOptions {
+  /** Repository over the templates collection/table. */
+  readonly repository: RepositoryLike;
+  /**
+   * One gate for every operation (CRUD + routes) — template drafting is an
+   * admin surface; be-prod runs it platform-admin-only. REQUIRED: an omitted
+   * permission would mount public template editing.
+   */
+  readonly permissions: PermissionCheck;
+  /** Resource name. Default "notification-template". */
+  readonly name?: string;
+  /** Route prefix. Default "/notifications/templates". */
+  readonly prefix?: string;
+  /** Code-defined templates surfaced by `GET /defaults` (the customize-from list). */
+  readonly defaults?: CodeTemplates;
+  /** Live resolver — write hooks invalidate its cache so drafts apply within one save. */
+  readonly resolver?: Pick<DbFirstTemplateResolver, "invalidate">;
+  /** 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
+export { type CodeTemplates, type DbFirstResolverOptions, type DbFirstTemplateResolver, type DeliveryLogDoc, type NotificationsJob, type NotificationsJobOptions, type NotificationsModuleConfig, type NotifyTrigger, type RepositoryDeliveryLogOptions, type StoredTemplate, type TemplateStore, type TemplatesResourceOptions, createDbFirstResolver, createRepositoryDeliveryLog, dispatchTrigger, notificationsJob, notificationsModule, templatesResource };

package/dist/index.mjs

@@ -0,0 +1,429 @@
+import { NotificationService, createSimpleResolver } from "@classytic/notifications";
+import { defineJob } from "@classytic/arc/integrations/jobs";
+import { subscribeWithBoundary } from "@classytic/arc/events";
+import { defineModule } from "@classytic/arc/factory";
+import { defineResource } from "@classytic/arc";
+//#region src/dbFirstResolver.ts
+/**
+* DB-first template resolver — generalized from be-prod's proven
+* `createDbFirstResolver` (shared/notifications). Templates are DRAFTABLE at
+* runtime: an active DB row for a template key wins; anything else falls back
+* to the code-defined resolver, so a bad draft can never take sends down.
+*
+* Storage-agnostic: `TemplateStore` is a one-method structural port
+* (`getByKey`) satisfied by any kit repository or hand-rolled lookup.
+*/
+function createDbFirstResolver(options) {
+	const { store, fallback, cacheTtlMs = 6e4, escape: escapeHtml = true, onError } = options;
+	const cache = /* @__PURE__ */ new Map();
+	const lookup = async (key) => {
+		if (cacheTtlMs > 0) {
+			const hit = cache.get(key);
+			if (hit && Date.now() - hit.at < cacheTtlMs) return hit.doc;
+		}
+		const doc = await store.getByKey(key);
+		if (cacheTtlMs > 0) cache.set(key, {
+			doc,
+			at: Date.now()
+		});
+		return doc;
+	};
+	const resolver = (async (templateId, data) => {
+		let doc = null;
+		try {
+			doc = await lookup(templateId);
+		} catch (err) {
+			onError?.(err, templateId);
+			if (!fallback) throw err;
+			doc = null;
+		}
+		if (doc && doc.isActive !== false) return createSimpleResolver({ [templateId]: {
+			...doc.subject !== void 0 ? { subject: doc.subject } : {},
+			...doc.html !== void 0 ? { html: doc.html } : {},
+			...doc.text !== void 0 ? { text: doc.text } : {}
+		} }, { escape: escapeHtml })(templateId, data);
+		if (!fallback) throw new Error(`[arc-notifications] template "${templateId}" has no active store row and no fallback resolver is configured.`);
+		return fallback(templateId, data);
+	});
+	resolver.invalidate = (key) => {
+		if (key === void 0) cache.clear();
+		else cache.delete(key);
+	};
+	return resolver;
+}
+//#endregion
+//#region src/jobsQueue.ts
+/**
+* `fastify.jobs` bridge — reuse arc's job subsystem instead of standing up a
+* second one.
+*
+* arc already ships a proper Fastify jobs plugin (`@classytic/arc/integrations/jobs`):
+* an `fp()`-wrapped plugin that decorates `fastify.jobs`, owns the BullMQ
+* queues/workers, and adds an arc-level semaphore, cron reconciliation, event
+* bridging, dead-letter queues, a `GET /jobs/:id/status` endpoint, and
+* `onClose` teardown. A host using that plugin should NOT also run
+* `createDurableQueue` (a parallel BullMQ setup with its own connection pool
+* and workers). This bridge maps the notifications `QueueAdapter` onto the
+* host's existing `fastify.jobs`, so sends flow through the one job subsystem.
+*
+* ```ts
+* import { jobsPlugin } from "@classytic/arc/integrations/jobs";
+* import { notificationsJob, notificationsModule } from "@classytic/arc-notifications";
+*
+* const notify = notificationsJob({ concurrency: 5, rateLimit: { max: 10, duration: 1000 } });
+*
+* await createApp({
+*   plugins: async (f) => f.register(jobsPlugin, { connection: redis, jobs: [notify.job] }),
+*   modules: [
+*     notificationsModule({
+*       channels: [...],
+*       queue: (f) => notify.toQueueAdapter(f.jobs),   // resolved at bootstrap
+*       notifyOn: [...],
+*     }),
+*   ],
+* });
+* ```
+*
+* The job's handler and the notification processor are wired through a shared
+* closure ref: `notificationsJob()` registers the job with `jobsPlugin` in the
+* plugins phase (handler known up front), and the service attaches its
+* processor later via `queue.process()`. By the time a job actually runs the
+* ref is set — a boot-phase enqueue before attach is the only error case.
+*/
+function mapState(state) {
+	switch (state) {
+		case "active": return "processing";
+		case "completed": return "completed";
+		case "failed": return "failed";
+		default: return "pending";
+	}
+}
+/**
+* Create the notifications job + its `QueueAdapter` factory. The job delegates
+* to the notification service's processor (attached later); the adapter routes
+* `enqueue`/`getJob`/`size` through `fastify.jobs`, keying `enqueue` on
+* `idempotencyKey` so crash-recovery / at-least-once redelivery dedupes.
+*/
+function notificationsJob(options = {}) {
+	const { name = "notifications", retries = 3, concurrency, rateLimit, backoff, maxConcurrent } = options;
+	const ref = {};
+	const job = defineJob({
+		name,
+		retries,
+		...concurrency !== void 0 ? { concurrency } : {},
+		...rateLimit ? { rateLimit } : {},
+		...backoff ? { backoff } : {},
+		...maxConcurrent !== void 0 ? { maxConcurrent } : {},
+		handler: async (data) => {
+			if (!ref.processor) throw new Error("[arc-notifications] notifications job fired before the service attached its processor — ensure the notificationsModule using this job is composed in the same app.");
+			await ref.processor(data);
+		}
+	});
+	const toQueueAdapter = (dispatcher) => ({
+		async enqueue(payload, opts) {
+			const { jobId } = await dispatcher.dispatch(name, payload, {
+				...payload.idempotencyKey ? { jobId: payload.idempotencyKey } : {},
+				...opts?.delay ? { delay: opts.delay } : {}
+			});
+			return jobId;
+		},
+		process(processor) {
+			ref.processor = processor;
+		},
+		async getJob(id) {
+			const status = await dispatcher.getStatus(id);
+			if (!status) return null;
+			const created = new Date(status.timestamp ?? Date.now());
+			return {
+				id: status.id,
+				payload: {
+					event: status.name,
+					recipient: {},
+					data: {}
+				},
+				status: mapState(status.state),
+				attempts: 0,
+				maxAttempts: retries,
+				retryDelay: backoff?.delay ?? 1e3,
+				maxRetryDelay: 3e4,
+				createdAt: created,
+				updatedAt: new Date(status.finishedOn ?? status.processedOn ?? created.getTime()),
+				...status.failedReason ? { error: status.failedReason } : {}
+			};
+		},
+		async size() {
+			const q = (await dispatcher.getStats())[name];
+			return q ? q.waiting + q.active + q.delayed : 0;
+		},
+		pause() {},
+		resume() {},
+		drain() {}
+	});
+	return {
+		job,
+		toQueueAdapter
+	};
+}
+//#endregion
+//#region src/module.ts
+/**
+* `notificationsModule` — the blessed seam from arc domain events to
+* user-facing notifications.
+*
+* Every arc app used to re-derive the same wiring: build a
+* NotificationService, subscribe `app.events`, map event payloads to
+* recipients, thread idempotency for at-least-once transports. This module is
+* that wiring, once:
+*
+* ```ts
+* const app = await createApp({
+*   modules: [
+*     notificationsModule({
+*       channels: [new EmailChannel({ from, transport })],
+*       templates: createDbFirstResolver({ store, fallback }),
+*       notifyOn: [{
+*         event: "approval.requested",
+*         template: "approval-requested",
+*         recipient: (e) => directory.contact(e.payload.approverId),
+*         data: (e) => ({ title: e.payload.title }),
+*       }],
+*     }),
+*   ],
+* });
+* app.notifications?.send({ ... });                       // decorated service
+* const svc = getModuleExports<NotificationService>(app, "notifications");
+* ```
+*
+* Triggers subscribe through arc's `subscribeWithBoundary` — handler failures
+* are logged and swallowed (fire-and-forget, matching arc's event gotcha), and
+* `idempotencyKey` defaults from event identity because Redis Streams are
+* at-least-once: redelivery must not double-send.
+*/
+function notificationsModule(config) {
+	const { name = "notifications", service: provided, notifyOn = [], decorate = "notifications", queue, ...serviceConfig } = config;
+	let service;
+	const unsubscribes = [];
+	return defineModule({
+		name,
+		bootstrap(fastify) {
+			const resolvedQueue = typeof queue === "function" ? queue(fastify) : queue;
+			service = provided ?? new NotificationService({
+				...serviceConfig,
+				...resolvedQueue ? { queue: resolvedQueue } : {}
+			});
+			if (!resolvedQueue && !provided && notifyOn.some((t) => t.enabled !== false)) fastify.log.warn(`[arc-notifications] module "${name}" wires notifyOn trigger(s) with NO durable queue — sends run on the in-memory queue and are lost on restart / not shared across instances. Wire \`queue: (f) => notificationsJob(...).toQueueAdapter(f.jobs)\` (with arc's jobsPlugin) for durability.`);
+			if (decorate !== false && !(decorate in fastify)) fastify.decorate(decorate, service);
+			return service;
+		},
+		async afterResources(fastify) {
+			const triggers = notifyOn.filter((t) => t.enabled !== false);
+			if (triggers.length === 0) return;
+			const bus = fastify;
+			if (!bus.events) throw new Error(`[arc-notifications] module "${name}" declares ${triggers.length} notifyOn trigger(s) but \`fastify.events\` is not decorated — register arc's eventPlugin (or drop notifyOn).`);
+			for (const trigger of triggers) {
+				const unsubscribe = await subscribeWithBoundary(bus, trigger.event, async (event) => dispatchTrigger(service, trigger, event), { name: `arc-notifications:${trigger.event}` });
+				unsubscribes.push(unsubscribe);
+			}
+			fastify.log.debug(`[arc-notifications] ${triggers.length} trigger(s) subscribed`);
+		},
+		async onClose() {
+			for (const unsubscribe of unsubscribes) unsubscribe();
+			unsubscribes.length = 0;
+		}
+	});
+}
+/** One event → N sends. Exported for direct unit testing. */
+async function dispatchTrigger(service, trigger, event) {
+	const resolved = await trigger.recipient(event);
+	if (!resolved) return;
+	const recipients = Array.isArray(resolved) ? resolved : [resolved];
+	if (recipients.length === 0) return;
+	const payload = event.payload;
+	const data = await trigger.data?.(event) ?? (payload !== null && typeof payload === "object" && !Array.isArray(payload) ? payload : {});
+	const baseKey = trigger.idempotencyKey ? trigger.idempotencyKey(event) : event.meta.idempotencyKey ?? `${event.type}:${event.meta.id}`;
+	for (const [index, recipient] of recipients.entries()) {
+		const idempotencyKey = baseKey === void 0 ? void 0 : recipients.length === 1 ? baseKey : `${baseKey}:${recipient.id ?? recipient.email ?? index}`;
+		await service.send({
+			event: event.type,
+			template: trigger.template ?? event.type,
+			recipient,
+			data,
+			...trigger.channels ? { channels: [...trigger.channels] } : {},
+			...idempotencyKey !== void 0 ? { idempotencyKey } : {},
+			metadata: {
+				source: "arc-notifications",
+				eventId: event.meta.id
+			}
+		});
+	}
+}
+//#endregion
+//#region src/repositoryDeliveryLog.ts
+function deriveStatus(dispatch) {
+	if (dispatch.sent > 0 && dispatch.failed === 0) return "delivered";
+	if (dispatch.sent > 0 && dispatch.failed > 0) return "partial";
+	if (dispatch.failed > 0) return "failed";
+	return "skipped";
+}
+function toEntry(doc) {
+	return {
+		id: String(doc.id ?? doc._id ?? ""),
+		timestamp: doc.timestamp instanceof Date ? doc.timestamp : new Date(doc.timestamp),
+		event: doc.event,
+		...doc.recipientId ? { recipientId: doc.recipientId } : {},
+		...doc.recipientEmail ? { recipientEmail: doc.recipientEmail } : {},
+		channels: doc.channels ?? [],
+		results: doc.results ?? [],
+		status: doc.status,
+		duration: doc.duration ?? 0,
+		...doc.metadata ? { metadata: doc.metadata } : {}
+	};
+}
+function createRepositoryDeliveryLog(repository, options = {}) {
+	const { defaultLimit = 100 } = options;
+	return {
+		async record(payload, dispatch) {
+			const doc = {
+				timestamp: /* @__PURE__ */ new Date(),
+				event: payload.event,
+				...payload.recipient.id ? { recipientId: payload.recipient.id } : {},
+				...payload.recipient.email ? { recipientEmail: payload.recipient.email } : {},
+				channels: dispatch.results.map((r) => r.channel),
+				results: dispatch.results,
+				status: deriveStatus(dispatch),
+				duration: dispatch.duration,
+				...payload.metadata ? { metadata: payload.metadata } : {}
+			};
+			await repository.create(doc);
+		},
+		async query(filter) {
+			const equality = {};
+			if (filter.recipientId) equality.recipientId = filter.recipientId;
+			if (filter.recipientEmail) equality.recipientEmail = filter.recipientEmail;
+			if (filter.event) equality.event = filter.event;
+			if (filter.status) equality.status = filter.status;
+			const limit = filter.limit ?? defaultLimit;
+			const result = await repository.getAll({
+				filter: equality,
+				limit
+			}, void 0);
+			let entries = (Array.isArray(result) ? result : result.data ?? []).map((r) => toEntry(r));
+			const { after, before, channel } = filter;
+			if (after) entries = entries.filter((e) => e.timestamp >= after);
+			if (before) entries = entries.filter((e) => e.timestamp <= before);
+			if (channel) entries = entries.filter((e) => e.channels.includes(channel));
+			return entries.slice(0, limit);
+		},
+		async get(id) {
+			const doc = await repository.getById(id);
+			return doc ? toEntry(doc) : null;
+		}
+	};
+}
+//#endregion
+//#region src/templatesResource.ts
+/**
+* `templatesResource` — DB-draftable notification templates as a normal arc
+* resource. Generalized from be-prod's email-template resource: admins draft
+* subject/html/text rows keyed by template id; the DB-first resolver picks up
+* ACTIVE rows over code defaults; `/defaults` lists the code templates a UI
+* can "customize into" a row; `/preview` renders a draft statelessly.
+*
+* Kit-less: pass any `RepositoryLike` (mongokit/sqlitekit/prismakit/custom) —
+* the resource is built on a plain `{ type: 'custom' }` adapter.
+*/
+function templatesResource(options) {
+	const { repository, permissions, name = "notification-template", prefix = "/notifications/templates", defaults = {}, resolver, tenantField = false } = options;
+	const invalidateFrom = (ctx) => {
+		const key = ctx.data?.key;
+		if (typeof key === "string") resolver?.invalidate(key);
+		else resolver?.invalidate();
+	};
+	return defineResource({
+		name,
+		prefix,
+		tenantField,
+		adapter: {
+			type: "custom",
+			name: `${name}-store`,
+			repository
+		},
+		permissions: {
+			list: permissions,
+			get: permissions,
+			create: permissions,
+			update: permissions,
+			delete: permissions
+		},
+		schemaOptions: { fieldRules: {
+			key: {
+				type: "string",
+				required: true,
+				immutable: true,
+				pattern: "^[a-z0-9_-]+$",
+				maxLength: 100,
+				description: "Template id this row overrides (matches notify()/notifyOn template)."
+			},
+			subject: {
+				type: "string",
+				required: true,
+				maxLength: 300
+			},
+			html: {
+				type: "string",
+				required: true,
+				maxLength: 1e5
+			},
+			text: {
+				type: "string",
+				maxLength: 2e4
+			},
+			description: {
+				type: "string",
+				maxLength: 500
+			},
+			variables: {
+				type: "array",
+				description: "UI hint — variable names the template interpolates. Not enforced."
+			},
+			isActive: {
+				type: "boolean",
+				default: true,
+				description: "Inactive rows fall back to the code-defined template."
+			}
+		} },
+		hooks: {
+			afterCreate: invalidateFrom,
+			afterUpdate: invalidateFrom,
+			afterDelete: () => resolver?.invalidate()
+		},
+		routes: [{
+			method: "GET",
+			path: "/defaults",
+			permissions,
+			summary: "Code-defined templates available to customize into DB rows",
+			handler: async () => ({ data: Object.entries(defaults).map(([key, t]) => ({
+				key,
+				subject: t.subject ?? "",
+				hasHtml: t.html !== void 0,
+				hasText: t.text !== void 0,
+				source: "code"
+			})) })
+		}, {
+			method: "POST",
+			path: "/preview",
+			permissions,
+			summary: "Stateless render of a draft (subject/html/text + sample data)",
+			handler: async (ctx) => {
+				const body = ctx.body ?? {};
+				return { data: await createSimpleResolver({ preview: {
+					...body.subject !== void 0 ? { subject: body.subject } : {},
+					...body.html !== void 0 ? { html: body.html } : {},
+					...body.text !== void 0 ? { text: body.text } : {}
+				} })("preview", body.data ?? {}) };
+			}
+		}]
+	});
+}
+//#endregion
+export { createDbFirstResolver, createRepositoryDeliveryLog, dispatchTrigger, notificationsJob, notificationsModule, templatesResource };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@classytic/arc-notifications",
+  "version": "0.1.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": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "prepublishOnly": "node ../../scripts/prepublish-gate.mjs"
+  },
+  "peerDependencies": {
+    "@classytic/arc": ">=2.20.0",
+    "@classytic/notifications": ">=2.2.0",
+    "@classytic/primitives": ">=0.9.0",
+    "@classytic/repo-core": ">=0.7.0"
+  },
+  "keywords": [
+    "arc",
+    "fastify",
+    "notifications",
+    "email",
+    "templates",
+    "classytic"
+  ],
+  "license": "MIT",
+  "author": "Classytic",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/classytic/arc-ecosystem.git",
+    "directory": "packages/arc-notifications"
+  }
+}