@warlock.js/notifications 5.34.0 → 5.34.2

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@warlock.js/notifications` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.34.2 - 2026-10-19
+
+### Fixed
+
+- Point the README at the package skill index, remove the outdated loose catalog, and include orientation in generated LLM projections.
+
 ## 5.32.0 - 2026-10-18
 
 ### Upgrading

package/README.md

@@ -58,7 +58,7 @@ await inApp.markAsRead(user); // recipient-scoped — no IDOR
 
 ## Skills
 
-The package ships `skills/<task>/SKILL.md` files describing every public surface. Browse the index at [`skills/README.md`](./skills/README.md) or load them via `agent-kit`.
+The package ships `skills/<task>/SKILL.md` files describing every public surface. Browse the index at [`skills/index.md`](./skills/index.md) or load them via `agent-kit`.
 
 ## License
 

package/llms-full.txt

@@ -4,6 +4,34 @@
 
 > Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/notifications/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.
 
+## Package orientation
+
+---
+description: 'Multi-channel notifications for Warlock: define once, send by mail, in-app database, or custom channels. Exports `defineNotification`, `notify`, `defineChannel`, `mailChannel`, `inApp`, `notificationColumns`, `notifications`, `bullmqQueue`, `heraldQueue`, `NotificationConfig`. Use for: "notify a user", "send order shipped by email and in-app", "unread notifications", "add a Slack or webhook channel", "queue notification delivery". Not this package: sending a plain email or mail templates → @warlock.js/core sendMail; background jobs → @warlock.js/queue.'
+---
+
+# @warlock.js/notifications
+
+An orchestrator over transports that already exist: one event, many recipients, any mix of channels, one render per channel. It is not a queue, template engine, or transport. `defineNotification` builds a reusable notification (`send`, `queue`, `only`); `notify.<channel>` does ad-hoc single-channel sends; `inApp` is the read side of the database channel. Server-only.
+
+## The 80% path
+
+1. Orient with `notifications-basics.md`.
+2. Configure channels in `src/config/notifications.ts`: `configure-notifications.md`; create the table: `write-notification-migration.md`.
+3. Define the notification with `via` and a renderer per channel: `define-notification.md`; one-off sends: `send-ad-hoc.md`.
+4. Serve the inbox (list, mark read): `use-in-app.md`.
+5. Custom channel: `define-channel.md`; deferred delivery: `queue-notifications.md`; sent/failed/skipped hooks: `observe-notifications.md`.
+
+## Conventions and pitfalls
+
+- The config is declarative; the connector registers its default export, so never call `setNotificationConfig` yourself.
+- Channel names are typed through `NotificationChannels` declaration merging.
+- `mailChannel` wraps core `sendMail`; use core directly for non-notification mail.
+- Every send accepts `force` and `idempotencyKey`; preferences and rate limits are pluggable gates.
+- `.queue()` needs a backend: `bullmqQueue` (with `@warlock.js/queue`) or `heraldQueue`.
+- Do not value-import from client code.
+
+
 ## configure-notifications  `@warlock.js/notifications/configure-notifications/SKILL.md`
 
 ---

package/llms.txt

@@ -6,6 +6,7 @@
 
 ## Skills
 
+- [Package orientation](@warlock.js/notifications/skills/index.md): Multi-channel notifications for Warlock: define once, send by mail, in-app database, or custom channels. Exports `defineNotification`, `notify`, `defineChannel`, `mailChannel`, `inApp`, `notificationColumns`, `notifications`, `bullmqQueue`, `heraldQueue`, `NotificationConfig`. Use for: "notify a user", "send order shipped by email and in-app", "unread notifications", "add a Slack or webhook channel", "queue notification delivery". Not this package: sending a plain email or mail templates → @warlock.js/core sendMail; background jobs → @warlock.js/queue.
 - [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 — the `define-notification` topic; the in-app read API — the `use-in-app` topic; adding a custom channel — the `define-channel` topic.
 - [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 — the `develop-warlock.js-feature` workspace skill; using built-in channels — the `configure-notifications` topic.
 - [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 — the `send-ad-hoc` topic; adding a brand-new channel — the `define-channel` topic; observing dispatch outcomes — the `observe-notifications` topic.

package/package.json

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

package/skills/README.md

@@ -1,23 +0,0 @@
-# @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
-```