@zerotal/notifications 1.0.0

package/src/config.ts

@@ -0,0 +1,122 @@
+import { deepMerge } from "@zerotal/core";
+import { NotificationConfigError } from "./errors.ts";
+import type { NotificationConfigShape } from "./types.ts";
+
+/** Recursively-optional view of the config, so callers can override just the keys they care about. */
+type DeepPartial<T> = {
+  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+
+const defaults: NotificationConfigShape = {
+  database: {
+    table: "notifications",
+  },
+  mail: {
+    driver: "log",
+    from: { address: "hello@example.com", name: "Zerotal App" },
+    smtp: { host: "localhost", port: 1025, secure: false, username: "", password: "" },
+    resend: { apiKey: "" },
+    log: { channel: "console" },
+  },
+};
+
+/**
+ * Create a typed notification configuration object with defaults.
+ *
+ * @example
+ * import { NotificationConfig } from '@zerotal/notifications';
+ *
+ * export default NotificationConfig({
+ *   database: { table: 'notifications' },
+ *
+ *   // Slack incoming webhook
+ *   slack: { webhook: Bun.env['SLACK_WEBHOOK'] ?? '' },
+ *
+ *   // SMS via Twilio
+ *   sms: {
+ *     driver: 'twilio',
+ *     twilio: {
+ *       accountSid: Bun.env['TWILIO_ACCOUNT_SID'] ?? '',
+ *       authToken:  Bun.env['TWILIO_AUTH_TOKEN']  ?? '',
+ *       from:       Bun.env['TWILIO_FROM']         ?? '',
+ *     },
+ *   },
+ * });
+ */
+export function NotificationConfig(
+  options: DeepPartial<NotificationConfigShape> = {},
+): NotificationConfigShape {
+  const config = deepMerge(defaults, options as Partial<NotificationConfigShape>);
+  validateNotificationConfig(config);
+  return config;
+}
+
+/**
+ * Check the config for combinations that would only fail at send time.
+ *
+ * A missing Resend key or an SMS driver without its credential block is a
+ * deployment mistake, and the cheapest place to notice one is here — at boot,
+ * naming the key — rather than on the first password-reset email of the day.
+ *
+ * @throws {NotificationConfigError} on the first inconsistency found.
+ */
+export function validateNotificationConfig(config: NotificationConfigShape): void {
+  const { mail, sms } = config;
+
+  if (!["log", "smtp", "resend"].includes(mail.driver)) {
+    throw new NotificationConfigError(
+      `Unknown mail driver '${mail.driver}'. Expected 'log', 'smtp', or 'resend'.`,
+      { driver: mail.driver },
+    );
+  }
+
+  if (mail.driver === "resend" && !mail.resend.apiKey) {
+    throw new NotificationConfigError(
+      "mail.driver is 'resend' but mail.resend.apiKey is empty. Set RESEND_API_KEY.",
+    );
+  }
+
+  if (mail.driver === "smtp") {
+    if (!mail.smtp.host) {
+      throw new NotificationConfigError("mail.driver is 'smtp' but mail.smtp.host is empty.");
+    }
+    if (mail.smtp.username && !mail.smtp.password) {
+      throw new NotificationConfigError(
+        "mail.smtp.username is set but mail.smtp.password is empty.",
+      );
+    }
+  }
+
+  if (!mail.from.address.includes("@")) {
+    throw new NotificationConfigError(
+      `mail.from.address '${mail.from.address}' is not an email address.`,
+      { address: mail.from.address },
+    );
+  }
+
+  if (sms !== undefined) {
+    if (sms.driver === "twilio" && !sms.twilio) {
+      throw new NotificationConfigError(
+        "sms.driver is 'twilio' but sms.twilio is missing. Provide accountSid, authToken, and from.",
+      );
+    }
+    if (sms.driver === "vonage" && !sms.vonage) {
+      throw new NotificationConfigError(
+        "sms.driver is 'vonage' but sms.vonage is missing. Provide apiKey, apiSecret, and from.",
+      );
+    }
+    if (sms.driver !== "twilio" && sms.driver !== "vonage") {
+      throw new NotificationConfigError(
+        `Unknown SMS driver '${String(sms.driver)}'. Expected 'twilio' or 'vonage'.`,
+        { driver: sms.driver },
+      );
+    }
+  }
+}
+
+// Register this package's config namespace for typed config() dot-paths.
+declare module "@zerotal/core" {
+  interface ConfigRegistry {
+    notifications: NotificationConfigShape;
+  }
+}

package/src/drivers/LogDriver.ts

@@ -0,0 +1,41 @@
+import type { MailDriver, MailPayload } from "./MailDriver.ts";
+
+/**
+ * Log driver — writes email content to the console or a log file. The safe default
+ * for development and tests; no email is actually sent.
+ */
+export class LogDriver implements MailDriver {
+  constructor(private _channel: "console" | string = "console") {}
+
+  async send(message: MailPayload): Promise<void> {
+    const lines = [
+      "────────────────────────────────────",
+      `[Mail] ${new Date().toISOString()}`,
+      `To:      ${message.to.map((a) => (a.name ? `${a.name} <${a.address}>` : a.address)).join(", ")}`,
+      `From:    ${message.from.name ? `${message.from.name} <${message.from.address}>` : message.from.address}`,
+      `Subject: ${message.subject}`,
+      ...(message.cc?.length ? [`CC:      ${message.cc.map((a) => a.address).join(", ")}`] : []),
+      ...(message.attachments?.length
+        ? [
+            `Files:   ${message.attachments
+              .map((a) => `${a.filename}${a.inline ? " (inline)" : ""}`)
+              .join(", ")}`,
+          ]
+        : []),
+      "",
+      ...(message.text ? [`[Text]\n${message.text}`] : []),
+      ...(message.html ? [`[HTML]\n${message.html}`] : []),
+      "────────────────────────────────────",
+    ].join("\n");
+
+    if (this._channel === "console") {
+      console.log(lines);
+      return;
+    }
+
+    const existing = await Bun.file(this._channel)
+      .text()
+      .catch(() => "");
+    await Bun.write(this._channel, existing + lines + "\n");
+  }
+}

package/src/drivers/MailDriver.ts

@@ -0,0 +1,54 @@
+/**
+ * Mail delivery layer for the notification system's `mail` channel.
+ *
+ * A `MailDriver` is the transport (log / SMTP / Resend). It receives a fully-resolved
+ * `MailPayload` — the wire shape of one email — and delivers it. The fluent
+ * {@link MailMessage} a notification returns from `toMail()` is rendered into this
+ * payload by `MailChannel`, so drivers never deal with templates or notifiables.
+ */
+
+export interface MailAddress {
+  address: string;
+  name?: string;
+}
+
+export type AddressInput = string | MailAddress;
+
+/** Normalise a string or object address to a `MailAddress`. */
+export function resolveAddress(input: AddressInput): MailAddress {
+  return typeof input === "string" ? { address: input } : input;
+}
+
+/** A file carried alongside the message body. */
+export interface MailAttachment {
+  /** Name the recipient sees. */
+  filename: string;
+  /** File bytes, or a string for text content. */
+  content: string | Uint8Array;
+  /** MIME type. Default: `application/octet-stream`. */
+  contentType?: string;
+  /**
+   * Reference the part from the HTML body instead of listing it as a download.
+   * Set `cid` too and use `<img src="cid:the-id">`.
+   */
+  inline?: boolean;
+  /** Content-ID for an inline part, without the angle brackets. */
+  cid?: string;
+}
+
+/** The resolved, ready-to-send shape of a single email. */
+export interface MailPayload {
+  to: MailAddress[];
+  from: MailAddress;
+  subject: string;
+  text?: string;
+  html?: string;
+  cc?: MailAddress[];
+  bcc?: MailAddress[];
+  replyTo?: MailAddress;
+  attachments?: MailAttachment[];
+}
+
+export interface MailDriver {
+  send(message: MailPayload): Promise<void>;
+}

package/src/drivers/ResendDriver.ts

@@ -0,0 +1,54 @@
+import type { MailDriver, MailPayload } from "./MailDriver.ts";
+import { NotificationDeliveryError } from "../errors.ts";
+
+/**
+ * Resend driver — sends via https://api.resend.com/emails. Zero npm dependencies
+ * (native fetch). Get an API key at https://resend.com (free tier available).
+ */
+export class ResendDriver implements MailDriver {
+  constructor(private _apiKey: string) {}
+
+  async send(message: MailPayload): Promise<void> {
+    const formatAddr = (a: { address: string; name?: string }) =>
+      a.name ? `${a.name} <${a.address}>` : a.address;
+
+    const body: Record<string, unknown> = {
+      from: formatAddr(message.from),
+      to: message.to.map(formatAddr),
+      subject: message.subject,
+    };
+
+    if (message.cc?.length) body["cc"] = message.cc.map((a) => a.address);
+    if (message.bcc?.length) body["bcc"] = message.bcc.map((a) => a.address);
+    if (message.replyTo) body["reply_to"] = message.replyTo.address;
+    if (message.html !== undefined) body["html"] = message.html;
+    if (message.text !== undefined) body["text"] = message.text;
+    if (message.attachments?.length) {
+      body["attachments"] = message.attachments.map((a) => ({
+        filename: a.filename,
+        content:
+          typeof a.content === "string"
+            ? Buffer.from(a.content, "utf8").toString("base64")
+            : Buffer.from(a.content).toString("base64"),
+        ...(a.contentType ? { content_type: a.contentType } : {}),
+        ...(a.cid ? { content_id: a.cid } : {}),
+      }));
+    }
+
+    const res = await fetch("https://api.resend.com/emails", {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this._apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const err = await res.text().catch(() => "unknown error");
+      throw new NotificationDeliveryError(
+        `[Zerotal/notifications] Resend API error ${res.status}: ${err}`,
+      );
+    }
+  }
+}