@warlock.js/notifications 5.24.0 → 5.26.0

package/skills/define-notification/SKILL.md

@@ -1,133 +1,133 @@
----
-name: define-notification
-description: 'Build a reusable multi-channel notification with `defineNotification<Data>({ type, via, ...renderers })`. `type` is the stable identifier preference/rate-limit gates use AND defaults the database channel''s `type`. `via` is `ChannelName[]` OR `(data, to) => ChannelName[]` for per-recipient channel selection. Renderers are `(data, to, ctx) => NotificationChannels[C]`; `ctx` carries `locale` + `meta` from `SendOptions`. The returned object exposes `.send(to|to[], data, options?)`, `.queue(to|to[], data, options?)`, and `.only(...channels)`. Per-recipient + per-channel `Promise.allSettled` isolates failures; the database channel''s `type` is auto-defaulted from `def.type`; `SendOptions.idempotencyKey` is injected into the database payload. Triggers: `defineNotification`, `via`, "reusable notification", "multi-channel notification", "send through several channels at once", "render per channel", `RenderContext`, `def.type`; "force on a notification", "queue with delay"; typical import `import { defineNotification } from "@warlock.js/notifications"`. Skip: single-channel ad-hoc sends — `@warlock.js/notifications/send-ad-hoc/SKILL.md`; adding a brand-new channel — `@warlock.js/notifications/define-channel/SKILL.md`; observing dispatch outcomes — `@warlock.js/notifications/observe-notifications/SKILL.md`.'
----
-
-# `defineNotification` — reusable multi-channel notification
-
-The reusable pattern. Define a notification once with `type` + `via` + a renderer per channel; fire it anywhere with `.send` / `.queue` / `.only`.
-
-## Shape
-
-```ts
-defineNotification<Data>({
-  type: string,                                       // REQUIRED — gate key + database default
-  via: ChannelName[] | (data, to) => ChannelName[],   // static array OR per-recipient callback
-  mail?:     (data, to, ctx) => MailPayload,
-  database?: (data, to, ctx) => Omit<DatabasePayload, "type">, // `type` defaulted from `def.type`
-  // ...one renderer per channel listed in `via`
-});
-```
-
-Returns `{ send, queue, only }`:
-
-| Method | Signature | What it does |
-|---|---|---|
-| `.send` | `(to, data, options?)` | Render + dispatch synchronously. |
-| `.queue` | `(to, data, options?)` | Render + enqueue. Throws if no queue dispatcher is configured. |
-| `.only(...channels)` | returns `{send, queue, only}` | Restrict dispatch to a subset of channels. |
-
-`to` accepts a `Notifiable` OR a `Notifiable[]`. Fan-out emits one render+dispatch per recipient with per-recipient + per-channel `Promise.allSettled` (one failure does not abort the others).
-
-## Static `via`
-
-```ts
-export const welcome = defineNotification<{ name: string }>({
-  type: "welcome",
-  via: ["mail"],
-  mail: ({ name }) => ({ subject: "Welcome", html: `<p>Hi ${name}</p>` }),
-});
-
-await welcome.send(user, { name: "Hasan" });
-```
-
-## Dynamic `via` per recipient
-
-```ts
-export const orderShipped = defineNotification<{ order: Order }>({
-  type: "order.shipped",
-  via: (_data, to) =>
-    to.get("telegram_chat_id")
-      ? ["database", "telegram"]
-      : ["database", "mail"],
-  database: ({ order }) => ({ title: `Order #${order.number} shipped` }),
-  mail: ({ order }, to) => ({
-    subject: `Order #${order.number} shipped`,
-    html: `<p>Hi ${to.get("name")}, on the way.</p>`,
-  }),
-  // telegram: ... (Phase 2 — bridges)
-});
-```
-
-## The renderer's 3rd arg — `RenderContext`
-
-```ts
-mail: ({ campaignId }, to, { locale = "en", meta }) => ({
-  subject: subjectsByLocale[locale],
-  html:    htmlByLocale[locale],
-}),
-
-// usage:
-await marketing.queue(user, payload, {
-  locale: user.get("locale"),
-  meta:   { campaignId, source: "blast" },
-});
-```
-
-`ctx` carries `locale` + `meta` from `SendOptions`. `meta` flows through to every observability event too.
-
-## Database channel — `type` is defaulted
-
-The `database` renderer may OMIT `type` — the dispatcher injects `def.type` automatically. This keeps the notification type in ONE place.
-
-```ts
-defineNotification({
-  type: "order.shipped",   // ← single source of truth
-  via: ["database"],
-  database: () => ({ title: "Shipped" }), // type omitted; dispatcher injects "order.shipped"
-});
-```
-
-## Fan-out
-
-```ts
-await orderShipped.send([buyer, salesRep], { order });
-// One render+dispatch per recipient. Database does N inserts (Phase 0);
-// Phase 1 ships a single bulk insert via `Channel.sendMany?`.
-```
-
-## `.only(...)` — restrict channels
-
-```ts
-await orderShipped.only("mail").send(user, { order });
-// `via` is filtered to just "mail"; other channels are skipped.
-```
-
-## Queue (Phase 2)
-
-```ts
-await orderShipped.queue(user, { order }, { delay: "10m" });
-// Throws NoQueueDispatcherError if no `queue` is configured in config/notifications.ts.
-```
-
-## SendOptions
-
-| Field | Effect |
-|---|---|
-| `delay` | Reserved — `"10m"` / `"3d"` / `600` (seconds). NOT honored yet: both `.send()` and the current `.queue()` worker dispatch immediately; delay-aware delivery is a follow-up. |
-| `locale` | Passed to renderers via `RenderContext.locale`. |
-| `meta` | Passed to renderers + included in every observability event. |
-| `idempotencyKey` | Injected into the database payload (dedupe via unique index). |
-| `force` | Bypass `PreferenceProvider`. Does NOT bypass `RateLimiter`. |
-| `type` | Ignored by `defineNotification` — see `send-ad-hoc` for ad-hoc gating. |
-
-## Failure isolation
-
-Per-recipient: each recipient gets an independent `Promise.allSettled`. Per-channel: each channel within a recipient gets an independent `allSettled`. A throw becomes a `failed` event on the event bus AND re-throws within its own slot — never aborts siblings.
-
-## See also
-
-- [`notifications-basics/SKILL.md`](../notifications-basics/SKILL.md) — package front door.
-- [`send-ad-hoc/SKILL.md`](../send-ad-hoc/SKILL.md) — `notify.<channel>` per-channel shorthand.
-- [`configure-notifications/SKILL.md`](../configure-notifications/SKILL.md) — wire channels + preferences + rate-limit + queue.
-- [`observe-notifications/SKILL.md`](../observe-notifications/SKILL.md) — `notifications.on("sending" | "sent" | "failed" | "skipped", …)`.
+---
+name: define-notification
+description: 'Build a reusable multi-channel notification with `defineNotification<Data>({ type, via, ...renderers })`. `type` is the stable identifier preference/rate-limit gates use AND defaults the database channel''s `type`. `via` is `ChannelName[]` OR `(data, to) => ChannelName[]` for per-recipient channel selection. Renderers are `(data, to, ctx) => NotificationChannels[C]`; `ctx` carries `locale` + `meta` from `SendOptions`. The returned object exposes `.send(to|to[], data, options?)`, `.queue(to|to[], data, options?)`, and `.only(...channels)`. Per-recipient + per-channel `Promise.allSettled` isolates failures; the database channel''s `type` is auto-defaulted from `def.type`; `SendOptions.idempotencyKey` is injected into the database payload. Triggers: `defineNotification`, `via`, "reusable notification", "multi-channel notification", "send through several channels at once", "render per channel", `RenderContext`, `def.type`; "force on a notification", "queue with delay"; typical import `import { defineNotification } from "@warlock.js/notifications"`. Skip: single-channel ad-hoc sends — `@warlock.js/notifications/send-ad-hoc/SKILL.md`; adding a brand-new channel — `@warlock.js/notifications/define-channel/SKILL.md`; observing dispatch outcomes — `@warlock.js/notifications/observe-notifications/SKILL.md`.'
+---
+
+# `defineNotification` — reusable multi-channel notification
+
+The reusable pattern. Define a notification once with `type` + `via` + a renderer per channel; fire it anywhere with `.send` / `.queue` / `.only`.
+
+## Shape
+
+```ts
+defineNotification<Data>({
+  type: string,                                       // REQUIRED — gate key + database default
+  via: ChannelName[] | (data, to) => ChannelName[],   // static array OR per-recipient callback
+  mail?:     (data, to, ctx) => MailPayload,
+  database?: (data, to, ctx) => Omit<DatabasePayload, "type">, // `type` defaulted from `def.type`
+  // ...one renderer per channel listed in `via`
+});
+```
+
+Returns `{ send, queue, only }`:
+
+| Method | Signature | What it does |
+|---|---|---|
+| `.send` | `(to, data, options?)` | Render + dispatch synchronously. |
+| `.queue` | `(to, data, options?)` | Render + enqueue. Throws if no queue dispatcher is configured. |
+| `.only(...channels)` | returns `{send, queue, only}` | Restrict dispatch to a subset of channels. |
+
+`to` accepts a `Notifiable` OR a `Notifiable[]`. Fan-out emits one render+dispatch per recipient with per-recipient + per-channel `Promise.allSettled` (one failure does not abort the others).
+
+## Static `via`
+
+```ts
+export const welcome = defineNotification<{ name: string }>({
+  type: "welcome",
+  via: ["mail"],
+  mail: ({ name }) => ({ subject: "Welcome", html: `<p>Hi ${name}</p>` }),
+});
+
+await welcome.send(user, { name: "Hasan" });
+```
+
+## Dynamic `via` per recipient
+
+```ts
+export const orderShipped = defineNotification<{ order: Order }>({
+  type: "order.shipped",
+  via: (_data, to) =>
+    to.get("telegram_chat_id")
+      ? ["database", "telegram"]
+      : ["database", "mail"],
+  database: ({ order }) => ({ title: `Order #${order.number} shipped` }),
+  mail: ({ order }, to) => ({
+    subject: `Order #${order.number} shipped`,
+    html: `<p>Hi ${to.get("name")}, on the way.</p>`,
+  }),
+  // telegram: ... (Phase 2 — bridges)
+});
+```
+
+## The renderer's 3rd arg — `RenderContext`
+
+```ts
+mail: ({ campaignId }, to, { locale = "en", meta }) => ({
+  subject: subjectsByLocale[locale],
+  html:    htmlByLocale[locale],
+}),
+
+// usage:
+await marketing.queue(user, payload, {
+  locale: user.get("locale"),
+  meta:   { campaignId, source: "blast" },
+});
+```
+
+`ctx` carries `locale` + `meta` from `SendOptions`. `meta` flows through to every observability event too.
+
+## Database channel — `type` is defaulted
+
+The `database` renderer may OMIT `type` — the dispatcher injects `def.type` automatically. This keeps the notification type in ONE place.
+
+```ts
+defineNotification({
+  type: "order.shipped",   // ← single source of truth
+  via: ["database"],
+  database: () => ({ title: "Shipped" }), // type omitted; dispatcher injects "order.shipped"
+});
+```
+
+## Fan-out
+
+```ts
+await orderShipped.send([buyer, salesRep], { order });
+// One render+dispatch per recipient. Database does N inserts (Phase 0);
+// Phase 1 ships a single bulk insert via `Channel.sendMany?`.
+```
+
+## `.only(...)` — restrict channels
+
+```ts
+await orderShipped.only("mail").send(user, { order });
+// `via` is filtered to just "mail"; other channels are skipped.
+```
+
+## Queue (Phase 2)
+
+```ts
+await orderShipped.queue(user, { order }, { delay: "10m" });
+// Throws NoQueueDispatcherError if no `queue` is configured in config/notifications.ts.
+```
+
+## SendOptions
+
+| Field | Effect |
+|---|---|
+| `delay` | Reserved — `"10m"` / `"3d"` / `600` (seconds). NOT honored yet: both `.send()` and the current `.queue()` worker dispatch immediately; delay-aware delivery is a follow-up. |
+| `locale` | Passed to renderers via `RenderContext.locale`. |
+| `meta` | Passed to renderers + included in every observability event. |
+| `idempotencyKey` | Injected into the database payload (dedupe via unique index). |
+| `force` | Bypass `PreferenceProvider`. Does NOT bypass `RateLimiter`. |
+| `type` | Ignored by `defineNotification` — see `send-ad-hoc` for ad-hoc gating. |
+
+## Failure isolation
+
+Per-recipient: each recipient gets an independent `Promise.allSettled`. Per-channel: each channel within a recipient gets an independent `allSettled`. A throw becomes a `failed` event on the event bus AND re-throws within its own slot — never aborts siblings.
+
+## See also
+
+- [`notifications-basics/SKILL.md`](../notifications-basics/SKILL.md) — package front door.
+- [`send-ad-hoc/SKILL.md`](../send-ad-hoc/SKILL.md) — `notify.<channel>` per-channel shorthand.
+- [`configure-notifications/SKILL.md`](../configure-notifications/SKILL.md) — wire channels + preferences + rate-limit + queue.
+- [`observe-notifications/SKILL.md`](../observe-notifications/SKILL.md) — `notifications.on("sending" | "sent" | "failed" | "skipped", …)`.

package/skills/observe-notifications/SKILL.md

@@ -1,66 +1,66 @@
----
-name: observe-notifications
-description: 'Wire metrics, logging, tracing, and audits via `notifications.on(event, handler)` — four events fire per (channel, recipient): `sending` (gates passed, about to hit the transport), `sent` (succeeded), `failed` (channel threw — carries the Error), `skipped` (a pre-send gate dropped it — carries `reason: "preference" | "rate-limit"`). Every event carries the recipient as `notifiable?` (undefined only for raw-target ad-hoc sends) and a `dispatchId` — `sending` and its terminal `sent`/`failed` share it, so observers can pair them (spans, latency, hung-send detection). `sent`/`failed` also carry `durationMs`. Handler exceptions are logged-and-swallowed so one bad listener can not break the dispatcher. `on(...)` returns an unsubscribe function; `off(event, handler)` exists for symmetry. Triggers: `notifications.on`, `notifications.off`, `"sending"` event, `"sent"` event, `"failed"` event, `"skipped"` event, `dispatchId`, `durationMs`, `NotificationEvents`, "notification metrics", "notification latency", "trace notifications", "notification audit log", "track notification drops"; typical import `import { notifications } from "@warlock.js/notifications"`. Skip: building notifications — `@warlock.js/notifications/define-notification/SKILL.md`; configuring the preference/rate-limit gates that produce `skipped` — `@warlock.js/notifications/configure-notifications/SKILL.md`.'
----
-
-# Observe notifications
-
-Every dispatch emits a `sending` event then a terminal `sent` / `failed` — or a `skipped` if a gate dropped it — per (channel, recipient).
-
-```ts
-import { notifications } from "@warlock.js/notifications";
-
-// latency + delivery, keyed by recipient
-notifications.on("sent", ({ channel, notifiable, durationMs, options }) =>
-  metrics.timing(`notif.${channel}.sent`, durationMs, { userId: notifiable?.id, ...options.meta }));
-
-notifications.on("failed", ({ channel, notifiable, error }) =>
-  log.error(`notif.${channel}`, error, { userId: notifiable?.id }));
-
-notifications.on("skipped", ({ channel, reason }) =>
-  metrics.inc(`notif.${channel}.skipped.${reason}`));
-
-// pair `sending` → terminal by dispatchId — open a span / arm a hung-send watchdog
-notifications.on("sending", ({ dispatchId, channel, notifiable }) =>
-  tracer.open(dispatchId, { channel, userId: notifiable?.id }));
-```
-
-## Events
-
-| Event | Fires when | Payload |
-|---|---|---|
-| `sending` | Gates passed; about to hit the transport (sync) / enqueue (queue) | `{ dispatchId, channel, notifiable?, payload, options }` |
-| `sent` | Channel dispatched OR job enqueued | `{ dispatchId, channel, notifiable?, payload, options, durationMs }` |
-| `failed` | `channel.send` (or `queue.dispatch`) threw | `{ dispatchId, channel, notifiable?, payload, error, options, durationMs }` |
-| `skipped` | A pre-send gate dropped this channel | `{ dispatchId, channel, notifiable?, reason, options }` — `reason: "preference" \| "rate-limit"` |
-
-`notifiable` is the recipient **model** (undefined only for raw-target ad-hoc sends like `notify.mail("x@y.com", …)`) — read `notifiable?.id` / `notifiable?.get(...)` to key your metrics or logs.
-
-`dispatchId` is unique per (channel, recipient) dispatch — `sending` and its terminal `sent`/`failed` share it, so you can pair them for a span, a latency measurement, or a watchdog that flags a `sending` with no terminal (a hung send). `durationMs` is transport time on a sync send, enqueue time on a queued one.
-
-`options` is the `SendOptions` passed at the call site — including `meta`. Tagging a send with `meta: { campaignId }` lets downstream observers join the event back to the campaign.
-
-## Unsubscribe
-
-```ts
-const off = notifications.on("sent", handler);
-// later
-off();
-
-// or
-notifications.off("sent", handler);
-```
-
-## Fan-out emits N events
-
-`orderShipped.send([buyer, salesRep], { order })` with `via: ["mail", "database"]` fires up to **4** `sent` events (2 recipients × 2 channels). Aggregate by `meta` or by `channel + notifiable.id` in your observer.
-
-## Handler isolation
-
-A handler that throws is logged and swallowed — the other handlers for the same event still run, and the dispatcher never observes the throw. Observers can't **abort** a send (there's no veto here — use `preferences` / `rateLimit` for that). They can delay it, though: `sending` is awaited before the transport, so keep that handler fast.
-
-## See also
-
-- [`notifications-basics/SKILL.md`](../notifications-basics/SKILL.md) — front door + mental model.
-- [`configure-notifications/SKILL.md`](../configure-notifications/SKILL.md) — `preferences` / `rateLimit` slots that emit `skipped`.
-- [`send-ad-hoc/SKILL.md`](../send-ad-hoc/SKILL.md) — when `notifiable` is undefined in events.
+---
+name: observe-notifications
+description: 'Wire metrics, logging, tracing, and audits via `notifications.on(event, handler)` — four events fire per (channel, recipient): `sending` (gates passed, about to hit the transport), `sent` (succeeded), `failed` (channel threw — carries the Error), `skipped` (a pre-send gate dropped it — carries `reason: "preference" | "rate-limit"`). Every event carries the recipient as `notifiable?` (undefined only for raw-target ad-hoc sends) and a `dispatchId` — `sending` and its terminal `sent`/`failed` share it, so observers can pair them (spans, latency, hung-send detection). `sent`/`failed` also carry `durationMs`. Handler exceptions are logged-and-swallowed so one bad listener can not break the dispatcher. `on(...)` returns an unsubscribe function; `off(event, handler)` exists for symmetry. Triggers: `notifications.on`, `notifications.off`, `"sending"` event, `"sent"` event, `"failed"` event, `"skipped"` event, `dispatchId`, `durationMs`, `NotificationEvents`, "notification metrics", "notification latency", "trace notifications", "notification audit log", "track notification drops"; typical import `import { notifications } from "@warlock.js/notifications"`. Skip: building notifications — `@warlock.js/notifications/define-notification/SKILL.md`; configuring the preference/rate-limit gates that produce `skipped` — `@warlock.js/notifications/configure-notifications/SKILL.md`.'
+---
+
+# Observe notifications
+
+Every dispatch emits a `sending` event then a terminal `sent` / `failed` — or a `skipped` if a gate dropped it — per (channel, recipient).
+
+```ts
+import { notifications } from "@warlock.js/notifications";
+
+// latency + delivery, keyed by recipient
+notifications.on("sent", ({ channel, notifiable, durationMs, options }) =>
+  metrics.timing(`notif.${channel}.sent`, durationMs, { userId: notifiable?.id, ...options.meta }));
+
+notifications.on("failed", ({ channel, notifiable, error }) =>
+  log.error(`notif.${channel}`, error, { userId: notifiable?.id }));
+
+notifications.on("skipped", ({ channel, reason }) =>
+  metrics.inc(`notif.${channel}.skipped.${reason}`));
+
+// pair `sending` → terminal by dispatchId — open a span / arm a hung-send watchdog
+notifications.on("sending", ({ dispatchId, channel, notifiable }) =>
+  tracer.open(dispatchId, { channel, userId: notifiable?.id }));
+```
+
+## Events
+
+| Event | Fires when | Payload |
+|---|---|---|
+| `sending` | Gates passed; about to hit the transport (sync) / enqueue (queue) | `{ dispatchId, channel, notifiable?, payload, options }` |
+| `sent` | Channel dispatched OR job enqueued | `{ dispatchId, channel, notifiable?, payload, options, durationMs }` |
+| `failed` | `channel.send` (or `queue.dispatch`) threw | `{ dispatchId, channel, notifiable?, payload, error, options, durationMs }` |
+| `skipped` | A pre-send gate dropped this channel | `{ dispatchId, channel, notifiable?, reason, options }` — `reason: "preference" \| "rate-limit"` |
+
+`notifiable` is the recipient **model** (undefined only for raw-target ad-hoc sends like `notify.mail("x@y.com", …)`) — read `notifiable?.id` / `notifiable?.get(...)` to key your metrics or logs.
+
+`dispatchId` is unique per (channel, recipient) dispatch — `sending` and its terminal `sent`/`failed` share it, so you can pair them for a span, a latency measurement, or a watchdog that flags a `sending` with no terminal (a hung send). `durationMs` is transport time on a sync send, enqueue time on a queued one.
+
+`options` is the `SendOptions` passed at the call site — including `meta`. Tagging a send with `meta: { campaignId }` lets downstream observers join the event back to the campaign.
+
+## Unsubscribe
+
+```ts
+const off = notifications.on("sent", handler);
+// later
+off();
+
+// or
+notifications.off("sent", handler);
+```
+
+## Fan-out emits N events
+
+`orderShipped.send([buyer, salesRep], { order })` with `via: ["mail", "database"]` fires up to **4** `sent` events (2 recipients × 2 channels). Aggregate by `meta` or by `channel + notifiable.id` in your observer.
+
+## Handler isolation
+
+A handler that throws is logged and swallowed — the other handlers for the same event still run, and the dispatcher never observes the throw. Observers can't **abort** a send (there's no veto here — use `preferences` / `rateLimit` for that). They can delay it, though: `sending` is awaited before the transport, so keep that handler fast.
+
+## See also
+
+- [`notifications-basics/SKILL.md`](../notifications-basics/SKILL.md) — front door + mental model.
+- [`configure-notifications/SKILL.md`](../configure-notifications/SKILL.md) — `preferences` / `rateLimit` slots that emit `skipped`.
+- [`send-ad-hoc/SKILL.md`](../send-ad-hoc/SKILL.md) — when `notifiable` is undefined in events.

package/skills/queue-notifications/SKILL.md

@@ -1,110 +1,110 @@
----
-name: queue-notifications
-description: "Send notifications asynchronously through the herald backend or the BullMQ driver. Configure a QueueDispatcher in config/notifications.ts, then use notif.queue(to, data, options?) to enqueue rendered jobs. Herald uses heraldQueue() and startNotificationsWorker(); bullmqQueue({ attempts, backoff }) from @warlock.js/notifications uses BullMQ (lazy-loading the optional @warlock.js/queue peer), supports retries, and honours SendOptions.delay. Without a queue configured, .queue() rejects NoQueueDispatcherError. Triggers: heraldQueue, bullmqQueue, startNotificationsWorker, QueueDispatcher, .queue(, async notifications, queue notifications, notification worker, background notifications, notifications.dispatch. Skip: synchronous sends - @warlock.js/notifications/define-notification/SKILL.md; herald itself - @warlock.js/herald/*."
----
-
-# Queue notifications (async)
-
-Move slow channels (SMTP, HTTP) off the request path. `.queue()` renders the
-payload and resolves the route before passing a serializable job to a dispatcher.
-
-## Wire the herald dispatcher
-
-```ts title="src/config/notifications.ts"
-import {
-  type NotificationConfig,
-  heraldQueue,
-  inApp,
-  mailChannel,
-} from "@warlock.js/notifications";
-import { Notification } from "app/notifications/notification.model";
-
-const config: NotificationConfig = {
-  channels: { mail: mailChannel(), database: inApp.configure({ model: Notification }) },
-  queue: heraldQueue(),
-};
-
-export default config;
-```
-
-`heraldQueue({ channel?, broker? })` publishes to `"notifications.dispatch"`
-on the default broker unless overridden. It lazy-imports `@warlock.js/herald`;
-if that package is missing, the first `.queue()` throws an install message.
-
-## Use BullMQ for delayed or retried delivery
-
-Use the `bullmq` driver instead of the herald dispatcher — it ships inside
-`@warlock.js/notifications` itself and lazy-loads `@warlock.js/queue` (an
-OPTIONAL peer) the first time `.queue()` runs:
-
-```ts title="src/config/notifications.ts"
-import { type NotificationConfig, bullmqQueue, mailChannel } from "@warlock.js/notifications";
-
-const config: NotificationConfig = {
-  channels: { mail: mailChannel() },
-  queue: bullmqQueue({ attempts: 3, backoff: { type: "exponential", delay: 5000 } }),
-};
-
-export default config;
-```
-
-The BullMQ driver honours `SendOptions.delay`: numeric delays are seconds and
-string delays use the normal duration syntax, such as `"10m"`. It also supports
-BullMQ retries through `attempts` and `backoff`. If `@warlock.js/queue` isn't
-installed, the first `.queue()` throws `QueuePackageNotInstalledError` naming
-`warlock add queue`.
-
-> **Removed (5.15.0):** `queueNotificationDispatcher` from
-> `@warlock.js/queue/notifications` — deprecated in 5.14, removed this
-> release, along with the `@warlock.js/notifications` peer dependency it was
-> the only reason `@warlock.js/queue` carried. Use `bullmqQueue` above — same
-> option names (`queue`, `attempts`, `backoff`).
-
-## Run the herald worker
-
-In a worker entrypoint (or the web process), after the config and herald broker
-are up:
-
-```ts
-import { startNotificationsWorker } from "@warlock.js/notifications";
-
-await startNotificationsWorker();
-```
-
-The worker looks up the channel by name and runs
-`channel.send({ payload, route, options })`. The worker needs no recipient model
-because rendering happened at enqueue time.
-
-## Send
-
-```ts
-await orderShipped.queue(user, { order });
-await orderShipped.queue(buyers, { order }, { delay: "10m" });
-await notify.mail(user, payload, {/* synchronous - notify.* does not queue */});
-```
-
-`.queue()` renders per recipient and enqueues one job per recipient. Without a
-configured dispatcher, it rejects `NoQueueDispatcherError`.
-
-## Idempotency
-
-Pass `idempotencyKey` so a redelivered or retried job does not create a duplicate
-in-app row. `createFor` finds or creates the row by that key.
-
-```ts
-await orderShipped.queue(user, { order }, { idempotencyKey: `ship:${order.id}` });
-```
-
-## Current limits
-
-- With the herald backend, `delay` is carried on the job but not honoured; the
-  worker delivers immediately. Use the BullMQ adapter for delayed delivery.
-- Herald has no retry or dead-letter handling yet; failed `channel.send` calls
-  are logged and acknowledged.
-- Rate-limit budget is consumed at enqueue time for queued sends.
-
-## See also
-
-- [`define-notification/SKILL.md`](../define-notification/SKILL.md) - `.queue()` on a defined notification.
-- [`configure-notifications/SKILL.md`](../configure-notifications/SKILL.md) - the `queue` config slot.
-- [`@warlock.js/herald/herald-basics/SKILL.md`](../../../herald/skills/herald-basics/SKILL.md) - connecting the broker.
+---
+name: queue-notifications
+description: "Send notifications asynchronously through the herald backend or the BullMQ driver. Configure a QueueDispatcher in config/notifications.ts, then use notif.queue(to, data, options?) to enqueue rendered jobs. Herald uses heraldQueue() and startNotificationsWorker(); bullmqQueue({ attempts, backoff }) from @warlock.js/notifications uses BullMQ (lazy-loading the optional @warlock.js/queue peer), supports retries, and honours SendOptions.delay. Without a queue configured, .queue() rejects NoQueueDispatcherError. Triggers: heraldQueue, bullmqQueue, startNotificationsWorker, QueueDispatcher, .queue(, async notifications, queue notifications, notification worker, background notifications, notifications.dispatch. Skip: synchronous sends - @warlock.js/notifications/define-notification/SKILL.md; herald itself - @warlock.js/herald/*."
+---
+
+# Queue notifications (async)
+
+Move slow channels (SMTP, HTTP) off the request path. `.queue()` renders the
+payload and resolves the route before passing a serializable job to a dispatcher.
+
+## Wire the herald dispatcher
+
+```ts title="src/config/notifications.ts"
+import {
+  type NotificationConfig,
+  heraldQueue,
+  inApp,
+  mailChannel,
+} from "@warlock.js/notifications";
+import { Notification } from "app/notifications/notification.model";
+
+const config: NotificationConfig = {
+  channels: { mail: mailChannel(), database: inApp.configure({ model: Notification }) },
+  queue: heraldQueue(),
+};
+
+export default config;
+```
+
+`heraldQueue({ channel?, broker? })` publishes to `"notifications.dispatch"`
+on the default broker unless overridden. It lazy-imports `@warlock.js/herald`;
+if that package is missing, the first `.queue()` throws an install message.
+
+## Use BullMQ for delayed or retried delivery
+
+Use the `bullmq` driver instead of the herald dispatcher — it ships inside
+`@warlock.js/notifications` itself and lazy-loads `@warlock.js/queue` (an
+OPTIONAL peer) the first time `.queue()` runs:
+
+```ts title="src/config/notifications.ts"
+import { type NotificationConfig, bullmqQueue, mailChannel } from "@warlock.js/notifications";
+
+const config: NotificationConfig = {
+  channels: { mail: mailChannel() },
+  queue: bullmqQueue({ attempts: 3, backoff: { type: "exponential", delay: 5000 } }),
+};
+
+export default config;
+```
+
+The BullMQ driver honours `SendOptions.delay`: numeric delays are seconds and
+string delays use the normal duration syntax, such as `"10m"`. It also supports
+BullMQ retries through `attempts` and `backoff`. If `@warlock.js/queue` isn't
+installed, the first `.queue()` throws `QueuePackageNotInstalledError` naming
+`warlock add queue`.
+
+> **Removed (5.15.0):** `queueNotificationDispatcher` from
+> `@warlock.js/queue/notifications` — deprecated in 5.14, removed this
+> release, along with the `@warlock.js/notifications` peer dependency it was
+> the only reason `@warlock.js/queue` carried. Use `bullmqQueue` above — same
+> option names (`queue`, `attempts`, `backoff`).
+
+## Run the herald worker
+
+In a worker entrypoint (or the web process), after the config and herald broker
+are up:
+
+```ts
+import { startNotificationsWorker } from "@warlock.js/notifications";
+
+await startNotificationsWorker();
+```
+
+The worker looks up the channel by name and runs
+`channel.send({ payload, route, options })`. The worker needs no recipient model
+because rendering happened at enqueue time.
+
+## Send
+
+```ts
+await orderShipped.queue(user, { order });
+await orderShipped.queue(buyers, { order }, { delay: "10m" });
+await notify.mail(user, payload, {/* synchronous - notify.* does not queue */});
+```
+
+`.queue()` renders per recipient and enqueues one job per recipient. Without a
+configured dispatcher, it rejects `NoQueueDispatcherError`.
+
+## Idempotency
+
+Pass `idempotencyKey` so a redelivered or retried job does not create a duplicate
+in-app row. `createFor` finds or creates the row by that key.
+
+```ts
+await orderShipped.queue(user, { order }, { idempotencyKey: `ship:${order.id}` });
+```
+
+## Current limits
+
+- With the herald backend, `delay` is carried on the job but not honoured; the
+  worker delivers immediately. Use the BullMQ adapter for delayed delivery.
+- Herald has no retry or dead-letter handling yet; failed `channel.send` calls
+  are logged and acknowledged.
+- Rate-limit budget is consumed at enqueue time for queued sends.
+
+## See also
+
+- [`define-notification/SKILL.md`](../define-notification/SKILL.md) - `.queue()` on a defined notification.
+- [`configure-notifications/SKILL.md`](../configure-notifications/SKILL.md) - the `queue` config slot.
+- [`@warlock.js/herald/herald-basics/SKILL.md`](../../../herald/skills/herald-basics/SKILL.md) - connecting the broker.