@classytic/arc-notifications 0.1.0 → 0.3.0

package/README.md

@@ -11,7 +11,7 @@ npm i @classytic/arc-notifications @classytic/notifications
 # peers: @classytic/arc >=2.20, @classytic/primitives >=0.9, @classytic/repo-core >=0.7
 ```
 
-## Three pieces
+## The pieces
 
 ### 1. `notificationsModule` — events → notifications
 
@@ -83,7 +83,54 @@ templatesResource({
 });
 ```
 
-### 4. Durable dispatch — crash-safe bulk sends (10k+)
+### 4. In-app feed + realtime — the full inbox lifecycle
+
+`InAppChannel` persists notifications into a host-owned feed repository;
+`inAppFeedResource` is the inbox REST surface (list / unread-count / mark-read /
+mark-all-read, plus `DELETE /:id` when the repository implements `delete`).
+Grounded against Puter's NotificationService — the lifecycle pieces a bare
+"push to a socket" setup lacks:
+
+```ts
+import {
+  InAppChannel, inAppFeedResource,
+  createUnreadCountCache, createInAppBackfill,
+} from "@classytic/arc-notifications";
+
+const unreadCache = createUnreadCountCache();       // badge count — hottest query, now cached
+const port = mySseHub;                              // host-owned RealtimePushPort
+
+const channel = new InAppChannel({
+  repository: feedRepo,
+  port,          // combined mode: push AFTER persist, WITH the row id on the wire
+  unreadCache,   // new rows move the badge immediately
+});
+
+const feed = inAppFeedResource({
+  repository: feedRepo,
+  resolveScope: (req) => ({ userId: ..., organizationId: ... }),
+  permissions: requireAuth(),
+  port,          // mark-read/-all/delete push "notification:read" → other tabs sync instantly
+  unreadCache,   // GET /unread-count reads through the shared cache
+});
+
+// Reconnect catch-up: push everything persisted while the user was offline.
+// Requires feedRepo.claimUndelivered (ATOMIC fetch-and-mark-delivered).
+const backfill = createInAppBackfill({ repository: feedRepo, port });
+sseHub.onConnect((userId, orgId) => backfill.onConnect(userId, orgId)); // debounced 2s (multi-tab)
+```
+
+- **Combined mode over a separate `SseChannel`** when you persist: the kernel
+  dispatches channels in parallel, so only persist-then-push can carry the feed-row
+  `id` — which is what lets a live toast be marked read without a refetch.
+  `SseChannel` remains for realtime-only setups.
+- **Delivered ≠ read.** `claimUndelivered` tracks "has any client received this
+  over realtime" (backfill's axis); the read flag tracks the user's action (the
+  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/`.
+
+### 5. 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

package/dist/index.d.mts

@@ -1,11 +1,220 @@
-import { DeliveryLog, DeliveryLogEntry, NotificationPayload, NotificationService, NotificationServiceConfig, QueueAdapter, Recipient, SendResult, TemplateResolver } from "@classytic/notifications";
+import { BaseChannel, ChannelConfig, DeliveryLog, DeliveryLogEntry, NotificationPayload, NotificationService, NotificationServiceConfig, QueueAdapter, Recipient, SendResult, TemplateResolver } from "@classytic/notifications";
 import { JobDefinition, JobDispatcher } from "@classytic/arc/integrations/jobs";
 import { ArcModule } from "@classytic/arc/factory";
+import { PermissionCheck } from "@classytic/arc/permissions";
+import { FastifyInstance, FastifyRequest } from "fastify";
 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/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
+ * channel + the realtime/SSE channel).
+ *
+ * A trigger declares an {@link InAppTemplate} (title/message/link/... with
+ * `{var}` placeholders). `dispatchTrigger` interpolates it ONCE per event
+ * against the trigger's `data`, then parks the rendered {@link InAppContent} on
+ * `payload.data[INAPP_DATA_KEY]`. Both in-app channels read it back via
+ * {@link readInAppContent} — so email/SMS channels ignore an extra data key
+ * while the feed + realtime channels get a fully-rendered payload with no
+ * per-channel template resolution.
+ *
+ * `{var}` (single-brace) interpolation is deliberate and matches the de-facto
+ * 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";
+/**
+ * Host realtime transport — push an event to one user within a tenant.
+ * The transport itself (connection registry, heartbeats, the `/stream`
+ * endpoint, multi-tab fan-out) stays host-owned; everything in this package
+ * that touches realtime ({@link SseChannel}, {@link InAppChannel}'s combined
+ * mode, {@link createInAppBackfill}, the feed resource's read-sync) goes
+ * through this one seam.
+ */
+interface RealtimePushPort {
+  push(userId: string, organizationId: string, event: string, data: unknown): void | Promise<void>;
+}
+type InAppPriority = "low" | "normal" | "high";
+/** Declarative in-app template on a trigger — `{var}` placeholders. */
+interface InAppTemplate {
+  /** Notification title. */
+  readonly title: string;
+  /** Notification body. */
+  readonly message: string;
+  /** Frontend route (`/dashboard/orders/{orderId}`). */
+  readonly link?: string;
+  /** Entity kind for UI grouping/icons ('order' | 'transfer' | ...). */
+  readonly entityType?: string;
+  /** Entity id placeholder (`{orderId}`) for deep-linking / dedup. */
+  readonly entityId?: string;
+}
+/** Fully-rendered in-app content the channels deliver. */
+interface InAppContent {
+  readonly title: string;
+  readonly message: string;
+  readonly link?: string;
+  readonly entityType?: string;
+  readonly entityId?: string;
+  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;
+/** 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
+/** A feed row the {@link InAppChannel} writes and this resource reads. */
+interface InAppFeedRow {
+  readonly organizationId: string;
+  readonly userId: string;
+  /** Notification type (the event type by default). */
+  readonly type: string;
+  readonly title: string;
+  readonly message: string;
+  readonly data?: {
+    readonly link?: string;
+    readonly entityId?: string;
+    readonly entityType?: string;
+    readonly meta?: Record<string, unknown>;
+  };
+  readonly priority: InAppPriority;
+}
+interface InAppFeedListOptions {
+  readonly page?: number;
+  readonly limit?: number;
+  readonly unreadOnly?: boolean;
+  readonly type?: string;
+}
+interface InAppFeedPage<TRow = unknown> {
+  readonly data: TRow[];
+  readonly pagination: {
+    readonly page: number;
+    readonly limit: number;
+    readonly total: number;
+    readonly totalPages: number;
+  };
+}
+/**
+ * Host repository over the feed collection. The host owns the persistence
+ * (schema, indexes, soft-TTL); this port is the minimal surface the channel
+ * (write) and resource (read + lifecycle) need.
+ */
+interface InAppFeedRepository<TRow = unknown> {
+  /** Insert a delivered notification (called by {@link InAppChannel}). */
+  create(row: InAppFeedRow): Promise<{
+    id: string;
+  }>;
+  /** Paginated, newest-first, user + tenant scoped. */
+  listForUser(organizationId: string, userId: string, options: InAppFeedListOptions): Promise<InAppFeedPage<TRow>>;
+  /** Unread badge count. */
+  countUnread(organizationId: string, userId: string): Promise<number>;
+  /** Mark one as read; `null` when not found / not owned. */
+  markRead(organizationId: string, userId: string, id: string): Promise<TRow | null>;
+  /** Mark all unread read; returns the modified count. */
+  markAllRead(organizationId: string, userId: string): Promise<number>;
+  /**
+   * OPTIONAL — atomically fetch up to `limit` rows never delivered to any live
+   * client AND mark them delivered, in one repo call (find-and-update).
+   * Powers `createInAppBackfill` (reconnect catch-up): "delivered" is a
+   * SEPARATE axis from read/unread — a row is *delivered* once any client has
+   * received it over realtime, *read* once the user acted on it. Track it
+   * however fits the schema (a `deliveredAt` timestamp is the convention).
+   * Atomicity is what keeps two near-simultaneous connects (multi-tab beyond
+   * the debounce window) from double-toasting the same rows.
+   */
+  claimUndelivered?(organizationId: string, userId: string, limit: number): Promise<TRow[]>;
+  /**
+   * OPTIONAL — delete one row (user dismissed it for good); `false` when not
+   * found / not owned. When implemented, the feed resource registers
+   * `DELETE /:id`. Hard vs soft delete is the host's call.
+   */
+  delete?(organizationId: string, userId: string, id: string): Promise<boolean>;
+}
+/**
+ * Cache seam for the unread badge count — the hottest query in the system
+ * (every open tab polls it). Structural + possibly-async so a host can back it
+ * with Redis; {@link createUnreadCountCache} is the in-process default.
+ *
+ * Share ONE instance between `inAppFeedResource({ unreadCache })` (reads
+ * through it, invalidates on read-state mutations) and
+ * `InAppChannel({ unreadCache })` (invalidates on new-row writes) — otherwise
+ * new notifications ride the TTL before the badge moves.
+ */
+interface UnreadCountCache {
+  get(organizationId: string, userId: string): number | undefined | Promise<number | undefined>;
+  set(organizationId: string, userId: string, count: number): void | Promise<void>;
+  invalidate(organizationId: string, userId: string): void | Promise<void>;
+}
+interface CreateUnreadCountCacheOptions {
+  /** Entry freshness window. Default 30_000ms. */
+  readonly ttlMs?: number;
+  /** Entry cap — oldest entries evicted past it (bounds memory). Default 10_000. */
+  readonly maxEntries?: number;
+}
+/**
+ * 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;
+/** The current user + tenant, resolved off a request by the host. */
+interface InAppFeedScope {
+  readonly userId: string;
+  readonly organizationId: string;
+}
+interface InAppFeedResourceOptions {
+  readonly repository: InAppFeedRepository;
+  /** Read `{ userId, organizationId }` off the request (host auth/scoping). */
+  readonly resolveScope: (req: FastifyRequest) => InAppFeedScope;
+  /** Gate for every feed route (a signed-in user reading their own feed). */
+  readonly permissions: PermissionCheck;
+  /** Resource name. Default "in-app-notification". */
+  readonly name?: string;
+  /** Route prefix. Default "/notifications". */
+  readonly prefix?: string;
+  /** Max page size (list `limit` cap). Default 50. */
+  readonly maxLimit?: number;
+  /**
+   * Realtime port for cross-tab read-sync: mark-read / mark-all-read / delete
+   * push a `readSyncEventName` event to the user's OTHER open tabs so badges
+   * and toasts drop instantly instead of on the next poll. Best-effort —
+   * a push failure never fails the request.
+   */
+  readonly port?: RealtimePushPort;
+  /** Read-sync event name. Default "notification:read". */
+  readonly readSyncEventName?: string;
+  /**
+   * Unread badge-count cache — see {@link UnreadCountCache}. Share the same
+   * instance with `InAppChannel` so new-row writes invalidate too.
+   */
+  readonly unreadCache?: UnreadCountCache;
+}
+declare function inAppFeedResource(options: InAppFeedResourceOptions): import("@classytic/arc").ResourceDefinition<import("@classytic/arc").AnyRecord>;
+//#endregion
+//#region src/backfill.d.ts
+interface InAppBackfillOptions {
+  /** Feed repository — MUST implement the optional `claimUndelivered`. */
+  readonly repository: InAppFeedRepository;
+  /** Host realtime transport the bulk event is pushed through. */
+  readonly port: RealtimePushPort;
+  /** Bulk event name. Default "notification:backfill". */
+  readonly eventName?: string;
+  /** Max rows claimed per connect. Default 100. */
+  readonly limit?: number;
+  /** Multi-tab coalescing window. Default 2000ms. */
+  readonly debounceMs?: number;
+  /** Claim/push failure sink (backfill is best-effort). Default: swallow. */
+  readonly onError?: (error: unknown) => void;
+}
+interface InAppBackfill {
+  /** Call from the host's SSE/WS connection handler. Sync, never throws. */
+  onConnect(userId: string, organizationId: string): void;
+  /** Cancel pending debounces (graceful shutdown / tests). */
+  close(): void;
+}
+declare function createInAppBackfill(options: InAppBackfillOptions): InAppBackfill;
+//#endregion
 //#region src/dbFirstResolver.d.ts
 /** One draftable template row — the shape be-prod's EmailTemplate model proved. */
 interface StoredTemplate {
@@ -44,6 +253,40 @@ interface DbFirstTemplateResolver {
 }
 declare function createDbFirstResolver(options: DbFirstResolverOptions): DbFirstTemplateResolver;
 //#endregion
+//#region src/inAppChannel.d.ts
+interface InAppChannelConfig extends ChannelConfig {
+  /** Feed store the channel writes rows to (host-owned persistence). */
+  readonly repository: InAppFeedRepository;
+  /**
+   * Combined mode: also push the notification to the user's live connection
+   * AFTER the feed write, with the persisted row `id` included — so a live
+   * toast can be marked read / deep-linked without a refetch. Prefer this over
+   * registering a separate {@link SseChannel} when you persist: the kernel
+   * dispatches channels in parallel, so a standalone realtime channel can
+   * never carry the row id. Best-effort — a push failure never fails the
+   * durable write (`metadata.realtimeDelivered` reports it).
+   */
+  readonly port?: RealtimePushPort;
+  /** Realtime event name in combined mode. Default "notification". */
+  readonly eventName?: string;
+  /**
+   * Unread badge-count cache to invalidate on every feed write. Share the
+   * same instance with `inAppFeedResource({ unreadCache })`.
+   */
+  readonly unreadCache?: UnreadCountCache;
+}
+declare class InAppChannel extends BaseChannel<InAppChannelConfig> {
+  private readonly repository;
+  private readonly port;
+  private readonly eventName;
+  private readonly unreadCache;
+  constructor(config: InAppChannelConfig);
+  /** Skip (not fail) when this payload isn't an in-app notification. */
+  canSend(payload: NotificationPayload): SendResult | null;
+  send(payload: NotificationPayload): Promise<SendResult>;
+  private orgOf;
+}
+//#endregion
 //#region src/jobsQueue.d.ts
 interface NotificationsJobOptions {
   /** Job/queue name registered with `jobsPlugin`. Default "notifications". */
@@ -83,6 +326,13 @@ interface NotificationsJob {
 declare function notificationsJob(options?: NotificationsJobOptions): NotificationsJob;
 //#endregion
 //#region src/module.d.ts
+/**
+ * Resolve a trigger's host-typed `audience` selector to concrete recipients —
+ * the shared seam so branch-role → members (or team → users, tenant → admins)
+ * logic lives in ONE injected resolver, not duplicated across every trigger's
+ * `recipient` function. `null`/`undefined`/`[]` skips the dispatch.
+ */
+type RecipientResolver = (audience: unknown, event: DomainEvent) => readonly Recipient[] | null | undefined | Promise<readonly Recipient[] | null | undefined>;
 interface NotifyTrigger<TPayload = unknown> {
   /** Event pattern to subscribe (wildcards per arc's `matchEventPattern`). */
   readonly event: string;
@@ -91,10 +341,26 @@ interface NotifyTrigger<TPayload = unknown> {
   /** 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", ...).
+   * Map the event to recipient(s) directly. Return `null`/`undefined`/`[]` to
+   * skip. Mutually exclusive with {@link audience}: provide this OR an
+   * `audience` + a module-level {@link NotificationsModuleConfig.recipientResolver}.
+   */
+  readonly recipient?: (event: DomainEvent<TPayload>) => Recipient | readonly Recipient[] | null | undefined | Promise<Recipient | readonly Recipient[] | null | undefined>;
+  /**
+   * Host-typed audience selector (e.g. `{ roles, organizationId, exclude }`)
+   * fed to the module's {@link NotificationsModuleConfig.recipientResolver}.
+   * Return `null`/`undefined` to skip. Use this to keep recipient resolution
+   * (role → members) in one injected place instead of per trigger.
    */
-  readonly recipient: (event: DomainEvent<TPayload>) => Recipient | readonly Recipient[] | null | undefined | Promise<Recipient | readonly Recipient[] | null | undefined>;
+  readonly audience?: (event: DomainEvent<TPayload>) => unknown | Promise<unknown>;
+  /**
+   * In-app notification template (`{var}` placeholders). When set, the feed +
+   * realtime channels render and deliver it — rendered ONCE per event and
+   * parked on the send payload so channels need no template lookup.
+   */
+  readonly inApp?: InAppTemplate;
+  /** In-app priority (badge intensity / sort). Default "normal". */
+  readonly priority?: InAppPriority;
   /** Template variables. Default: the event payload (when object-shaped). */
   readonly data?: (event: DomainEvent<TPayload>) => Record<string, unknown> | Promise<Record<string, unknown>>;
   /**
@@ -113,6 +379,12 @@ interface NotificationsModuleConfig extends Omit<NotificationServiceConfig, "que
   readonly service?: NotificationService;
   /** Declarative event → notification triggers, wired in `afterResources`. */
   readonly notifyOn?: readonly NotifyTrigger[];
+  /**
+   * Resolves a trigger's `audience` selector to recipients (the shared
+   * role → members seam). Required only if any trigger uses `audience` instead
+   * of an explicit `recipient` function.
+   */
+  readonly recipientResolver?: RecipientResolver;
   /** Decorate `fastify.<name>` with the service. Default "notifications"; `false` to skip. */
   readonly decorate?: string | false;
   /**
@@ -132,7 +404,9 @@ declare module "fastify" {
 }
 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>;
+declare function dispatchTrigger(service: NotificationService, trigger: NotifyTrigger, event: DomainEvent, opts?: {
+  recipientResolver?: RecipientResolver;
+}): Promise<void>;
 //#endregion
 //#region src/repositoryDeliveryLog.d.ts
 type EntryStatus = DeliveryLogEntry["status"];
@@ -155,6 +429,22 @@ interface RepositoryDeliveryLogOptions {
 }
 declare function createRepositoryDeliveryLog(repository: RepositoryLike, options?: RepositoryDeliveryLogOptions): DeliveryLog;
 //#endregion
+//#region src/sseChannel.d.ts
+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> {
+  private readonly port;
+  private readonly eventName;
+  constructor(config: SseChannelConfig);
+  canSend(payload: NotificationPayload): SendResult | null;
+  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, {
@@ -184,4 +474,4 @@ interface TemplatesResourceOptions {
 }
 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 };
+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 };

package/dist/index.mjs

@@ -1,8 +1,44 @@
-import { NotificationService, createSimpleResolver } from "@classytic/notifications";
+import { BaseChannel, NotificationService, createSimpleResolver } from "@classytic/notifications";
+import { defineResource } from "@classytic/arc";
+import { NotFoundError } from "@classytic/arc/utils";
 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/backfill.ts
+function createInAppBackfill(options) {
+	const { repository, port, eventName = "notification:backfill", limit = 100, onError } = options;
+	const debounceMs = options.debounceMs ?? 2e3;
+	if (typeof repository.claimUndelivered !== "function") throw new Error("createInAppBackfill requires a repository implementing claimUndelivered() (atomic fetch-undelivered-and-mark-delivered). Add it to your feed repository, or skip backfill and let clients refetch GET /notifications/ on connect.");
+	const claimUndelivered = repository.claimUndelivered.bind(repository);
+	const pending = /* @__PURE__ */ new Map();
+	let closed = false;
+	const run = async (userId, organizationId) => {
+		try {
+			const rows = await claimUndelivered(organizationId, userId, limit);
+			if (!rows.length || closed) return;
+			await port.push(userId, organizationId, eventName, { notifications: rows });
+		} catch (error) {
+			onError?.(error);
+		}
+	};
+	return {
+		onConnect(userId, organizationId) {
+			if (closed) return;
+			const key = `${organizationId} ${userId}`;
+			if (pending.has(key)) return;
+			pending.set(key, setTimeout(() => {
+				pending.delete(key);
+				run(userId, organizationId);
+			}, debounceMs));
+		},
+		close() {
+			closed = true;
+			for (const timer of pending.values()) clearTimeout(timer);
+			pending.clear();
+		}
+	};
+}
+//#endregion
 //#region src/dbFirstResolver.ts
 /**
 * DB-first template resolver — generalized from be-prod's proven
@@ -52,6 +88,326 @@ function createDbFirstResolver(options) {
 	return resolver;
 }
 //#endregion
+//#region src/inApp.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
+* channel + the realtime/SSE channel).
+*
+* A trigger declares an {@link InAppTemplate} (title/message/link/... with
+* `{var}` placeholders). `dispatchTrigger` interpolates it ONCE per event
+* against the trigger's `data`, then parks the rendered {@link InAppContent} on
+* `payload.data[INAPP_DATA_KEY]`. Both in-app channels read it back via
+* {@link readInAppContent} — so email/SMS channels ignore an extra data key
+* while the feed + realtime channels get a fully-rendered payload with no
+* per-channel template resolution.
+*
+* `{var}` (single-brace) interpolation is deliberate and matches the de-facto
+* in-app convention; the email template layer keeps its own `${var}` engine.
+*/
+/** Reserved `payload.data` key carrying the rendered in-app content. */
+const INAPP_DATA_KEY = "__inApp";
+/** `{var}` interpolation — unknown keys are left as-is (visible, not silently blanked). */
+function interpolate(template, vars) {
+	return template.replace(/\{(\w+)\}/g, (_, key) => {
+		const v = vars[key];
+		return v === void 0 || v === null ? `{${key}}` : String(v);
+	});
+}
+/** Render a trigger's in-app template against event data + priority. */
+function renderInApp(template, vars, priority = "normal") {
+	return {
+		title: interpolate(template.title, vars),
+		message: interpolate(template.message, vars),
+		...template.link !== void 0 ? { link: interpolate(template.link, vars) } : {},
+		...template.entityType !== void 0 ? { entityType: interpolate(template.entityType, vars) } : {},
+		...template.entityId !== void 0 ? { entityId: interpolate(template.entityId, vars) } : {},
+		priority
+	};
+}
+/** Read the rendered in-app content a trigger parked on the send payload's data. */
+function readInAppContent(data) {
+	const raw = data?.[INAPP_DATA_KEY];
+	if (raw === null || typeof raw !== "object") return null;
+	const c = raw;
+	if (typeof c.title !== "string" || typeof c.message !== "string") return null;
+	return c;
+}
+//#endregion
+//#region src/inAppChannel.ts
+var InAppChannel = class extends BaseChannel {
+	repository;
+	port;
+	eventName;
+	unreadCache;
+	constructor(config) {
+		super({
+			name: "in-app",
+			...config
+		});
+		this.repository = config.repository;
+		this.port = config.port;
+		this.eventName = config.eventName ?? "notification";
+		this.unreadCache = config.unreadCache;
+	}
+	/** Skip (not fail) when this payload isn't an in-app notification. */
+	canSend(payload) {
+		if (!payload.recipient.id) return {
+			status: "skipped",
+			channel: this.name,
+			error: "no recipient.id (user)"
+		};
+		if (!this.orgOf(payload)) return {
+			status: "skipped",
+			channel: this.name,
+			error: "no organizationId in recipient.metadata"
+		};
+		if (!readInAppContent(payload.data)) return {
+			status: "skipped",
+			channel: this.name,
+			error: "no in-app content on payload"
+		};
+		return null;
+	}
+	async send(payload) {
+		const content = readInAppContent(payload.data);
+		const userId = payload.recipient.id;
+		const organizationId = this.orgOf(payload);
+		if (!content || !userId || !organizationId) return {
+			status: "skipped",
+			channel: this.name,
+			error: "incomplete in-app payload"
+		};
+		const type = payload.template ?? payload.event;
+		const data = {
+			...content.link !== void 0 ? { link: content.link } : {},
+			...content.entityId !== void 0 ? { entityId: content.entityId } : {},
+			...content.entityType !== void 0 ? { entityType: content.entityType } : {}
+		};
+		const { id } = await this.repository.create({
+			organizationId,
+			userId,
+			type,
+			title: content.title,
+			message: content.message,
+			priority: content.priority,
+			data
+		});
+		try {
+			await this.unreadCache?.invalidate(organizationId, userId);
+		} catch {}
+		if (!this.port) return {
+			status: "sent",
+			channel: this.name,
+			metadata: { notificationId: id }
+		};
+		let realtimeDelivered = true;
+		try {
+			await this.port.push(userId, organizationId, this.eventName, {
+				id,
+				type,
+				title: content.title,
+				message: content.message,
+				priority: content.priority,
+				data
+			});
+		} catch {
+			realtimeDelivered = false;
+		}
+		return {
+			status: "sent",
+			channel: this.name,
+			metadata: {
+				notificationId: id,
+				realtimeDelivered
+			}
+		};
+	}
+	orgOf(payload) {
+		const org = payload.recipient.metadata?.organizationId;
+		return typeof org === "string" && org ? org : void 0;
+	}
+};
+//#endregion
+//#region src/inAppFeed.ts
+/**
+* `inAppFeedResource` — the user-facing notification inbox as a normal arc
+* resource. Generalized from be-prod's `notification.resource`: a per-user,
+* per-tenant feed of notifications with unread-count, mark-read, and
+* mark-all-read. Rows are WRITTEN by the {@link InAppChannel} (a delivery
+* channel), so this resource is read + lifecycle only — no create/delete REST.
+*
+* Kit-less: the host passes an {@link InAppFeedRepository} (its Mongoose/
+* mongokit/sqlite repo, owning the schema, indexes, and TTL) plus a
+* {@link InAppFeedScope} resolver (how to read the current user + tenant off a
+* request). The realtime `/stream` (SSE/WebSocket) endpoint stays host-owned —
+* it is transport-specific; this resource is the queryable feed.
+*/
+/**
+* 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}.
+*/
+function createUnreadCountCache(options = {}) {
+	const { ttlMs = 3e4, maxEntries = 1e4 } = options;
+	const entries = /* @__PURE__ */ new Map();
+	const keyOf = (organizationId, userId) => `${organizationId}\u0000${userId}`;
+	return {
+		get(organizationId, userId) {
+			const key = keyOf(organizationId, userId);
+			const entry = entries.get(key);
+			if (!entry) return void 0;
+			if (entry.expiresAt <= Date.now()) {
+				entries.delete(key);
+				return;
+			}
+			return entry.count;
+		},
+		set(organizationId, userId, count) {
+			if (entries.size >= maxEntries) {
+				const oldest = entries.keys().next().value;
+				if (oldest !== void 0) entries.delete(oldest);
+			}
+			entries.set(keyOf(organizationId, userId), {
+				count,
+				expiresAt: Date.now() + ttlMs
+			});
+		},
+		invalidate(organizationId, userId) {
+			entries.delete(keyOf(organizationId, userId));
+		}
+	};
+}
+function toInt(value, fallback) {
+	const n = Number(value);
+	return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+function inAppFeedResource(options) {
+	const { repository, resolveScope, permissions, name = "in-app-notification", prefix = "/notifications", maxLimit = 50, port, readSyncEventName = "notification:read", unreadCache } = options;
+	/** Fire-and-forget: read-sync + cache invalidation must never fail a request. */
+	const afterReadStateChange = async (scope, data) => {
+		try {
+			await unreadCache?.invalidate(scope.organizationId, scope.userId);
+		} catch {}
+		if (!port) return;
+		try {
+			await port.push(scope.userId, scope.organizationId, readSyncEventName, data);
+		} catch {}
+	};
+	return defineResource({
+		name,
+		prefix,
+		disableDefaultRoutes: true,
+		routes: [
+			{
+				method: "GET",
+				path: "/",
+				permissions,
+				raw: true,
+				summary: "List my notifications (newest first, paginated)",
+				schema: { querystring: {
+					type: "object",
+					properties: {
+						page: {
+							type: "integer",
+							minimum: 1
+						},
+						limit: {
+							type: "integer",
+							minimum: 1,
+							maximum: maxLimit
+						},
+						unreadOnly: {
+							type: "string",
+							enum: ["true", "false"]
+						},
+						type: { type: "string" }
+					},
+					additionalProperties: true
+				} },
+				handler: async (req, reply) => {
+					const { userId, organizationId } = resolveScope(req);
+					const q = req.query ?? {};
+					const result = await repository.listForUser(organizationId, userId, {
+						page: toInt(q.page, 1),
+						limit: Math.min(toInt(q.limit, 20), maxLimit),
+						unreadOnly: q.unreadOnly === "true",
+						...typeof q.type === "string" && q.type ? { type: q.type } : {}
+					});
+					return reply.send(result);
+				}
+			},
+			{
+				method: "GET",
+				path: "/unread-count",
+				permissions,
+				raw: true,
+				summary: "Unread notification count (badge)",
+				handler: async (req, reply) => {
+					const { userId, organizationId } = resolveScope(req);
+					if (unreadCache) {
+						const cached = await unreadCache.get(organizationId, userId);
+						if (cached !== void 0) return reply.send({ count: cached });
+					}
+					const count = await repository.countUnread(organizationId, userId);
+					if (unreadCache) try {
+						await unreadCache.set(organizationId, userId, count);
+					} catch {}
+					return reply.send({ count });
+				}
+			},
+			{
+				method: "PATCH",
+				path: "/:id/read",
+				permissions,
+				raw: true,
+				summary: "Mark a single notification read",
+				handler: async (req, reply) => {
+					const scope = resolveScope(req);
+					const id = req.params.id;
+					const updated = await repository.markRead(scope.organizationId, scope.userId, id);
+					if (!updated) throw new NotFoundError("Notification");
+					await afterReadStateChange(scope, { id });
+					return reply.send(updated);
+				}
+			},
+			{
+				method: "PATCH",
+				path: "/read-all",
+				permissions,
+				raw: true,
+				summary: "Mark all my notifications read",
+				handler: async (req, reply) => {
+					const scope = resolveScope(req);
+					const modifiedCount = await repository.markAllRead(scope.organizationId, scope.userId);
+					await afterReadStateChange(scope, {
+						all: true,
+						modifiedCount
+					});
+					return reply.send({ modifiedCount });
+				}
+			},
+			...typeof repository.delete === "function" ? [{
+				method: "DELETE",
+				path: "/:id",
+				permissions,
+				raw: true,
+				summary: "Delete (dismiss) a notification",
+				handler: async (req, reply) => {
+					const scope = resolveScope(req);
+					const id = req.params.id;
+					if (!await repository.delete(scope.organizationId, scope.userId, id)) throw new NotFoundError("Notification");
+					await afterReadStateChange(scope, {
+						id,
+						deleted: true
+					});
+					return reply.send({ deleted: true });
+				}
+			}] : []
+		]
+	});
+}
+//#endregion
 //#region src/jobsQueue.ts
 /**
 * `fastify.jobs` bridge — reuse arc's job subsystem instead of standing up a
@@ -200,7 +556,7 @@ function notificationsJob(options = {}) {
 * at-least-once: redelivery must not double-send.
 */
 function notificationsModule(config) {
-	const { name = "notifications", service: provided, notifyOn = [], decorate = "notifications", queue, ...serviceConfig } = config;
+	const { name = "notifications", service: provided, notifyOn = [], decorate = "notifications", queue, recipientResolver, ...serviceConfig } = config;
 	let service;
 	const unsubscribes = [];
 	return defineModule({
@@ -221,7 +577,7 @@ function notificationsModule(config) {
 			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}` });
+				const unsubscribe = await subscribeWithBoundary(bus, trigger.event, async (event) => dispatchTrigger(service, trigger, event, { ...recipientResolver ? { recipientResolver } : {} }), { name: `arc-notifications:${trigger.event}` });
 				unsubscribes.push(unsubscribe);
 			}
 			fastify.log.debug(`[arc-notifications] ${triggers.length} trigger(s) subscribed`);
@@ -233,13 +589,23 @@ function notificationsModule(config) {
 	});
 }
 /** One event → N sends. Exported for direct unit testing. */
-async function dispatchTrigger(service, trigger, event) {
-	const resolved = await trigger.recipient(event);
+async function dispatchTrigger(service, trigger, event, opts) {
+	let resolved;
+	if (trigger.recipient) resolved = await trigger.recipient(event);
+	else if (trigger.audience) {
+		const audience = await trigger.audience(event);
+		if (audience === null || audience === void 0) return;
+		resolved = opts?.recipientResolver ? await opts.recipientResolver(audience, event) : void 0;
+	}
 	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 sendData = trigger.inApp ? {
+		...data,
+		[INAPP_DATA_KEY]: renderInApp(trigger.inApp, data, trigger.priority)
+	} : data;
 	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}`;
@@ -247,7 +613,7 @@ async function dispatchTrigger(service, trigger, event) {
 			event: event.type,
 			template: trigger.template ?? event.type,
 			recipient,
-			data,
+			data: sendData,
 			...trigger.channels ? { channels: [...trigger.channels] } : {},
 			...idempotencyKey !== void 0 ? { idempotencyKey } : {},
 			metadata: {
@@ -321,6 +687,67 @@ function createRepositoryDeliveryLog(repository, options = {}) {
 	};
 }
 //#endregion
+//#region src/sseChannel.ts
+var SseChannel = class extends BaseChannel {
+	port;
+	eventName;
+	constructor(config) {
+		super({
+			name: "sse",
+			...config
+		});
+		this.port = config.port;
+		this.eventName = config.eventName ?? "notification";
+	}
+	canSend(payload) {
+		if (!payload.recipient.id) return {
+			status: "skipped",
+			channel: this.name,
+			error: "no recipient.id (user)"
+		};
+		if (!this.orgOf(payload)) return {
+			status: "skipped",
+			channel: this.name,
+			error: "no organizationId in recipient.metadata"
+		};
+		if (!readInAppContent(payload.data)) return {
+			status: "skipped",
+			channel: this.name,
+			error: "no in-app content on payload"
+		};
+		return null;
+	}
+	async send(payload) {
+		const content = readInAppContent(payload.data);
+		const userId = payload.recipient.id;
+		const organizationId = this.orgOf(payload);
+		if (!content || !userId || !organizationId) return {
+			status: "skipped",
+			channel: this.name,
+			error: "incomplete in-app payload"
+		};
+		await this.port.push(userId, organizationId, this.eventName, {
+			type: payload.template ?? payload.event,
+			title: content.title,
+			message: content.message,
+			priority: content.priority,
+			data: {
+				...content.link !== void 0 ? { link: content.link } : {},
+				...content.entityId !== void 0 ? { entityId: content.entityId } : {},
+				...content.entityType !== void 0 ? { entityType: content.entityType } : {}
+			}
+		});
+		return {
+			status: "sent",
+			channel: this.name
+		};
+	}
+	orgOf(payload) {
+		const org = payload.recipient.metadata?.organizationId;
+		return typeof org === "string" && org ? org : void 0;
+	}
+};
+//#endregion
 //#region src/templatesResource.ts
 /**
 * `templatesResource` — DB-draftable notification templates as a normal arc
@@ -426,4 +853,4 @@ function templatesResource(options) {
 	});
 }
 //#endregion
-export { createDbFirstResolver, createRepositoryDeliveryLog, dispatchTrigger, notificationsJob, notificationsModule, templatesResource };
+export { INAPP_DATA_KEY, InAppChannel, SseChannel, createDbFirstResolver, createInAppBackfill, createRepositoryDeliveryLog, createUnreadCountCache, dispatchTrigger, inAppFeedResource, notificationsJob, notificationsModule, readInAppContent, renderInApp, templatesResource };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc-notifications",
-  "version": "0.1.0",
+  "version": "0.3.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": {
@@ -24,14 +24,15 @@
   "scripts": {
     "build": "tsdown",
     "typecheck": "tsc --noEmit",
+    "test": "vitest run --root ../.. packages/arc-notifications/tests",
     "lint": "biome check src/",
     "prepublishOnly": "node ../../scripts/prepublish-gate.mjs"
   },
   "peerDependencies": {
-    "@classytic/arc": ">=2.20.0",
+    "@classytic/arc": ">=2.23.0",
     "@classytic/notifications": ">=2.2.0",
-    "@classytic/primitives": ">=0.9.0",
-    "@classytic/repo-core": ">=0.7.0"
+    "@classytic/primitives": ">=0.14.0",
+    "@classytic/repo-core": ">=0.14.0"
   },
   "keywords": [
     "arc",