@warlock.js/notifications 4.2.0

package/cjs/index.cjs

@@ -0,0 +1,1034 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let _warlock_js_logger = require("@warlock.js/logger");
+let node_crypto = require("node:crypto");
+let _warlock_js_core = require("@warlock.js/core");
+let _warlock_js_cascade = require("@warlock.js/cascade");
+
+//#region ../@warlock.js/notifications/src/errors.ts
+/**
+* Domain errors for `@warlock.js/notifications`. All extend `Error` directly
+* (no framework HttpError) so the package stays runtime-agnostic — the host
+* app maps them to its own error shape via `instanceof` if needed.
+*
+* Each captures a clean V8 stack (drops the Error-constructor frame) to match
+* the cascade convention.
+*/
+function captureStack(target, ctor) {
+	Error.captureStackTrace?.(target, ctor);
+}
+var NotificationsNotConfiguredError = class NotificationsNotConfiguredError extends Error {
+	constructor() {
+		super("Notifications not configured — add `src/config/notifications.ts` with a default-exported config; the notifications connector registers it at boot.");
+		this.name = "NotificationsNotConfiguredError";
+		captureStack(this, NotificationsNotConfiguredError);
+	}
+};
+var ChannelNotFoundError = class ChannelNotFoundError extends Error {
+	constructor(channelName) {
+		super(`Channel "${channelName}" is not configured. Add it to the \`channels\` map in \`src/config/notifications.ts\`.`);
+		this.name = "ChannelNotFoundError";
+		captureStack(this, ChannelNotFoundError);
+	}
+};
+var NoQueueDispatcherError = class NoQueueDispatcherError extends Error {
+	constructor(channelName) {
+		super(`Cannot queue to channel "${channelName}" — no queue dispatcher configured. Add a \`queue\` to \`src/config/notifications.ts\`, or call \`.send()\` instead of \`.queue()\`.`);
+		this.name = "NoQueueDispatcherError";
+		captureStack(this, NoQueueDispatcherError);
+	}
+};
+var MissingRendererError = class MissingRendererError extends Error {
+	constructor(notificationType, channelName) {
+		super(`Notification "${notificationType}" routes to channel "${channelName}" via \`via\` but defines no \`${channelName}\` renderer.`);
+		this.name = "MissingRendererError";
+		captureStack(this, MissingRendererError);
+	}
+};
+/**
+* Thrown when a channel's `route()` resolver runs but returns `undefined` for
+* a recipient (e.g. a mail recipient with no email). Distinct from "the
+* channel declares no resolver" — that case falls back to `{ id }`.
+*/
+var UnresolvableRouteError = class UnresolvableRouteError extends Error {
+	constructor(channelName, recipientId) {
+		super(`Channel "${channelName}" could not resolve a route for recipient ${recipientId ?? "(unknown)"}. The channel's \`route()\` returned undefined — the recipient is missing the address column this channel needs.`);
+		this.name = "UnresolvableRouteError";
+		captureStack(this, UnresolvableRouteError);
+	}
+};
+
+//#endregion
+//#region ../@warlock.js/notifications/src/config.ts
+let activeConfig;
+/**
+* Set the active notifications configuration. In a Warlock app the
+* notifications connector calls this at boot with the default export of
+* `src/config/notifications.ts`. Subsequent calls REPLACE the active config
+* (does not merge) — pass the complete config, not a partial.
+*/
+function setNotificationConfig(config) {
+	activeConfig = config;
+}
+/**
+* Get the active notifications configuration. Throws if not yet configured —
+* fail loudly at the first send rather than silently doing nothing.
+*/
+function getNotificationConfig() {
+	if (!activeConfig) throw new NotificationsNotConfiguredError();
+	return activeConfig;
+}
+/**
+* Clear the active configuration. Intended for tests; not part of the runtime
+* surface. Production code should never call this.
+*/
+function resetNotificationConfig() {
+	activeConfig = void 0;
+}
+
+//#endregion
+//#region ../@warlock.js/notifications/src/dispatch/define-channel.ts
+/**
+* Identity helper that narrows the channel type to its payload. Use it when
+* you want TypeScript to enforce the `send` payload shape against the
+* payload type you declared.
+*
+* Built-in channels (`mail`, `database`) ship as factories; custom channels
+* are usually defined with this helper.
+*
+* @example
+*   import { defineChannel } from "@warlock.js/notifications";
+*
+*   type DiscordPayload = { content: string };
+*
+*   export const discordChannel = () =>
+*     defineChannel<DiscordPayload>({
+*       name: "discord",
+*       route: (n) => n.get("discord_webhook"),
+*       async send({ payload, route }) {
+*         await fetch(route as string, {
+*           method: "POST",
+*           headers: { "content-type": "application/json" },
+*           body: JSON.stringify(payload),
+*         });
+*       },
+*     });
+*
+*   // Then teach the registry:
+*   declare module "@warlock.js/notifications" {
+*     interface NotificationChannels { discord: DiscordPayload }
+*   }
+*/
+function defineChannel(channel) {
+	return channel;
+}
+
+//#endregion
+//#region ../@warlock.js/notifications/src/dispatch/dispatch-id.ts
+/**
+* A unique id for one (channel, recipient) dispatch. `sending` and its terminal
+* `sent` / `failed` event share it so observers can pair them — for tracing
+* spans, latency, or spotting a `sending` with no terminal (a hung send).
+*/
+function newDispatchId() {
+	return (0, node_crypto.randomUUID)();
+}
+
+//#endregion
+//#region ../@warlock.js/notifications/src/dispatch/notifications-event-bus.ts
+/**
+* Typed event bus for notifications observability. Emits `sent`, `failed`,
+* and `skipped` events per (channel, recipient) — fan-out emits N events.
+*
+* Intentionally minimal — a `Map<event, Set<handler>>` keeps tests trivial
+* and avoids pulling event-emitter machinery for what is fundamentally
+* pub/sub. Handler exceptions are logged-and-swallowed so one bad listener
+* cannot break the dispatcher.
+*
+* @example
+*   notifications.on("sent",    ({ channel }) => metrics.inc(`notif.${channel}.sent`));
+*   notifications.on("skipped", ({ reason })  => metrics.inc(`notif.skipped.${reason}`));
+*   const off = notifications.on("failed", logErr);
+*   off(); // unsubscribe
+*/
+const handlers = {
+	sending: /* @__PURE__ */ new Set(),
+	sent: /* @__PURE__ */ new Set(),
+	failed: /* @__PURE__ */ new Set(),
+	skipped: /* @__PURE__ */ new Set()
+};
+/**
+* Public observability surface.
+*
+* `on(event, handler)` returns an unsubscribe function. `off` exists for
+* symmetry with libraries that hold handler references for later removal.
+*/
+const notifications = {
+	on(event, handler) {
+		handlers[event].add(handler);
+		return () => {
+			handlers[event].delete(handler);
+		};
+	},
+	off(event, handler) {
+		handlers[event].delete(handler);
+	}
+};
+/**
+* Internal emit — used by the dispatcher. Not exported from the package.
+* Handlers run in registration order; an awaited Promise.allSettled isolates
+* each listener so one throw cannot block the others.
+*/
+async function emit(event, data) {
+	const set = handlers[event];
+	if (set.size === 0) return;
+	const results = await Promise.allSettled(Array.from(set).map(async (handler) => {
+		await handler(data);
+	}));
+	for (const result of results) if (result.status === "rejected") _warlock_js_logger.log.error("notifications", "event-handler", result.reason);
+}
+
+//#endregion
+//#region ../@warlock.js/notifications/src/dispatch/dispatcher.ts
+/**
+* Internal dispatch core — shared by `defineNotification` and `notify.<channel>`.
+*
+* Responsibilities:
+* 1. Look up the channel in the configured registry (throws if missing).
+* 2. Run the rate-limit gate (if a notification type is known) — drop with a
+*    `skipped` event when the limiter refuses.
+* 3. Resolve the route: raw string > channel.route(notifiable) > { id }.
+* 4. Inject the per-send `idempotencyKey` into the database payload.
+* 5. Dispatch (sync via channel.send OR async via queue.dispatch).
+* 6. Emit `sent` on success, `failed` on throw.
+*
+* Per-channel failure isolation is the CALLER's job (it wraps a list of
+* `dispatchChannel` calls in `Promise.allSettled`).
+*/
+/**
+* Dispatch ONE rendered payload to ONE recipient through ONE channel.
+* Does NOT consult `PreferenceProvider` — that gate runs at the caller level.
+*
+* Throws `ChannelNotFoundError` (channel not registered) and
+* `UnresolvableRouteError` (channel's `route()` returned undefined) — both are
+* configuration/data errors that should surface loudly. Transport failures
+* (channel.send throwing) are emitted as `failed` AND rethrown.
+*/
+async function dispatchChannel(args) {
+	const config = getNotificationConfig();
+	const channel = config.channels[args.channelName];
+	if (!channel) throw new ChannelNotFoundError(args.channelName);
+	const dispatchId = newDispatchId();
+	if (args.to && args.notificationType && config.rateLimit) {
+		if (!await config.rateLimit.allow(args.to, args.channelName, args.notificationType)) {
+			await emit("skipped", {
+				dispatchId,
+				channel: args.channelName,
+				notifiable: args.to,
+				reason: "rate-limit",
+				options: args.options
+			});
+			return;
+		}
+	}
+	const route = resolveRoute(args, channel.route);
+	let payload = args.payload;
+	if (args.channelName === "database" && args.options.idempotencyKey && payload && typeof payload === "object") payload = {
+		...payload,
+		idempotencyKey: args.options.idempotencyKey
+	};
+	await emit("sending", {
+		dispatchId,
+		channel: args.channelName,
+		notifiable: args.to,
+		payload,
+		options: args.options
+	});
+	const startedAt = Date.now();
+	try {
+		if (args.mode === "queue") {
+			if (!config.queue) throw new NoQueueDispatcherError(args.channelName);
+			await config.queue.dispatch({
+				channel: args.channelName,
+				route,
+				payload,
+				options: args.options
+			});
+		} else await channel.send({
+			payload,
+			route,
+			notifiable: args.to,
+			options: args.options
+		});
+		await emit("sent", {
+			dispatchId,
+			channel: args.channelName,
+			notifiable: args.to,
+			payload,
+			options: args.options,
+			durationMs: Date.now() - startedAt
+		});
+	} catch (error) {
+		await emit("failed", {
+			dispatchId,
+			channel: args.channelName,
+			notifiable: args.to,
+			payload,
+			error,
+			options: args.options,
+			durationMs: Date.now() - startedAt
+		});
+		throw error;
+	}
+}
+/**
+* Route resolution priority:
+*   1. raw route string (ad-hoc `notify.mail("x@y.com", …)`)
+*   2. the channel's `route(notifiable)` resolver
+*   3. `{ id: notifiable.id }` — ONLY when the channel declares no resolver
+*
+* When a channel HAS a resolver but it returns undefined (e.g. a mail
+* recipient with no email), we throw `UnresolvableRouteError` rather than
+* silently coercing to `{ id }` — that would hand a string-route channel an
+* object and fail deep inside the transport.
+*/
+function resolveRoute(args, resolver) {
+	if (args.rawRoute !== void 0) return args.rawRoute;
+	if (!args.to) throw new UnresolvableRouteError(args.channelName);
+	if (!resolver) return { id: args.to.id };
+	const resolved = resolver(args.to);
+	if (resolved === void 0) throw new UnresolvableRouteError(args.channelName, args.to.id);
+	return resolved;
+}
+
+//#endregion
+//#region ../@warlock.js/notifications/src/dispatch/define-notification.ts
+/**
+* `defineNotification` — reusable, type-safe, multi-channel notification.
+*
+* Functional, not class-based: pass `via` + a renderer per channel + a
+* stable `type`. The returned object exposes `.send` / `.queue` / `.only`.
+*
+* Renderer signature is `(data, to, ctx)` where `ctx` carries `locale` and
+* `meta` from `SendOptions`. The database renderer's `type` is OPTIONAL — the
+* dispatcher injects `def.type`, keeping the type defined in ONE place.
+*
+* ## Error policy
+* - **Config errors** (missing renderer, no queue dispatcher, unknown channel)
+*   are programmer mistakes → they REJECT `.send()`/`.queue()` (and a static
+*   `via` with a missing renderer throws at definition time). Consistent with
+*   `notify`, which rejects `ChannelNotFoundError`.
+* - **Transport errors** (a channel's `send` throwing) stay ISOLATED — emitted
+*   as a `failed` event, never aborting sibling channels/recipients.
+* - **`via()` / preferences throws** for one recipient are logged and that
+*   recipient is dropped (the rest of a fan-out still go).
+*
+* @example
+*   export const orderShipped = defineNotification<{ order: Order }>({
+*     type: "order.shipped",
+*     via: ["mail", "database"],
+*     mail: ({ order }, to) => ({ subject: `#${order.number} shipped`, html: "…" }),
+*     database: ({ order }) => ({ title: "Your order shipped", payload: { id: order.id } }),
+*   });
+*   await orderShipped.send(user, { order });
+*   await orderShipped.queue([buyer, salesRep], { order }, { delay: "10m" });
+*   await orderShipped.only("mail").send(user, { order });
+*/
+/** Errors that represent a misconfiguration and must surface (reject), not isolate. */
+function isConfigError(error) {
+	return error instanceof MissingRendererError || error instanceof NoQueueDispatcherError || error instanceof ChannelNotFoundError;
+}
+function defineNotification(def) {
+	const make = (restrict) => {
+		if (Array.isArray(def.via)) {
+			const channels = restrict ? def.via.filter((c) => restrict.includes(c)) : def.via;
+			for (const channel of channels) if (!def[channel]) throw new MissingRendererError(def.type, channel);
+		}
+		return {
+			send(to, data, options) {
+				return dispatchAll(def, to, data, options ?? {}, "send", restrict);
+			},
+			queue(to, data, options) {
+				return dispatchAll(def, to, data, options ?? {}, "queue", restrict);
+			},
+			only(...channels) {
+				return make(channels);
+			}
+		};
+	};
+	return make();
+}
+/**
+* Fan-out to all recipients. Each recipient dispatches independently; one
+* recipient's transport failure never aborts the others. CONFIG errors,
+* however, propagate — they reject the returned promise.
+*/
+async function dispatchAll(def, to, data, options, mode, restrict) {
+	const recipients = Array.isArray(to) ? to : [to];
+	rethrowConfigErrors(await Promise.allSettled(recipients.map((recipient) => dispatchToRecipient(def, recipient, data, options, mode, restrict))));
+}
+async function dispatchToRecipient(def, to, data, options, mode, restrict) {
+	const config = getNotificationConfig();
+	let channels;
+	try {
+		channels = typeof def.via === "function" ? def.via(data, to) : [...def.via];
+		if (restrict) channels = channels.filter((c) => restrict.includes(c));
+		if (!options.force && config.preferences) {
+			const allowed = await config.preferences.resolveChannels(to, def.type, channels);
+			for (const channel of channels.filter((c) => !allowed.includes(c))) await emit("skipped", {
+				dispatchId: newDispatchId(),
+				channel,
+				notifiable: to,
+				reason: "preference",
+				options
+			});
+			channels = channels.filter((c) => allowed.includes(c));
+		}
+	} catch (error) {
+		_warlock_js_logger.log.error("notifications", `resolve.${def.type}`, error);
+		return;
+	}
+	const renderCtx = {
+		locale: options.locale,
+		meta: options.meta
+	};
+	rethrowConfigErrors(await Promise.allSettled(channels.map((name) => {
+		const renderer = def[name];
+		if (!renderer) return Promise.reject(new MissingRendererError(def.type, name));
+		let payload = renderer(data, to, renderCtx);
+		if (name === "database" && payload && typeof payload === "object" && !("type" in payload)) payload = {
+			...payload,
+			type: def.type
+		};
+		return dispatchChannel({
+			channelName: name,
+			payload,
+			to,
+			notificationType: def.type,
+			mode,
+			options
+		});
+	})));
+}
+/** Collect config-class rejections and rethrow (single or AggregateError). */
+function rethrowConfigErrors(results) {
+	const configErrors = results.filter((r) => r.status === "rejected" && isConfigError(r.reason)).map((r) => r.reason);
+	if (configErrors.length === 1) throw configErrors[0];
+	if (configErrors.length > 1) throw new AggregateError(configErrors, "Multiple notification configuration errors");
+}
+
+//#endregion
+//#region ../@warlock.js/notifications/src/dispatch/notify.ts
+/**
+* `notify` — ad-hoc, per-channel send facade.
+*
+* A Proxy keyed by the channel registry. `notify.<channel>(to, payload,
+* options?)` works for ANY channel name registered in
+* `NotificationChannels` — built-in or custom (via declaration merging).
+*
+* For multi-channel sends, use `defineNotification` — that's the reusable
+* pattern and the only mental model for "send through several channels at
+* once" (no inline multi-channel overload here on purpose).
+*
+* `notify.channel(name)` is the runtime escape when the channel name isn't a
+* compile-time literal.
+*
+* @example
+*   await notify.mail(user, { subject: "Welcome", html: "<p>Hi!</p>" });
+*   await notify.database(user, { type: "welcome", title: "Welcome!" });
+*   await notify.mail("guest@example.com", { subject: "…", html: "…" });   // raw target
+*   await notify.channel(dynamicName).send(user, payload);                 // dynamic name
+*/
+/**
+* Per-call dispatch for `notify.<channel>`. Mirrors `defineNotification`'s
+* pipeline but without rendering: payload is already concrete.
+*
+* Preferences gate runs ONLY when a notification `type` is known — explicit
+* via `options.type`, or implicit from a database payload's `type` field.
+* Without a type we have nothing to gate on, and ad-hoc sends bypass
+* preferences silently (use `defineNotification` if you want guaranteed
+* gating).
+*/
+async function notifyImpl(channelName, to, payload, options = {}) {
+	const isRawTarget = typeof to === "string";
+	const notifiable = isRawTarget ? void 0 : to;
+	let notificationType = options.type;
+	if (notificationType === void 0 && payload && typeof payload === "object" && "type" in payload && typeof payload.type === "string") notificationType = payload.type;
+	if (notifiable && notificationType && !options.force) {
+		const config = getNotificationConfig();
+		if (config.preferences) {
+			if (!(await config.preferences.resolveChannels(notifiable, notificationType, [channelName])).includes(channelName)) {
+				await emit("skipped", {
+					dispatchId: newDispatchId(),
+					channel: channelName,
+					notifiable,
+					reason: "preference",
+					options
+				});
+				return;
+			}
+		}
+	}
+	await dispatchChannel({
+		channelName,
+		payload,
+		to: notifiable,
+		rawRoute: isRawTarget ? to : void 0,
+		notificationType,
+		mode: "send",
+		options
+	});
+}
+/**
+* Build the `notify` proxy. `channel(name)` returns a `{ send }` object;
+* any other property access returns a one-shot dispatcher for that channel.
+*/
+const notify = new Proxy({}, { get(_target, prop) {
+	if (typeof prop === "symbol") return;
+	if (prop === "then" || prop === "catch" || prop === "finally" || prop === "toJSON") return;
+	if (prop === "channel") return (name) => ({ send: (to, payload, options) => notifyImpl(name, to, payload, options) });
+	return (to, payload, options) => notifyImpl(prop, to, payload, options);
+} });
+
+//#endregion
+//#region ../@warlock.js/notifications/src/channels/database-channel.ts
+function databaseChannel(repo) {
+	return defineChannel({
+		name: "database",
+		route: (notifiable) => ({ id: notifiable.id }),
+		async send({ payload, route, notifiable }) {
+			const id = typeof route === "object" ? route.id : route;
+			const { tenantColumn } = repo;
+			const tenantId = tenantColumn && notifiable ? notifiable.get(tenantColumn) : void 0;
+			await repo.createFor(id, payload, tenantId);
+		}
+	});
+}
+
+//#endregion
+//#region ../@warlock.js/notifications/src/channels/mail-channel.ts
+/**
+* `mailChannel` — wraps `@warlock.js/core` `sendMail`.
+*
+* Route is `notifiable.email` by convention; override via `config.route`
+* when the column is named differently or computed.
+*
+* The renderer's payload is forwarded verbatim (`subject`, `html`, `text`,
+* `cc`). `from` is set once at channel-config time; per-send overrides go
+* through the payload itself (you can include `from` in `MailPayload` if
+* you extend the registry — but the convention is one channel = one
+* sender identity).
+*
+* @example
+*   // src/config/notifications.ts
+*   channels: {
+*     mail: mailChannel({ from: "no-reply@store.com" }),
+*   }
+*
+*   // anywhere
+*   await notify.mail(user, { subject: "Welcome", html: "<p>Hi!</p>" });
+*/
+function mailChannel(config = {}) {
+	const resolveRoute = config.route ?? ((n) => n.get("email"));
+	return defineChannel({
+		name: "mail",
+		route: (notifiable) => resolveRoute(notifiable),
+		async send({ payload, route }) {
+			await (0, _warlock_js_core.sendMail)({
+				to: route,
+				from: config.from,
+				...payload
+			});
+		}
+	});
+}
+
+//#endregion
+//#region ../@warlock.js/notifications/src/in-app/column-map.ts
+const DEFAULT_RECIPIENT_COLUMN = "user_id";
+const DEFAULT_READ_AT_COLUMN = "read_at";
+/**
+* Resolve a model's declared `columnMap` into a complete map: default the
+* recipient column, and fall back to a `read_at` timestamp when the model
+* declares no read-state column. The fallback guarantees the result always
+* has a usable read-state representation, so no boot-time validation is needed.
+*/
+function resolveColumnMap(map) {
+	const recipient = map?.recipient ?? DEFAULT_RECIPIENT_COLUMN;
+	const tenant = map?.tenant;
+	if (!map?.readAt && !map?.isRead) return {
+		recipient,
+		tenant,
+		readAt: DEFAULT_READ_AT_COLUMN
+	};
+	return {
+		recipient,
+		tenant,
+		readAt: map.readAt,
+		isRead: map.isRead
+	};
+}
+
+//#endregion
+//#region ../@warlock.js/notifications/src/in-app/base-notifications-repository.ts
+/**
+* Shipped behavior repository for the in-app store.
+*
+* Concrete (NOT abstract) so `inApp.configure({ model })` can
+* `new BaseNotificationsRepository(model)` without subclassing. The dev only
+* extends this when they need extra query methods.
+*
+* ## The single source of truth: the model's `columnMap`
+*
+* The model declares its physical columns ONCE via `static columnMap`. The
+* constructor resolves that map and derives BOTH sides from it:
+*
+*  - the READ path — `filterBy` maps logical keys (`recipientId`, `unread`,
+*    `type`, …) onto the model's columns; `RepositoryManager` applies it.
+*  - the WRITE / UPDATE / DELETE path — `createFor` / `markRead` / … translate
+*    logical keys through the same `filterBy` via `toRow`.
+*
+* Because both come from one `columnMap`, reads and writes can never target
+* different columns. `unread` is mode-agnostic: it filters `is_read = false`
+* when the model has that flag, otherwise `read_at IS NULL`.
+*
+* @example  default (SQL snake_case — no subclass needed)
+*   inApp.configure({ model: Notification })
+*
+* @example  custom columns — declare them on the model, not here
+*   class Notification extends DatabaseNotification {
+*     public static columnMap = { recipient: "audience_id", isRead: "seen" };
+*   }
+*/
+var BaseNotificationsRepository = class extends _warlock_js_core.RepositoryManager {
+	/** Resolved physical columns for the bound model — the single source. */
+	columns;
+	filterBy;
+	constructor(model) {
+		super();
+		if (model) this.source = model;
+		this.columns = resolveColumnMap(model?.columnMap);
+		this.filterBy = this.buildFilterBy();
+	}
+	/** The tenant column for this model, or `undefined` for single-tenant. */
+	get tenantColumn() {
+		return this.columns.tenant;
+	}
+	/**
+	* Build `filterBy` from the resolved column map. `unread` is the
+	* mode-agnostic read filter; `isRead` / `readAt` / `tenant` are exposed for
+	* direct filtering only when the model declares those columns.
+	*/
+	buildFilterBy() {
+		const { recipient, tenant, readAt, isRead } = this.columns;
+		const rules = {
+			id: "=",
+			type: "=",
+			recipientId: ["=", recipient],
+			idempotencyKey: ["=", "idempotency_key"],
+			unread: (value, query) => {
+				if (value !== true && value !== "true") return;
+				if (isRead) query.where(isRead, false);
+				else if (readAt) query.whereNull(readAt);
+			}
+		};
+		if (isRead) rules.isRead = ["=", isRead];
+		if (readAt) rules.readAt = ["=", readAt];
+		if (tenant) rules.tenant = ["=", tenant];
+		return rules;
+	}
+	/**
+	* Translate an object keyed by LOGICAL names into one keyed by PHYSICAL
+	* columns, using `filterBy` as the lookup. Keys with no `[op, column]` tuple
+	* (e.g. `title`, `body`, `payload`, `type`, `id`) pass through unchanged —
+	* they're already physical. Used for every write / update / delete payload +
+	* filter (the paths `RepositoryManager` does NOT map).
+	*/
+	toRow(obj) {
+		const rules = this.filterBy;
+		const row = {};
+		for (const [logical, value] of Object.entries(obj)) {
+			const rule = rules[logical];
+			const column = Array.isArray(rule) ? rule[1] : logical;
+			row[column] = value;
+		}
+		return row;
+	}
+	/**
+	* Create one row for the recipient. New rows start unread; the tenant column
+	* (when the model declares one) is written from `tenantId`, which the
+	* database channel reads off the recipient.
+	*
+	* Idempotency: when `input.idempotencyKey` is set, find-or-create — return
+	* the existing row instead of inserting a duplicate. A unique index on the
+	* key is the backstop for the rare insert race (we re-fetch on conflict).
+	*/
+	async createFor(recipientId, input, tenantId) {
+		const { idempotencyKey } = input;
+		if (idempotencyKey) {
+			const existing = await this.firstByIdempotencyKey(recipientId, idempotencyKey);
+			if (existing) return existing;
+		}
+		const row = {
+			recipientId,
+			...input
+		};
+		if (this.columns.isRead) row.isRead = false;
+		if (this.columns.tenant && tenantId !== void 0) row.tenant = tenantId;
+		try {
+			return await this.create(this.toRow(row));
+		} catch (error) {
+			if (idempotencyKey) {
+				const existing = await this.firstByIdempotencyKey(recipientId, idempotencyKey);
+				if (existing) return existing;
+			}
+			throw error;
+		}
+	}
+	/**
+	* Bulk-create one row per recipient sharing the same input + tenant. Reserved
+	* for the Phase-2 `Channel.sendMany` fan-out hook; not on the per-recipient
+	* send path yet.
+	*/
+	createManyFor(recipientIds, input, tenantId) {
+		return Promise.all(recipientIds.map((recipientId) => this.createFor(recipientId, input, tenantId)));
+	}
+	/**
+	* Mark rows read — recipient-scoped. `id` omitted → all unread rows for the
+	* recipient; `id` given → that one row, still scoped to the recipient. Scoped
+	* to unread so a re-mark never overwrites an earlier `read_at` timestamp.
+	* Sets whichever read-state column(s) the model declares.
+	*/
+	markRead(recipientId, id) {
+		const { isRead, readAt } = this.columns;
+		const unreadScope = isRead ? { isRead: false } : { readAt: null };
+		const data = {};
+		if (isRead) data.isRead = true;
+		if (readAt) data.readAt = /* @__PURE__ */ new Date();
+		return this.updateMany(this.toRow({
+			recipientId,
+			...unreadScope,
+			...id !== void 0 ? { id } : {}
+		}), this.toRow(data));
+	}
+	/**
+	* Inverse of `markRead`, same recipient-scoping. No unread scope needed —
+	* clearing the read-state of an already-unread row is a no-op.
+	*/
+	markUnread(recipientId, id) {
+		const { isRead, readAt } = this.columns;
+		const data = {};
+		if (isRead) data.isRead = false;
+		if (readAt) data.readAt = null;
+		return this.updateMany(this.toRow({
+			recipientId,
+			...id !== void 0 ? { id } : {}
+		}), this.toRow(data));
+	}
+	/** Find one row for a recipient (read path — `filterBy` maps the keys). */
+	findFor(recipientId, id) {
+		return this.first({
+			recipientId,
+			id
+		});
+	}
+	/**
+	* Delete rows — recipient-scoped. `id` omitted → clear all for the
+	* recipient; `id` given → that one row.
+	*/
+	deleteFor(recipientId, id) {
+		return this.deleteMany(this.toRow({
+			recipientId,
+			...id !== void 0 ? { id } : {}
+		}));
+	}
+	/** Read path — `filterBy` maps `recipientId`/`idempotencyKey` to columns. */
+	firstByIdempotencyKey(recipientId, idempotencyKey) {
+		return this.first({
+			recipientId,
+			idempotencyKey
+		});
+	}
+};
+
+//#endregion
+//#region ../@warlock.js/notifications/src/in-app/database-notification.ts
+/**
+* Shipped BASE in-app notification model. The scaffolded user model
+* `extends DatabaseNotification`, sets `static table`, and declares its
+* physical columns ONCE via `static columnMap`. Every accessor below derives
+* from that map, so the model, the repository, and the migration agree by
+* construction.
+*
+* The package ships NO concrete table or migration — those eject to userland
+* (thin eject). See `notificationColumns()` for the matching migration factory.
+*
+* @example
+*   @RegisterModel()
+*   export class Notification extends DatabaseNotification {
+*     public static table = "notifications";
+*     public static columnMap: NotificationColumnMap = {
+*       tenant: "organization_id",
+*       readAt: "read_at",
+*     };
+*   }
+*/
+var DatabaseNotification = class extends _warlock_js_cascade.Model {
+	/**
+	* Physical column bindings for THIS model's table. Override in the subclass;
+	* the empty default resolves to `{ recipient: "user_id", readAt: "read_at" }`.
+	*/
+	static columnMap = {};
+	/** The resolved column map for this row's model — defaults applied. */
+	get columns() {
+		return resolveColumnMap(this.constructor.columnMap);
+	}
+	get recipientId() {
+		return this.get(this.columns.recipient);
+	}
+	/** Tenant scope value, or `undefined` for single-tenant models. */
+	get tenantId() {
+		const { tenant } = this.columns;
+		return tenant ? this.get(tenant) : void 0;
+	}
+	get type() {
+		return this.get("type");
+	}
+	get isRead() {
+		const { isRead, readAt } = this.columns;
+		if (isRead) return Boolean(this.get(isRead));
+		return readAt ? this.get(readAt) != null : false;
+	}
+	get readAt() {
+		const { readAt } = this.columns;
+		return readAt ? this.get(readAt) ?? null : null;
+	}
+	/**
+	* Mark this row read. Sets whichever read-state column(s) the model
+	* declares — the boolean (fast unread filtering) and/or the timestamp
+	* (when it was read). Persists via `save()`.
+	*/
+	async markRead() {
+		const { isRead, readAt } = this.columns;
+		if (isRead) this.set(isRead, true);
+		if (readAt) this.set(readAt, /* @__PURE__ */ new Date());
+		await this.save();
+	}
+};
+
+//#endregion
+//#region ../@warlock.js/notifications/src/in-app/in-app.ts
+const idOf = (recipient) => typeof recipient === "object" ? recipient.id : recipient;
+var InApp = class {
+	repo;
+	/**
+	* Bind the in-app store AND return the `database` channel. Called once
+	* from `config/notifications.ts`. Subsequent calls REPLACE the binding.
+	*/
+	configure(options) {
+		this.repo = "repository" in options && options.repository ? options.repository : new BaseNotificationsRepository(options.model);
+		return databaseChannel(this.repo);
+	}
+	get repository() {
+		if (!this.repo) throw new Error("In-app notifications not configured — add `database: inApp.configure({ model: Notification })` to config/notifications.ts");
+		return this.repo;
+	}
+	/** General list — scoped to recipient; pass `options` for paging + filters. */
+	list(recipient, options) {
+		return this.repository.list({
+			...options,
+			recipientId: idOf(recipient)
+		});
+	}
+	/** Unread-only list — common case for badges + dashboards. */
+	listUnread(recipient, options) {
+		return this.repository.list({
+			...options,
+			recipientId: idOf(recipient),
+			unread: true
+		});
+	}
+	/**
+	* Cached unread count — backs the badge. Auto-invalidated by the repo's
+	* model create/update events (`RepositoryManager.registerEvents`).
+	*/
+	countUnread(recipient) {
+		return this.repository.countCached({
+			recipientId: idOf(recipient),
+			unread: true
+		});
+	}
+	/** Find one notification for a recipient — for a detail view. */
+	find(recipient, id) {
+		return this.repository.findFor(idOf(recipient), id);
+	}
+	/** Mark read — `id` omitted = all unread for this recipient. */
+	markAsRead(recipient, id) {
+		return this.repository.markRead(idOf(recipient), id);
+	}
+	/** Mark unread — same recipient-scoping. */
+	markAsUnread(recipient, id) {
+		return this.repository.markUnread(idOf(recipient), id);
+	}
+	/** Delete/dismiss — `id` omitted = clear all for this recipient. */
+	dismiss(recipient, id) {
+		return this.repository.deleteFor(idOf(recipient), id);
+	}
+};
+/** Single in-app facade — bound at boot via `inApp.configure(...)`. */
+const inApp = new InApp();
+
+//#endregion
+//#region ../@warlock.js/notifications/src/migration/notification-columns.ts
+/**
+* Column factory for the notifications table, driven by the model's
+* `columnMap`. The recipient / read-state / tenant columns take the NAMES the
+* model declares, so the table, the repository, and the model accessors all
+* agree by construction. The stable lexical columns (`type`, `title`, `body`,
+* `payload`, `idempotency_key`) keep fixed names.
+*
+* Read-state follows the map's presence rules (see `NotificationColumnMap`):
+* `readAt` → a nullable timestamp, `isRead` → an indexed boolean, both → both.
+*
+* Spread + extend for app-specific extras (FK references, composite indexes).
+*
+* @example
+*   import { Migration } from "@warlock.js/cascade";
+*   import { notificationColumns } from "@warlock.js/notifications";
+*   import { Notification } from "../notification.model";
+*
+*   export default Migration.create(Notification, notificationColumns(Notification));
+*
+* @example  // with extras (multi-tenant FK)
+*   export default Migration.create(Notification, {
+*     ...notificationColumns(Notification),
+*     organization_id: uuid().references(Organization.table).notNullable(),
+*   });
+*/
+/**
+* Returns the column map for a notification table, named from the model's
+* `columnMap`. Without a model, falls back to the resolved defaults
+* (`user_id` recipient + `read_at` read-state).
+*/
+function notificationColumns(model) {
+	const { recipient, tenant, readAt, isRead } = resolveColumnMap(model?.columnMap);
+	const columns = {
+		[recipient]: (0, _warlock_js_cascade.uuid)().index().notNullable(),
+		type: (0, _warlock_js_cascade.string)().index().notNullable(),
+		title: (0, _warlock_js_cascade.string)().notNullable(),
+		body: (0, _warlock_js_cascade.text)().nullable(),
+		payload: (0, _warlock_js_cascade.json)().nullable()
+	};
+	if (readAt) columns[readAt] = (0, _warlock_js_cascade.timestamp)().nullable();
+	if (isRead) columns[isRead] = (0, _warlock_js_cascade.boolCol)().default(false).index();
+	if (tenant) columns[tenant] = (0, _warlock_js_cascade.uuid)().index().notNullable();
+	columns.idempotency_key = (0, _warlock_js_cascade.string)().nullable().unique();
+	return columns;
+}
+
+//#endregion
+//#region ../@warlock.js/notifications/src/queue/load-herald.ts
+/**
+* Lazily load `@warlock.js/herald` — the optional peer backing `.queue()`.
+*
+* Memoized: the dynamic import runs at most once. A missing package surfaces a
+* curated install message at use time rather than a boot-time resolution error
+* (the lazy-optional-peer pattern used across the framework's drivers).
+*/
+let heraldModule;
+const INSTALL_INSTRUCTIONS = `
+The notifications queue requires the @warlock.js/herald package.
+Install it with:
+
+  npm install @warlock.js/herald
+
+Or with your preferred package manager:
+
+  pnpm add @warlock.js/herald
+  yarn add @warlock.js/herald
+`.trim();
+async function loadHerald() {
+	if (heraldModule) return heraldModule;
+	try {
+		heraldModule = await import("@warlock.js/herald");
+		return heraldModule;
+	} catch {
+		throw new Error(INSTALL_INSTRUCTIONS);
+	}
+}
+/** The herald channel notification jobs are published to / consumed from. */
+const DEFAULT_QUEUE_CHANNEL = "notifications.dispatch";
+
+//#endregion
+//#region ../@warlock.js/notifications/src/queue/herald-queue.ts
+function heraldQueue(options = {}) {
+	const channelName = options.channel ?? "notifications.dispatch";
+	return { async dispatch(job) {
+		const { herald } = await loadHerald();
+		await herald(options.broker).channel(channelName).publish(job);
+	} };
+}
+
+//#endregion
+//#region ../@warlock.js/notifications/src/queue/notifications-worker.ts
+/**
+* Notification queue worker — consumes the jobs `heraldQueue` publishes and
+* runs the actual `channel.send`. Call this once in a worker process (or the
+* web process) after the notifications config + herald broker are up.
+*
+* The job carries an ALREADY-RENDERED payload + resolved route, so the worker
+* only looks the channel up by name and dispatches — no notifiable needed.
+*
+* @example
+*   // in a worker entrypoint, after the notifications config + broker are up
+*   import { startNotificationsWorker } from "@warlock.js/notifications";
+*   await startNotificationsWorker();
+*/
+async function startNotificationsWorker(options = {}) {
+	const channelName = options.channel ?? "notifications.dispatch";
+	const { herald } = await loadHerald();
+	await herald(options.broker).channel(channelName).subscribe(async (message, ctx) => {
+		const job = message.payload;
+		try {
+			const channel = getNotificationConfig().channels[job.channel];
+			if (!channel) {
+				_warlock_js_logger.log.error("notifications", "queue.worker", `Unknown channel "${job.channel}" — dropping job`);
+				await ctx.ack();
+				return;
+			}
+			await channel.send({
+				payload: job.payload,
+				route: job.route,
+				options: job.options
+			});
+			await ctx.ack();
+		} catch (error) {
+			_warlock_js_logger.log.error("notifications", "queue.worker", error);
+			await ctx.ack();
+		}
+	});
+}
+
+//#endregion
+exports.BaseNotificationsRepository = BaseNotificationsRepository;
+exports.ChannelNotFoundError = ChannelNotFoundError;
+exports.DEFAULT_QUEUE_CHANNEL = DEFAULT_QUEUE_CHANNEL;
+exports.DatabaseNotification = DatabaseNotification;
+exports.MissingRendererError = MissingRendererError;
+exports.NoQueueDispatcherError = NoQueueDispatcherError;
+exports.NotificationsNotConfiguredError = NotificationsNotConfiguredError;
+exports.UnresolvableRouteError = UnresolvableRouteError;
+exports.databaseChannel = databaseChannel;
+exports.defineChannel = defineChannel;
+exports.defineNotification = defineNotification;
+exports.getNotificationConfig = getNotificationConfig;
+exports.heraldQueue = heraldQueue;
+exports.inApp = inApp;
+exports.mailChannel = mailChannel;
+exports.notificationColumns = notificationColumns;
+exports.notifications = notifications;
+exports.notify = notify;
+exports.resetNotificationConfig = resetNotificationConfig;
+exports.resolveColumnMap = resolveColumnMap;
+exports.setNotificationConfig = setNotificationConfig;
+exports.startNotificationsWorker = startNotificationsWorker;
+//# sourceMappingURL=index.cjs.map