@warlock.js/notifications 5.30.0 → 5.32.0

package/skills/observe-notifications/SKILL.md

@@ -12,27 +12,31 @@ 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 }));
+  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 }));
+  log.error(`notif.${channel}`, error, { userId: notifiable?.id }),
+);
 
 notifications.on("skipped", ({ channel, reason }) =>
-  metrics.inc(`notif.${channel}.skipped.${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 }));
+  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"` |
+| 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.
 

package/skills/send-ad-hoc/SKILL.md

@@ -32,7 +32,7 @@ Pass a string instead of a model to use the string as the route directly:
 
 ```ts
 await notify.mail("guest@example.com", { subject: "Receipt", html: "<p>…</p>" });
-await notify.whatsapp("+201234567890", { body: "Promo: 20% off!" });  // Phase 2
+await notify.whatsapp("+201234567890", { body: "Promo: 20% off!" }); // Phase 2
 ```
 
 When the recipient isn't a model, `PreferenceProvider` and `RateLimiter` are skipped — there's no `Notifiable` to consult.
@@ -74,14 +74,14 @@ await notify.slack(staff, { text: "Deploy starting" });
 
 ## SendOptions (3rd arg)
 
-| Field | Effect |
-|---|---|
-| `delay` | Reserved for `.queue` paths; not used by `notify.<channel>` (sync). |
-| `locale` | Forwarded to the channel's `send({ options })`. |
-| `meta` | Forwarded to the channel + included in every observability event. |
-| `idempotencyKey` | Injected into the database payload (dedupe). |
-| `force` | Bypass `PreferenceProvider`. Does NOT bypass `RateLimiter`. |
-| `type` | Notification type for gating (ad-hoc only). |
+| Field            | Effect                                                              |
+| ---------------- | ------------------------------------------------------------------- |
+| `delay`          | Reserved for `.queue` paths; not used by `notify.<channel>` (sync). |
+| `locale`         | Forwarded to the channel's `send({ options })`.                     |
+| `meta`           | Forwarded to the channel + included in every observability event.   |
+| `idempotencyKey` | Injected into the database payload (dedupe).                        |
+| `force`          | Bypass `PreferenceProvider`. Does NOT bypass `RateLimiter`.         |
+| `type`           | Notification type for gating (ad-hoc only).                         |
 
 ## Failure surfaces
 

package/skills/use-in-app/SKILL.md

@@ -81,7 +81,9 @@ abstract class DatabaseNotification extends Model implements NotificationContrac
 class BaseNotificationsRepository extends RepositoryManager {
   // constructor resolves the model's columnMap → builds `filterBy` +
   // createFor / markRead / markUnread / deleteFor from it.
-  public createFor(recipientId, input, tenantId?)   { /* one insert, starts unread */ }
+  public createFor(recipientId, input, tenantId?) {
+    /* one insert, starts unread */
+  }
 }
 ```
 
@@ -94,9 +96,9 @@ class BaseNotificationsRepository extends RepositoryManager {
 ```ts
 export type NotificationColumnMap = {
   recipient?: string; // recipient FK. Default "user_id"
-  tenant?: string;    // multi-tenant scope, written from the recipient. Omit → single-tenant
-  readAt?: string;    // read-timestamp column
-  isRead?: string;    // read-flag column (indexed)
+  tenant?: string; // multi-tenant scope, written from the recipient. Omit → single-tenant
+  readAt?: string; // read-timestamp column
+  isRead?: string; // read-flag column (indexed)
 };
 ```
 

package/skills/write-notification-migration/SKILL.md

@@ -22,12 +22,12 @@ export default Migration.create(Notification, notificationColumns(Notification))
 `notificationColumns(Notification)` reads the model's `columnMap` and returns the
 matching columns:
 
-| columnMap | Columns |
-|---|---|
-| _(none / default)_ | `user_id`, `type`, `title`, `body`, `payload`, `read_at`, `idempotency_key` |
-| `{ tenant: "organization_id", readAt: "read_at" }` | adds `organization_id`; read_at-only |
-| `{ isRead: "is_read" }` | swaps `read_at` for `is_read` (indexed boolean) |
-| `{ isRead: "is_read", readAt: "read_at" }` | both read-state columns |
+| columnMap                                          | Columns                                                                     |
+| -------------------------------------------------- | --------------------------------------------------------------------------- |
+| _(none / default)_                                 | `user_id`, `type`, `title`, `body`, `payload`, `read_at`, `idempotency_key` |
+| `{ tenant: "organization_id", readAt: "read_at" }` | adds `organization_id`; read_at-only                                        |
+| `{ isRead: "is_read" }`                            | swaps `read_at` for `is_read` (indexed boolean)                             |
+| `{ isRead: "is_read", readAt: "read_at" }`         | both read-state columns                                                     |
 
 The recipient / tenant / read-state column NAMES come from `columnMap`; `type` /
 `title` / `body` / `payload` / `idempotency_key` are fixed. `id` / `createdAt` /
@@ -40,7 +40,10 @@ are `bigint`, `integer`, or strings, pass `idType`; it is applied to every
 identifier column the factory creates:
 
 ```ts
-export default Migration.create(Notification, notificationColumns(Notification, { idType: "bigint" }));
+export default Migration.create(
+  Notification,
+  notificationColumns(Notification, { idType: "bigint" }),
+);
 ```
 
 ## With extras — spread + extend