@warlock.js/notifications 4.2.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog — @warlock.js/notifications
+
+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.
+
+## [Unreleased]
+
+### Changed
+
+- **In-app column mapping moved onto the model as `static columnMap`.** A notification model declares its physical columns once (`recipient` / `tenant` / `readAt` / `isRead`); `DatabaseNotification` accessors, `BaseNotificationsRepository` (read filter **and** write mapping), the `database` channel, and `notificationColumns` all derive from it — replacing the duplicated per-getter + `filterBy` column literals. New exported `NotificationColumnMap` type.
+- **Read-state is presence-based.** Declaring `readAt`, `isRead`, or both selects the representation (timestamp / indexed boolean / both); omitting both defaults to a `read_at` timestamp. The mode-agnostic `unread` filter replaces the `isRead` filter key on `inApp` and the repository.
+- **Multi-tenant support.** When the model declares a `tenant` column, the `database` channel reads the tenant value off the recipient and `createFor(recipientId, input, tenantId?)` writes it — no custom channel needed.
+- `inApp.list` / `inApp.listUnread` now forward full list options (`page` / `limit` / `orderBy` + filters), not just filter keys.
+- `notificationColumns(model)` names the recipient / tenant / read-state columns from `columnMap`; the SQL-vs-MongoDB `dataSource` branch is removed (declare the column names in `columnMap` instead).
+
+## 4.2.0
+
+### Added
+
+- Shipped Warlock.js Notifications Package.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Hassan Zohdy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @warlock.js/notifications
+
+Multi-channel notifications for Warlock.js — **define once, fire anywhere**.
+
+- 📬 **Mail** via `@warlock.js/core`'s `sendMail`.
+- 🗄️ **In-app database** with a recipient-scoped read API (no IDOR by construction).
+- 🔌 **Custom channels** via `defineChannel` (3-line escape hatch).
+- 🎚️ **Pluggable gates** for user preferences + rate limits.
+- 🔐 **`force` + `idempotencyKey`** on every send.
+- 📊 **Observability events** — `sent` / `failed` / `skipped`.
+
+> WhatsApp / Telegram / Slack / Push channels arrive with `@warlock.js/bridges` (Phase 2). Until then, roll your own with `defineChannel` + `fetch` — see the example app's `internal-webhook.channel.ts`.
+
+## Quick start
+
+```bash
+# installs the package, ejects a declarative config/notifications.ts,
+# and scaffolds the in-app model + migration into src/app/notifications/*
+npx warlock add notifications
+```
+
+```ts
+// src/app/orders/notifications/order-shipped.ts
+import { defineNotification } from "@warlock.js/notifications";
+
+export const orderShipped = defineNotification<{ order: Order }>({
+  via: ["mail", "database"],
+  mail: ({ order }, to) => ({
+    subject: `Order #${order.number} shipped`,
+    html: `<p>Hi ${to.get("name")}, your order is on the way.</p>`,
+  }),
+  database: ({ order }) => ({
+    type: "order.shipped",
+    title: "Your order shipped",
+    payload: { orderId: order.id },
+  }),
+});
+
+// anywhere
+await orderShipped.send(user, { order });
+await orderShipped.queue(buyers, { order }, { delay: "10m" });
+
+// ad-hoc
+await notify.mail(user, { subject: "Welcome", html: "<p>Hi!</p>" });
+
+// in-app reads
+await inApp.listUnread(user);
+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`.
+
+## License
+
+MIT