@zerotal/notifications 1.0.0

package/src/provider/NotificationProvider.ts

@@ -0,0 +1,62 @@
+import { ServiceProvider } from "@zerotal/core";
+import type { AppEnvironment } from "@zerotal/core";
+import type { ConfigManager } from "@zerotal/core/config";
+import { NotificationManager } from "../NotificationManager.ts";
+import { NotificationConfig } from "../config.ts";
+import { installNotificationsObservability } from "../observability.ts";
+import { installNotificationStats } from "../stats.ts";
+import { installNotificationsAdmin } from "../admin.ts";
+
+declare module "@zerotal/core" {
+  interface ContainerBindings {
+    notifications: NotificationManager;
+  }
+}
+
+export class NotificationProvider extends ServiceProvider {
+  static override provides = ["notifications"] as const;
+  static override environments: AppEnvironment[] = ["web", "console", "worker", "test"];
+
+  private _disposeObservability: (() => void) | undefined = undefined;
+  private _disposeStats: (() => void) | undefined = undefined;
+
+  override onRegister(): void {
+    this.app.container.singleton("notifications", () => {
+      const config = this.app.container.makeSync("config") as ConfigManager;
+      const cfg = config.get<ReturnType<typeof NotificationConfig>>(
+        "notifications",
+        NotificationConfig(),
+      );
+      return new NotificationManager(cfg);
+    });
+  }
+
+  override async onBooting(): Promise<void> {
+    // The admin panel binds its contribution surface during registration, so the
+    // booting phase reaches it regardless of provider order.
+    installNotificationsAdmin(this.app);
+  }
+
+  override async onBooted(): Promise<void> {
+    await this.app.container.make("notifications");
+    this._disposeObservability = installNotificationsObservability(this.app);
+    this._disposeStats = installNotificationStats();
+
+    const runner = this.app.container.tryMake("commands");
+    if (!runner) return;
+
+    runner.registerLazy("notifications:prune", () =>
+      import("../commands/NotificationsPruneCommand.ts").then((m) => m.NotificationsPruneCommand),
+    );
+    runner.registerLazy("notifications:test", () =>
+      import("../commands/NotificationsTestCommand.ts").then((m) => m.NotificationsTestCommand),
+    );
+  }
+
+  override async onStopping(): Promise<void> {
+    this._disposeObservability?.();
+    this._disposeObservability = undefined;
+    this._disposeStats?.();
+    this._disposeStats = undefined;
+  }
+}

package/src/serialization.ts

@@ -0,0 +1,188 @@
+/**
+ * Queue serialization for notifications.
+ *
+ * A notification queued with `notifyLater()` may be delivered by a different
+ * process from the one that queued it, so both the notification and its
+ * recipient have to survive a round trip through JSON. This module defines that
+ * wire form and rebuilds both sides of it.
+ *
+ * The recipient crosses as a **snapshot**, not a live model: channels read the
+ * `Notifiable` contract (`id`, `email`, `name`, `phone`) plus whatever else the
+ * model exposes through `toJSON()`. A hydrated notifiable is a plain object, so
+ * a `to*()` method that calls a model *method* on its recipient will not find it
+ * — read fields, not behaviour, when a notification is queued.
+ */
+import { NotificationRegistry } from "./NotificationRegistry.ts";
+import { UnknownNotificationTypeError } from "./errors.ts";
+import type { Notification } from "./Notification.ts";
+import type { Notifiable } from "./types.ts";
+
+/** The serialized form of a notifiable — its public fields plus routing hints. */
+export interface SerializedNotifiable extends Record<string, unknown> {
+  id: number | string;
+  /** The recipient's model/class name, so the database channel keeps its `notifiable_type`. */
+  __type?: string;
+  /** The resolved broadcast channel, captured because the method itself cannot cross. */
+  __broadcastChannel?: string;
+}
+
+/** The serialized form of one queued notification. */
+export interface SerializedNotification {
+  notifiable: SerializedNotifiable;
+  type: string;
+  data: Record<string, unknown>;
+}
+
+/** True for values that survive `JSON.stringify` without surprises. */
+function isPlain(value: unknown): boolean {
+  if (value === null) return true;
+  const t = typeof value;
+  if (t === "string" || t === "number" || t === "boolean") return true;
+  if (value instanceof Date) return true;
+  if (Array.isArray(value)) return value.every(isPlain);
+  if (t === "object") {
+    const proto = Object.getPrototypeOf(value as object) as unknown;
+    return proto === Object.prototype || proto === null;
+  }
+  return false;
+}
+
+/**
+ * Snapshot a notifiable for the queue.
+ *
+ * ORM models expose `toJSON()`, which already strips internal state (`_original`,
+ * `_exists`, …) and honours `hidden`/`visible`; that is the preferred source. For
+ * a plain object, own enumerable non-underscore fields are copied instead. Values
+ * that would not survive JSON (class instances, functions) are dropped rather
+ * than silently corrupted.
+ */
+export function serializeNotifiable(notifiable: Notifiable): SerializedNotifiable {
+  const candidate = notifiable as unknown as { toJSON?: () => Record<string, unknown> };
+  const source =
+    typeof candidate.toJSON === "function"
+      ? candidate.toJSON()
+      : (notifiable as unknown as Record<string, unknown>);
+
+  const out: SerializedNotifiable = { id: notifiable.id };
+  for (const [key, value] of Object.entries(source)) {
+    if (key.startsWith("_") || key.startsWith("$")) continue;
+    if (!isPlain(value)) continue;
+    out[key] = value;
+  }
+
+  // `id` may be hidden from toJSON() — the contract needs it regardless.
+  out.id = notifiable.id;
+
+  const type = notifiable.constructor?.name;
+  if (type && type !== "Object") out.__type = type;
+
+  // Resolve the custom broadcast channel now: it is a method, and methods do not
+  // cross a queue boundary.
+  const channel = notifiable.receivesBroadcastNotificationsOn?.();
+  if (channel !== undefined) out.__broadcastChannel = channel;
+
+  return out;
+}
+
+/** Rebuild a notifiable snapshot into something the channels can consume. */
+export function hydrateNotifiable(data: SerializedNotifiable): Notifiable {
+  const { __broadcastChannel, ...fields } = data;
+  const notifiable = fields as unknown as Notifiable;
+  if (__broadcastChannel !== undefined) {
+    notifiable.receivesBroadcastNotificationsOn = () => __broadcastChannel;
+  }
+  return notifiable;
+}
+
+/** The notifiable's originating class name, used as `notifiable_type`. */
+export function notifiableType(notifiable: Notifiable): string {
+  const explicit = (notifiable as unknown as { __type?: string }).__type;
+  if (typeof explicit === "string" && explicit.length > 0) return explicit;
+  const name = notifiable.constructor?.name;
+  return name && name !== "Object" ? name : "Notifiable";
+}
+
+/** Serialize one notification plus its recipient into the queued job payload. */
+export function serializeNotification(
+  notifiable: Notifiable,
+  notification: Notification,
+): SerializedNotification {
+  return {
+    notifiable: serializeNotifiable(notifiable),
+    type: notification.constructor.name,
+    data: notification.payload(),
+  };
+}
+
+let _discovered = false;
+
+/**
+ * Import `app/notifications/*.ts` so every notification class registers itself.
+ *
+ * A worker thread does not boot a full application, so the classes it must
+ * rebuild have never been imported there. This runs once, lazily, the first time
+ * a name fails to resolve — an app whose notifications are all already imported
+ * never pays for it.
+ */
+export async function discoverNotifications(): Promise<void> {
+  if (_discovered) return;
+  _discovered = true;
+
+  const dir = `${process.cwd()}/app/notifications`;
+  try {
+    const glob = new Bun.Glob("**/*.ts");
+    for await (const file of glob.scan({ cwd: dir, absolute: true })) {
+      const mod = (await import(`file://${file.replace(/\\/g, "/")}`)) as Record<string, unknown>;
+      for (const exported of Object.values(mod)) {
+        if (typeof exported === "function" && isNotificationClass(exported as AnyConstructor)) {
+          NotificationRegistry.register(exported as never);
+        }
+      }
+    }
+  } catch {
+    /* app/notifications/ doesn't exist — nothing to discover */
+  }
+}
+
+/** Any constructor, used only for walking a prototype chain. */
+type AnyConstructor = new (...args: never[]) => unknown;
+
+/** Walk the prototype chain looking for the `Notification` base class by name. */
+function isNotificationClass(value: AnyConstructor): boolean {
+  let proto: unknown = Object.getPrototypeOf(value) as unknown;
+  while (typeof proto === "function") {
+    if ((proto as AnyConstructor).name === "Notification") return true;
+    proto = Object.getPrototypeOf(proto) as unknown;
+  }
+  return false;
+}
+
+/**
+ * Rebuild a notification from its class name and serialized state, discovering
+ * app notification classes on demand when the name is not yet registered.
+ *
+ * @throws {UnknownNotificationTypeError} when the class cannot be found.
+ */
+export async function hydrateNotification(
+  type: string,
+  data: Record<string, unknown>,
+): Promise<Notification> {
+  let NotificationClass = NotificationRegistry.resolve(type);
+  if (!NotificationClass) {
+    await discoverNotifications();
+    NotificationClass = NotificationRegistry.resolve(type);
+  }
+  if (!NotificationClass) {
+    throw new UnknownNotificationTypeError(type, [...NotificationRegistry.all().keys()]);
+  }
+
+  if (typeof NotificationClass.fromPayload === "function") {
+    return NotificationClass.fromPayload(data);
+  }
+  return Object.assign(Object.create(NotificationClass.prototype) as Notification, data);
+}
+
+/** @internal Reset discovery memoization. Tests only. */
+export function _resetDiscovery(): void {
+  _discovered = false;
+}

package/src/stats.ts

@@ -0,0 +1,93 @@
+/**
+ * In-process delivery counters, kept for the admin panel.
+ *
+ * Best-effort and deliberately bounded: this is the "what is happening right
+ * now" view an operator wants when a channel starts failing, not a history. It
+ * is not persisted, and it resets when the process does — the durable record of
+ * a notification is the database channel.
+ */
+import { FrameworkEvents } from "@zerotal/core";
+import { NotificationSent } from "./events.ts";
+
+/** The most recent deliveries retained for the panel's feed. */
+const MAX_RECENT = 200;
+
+/** One recorded delivery attempt on one channel. */
+export interface RecentDelivery {
+  at: number;
+  className: string;
+  channel: string;
+  notifiable: string;
+  ok: boolean;
+  durationMs: number;
+  error: string | undefined;
+}
+
+/** Per-channel totals since the process booted. */
+export interface ChannelStat {
+  channel: string;
+  sent: number;
+  failed: number;
+  /** Mean duration in milliseconds across successful sends. */
+  avgMs: number;
+}
+
+const _recent: RecentDelivery[] = [];
+const _byChannel = new Map<string, { sent: number; failed: number; totalMs: number }>();
+let _installed: (() => void) | undefined;
+
+/** Subscribe the counters to the delivery event bus. Idempotent. */
+export function installNotificationStats(): () => void {
+  if (_installed) return _installed;
+
+  const off = FrameworkEvents.on(NotificationSent, (e) => {
+    _recent.push({
+      at: Date.now(),
+      className: e.className,
+      channel: e.channel,
+      notifiable: e.notifiable,
+      ok: e.ok,
+      durationMs: e.durationMs,
+      error: e.error,
+    });
+    if (_recent.length > MAX_RECENT) _recent.splice(0, _recent.length - MAX_RECENT);
+
+    const stat = _byChannel.get(e.channel) ?? { sent: 0, failed: 0, totalMs: 0 };
+    if (e.ok) {
+      stat.sent++;
+      stat.totalMs += e.durationMs;
+    } else {
+      stat.failed++;
+    }
+    _byChannel.set(e.channel, stat);
+  });
+
+  _installed = () => {
+    off();
+    _installed = undefined;
+  };
+  return _installed;
+}
+
+/** Recent delivery attempts, newest first. */
+export function recentDeliveries(): RecentDelivery[] {
+  return [..._recent].reverse();
+}
+
+/** Per-channel totals, busiest first. */
+export function channelStats(): ChannelStat[] {
+  return [..._byChannel.entries()]
+    .map(([channel, s]) => ({
+      channel,
+      sent: s.sent,
+      failed: s.failed,
+      avgMs: s.sent > 0 ? Math.round(s.totalMs / s.sent) : 0,
+    }))
+    .sort((a, b) => b.sent + b.failed - (a.sent + a.failed));
+}
+
+/** @internal Clear the counters. Tests only. */
+export function _resetStats(): void {
+  _recent.length = 0;
+  _byChannel.clear();
+}

package/src/types.ts

@@ -0,0 +1,129 @@
+/** The entity receiving the notification (typically a user). */
+export interface Notifiable {
+  id: number | string;
+  email?: string;
+  name?: string;
+  /** Phone number in E.164 format, required when using the sms channel. */
+  phone?: string;
+  /**
+   * Override the channel this notifiable receives broadcast notifications on.
+   * Default: `notifications.{id}` (broadcast as a private channel). Used by the 'broadcast' channel.
+   */
+  receivesBroadcastNotificationsOn?(): string;
+  /**
+   * Per-channel destination override, consulted before the default field.
+   *
+   * Return the address a channel should deliver to — an email for `"mail"`, an
+   * E.164 number for `"sms"`, a webhook URL for `"slack"` — or `undefined` to
+   * fall back. Lets one model route differently per channel without every
+   * notification having to know how.
+   *
+   * @example
+   * routeNotificationFor(channel: string) {
+   *   return channel === "mail" ? this.billingEmail : undefined;
+   * }
+   */
+  routeNotificationFor?(channel: string): string | undefined;
+}
+
+/**
+ * A delivery channel. Every built-in channel implements this, and so does any
+ * channel registered with `NotificationManager.extend()`.
+ */
+export interface NotificationChannel {
+  send(notifiable: Notifiable, notification: NotificationLike): Promise<void>;
+}
+
+/**
+ * The shape a channel sees. Declared structurally so `types.ts` stays free of a
+ * runtime import of the `Notification` class.
+ */
+export interface NotificationLike {
+  channels(notifiable?: Notifiable): string[];
+  constructor: { name: string };
+}
+
+/** Mail-channel settings (driver selection + the default sender + credentials). */
+export interface MailConfigShape {
+  /** Transport for the mail channel. Default: 'log' (prints to console). */
+  driver: "log" | "smtp" | "resend";
+  /** Default From address, used unless a MailMessage overrides it with `from()`. */
+  from: {
+    address: string;
+    name: string;
+  };
+  /** SMTP options (used when driver === 'smtp'). */
+  smtp: {
+    host: string;
+    port: number;
+    /** TLS on connect (port 465); false = plain, upgraded via STARTTLS when offered (port 587). */
+    secure: boolean;
+    username: string;
+    password: string;
+    /**
+     * Send credentials even when the connection is not encrypted. Off by default:
+     * `AUTH LOGIN`/`PLAIN` are base64, so a plaintext session hands the password
+     * to anyone on the path. Turn on only for a trusted local relay.
+     */
+    allowInsecureAuth?: boolean;
+    /** Reject servers presenting an untrusted certificate. Default: true. */
+    rejectUnauthorized?: boolean;
+    /** Per-reply timeout in milliseconds. Default: 30000. */
+    timeoutMs?: number;
+    /** Name sent in the EHLO greeting. Default: 'zerotal'. */
+    clientName?: string;
+  };
+  /** Resend options (used when driver === 'resend'). */
+  resend: {
+    apiKey: string;
+  };
+  /** Log options (used when driver === 'log'). */
+  log: {
+    /** 'console' writes to stdout; a path writes to a file. */
+    channel: "console" | string;
+  };
+}
+
+export interface TwilioConfigShape {
+  accountSid: string;
+  authToken: string;
+  from: string;
+}
+
+export interface VonageConfigShape {
+  apiKey: string;
+  apiSecret: string;
+  from: string;
+}
+
+export interface SmsConfigShape {
+  driver: "twilio" | "vonage";
+  twilio?: TwilioConfigShape;
+  vonage?: VonageConfigShape;
+}
+
+export interface NotificationConfigShape {
+  database: {
+    /** Table name for stored notifications. Default: 'notifications' */
+    table: string;
+  };
+  /**
+   * Mail-channel settings. Always present (defaults to the `log` driver), so the
+   * `mail` channel works out of the box without extra configuration.
+   */
+  mail: MailConfigShape;
+  /**
+   * Slack incoming webhook settings.
+   * The per-notification toSlack() method provides the webhookUrl, so this is
+   * only needed if you want a global fallback URL.
+   */
+  slack?: {
+    /** Default webhook URL — can be overridden per-notification in toSlack(). */
+    webhook?: string;
+  };
+  /**
+   * SMS provider settings (Twilio or Vonage).
+   * Required when any notification uses the 'sms' channel.
+   */
+  sms?: SmsConfigShape;
+}