@warlock.js/notifications 5.12.0 → 5.14.0

package/llms.txt

@@ -11,7 +11,7 @@
 - [define-notification](@warlock.js/notifications/define-notification/SKILL.md): 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`.
 - [notifications-basics](@warlock.js/notifications/notifications-basics/SKILL.md): Front-door for `@warlock.js/notifications` — what the package is, when to reach for it, and the four moving parts (channel registry, defineNotification, notify, inApp). Multi-channel dispatch: define once, fire anywhere. Recipients are cascade `Model` instances; payloads are typed per channel via a declaration-merge `NotificationChannels` registry; reusable definitions go through `defineNotification`; ad-hoc per-channel sends go through the `notify.<channel>` proxy; the in-app database channel is read via the `inApp` facade. Phase 1 ships `mail` + `database`; bridges-backed channels (whatsapp/telegram/push/slack) arrive in Phase 2. Triggers: `defineNotification`, `notify.<channel>`, `inApp.configure`, `setNotificationConfig`, `NotificationConfig`, `NotificationChannels`; "send a notification", "in-app notifications", "what channels can I use", "what is `@warlock.js/notifications`", "where do I start"; typical import `import { defineNotification, notify, inApp } from "@warlock.js/notifications"`. Skip: configuring channels in `config/notifications.ts` — `@warlock.js/notifications/configure-notifications/SKILL.md`; building a multi-channel definition — `@warlock.js/notifications/define-notification/SKILL.md`; reading in-app rows — `@warlock.js/notifications/use-in-app/SKILL.md`.
 - [observe-notifications](@warlock.js/notifications/observe-notifications/SKILL.md): 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`.
-- [queue-notifications](@warlock.js/notifications/queue-notifications/SKILL.md): Send notifications asynchronously via the herald-backed queue. `heraldQueue({ channel?, broker? })` is a `QueueDispatcher` you add to the `queue` slot of the declarative `config/notifications.ts` (the connector registers it at boot); then `notif.queue(to, data, options?)` / `notify` publish a rendered job instead of sending inline. `startNotificationsWorker({ channel?, broker? })` runs the consumer (in a worker or the web process) that pulls jobs and runs `channel.send`. Both lazy-import `@warlock.js/herald` (optional peer) — a missing package throws a curated install message at use time. `defineNotification` renders payloads + resolves routes BEFORE queuing, so the job (`{ channel, route, payload, options }`) is fully serializable — no model re-hydration. Without a queue configured, `.queue()` rejects `NoQueueDispatcherError`. Triggers: `heraldQueue`, `startNotificationsWorker`, `QueueDispatcher`, `.queue(`, "async notifications", "queue notifications", "notification worker", "background notifications", `notifications.dispatch`; typical import `import { heraldQueue, startNotificationsWorker } from "@warlock.js/notifications"`. Skip: synchronous sends — `@warlock.js/notifications/define-notification/SKILL.md`; herald itself — `@warlock.js/herald/*`.
+- [queue-notifications](@warlock.js/notifications/queue-notifications/SKILL.md): 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/*.
 - [send-ad-hoc](@warlock.js/notifications/send-ad-hoc/SKILL.md): Ad-hoc per-channel send via the `notify.<channel>(to, payload, options?)` Proxy facade. Works for any channel registered in `NotificationChannels` (built-in or custom). `to` accepts a `Notifiable` model OR a raw route string (`"x@y.com"`); `payload` is typed per channel via the registry; `options` is the standard `SendOptions`. `notify.channel(name).send(...)` is the runtime escape when the channel name is not a compile-time literal. Type-based preference gating applies when a type is known — explicit via `options.type` OR auto-detected from a database payload's `type` field. For multi-channel sends use `defineNotification` instead — there is no inline `notify(to, { via, ... })` form on purpose. Triggers: `notify.<channel>`, `notify.channel(name)`, `notify.mail`, `notify.database`, "send a one-off notification", "ad-hoc notification", "send an email without defining a notification", "raw email target", "dynamic channel name"; typical import `import { notify } from "@warlock.js/notifications"`. Skip: reusable multi-channel notifications — `@warlock.js/notifications/define-notification/SKILL.md`; configuring channels — `@warlock.js/notifications/configure-notifications/SKILL.md`.
 - [use-in-app](@warlock.js/notifications/use-in-app/SKILL.md): Use the `inApp` facade for the in-app/database channel's READ side: `inApp.configure({ model: Notification })` or `{ repository: myRepo }` binds the store AND returns the channel; `inApp.list / listUnread / countUnread / markAsRead / markAsUnread` are RECIPIENT-SCOPED by construction (no IDOR — `markAsRead(user, id)` cannot flip another user's row even with a foreign id). `countUnread` uses `RepositoryManager.countCached` for the badge fast-path. Triggers: `inApp.configure`, `inApp.list`, `inApp.listUnread`, `inApp.countUnread`, `inApp.markAsRead`, `inApp.markAsUnread`, `BaseNotificationsRepository`, `DatabaseNotification`, `NotificationsFilter`, "in-app notifications", "mark notification as read", "unread count", "notification badge", "IDOR-safe markAsRead"; typical import `import { inApp } from "@warlock.js/notifications"`. Skip: writing notifications (use `defineNotification` or `notify.database`) — `@warlock.js/notifications/define-notification/SKILL.md`; the migration columns — `@warlock.js/notifications/write-notification-migration/SKILL.md`; wiring it into config — `@warlock.js/notifications/configure-notifications/SKILL.md`.
 - [write-notification-migration](@warlock.js/notifications/write-notification-migration/SKILL.md): Create the notifications table with the `notificationColumns(Notification)` factory + cascade `Migration.create`. Column NAMES come from the model's `columnMap` (recipient / tenant / readAt / isRead); the fixed columns are `type` / `title` / `body` / `payload` / `idempotency_key`. Read-state follows columnMap presence: `readAt` → nullable timestamp, `isRead` → indexed boolean, both → both. Defaults to `user_id` + `read_at` when no columnMap. Spread + extend for extras (FK references, composite indexes). Triggers: `notificationColumns`, `Migration.create` for notifications, "create the notifications table", "notification migration", "add organization_id to notifications", `is_read` column, `read_at` column, `idempotency_key` column; typical import `import { Migration } from "@warlock.js/cascade"; import { notificationColumns } from "@warlock.js/notifications"`. Skip: generic cascade migration writing — `@warlock.js/cascade/write-migration/SKILL.md`; the model itself — `@warlock.js/notifications/use-in-app/SKILL.md`.

package/package.json

@@ -5,13 +5,21 @@
     "environment": "server"
   },
   "dependencies": {
-    "@warlock.js/cache": "5.12.0",
-    "@warlock.js/cascade": "5.12.0",
-    "@warlock.js/core": "5.12.0",
-    "@warlock.js/logger": "5.12.0"
+    "@warlock.js/cache": "5.14.0",
+    "@warlock.js/cascade": "5.14.0",
+    "@warlock.js/core": "5.14.0",
+    "@warlock.js/logger": "5.14.0"
   },
   "optionalDependencies": {
-    "@warlock.js/herald": "5.12.0"
+    "@warlock.js/herald": "5.14.0"
+  },
+  "peerDependencies": {
+    "@warlock.js/queue": "5.14.0"
+  },
+  "peerDependenciesMeta": {
+    "@warlock.js/queue": {
+      "optional": true
+    }
   },
   "repository": {
     "type": "git",
@@ -27,7 +35,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.12.0",
+  "version": "5.14.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/queue-notifications/SKILL.md

@@ -1,81 +1,109 @@
 ---
 name: queue-notifications
-description: 'Send notifications asynchronously via the herald-backed queue. `heraldQueue({ channel?, broker? })` is a `QueueDispatcher` you add to the `queue` slot of the declarative `config/notifications.ts` (the connector registers it at boot); then `notif.queue(to, data, options?)` / `notify` publish a rendered job instead of sending inline. `startNotificationsWorker({ channel?, broker? })` runs the consumer (in a worker or the web process) that pulls jobs and runs `channel.send`. Both lazy-import `@warlock.js/herald` (optional peer) — a missing package throws a curated install message at use time. `defineNotification` renders payloads + resolves routes BEFORE queuing, so the job (`{ channel, route, payload, options }`) is fully serializable — no model re-hydration. Without a queue configured, `.queue()` rejects `NoQueueDispatcherError`. Triggers: `heraldQueue`, `startNotificationsWorker`, `QueueDispatcher`, `.queue(`, "async notifications", "queue notifications", "notification worker", "background notifications", `notifications.dispatch`; typical import `import { heraldQueue, startNotificationsWorker } from "@warlock.js/notifications"`. Skip: synchronous sends — `@warlock.js/notifications/define-notification/SKILL.md`; herald itself — `@warlock.js/herald/*`.'
+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()` publishes a
-rendered job to herald; a worker delivers it.
+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 dispatcher
+## Wire the herald dispatcher
 
 ```ts title="src/config/notifications.ts"
-import { type NotificationConfig, heraldQueue, inApp, mailChannel } from "@warlock.js/notifications";
+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(), // → `.queue()` now works
+  queue: heraldQueue(),
 };
 
-export default config; // the notifications connector registers it at boot
+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 isn't installed, the first `.queue()` throws an install message.
+`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.
 
-Without `queue` configured, `.queue()` rejects `NoQueueDispatcherError` — a loud
-config error, not a silent no-op.
+## Use BullMQ for delayed or retried delivery
 
-## Run the worker
+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:
 
-In a worker entrypoint (or the web process), after the config + the herald
-broker are up:
+```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`.
+
+> **Deprecated:** `queueNotificationDispatcher` from
+> `@warlock.js/queue/notifications` still works for this release (it logs a
+> one-time deprecation warning) and is removed next release. Migrate to
+> `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(); // subscribes to "notifications.dispatch"
+await startNotificationsWorker();
 ```
 
-The worker pulls each job, looks the channel up by name, and runs
-`channel.send({ payload, route, options })`. The job carries an
-ALREADY-RENDERED payload + resolved route (rendering happens at enqueue), so the
-worker needs no recipient model.
+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 });               // async
+await orderShipped.queue(user, { order });
 await orderShipped.queue(buyers, { order }, { delay: "10m" });
-await notify.mail(user, payload, { /* sync — notify.* doesn't queue */ });
+await notify.mail(user, payload, {/* synchronous - notify.* does not queue */});
 ```
 
-`.queue()` renders synchronously then enqueues. Fan-out renders per recipient
-and enqueues one job each.
+`.queue()` renders per recipient and enqueues one job per recipient. Without a
+configured dispatcher, it rejects `NoQueueDispatcherError`.
 
 ## Idempotency
 
-Pass `idempotencyKey` so a redelivered/retried job doesn't create a duplicate
-in-app row — `createFor` find-or-creates on the key.
+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}` });
 ```
 
-## Phase notes / current limits
+## Current limits
 
-- **`delay` is carried on the job but not yet honored** — the worker delivers
-  immediately. Delay-aware delivery lands with a scheduled worker.
-- **No retry / dead-letter yet** — a failed `channel.send` is logged + acked
-  (no poison-message loop). DLQ handling is a follow-up.
-- Rate-limit budget is consumed at ENQUEUE time for queued sends (see
-  `RateLimiter` docstring).
+- 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.
+- [`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.

package/cjs/rabbitmq-driver-Dn0M0-ln.cjs

@@ -1,3 +0,0 @@
-const require_src = require('./src-Cx9y1PWY.cjs');
-
-exports.RabbitMQDriver = require_src.RabbitMQDriver;