@zerotal/notifications 1.0.0

package/src/DatabaseChannel.ts

@@ -0,0 +1,295 @@
+import type { SQLInstance } from "@zerotal/orm";
+import type { Notifiable } from "./types.ts";
+import { NotificationError } from "./errors.ts";
+import { notifiableType } from "./serialization.ts";
+import type { Notification } from "./Notification.ts";
+
+/** Build a TemplateStringsArray from a plain string array (mirrors ORM helper). */
+function tpl(strings: string[]): TemplateStringsArray {
+  return Object.freeze(
+    Object.assign([...strings], { raw: [...strings] }),
+  ) as unknown as TemplateStringsArray;
+}
+
+/** Execute sql with a dynamically-constructed template (table name in static parts). */
+async function run<T = Record<string, unknown>>(
+  conn: SQLInstance,
+  parts: string[],
+  ...values: unknown[]
+): Promise<T[]> {
+  return conn<T>(tpl(parts), ...values);
+}
+
+/** Allow only simple identifier characters — guards against injection in table names. */
+function safeIdentifier(name: string): string {
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+    throw new NotificationError(
+      `Invalid table name: '${name}'`,
+      "E_NOTIFICATION_INVALID_TABLE",
+      500,
+    );
+  }
+  return name;
+}
+
+/** How many rows `all()` and `unread()` return when no limit is given. */
+const DEFAULT_LIMIT = 100;
+
+/** Paging and ordering options for an inbox query. */
+export interface InboxQuery {
+  /** Maximum rows to return. Default: 100. Pass 0 for no limit. */
+  limit?: number;
+  /** Rows to skip, for paging. Default: 0. */
+  offset?: number;
+}
+
+/**
+ * Stores notifications in the database.
+ * The table and its indexes are created automatically on first use.
+ *
+ * Schema:
+ *   id              TEXT PRIMARY KEY       — UUID
+ *   notifiable_type TEXT NOT NULL          — recipient's model class name
+ *   notifiable_id   TEXT NOT NULL          — stringified notifiable id
+ *   type            TEXT NOT NULL          — notification class name
+ *   data            TEXT NOT NULL          — JSON-encoded toDatabase() result
+ *   read_at         TEXT                   — ISO timestamp when read; NULL = unread
+ *   created_at      TEXT NOT NULL          — ISO timestamp
+ *
+ * Every read is scoped by `(notifiable_type, notifiable_id)`, not by id alone:
+ * ids are only unique within a model, so a `User#1` and a `Team#1` would
+ * otherwise share one inbox.
+ */
+export class DatabaseChannel {
+  private readonly _t: string;
+  private _ready: Promise<void>;
+
+  constructor(
+    table: string,
+    private readonly _sql: SQLInstance,
+  ) {
+    this._t = safeIdentifier(table);
+    this._ready = this._ensureTable();
+    // The constructor cannot await, so a failure here would otherwise surface as
+    // an unhandled rejection before the first query re-awaits it.
+    this._ready.catch(() => undefined);
+  }
+
+  private async _ensureTable(): Promise<void> {
+    await run(this._sql, [
+      `CREATE TABLE IF NOT EXISTS ${this._t} (
+        id              TEXT PRIMARY KEY,
+        notifiable_type TEXT NOT NULL,
+        notifiable_id   TEXT NOT NULL,
+        type            TEXT NOT NULL,
+        data            TEXT NOT NULL,
+        read_at         TEXT,
+        created_at      TEXT NOT NULL
+      )`,
+    ]);
+
+    // The inbox is read far more often than it is written, and always by
+    // recipient — usually filtered to unread and ordered by recency.
+    await run(this._sql, [
+      `CREATE INDEX IF NOT EXISTS ${this._t}_notifiable_idx
+         ON ${this._t} (notifiable_type, notifiable_id, created_at)`,
+    ]);
+    await run(this._sql, [
+      `CREATE INDEX IF NOT EXISTS ${this._t}_unread_idx
+         ON ${this._t} (notifiable_type, notifiable_id, read_at)`,
+    ]);
+  }
+
+  async send(notifiable: Notifiable, notification: Notification): Promise<void> {
+    await this._ready;
+    const id = crypto.randomUUID();
+    const type = notification.constructor.name;
+    const data = JSON.stringify(await notification.toDatabase(notifiable));
+    const createdAt = new Date().toISOString();
+
+    // N values → N+1 string parts (tagged-template invariant).
+    await run(
+      this._sql,
+      [
+        `INSERT INTO ${this._t} (id, notifiable_type, notifiable_id, type, data, read_at, created_at) VALUES (`,
+        ", ", // between id and notifiable_type
+        ", ", // between notifiable_type and notifiable_id
+        ", ", // between notifiable_id and type
+        ", ", // between type and data
+        ", ", // between data and read_at
+        ", ", // between read_at and created_at
+        ")", // after created_at
+      ],
+      id,
+      notifiableType(notifiable),
+      String(notifiable.id),
+      type,
+      data,
+      null,
+      createdAt,
+    );
+  }
+
+  /** Mark a notification as read by its id. */
+  async markAsRead(id: string): Promise<void> {
+    await this._ready;
+    const readAt = new Date().toISOString();
+    await run(this._sql, [`UPDATE ${this._t} SET read_at = `, ` WHERE id = `, ""], readAt, id);
+  }
+
+  /** Mark a notification as unread by its id. */
+  async markAsUnread(id: string): Promise<void> {
+    await this._ready;
+    await run(this._sql, [`UPDATE ${this._t} SET read_at = NULL WHERE id = `, ""], id);
+  }
+
+  /** Return unread notifications for a notifiable, newest first. */
+  async unread(notifiable: Notifiable, query: InboxQuery = {}): Promise<NotificationRecord[]> {
+    await this._ready;
+    return run<NotificationRecord>(
+      this._sql,
+      [
+        `SELECT * FROM ${this._t} WHERE notifiable_type = `,
+        ` AND notifiable_id = `,
+        ` AND read_at IS NULL ORDER BY created_at DESC${this._paging(query)}`,
+      ],
+      notifiableType(notifiable),
+      String(notifiable.id),
+    );
+  }
+
+  /** Return notifications for a notifiable, newest first. */
+  async all(notifiable: Notifiable, query: InboxQuery = {}): Promise<NotificationRecord[]> {
+    await this._ready;
+    return run<NotificationRecord>(
+      this._sql,
+      [
+        `SELECT * FROM ${this._t} WHERE notifiable_type = `,
+        ` AND notifiable_id = `,
+        ` ORDER BY created_at DESC${this._paging(query)}`,
+      ],
+      notifiableType(notifiable),
+      String(notifiable.id),
+    );
+  }
+
+  /** How many unread notifications a notifiable has — for a badge, without loading rows. */
+  async unreadCount(notifiable: Notifiable): Promise<number> {
+    await this._ready;
+    const rows = await run<{ count: number }>(
+      this._sql,
+      [
+        `SELECT COUNT(*) AS count FROM ${this._t} WHERE notifiable_type = `,
+        ` AND notifiable_id = `,
+        ` AND read_at IS NULL`,
+      ],
+      notifiableType(notifiable),
+      String(notifiable.id),
+    );
+    return Number(rows[0]?.count ?? 0);
+  }
+
+  /** Mark every unread notification for a notifiable as read. */
+  async markAllAsRead(notifiable: Notifiable): Promise<void> {
+    await this._ready;
+    const readAt = new Date().toISOString();
+    await run(
+      this._sql,
+      [
+        `UPDATE ${this._t} SET read_at = `,
+        ` WHERE notifiable_type = `,
+        ` AND notifiable_id = `,
+        ` AND read_at IS NULL`,
+      ],
+      readAt,
+      notifiableType(notifiable),
+      String(notifiable.id),
+    );
+  }
+
+  /**
+   * The most recent stored notifications across every notifiable, newest first.
+   * Backs the admin console; use `all()` for one recipient's inbox.
+   */
+  async recent(limit = 100): Promise<NotificationRecord[]> {
+    await this._ready;
+    const capped = Math.max(1, Math.floor(limit));
+    return run<NotificationRecord>(this._sql, [
+      `SELECT * FROM ${this._t} ORDER BY created_at DESC LIMIT ${capped}`,
+    ]);
+  }
+
+  /** Delete one stored notification by id. */
+  async delete(id: string): Promise<void> {
+    await this._ready;
+    await run(this._sql, [`DELETE FROM ${this._t} WHERE id = `, ""], id);
+  }
+
+  /** Delete every stored notification for a notifiable. */
+  async clear(notifiable: Notifiable): Promise<void> {
+    await this._ready;
+    await run(
+      this._sql,
+      [`DELETE FROM ${this._t} WHERE notifiable_type = `, ` AND notifiable_id = `, ""],
+      notifiableType(notifiable),
+      String(notifiable.id),
+    );
+  }
+
+  /**
+   * Delete read notifications older than `days`, across every notifiable.
+   * Backs `notifications:prune` — an inbox table grows without bound otherwise.
+   *
+   * @param days - Age threshold in days.
+   * @param includeUnread - Also prune notifications never read. Default: false.
+   * @returns How many rows were deleted.
+   */
+  async prune(days: number, includeUnread = false): Promise<number> {
+    await this._ready;
+    const cutoff = new Date(Date.now() - days * 86_400_000).toISOString();
+
+    const before = await this._count();
+    if (includeUnread) {
+      await run(this._sql, [`DELETE FROM ${this._t} WHERE created_at < `, ""], cutoff);
+    } else {
+      await run(
+        this._sql,
+        [`DELETE FROM ${this._t} WHERE created_at < `, ` AND read_at IS NOT NULL`],
+        cutoff,
+      );
+    }
+    return before - (await this._count());
+  }
+
+  /** Total stored notifications, across every notifiable. */
+  async _count(): Promise<number> {
+    const rows = await run<{ count: number }>(this._sql, [
+      `SELECT COUNT(*) AS count FROM ${this._t}`,
+    ]);
+    return Number(rows[0]?.count ?? 0);
+  }
+
+  /**
+   * Render LIMIT/OFFSET into the static part of the template.
+   *
+   * Both are coerced to non-negative integers before interpolation — they are
+   * numbers by type, but this is a string concatenated into SQL, so the
+   * narrowing is enforced rather than assumed.
+   */
+  private _paging(query: InboxQuery): string {
+    const limit = query.limit === undefined ? DEFAULT_LIMIT : Math.max(0, Math.floor(query.limit));
+    const offset = Math.max(0, Math.floor(query.offset ?? 0));
+    if (limit === 0) return offset > 0 ? ` LIMIT -1 OFFSET ${offset}` : "";
+    return ` LIMIT ${limit}${offset > 0 ? ` OFFSET ${offset}` : ""}`;
+  }
+}
+
+export interface NotificationRecord {
+  id: string;
+  notifiable_type: string;
+  notifiable_id: string;
+  type: string;
+  data: string;
+  read_at: string | null;
+  created_at: string;
+}

package/src/MailChannel.ts

@@ -0,0 +1,93 @@
+import { FrameworkEvents } from "@zerotal/core";
+import { MessageSent, MessageFailed } from "./events.ts";
+import type { Notifiable, MailConfigShape } from "./types.ts";
+import type { Notification } from "./Notification.ts";
+import type { MailAddress, MailDriver } from "./drivers/MailDriver.ts";
+import { LogDriver } from "./drivers/LogDriver.ts";
+import { SmtpDriver } from "./drivers/SmtpDriver.ts";
+import { ResendDriver } from "./drivers/ResendDriver.ts";
+
+/**
+ * The `mail` notification channel — renders a notification's `toMail()` MailMessage and
+ * delivers it through the configured driver (log / SMTP / Resend). Built-in to
+ * @zerotal/notifications, so the mail channel works without any extra package.
+ */
+export class MailChannel {
+  private readonly _driver: MailDriver;
+  private readonly _from: MailAddress;
+
+  constructor(config: MailConfigShape) {
+    this._from = config.from;
+    this._driver = MailChannel._buildDriver(config);
+  }
+
+  private static _buildDriver(config: MailConfigShape): MailDriver {
+    switch (config.driver) {
+      case "smtp":
+        return new SmtpDriver(
+          config.smtp.host,
+          config.smtp.port,
+          config.smtp.username,
+          config.smtp.password,
+          config.smtp.secure,
+          {
+            ...(config.smtp.allowInsecureAuth !== undefined
+              ? { allowInsecureAuth: config.smtp.allowInsecureAuth }
+              : {}),
+            ...(config.smtp.rejectUnauthorized !== undefined
+              ? { rejectUnauthorized: config.smtp.rejectUnauthorized }
+              : {}),
+            ...(config.smtp.timeoutMs !== undefined ? { timeoutMs: config.smtp.timeoutMs } : {}),
+            ...(config.smtp.clientName !== undefined ? { clientName: config.smtp.clientName } : {}),
+          },
+        );
+      case "resend":
+        return new ResendDriver(config.resend.apiKey);
+      case "log":
+      default:
+        return new LogDriver(config.log.channel);
+    }
+  }
+
+  async send(notifiable: Notifiable, notification: Notification): Promise<void> {
+    const message = await notification.toMail(notifiable);
+    // The recipient defaults to the notifiable's email unless the MailMessage set
+    // one, or the notifiable routes 'mail' somewhere else (e.g. a billing address).
+    const address = notifiable.routeNotificationFor?.("mail") ?? notifiable.email;
+    const fallbackTo: MailAddress[] = address
+      ? [{ address, ...(notifiable.name ? { name: notifiable.name } : {}) }]
+      : [];
+    const payload = message.toPayload(this._from, fallbackTo);
+
+    // Mail telemetry — these FrameworkEvents are what feeds the monitor's Mail tab.
+    // The notification class is the "mailer" identity; recipients/subject/body come
+    // from the resolved payload so the panel mirrors exactly what was put on the wire.
+    const className = notification.constructor?.name ?? "Notification";
+    const to = payload.to.map((a) => a.address);
+    const startedAt = performance.now();
+    try {
+      await this._driver.send(payload);
+      FrameworkEvents.emit(
+        new MessageSent(
+          className,
+          to,
+          payload.subject,
+          payload.html ?? payload.text ?? "",
+          performance.now() - startedAt,
+          false,
+        ),
+      );
+    } catch (error) {
+      FrameworkEvents.emit(
+        new MessageFailed(
+          className,
+          to,
+          payload.subject,
+          performance.now() - startedAt,
+          error instanceof Error ? error.message : String(error),
+        ),
+      );
+      throw error;
+    }
+  }
+}

package/src/Notifiable.ts

@@ -0,0 +1,95 @@
+// ── Notifiable ────────────────────────────────────────────────────────────────
+//
+// Notifiable model mixin — compose it
+// onto any model that should receive notifications (typically User):
+//
+//   import { BaseModelWith } from "@zerotal/orm";
+//   import { Notifiable } from "@zerotal/notifications";
+//
+//   export class User extends BaseModelWith(Notifiable) {
+//     @column() email!: string;
+//   }
+//
+//   await user.notify(new OrderShipped(order));   // send now, across all channels
+//   await user.notifyLater(new OrderShipped(order)); // queue for background delivery
+//   const unread = await user.unreadNotifications();  // database-channel inbox
+//   await user.markNotificationsAsRead();
+//
+// The model only needs an `id` (and `email`/`phone` for the mail/sms channels) to
+// satisfy the Notifiable contract. These methods delegate to the same
+// NotificationManager the `Notify` facade uses, so behaviour is identical — this is
+// purely an ergonomic, object-oriented entry point.
+//
+// `Notifiable` is both the mixin (value) and the contract (type) — a function+interface
+// merge — so `import { Notifiable }` composes and `import type { Notifiable }` annotates.
+
+import { currentApp } from "@zerotal/core";
+import type { Notifiable as NotifiableContract } from "./types.ts";
+import type { Notification } from "./Notification.ts";
+import type { NotificationManager } from "./NotificationManager.ts";
+import type { InboxQuery, NotificationRecord } from "./DatabaseChannel.ts";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- generic mixin base bound
+type Constructor<T = object> = new (...args: any[]) => T;
+
+/** Resolve the live NotificationManager from the container (bound by NotificationProvider). */
+function _manager(): NotificationManager {
+  return currentApp().container.makeSync("notifications") as NotificationManager;
+}
+
+/**
+ * The one cast this module makes: a mixin's `this` is typed by its generic base,
+ * which cannot promise the `id`/`email` fields the Notifiable contract reads —
+ * those come from the composing model's columns. The manager reads them at
+ * delivery time, so a model composed without an `id` fails there, not here.
+ */
+function asNotifiable(model: object): Notifiable {
+  return model as unknown as Notifiable;
+}
+
+export function Notifiable<TBase extends Constructor>(Base: TBase) {
+  return class extends Base {
+    /** Send a notification to this model now, across the notification's channels. */
+    async notify(notification: Notification): Promise<void> {
+      await _manager().send(asNotifiable(this), notification);
+    }
+
+    /** Queue a notification for background delivery via @zerotal/queue. */
+    async notifyLater(notification: Notification): Promise<void> {
+      await _manager().queue(asNotifiable(this), notification);
+    }
+
+    /** All stored (database-channel) notifications for this model, newest first. */
+    async notifications(query?: InboxQuery): Promise<NotificationRecord[]> {
+      return _manager().database.all(asNotifiable(this), query);
+    }
+
+    /** Unread stored notifications for this model, newest first. */
+    async unreadNotifications(query?: InboxQuery): Promise<NotificationRecord[]> {
+      return _manager().database.unread(asNotifiable(this), query);
+    }
+
+    /** How many unread notifications this model has — for a badge, without loading rows. */
+    async unreadNotificationCount(): Promise<number> {
+      return _manager().database.unreadCount(asNotifiable(this));
+    }
+
+    /** Mark all of this model's unread notifications as read. */
+    async markNotificationsAsRead(): Promise<void> {
+      await _manager().database.markAllAsRead(asNotifiable(this));
+    }
+
+    /** Delete every stored notification for this model. */
+    async clearNotifications(): Promise<void> {
+      await _manager().database.clear(asNotifiable(this));
+    }
+  };
+}
+
+/**
+ * A model composed with the {@link Notifiable} mixin. Declared here so `Notifiable` is both a
+ * value (the mixin) and a type (the contract) — it merges with the function above. Extends the
+ * base notifiable contract, so instances pass anywhere a notifiable is expected.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- the empty body is the point: it merges the name with the mixin function above
+export interface Notifiable extends NotifiableContract {}

package/src/Notification.ts

@@ -0,0 +1,114 @@
+import { NotificationContractError } from "./errors.ts";
+import type { Notifiable } from "./types.ts";
+import type { MailMessage } from "./messages/MailMessage.ts";
+import type { SlackMessage } from "./SlackChannel.ts";
+import type { SmsMessage } from "./SmsChannel.ts";
+import type { BroadcastMessage } from "./BroadcastMessage.ts";
+
+/**
+ * Base class for all notifications.
+ *
+ * Extend this class, declare which channels() to use, then implement
+ * the corresponding to*() method for each declared channel.
+ *
+ * Supported channels:
+ *   'mail'     — implement toMail()     → returns a MailMessage
+ *   'database' — implement toDatabase() → returns a plain object
+ *   'slack'    — implement toSlack()    → returns a SlackMessage
+ *   'sms'      — implement toSms()      → returns an SmsMessage
+ *
+ * @example
+ * export class OrderShippedNotification extends Notification {
+ *   constructor(private order: Order) { super(); }
+ *
+ *   channels() { return ['mail', 'slack', 'database']; }
+ *
+ *   toMail(notifiable: Notifiable): MailMessage {
+ *     return new MailMessage()
+ *       .subject(`Order #${this.order.id} shipped`)
+ *       .line('Your order is on its way.')
+ *       .action('Track', `https://app.test/orders/${this.order.id}`);
+ *   }
+ *
+ *   toSlack(_notifiable: Notifiable): SlackMessage | Promise<SlackMessage> {
+ *     return {
+ *       webhookUrl: 'https://hooks.slack.com/services/...',
+ *       text:       `Order #${this.order.id} was shipped!`,
+ *     };
+ *   }
+ *
+ *   toDatabase() {
+ *     return { orderId: this.order.id, status: 'shipped' };
+ *   }
+ * }
+ */
+export abstract class Notification {
+  /**
+   * Declare which channels to deliver on: `'mail'`, `'database'`, `'slack'`,
+   * `'sms'`, `'broadcast'`, or any channel registered with `extend()`.
+   *
+   * The recipient is passed in, so routing can follow their preferences.
+   * Ignore the parameter when every recipient gets the same channels.
+   *
+   * @example
+   * channels(user: Notifiable) {
+   *   return user.wantsSms ? ["database", "sms"] : ["database", "mail"];
+   * }
+   */
+  abstract channels(notifiable?: Notifiable): string[];
+
+  toMail(_notifiable: Notifiable): MailMessage | Promise<MailMessage> {
+    throw new NotificationContractError(this.constructor.name, "toMail", "mail");
+  }
+
+  toDatabase(_notifiable: Notifiable): Record<string, unknown> | Promise<Record<string, unknown>> {
+    throw new NotificationContractError(this.constructor.name, "toDatabase", "database");
+  }
+
+  toSlack(_notifiable: Notifiable): SlackMessage | Promise<SlackMessage> {
+    throw new NotificationContractError(this.constructor.name, "toSlack", "slack");
+  }
+
+  toSms(_notifiable: Notifiable): SmsMessage | Promise<SmsMessage> {
+    throw new NotificationContractError(this.constructor.name, "toSms", "sms");
+  }
+
+  /**
+   * The real-time representation for the 'broadcast' channel. Return a `BroadcastMessage`
+   * (or a plain data object). Required when `channels()` includes `'broadcast'`.
+   */
+  toBroadcast(
+    _notifiable: Notifiable,
+  ):
+    | BroadcastMessage
+    | Record<string, unknown>
+    | Promise<BroadcastMessage | Record<string, unknown>> {
+    throw new NotificationContractError(this.constructor.name, "toBroadcast", "broadcast");
+  }
+
+  /** The wire `type` of a broadcast notification (lets clients distinguish kinds). Default: class name. */
+  broadcastType(): string {
+    return this.constructor.name;
+  }
+
+  /**
+   * Serialize this notification's state so it can be queued.
+   *
+   * The default copies own enumerable fields, which covers the usual case of a
+   * constructor assigning plain values. Override it when the notification holds
+   * something JSON cannot carry — a model instance, a Date-keyed Map, a closure
+   * — and pair the override with a matching `static fromPayload()`.
+   *
+   * @example
+   * override payload() {
+   *   return { orderId: this.order.id };
+   * }
+   *
+   * static override async fromPayload(data: Record<string, unknown>) {
+   *   return new OrderShipped(await Order.find(data.orderId as number));
+   * }
+   */
+  payload(): Record<string, unknown> {
+    return { ...this } as Record<string, unknown>;
+  }
+}