@warlock.js/notifications 5.23.2 → 5.25.0

package/package.json

@@ -5,16 +5,16 @@
     "environment": "server"
   },
   "dependencies": {
-    "@warlock.js/cache": "5.23.2",
-    "@warlock.js/cascade": "5.23.2",
-    "@warlock.js/core": "5.23.2",
-    "@warlock.js/logger": "5.23.2"
+    "@warlock.js/cache": "5.25.0",
+    "@warlock.js/cascade": "5.25.0",
+    "@warlock.js/core": "5.25.0",
+    "@warlock.js/logger": "5.25.0"
   },
   "optionalDependencies": {
-    "@warlock.js/herald": "5.23.2"
+    "@warlock.js/herald": "5.25.0"
   },
   "peerDependencies": {
-    "@warlock.js/queue": "5.23.2"
+    "@warlock.js/queue": "5.25.0"
   },
   "peerDependenciesMeta": {
     "@warlock.js/queue": {
@@ -35,7 +35,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.23.2",
+  "version": "5.25.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/configure-notifications/SKILL.md

@@ -1,138 +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 and the recipient-scoped read/dismiss routes + controllers. 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.
+---
+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 and the recipient-scoped read/dismiss routes + controllers. 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

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