@zerotal/notifications 1.0.0

package/src/events.ts

@@ -0,0 +1,70 @@
+/**
+ * The notifications package's framework events (mail + notification delivery),
+ * emitted on core's {@link FrameworkEvents} bus. Observability packages subscribe
+ * to them by kind (their class name).
+ */
+
+/**
+ * Emitted after a mail message is sent or queued. `queued` distinguishes an
+ * immediate send from a deferred one.
+ *
+ * @category Mail
+ */
+export class MessageSent {
+  constructor(
+    readonly className: string,
+    readonly to: string[],
+    readonly subject: string,
+    readonly html: string,
+    readonly durationMs: number,
+    readonly queued: boolean,
+  ) {}
+}
+
+/**
+ * Emitted when a mail message is pushed onto a queue (deferred send).
+ * @category Mail
+ */
+export class MessageQueued {
+  constructor(
+    readonly className: string,
+    readonly to: string[],
+    readonly subject: string,
+    readonly queue: string,
+  ) {}
+}
+
+/**
+ * Emitted when a mail message fails to send.
+ * @category Mail
+ */
+export class MessageFailed {
+  constructor(
+    readonly className: string,
+    readonly to: string[],
+    readonly subject: string,
+    readonly durationMs: number,
+    readonly error: string,
+  ) {}
+}
+
+/**
+ * Emitted after a notification is delivered (or fails) through one channel —
+ * distinct from `MessageSent`, which is mail-specific. One notification dispatched
+ * to N channels fires N of these.
+ *
+ * @category Notifications
+ */
+export class NotificationSent {
+  constructor(
+    /** The notification class name, e.g. "OrderShippedNotification". */
+    readonly className: string,
+    /** The channel it went out on: "mail" | "database" | "slack" | "sms" | "broadcast". */
+    readonly channel: string,
+    /** The recipient identity (email or id). */
+    readonly notifiable: string,
+    readonly ok: boolean,
+    readonly durationMs: number,
+    readonly error?: string,
+  ) {}
+}

package/src/facades/Notify.ts

@@ -0,0 +1,3 @@
+import { createFacade } from "@zerotal/core";
+
+export const Notify = createFacade("notifications");

package/src/global.d.ts

@@ -0,0 +1,31 @@
+// Ambient declarations specific to this package.
+// Bun, Node (node:*), and bun:test types come from @types/bun (→ bun-types).
+// Only declarations bun-types does NOT provide are kept here.
+
+// ── Bun globals ───────────────────────────────────────────────────────────
+interface Request {
+  readonly params?: Record<string, string>;
+}
+
+// ── SQLInstance ───────────────────────────────────────────────────────────
+interface SQLInstance {
+  <T = Record<string, unknown>>(
+    strings: TemplateStringsArray,
+    ...values: unknown[]
+  ): Promise<T[]>;
+  begin<T>(fn: (tx: SQLInstance) => Promise<T>): Promise<T>;
+  end(): Promise<void>;
+}
+
+interface RedisInstance {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  set(key: string, value: string, options: { ex: number }): Promise<void>;
+  lpush(key: string, value: string): Promise<number>;
+  rpop(key: string): Promise<string | null>;
+  llen(key: string): Promise<number>;
+  del(...keys: string[]): Promise<number>;
+  expire(key: string, seconds: number): Promise<number>;
+  keys(pattern: string): Promise<string[]>;
+  flushdb(): Promise<void>;
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+export { Notification } from "./Notification.ts";
+// `Notifiable` is exported here as BOTH the mixin (value) and the contract (type) — a
+// function+interface merge in Notifiable.ts.
+export { Notifiable } from "./Notifiable.ts";
+export { NotificationManager } from "./NotificationManager.ts";
+export { NotificationFake } from "./NotificationFake.ts";
+export { NotificationProvider } from "./provider/NotificationProvider.ts";
+export { Notify } from "./facades/Notify.ts";
+export { NotificationConfig, validateNotificationConfig } from "./config.ts";
+
+// Channels
+export { MailChannel } from "./MailChannel.ts";
+export { DatabaseChannel } from "./DatabaseChannel.ts";
+export { SlackChannel } from "./SlackChannel.ts";
+export { SmsChannel } from "./SmsChannel.ts";
+export { BroadcastChannel, BROADCAST_NOTIFICATION_EVENT } from "./BroadcastChannel.ts";
+
+// Per-channel messages
+export { MailMessage, RichLine } from "./messages/MailMessage.ts";
+export { BroadcastMessage } from "./BroadcastMessage.ts";
+
+// On-demand (model-less) recipients
+export { OnDemandNotifiable } from "./OnDemandNotifiable.ts";
+export type { OnDemandRoutes } from "./OnDemandNotifiable.ts";
+
+// Queue serialization — a notification outside app/notifications/ registers here.
+export { NotificationRegistry } from "./NotificationRegistry.ts";
+export type { NotificationClass } from "./NotificationRegistry.ts";
+
+// Mail drivers (for the mail channel) — swap or supply your own transport.
+export { LogDriver } from "./drivers/LogDriver.ts";
+export { SmtpDriver } from "./drivers/SmtpDriver.ts";
+export { ResendDriver } from "./drivers/ResendDriver.ts";
+export type {
+  MailDriver,
+  MailPayload,
+  MailAddress,
+  MailAttachment,
+  AddressInput,
+} from "./drivers/MailDriver.ts";
+
+export { SendNotificationJob } from "./SendNotificationJob.ts";
+export { BroadcastNotificationJob } from "./BroadcastNotificationJob.ts";
+export type {
+  NotificationConfigShape,
+  MailConfigShape,
+  SmsConfigShape,
+  TwilioConfigShape,
+  VonageConfigShape,
+  NotificationChannel,
+} from "./types.ts";
+export type { NotificationRecord, InboxQuery } from "./DatabaseChannel.ts";
+export type { SlackMessage } from "./SlackChannel.ts";
+export type { SmsMessage } from "./SmsChannel.ts";
+export type { TextStyle } from "./messages/MailMessage.ts";
+
+// Delivery counters backing the admin console.
+export { recentDeliveries, channelStats } from "./stats.ts";
+export type { RecentDelivery, ChannelStat } from "./stats.ts";
+
+// Console commands
+export { NotificationsPruneCommand, NotificationsTestCommand } from "./commands/index.ts";
+
+// Typed error vocabulary
+export * from "./errors.ts";
+
+// Framework instrumentation events (emitted on the core FrameworkEvents bus)
+export { MessageSent, MessageQueued, MessageFailed, NotificationSent } from "./events.ts";

package/src/messages/MailMessage.ts

@@ -0,0 +1,342 @@
+import {
+  resolveAddress,
+  type AddressInput,
+  type MailAddress,
+  type MailAttachment,
+  type MailPayload,
+} from "../drivers/MailDriver.ts";
+
+/** Inline text styling applied to a whole line or to a single run within a line. */
+export interface TextStyle {
+  bold?: boolean;
+  italic?: boolean;
+  /** Any CSS color, e.g. "#dc2626" or "red". */
+  color?: string;
+  /** Font size in pixels. */
+  size?: number;
+}
+
+/** One styled run of text. */
+interface TextSegment {
+  text: string;
+  style?: TextStyle;
+}
+
+/** A line is one or more styled runs rendered into a single paragraph. */
+type Line = TextSegment[];
+
+const escapeHtml = (s: string): string =>
+  s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+/** Escape a value placed inside a double-quoted HTML attribute (prevents breakout). */
+const escapeAttribute = (s: string): string =>
+  s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+const styleToCss = (style?: TextStyle): string => {
+  if (!style) return "";
+  const css: string[] = [];
+  if (style.bold) css.push("font-weight:600");
+  if (style.italic) css.push("font-style:italic");
+  if (style.color) css.push(`color:${style.color}`);
+  if (style.size) css.push(`font-size:${style.size}px`);
+  return css.join(";");
+};
+
+/**
+ * Fluent builder for a single line composed of differently-styled runs of text.
+ * Passed to the callback form of `MailMessage.line()`.
+ *
+ * @example
+ * .line((t) => t
+ *   .text("Your order ")
+ *   .bold("#1234")
+ *   .text(" is ")
+ *   .color("on its way", "#16a34a"))
+ */
+export class RichLine {
+  /** @internal Collected runs, read by MailMessage during rendering. */
+  readonly segments: TextSegment[] = [];
+
+  /** Append an unstyled run. */
+  text(content: string): this {
+    this.segments.push({ text: content });
+    return this;
+  }
+
+  /** Append a bold run. */
+  bold(content: string): this {
+    this.segments.push({ text: content, style: { bold: true } });
+    return this;
+  }
+
+  /** Append an italic run. */
+  italic(content: string): this {
+    this.segments.push({ text: content, style: { italic: true } });
+    return this;
+  }
+
+  /** Append a coloured run. `color` is any CSS color. */
+  color(content: string, color: string): this {
+    this.segments.push({ text: content, style: { color } });
+    return this;
+  }
+
+  /** Append a run with an explicit font size in pixels. */
+  size(content: string, px: number): this {
+    this.segments.push({ text: content, style: { size: px } });
+    return this;
+  }
+
+  /** Append a run with an arbitrary combination of styles. */
+  styled(content: string, style: TextStyle): this {
+    this.segments.push({ text: content, style });
+    return this;
+  }
+}
+
+/**
+ * The fluent representation a notification returns from `toMail()` — symmetric with
+ * `toSms() → SmsMessage` and `toSlack() → SlackMessage`. Compose a branded email from
+ * a greeting, lines, and an optional call-to-action button, or drop to `.html()` for a
+ * fully custom body.
+ *
+ * Lines accept inline styling. Pass a `TextStyle` to style a whole line, or use the
+ * callback form to mix differently-styled runs within one line.
+ *
+ * The recipient is normally the notifiable (its `email`), so you don't set `to()` —
+ * `MailChannel` fills it in. Use `to()`/`cc()`/`bcc()`/`from()`/`replyTo()` only to
+ * override.
+ *
+ * @example
+ * toMail(n: Notifiable): MailMessage {
+ *   return new MailMessage()
+ *     .subject("Your order shipped")
+ *     .greeting(`Hi ${n.name ?? "there"},`, { bold: true })
+ *     .line("Your order is on its way.")
+ *     .line("Action required", { bold: true, color: "#dc2626", size: 18 })
+ *     .line((t) => t.text("Tracking number: ").bold(this.order.tracking))
+ *     .action("Track package", `https://app.test/orders/${this.order.id}`)
+ *     .line("Thanks for shopping with us!");
+ * }
+ */
+export class MailMessage {
+  private _subject = "";
+  private _greeting?: Line;
+  private _salutation?: Line;
+  private _introLines: Line[] = [];
+  private _outroLines: Line[] = [];
+  private _actionText?: string;
+  private _actionUrl?: string;
+  private _html?: string;
+  private _text?: string;
+  private _to: MailAddress[] = [];
+  private _cc: MailAddress[] = [];
+  private _bcc: MailAddress[] = [];
+  private _from?: MailAddress;
+  private _replyTo?: MailAddress;
+  private _attachments: MailAttachment[] = [];
+
+  subject(text: string): this {
+    this._subject = text;
+    return this;
+  }
+
+  /**
+   * Opening line, e.g. "Hi Ada,". Defaults to "Hello," when omitted. Accepts the same
+   * styling forms as `line()`: a plain string, a string + `TextStyle`, or a `RichLine`
+   * callback for mixed runs.
+   */
+  greeting(text: string): this;
+  greeting(text: string, style: TextStyle): this;
+  greeting(build: (t: RichLine) => void): this;
+  greeting(arg: string | ((t: RichLine) => void), style?: TextStyle): this {
+    this._greeting = this._toLine(arg, style);
+    return this;
+  }
+
+  /**
+   * Closing line, e.g. "Regards,". Defaults to "Regards,". Accepts the same styling
+   * forms as `line()`.
+   */
+  salutation(text: string): this;
+  salutation(text: string, style: TextStyle): this;
+  salutation(build: (t: RichLine) => void): this;
+  salutation(arg: string | ((t: RichLine) => void), style?: TextStyle): this {
+    this._salutation = this._toLine(arg, style);
+    return this;
+  }
+
+  /**
+   * Add a paragraph. Lines before `action()` render above the button; lines after, below it.
+   *
+   * - Plain: `.line("Welcome aboard.")`
+   * - Whole-line style: `.line("Heads up", { bold: true, color: "#dc2626", size: 18 })`
+   * - Mixed runs: `.line((t) => t.text("Code: ").bold("AB12").color(" (expires soon)", "#6b7280"))`
+   */
+  line(text: string): this;
+  line(text: string, style: TextStyle): this;
+  line(build: (t: RichLine) => void): this;
+  line(arg: string | ((t: RichLine) => void), style?: TextStyle): this {
+    const segments = this._toLine(arg, style);
+    if (this._actionText) this._outroLines.push(segments);
+    else this._introLines.push(segments);
+    return this;
+  }
+
+  /** A call-to-action button. At most one per message. */
+  action(text: string, url: string): this {
+    this._actionText = text;
+    this._actionUrl = url;
+    return this;
+  }
+
+  /** Provide a fully custom HTML body, bypassing the greeting/line/action template. */
+  html(content: string): this {
+    this._html = content;
+    return this;
+  }
+
+  /** Provide an explicit plain-text body (otherwise one is derived from the lines). */
+  text(content: string): this {
+    this._text = content;
+    return this;
+  }
+
+  to(address: AddressInput | AddressInput[]): this {
+    return this._push(this._to, address);
+  }
+
+  cc(address: AddressInput | AddressInput[]): this {
+    return this._push(this._cc, address);
+  }
+
+  bcc(address: AddressInput | AddressInput[]): this {
+    return this._push(this._bcc, address);
+  }
+
+  from(address: AddressInput): this {
+    this._from = resolveAddress(address);
+    return this;
+  }
+
+  replyTo(address: AddressInput): this {
+    this._replyTo = resolveAddress(address);
+    return this;
+  }
+
+  /**
+   * Attach a file to the message.
+   *
+   * @example
+   * .attach({ filename: "invoice.pdf", content: pdfBytes, contentType: "application/pdf" })
+   */
+  attach(attachment: MailAttachment): this {
+    this._attachments.push(attachment);
+    return this;
+  }
+
+  /**
+   * Attach a file read from disk. Reads the bytes when called, so the message is
+   * self-contained by the time a driver sends it.
+   *
+   * @example
+   * await new MailMessage().subject("Your invoice").attachFile("./storage/invoice.pdf");
+   */
+  async attachFile(path: string, options: { filename?: string; contentType?: string } = {}) {
+    const file = Bun.file(path);
+    return this.attach({
+      filename: options.filename ?? path.split(/[\\/]/).pop() ?? "attachment",
+      content: new Uint8Array(await file.arrayBuffer()),
+      contentType: options.contentType ?? file.type ?? "application/octet-stream",
+    });
+  }
+
+  /**
+   * Embed an image referenced from the HTML body as `<img src="cid:the-id">`,
+   * rather than listing it as a download.
+   */
+  embed(cid: string, attachment: Omit<MailAttachment, "cid" | "inline">): this {
+    return this.attach({ ...attachment, cid, inline: true });
+  }
+
+  private _push(target: MailAddress[], address: AddressInput | AddressInput[]): this {
+    const arr = Array.isArray(address) ? address : [address];
+    target.push(...arr.map(resolveAddress));
+    return this;
+  }
+
+  private _toLine(arg: string | ((t: RichLine) => void), style?: TextStyle): Line {
+    if (typeof arg === "function") {
+      const rich = new RichLine();
+      arg(rich);
+      return rich.segments;
+    }
+    return [{ text: arg, ...(style ? { style } : {}) }];
+  }
+
+  /**
+   * Resolve to the wire payload a driver sends. `defaultFrom` and `fallbackTo` come from
+   * MailChannel (config default sender + the notifiable's address).
+   */
+  toPayload(defaultFrom: MailAddress, fallbackTo: MailAddress[]): MailPayload {
+    const html = this._html ?? this._renderHtml();
+    const text = this._text ?? this._renderText();
+    return {
+      to: this._to.length > 0 ? this._to : fallbackTo,
+      from: this._from ?? defaultFrom,
+      subject: this._subject,
+      ...(html ? { html } : {}),
+      ...(text ? { text } : {}),
+      ...(this._cc.length > 0 ? { cc: this._cc } : {}),
+      ...(this._bcc.length > 0 ? { bcc: this._bcc } : {}),
+      ...(this._replyTo ? { replyTo: this._replyTo } : {}),
+      ...(this._attachments.length > 0 ? { attachments: this._attachments } : {}),
+    };
+  }
+
+  // ── Rendering ──────────────────────────────────────────────────────────────
+
+  private _renderHtml(): string {
+    const parts: string[] = [];
+    parts.push(this._paragraph(this._greeting ?? [{ text: "Hello," }]));
+    for (const l of this._introLines) parts.push(this._paragraph(l));
+    if (this._actionText && this._actionUrl) {
+      parts.push(
+        `<p style="margin:24px 0"><a href="${escapeHtml(this._actionUrl)}" ` +
+          `style="display:inline-block;background:#4f46e5;color:#fff;text-decoration:none;` +
+          `padding:12px 20px;border-radius:8px;font-size:14px;font-weight:600">${escapeHtml(this._actionText)}</a></p>`,
+      );
+    }
+    for (const l of this._outroLines) parts.push(this._paragraph(l));
+    parts.push(this._paragraph(this._salutation ?? [{ text: "Regards," }]));
+
+    return (
+      `<div style="max-width:560px;margin:0 auto;padding:32px 24px;font-family:` +
+      `-apple-system,Segoe UI,Roboto,Helvetica,Arial,sans-serif">${parts.join("")}</div>`
+    );
+  }
+
+  private _paragraph(line: Line): string {
+    const inner = line.map((seg) => this._span(seg)).join("");
+    return `<p style="margin:0 0 16px;font-size:15px;line-height:1.6;color:#374151">${inner}</p>`;
+  }
+
+  private _span(seg: TextSegment): string {
+    const text = escapeHtml(seg.text);
+    const css = styleToCss(seg.style);
+    return css ? `<span style="${escapeAttribute(css)}">${text}</span>` : text;
+  }
+
+  private _renderText(): string {
+    const parts: string[] = [this._lineText(this._greeting ?? [{ text: "Hello," }])];
+    for (const l of this._introLines) parts.push(this._lineText(l));
+    if (this._actionText && this._actionUrl) parts.push(`${this._actionText}: ${this._actionUrl}`);
+    for (const l of this._outroLines) parts.push(this._lineText(l));
+    parts.push(this._lineText(this._salutation ?? [{ text: "Regards," }]));
+    return parts.join("\n\n");
+  }
+
+  private _lineText(line: Line): string {
+    return line.map((seg) => seg.text).join("");
+  }
+}

package/src/observability.ts

@@ -0,0 +1,146 @@
+/**
+ * Notifications → observer bridges. The mail/notification stack emits its own
+ * `MessageSent` / `MessageQueued` / `MessageFailed` / `NotificationSent` framework
+ * events on the core `FrameworkEvents` bus; this module forwards them to whichever
+ * observer packages are installed.
+ *
+ * Each observer's write surface is resolved from the container by binding key and
+ * typed through a local structural interface, so this package depends on none of
+ * the observer packages — installing or removing an observer requires no change here.
+ */
+import { FrameworkEvents, RequestContext } from "@zerotal/core";
+import type { Application } from "@zerotal/core";
+import { MessageSent, MessageQueued, MessageFailed, NotificationSent } from "./events.ts";
+
+/** The subset of the monitor store this bridge calls (bound as `monitor.store`). */
+interface MonitorSink {
+  recordMail(m: {
+    subject: string;
+    to: string;
+    mailer: string;
+    status: "sent" | "queued" | "failed";
+    ms: number;
+    body: string;
+  }): void;
+  recordEvent(e: {
+    kind: string;
+    label: string;
+    status?: "ok" | "warn" | "bad" | "info";
+    route?: string | null;
+    data?: Record<string, unknown>;
+  }): void;
+}
+
+/** The subset of the devtools trace sink this bridge calls (bound as `devtools.trace`). */
+interface DevtoolsSink {
+  bufferMail(
+    ctx: object,
+    m: {
+      className: string;
+      to: string[];
+      subject: string;
+      html: string;
+      durationMs: number;
+      queued: boolean;
+    },
+  ): void;
+}
+
+/** The subset of the logger this bridge calls (bound as `log`). */
+interface LogSink {
+  error(message: string, context?: Record<string, unknown>, error?: unknown): void;
+}
+
+/**
+ * Subscribe the notification events to every installed observer. Returns a disposer
+ * that removes every subscription; call it from the provider's `onStopping()`.
+ */
+export function installNotificationsObservability(app: Application): () => void {
+  const unsubs: Array<() => void> = [];
+
+  const store = app.container.tryMake("monitor.store" as never) as MonitorSink | undefined;
+  if (store) {
+    unsubs.push(
+      FrameworkEvents.on(MessageSent, (e) =>
+        store.recordMail({
+          subject: e.subject,
+          to: e.to.join(", "),
+          mailer: e.className,
+          status: e.queued ? "queued" : "sent",
+          ms: Math.round(e.durationMs),
+          body: e.html,
+        }),
+      ),
+      FrameworkEvents.on(MessageFailed, (e) =>
+        store.recordMail({
+          subject: e.subject,
+          to: e.to.join(", "),
+          mailer: e.className,
+          status: "failed",
+          ms: Math.round(e.durationMs),
+          body: e.error,
+        }),
+      ),
+      FrameworkEvents.on(MessageQueued, (e) =>
+        store.recordMail({
+          subject: e.subject,
+          to: e.to.join(", "),
+          mailer: e.className,
+          status: "queued",
+          ms: 0,
+          body: `Queued for delivery on "${e.queue}".`,
+        }),
+      ),
+      FrameworkEvents.on(NotificationSent, (e) =>
+        store.recordEvent({
+          kind: "notification",
+          label: e.className,
+          status: e.ok ? "ok" : "bad",
+          route: e.channel,
+          data: {
+            channel: e.channel,
+            to: e.notifiable,
+            ms: Math.round(e.durationMs),
+            detail: e.error ?? e.notifiable,
+          },
+        }),
+      ),
+    );
+  }
+
+  const trace = app.container.tryMake("devtools.trace" as never) as DevtoolsSink | undefined;
+  if (trace) {
+    unsubs.push(
+      // Mail happens outside the HTTP frame, so correlate to the in-flight request.
+      FrameworkEvents.on(MessageSent, (e) => {
+        const ctx = RequestContext.tryGet();
+        if (!ctx) return;
+        trace.bufferMail(ctx, {
+          className: e.className,
+          to: e.to,
+          subject: e.subject,
+          html: e.html,
+          durationMs: e.durationMs,
+          queued: e.queued,
+        });
+      }),
+    );
+  }
+
+  const log = app.container.tryMake("log" as never) as LogSink | undefined;
+  if (log) {
+    unsubs.push(
+      FrameworkEvents.on(MessageFailed, (e) =>
+        log.error(
+          "Mail send failed",
+          { className: e.className, to: e.to, subject: e.subject, durationMs: e.durationMs },
+          new Error(e.error),
+        ),
+      ),
+    );
+  }
+
+  return () => {
+    for (const unsub of unsubs) unsub();
+  };
+}