@zerotal/notifications 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog — @zerotal/notifications
+
+All notable changes to this package are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/); this package
+follows the Zerotal monorepo's unified versioning.
+
+**Maturity: `beta`**
+
+## [Unreleased]
+
+### Fixed
+
+- Queued notifications survive a persistent queue driver. `SendNotificationJob`
+  serializes its notifiable and notification, and rebuilds both on the worker
+  side; previously only the sync driver worked, and SQLite/Redis delivered a job
+  whose recipient and notification were `undefined`.
+- The SMTP driver honours `secure`. It opens a TLS connection for `secure: true`,
+  upgrades via STARTTLS when a server offers it, and refuses to send credentials
+  over an unencrypted connection unless `allowInsecureAuth` says otherwise.
+- SMTP replies are parsed and their status codes checked, so a rejected
+  recipient or failed authentication raises instead of reporting a successful
+  send. The reader frames multi-line replies rather than assuming one per packet.
+- Header values are stripped of CR/LF before being written, closing a header
+  injection through a notification's subject or a display name. Non-ASCII header
+  values are encoded per RFC 2047, and body lines beginning with `.` are
+  dot-stuffed so a message is not truncated at its first such line.
+- The database channel records the recipient's own class as `notifiable_type` and
+  scopes every read by type and id together, so models sharing an id no longer
+  share an inbox.
+- A failing channel no longer cancels the others. Every declared channel is
+  attempted and the failures are reported together as `NotificationDispatchError`.
+
+### Added
+
+- Custom channels via `NotificationManager.extend(name, factory)`, resolved
+  lazily and able to replace a built-in.
+- `channels(notifiable)` receives the recipient, so one notification can route
+  per person's preferences, and `routeNotificationFor(channel)` lets a notifiable
+  redirect an individual channel.
+- `sendMany` / `queueMany` for many recipients, and `route()` for a destination
+  with no model behind it.
+- Mail attachments — `MailMessage.attach()`, `attachFile()`, and `embed()` for
+  inline images — carried by the SMTP, Resend, and log drivers.
+- `to*()` methods may return a promise, so building a message can do I/O.
+- Inbox operations: paging on `all()`/`unread()`, `unreadCount()`,
+  `markAsUnread()`, `delete()`, `clear()`, `recent()`, and `prune()`. The table
+  gains indexes on the recipient lookups.
+- `notifications:prune` and `notifications:test` console commands.
+- An admin panel console showing recent deliveries, per-channel totals, and the
+  stored inbox, gated on the `notifications.view` ability.
+- Config validation at boot through `NotificationConfig()` /
+  `validateNotificationConfig()`.
+- `NotificationFake` gains `assertSentOn`, `assertQueued`, `assertSentTimes`,
+  `sentTo`, an inert `database` accessor, and failure messages listing what was
+  actually captured.
+
+- `SlackMessage.webhookUrl` is optional; the URL resolves from the message, then
+  the notifiable's route, then `slack.webhook` in config.
+- `SmsMessage.to` is optional and defaults to the notifiable's `phone`.
+- `BroadcastMessage.onQueue()` delivers through the queue. `onConnection()` is
+  removed — the queue has no connection concept for it to name.
+
+## [1.0.0] — 2026-08-05
+
+_First public release._
+
+### Changed
+
+- Added a typed error vocabulary (`NotificationError` + `E_NOTIFICATION_*` codes).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerotal
+
+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,138 @@
+# @zerotal/notifications
+
+> Multi-channel notifications — mail, database, broadcast, Slack, and SMS — from a single class.
+
+Send the same notification across multiple delivery channels from one class: a `Notification` describes _what_ to send and which `channels()` to deliver on, while the `NotificationManager` routes it to each channel. Includes a `Notifiable` mixin for an object-oriented API and a `NotificationFake` for tests.
+
+Part of the [Zerotal](../../README.md) framework. Requires **Bun ≥ 1.3.14**.
+
+## Installation
+
+```bash
+bun add @zerotal/notifications
+```
+
+## Setup
+
+Register the provider in `bootstrap/providers.ts`:
+
+```ts
+import { NotificationProvider } from "@zerotal/notifications";
+```
+
+## Usage
+
+Write a notification by extending `Notification`, declaring `channels()`, then implementing a `to*()` method per channel:
+
+```ts
+import { Notification, MailMessage } from "@zerotal/notifications";
+import type { Notifiable } from "@zerotal/notifications";
+
+export class OrderShippedNotification extends Notification {
+  constructor(private order: Order) {
+    super();
+  }
+
+  channels() {
+    return ["mail", "database", "slack"];
+  }
+
+  toMail(_notifiable: Notifiable) {
+    return new MailMessage()
+      .subject(`Order #${this.order.id} shipped`)
+      .line("Your order is on its way.")
+      .action("Track package", `https://app.test/orders/${this.order.id}`);
+  }
+
+  toDatabase(_notifiable: Notifiable) {
+    return { orderId: this.order.id, status: "shipped" };
+  }
+
+  toSlack(_notifiable: Notifiable) {
+    return { text: `Order #${this.order.id} shipped` };
+  }
+}
+```
+
+The recipient is passed to `channels()`, so one notification can follow each person's preferences:
+
+```ts
+channels(user: Notifiable) {
+  return user.wantsSms ? ["database", "sms"] : ["database", "mail"];
+}
+```
+
+Send via the `Notify` facade or the `Notifiable` mixin:
+
+```ts
+import { Notify } from "@zerotal/notifications";
+
+await Notify.send(user, new OrderShippedNotification(order));
+await Notify.sendMany(admins, new LowStockNotification(product));
+await Notify.route({ mail: "ops@acme.test" }).notify(new DeployFinished(build));
+```
+
+```ts
+import { Notifiable } from "@zerotal/notifications";
+import { AuthUser } from "@zerotal/auth";
+
+export class User extends Notifiable(AuthUser) {}
+
+await user.notify(new OrderShippedNotification(order)); // send now
+await user.notifyLater(new OrderShippedNotification(order)); // queue
+const unread = await user.unreadNotifications();
+const badge = await user.unreadNotificationCount();
+```
+
+Every declared channel is attempted even if one fails, so a broken Slack webhook never costs the recipient their email. The failures are reported together afterwards as a `NotificationDispatchError`.
+
+Real-time delivery: add `"broadcast"` to `channels()` and return a `BroadcastMessage` from `toBroadcast()` (requires `BroadcastProvider`).
+
+Add a channel of your own with `extend()`:
+
+```ts
+const notifications = app.container.makeSync("notifications");
+notifications.extend("discord", () => new DiscordChannel(config));
+```
+
+Testing with `NotificationFake`:
+
+```ts
+import { NotificationFake } from "@zerotal/notifications";
+
+const notify = NotificationFake.install();
+await triggerShipment(order);
+notify.assertSentTo(user, OrderShippedNotification);
+notify.assertSentOn(user, OrderShippedNotification, "mail");
+notify.assertSentCount(1);
+notify.restore();
+```
+
+## Console commands
+
+- `bun zt notifications:prune --days 30` — delete stored notifications that have been read and are older than the threshold. Pass `--all` to include unread.
+- `bun zt notifications:test you@example.com` — send one real email through the configured mail driver, to check a transport end to end.
+
+## Exports
+
+- `Notification` — base class for notifications; declare `channels()` and `to*()` methods.
+- `Notify` — facade for `send` / `sendMany` / `queue` / `route` / `extend`.
+- `Notifiable` — mixin adding `notify`, `notifyLater`, and database-inbox helpers to a model (also the recipient contract type).
+- `NotificationManager` — the manager that routes notifications to channels.
+- `NotificationFake` — in-memory test double with `assertSentTo` / `assertSentOn` / `assertQueued` / `assertSentTimes` / `assertSentCount` / `assertNothingSent`.
+- `NotificationProvider` — service provider registering the manager.
+- `NotificationConfig` / `validateNotificationConfig` — config factory and its boot-time checks.
+- `NotificationRegistry` — registers a notification class for queue rebuilding when it lives outside `app/notifications/`.
+- Channels: `MailChannel`, `DatabaseChannel`, `SlackChannel`, `SmsChannel`, `BroadcastChannel`, plus `BROADCAST_NOTIFICATION_EVENT`.
+- `MailMessage` — fluent email builder with styled lines, a call-to-action, and attachments. `RichLine` builds mixed-style lines.
+- `BroadcastMessage` — payload wrapper for the broadcast channel (supports `.onQueue()`).
+- `OnDemandNotifiable` — recipient addressed directly rather than looked up.
+- Mail drivers: `LogDriver`, `SmtpDriver`, `ResendDriver`, and the `MailDriver` contract.
+- `SendNotificationJob` / `BroadcastNotificationJob` — queued jobs backing `notifyLater` and `onQueue`.
+- `recentDeliveries` / `channelStats` — in-process delivery counters behind the admin console.
+- Types: `Notifiable`, `NotificationChannel`, `NotificationConfigShape`, `SmsConfigShape`, `TwilioConfigShape`, `VonageConfigShape`, `NotificationRecord`, `InboxQuery`, `SlackMessage`, `SmsMessage`, `MailAttachment`, `TextStyle`.
+- Typed error vocabulary re-exported from `./errors`.
+
+## Documentation
+
+- [Notifications](../../docs/notifications.md)

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@zerotal/notifications",
+  "version": "1.0.0",
+  "license": "MIT",
+  "maturity": "beta",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/__fixtures__/**"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zerotal/core": "1.0.0",
+    "@zerotal/orm": "1.0.0",
+    "@zerotal/queue": "1.0.0"
+  },
+  "devDependencies": {
+    "@zerotal/broadcasting": "1.0.0",
+    "typescript": "^5.8.0"
+  },
+  "description": "Multi-channel notifications for Zerotal — mail (SMTP/Resend), database, broadcast, Slack, and SMS.",
+  "keywords": [
+    "zerotal",
+    "bun",
+    "typescript",
+    "framework",
+    "notifications",
+    "mail",
+    "slack",
+    "sms"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerotaldev/zerotal.git",
+    "directory": "packages/notifications"
+  },
+  "homepage": "https://github.com/zerotaldev/zerotal/tree/main/packages/notifications#readme",
+  "bugs": "https://github.com/zerotaldev/zerotal/issues"
+}

package/src/BroadcastChannel.ts

@@ -0,0 +1,80 @@
+import type { Notifiable } from "./types.ts";
+import type { Notification } from "./Notification.ts";
+import { BroadcastMessage } from "./BroadcastMessage.ts";
+import { NotificationChannelUnavailableError } from "./errors.ts";
+
+/** The wire event name used for every broadcast notification; the payload `type` distinguishes them. */
+export const BROADCAST_NOTIFICATION_EVENT = "notification";
+
+/**
+ * Notification channel that pushes a notification to a connected client in real time via
+ * `@zerotal/broadcasting`. Broadcasts on the notifiable's private channel
+ * (`private-notifications.{id}` by default) with the event name `"notification"`; the payload
+ * carries `{ ...data, id, type, readAt, createdAt }`.
+ */
+export class BroadcastChannel {
+  async send(notifiable: Notifiable, notification: Notification): Promise<void> {
+    // Lazy import so @zerotal/notifications has no hard dependency on @zerotal/broadcasting.
+    interface BroadcastApi {
+      Broadcast: {
+        to(channel: string, event: string, data: unknown): void;
+        later?(
+          channel: string,
+          event: string,
+          data: unknown,
+          options?: { queue?: string; connection?: string },
+        ): Promise<void> | void;
+      };
+    }
+    let broadcasting: BroadcastApi;
+    try {
+      broadcasting = (await import("@zerotal/broadcasting" as string)) as BroadcastApi;
+    } catch (error) {
+      // Distinguish "not installed" from "installed but threw on import" — the
+      // second reported as the first sends people to fix the wrong thing.
+      const detail = error instanceof Error ? error.message : String(error);
+      const missing = /cannot find (module|package)|module not found/i.test(detail);
+      throw new NotificationChannelUnavailableError(
+        missing
+          ? "[Zerotal] Notifications broadcast channel requires @zerotal/broadcasting. " +
+              "Register BroadcastProvider in bootstrap/providers.ts."
+          : `[Zerotal] Notifications broadcast channel could not load @zerotal/broadcasting — ${detail}`,
+      );
+    }
+
+    const result = await notification.toBroadcast(notifiable);
+    const message = result instanceof BroadcastMessage ? result : new BroadcastMessage(result);
+
+    const channel = this.channelFor(notifiable);
+    const type = notification.broadcastType();
+    const payload = {
+      ...message.data,
+      id: crypto.randomUUID(),
+      type,
+      readAt: null,
+      createdAt: new Date().toISOString(),
+    };
+
+    // A message routed with onQueue() is handed to the queue; anything else goes
+    // out inline, which is the point of the channel.
+    if (message.queue !== undefined) {
+      const { BroadcastNotificationJob } = await import("./BroadcastNotificationJob.ts");
+      const { Queue } = await import("@zerotal/queue");
+      await Queue.dispatch(
+        new BroadcastNotificationJob(channel, BROADCAST_NOTIFICATION_EVENT, payload, message.queue),
+      );
+      return;
+    }
+
+    broadcasting.Broadcast.to(channel, BROADCAST_NOTIFICATION_EVENT, payload);
+  }
+
+  /** The (prefixed) private channel a notifiable receives broadcast notifications on. */
+  channelFor(notifiable: Notifiable): string {
+    const custom = (
+      notifiable as { receivesBroadcastNotificationsOn?(): string }
+    ).receivesBroadcastNotificationsOn?.();
+    const name = custom ?? `notifications.${notifiable.id}`;
+    return name.startsWith("private-") || name.startsWith("presence-") ? name : `private-${name}`;
+  }
+}

package/src/BroadcastMessage.ts

@@ -0,0 +1,32 @@
+/**
+ * The broadcastable representation of a notification, returned from `Notification.toBroadcast()`.
+ * Wraps the data payload plus optional queue routing.
+ *
+ * @example
+ * toBroadcast() {
+ *   return new BroadcastMessage({ invoiceId: this.invoice.id, amount: this.invoice.amount });
+ * }
+ */
+export class BroadcastMessage {
+  /** Queue to deliver this broadcast on. Unset means deliver inline. */
+  queue: string | undefined = undefined;
+
+  constructor(public readonly data: Record<string, unknown>) {}
+
+  /**
+   * Deliver this broadcast from a queue rather than inline.
+   *
+   * Worth doing when the broadcast fans out to many connections and the
+   * request should not wait for it. The trade is latency: a queued broadcast
+   * arrives whenever a worker picks it up.
+   *
+   * @example
+   * toBroadcast() {
+   *   return new BroadcastMessage({ id: this.report.id }).onQueue("broadcasts");
+   * }
+   */
+  onQueue(queue: string): this {
+    this.queue = queue;
+    return this;
+  }
+}

package/src/BroadcastNotificationJob.ts

@@ -0,0 +1,51 @@
+import { Job, JobRegistry } from "@zerotal/queue";
+
+/**
+ * Delivers one broadcast notification from a queue.
+ *
+ * Dispatched only when a `BroadcastMessage` names a queue or connection via
+ * `onQueue()` / `onConnection()`; an unrouted broadcast goes out inline, since
+ * the whole point of the channel is immediacy. Its payload is the resolved wire
+ * data, so it round-trips through a persistent driver without needing the
+ * notification class.
+ */
+export class BroadcastNotificationJob extends Job {
+  override readonly queue: string;
+
+  constructor(
+    private readonly _channel: string = "",
+    private readonly _event: string = "",
+    private readonly _data: Record<string, unknown> = {},
+    queue = "broadcast",
+  ) {
+    super();
+    this.queue = queue;
+  }
+
+  override payload(): Record<string, unknown> {
+    return {
+      channel: this._channel,
+      event: this._event,
+      data: this._data,
+      queue: this.queue,
+    };
+  }
+
+  static fromPayload(data: Record<string, unknown>): BroadcastNotificationJob {
+    return new BroadcastNotificationJob(
+      data["channel"] as string,
+      data["event"] as string,
+      data["data"] as Record<string, unknown>,
+      (data["queue"] as string) ?? "broadcast",
+    );
+  }
+
+  async handle(): Promise<void> {
+    const { Broadcast } = (await import("@zerotal/broadcasting" as string)) as {
+      Broadcast: { to(channel: string, event: string, data: unknown): void };
+    };
+    Broadcast.to(this._channel, this._event, this._data);
+  }
+}
+
+JobRegistry.register(BroadcastNotificationJob);