@warlock.js/notifications 4.2.0

package/esm/dispatch/define-channel.mjs

@@ -0,0 +1,39 @@
+//#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
+export { defineChannel };
+//# sourceMappingURL=define-channel.mjs.map

package/esm/dispatch/define-channel.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-channel.mjs","names":[],"sources":["../../../../../../../@warlock.js/notifications/src/dispatch/define-channel.ts"],"sourcesContent":["import type { Channel } from \"../contracts\";\n\n/**\n * Identity helper that narrows the channel type to its payload. Use it when\n * you want TypeScript to enforce the `send` payload shape against the\n * payload type you declared.\n *\n * Built-in channels (`mail`, `database`) ship as factories; custom channels\n * are usually defined with this helper.\n *\n * @example\n *   import { defineChannel } from \"@warlock.js/notifications\";\n *\n *   type DiscordPayload = { content: string };\n *\n *   export const discordChannel = () =>\n *     defineChannel<DiscordPayload>({\n *       name: \"discord\",\n *       route: (n) => n.get(\"discord_webhook\"),\n *       async send({ payload, route }) {\n *         await fetch(route as string, {\n *           method: \"POST\",\n *           headers: { \"content-type\": \"application/json\" },\n *           body: JSON.stringify(payload),\n *         });\n *       },\n *     });\n *\n *   // Then teach the registry:\n *   declare module \"@warlock.js/notifications\" {\n *     interface NotificationChannels { discord: DiscordPayload }\n *   }\n */\nexport function defineChannel<P>(channel: Channel<P>): Channel<P> {\n  return channel;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,SAAgB,cAAiB,SAAiC;CAChE,OAAO;AACT"}

package/esm/dispatch/define-notification.d.mts

@@ -0,0 +1,22 @@
+import { ChannelName, Notifiable, NotificationChannels, RenderContext, SendOptions } from "../types.mjs";
+
+//#region ../@warlock.js/notifications/src/dispatch/define-notification.d.ts
+/**
+ * Per-channel renderer return type. The `database` renderer may OMIT `type`
+ * — it inherits from `NotificationDef.type` at dispatch time.
+ */
+type RendererReturn<C extends ChannelName> = C extends "database" ? Omit<NotificationChannels["database"], "type"> : NotificationChannels[C];
+type Renderer<Data, C extends ChannelName> = (data: Data, to: Notifiable, ctx: RenderContext) => RendererReturn<C>;
+type NotificationDef<Data> = {
+  type: string;
+  via: ChannelName[] | ((data: Data, to: Notifiable) => ChannelName[]);
+} & { [C in ChannelName]?: Renderer<Data, C> };
+interface DefinedNotification<Data> {
+  send(to: Notifiable | Notifiable[], data: Data, options?: SendOptions): Promise<void>;
+  queue(to: Notifiable | Notifiable[], data: Data, options?: SendOptions): Promise<void>;
+  only(...channels: ChannelName[]): DefinedNotification<Data>;
+}
+declare function defineNotification<Data>(def: NotificationDef<Data>): DefinedNotification<Data>;
+//#endregion
+export { DefinedNotification, NotificationDef, defineNotification };
+//# sourceMappingURL=define-notification.d.mts.map

package/esm/dispatch/define-notification.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-notification.d.mts","names":[],"sources":["../../../../../../../@warlock.js/notifications/src/dispatch/define-notification.ts"],"mappings":";;;;;AA4CkB;;KASb,cAAA,WAAyB,WAAA,IAAe,CAAA,sBACzC,IAAA,CAAK,oBAAA,wBACL,oBAAA,CAAqB,CAAA;AAAA,KAEpB,QAAA,iBAAyB,WAAA,KAC5B,IAAA,EAAM,IAAA,EACN,EAAA,EAAI,UAAA,EACJ,GAAA,EAAK,aAAA,KACF,cAAA,CAAe,CAAA;AAAA,KAER,eAAA;EACV,IAAA;EACA,GAAA,EAAK,WAAA,OAAkB,IAAA,EAAM,IAAA,EAAM,EAAA,EAAI,UAAA,KAAe,WAAA;AAAA,YAEhD,WAAA,IAAe,QAAA,CAAS,IAAA,EAAM,CAAA;AAAA,UAGrB,mBAAA;EACf,IAAA,CAAK,EAAA,EAAI,UAAA,GAAa,UAAA,IAAc,IAAA,EAAM,IAAA,EAAM,OAAA,GAAU,WAAA,GAAc,OAAA;EACxE,KAAA,CAAM,EAAA,EAAI,UAAA,GAAa,UAAA,IAAc,IAAA,EAAM,IAAA,EAAM,OAAA,GAAU,WAAA,GAAc,OAAA;EACzE,IAAA,IAAQ,QAAA,EAAU,WAAA,KAAgB,mBAAA,CAAoB,IAAA;AAAA;AAAA,iBAYxC,kBAAA,OAAyB,GAAA,EAAK,eAAA,CAAgB,IAAA,IAAQ,mBAAA,CAAoB,IAAA"}

package/esm/dispatch/define-notification.mjs

@@ -0,0 +1,125 @@
+import { ChannelNotFoundError, MissingRendererError, NoQueueDispatcherError } from "../errors.mjs";
+import { getNotificationConfig } from "../config.mjs";
+import { newDispatchId } from "./dispatch-id.mjs";
+import { emit } from "./notifications-event-bus.mjs";
+import { dispatchChannel } from "./dispatcher.mjs";
+import { log } from "@warlock.js/logger";
+
+//#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) {
+		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
+export { defineNotification };
+//# sourceMappingURL=define-notification.mjs.map

package/esm/dispatch/define-notification.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-notification.mjs","names":[],"sources":["../../../../../../../@warlock.js/notifications/src/dispatch/define-notification.ts"],"sourcesContent":["/**\n * `defineNotification` — reusable, type-safe, multi-channel notification.\n *\n * Functional, not class-based: pass `via` + a renderer per channel + a\n * stable `type`. The returned object exposes `.send` / `.queue` / `.only`.\n *\n * Renderer signature is `(data, to, ctx)` where `ctx` carries `locale` and\n * `meta` from `SendOptions`. The database renderer's `type` is OPTIONAL — the\n * dispatcher injects `def.type`, keeping the type defined in ONE place.\n *\n * ## Error policy\n * - **Config errors** (missing renderer, no queue dispatcher, unknown channel)\n *   are programmer mistakes → they REJECT `.send()`/`.queue()` (and a static\n *   `via` with a missing renderer throws at definition time). Consistent with\n *   `notify`, which rejects `ChannelNotFoundError`.\n * - **Transport errors** (a channel's `send` throwing) stay ISOLATED — emitted\n *   as a `failed` event, never aborting sibling channels/recipients.\n * - **`via()` / preferences throws** for one recipient are logged and that\n *   recipient is dropped (the rest of a fan-out still go).\n *\n * @example\n *   export const orderShipped = defineNotification<{ order: Order }>({\n *     type: \"order.shipped\",\n *     via: [\"mail\", \"database\"],\n *     mail: ({ order }, to) => ({ subject: `#${order.number} shipped`, html: \"…\" }),\n *     database: ({ order }) => ({ title: \"Your order shipped\", payload: { id: order.id } }),\n *   });\n *   await orderShipped.send(user, { order });\n *   await orderShipped.queue([buyer, salesRep], { order }, { delay: \"10m\" });\n *   await orderShipped.only(\"mail\").send(user, { order });\n */\nimport { log } from \"@warlock.js/logger\";\nimport { getNotificationConfig } from \"../config\";\nimport {\n  ChannelNotFoundError,\n  MissingRendererError,\n  NoQueueDispatcherError,\n} from \"../errors\";\nimport type {\n  ChannelName,\n  Notifiable,\n  NotificationChannels,\n  RenderContext,\n  SendOptions,\n} from \"../types\";\nimport { newDispatchId } from \"./dispatch-id\";\nimport { dispatchChannel, type DispatchMode } from \"./dispatcher\";\nimport { emit } from \"./notifications-event-bus\";\n\n/**\n * Per-channel renderer return type. The `database` renderer may OMIT `type`\n * — it inherits from `NotificationDef.type` at dispatch time.\n */\ntype RendererReturn<C extends ChannelName> = C extends \"database\"\n  ? Omit<NotificationChannels[\"database\"], \"type\">\n  : NotificationChannels[C];\n\ntype Renderer<Data, C extends ChannelName> = (\n  data: Data,\n  to: Notifiable,\n  ctx: RenderContext,\n) => RendererReturn<C>;\n\nexport type NotificationDef<Data> = {\n  type: string;\n  via: ChannelName[] | ((data: Data, to: Notifiable) => ChannelName[]);\n} & {\n  [C in ChannelName]?: Renderer<Data, C>;\n};\n\nexport interface DefinedNotification<Data> {\n  send(to: Notifiable | Notifiable[], data: Data, options?: SendOptions): Promise<void>;\n  queue(to: Notifiable | Notifiable[], data: Data, options?: SendOptions): Promise<void>;\n  only(...channels: ChannelName[]): DefinedNotification<Data>;\n}\n\n/** Errors that represent a misconfiguration and must surface (reject), not isolate. */\nfunction isConfigError(error: unknown): boolean {\n  return (\n    error instanceof MissingRendererError ||\n    error instanceof NoQueueDispatcherError ||\n    error instanceof ChannelNotFoundError\n  );\n}\n\nexport function defineNotification<Data>(def: NotificationDef<Data>): DefinedNotification<Data> {\n  const make = (restrict?: ChannelName[]): DefinedNotification<Data> => {\n    // Validate at definition time when the channel set is static — a missing\n    // renderer is a programmer error, surfaced loudly at import.\n    if (Array.isArray(def.via)) {\n      const channels = restrict ? def.via.filter((c) => restrict.includes(c)) : def.via;\n      for (const channel of channels) {\n        if (!def[channel]) {\n          throw new MissingRendererError(def.type, channel);\n        }\n      }\n    }\n\n    return {\n      send(to, data, options) {\n        return dispatchAll(def, to, data, options ?? {}, \"send\", restrict);\n      },\n      queue(to, data, options) {\n        return dispatchAll(def, to, data, options ?? {}, \"queue\", restrict);\n      },\n      only(...channels) {\n        return make(channels);\n      },\n    };\n  };\n\n  return make();\n}\n\n/**\n * Fan-out to all recipients. Each recipient dispatches independently; one\n * recipient's transport failure never aborts the others. CONFIG errors,\n * however, propagate — they reject the returned promise.\n */\nasync function dispatchAll<Data>(\n  def: NotificationDef<Data>,\n  to: Notifiable | Notifiable[],\n  data: Data,\n  options: SendOptions,\n  mode: DispatchMode,\n  restrict?: ChannelName[],\n): Promise<void> {\n  const recipients = Array.isArray(to) ? to : [to];\n\n  const results = await Promise.allSettled(\n    recipients.map((recipient) =>\n      dispatchToRecipient(def, recipient, data, options, mode, restrict),\n    ),\n  );\n\n  rethrowConfigErrors(results);\n}\n\nasync function dispatchToRecipient<Data>(\n  def: NotificationDef<Data>,\n  to: Notifiable,\n  data: Data,\n  options: SendOptions,\n  mode: DispatchMode,\n  restrict?: ChannelName[],\n): Promise<void> {\n  const config = getNotificationConfig();\n\n  // Resolve channels (via + preferences). A throw here drops THIS recipient\n  // with a log — it's a per-recipient data problem, not a config error.\n  let channels: ChannelName[];\n  try {\n    channels = typeof def.via === \"function\" ? def.via(data, to) : [...def.via];\n\n    if (restrict) {\n      channels = channels.filter((c) => restrict.includes(c));\n    }\n\n    if (!options.force && config.preferences) {\n      const allowed = await config.preferences.resolveChannels(to, def.type, channels);\n      for (const channel of channels.filter((c) => !allowed.includes(c))) {\n        await emit(\"skipped\", {\n          dispatchId: newDispatchId(),\n          channel,\n          notifiable: to,\n          reason: \"preference\",\n          options,\n        });\n      }\n      channels = channels.filter((c) => allowed.includes(c));\n    }\n  } catch (error) {\n    log.error(\"notifications\", `resolve.${def.type}`, error as Error);\n    return;\n  }\n\n  const renderCtx: RenderContext = { locale: options.locale, meta: options.meta };\n\n  const results = await Promise.allSettled(\n    channels.map((name) => {\n      const renderer = def[name] as Renderer<Data, ChannelName> | undefined;\n      if (!renderer) {\n        // Dynamic via chose a channel with no renderer — surface it.\n        return Promise.reject(new MissingRendererError(def.type, name));\n      }\n\n      let payload: unknown = renderer(data, to, renderCtx);\n\n      // Default the database channel's `type` from `def.type` when omitted.\n      if (name === \"database\" && payload && typeof payload === \"object\" && !(\"type\" in payload)) {\n        payload = { ...(payload as object), type: def.type };\n      }\n\n      return dispatchChannel({\n        channelName: name,\n        payload,\n        to,\n        notificationType: def.type,\n        mode,\n        options,\n      });\n    }),\n  );\n\n  rethrowConfigErrors(results);\n}\n\n/** Collect config-class rejections and rethrow (single or AggregateError). */\nfunction rethrowConfigErrors(results: PromiseSettledResult<unknown>[]): void {\n  const configErrors = results\n    .filter((r): r is PromiseRejectedResult => r.status === \"rejected\" && isConfigError(r.reason))\n    .map((r) => r.reason);\n\n  if (configErrors.length === 1) {\n    throw configErrors[0];\n  }\n  if (configErrors.length > 1) {\n    throw new AggregateError(configErrors, \"Multiple notification configuration errors\");\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6EA,SAAS,cAAc,OAAyB;CAC9C,OACE,iBAAiB,wBACjB,iBAAiB,0BACjB,iBAAiB;AAErB;AAEA,SAAgB,mBAAyB,KAAuD;CAC9F,MAAM,QAAQ,aAAwD;EAGpE,IAAI,MAAM,QAAQ,IAAI,GAAG,GAAG;GAC1B,MAAM,WAAW,WAAW,IAAI,IAAI,QAAQ,MAAM,SAAS,SAAS,CAAC,CAAC,IAAI,IAAI;GAC9E,KAAK,MAAM,WAAW,UACpB,IAAI,CAAC,IAAI,UACP,MAAM,IAAI,qBAAqB,IAAI,MAAM,OAAO;EAGtD;EAEA,OAAO;GACL,KAAK,IAAI,MAAM,SAAS;IACtB,OAAO,YAAY,KAAK,IAAI,MAAM,WAAW,CAAC,GAAG,QAAQ,QAAQ;GACnE;GACA,MAAM,IAAI,MAAM,SAAS;IACvB,OAAO,YAAY,KAAK,IAAI,MAAM,WAAW,CAAC,GAAG,SAAS,QAAQ;GACpE;GACA,KAAK,GAAG,UAAU;IAChB,OAAO,KAAK,QAAQ;GACtB;EACF;CACF;CAEA,OAAO,KAAK;AACd;;;;;;AAOA,eAAe,YACb,KACA,IACA,MACA,SACA,MACA,UACe;CACf,MAAM,aAAa,MAAM,QAAQ,EAAE,IAAI,KAAK,CAAC,EAAE;CAQ/C,oBAAoB,MANE,QAAQ,WAC5B,WAAW,KAAK,cACd,oBAAoB,KAAK,WAAW,MAAM,SAAS,MAAM,QAAQ,CACnE,CACF,CAE2B;AAC7B;AAEA,eAAe,oBACb,KACA,IACA,MACA,SACA,MACA,UACe;CACf,MAAM,SAAS,sBAAsB;CAIrC,IAAI;CACJ,IAAI;EACF,WAAW,OAAO,IAAI,QAAQ,aAAa,IAAI,IAAI,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI,GAAG;EAE1E,IAAI,UACF,WAAW,SAAS,QAAQ,MAAM,SAAS,SAAS,CAAC,CAAC;EAGxD,IAAI,CAAC,QAAQ,SAAS,OAAO,aAAa;GACxC,MAAM,UAAU,MAAM,OAAO,YAAY,gBAAgB,IAAI,IAAI,MAAM,QAAQ;GAC/E,KAAK,MAAM,WAAW,SAAS,QAAQ,MAAM,CAAC,QAAQ,SAAS,CAAC,CAAC,GAC/D,MAAM,KAAK,WAAW;IACpB,YAAY,cAAc;IAC1B;IACA,YAAY;IACZ,QAAQ;IACR;GACF,CAAC;GAEH,WAAW,SAAS,QAAQ,MAAM,QAAQ,SAAS,CAAC,CAAC;EACvD;CACF,SAAS,OAAO;EACd,IAAI,MAAM,iBAAiB,WAAW,IAAI,QAAQ,KAAc;EAChE;CACF;CAEA,MAAM,YAA2B;EAAE,QAAQ,QAAQ;EAAQ,MAAM,QAAQ;CAAK;CA4B9E,oBAAoB,MA1BE,QAAQ,WAC5B,SAAS,KAAK,SAAS;EACrB,MAAM,WAAW,IAAI;EACrB,IAAI,CAAC,UAEH,OAAO,QAAQ,OAAO,IAAI,qBAAqB,IAAI,MAAM,IAAI,CAAC;EAGhE,IAAI,UAAmB,SAAS,MAAM,IAAI,SAAS;EAGnD,IAAI,SAAS,cAAc,WAAW,OAAO,YAAY,YAAY,EAAE,UAAU,UAC/E,UAAU;GAAE,GAAI;GAAoB,MAAM,IAAI;EAAK;EAGrD,OAAO,gBAAgB;GACrB,aAAa;GACb;GACA;GACA,kBAAkB,IAAI;GACtB;GACA;EACF,CAAC;CACH,CAAC,CACH,CAE2B;AAC7B;;AAGA,SAAS,oBAAoB,SAAgD;CAC3E,MAAM,eAAe,QAClB,QAAQ,MAAkC,EAAE,WAAW,cAAc,cAAc,EAAE,MAAM,CAAC,CAAC,CAC7F,KAAK,MAAM,EAAE,MAAM;CAEtB,IAAI,aAAa,WAAW,GAC1B,MAAM,aAAa;CAErB,IAAI,aAAa,SAAS,GACxB,MAAM,IAAI,eAAe,cAAc,4CAA4C;AAEvF"}

package/esm/dispatch/dispatch-id.mjs

@@ -0,0 +1,15 @@
+import { randomUUID } from "node:crypto";
+
+//#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 randomUUID();
+}
+
+//#endregion
+export { newDispatchId };
+//# sourceMappingURL=dispatch-id.mjs.map

package/esm/dispatch/dispatch-id.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-id.mjs","names":[],"sources":["../../../../../../../@warlock.js/notifications/src/dispatch/dispatch-id.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\n\n/**\n * A unique id for one (channel, recipient) dispatch. `sending` and its terminal\n * `sent` / `failed` event share it so observers can pair them — for tracing\n * spans, latency, or spotting a `sending` with no terminal (a hung send).\n */\nexport function newDispatchId(): string {\n  return randomUUID();\n}\n"],"mappings":";;;;;;;;AAOA,SAAgB,gBAAwB;CACtC,OAAO,WAAW;AACpB"}

package/esm/dispatch/dispatcher.mjs

@@ -0,0 +1,120 @@
+import { ChannelNotFoundError, NoQueueDispatcherError, UnresolvableRouteError } from "../errors.mjs";
+import { getNotificationConfig } from "../config.mjs";
+import { newDispatchId } from "./dispatch-id.mjs";
+import { emit } from "./notifications-event-bus.mjs";
+
+//#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
+export { dispatchChannel };
+//# sourceMappingURL=dispatcher.mjs.map

package/esm/dispatch/dispatcher.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.mjs","names":[],"sources":["../../../../../../../@warlock.js/notifications/src/dispatch/dispatcher.ts"],"sourcesContent":["/**\n * Internal dispatch core — shared by `defineNotification` and `notify.<channel>`.\n *\n * Responsibilities:\n * 1. Look up the channel in the configured registry (throws if missing).\n * 2. Run the rate-limit gate (if a notification type is known) — drop with a\n *    `skipped` event when the limiter refuses.\n * 3. Resolve the route: raw string > channel.route(notifiable) > { id }.\n * 4. Inject the per-send `idempotencyKey` into the database payload.\n * 5. Dispatch (sync via channel.send OR async via queue.dispatch).\n * 6. Emit `sent` on success, `failed` on throw.\n *\n * Per-channel failure isolation is the CALLER's job (it wraps a list of\n * `dispatchChannel` calls in `Promise.allSettled`).\n */\nimport { getNotificationConfig } from \"../config\";\nimport { ChannelNotFoundError, NoQueueDispatcherError, UnresolvableRouteError } from \"../errors\";\nimport type { ChannelName, Id, Notifiable, SendOptions } from \"../types\";\nimport { newDispatchId } from \"./dispatch-id\";\nimport { emit } from \"./notifications-event-bus\";\n\nexport type DispatchMode = \"send\" | \"queue\";\n\nexport type DispatchChannelArgs = {\n  channelName: string;\n  payload: unknown;\n  /** The recipient model — undefined when dispatching to a raw route string. */\n  to: Notifiable | undefined;\n  /** Raw route override (ad-hoc `notify.mail(\"x@y.com\", …)`). */\n  rawRoute?: string;\n  /** Notification type — drives the rate-limit gate. May be undefined. */\n  notificationType: string | undefined;\n  mode: DispatchMode;\n  options: SendOptions;\n};\n\n/**\n * Dispatch ONE rendered payload to ONE recipient through ONE channel.\n * Does NOT consult `PreferenceProvider` — that gate runs at the caller level.\n *\n * Throws `ChannelNotFoundError` (channel not registered) and\n * `UnresolvableRouteError` (channel's `route()` returned undefined) — both are\n * configuration/data errors that should surface loudly. Transport failures\n * (channel.send throwing) are emitted as `failed` AND rethrown.\n */\nexport async function dispatchChannel(args: DispatchChannelArgs): Promise<void> {\n  const config = getNotificationConfig();\n  const channel = config.channels[args.channelName as ChannelName];\n\n  if (!channel) {\n    throw new ChannelNotFoundError(args.channelName);\n  }\n\n  // One id for this (channel, recipient) dispatch — `sending` and its terminal\n  // `sent` / `failed` share it so observers can pair them.\n  const dispatchId = newDispatchId();\n\n  // Rate-limit gate. Only applies when we have a notifiable + a notification\n  // type (otherwise there's nothing to rate-limit on). `force` does NOT\n  // bypass — rate limits are a safety valve, not a UX preference.\n  //\n  // NOTE (Phase-2 seam): for mode \"queue\" the budget is consumed at ENQUEUE\n  // time here, not at delivery. When the herald worker lands it should run\n  // this gate at delivery instead; see RateLimiter docstring.\n  if (args.to && args.notificationType && config.rateLimit) {\n    const allowed = await config.rateLimit.allow(\n      args.to,\n      args.channelName as ChannelName,\n      args.notificationType,\n    );\n\n    if (!allowed) {\n      await emit(\"skipped\", {\n        dispatchId,\n        channel: args.channelName,\n        notifiable: args.to,\n        reason: \"rate-limit\",\n        options: args.options,\n      });\n      return;\n    }\n  }\n\n  const route = resolveRoute(args, channel.route);\n\n  // Inject idempotency key into the database payload (so the repo can dedupe).\n  let payload = args.payload;\n  if (\n    args.channelName === \"database\" &&\n    args.options.idempotencyKey &&\n    payload &&\n    typeof payload === \"object\"\n  ) {\n    payload = { ...(payload as object), idempotencyKey: args.options.idempotencyKey };\n  }\n\n  // `sending` fires after the gates pass + the route resolves, BEFORE the\n  // transport — awaited so it always precedes the send. Observers can't abort\n  // the send, but a slow handler delays it; keep them fast.\n  await emit(\"sending\", {\n    dispatchId,\n    channel: args.channelName,\n    notifiable: args.to,\n    payload,\n    options: args.options,\n  });\n\n  const startedAt = Date.now();\n\n  try {\n    if (args.mode === \"queue\") {\n      if (!config.queue) {\n        throw new NoQueueDispatcherError(args.channelName);\n      }\n      await config.queue.dispatch({\n        channel: args.channelName,\n        route,\n        payload,\n        options: args.options,\n      });\n    } else {\n      await channel.send({\n        payload: payload as never,\n        route,\n        notifiable: args.to,\n        options: args.options,\n      });\n    }\n\n    await emit(\"sent\", {\n      dispatchId,\n      channel: args.channelName,\n      notifiable: args.to,\n      payload,\n      options: args.options,\n      durationMs: Date.now() - startedAt,\n    });\n  } catch (error) {\n    await emit(\"failed\", {\n      dispatchId,\n      channel: args.channelName,\n      notifiable: args.to,\n      payload,\n      error: error as Error,\n      options: args.options,\n      durationMs: Date.now() - startedAt,\n    });\n    throw error;\n  }\n}\n\n/**\n * Route resolution priority:\n *   1. raw route string (ad-hoc `notify.mail(\"x@y.com\", …)`)\n *   2. the channel's `route(notifiable)` resolver\n *   3. `{ id: notifiable.id }` — ONLY when the channel declares no resolver\n *\n * When a channel HAS a resolver but it returns undefined (e.g. a mail\n * recipient with no email), we throw `UnresolvableRouteError` rather than\n * silently coercing to `{ id }` — that would hand a string-route channel an\n * object and fail deep inside the transport.\n */\nfunction resolveRoute(\n  args: DispatchChannelArgs,\n  resolver: ((notifiable: Notifiable) => string | { id: Id } | undefined) | undefined,\n): string | { id: Id } {\n  if (args.rawRoute !== undefined) {\n    return args.rawRoute;\n  }\n\n  if (!args.to) {\n    throw new UnresolvableRouteError(args.channelName);\n  }\n\n  // No resolver declared → the channel addresses by id (database/internal).\n  if (!resolver) {\n    return { id: args.to.id };\n  }\n\n  const resolved = resolver(args.to);\n\n  if (resolved === undefined) {\n    throw new UnresolvableRouteError(args.channelName, args.to.id);\n  }\n\n  return resolved;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,eAAsB,gBAAgB,MAA0C;CAC9E,MAAM,SAAS,sBAAsB;CACrC,MAAM,UAAU,OAAO,SAAS,KAAK;CAErC,IAAI,CAAC,SACH,MAAM,IAAI,qBAAqB,KAAK,WAAW;CAKjD,MAAM,aAAa,cAAc;CASjC,IAAI,KAAK,MAAM,KAAK,oBAAoB,OAAO,WAO7C;MAAI,CAAC,MANiB,OAAO,UAAU,MACrC,KAAK,IACL,KAAK,aACL,KAAK,gBACP,GAEc;GACZ,MAAM,KAAK,WAAW;IACpB;IACA,SAAS,KAAK;IACd,YAAY,KAAK;IACjB,QAAQ;IACR,SAAS,KAAK;GAChB,CAAC;GACD;EACF;;CAGF,MAAM,QAAQ,aAAa,MAAM,QAAQ,KAAK;CAG9C,IAAI,UAAU,KAAK;CACnB,IACE,KAAK,gBAAgB,cACrB,KAAK,QAAQ,kBACb,WACA,OAAO,YAAY,UAEnB,UAAU;EAAE,GAAI;EAAoB,gBAAgB,KAAK,QAAQ;CAAe;CAMlF,MAAM,KAAK,WAAW;EACpB;EACA,SAAS,KAAK;EACd,YAAY,KAAK;EACjB;EACA,SAAS,KAAK;CAChB,CAAC;CAED,MAAM,YAAY,KAAK,IAAI;CAE3B,IAAI;EACF,IAAI,KAAK,SAAS,SAAS;GACzB,IAAI,CAAC,OAAO,OACV,MAAM,IAAI,uBAAuB,KAAK,WAAW;GAEnD,MAAM,OAAO,MAAM,SAAS;IAC1B,SAAS,KAAK;IACd;IACA;IACA,SAAS,KAAK;GAChB,CAAC;EACH,OACE,MAAM,QAAQ,KAAK;GACR;GACT;GACA,YAAY,KAAK;GACjB,SAAS,KAAK;EAChB,CAAC;EAGH,MAAM,KAAK,QAAQ;GACjB;GACA,SAAS,KAAK;GACd,YAAY,KAAK;GACjB;GACA,SAAS,KAAK;GACd,YAAY,KAAK,IAAI,IAAI;EAC3B,CAAC;CACH,SAAS,OAAO;EACd,MAAM,KAAK,UAAU;GACnB;GACA,SAAS,KAAK;GACd,YAAY,KAAK;GACjB;GACO;GACP,SAAS,KAAK;GACd,YAAY,KAAK,IAAI,IAAI;EAC3B,CAAC;EACD,MAAM;CACR;AACF;;;;;;;;;;;;AAaA,SAAS,aACP,MACA,UACqB;CACrB,IAAI,KAAK,aAAa,QACpB,OAAO,KAAK;CAGd,IAAI,CAAC,KAAK,IACR,MAAM,IAAI,uBAAuB,KAAK,WAAW;CAInD,IAAI,CAAC,UACH,OAAO,EAAE,IAAI,KAAK,GAAG,GAAG;CAG1B,MAAM,WAAW,SAAS,KAAK,EAAE;CAEjC,IAAI,aAAa,QACf,MAAM,IAAI,uBAAuB,KAAK,aAAa,KAAK,GAAG,EAAE;CAG/D,OAAO;AACT"}

package/esm/dispatch/index.d.mts

@@ -0,0 +1,4 @@
+import { defineChannel } from "./define-channel.mjs";
+import { DefinedNotification, NotificationDef, defineNotification } from "./define-notification.mjs";
+import { Notify, notify } from "./notify.mjs";
+import { notifications } from "./notifications-event-bus.mjs";

package/esm/dispatch/index.mjs

@@ -0,0 +1,6 @@
+import { defineChannel } from "./define-channel.mjs";
+import { notifications } from "./notifications-event-bus.mjs";
+import { defineNotification } from "./define-notification.mjs";
+import { notify } from "./notify.mjs";
+
+export {  };

package/esm/dispatch/notifications-event-bus.d.mts

@@ -0,0 +1,18 @@
+import { NotificationEvents } from "../types.mjs";
+
+//#region ../@warlock.js/notifications/src/dispatch/notifications-event-bus.d.ts
+type EventName = keyof NotificationEvents;
+type Handler<E extends EventName> = (data: NotificationEvents[E]) => void | Promise<void>;
+/**
+ * Public observability surface.
+ *
+ * `on(event, handler)` returns an unsubscribe function. `off` exists for
+ * symmetry with libraries that hold handler references for later removal.
+ */
+declare const notifications: {
+  on<E extends EventName>(event: E, handler: Handler<E>): () => void;
+  off<E extends EventName>(event: E, handler: Handler<E>): void;
+};
+//#endregion
+export { notifications };
+//# sourceMappingURL=notifications-event-bus.d.mts.map

package/esm/dispatch/notifications-event-bus.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications-event-bus.d.mts","names":[],"sources":["../../../../../../../@warlock.js/notifications/src/dispatch/notifications-event-bus.ts"],"mappings":";;;KAkBK,SAAA,SAAkB,kBAAkB;AAAA,KACpC,OAAA,WAAkB,SAAA,KAAc,IAAA,EAAM,kBAAA,CAAmB,CAAA,aAAc,OAAA;AAHzB;;;;AAEV;AAAA;AAFU,cAkBtC,aAAA;eACE,SAAA,EAAS,KAAA,EAAS,CAAA,EAAC,OAAA,EAAW,OAAA,CAAQ,CAAA;gBAMrC,SAAA,EAAS,KAAA,EAAS,CAAA,EAAC,OAAA,EAAW,OAAA,CAAQ,CAAA;AAAA"}

package/esm/dispatch/notifications-event-bus.mjs

@@ -0,0 +1,58 @@
+import { log } from "@warlock.js/logger";
+
+//#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") log.error("notifications", "event-handler", result.reason);
+}
+
+//#endregion
+export { emit, notifications };
+//# sourceMappingURL=notifications-event-bus.mjs.map

package/esm/dispatch/notifications-event-bus.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications-event-bus.mjs","names":[],"sources":["../../../../../../../@warlock.js/notifications/src/dispatch/notifications-event-bus.ts"],"sourcesContent":["/**\n * Typed event bus for notifications observability. Emits `sent`, `failed`,\n * and `skipped` events per (channel, recipient) — fan-out emits N events.\n *\n * Intentionally minimal — a `Map<event, Set<handler>>` keeps tests trivial\n * and avoids pulling event-emitter machinery for what is fundamentally\n * pub/sub. Handler exceptions are logged-and-swallowed so one bad listener\n * cannot break the dispatcher.\n *\n * @example\n *   notifications.on(\"sent\",    ({ channel }) => metrics.inc(`notif.${channel}.sent`));\n *   notifications.on(\"skipped\", ({ reason })  => metrics.inc(`notif.skipped.${reason}`));\n *   const off = notifications.on(\"failed\", logErr);\n *   off(); // unsubscribe\n */\nimport { log } from \"@warlock.js/logger\";\nimport type { NotificationEvents } from \"../types\";\n\ntype EventName = keyof NotificationEvents;\ntype Handler<E extends EventName> = (data: NotificationEvents[E]) => void | Promise<void>;\n\nconst handlers: { [E in EventName]: Set<Handler<E>> } = {\n  sending: new Set(),\n  sent: new Set(),\n  failed: new Set(),\n  skipped: new Set(),\n};\n\n/**\n * Public observability surface.\n *\n * `on(event, handler)` returns an unsubscribe function. `off` exists for\n * symmetry with libraries that hold handler references for later removal.\n */\nexport const notifications = {\n  on<E extends EventName>(event: E, handler: Handler<E>): () => void {\n    handlers[event].add(handler as Handler<EventName>);\n    return () => {\n      handlers[event].delete(handler as Handler<EventName>);\n    };\n  },\n  off<E extends EventName>(event: E, handler: Handler<E>): void {\n    handlers[event].delete(handler as Handler<EventName>);\n  },\n};\n\n/**\n * Internal emit — used by the dispatcher. Not exported from the package.\n * Handlers run in registration order; an awaited Promise.allSettled isolates\n * each listener so one throw cannot block the others.\n */\nexport async function emit<E extends EventName>(\n  event: E,\n  data: NotificationEvents[E],\n): Promise<void> {\n  const set = handlers[event];\n  if (set.size === 0) return;\n\n  // The `async` wrapper turns SYNC handler throws into promise rejections so\n  // `Promise.allSettled` can isolate them. Without it, a `throw` inside the\n  // handler escapes the array map before allSettled gets a chance to catch.\n  const results = await Promise.allSettled(\n    Array.from(set).map(async (handler) => {\n      await (handler as Handler<E>)(data);\n    }),\n  );\n\n  for (const result of results) {\n    if (result.status === \"rejected\") {\n      log.error(\"notifications\", \"event-handler\", result.reason);\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAqBA,MAAM,WAAkD;CACtD,yBAAS,IAAI,IAAI;CACjB,sBAAM,IAAI,IAAI;CACd,wBAAQ,IAAI,IAAI;CAChB,yBAAS,IAAI,IAAI;AACnB;;;;;;;AAQA,MAAa,gBAAgB;CAC3B,GAAwB,OAAU,SAAiC;EACjE,SAAS,MAAM,CAAC,IAAI,OAA6B;EACjD,aAAa;GACX,SAAS,MAAM,CAAC,OAAO,OAA6B;EACtD;CACF;CACA,IAAyB,OAAU,SAA2B;EAC5D,SAAS,MAAM,CAAC,OAAO,OAA6B;CACtD;AACF;;;;;;AAOA,eAAsB,KACpB,OACA,MACe;CACf,MAAM,MAAM,SAAS;CACrB,IAAI,IAAI,SAAS,GAAG;CAKpB,MAAM,UAAU,MAAM,QAAQ,WAC5B,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,OAAO,YAAY;EACrC,MAAO,QAAuB,IAAI;CACpC,CAAC,CACH;CAEA,KAAK,MAAM,UAAU,SACnB,IAAI,OAAO,WAAW,YACpB,IAAI,MAAM,iBAAiB,iBAAiB,OAAO,MAAM;AAG/D"}

package/esm/dispatch/notify.d.mts

@@ -0,0 +1,20 @@
+import { ChannelName, Notifiable, NotificationChannels, SendOptions } from "../types.mjs";
+
+//#region ../@warlock.js/notifications/src/dispatch/notify.d.ts
+/**
+ * Public shape of `notify`. The mapped portion gives `notify.<channel>` per
+ * registered channel; `channel(name)` is the runtime escape.
+ */
+type Notify = {
+  channel(name: string): {
+    send(to: Notifiable | string, payload: unknown, options?: SendOptions): Promise<void>;
+  };
+} & { [C in ChannelName]: (to: Notifiable | string, payload: NotificationChannels[C], options?: SendOptions) => Promise<void> };
+/**
+ * Build the `notify` proxy. `channel(name)` returns a `{ send }` object;
+ * any other property access returns a one-shot dispatcher for that channel.
+ */
+declare const notify: Notify;
+//#endregion
+export { Notify, notify };
+//# sourceMappingURL=notify.d.mts.map

package/esm/dispatch/notify.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.d.mts","names":[],"sources":["../../../../../../../@warlock.js/notifications/src/dispatch/notify.ts"],"mappings":";;;;;AA8BA;;KAAY,MAAA;EACV,OAAA,CAAQ,IAAA;IACN,IAAA,CACE,EAAA,EAAI,UAAA,WACJ,OAAA,WACA,OAAA,GAAU,WAAA,GACT,OAAA;EAAA;AAAA,YAGC,WAAA,IACJ,EAAA,EAAI,UAAA,WACJ,OAAA,EAAS,oBAAA,CAAqB,CAAA,GAC9B,OAAA,GAAU,WAAA,KACP,OAAA;;;;;cA0EM,MAAA,EAAQ,MAuBnB"}

package/esm/dispatch/notify.mjs

@@ -0,0 +1,80 @@
+import { getNotificationConfig } from "../config.mjs";
+import { newDispatchId } from "./dispatch-id.mjs";
+import { emit } from "./notifications-event-bus.mjs";
+import { dispatchChannel } from "./dispatcher.mjs";
+
+//#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
+export { notify };
+//# sourceMappingURL=notify.mjs.map

package/esm/dispatch/notify.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.mjs","names":[],"sources":["../../../../../../../@warlock.js/notifications/src/dispatch/notify.ts"],"sourcesContent":["/**\n * `notify` — ad-hoc, per-channel send facade.\n *\n * A Proxy keyed by the channel registry. `notify.<channel>(to, payload,\n * options?)` works for ANY channel name registered in\n * `NotificationChannels` — built-in or custom (via declaration merging).\n *\n * For multi-channel sends, use `defineNotification` — that's the reusable\n * pattern and the only mental model for \"send through several channels at\n * once\" (no inline multi-channel overload here on purpose).\n *\n * `notify.channel(name)` is the runtime escape when the channel name isn't a\n * compile-time literal.\n *\n * @example\n *   await notify.mail(user, { subject: \"Welcome\", html: \"<p>Hi!</p>\" });\n *   await notify.database(user, { type: \"welcome\", title: \"Welcome!\" });\n *   await notify.mail(\"guest@example.com\", { subject: \"…\", html: \"…\" });   // raw target\n *   await notify.channel(dynamicName).send(user, payload);                 // dynamic name\n */\nimport { getNotificationConfig } from \"../config\";\nimport type { ChannelName, Notifiable, NotificationChannels, SendOptions } from \"../types\";\nimport { newDispatchId } from \"./dispatch-id\";\nimport { dispatchChannel } from \"./dispatcher\";\nimport { emit } from \"./notifications-event-bus\";\n\n/**\n * Public shape of `notify`. The mapped portion gives `notify.<channel>` per\n * registered channel; `channel(name)` is the runtime escape.\n */\nexport type Notify = {\n  channel(name: string): {\n    send(\n      to: Notifiable | string,\n      payload: unknown,\n      options?: SendOptions,\n    ): Promise<void>;\n  };\n} & {\n  [C in ChannelName]: (\n    to: Notifiable | string,\n    payload: NotificationChannels[C],\n    options?: SendOptions,\n  ) => Promise<void>;\n};\n\n/**\n * Per-call dispatch for `notify.<channel>`. Mirrors `defineNotification`'s\n * pipeline but without rendering: payload is already concrete.\n *\n * Preferences gate runs ONLY when a notification `type` is known — explicit\n * via `options.type`, or implicit from a database payload's `type` field.\n * Without a type we have nothing to gate on, and ad-hoc sends bypass\n * preferences silently (use `defineNotification` if you want guaranteed\n * gating).\n */\nasync function notifyImpl(\n  channelName: string,\n  to: Notifiable | string,\n  payload: unknown,\n  options: SendOptions = {},\n): Promise<void> {\n  const isRawTarget = typeof to === \"string\";\n  const notifiable: Notifiable | undefined = isRawTarget ? undefined : to;\n\n  // Derive the type: explicit `options.type` wins, then the payload's\n  // `type` field (database channel convention).\n  let notificationType: string | undefined = options.type;\n  if (\n    notificationType === undefined &&\n    payload &&\n    typeof payload === \"object\" &&\n    \"type\" in payload &&\n    typeof (payload as { type: unknown }).type === \"string\"\n  ) {\n    notificationType = (payload as { type: string }).type;\n  }\n\n  // Preferences gate — only when notifiable + type are both available.\n  if (notifiable && notificationType && !options.force) {\n    const config = getNotificationConfig();\n\n    if (config.preferences) {\n      const allowed = await config.preferences.resolveChannels(\n        notifiable,\n        notificationType,\n        [channelName as ChannelName],\n      );\n\n      if (!allowed.includes(channelName as ChannelName)) {\n        await emit(\"skipped\", {\n          dispatchId: newDispatchId(),\n          channel: channelName,\n          notifiable,\n          reason: \"preference\",\n          options,\n        });\n        return;\n      }\n    }\n  }\n\n  await dispatchChannel({\n    channelName,\n    payload,\n    to: notifiable,\n    rawRoute: isRawTarget ? to : undefined,\n    notificationType,\n    mode: \"send\",\n    options,\n  });\n}\n\n/**\n * Build the `notify` proxy. `channel(name)` returns a `{ send }` object;\n * any other property access returns a one-shot dispatcher for that channel.\n */\nexport const notify: Notify = new Proxy({} as Notify, {\n  get(_target, prop) {\n    if (typeof prop === \"symbol\") {\n      return undefined;\n    }\n\n    // Don't masquerade as a thenable — awaiting or Promise-wrapping `notify`\n    // must NOT invoke notify.then(...) as a channel send. Also keep common\n    // serialization probes from being treated as channel names.\n    if (prop === \"then\" || prop === \"catch\" || prop === \"finally\" || prop === \"toJSON\") {\n      return undefined;\n    }\n\n    if (prop === \"channel\") {\n      return (name: string) => ({\n        send: (to: Notifiable | string, payload: unknown, options?: SendOptions) =>\n          notifyImpl(name, to, payload, options),\n      });\n    }\n\n    return (to: Notifiable | string, payload: unknown, options?: SendOptions) =>\n      notifyImpl(prop, to, payload, options);\n  },\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwDA,eAAe,WACb,aACA,IACA,SACA,UAAuB,CAAC,GACT;CACf,MAAM,cAAc,OAAO,OAAO;CAClC,MAAM,aAAqC,cAAc,SAAY;CAIrE,IAAI,mBAAuC,QAAQ;CACnD,IACE,qBAAqB,UACrB,WACA,OAAO,YAAY,YACnB,UAAU,WACV,OAAQ,QAA8B,SAAS,UAE/C,mBAAoB,QAA6B;CAInD,IAAI,cAAc,oBAAoB,CAAC,QAAQ,OAAO;EACpD,MAAM,SAAS,sBAAsB;EAErC,IAAI,OAAO,aAOT;OAAI,EAAC,MANiB,OAAO,YAAY,gBACvC,YACA,kBACA,CAAC,WAA0B,CAC7B,EAEY,CAAC,SAAS,WAA0B,GAAG;IACjD,MAAM,KAAK,WAAW;KACpB,YAAY,cAAc;KAC1B,SAAS;KACT;KACA,QAAQ;KACR;IACF,CAAC;IACD;GACF;;CAEJ;CAEA,MAAM,gBAAgB;EACpB;EACA;EACA,IAAI;EACJ,UAAU,cAAc,KAAK;EAC7B;EACA,MAAM;EACN;CACF,CAAC;AACH;;;;;AAMA,MAAa,SAAiB,IAAI,MAAM,CAAC,GAAa,EACpD,IAAI,SAAS,MAAM;CACjB,IAAI,OAAO,SAAS,UAClB;CAMF,IAAI,SAAS,UAAU,SAAS,WAAW,SAAS,aAAa,SAAS,UACxE;CAGF,IAAI,SAAS,WACX,QAAQ,UAAkB,EACxB,OAAO,IAAyB,SAAkB,YAChD,WAAW,MAAM,IAAI,SAAS,OAAO,EACzC;CAGF,QAAQ,IAAyB,SAAkB,YACjD,WAAW,MAAM,IAAI,SAAS,OAAO;AACzC,EACF,CAAC"}

package/esm/errors.d.mts

@@ -0,0 +1,32 @@
+//#region ../@warlock.js/notifications/src/errors.d.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.
+ */
+declare class NotificationsNotConfiguredError extends Error {
+  constructor();
+}
+declare class ChannelNotFoundError extends Error {
+  constructor(channelName: string);
+}
+declare class NoQueueDispatcherError extends Error {
+  constructor(channelName: string);
+}
+declare class MissingRendererError extends Error {
+  constructor(notificationType: string, channelName: string);
+}
+/**
+ * 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 }`.
+ */
+declare class UnresolvableRouteError extends Error {
+  constructor(channelName: string, recipientId?: unknown);
+}
+//#endregion
+export { ChannelNotFoundError, MissingRendererError, NoQueueDispatcherError, NotificationsNotConfiguredError, UnresolvableRouteError };
+//# sourceMappingURL=errors.d.mts.map