@warlock.js/notifications 4.2.0

package/skills/queue-notifications/SKILL.md

@@ -0,0 +1,81 @@
+---
+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/*`.'
+---
+
+# Queue notifications (async)
+
+Move slow channels (SMTP, HTTP) off the request path. `.queue()` publishes a
+rendered job to herald; a worker delivers it.
+
+## Wire the 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(), // → `.queue()` now works
+};
+
+export default config; // the notifications connector registers it at boot
+```
+
+`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.
+
+Without `queue` configured, `.queue()` rejects `NoQueueDispatcherError` — a loud
+config error, not a silent no-op.
+
+## Run the worker
+
+In a worker entrypoint (or the web process), after the config + the herald
+broker are up:
+
+```ts
+import { startNotificationsWorker } from "@warlock.js/notifications";
+
+await startNotificationsWorker(); // subscribes to "notifications.dispatch"
+```
+
+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.
+
+## Send
+
+```ts
+await orderShipped.queue(user, { order });               // async
+await orderShipped.queue(buyers, { order }, { delay: "10m" });
+await notify.mail(user, payload, { /* sync — notify.* doesn't queue */ });
+```
+
+`.queue()` renders synchronously then enqueues. Fan-out renders per recipient
+and enqueues one job each.
+
+## Idempotency
+
+Pass `idempotencyKey` so a redelivered/retried job doesn't create a duplicate
+in-app row — `createFor` find-or-creates on the key.
+
+```ts
+await orderShipped.queue(user, { order }, { idempotencyKey: `ship:${order.id}` });
+```
+
+## Phase notes / 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).
+
+## 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.

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

@@ -0,0 +1,95 @@
+---
+name: send-ad-hoc
+description: '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`.'
+---
+
+# `notify.<channel>` — ad-hoc, per-channel sends
+
+When you don't need a reusable definition — fire one channel, one recipient.
+
+```ts
+import { notify } from "@warlock.js/notifications";
+
+await notify.mail(user, { subject: "Welcome", html: "<p>Hi!</p>" });
+await notify.database(user, { type: "welcome", title: "Welcome!" });
+```
+
+For **multi-channel** sends, use [`defineNotification`](../define-notification/SKILL.md) — that's the reusable pattern and the only mental model for "send through several channels at once" (no inline multi-channel overload).
+
+## Shape
+
+```ts
+notify.<channel>(
+  to:      Notifiable | string,           // model OR raw route
+  payload: NotificationChannels[channel], // typed per channel
+  options?: SendOptions,
+): Promise<void>
+```
+
+## Raw target — no model
+
+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
+```
+
+When the recipient isn't a model, `PreferenceProvider` and `RateLimiter` are skipped — there's no `Notifiable` to consult.
+
+## Runtime-dynamic channel name
+
+When the channel isn't a literal, use `notify.channel(name).send(...)`:
+
+```ts
+const channelName = await chooseChannelForUser(user);
+await notify.channel(channelName).send(user, payload);
+```
+
+This is the only path with `unknown`-typed payloads — prefer the literal `notify.<channel>` when you can.
+
+## Opt into preference/rate-limit gating
+
+Ad-hoc sends bypass the preference gate unless a notification `type` is known. Two ways to provide it:
+
+```ts
+// 1. Explicit — wins regardless of payload.
+await notify.mail(user, payload, { type: "marketing.weekly" });
+
+// 2. Auto-detected — database payloads carry their own `type` field.
+await notify.database(user, { type: "welcome", title: "Welcome!" });
+//                            ^^^^^^^^^^^^^^^ used for gating
+```
+
+`SendOptions.force === true` bypasses preferences. `RateLimiter` is consulted whenever a type is known (regardless of `force`).
+
+## Custom channels
+
+After registering a custom channel (see [`define-channel`](../define-channel/SKILL.md)), it's first-class:
+
+```ts
+await notify.discord(user, { content: "Build finished 🎉" });
+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). |
+
+## Failure surfaces
+
+`notify.<channel>` rejects on configuration errors (`ChannelNotFoundError`) — those are loud, immediate, and don't fire a `failed` event. Channel-level send failures rethrow AND fire a `failed` event with the channel + error.
+
+## See also
+
+- [`notifications-basics/SKILL.md`](../notifications-basics/SKILL.md) — front door + mental model.
+- [`define-notification/SKILL.md`](../define-notification/SKILL.md) — reusable multi-channel.
+- [`define-channel/SKILL.md`](../define-channel/SKILL.md) — register a custom channel.
+- [`observe-notifications/SKILL.md`](../observe-notifications/SKILL.md) — `sending` / `sent` / `failed` / `skipped` events.

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

@@ -0,0 +1,168 @@
+---
+name: use-in-app
+description: '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`.'
+---
+
+# `inApp` — in-app notification read API
+
+The in-app database channel has two sides:
+
+- **Write side** — `notify.database(user, {...})` and the database channel inside `defineNotification` create rows.
+- **Read side** — `inApp.list` / `listUnread` / `countUnread` / `markAsRead` / `markAsUnread` query and mutate.
+
+`inApp.configure({ model | repository })` binds the same repository for both sides, so cache invalidation just works.
+
+## Configure (once, in `config/notifications.ts`)
+
+```ts
+// 90% case — pass the model class; default repo built internally.
+database: inApp.configure({ model: Notification }),
+
+// 10% case — pass a custom repo.
+database: inApp.configure({ repository: notificationsRepository }),
+```
+
+## Reads
+
+```ts
+import { inApp } from "@warlock.js/notifications";
+
+// all rows for this recipient (paginated via the repo's standard `list`)
+const all = await inApp.list(user);
+
+// unread-only — pass `filter` to add type/etc. constraints
+const unread = await inApp.listUnread(user, { type: "order.shipped" });
+
+// cached unread count — backs the badge
+const badge = await inApp.countUnread(user);
+
+// one notification — for a detail view (recipient-scoped)
+const one = await inApp.find(user, "ntf_123");
+```
+
+All read methods accept a cascade `Notifiable` model OR a raw `id` (string | number) — convenient when you only have an id without fetching the user.
+
+```ts
+await inApp.list("user_42");
+await inApp.countUnread(123);
+```
+
+## Writes (recipient-scoped → no IDOR)
+
+```ts
+// mark ALL unread rows for this recipient as read
+await inApp.markAsRead(user);
+
+// mark ONE specific row — STILL scoped to this recipient
+await inApp.markAsRead(user, "ntf_123");
+
+// inverse
+await inApp.markAsUnread(user, "ntf_123");
+
+// delete / dismiss — one row, or clear all for this recipient
+await inApp.dismiss(user, "ntf_123");
+await inApp.dismiss(user);
+```
+
+The recipient-id is forced into the `where` clause. A controller that receives an `id` from the request and naively calls `inApp.markAsRead(currentUser, id)` cannot accidentally flip another user's row — even if the request contains a forged id. The mutation will simply update 0 rows.
+
+## Behind the scenes — `columnMap` drives everything
+
+The model declares its physical columns ONCE via `static columnMap`. The
+shipped `DatabaseNotification` accessors and `BaseNotificationsRepository`
+(read filter + write mapping) both derive from it, so they can never drift:
+
+```ts
+abstract class DatabaseNotification extends Model implements NotificationContract {
+  public static columnMap: NotificationColumnMap = {};
+  // recipientId / tenantId / isRead / readAt / markRead all read `columnMap`.
+}
+
+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 */ }
+}
+```
+
+### `columnMap` — map logical roles → your columns
+
+```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)
+};
+```
+
+**Read-state is chosen by which keys are PRESENT:**
+
+- `readAt` only → unread = `read_at IS NULL`; marking read stamps it.
+- `isRead` only → unread = `is_read = false`; no timestamp.
+- both → `is_read` is the indexed filter flag, `read_at` records WHEN.
+
+Declare neither and you get the `readAt`-only default — so a model can omit
+`columnMap` entirely. `unread` is the mode-agnostic read filter on `inApp` /
+the repo; there is no `isRead` filter key to remember.
+
+## Your model — declare `table`, `schema`, and `columnMap`
+
+```ts title="src/app/notifications/notification.model.ts"
+import { RegisterModel } from "@warlock.js/cascade";
+import { v } from "@warlock.js/seal";
+import { DatabaseNotification, type NotificationColumnMap } from "@warlock.js/notifications";
+
+// Mirrors the migration columns; cascade validates + casts every write.
+const notificationSchema = v.object({
+  user_id: v.string(),
+  type: v.string(),
+  title: v.string(),
+  body: v.string().nullish(),
+  payload: v.record(v.any()).nullish(),
+  read_at: v.date().nullish(),
+  idempotency_key: v.string().nullish(),
+});
+
+@RegisterModel()
+export class Notification extends DatabaseNotification {
+  public static table = "notifications";
+  public static schema = notificationSchema;
+  // read_at-only, single-tenant. Add `tenant: "organization_id"` for multi-tenant,
+  // swap to `isRead: "is_read"` (or add it) to change the read-state representation.
+  public static columnMap: NotificationColumnMap = { readAt: "read_at" };
+}
+```
+
+To change columns, edit `columnMap` — the migration (`notificationColumns`), the
+repo filter, and the accessors all follow. For a different driver's naming
+(e.g. MongoDB camelCase), name the columns in `columnMap`
+(`{ recipient: "userId", readAt: "readAt" }`).
+
+## Custom repository (advanced, optional)
+
+`columnMap` already covers column naming. Subclass only for EXTRA query methods:
+
+```ts title="src/app/notifications/notifications.repository.ts"
+import { BaseNotificationsRepository } from "@warlock.js/notifications";
+import { Notification } from "./notification.model";
+
+export class NotificationsRepository extends BaseNotificationsRepository<Notification> {
+  public source = Notification; // its columnMap still drives filter + write mapping
+  // …extra methods specific to your app
+}
+export const notificationsRepository = new NotificationsRepository();
+```
+
+Then swap config:
+
+```ts
+database: inApp.configure({ repository: notificationsRepository }),
+```
+
+## See also
+
+- [`notifications-basics/SKILL.md`](../notifications-basics/SKILL.md) — package front door.
+- [`configure-notifications/SKILL.md`](../configure-notifications/SKILL.md) — wire `inApp.configure` into the config.
+- [`write-notification-migration/SKILL.md`](../write-notification-migration/SKILL.md) — `notificationColumns(Notification)`, named from `columnMap`.
+- [`define-notification/SKILL.md`](../define-notification/SKILL.md) — create rows via the database channel.

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

@@ -0,0 +1,70 @@
+---
+name: write-notification-migration
+description: '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`.'
+---
+
+# Write the notifications migration
+
+The package ships no table or migration (thin eject). You own the migration; the package gives you a column factory that names columns from your model's `columnMap`, so it's one line.
+
+> `npx warlock add notifications` scaffolds this migration (+ the model) for you. Reach for this skill when you need to customize columns or add extras.
+
+## Common case — one line
+
+```ts title="src/app/notifications/migrations/01-01-2026_00-00-00-notifications.migration.ts"
+import { Migration } from "@warlock.js/cascade";
+import { notificationColumns } from "@warlock.js/notifications";
+import { Notification } from "../notification.model";
+
+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 |
+
+The recipient / tenant / read-state column NAMES come from `columnMap`; `type` /
+`title` / `body` / `payload` / `idempotency_key` are fixed. `id` / `createdAt` /
+`updatedAt` are added automatically by cascade.
+
+## With extras — spread + extend
+
+Add your own columns — a category, a source channel, a tenant id, anything:
+
+```ts
+import { Migration, string } from "@warlock.js/cascade";
+import { notificationColumns } from "@warlock.js/notifications";
+import { Notification } from "../notification.model";
+
+export default Migration.create(Notification, {
+  ...notificationColumns(Notification),
+  category: string().index().nullable(),
+});
+```
+
+Mirror any extra column in the model `schema`. To make it filterable, add a method to a custom repository (see `use-in-app/SKILL.md`).
+
+## Column naming follows `columnMap`
+
+The factory does NOT guess names from the driver — it reads the model's `columnMap`. To match a different convention (e.g. MongoDB camelCase), name the columns there and the migration follows:
+
+```ts
+class Notification extends DatabaseNotification {
+  public static columnMap = { recipient: "userId", readAt: "readAt" };
+}
+// → notificationColumns(Notification) emits `userId` + `readAt`
+```
+
+Without a model passed, defaults to `user_id` + `read_at` (read_at-only). See [`use-in-app/SKILL.md`](../use-in-app/SKILL.md) for the full `columnMap` shape.
+
+## See also
+
+- [`use-in-app/SKILL.md`](../use-in-app/SKILL.md) — the model + repository the migration backs.
+- [`@warlock.js/cascade/write-migration/SKILL.md`](../../../cascade/skills/write-migration/SKILL.md) — generic Cascade migration form, `Migration.alter`, etc.
+- [`@warlock.js/cascade/manage-data-sources/SKILL.md`](../../../cascade/skills/manage-data-sources/SKILL.md) — multi-data-source setup.