@zerotal/notifications 1.0.0

package/src/SendNotificationJob.ts

@@ -0,0 +1,67 @@
+import { Job, JobRegistry } from "@zerotal/queue";
+import type { Notifiable } from "./types.ts";
+import type { Notification } from "./Notification.ts";
+import type { NotificationManager } from "./NotificationManager.ts";
+import {
+  hydrateNotifiable,
+  hydrateNotification,
+  serializeNotification,
+  type SerializedNotification,
+} from "./serialization.ts";
+
+/**
+ * Background job that sends a queued Notification. Dispatched by `Notify.queue()`
+ * and `notifyLater()`.
+ *
+ * The job carries the notification in one of two states. Dispatched in-process it
+ * holds the live objects and uses them directly. Restored from a persistent driver
+ * (SQLite/Redis) it holds only the serialized snapshot written by `payload()`, and
+ * rebuilds both sides in `handle()` — asynchronously, because resolving a
+ * notification class may require importing `app/notifications/`.
+ */
+export class SendNotificationJob extends Job {
+  override readonly queue = "notifications";
+
+  private readonly _serialized: SerializedNotification | undefined;
+
+  constructor(
+    private readonly _notifiable?: Notifiable,
+    private readonly _notification?: Notification,
+    serialized?: SerializedNotification,
+  ) {
+    super();
+    this._serialized = serialized;
+  }
+
+  /** The wire form stored by persistent queue drivers. */
+  override payload(): Record<string, unknown> {
+    if (this._serialized) return { ...this._serialized };
+    return {
+      ...serializeNotification(this._notifiable as Notifiable, this._notification as Notification),
+    };
+  }
+
+  /** Rebuild the job from a stored payload. Called by the queue on the worker side. */
+  static fromPayload(data: Record<string, unknown>): SendNotificationJob {
+    return new SendNotificationJob(undefined, undefined, data as unknown as SerializedNotification);
+  }
+
+  async handle(): Promise<void> {
+    const { currentApp } = await import("@zerotal/core");
+    const manager = currentApp().container.makeSync("notifications") as NotificationManager;
+
+    const [notifiable, notification] = await this._resolve();
+    await manager.send(notifiable, notification);
+  }
+
+  /** The live pair when dispatched in-process; the rebuilt pair when restored. */
+  private async _resolve(): Promise<[Notifiable, Notification]> {
+    if (this._notifiable && this._notification) {
+      return [this._notifiable, this._notification];
+    }
+    const s = this._serialized as SerializedNotification;
+    return [hydrateNotifiable(s.notifiable), await hydrateNotification(s.type, s.data)];
+  }
+}
+
+JobRegistry.register(SendNotificationJob);

package/src/SlackChannel.ts

@@ -0,0 +1,76 @@
+import type { Notifiable } from "./types.ts";
+import type { Notification } from "./Notification.ts";
+import { NotificationDeliveryError, NotificationChannelNotConfiguredError } from "./errors.ts";
+
+/**
+ * Payload returned by notification.toSlack().
+ *
+ * @example
+ * toSlack(_notifiable: Notifiable): SlackMessage {
+ *   return {
+ *     webhookUrl: 'https://hooks.slack.com/services/...',
+ *     text:       `Order #${this.order.id} was shipped!`,
+ *     // Optional Block Kit blocks for rich formatting:
+ *     // blocks: [{ type: 'section', text: { type: 'mrkdwn', text: '...' } }],
+ *   };
+ * }
+ */
+export interface SlackMessage {
+  /**
+   * Incoming webhook URL. Optional when the notifiable routes `"slack"` or
+   * `config.slack.webhook` is set — the message value wins over both.
+   */
+  webhookUrl?: string;
+  /** Fallback plain text (required by Slack even when blocks are present). */
+  text: string;
+  /** Optional Block Kit blocks for rich formatting. */
+  blocks?: unknown[];
+}
+
+/**
+ * Slack notification channel — POSTs a JSON payload to an incoming webhook URL.
+ *
+ * No npm dependencies — uses the global fetch API.
+ *
+ * Usage in a Notification:
+ *   channels() { return ['slack']; }
+ *   toSlack(_notifiable: Notifiable): SlackMessage {
+ *     return { webhookUrl: 'https://hooks.slack.com/...', text: 'Hello!' };
+ *   }
+ */
+export class SlackChannel {
+  constructor(private readonly config: { webhook?: string } = {}) {}
+
+  async send(notifiable: Notifiable, notification: Notification): Promise<void> {
+    const message = await notification.toSlack(notifiable);
+
+    // Most specific wins: the message's own URL, then the recipient's route,
+    // then the global webhook from config/notifications.ts.
+    const webhookUrl =
+      message.webhookUrl ?? notifiable.routeNotificationFor?.("slack") ?? this.config.webhook;
+
+    if (!webhookUrl) {
+      throw new NotificationChannelNotConfiguredError(
+        "slack",
+        `No webhook URL for ${notification.constructor.name}. Return one from toSlack(), ` +
+          `route it on the notifiable, or set slack: { webhook: "..." } in config/notifications.ts.`,
+      );
+    }
+
+    const res = await fetch(webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        text: message.text,
+        ...(message.blocks ? { blocks: message.blocks } : {}),
+      }),
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new NotificationDeliveryError(
+        `[Zerotal/notifications] Slack webhook returned ${res.status}: ${body}`,
+      );
+    }
+  }
+}

package/src/SmsChannel.ts

@@ -0,0 +1,151 @@
+import type { Notifiable } from "./types.ts";
+import type { Notification } from "./Notification.ts";
+import type { SmsConfigShape } from "./types.ts";
+import {
+  NotificationDeliveryError,
+  NotificationChannelUnavailableError,
+  UnknownSmsDriverError,
+} from "./errors.ts";
+
+/**
+ * Payload returned by notification.toSms().
+ *
+ * @example
+ * toSms(_notifiable: Notifiable): SmsMessage {
+ *   return { body: `Your verification code is ${this.code}` };
+ * }
+ */
+export interface SmsMessage {
+  /**
+   * Recipient phone number in E.164 format, e.g. '+15551234567'. Optional — it
+   * defaults to the notifiable's `phone`, so most notifications omit it.
+   */
+  to?: string;
+  /** Message body text. */
+  body: string;
+  /**
+   * Sender number or alphanumeric ID.
+   * Overrides the global `from` in config/notifications.ts when set.
+   */
+  from?: string;
+}
+
+/** An SmsMessage after the recipient has been resolved. */
+interface ResolvedSms extends SmsMessage {
+  to: string;
+}
+
+/**
+ * SMS notification channel — sends via Twilio or Vonage REST APIs.
+ *
+ * No npm dependencies — uses the global fetch API.
+ *
+ * Configure in config/notifications.ts:
+ *   sms: {
+ *     driver: 'twilio',
+ *     twilio: {
+ *       accountSid: Bun.env['TWILIO_ACCOUNT_SID'] ?? '',
+ *       authToken:  Bun.env['TWILIO_AUTH_TOKEN']  ?? '',
+ *       from:       Bun.env['TWILIO_FROM']         ?? '',
+ *     },
+ *   }
+ *
+ * Usage in a Notification:
+ *   channels() { return ['sms']; }
+ *   toSms(_notifiable: Notifiable): SmsMessage {
+ *     return { body: 'Your code is 1234' };   // delivered to notifiable.phone
+ *   }
+ */
+export class SmsChannel {
+  constructor(private readonly config: SmsConfigShape) {}
+
+  async send(notifiable: Notifiable, notification: Notification): Promise<void> {
+    const message = await notification.toSms(notifiable);
+    const driver = this.config.driver;
+
+    // Mirror the mail channel: the recipient is the notifiable unless the
+    // message names someone else.
+    const to = message.to ?? notifiable.routeNotificationFor?.("sms") ?? notifiable.phone;
+    if (!to) {
+      throw new NotificationChannelUnavailableError(
+        `[Zerotal/notifications] No SMS recipient for ${notification.constructor.name}: ` +
+          `the notifiable has no 'phone' and toSms() did not set 'to'.`,
+      );
+    }
+    const resolved: ResolvedSms = { ...message, to };
+
+    if (driver === "twilio") {
+      await this._sendTwilio(resolved);
+    } else if (driver === "vonage") {
+      await this._sendVonage(resolved);
+    } else {
+      throw new UnknownSmsDriverError(driver);
+    }
+  }
+
+  // ── Twilio ──────────────────────────────────────────────────────────────────
+
+  private async _sendTwilio(message: ResolvedSms): Promise<void> {
+    const cfg = this.config.twilio;
+    if (!cfg)
+      throw new NotificationChannelUnavailableError(
+        "[Zerotal/notifications] SMS driver is twilio but config.sms.twilio is not set.",
+      );
+
+    const from = message.from ?? cfg.from;
+    const url = `https://api.twilio.com/2010-04-01/Accounts/${cfg.accountSid}/Messages.json`;
+
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Basic ${btoa(`${cfg.accountSid}:${cfg.authToken}`)}`,
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: new URLSearchParams({ From: from, To: message.to, Body: message.body }),
+    });
+
+    if (!res.ok) {
+      const body = (await res.json().catch(() => ({}))) as { message?: string };
+      throw new NotificationDeliveryError(
+        `[Zerotal/notifications] Twilio returned ${res.status}: ${body.message ?? "unknown error"}`,
+      );
+    }
+  }
+
+  // ── Vonage ──────────────────────────────────────────────────────────────────
+
+  private async _sendVonage(message: ResolvedSms): Promise<void> {
+    const cfg = this.config.vonage;
+    if (!cfg)
+      throw new NotificationChannelUnavailableError(
+        "[Zerotal/notifications] SMS driver is vonage but config.sms.vonage is not set.",
+      );
+
+    const from = message.from ?? cfg.from;
+    const res = await fetch("https://rest.nexmo.com/sms/json", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        api_key: cfg.apiKey,
+        api_secret: cfg.apiSecret,
+        from,
+        to: message.to,
+        text: message.body,
+      }),
+    });
+
+    if (!res.ok) {
+      throw new NotificationDeliveryError(`[Zerotal/notifications] Vonage returned ${res.status}`);
+    }
+
+    const data = (await res.json()) as {
+      messages: Array<{ status: string; "error-text"?: string }>;
+    };
+    const first = data.messages[0];
+    if (first && first.status !== "0") {
+      throw new NotificationDeliveryError(
+        `[Zerotal/notifications] Vonage error: ${first["error-text"] ?? `status ${first.status}`}`,
+      );
+    }
+  }
+}

package/src/admin.ts

@@ -0,0 +1,219 @@
+/**
+ * Notifications → admin panel contribution.
+ *
+ * When something stops arriving, the question is always the same: did we try,
+ * on which channel, and what did the provider say? This console answers that
+ * from the delivery counters, and exposes the stored inbox so an operator can
+ * see and prune what the database channel has accumulated.
+ *
+ * The panel's write surface is resolved from the container by binding key and
+ * typed through a local structural interface, exactly as the observer bridges in
+ * `observability.ts` are: this package depends on `@zerotal/admin` not at all,
+ * and an app without the panel pulls in nothing extra — the binding is simply
+ * absent and this returns.
+ */
+import type { Application } from "@zerotal/core";
+import { channelStats, recentDeliveries } from "./stats.ts";
+import type { NotificationManager } from "./NotificationManager.ts";
+
+/** The slice of the admin panel's contribution surface this module uses. */
+interface AdminPanelSink {
+  enabled(id: string): boolean;
+  console(contribution: ConsoleSpec): void;
+}
+
+type Row = Record<string, unknown>;
+type Tone = "primary" | "success" | "muted" | "destructive" | "default";
+
+interface ConsoleSpec {
+  slug: string;
+  title: string;
+  ability: string;
+  navigationIcon?: string;
+  navigationGroup?: string;
+  navigationSort?: number;
+  navigationBadge?: () => Promise<string | number | null>;
+  navigationBadgeColor?: Tone;
+  tabs: Array<{
+    key: string;
+    label: string;
+    description?: string;
+    columns: Array<{
+      key: string;
+      label: string;
+      align?: "start" | "center" | "end";
+      mono?: boolean;
+      format?: (value: unknown, row: Row) => string;
+      badge?: (value: unknown, row: Row) => Tone | null;
+    }>;
+    rows: () => Promise<Row[]>;
+    rowKey?: string;
+    rowActions?: Array<{
+      key: string;
+      label: string;
+      icon?: string;
+      danger?: boolean;
+      confirm?: string;
+      run: (row: Row) => Promise<string | void>;
+    }>;
+    headerActions?: Array<{
+      key: string;
+      label: string;
+      icon?: string;
+      danger?: boolean;
+      confirm?: string;
+      run: () => Promise<string | void>;
+    }>;
+    empty?: string;
+    badge?: () => Promise<number | null>;
+  }>;
+}
+
+/** The ability an operator needs to see and act on the notifications console. */
+const ABILITY = "notifications.view";
+
+function formatTime(value: unknown): string {
+  if (value === null || value === undefined || value === "") return "—";
+  const date = typeof value === "number" ? new Date(value) : new Date(String(value));
+  return Number.isNaN(date.getTime()) ? String(value) : date.toLocaleString();
+}
+
+/** Trim a long provider error down to its first line. */
+function firstLine(value: unknown): string {
+  const text = value === null || value === undefined ? "" : String(value);
+  const line = text.split("\n")[0]?.trim() ?? "";
+  return line.length > 140 ? `${line.slice(0, 137)}…` : line || "—";
+}
+
+function formatMs(value: unknown): string {
+  const n = Number(value);
+  return Number.isFinite(n) ? `${Math.round(n)}ms` : "—";
+}
+
+/**
+ * Contribute the notifications console to the admin panel, when one is installed.
+ *
+ * Call from `NotificationProvider.onBooting()` — the panel binds its surface
+ * during the registration phase, so it is reachable from any provider's booting
+ * phase regardless of the order the two were registered in.
+ */
+export function installNotificationsAdmin(app: Application): void {
+  const panel = app.container.tryMake("admin.panel" as never) as AdminPanelSink | undefined;
+  if (!panel?.enabled("notifications")) return;
+
+  const manager = (): NotificationManager =>
+    app.container.makeSync("notifications") as NotificationManager;
+
+  panel.console({
+    slug: "notifications",
+    title: "Notifications",
+    ability: ABILITY,
+    navigationIcon: "bell",
+    navigationGroup: "Operations",
+    navigationBadgeColor: "destructive",
+    // A failure count is the number worth noticing without looking for it.
+    navigationBadge: async () => {
+      const failed = recentDeliveries().filter((d) => !d.ok).length;
+      return failed > 0 ? failed : null;
+    },
+    tabs: [
+      {
+        key: "recent",
+        label: "Recent",
+        description:
+          "Delivery attempts since this process booted, newest first. Not persisted history.",
+        empty: "Nothing delivered yet.",
+        badge: async () => recentDeliveries().length,
+        columns: [
+          { key: "at", label: "When", format: formatTime },
+          { key: "className", label: "Notification" },
+          { key: "channel", label: "Channel", badge: () => "muted" },
+          { key: "notifiable", label: "To", mono: true },
+          {
+            key: "ok",
+            label: "Result",
+            format: (v) => (v ? "sent" : "failed"),
+            badge: (v) => (v ? "success" : "destructive"),
+          },
+          { key: "durationMs", label: "Took", align: "end", format: formatMs },
+          { key: "error", label: "Error", mono: true, format: firstLine },
+        ],
+        rows: async () =>
+          recentDeliveries().map((d) => ({
+            at: d.at,
+            className: d.className,
+            channel: d.channel,
+            notifiable: d.notifiable,
+            ok: d.ok,
+            durationMs: d.durationMs,
+            error: d.error ?? "",
+          })),
+      },
+      {
+        key: "channels",
+        label: "Channels",
+        description: "Per-channel totals since boot — where failures are concentrated.",
+        empty: "No channel has been used yet.",
+        rowKey: "channel",
+        columns: [
+          { key: "channel", label: "Channel" },
+          { key: "sent", label: "Sent", align: "end" },
+          {
+            key: "failed",
+            label: "Failed",
+            align: "end",
+            badge: (v) => (Number(v) > 0 ? "destructive" : "muted"),
+          },
+          { key: "avgMs", label: "Avg", align: "end", format: formatMs },
+        ],
+        rows: async () => channelStats().map((s) => ({ ...s })),
+      },
+      {
+        key: "stored",
+        label: "Stored",
+        description:
+          "Rows written by the database channel, newest first. Pruning deletes read notifications.",
+        empty: "No stored notifications.",
+        columns: [
+          { key: "created_at", label: "When", format: formatTime },
+          { key: "type", label: "Notification" },
+          { key: "notifiable_type", label: "Recipient type", badge: () => "muted" },
+          { key: "notifiable_id", label: "Recipient", mono: true },
+          {
+            key: "read_at",
+            label: "Read",
+            format: (v) => (v ? formatTime(v) : "unread"),
+            badge: (v) => (v ? "muted" : "primary"),
+          },
+        ],
+        rows: async () => (await manager().database.recent(100)).map((r) => ({ ...r })),
+        rowActions: [
+          {
+            key: "delete",
+            label: "Delete",
+            icon: "trash",
+            danger: true,
+            confirm: "Delete this stored notification?",
+            run: async (row) => {
+              await manager().database.delete(String(row["id"]));
+              return "Notification deleted.";
+            },
+          },
+        ],
+        headerActions: [
+          {
+            key: "prune",
+            label: "Prune read (30d)",
+            icon: "trash",
+            danger: true,
+            confirm: "Delete read notifications older than 30 days?",
+            run: async () => {
+              const deleted = await manager().database.prune(30);
+              return `${deleted} notification(s) pruned.`;
+            },
+          },
+        ],
+      },
+    ],
+  });
+}

package/src/commands/NotificationsPruneCommand.ts

@@ -0,0 +1,54 @@
+import type { Application, FlagDef } from "@zerotal/core";
+import { Command } from "@zerotal/core";
+import type { NotificationManager } from "../NotificationManager.ts";
+
+/**
+ * `zt notifications:prune` — delete old stored notifications.
+ *
+ * The database channel never removes anything on its own, so an app that has
+ * been notifying users for a year is carrying a year of rows. Run this on a
+ * schedule.
+ */
+export class NotificationsPruneCommand extends Command {
+  static commandName = "notifications:prune";
+  static description = "Delete stored notifications older than a given age";
+  static needsApp = true;
+
+  static flags: FlagDef[] = [
+    {
+      name: "days",
+      type: "number",
+      description: "Age threshold in days",
+      default: 30,
+    },
+    {
+      name: "all",
+      type: "boolean",
+      description: "Also prune notifications that were never read",
+      default: false,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const app = this.app as Application | undefined;
+    if (!app) {
+      this.error("Application not available.");
+      return;
+    }
+
+    const days = Number(this.flags["days"] ?? 30);
+    if (!Number.isFinite(days) || days < 0) {
+      this.error(`--days must be a non-negative number, got '${String(this.flags["days"])}'.`);
+      return;
+    }
+
+    const includeUnread = this.flags["all"] === true;
+    const notifications = app.container.makeSync("notifications") as NotificationManager;
+    const deleted = await notifications.database.prune(days, includeUnread);
+
+    this.info(
+      `Pruned ${deleted} notification(s) older than ${days} day(s)` +
+        (includeUnread ? ", including unread." : " that had been read."),
+    );
+  }
+}

package/src/commands/NotificationsTestCommand.ts

@@ -0,0 +1,63 @@
+import type { Application, ArgDef } from "@zerotal/core";
+import { Command } from "@zerotal/core";
+import type { NotificationManager } from "../NotificationManager.ts";
+import { Notification } from "../Notification.ts";
+import { MailMessage } from "../messages/MailMessage.ts";
+import type { Notifiable } from "../types.ts";
+
+/** The message `notifications:test` sends. Nothing else references it. */
+class TestNotification extends Notification {
+  channels(): string[] {
+    return ["mail"];
+  }
+
+  toMail(_notifiable: Notifiable): MailMessage {
+    return new MailMessage()
+      .subject("Zerotal test notification")
+      .greeting("Hello,")
+      .line("If you are reading this, your mail configuration works.")
+      .line(`Sent at ${new Date().toISOString()}.`)
+      .salutation("— Zerotal");
+  }
+}
+
+/**
+ * `zt notifications:test <email>` — send one real email through the configured
+ * mail driver.
+ *
+ * Mail configuration fails in ways unit tests cannot reach: a wrong port, a
+ * refused STARTTLS upgrade, credentials the server rejects. This exercises the
+ * whole path and prints what the server said.
+ */
+export class NotificationsTestCommand extends Command {
+  static commandName = "notifications:test";
+  static description = "Send a test email through the configured mail driver";
+  static needsApp = true;
+
+  static args: ArgDef[] = [{ name: "email", required: true }];
+
+  async run(): Promise<void> {
+    const app = this.app as Application | undefined;
+    if (!app) {
+      this.error("Application not available.");
+      return;
+    }
+
+    const email = this.args["email"];
+    if (!email || !email.includes("@")) {
+      this.error(`'${String(email)}' is not an email address.`);
+      return;
+    }
+
+    const notifications = app.container.makeSync("notifications") as NotificationManager;
+
+    this.line(`Sending a test notification to ${email}…`);
+    try {
+      await notifications.route({ mail: email }).notify(new TestNotification());
+      this.info(`Sent. Check ${email} (and the mail driver's own log).`);
+    } catch (error) {
+      // The provider's own message is the useful part — surface it verbatim.
+      this.error(`Send failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}

package/src/commands/index.ts

@@ -0,0 +1,2 @@
+export { NotificationsPruneCommand } from "./NotificationsPruneCommand.ts";
+export { NotificationsTestCommand } from "./NotificationsTestCommand.ts";