@zerotal/notifications 1.0.0

package/src/NotificationFake.ts

@@ -0,0 +1,282 @@
+import { Application, currentApp } from "@zerotal/core";
+import type { Notifiable } from "./types.ts";
+import type { Notification } from "./Notification.ts";
+import type { NotificationRecord } from "./DatabaseChannel.ts";
+import type { OnDemandRoutes } from "./OnDemandNotifiable.ts";
+import { OnDemandNotifiable } from "./OnDemandNotifiable.ts";
+
+type Binding = unknown;
+
+interface CapturedNotification {
+  notifiable: Notifiable;
+  notification: Notification;
+  /** The channels the notification declared for this recipient. */
+  channels: string[];
+  /** Whether it went through `queue()` rather than `send()`. */
+  queued: boolean;
+}
+
+/**
+ * Drop-in replacement for NotificationManager that captures sent notifications
+ * instead of delivering them. Install at the start of a test; restore after.
+ *
+ * @example
+ * const notify = NotificationFake.install();
+ *
+ * await Notify.send(user, new OrderShippedNotification(order));
+ *
+ * notify.assertSentTo(user, OrderShippedNotification);
+ * notify.assertSentOn(user, OrderShippedNotification, "mail");
+ * notify.assertNothingSent(); // or assertSentCount(1)
+ *
+ * notify.restore(); // call in afterEach
+ */
+export class NotificationFake {
+  private readonly _sent: CapturedNotification[] = [];
+  private readonly _app: Application;
+  private readonly _original: Binding;
+
+  private constructor(app: Application, original: Binding) {
+    this._app = app;
+    this._original = original;
+  }
+
+  /** Replace the 'notifications' container binding with this fake. */
+  static install(): NotificationFake {
+    const app = currentApp();
+    const original = app.container.registry.get("notifications");
+    const fake = new NotificationFake(app, original);
+    app.container.value("notifications", fake);
+    return fake;
+  }
+
+  /** Restore the original 'notifications' binding. Call in afterEach. */
+  restore(): void {
+    if (this._original !== undefined) {
+      this._app.container.registry.set("notifications", this._original as never);
+    } else {
+      this._app.container.registry.delete("notifications");
+    }
+  }
+
+  // ── Notification manager interface ───────────────────────────────────────
+
+  async send(notifiable: Notifiable, notification: Notification): Promise<void> {
+    this._capture(notifiable, notification, false);
+  }
+
+  async queue(notifiable: Notifiable, notification: Notification): Promise<void> {
+    this._capture(notifiable, notification, true);
+  }
+
+  async sendMany(notifiables: Iterable<Notifiable>, notification: Notification): Promise<void> {
+    for (const notifiable of notifiables) this._capture(notifiable, notification, false);
+  }
+
+  async queueMany(notifiables: Iterable<Notifiable>, notification: Notification): Promise<void> {
+    for (const notifiable of notifiables) this._capture(notifiable, notification, true);
+  }
+
+  route(routes: OnDemandRoutes): {
+    notify(notification: Notification): Promise<void>;
+    notifyLater(notification: Notification): Promise<void>;
+  } {
+    const notifiable = new OnDemandNotifiable(routes);
+    return {
+      notify: async (notification) => this._capture(notifiable, notification, false),
+      notifyLater: async (notification) => this._capture(notifiable, notification, true),
+    };
+  }
+
+  /** Registering a custom channel on the fake is a no-op — nothing is delivered. */
+  extend(): this {
+    return this;
+  }
+
+  channels(): string[] {
+    return ["mail", "database", "slack", "sms", "broadcast"];
+  }
+
+  /**
+   * An inert stand-in for the real database channel.
+   *
+   * A faked send writes no rows, so the inbox is empty rather than absent — code
+   * under test that reads `unreadNotifications()` keeps working instead of
+   * throwing on a missing property. Assert on what was sent, not on this.
+   */
+  get database(): {
+    all(): Promise<NotificationRecord[]>;
+    unread(): Promise<NotificationRecord[]>;
+    unreadCount(): Promise<number>;
+    markAllAsRead(): Promise<void>;
+    markAsRead(): Promise<void>;
+    markAsUnread(): Promise<void>;
+    delete(): Promise<void>;
+    clear(): Promise<void>;
+  } {
+    return {
+      all: async () => [],
+      unread: async () => [],
+      unreadCount: async () => 0,
+      markAllAsRead: async () => undefined,
+      markAsRead: async () => undefined,
+      markAsUnread: async () => undefined,
+      delete: async () => undefined,
+      clear: async () => undefined,
+    };
+  }
+
+  private _capture(notifiable: Notifiable, notification: Notification, queued: boolean): void {
+    let channels: string[] = [];
+    try {
+      channels = notification.channels(notifiable);
+    } catch {
+      /* a notification whose channels() throws is still worth recording */
+    }
+    this._sent.push({ notifiable, notification, channels, queued });
+  }
+
+  // ── Assertions ───────────────────────────────────────────────────────────
+
+  /** All captured notifications. */
+  sent(): CapturedNotification[] {
+    return [...this._sent];
+  }
+
+  /** Captured notifications for one recipient. */
+  sentTo(notifiable: Notifiable): CapturedNotification[] {
+    return this._sent.filter(({ notifiable: n }) => String(n.id) === String(notifiable.id));
+  }
+
+  /**
+   * Assert that a notification was sent to the given notifiable.
+   * Pass an optional filter callback to narrow the assertion.
+   *
+   * @example
+   * notify.assertSentTo(user, OrderShippedNotification);
+   * notify.assertSentTo(user, OrderShippedNotification, (n) => n.orderId === 42);
+   */
+  assertSentTo<T extends Notification>(
+    notifiable: Notifiable,
+    NotificationClass: new (...args: never[]) => T,
+    callback?: (notification: T) => boolean,
+  ): void {
+    const matching = this._match(notifiable, NotificationClass, callback);
+    if (matching.length === 0) {
+      const hint = callback ? " matching the given filter" : "";
+      throw new Error(
+        `Expected ${NotificationClass.name} to have been sent to notifiable #${notifiable.id}${hint}, but it was not.${this._summary()}`,
+      );
+    }
+  }
+
+  /** Assert that a notification class was NOT sent to the given notifiable. */
+  assertNotSentTo<T extends Notification>(
+    notifiable: Notifiable,
+    NotificationClass: new (...args: never[]) => T,
+  ): void {
+    const matching = this._match(notifiable, NotificationClass);
+    if (matching.length > 0) {
+      throw new Error(
+        `Expected ${NotificationClass.name} NOT to have been sent to notifiable #${notifiable.id}, but it was (${matching.length}×).`,
+      );
+    }
+  }
+
+  /**
+   * Assert a notification was sent to a recipient on a specific channel.
+   *
+   * @example
+   * notify.assertSentOn(user, PasswordChanged, "mail");
+   */
+  assertSentOn<T extends Notification>(
+    notifiable: Notifiable,
+    NotificationClass: new (...args: never[]) => T,
+    channel: string,
+  ): void {
+    const matching = this._match(notifiable, NotificationClass);
+    if (matching.length === 0) {
+      throw new Error(
+        `Expected ${NotificationClass.name} to have been sent to notifiable #${notifiable.id} on '${channel}', but it was not sent at all.${this._summary()}`,
+      );
+    }
+    if (!matching.some((m) => m.channels.includes(channel))) {
+      const seen = [...new Set(matching.flatMap((m) => m.channels))];
+      throw new Error(
+        `Expected ${NotificationClass.name} to have been sent to notifiable #${notifiable.id} on '${channel}', ` +
+          `but it declared: ${seen.join(", ") || "no channels"}.`,
+      );
+    }
+  }
+
+  /** Assert a notification was queued rather than sent immediately. */
+  assertQueued<T extends Notification>(
+    notifiable: Notifiable,
+    NotificationClass: new (...args: never[]) => T,
+  ): void {
+    const matching = this._match(notifiable, NotificationClass);
+    if (!matching.some((m) => m.queued)) {
+      throw new Error(
+        `Expected ${NotificationClass.name} to have been queued for notifiable #${notifiable.id}, ` +
+          `but ${matching.length === 0 ? "it was not sent at all" : "it was sent immediately"}.${this._summary()}`,
+      );
+    }
+  }
+
+  /** Assert how many times a notification class was sent, to anyone. */
+  assertSentTimes<T extends Notification>(
+    NotificationClass: new (...args: never[]) => T,
+    count: number,
+  ): void {
+    const actual = this._sent.filter(
+      ({ notification }) => notification instanceof NotificationClass,
+    ).length;
+    if (actual !== count) {
+      throw new Error(
+        `Expected ${NotificationClass.name} to have been sent ${count}×, but it was sent ${actual}×.`,
+      );
+    }
+  }
+
+  /** Assert that zero notifications were sent. */
+  assertNothingSent(): void {
+    if (this._sent.length > 0) {
+      const names = this._sent.map(({ notification }) => notification.constructor.name).join(", ");
+      throw new Error(
+        `Expected nothing to be sent, but ${this._sent.length} notification(s) were: ${names}.`,
+      );
+    }
+  }
+
+  /** Assert the exact total number of notifications sent. */
+  assertSentCount(count: number): void {
+    if (this._sent.length !== count) {
+      throw new Error(
+        `Expected ${count} notification(s) to be sent, but ${this._sent.length} were.${this._summary()}`,
+      );
+    }
+  }
+
+  private _match<T extends Notification>(
+    notifiable: Notifiable,
+    NotificationClass: new (...args: never[]) => T,
+    callback?: (notification: T) => boolean,
+  ): CapturedNotification[] {
+    return this._sent.filter(
+      ({ notifiable: n, notification }) =>
+        String(n.id) === String(notifiable.id) &&
+        notification instanceof NotificationClass &&
+        (callback === undefined || callback(notification as T)),
+    );
+  }
+
+  /** What was actually captured — the first thing you want when an assertion fails. */
+  private _summary(): string {
+    if (this._sent.length === 0) return " Nothing was sent.";
+    const lines = this._sent.map(
+      ({ notification, notifiable, channels, queued }) =>
+        `${notification.constructor.name} → #${notifiable.id} [${channels.join(", ") || "no channels"}]${queued ? " (queued)" : ""}`,
+    );
+    return ` Sent: ${lines.join("; ")}.`;
+  }
+}

package/src/NotificationManager.ts

@@ -0,0 +1,269 @@
+import type { Notifiable, NotificationChannel, NotificationConfigShape } from "./types.ts";
+import {
+  NotificationChannelNotConfiguredError,
+  NotificationDispatchError,
+  UnknownNotificationChannelError,
+} from "./errors.ts";
+import type { Notification } from "./Notification.ts";
+import { MailChannel } from "./MailChannel.ts";
+import { DatabaseChannel } from "./DatabaseChannel.ts";
+import { SlackChannel } from "./SlackChannel.ts";
+import { SmsChannel } from "./SmsChannel.ts";
+import { BroadcastChannel } from "./BroadcastChannel.ts";
+import { OnDemandNotifiable, type OnDemandRoutes } from "./OnDemandNotifiable.ts";
+import { _getConnection } from "@zerotal/orm";
+import { FrameworkEvents } from "@zerotal/core";
+import { NotificationSent, MessageQueued } from "./events.ts";
+
+/** A channel factory, resolved once on first use. */
+type ChannelResolver = () => NotificationChannel;
+
+export class NotificationManager {
+  /** Channel name → resolver. Built-ins are seeded here; `extend()` adds to it. */
+  private readonly _resolvers = new Map<string, ChannelResolver>();
+  /** Resolved channel instances, memoized per name. */
+  private readonly _channels = new Map<string, NotificationChannel>();
+  private readonly _db: DatabaseChannel;
+
+  constructor(private readonly config: NotificationConfigShape) {
+    this._db = new DatabaseChannel(config.database.table, _getConnection());
+
+    this._resolvers.set("mail", () => new MailChannel(config.mail));
+    this._resolvers.set("database", () => this._db);
+    this._resolvers.set("broadcast", () => new BroadcastChannel());
+
+    this._resolvers.set("slack", () => {
+      if (config.slack === undefined) {
+        throw new NotificationChannelNotConfiguredError(
+          "slack",
+          'Add slack: { webhook: "..." } to config/notifications.ts.',
+        );
+      }
+      return new SlackChannel(config.slack);
+    });
+
+    this._resolvers.set("sms", () => {
+      if (config.sms === undefined) {
+        throw new NotificationChannelNotConfiguredError(
+          "sms",
+          'Add sms: { driver: "twilio", twilio: { ... } } to config/notifications.ts.',
+        );
+      }
+      return new SmsChannel(config.sms);
+    });
+  }
+
+  /**
+   * Register a custom delivery channel, or replace a built-in one.
+   *
+   * The factory runs once, the first time the channel is used, so a channel
+   * nobody sends on costs nothing.
+   *
+   * @example
+   * // in a service provider's onBooted()
+   * const notify = app.container.makeSync("notifications");
+   * notify.extend("discord", () => new DiscordChannel(config));
+   *
+   * // then, in a notification
+   * channels() { return ["discord"]; }
+   * toDiscord() { return { content: "Deploy finished" }; }
+   */
+  extend(channel: string, factory: ChannelResolver): this {
+    this._resolvers.set(channel, factory);
+    this._channels.delete(channel);
+    return this;
+  }
+
+  /** Every registered channel name, built-in and custom. */
+  channels(): string[] {
+    return [...this._resolvers.keys()];
+  }
+
+  /**
+   * Send a notification via all declared channels immediately.
+   *
+   * Every channel is attempted even if an earlier one fails — a Slack webhook
+   * returning 500 must not cost the recipient the email and the stored row that
+   * were declared alongside it. If any channel failed, the failures are reported
+   * together as a {@link NotificationDispatchError} once the rest are delivered.
+   *
+   * @throws {NotificationDispatchError} when one or more channels failed.
+   *
+   * @example
+   * await Notify.send(user, new OrderShippedNotification(order));
+   */
+  async send(notifiable: Notifiable, notification: Notification): Promise<void> {
+    const className = notification.constructor?.name ?? "Notification";
+    const recipient = NotificationManager._notifiableLabel(notifiable);
+
+    const failures: Array<{ channel: string; error: Error }> = [];
+    const delivered: string[] = [];
+
+    for (const channel of notification.channels(notifiable)) {
+      // Per-channel delivery telemetry — one NotificationSent event per channel,
+      // feeding the monitor's Notifications feed (distinct from the Mail log). This
+      // single point also covers queued sends, which route back through send().
+      const startedAt = performance.now();
+      try {
+        await this._dispatch(channel, notifiable, notification);
+        delivered.push(channel);
+        FrameworkEvents.emit(
+          new NotificationSent(className, channel, recipient, true, performance.now() - startedAt),
+        );
+      } catch (error) {
+        failures.push({
+          channel,
+          error: error instanceof Error ? error : new Error(String(error)),
+        });
+        FrameworkEvents.emit(
+          new NotificationSent(
+            className,
+            channel,
+            recipient,
+            false,
+            performance.now() - startedAt,
+            error instanceof Error ? error.message : String(error),
+          ),
+        );
+      }
+    }
+
+    if (failures.length > 0) {
+      // A single failing channel keeps its own error type, so `catch (e) { if (e
+      // instanceof NotificationDeliveryError) }` still works for the common case.
+      if (failures.length === 1 && delivered.length === 0) throw failures[0]!.error;
+      throw new NotificationDispatchError(className, failures, delivered);
+    }
+  }
+
+  /**
+   * Send one notification to many recipients.
+   *
+   * Recipients are independent: one failing does not stop the rest, and the
+   * errors are reported together at the end.
+   *
+   * @throws {NotificationDispatchError} when one or more recipients failed.
+   *
+   * @example
+   * await Notify.sendMany(admins, new LowStockNotification(product));
+   */
+  async sendMany(notifiables: Iterable<Notifiable>, notification: Notification): Promise<void> {
+    const failures: Array<{ channel: string; error: Error }> = [];
+    let delivered = 0;
+
+    for (const notifiable of notifiables) {
+      try {
+        await this.send(notifiable, notification);
+        delivered++;
+      } catch (error) {
+        failures.push({
+          channel: `recipient ${NotificationManager._notifiableLabel(notifiable)}`,
+          error: error instanceof Error ? error : new Error(String(error)),
+        });
+      }
+    }
+
+    if (failures.length > 0) {
+      throw new NotificationDispatchError(
+        notification.constructor?.name ?? "Notification",
+        failures,
+        Array.from({ length: delivered }, (_, i) => `recipient ${i + 1}`),
+      );
+    }
+  }
+
+  /** Queue one notification for many recipients. */
+  async queueMany(notifiables: Iterable<Notifiable>, notification: Notification): Promise<void> {
+    for (const notifiable of notifiables) {
+      await this.queue(notifiable, notification);
+    }
+  }
+
+  /**
+   * Notify a destination that has no model behind it — a bare email address,
+   * phone number, or Slack webhook.
+   *
+   * @example
+   * await Notify.route({ mail: "ops@acme.test" }).notify(new DeployFinished(build));
+   * await Notify.route({ sms: "+15551234567", mail: "on-call@acme.test" })
+   *   .notifyLater(new PagerAlert(incident));
+   */
+  route(routes: OnDemandRoutes): {
+    notify(notification: Notification): Promise<void>;
+    notifyLater(notification: Notification): Promise<void>;
+  } {
+    const notifiable = new OnDemandNotifiable(routes);
+    return {
+      notify: (notification) => this.send(notifiable, notification),
+      notifyLater: (notification) => this.queue(notifiable, notification),
+    };
+  }
+
+  /** A stable recipient label: email when present, else the id. */
+  private static _notifiableLabel(n: Notifiable): string {
+    return n.email ?? String(n.id);
+  }
+
+  /**
+   * Queue the notification for background delivery via @zerotal/queue.
+   *
+   * @example
+   * await Notify.queue(user, new OrderShippedNotification(order));
+   */
+  async queue(notifiable: Notifiable, notification: Notification): Promise<void> {
+    // If this notification mails, log it as "queued" now — the Mail tab shows the
+    // deferred message immediately, before SendNotificationJob delivers it (at which
+    // point MessageSent flips it to "sent"). Telemetry must never block the queue.
+    if (notification.channels(notifiable).includes("mail")) {
+      try {
+        const message = await notification.toMail(notifiable);
+        const to = notifiable.routeNotificationFor?.("mail") ?? notifiable.email;
+        const fallbackTo = to
+          ? [{ address: to, ...(notifiable.name ? { name: notifiable.name } : {}) }]
+          : [];
+        const payload = message.toPayload(this.config.mail.from, fallbackTo);
+        FrameworkEvents.emit(
+          new MessageQueued(
+            notification.constructor?.name ?? "Notification",
+            payload.to.map((a) => a.address),
+            payload.subject,
+            "notifications",
+          ),
+        );
+      } catch {
+        /* never block queuing on telemetry */
+      }
+    }
+    const { SendNotificationJob } = await import("./SendNotificationJob.ts");
+    const { Queue } = await import("@zerotal/queue");
+    await Queue.dispatch(new SendNotificationJob(notifiable, notification));
+  }
+
+  /** Expose the database channel for direct queries (unread, markAsRead). */
+  get database(): DatabaseChannel {
+    return this._db;
+  }
+
+  private async _dispatch(
+    channel: string,
+    notifiable: Notifiable,
+    notification: Notification,
+  ): Promise<void> {
+    await this._resolveChannel(channel).send(notifiable, notification);
+  }
+
+  /** Resolve a channel by name, constructing it on first use. */
+  private _resolveChannel(channel: string): NotificationChannel {
+    const existing = this._channels.get(channel);
+    if (existing) return existing;
+
+    const resolver = this._resolvers.get(channel);
+    if (!resolver) {
+      throw new UnknownNotificationChannelError(channel, [...this._resolvers.keys()]);
+    }
+
+    const instance = resolver();
+    this._channels.set(channel, instance);
+    return instance;
+  }
+}

package/src/NotificationRegistry.ts

@@ -0,0 +1,37 @@
+import type { Notification } from "./Notification.ts";
+
+/**
+ * A notification class, optionally with a custom `fromPayload` reviver. The
+ * reviver may be async — rebuilding often means loading a record back.
+ */
+export type NotificationClass = (new (...args: never[]) => Notification) & {
+  fromPayload?(data: Record<string, unknown>): Notification | Promise<Notification>;
+};
+
+/**
+ * Global registry mapping notification class names to their constructors.
+ *
+ * A queued notification is stored as `{ type, data }` — the class name plus the
+ * result of `payload()`. When a worker picks the job up it has only those two
+ * strings, so the class must be reachable by name to be rebuilt. That is what
+ * this registry provides.
+ *
+ * Registration is automatic in the common case: {@link discoverNotifications}
+ * imports `app/notifications/*.ts` and registers every exported notification
+ * class. Call `register()` yourself only for notifications that live elsewhere.
+ */
+export const NotificationRegistry = {
+  _map: new Map<string, NotificationClass>(),
+
+  register(NotificationClass: NotificationClass): void {
+    NotificationRegistry._map.set(NotificationClass.name, NotificationClass);
+  },
+
+  resolve(className: string): NotificationClass | undefined {
+    return NotificationRegistry._map.get(className);
+  },
+
+  all(): ReadonlyMap<string, NotificationClass> {
+    return NotificationRegistry._map;
+  },
+};

package/src/OnDemandNotifiable.ts

@@ -0,0 +1,46 @@
+import type { Notifiable } from "./types.ts";
+
+/** Per-channel destinations for a recipient with no model behind it. */
+export interface OnDemandRoutes {
+  /** Email address for the `mail` channel. */
+  mail?: string;
+  /** E.164 phone number for the `sms` channel. */
+  sms?: string;
+  /** Incoming webhook URL for the `slack` channel. */
+  slack?: string;
+  /** Broadcast channel name for the `broadcast` channel. */
+  broadcast?: string;
+  /** Destination for a channel registered with `extend()`. */
+  [channel: string]: string | undefined;
+}
+
+/**
+ * A recipient addressed directly rather than looked up — `Notify.route({ mail:
+ * "ops@acme.test" })`.
+ *
+ * It satisfies `Notifiable` without being a model, so every channel works
+ * unchanged. The `database` channel is the exception worth knowing about: rows
+ * it writes are keyed to a random id nothing can query back, which is why an
+ * on-demand notification normally declares only transport channels.
+ */
+export class OnDemandNotifiable implements Notifiable {
+  readonly id: string;
+  readonly email?: string;
+  readonly phone?: string;
+
+  constructor(private readonly _routes: OnDemandRoutes) {
+    this.id = `on-demand:${crypto.randomUUID()}`;
+    // Assigned only when present: `exactOptionalPropertyTypes` distinguishes an
+    // absent optional field from one explicitly set to undefined.
+    if (_routes.mail !== undefined) this.email = _routes.mail;
+    if (_routes.sms !== undefined) this.phone = _routes.sms;
+  }
+
+  routeNotificationFor(channel: string): string | undefined {
+    return this._routes[channel];
+  }
+
+  receivesBroadcastNotificationsOn(): string {
+    return this._routes.broadcast ?? `notifications.${this.id}`;
+  }
+}