@warlock.js/notifications 4.2.0

package/llms.txt

@@ -0,0 +1,17 @@
+# Warlock Notifications
+
+> Package: `@warlock.js/notifications`
+
+> Multi-channel notifications for Warlock.js — define once, fire anywhere; mail / in-app database / pluggable custom channels with preferences, rate limits, and idempotency.
+
+## Skills
+
+- [configure-notifications](@warlock.js/notifications/configure-notifications/SKILL.md): Wire `@warlock.js/notifications` via a declarative `src/config/notifications.ts` that exports a `NotificationConfig` default — the notifications connector registers it at boot, so app code never calls `setNotificationConfig`. `channels`: registry mapping name → factory result (`mailChannel`, `inApp.configure`, custom `defineChannel`); `queue`: optional `QueueDispatcher` (`.queue()` throws without it); `preferences`: optional `PreferenceProvider` (drops channels the recipient muted); `rateLimit`: optional `RateLimiter` (drops channels exceeding per-recipient budgets). Triggers: `config/notifications.ts`, `NotificationConfig`, `setNotificationConfig`, `getNotificationConfig`, `mailChannel`, `inApp.configure`, "configure notifications", "wire notifications at boot", "set preferences provider", "set rate limit"; typical import `import { type NotificationConfig, mailChannel, inApp } from "@warlock.js/notifications"`. Skip: building a reusable notification — `@warlock.js/notifications/define-notification/SKILL.md`; the in-app read API — `@warlock.js/notifications/use-in-app/SKILL.md`; adding a custom channel — `@warlock.js/notifications/define-channel/SKILL.md`.
+- [define-channel](@warlock.js/notifications/define-channel/SKILL.md): Add a custom notification channel — `defineChannel<P>({ name, route?, send })` returns a `Channel<P>` you register in the `channels` map of `setNotificationConfig`. `name` matches the key in `NotificationChannels` (extend via `declare module` for typing); `route(notifiable)` resolves the recipient's address (defaults to `{ id }` when omitted); `send({ payload, route, notifiable, options })` does the actual transport. Use for Slack/Discord/internal-webhook/anything else — `fetch`-based with NO SDK is the simplest variant. Channels that load a heavy SDK should follow the lazy-import pattern from the develop-feature playbook. Triggers: `defineChannel`, `Channel<P>`, "custom notification channel", "add discord channel", "slack channel", "webhook channel", "new channel type", `declare module "@warlock.js/notifications"`; typical import `import { defineChannel } from "@warlock.js/notifications"`. Skip: lazy-loading an optional SDK behind the channel — `D:/xampp/htdocs/mongez/node/.claude/skills/develop-warlock.js-feature/SKILL.md`; using built-in channels — `@warlock.js/notifications/configure-notifications/SKILL.md`.
+- [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/*`.
+- [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

@@ -0,0 +1,40 @@
+{
+  "name": "@warlock.js/notifications",
+  "description": "Multi-channel notifications for Warlock.js — define once, fire anywhere; mail / in-app database / pluggable custom channels with preferences, rate limits, and idempotency.",
+  "keywords": [
+    "notifications",
+    "mail",
+    "in-app",
+    "multi-channel",
+    "warlock.js",
+    "typescript"
+  ],
+  "author": "hassanzohdy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/warlockjs/notifications"
+  },
+  "dependencies": {
+    "@warlock.js/cache": "4.2.0",
+    "@warlock.js/cascade": "4.2.0",
+    "@warlock.js/core": "4.2.0",
+    "@warlock.js/logger": "4.2.0"
+  },
+  "version": "4.2.0",
+  "main": "./cjs/index.cjs",
+  "module": "./esm/index.mjs",
+  "types": "./esm/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./esm/index.d.mts",
+        "default": "./esm/index.mjs"
+      },
+      "require": {
+        "types": "./esm/index.d.mts",
+        "default": "./cjs/index.cjs"
+      }
+    }
+  }
+}

package/skills/README.md

@@ -0,0 +1,23 @@
+# @warlock.js/notifications — skills
+
+All cross-references use the form `@warlock.js/notifications/<skill>/SKILL.md`.
+
+Skills are added as the package's public surface lands. Phase 0 (core dispatch) ships:
+
+- (incoming) `notifications-basics/` — what the package is, when to reach for it, the mental model.
+- (incoming) `define-notification/` — reusable multi-channel definitions; `via`, renderers, `(data, to, ctx)`.
+- (incoming) `send-ad-hoc/` — `notify.<channel>` proxy + `notify.channel(name)` runtime form.
+- (incoming) `configure-notifications/` — `config/notifications.ts`, `NotificationConfig`, `SendOptions`.
+- (incoming) `define-channel/` — custom channels via `defineChannel` + `declare module`.
+- (incoming) `use-in-app/` — `inApp.configure({model})`, `listUnread` / `markAsRead` / `markAsUnread`.
+- (incoming) `write-notification-migration/` — `notificationColumns(Notification)`, named from the model's `columnMap`.
+- (incoming) `observe-notifications/` — `notifications.on("sending" | "sent" | "failed" | "skipped", …)`.
+- `queue-notifications/` — async `.queue()` via the herald-backed dispatcher + worker.
+- (deferred — Phase 2, bridges) `gate-with-preferences/` — already covered in `configure-notifications`; promote if it grows.
+- (deferred — Phase 2, bridges) `send-via-whatsapp/`, `send-via-telegram/`, `send-via-push/`, `send-via-slack/`.
+
+Regenerate the LLM index after any change:
+
+```bash
+node scripts/generate-llms.mjs
+```

package/skills/configure-notifications/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: configure-notifications
+description: 'Wire `@warlock.js/notifications` via a declarative `src/config/notifications.ts` that exports a `NotificationConfig` default — the notifications connector registers it at boot, so app code never calls `setNotificationConfig`. `channels`: registry mapping name → factory result (`mailChannel`, `inApp.configure`, custom `defineChannel`); `queue`: optional `QueueDispatcher` (`.queue()` throws without it); `preferences`: optional `PreferenceProvider` (drops channels the recipient muted); `rateLimit`: optional `RateLimiter` (drops channels exceeding per-recipient budgets). Triggers: `config/notifications.ts`, `NotificationConfig`, `setNotificationConfig`, `getNotificationConfig`, `mailChannel`, `inApp.configure`, "configure notifications", "wire notifications at boot", "set preferences provider", "set rate limit"; typical import `import { type NotificationConfig, mailChannel, inApp } from "@warlock.js/notifications"`. Skip: building a reusable notification — `@warlock.js/notifications/define-notification/SKILL.md`; the in-app read API — `@warlock.js/notifications/use-in-app/SKILL.md`; adding a custom channel — `@warlock.js/notifications/define-channel/SKILL.md`.'
+---
+
+# Configure notifications
+
+`src/config/notifications.ts` exports a `NotificationConfig` as its default; the notifications connector registers it at boot and the dispatcher reads from it on every send. The file is **declarative** — you never call `setNotificationConfig` yourself (the connector does, the same way the rest of `src/config/*.ts` is wired).
+
+> `npx warlock add notifications` ejects this file pre-wired (mail + in-app) alongside the `Notification` model + migration. Edit the ejected config to taste — the sections below are the full surface.
+
+## Minimal
+
+```ts title="src/config/notifications.ts"
+import { type NotificationConfig, inApp, mailChannel } from "@warlock.js/notifications";
+import { Notification } from "app/notifications/notification.model";
+
+const config: NotificationConfig = {
+  channels: {
+    mail:     mailChannel({ from: "no-reply@store.com" }),
+    database: inApp.configure({ model: Notification }),
+  },
+};
+
+export default config;
+```
+
+The `database` channel is returned by `inApp.configure({ model | repository })` — it binds the in-app store AND returns the channel, so the read side + the write side share ONE repository instance.
+
+## Full surface
+
+```ts
+const config: NotificationConfig = {
+  channels: {
+    mail:     mailChannel({ from }),
+    database: inApp.configure({ model: Notification }),
+
+    // custom channels
+    discord:  discordChannel(),            // defineChannel + declare module
+  },
+
+  // optional gates — both app-owned; package ships no defaults
+  preferences: userPreferences,            // drops channels recipient muted
+  rateLimit,                               // drops channels over budget
+  queue: heraldQueue(),                    // backs `.queue()` (needs @warlock.js/herald)
+};
+
+export default config;
+```
+
+## Channel keys must match the registry
+
+`channels: { mail, database, discord }` — keys correspond to `NotificationChannels` entries. Built-ins (`mail`, `database`) ship in the registry; custom channels extend it with `declare module`.
+
+```ts
+// in your custom channel file
+declare module "@warlock.js/notifications" {
+  interface NotificationChannels {
+    discord: { content: string };
+  }
+}
+```
+
+After that, `notify.discord(...)`, `via: ["discord"]`, and the `discord:` key in `defineNotification` all autocomplete + type-check.
+
+## `inApp.configure({ model | repository })`
+
+Two paths; mutually exclusive at the type level.
+
+```ts
+// 90% case — pass the model class; default repo built internally.
+database: inApp.configure({ model: Notification }),
+
+// 10% case — pass a custom repo (only for EXTRA query methods; column names
+// come from the model's columnMap, not a repo override).
+database: inApp.configure({ repository: notificationsRepository }),
+```
+
+There is NO zero-arg form — the package ships no concrete table/model.
+
+## `preferences` — pre-send opt-in gate (optional)
+
+```ts
+import type { PreferenceProvider } from "@warlock.js/notifications";
+
+export const userPreferences: PreferenceProvider = {
+  resolveChannels(user, type, requested) {
+    const muted: Record<string, string[]> = user.get("preferences.muted") ?? {};
+    return requested.filter((c) => !(muted[c] ?? []).includes(type));
+  },
+};
+```
+
+Dropped channels fire a `skipped` event with reason `"preference"`. `SendOptions.force === true` bypasses this gate.
+
+## `rateLimit` — pre-send safety valve (optional)
+
+```ts
+import { cache } from "@warlock.js/cache";
+import type { RateLimiter } from "@warlock.js/notifications";
+
+export const rateLimit: RateLimiter = {
+  async allow(user, channel, type) {
+    const key = `notif.rl.${user.id}.${channel}.${type}`;
+    const count = await cache.increment(key, 1);
+    if (count === 1) await cache.set(key, 1, { ttl: 3600 });
+    return count <= 5;
+  },
+};
+```
+
+Dropped channels fire a `skipped` event with reason `"rate-limit"`. `force` does NOT bypass this — rate limits are a safety valve, not a UX preference.
+
+## Reading the config back
+
+```ts
+import { getNotificationConfig } from "@warlock.js/notifications";
+
+const cfg = getNotificationConfig();   // throws NotificationsNotConfiguredError if unset
+```
+
+## Tests
+
+Tests call `setNotificationConfig` directly — bypassing the connector — to set state, then `resetNotificationConfig` to tear down:
+
+```ts
+import { resetNotificationConfig, setNotificationConfig } from "@warlock.js/notifications";
+
+beforeEach(() => setNotificationConfig({ channels: { ... } }));
+afterEach(() => resetNotificationConfig());
+```
+
+## See also
+
+- [`notifications-basics/SKILL.md`](../notifications-basics/SKILL.md) — package front door.
+- [`define-notification/SKILL.md`](../define-notification/SKILL.md) — reusable multi-channel definitions.
+- [`use-in-app/SKILL.md`](../use-in-app/SKILL.md) — in-app read API.
+- [`define-channel/SKILL.md`](../define-channel/SKILL.md) — custom channels.

package/skills/define-channel/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: define-channel
+description: 'Add a custom notification channel — `defineChannel<P>({ name, route?, send })` returns a `Channel<P>` you register in the `channels` map of `setNotificationConfig`. `name` matches the key in `NotificationChannels` (extend via `declare module` for typing); `route(notifiable)` resolves the recipient''s address (defaults to `{ id }` when omitted); `send({ payload, route, notifiable, options })` does the actual transport. Use for Slack/Discord/internal-webhook/anything else — `fetch`-based with NO SDK is the simplest variant. Channels that load a heavy SDK should follow the lazy-import pattern from the develop-feature playbook. Triggers: `defineChannel`, `Channel<P>`, "custom notification channel", "add discord channel", "slack channel", "webhook channel", "new channel type", `declare module "@warlock.js/notifications"`; typical import `import { defineChannel } from "@warlock.js/notifications"`. Skip: lazy-loading an optional SDK behind the channel — `D:/xampp/htdocs/mongez/node/.claude/skills/develop-warlock.js-feature/SKILL.md`; using built-in channels — `@warlock.js/notifications/configure-notifications/SKILL.md`.'
+---
+
+# `defineChannel` — custom channels
+
+The escape hatch for channel types the package doesn't ship.
+
+## Minimal — `fetch`-based webhook (no SDK)
+
+```ts title="src/app/notifications/channels/discord.channel.ts"
+import { defineChannel } from "@warlock.js/notifications";
+
+type DiscordPayload = { content: string };
+
+export const discordChannel = () =>
+  defineChannel<DiscordPayload>({
+    name: "discord",
+    route: (notifiable) => notifiable.get("discord_webhook") as string,
+    async send({ payload, route }) {
+      const response = await fetch(route as string, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(payload),
+      });
+      if (!response.ok) throw new Error(`Discord send failed: ${response.status}`);
+    },
+  });
+
+// Teach TypeScript about the new channel — picks up notify.discord and
+// `defineNotification` typing.
+declare module "@warlock.js/notifications" {
+  interface NotificationChannels {
+    discord: DiscordPayload;
+  }
+}
+```
+
+Register in `config/notifications.ts`:
+
+```ts
+channels: {
+  // ...
+  discord: discordChannel(),
+}
+```
+
+Now `notify.discord(user, { content: "🎉" })` works, and `discord:` is a valid renderer key in `defineNotification`.
+
+## `route` resolution
+
+| What `route` returns | Effect |
+|---|---|
+| `string` | Used directly as the address (`"user@example.com"`, webhook URL). |
+| `{ id: Id }` | The recipient's storage id — for database/internal channels. |
+| `undefined` | Dispatcher falls back to `{ id: notifiable.id }`. |
+| `route` omitted | Same as returning `undefined` — `{ id }` fallback. |
+
+For raw-target ad-hoc sends (`notify.discord("https://hooks.../foo", payload)`), the raw string wins over `route()`.
+
+## `send` — the contract
+
+```ts
+async send({
+  payload,      // P — the channel's payload type
+  route,        // string | { id: Id } — resolved by `route()` or raw target
+  notifiable,   // Notifiable | undefined — undefined for raw-target ad-hoc
+  options,      // SendOptions — delay/locale/meta/idempotencyKey/force/type
+}): Promise<void>
+```
+
+Throw to fail the send. The dispatcher catches per channel, fires a `failed` event, and continues with siblings (per-channel isolation).
+
+## SDK-backed channels — lazy-import the SDK
+
+Channels that wrap a heavy SDK (Twilio, Slack SDK, FCM SDK) should follow the lazy-import pattern so apps that don't use them don't pay the install/load cost. The recipe + race-safe template lives in [`develop-warlock.js-feature`](../../../../.claude/skills/develop-warlock.js-feature/SKILL.md) — copy from there; do not invent a variant.
+
+Sketch:
+
+```ts
+import type { WebClient } from "@slack/web-api";
+let Slack: typeof import("@slack/web-api");
+let isModuleExists: boolean | null = null;
+
+async function loadSlack() { /* try/catch await import; set flag */ }
+loadSlack();
+
+export const slackChannel = (config: { token: string }) =>
+  defineChannel<{ text: string }>({
+    name: "slack",
+    route: (n) => n.get("slack_channel"),
+    async send({ payload, route }) {
+      await loadSlack();
+      if (!isModuleExists) throw new Error(INSTALL_INSTRUCTIONS);
+      const client = new Slack.WebClient(config.token);
+      await client.chat.postMessage({ channel: route as string, text: payload.text });
+    },
+  });
+```
+
+## See also
+
+- [`configure-notifications/SKILL.md`](../configure-notifications/SKILL.md) — register channels in the config.
+- [`send-ad-hoc/SKILL.md`](../send-ad-hoc/SKILL.md) — `notify.<custom-channel>` works after registration.
+- [`define-notification/SKILL.md`](../define-notification/SKILL.md) — multi-channel renderers with the custom channel key.
+- `D:/xampp/htdocs/mongez/node/.claude/skills/develop-warlock.js-feature/SKILL.md` — lazy-import pattern for SDK-backed channels.

package/skills/define-notification/SKILL.md

@@ -0,0 +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", …)`.

package/skills/notifications-basics/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: notifications-basics
+description: '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`.'
+---
+
+# `@warlock.js/notifications` — basics
+
+Multi-channel notifications for Warlock.js. **Define once, fire anywhere.**
+
+## What the package is for
+
+You have an event (`order.shipped`, `comment.mentioned`, `password.changed`) and one or more recipients. You want to address them through any combination of channels (mail, in-app, push, ...) with one render. That's what this package is.
+
+It is NOT a queue, a template engine, a transport library, or an analytics pipeline — it orchestrates *over* the transports cascade / core / herald / bridges already provide.
+
+## Four moving parts
+
+1. **`NotificationChannels`** — a TypeScript interface (declaration-merge target) mapping channel name → payload type. Drives `notify.<channel>` typing and `defineNotification` renderers.
+2. **`defineNotification`** — reusable multi-channel notification. Pass a `type`, a `via`, and a renderer per channel. Returns `{ send, queue, only }`.
+3. **`notify`** — Proxy facade for ad-hoc single-channel sends. `notify.<channel>(to, payload, options?)` works for any registered channel.
+4. **`inApp`** — facade for the database channel's read side. `inApp.configure({ model })` in the config returns the channel; `inApp.listUnread` / `markAsRead` / `markAsUnread` are the read API.
+
+## Minimal end-to-end
+
+`npx warlock add notifications` ejects the config + model + migration. The config is **declarative** — the notifications connector registers its default export at boot, so you never call `setNotificationConfig` yourself.
+
+```ts title="src/config/notifications.ts"
+import { type NotificationConfig, mailChannel, inApp } from "@warlock.js/notifications";
+import { Notification } from "app/notifications/notification.model";
+
+const config: NotificationConfig = {
+  channels: {
+    mail:     mailChannel({ from: "no-reply@store.com" }),
+    database: inApp.configure({ model: Notification }),
+  },
+};
+
+export default config;
+```
+
+```ts title="src/app/orders/notifications/order-shipped.ts"
+import { defineNotification } from "@warlock.js/notifications";
+
+export const orderShipped = defineNotification<{ orderId: string; number: string }>({
+  type: "order.shipped",
+  via: ["database", "mail"],
+  database: ({ orderId, number }) => ({
+    title: `Order #${number} shipped`,
+    payload: { orderId },
+  }),
+  mail: ({ number }, to) => ({
+    subject: `Order #${number} shipped`,
+    html: `<p>Hi ${to.get("name")}, on the way.</p>`,
+  }),
+});
+```
+
+```ts title="anywhere"
+import { notify, inApp } from "@warlock.js/notifications";
+import { orderShipped } from "app/orders/notifications/order-shipped";
+
+await orderShipped.send(user, { orderId: order.id, number: order.number });
+await notify.mail(user, { subject: "Welcome", html: "<p>Hi!</p>" });
+
+const unread = await inApp.listUnread(user);
+const badge  = await inApp.countUnread(user);
+await inApp.markAsRead(user, "ntf_123");
+```
+
+## Recipient = cascade `Model` instance
+
+`Notifiable` is typed as `Model`, so any cascade model is a valid recipient — `.id` (number | string) and `.get(path)` come for free. Routing is a **channel concern**, not a model concern — channels resolve `notifiable.email` / `.phone` / `.id` / etc. by convention (overridable in channel config).
+
+## Phase 1 vs Phase 2
+
+| Channel | Phase | How |
+|---|---|---|
+| `mail` | 1 ✅ | core `sendMail` |
+| `database` | 1 ✅ | cascade repo (recipient-scoped reads) |
+| `whatsapp` | 2 | bridges `MessageProvider` |
+| `telegram` | 2 | bridges `MessageProvider` |
+| `slack` | 2 | bridges `MessageProvider` |
+| `push` | 2 | bridges `PushProvider` |
+| your own | 1 ✅ | `defineChannel` + 3-line `declare module` |
+
+## See also
+
+- [`configure-notifications/SKILL.md`](../configure-notifications/SKILL.md) — wire `config/notifications.ts`.
+- [`define-notification/SKILL.md`](../define-notification/SKILL.md) — reusable multi-channel definitions.
+- [`send-ad-hoc/SKILL.md`](../send-ad-hoc/SKILL.md) — `notify.<channel>` shorthand.
+- [`use-in-app/SKILL.md`](../use-in-app/SKILL.md) — `inApp` read API.
+- [`define-channel/SKILL.md`](../define-channel/SKILL.md) — custom channels.
+- [`write-notification-migration/SKILL.md`](../write-notification-migration/SKILL.md) — columnMap-driven columns.
+- [`observe-notifications/SKILL.md`](../observe-notifications/SKILL.md) — events + metrics.

package/skills/observe-notifications/SKILL.md

@@ -0,0 +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.