@stacksjs/email 0.70.88 → 0.70.90

package/dist/drivers/smtp.js

@@ -0,0 +1,225 @@
+import { Buffer } from "node:buffer";
+import process from "node:process";
+import * as tls from "node:tls";
+import * as net from "node:net";
+import { config } from "@stacksjs/config";
+import { log } from "@stacksjs/logging";
+import { template } from "../template";
+import { buildMimeMessage } from "../mime";
+import { ENVELOPE_ADDRESS, filterStringHeaders } from "../validation";
+import { BaseEmailDriver } from "./base";
+function assertEnvelopeAddress(addr, role) {
+  if (typeof addr !== "string" || !ENVELOPE_ADDRESS.test(addr))
+    throw Error(`[smtp] Refusing to send: ${role} envelope address contains forbidden characters or is malformed: ${JSON.stringify(addr)}`);
+}
+
+export class SMTPDriver extends BaseEmailDriver {
+  static SMTP_TIMEOUT = 30000;
+  name = "smtp";
+  getConfig() {
+    const smtp = config.services?.smtp, env = process.env, host = smtp?.host || env.MAIL_HOST || "127.0.0.1", port = smtp?.port || (env.MAIL_PORT ? Number(env.MAIL_PORT) : void 0) || 587, fromAddress = typeof config.email?.from?.address === "string" ? config.email.from.address : "", username = smtp?.username || env.MAIL_USERNAME || fromAddress || "", localPart = (username.includes("@") ? username.split("@")[0] : username).toUpperCase().replace(/[^A-Z0-9]/g, "_"), password = smtp?.password || env.MAIL_PASSWORD || (localPart ? env[`MAIL_PASSWORD_${localPart}`] : void 0) || "", rawEncryption = smtp?.encryption ?? env.MAIL_ENCRYPTION ?? null;
+    return {
+      host,
+      port,
+      username,
+      password,
+      encryption: rawEncryption === "tls" ? "starttls" : rawEncryption || null
+    };
+  }
+  async send(message, options) {
+    const smtpConfig = this.getConfig();
+    if (!smtpConfig.host || smtpConfig.host === "")
+      throw Error("[SMTP] Host is not configured. Set MAIL_HOST in your .env file.");
+    const logContext = {
+      provider: this.name,
+      to: message.to,
+      subject: message.subject,
+      host: smtpConfig.host,
+      port: smtpConfig.port
+    };
+    log.info("Sending email via SMTP...", logContext);
+    try {
+      this.validateMessage(message);
+      let htmlContent;
+      if (message.template) {
+        const templ = await template(message.template, options);
+        if (templ && "html" in templ)
+          htmlContent = templ.html;
+      }
+      const finalHtml = htmlContent || message.html, fromAddress = message.from?.address || config.email.from?.address || "", fromName = message.from?.name || config.email.from?.name || "", toAddresses = this.formatAddresses(message.to), replyToAddresses = this.formatAddressList(message.replyTo), emailContent = buildMimeMessage({
+        from: fromName ? `${fromName} <${fromAddress}>` : fromAddress,
+        to: toAddresses.join(", "),
+        cc: message.cc ? this.formatAddresses(message.cc).join(", ") : void 0,
+        replyTo: replyToAddresses.length > 0 ? replyToAddresses.join(", ") : void 0,
+        customHeaders: filterStringHeaders(message.headers),
+        subject: message.subject,
+        text: message.text,
+        html: finalHtml,
+        attachments: message.attachments,
+        messageIdDomain: config.email.domain
+      }), messageId = await this.sendViaSMTP(smtpConfig, fromAddress, toAddresses, emailContent);
+      return this.handleSuccess(message, messageId);
+    } catch (error) {
+      return this.handleError(error, message);
+    }
+  }
+  async sendViaSMTP(smtpConfig, from, to, content) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(Error(`SMTP connection timed out after ${SMTPDriver.SMTP_TIMEOUT}ms`));
+      }, SMTPDriver.SMTP_TIMEOUT), originalResolve = resolve, originalReject = reject;
+      resolve = (value) => {
+        clearTimeout(timeout);
+        originalResolve(value);
+      };
+      reject = (reason) => {
+        clearTimeout(timeout);
+        originalReject(reason);
+      };
+      let socket, buffer = "";
+      const _currentCommand = "", commandQueue = [], _isProcessing = !1;
+      let completed = !1;
+      const processResponse = (response) => {
+        log.debug(`[SMTP] Server: ${response.trim()}`);
+        if (parseInt(response.substring(0, 3), 10) >= 400) {
+          const error = Error(`SMTP Error: ${response.trim()}`);
+          if (commandQueue.length > 0)
+            commandQueue.shift()?.reject(error);
+          return;
+        }
+        if (commandQueue.length > 0)
+          commandQueue.shift()?.resolve(response);
+      }, sendCommand = (cmd) => {
+        return new Promise((res, rej) => {
+          commandQueue.push({ cmd, resolve: res, reject: rej });
+          log.debug(`[SMTP] Client: ${cmd}`);
+          socket.write(`${cmd}\r
+`);
+        });
+      }, handleData = (data) => {
+        buffer += data.toString();
+        const lines = buffer.split(`\r
+`);
+        buffer = lines.pop() || "";
+        for (const line of lines)
+          if (line.length >= 3) {
+            if (line.length === 3 || line[3] === " ")
+              processResponse(line);
+          }
+      }, runSmtpSession = async () => {
+        try {
+          await new Promise((res, rej) => {
+            commandQueue.push({ cmd: "GREETING", resolve: res, reject: rej });
+          });
+          const _ehloResponse = await sendCommand(`EHLO ${config.email.domain || "localhost"}`);
+          if (smtpConfig.encryption === "starttls" && !(socket instanceof tls.TLSSocket)) {
+            await sendCommand("STARTTLS");
+            const plainSocket = socket;
+            plainSocket.removeAllListeners("data");
+            socket = await new Promise((res, rej) => {
+              const tlsSocket = tls.connect({
+                socket: plainSocket,
+                host: smtpConfig.host,
+                servername: smtpConfig.host
+              }, () => {
+                log.debug("[SMTP] TLS connection established");
+                res(tlsSocket);
+              });
+              tlsSocket.on("error", (err) => {
+                log.error("[SMTP] TLS socket error:", err);
+                rej(err);
+              });
+              tlsSocket.on("data", handleData);
+              tlsSocket.on("close", (hadError) => {
+                log.debug(`[SMTP] TLS socket closed (hadError: ${hadError})`);
+                while (commandQueue.length > 0)
+                  commandQueue.shift()?.reject(Error("TLS connection closed unexpectedly"));
+              });
+            });
+            await sendCommand(`EHLO ${config.email.domain || "localhost"}`);
+          }
+          if (smtpConfig.username && smtpConfig.password) {
+            await sendCommand("AUTH LOGIN");
+            await sendCommand(Buffer.from(smtpConfig.username).toString("base64"));
+            await sendCommand(Buffer.from(smtpConfig.password).toString("base64"));
+          }
+          assertEnvelopeAddress(from, "MAIL FROM");
+          for (const recipient of to)
+            assertEnvelopeAddress(recipient, "RCPT TO");
+          await sendCommand(`MAIL FROM:<${from}>`);
+          for (const recipient of to)
+            await sendCommand(`RCPT TO:<${recipient}>`);
+          await sendCommand("DATA");
+          socket.write(`${content}\r
+.\r
+`);
+          await new Promise((res, rej) => {
+            commandQueue.push({ cmd: "DATA_END", resolve: res, reject: rej });
+          });
+          completed = !0;
+          const messageId = `${Date.now()}.${Math.random().toString(36).substring(2)}@${smtpConfig.host}`;
+          try {
+            socket.write(`QUIT\r
+`);
+          } catch {}
+          socket.end();
+          resolve(messageId);
+        } catch (error) {
+          if (completed) {
+            socket.end();
+            return;
+          }
+          socket.end();
+          reject(error);
+        }
+      };
+      if (smtpConfig.encryption === "ssl")
+        socket = tls.connect({
+          host: smtpConfig.host,
+          port: smtpConfig.port,
+          servername: smtpConfig.host
+        }, () => {
+          log.debug(`[SMTP] TLS connected to ${smtpConfig.host}:${smtpConfig.port}`);
+          runSmtpSession();
+        });
+      else
+        socket = net.connect({
+          host: smtpConfig.host,
+          port: smtpConfig.port
+        }, () => {
+          log.debug(`[SMTP] Connected to ${smtpConfig.host}:${smtpConfig.port}`);
+          runSmtpSession();
+        });
+      socket.on("data", handleData);
+      socket.setTimeout(SMTPDriver.SMTP_TIMEOUT);
+      socket.on("timeout", () => {
+        socket.destroy(Error(`SMTP socket timed out after ${SMTPDriver.SMTP_TIMEOUT}ms`));
+      });
+      socket.on("error", (error) => {
+        if (completed)
+          return;
+        log.error(`[SMTP] Connection error to ${smtpConfig.host}:${smtpConfig.port}:`, error);
+        reject(error);
+      });
+      socket.on("close", (hadError) => {
+        log.debug(`[SMTP] Connection closed (hadError: ${hadError})`);
+        if (completed)
+          return;
+        while (commandQueue.length > 0)
+          commandQueue.shift()?.reject(Error("Connection closed unexpectedly"));
+      });
+    });
+  }
+  formatAddresses(addresses) {
+    if (!addresses)
+      return [];
+    if (typeof addresses === "string")
+      return [addresses];
+    return addresses.map((addr) => {
+      if (typeof addr === "string")
+        return addr;
+      return addr.address;
+    });
+  }
+}
+export default SMTPDriver;

package/dist/email.d.ts

@@ -0,0 +1,39 @@
+import type { EmailMessage, EmailResult } from '@stacksjs/types';
+import type { Message } from './types';
+export declare const mail: Mail;
+/** Result returned by email handler callbacks */
+declare interface EmailHandlerResult {
+  message: string
+}
+/** Configuration for the sender address */
+declare interface EmailFromAddress {
+  name: string
+  address: string
+}
+/** Configuration for the Mail singleton */
+declare interface MailConfig {
+  defaultDriver?: string
+}
+/**
+ * Email notification class for defining email notifications
+ */
+export declare class Email {
+  name: string;
+  subject: string;
+  to: string | string[];
+  from?: EmailFromAddress;
+  template: string;
+  handle?: () => Promise<EmailHandlerResult>;
+  onError?: (error: Error) => Promise<EmailHandlerResult>;
+  onSuccess?: () => void;
+  constructor(options: Message);
+  send(to?: string | string[]): Promise<EmailHandlerResult>;
+}
+export declare class Mail {
+  constructor(options?: MailConfig);
+  send(message: EmailMessage): Promise<EmailResult>;
+  use(driver: string): Mail;
+  queue(message: EmailMessage): Promise<void>;
+  later(delaySeconds: number, message: EmailMessage): Promise<void>;
+  queueOn(queueName: string, message: EmailMessage): Promise<void>;
+}

package/dist/email.js

@@ -0,0 +1,198 @@
+import { config } from "@stacksjs/config";
+import { log } from "@stacksjs/logging";
+import { CaptureEmailDriver } from "./drivers/capture";
+import { LogEmailDriver } from "./drivers/log";
+import { MailgunDriver } from "./drivers/mailgun";
+import { MailtrapDriver } from "./drivers/mailtrap";
+import { SendGridDriver } from "./drivers/sendgrid";
+import { SESDriver } from "./drivers/ses";
+import { SMTPDriver } from "./drivers/smtp";
+import { findEmailByIdempotencyKey, recordEmailIdempotency } from "./idempotency";
+import { checkSuppressionFor } from "./suppression";
+
+export class Email {
+  name;
+  subject;
+  to;
+  from;
+  template;
+  handle;
+  onError;
+  onSuccess;
+  constructor(options) {
+    this.name = options.name;
+    this.subject = options.subject;
+    this.to = options.to;
+    this.from = options.from;
+    this.template = options.template;
+    this.handle = options.handle;
+    this.onError = options.onError;
+    this.onSuccess = options.onSuccess;
+  }
+  async renderTemplate() {
+    if (!this.template)
+      return "";
+    try {
+      const { path: p } = await import("@stacksjs/path"), templatePath = p.resourcesPath(`views/emails/${this.template}.html`), file = Bun.file(templatePath);
+      if (await file.exists())
+        return await file.text();
+    } catch {}
+    if (this.template.includes("<"))
+      return this.template;
+    return `<p>${this.template}</p>`;
+  }
+  async send(to) {
+    const target = to ?? this.to, recipients = Array.isArray(target) ? target : target ? [target] : [];
+    if (recipients.length === 0)
+      throw Error("No recipient specified for email");
+    try {
+      await mail.send({
+        to: recipients,
+        from: this.from || {
+          name: config.email.from?.name || "Stacks",
+          address: config.email.from?.address || "no-reply@stacksjs.com"
+        },
+        subject: this.subject,
+        html: await this.renderTemplate()
+      });
+      if (this.onSuccess)
+        this.onSuccess();
+      if (this.handle)
+        return this.handle();
+      return { message: "Email sent" };
+    } catch (error) {
+      if (this.onError)
+        return this.onError(error instanceof Error ? error : Error(String(error)));
+      throw error;
+    }
+  }
+}
+
+export class Mail {
+  drivers = new Map;
+  defaultDriver;
+  constructor(options = {}) {
+    this.defaultDriver = options.defaultDriver || config.email.default || "ses";
+    this.registerDefaultDrivers();
+  }
+  registerDefaultDrivers() {
+    this.drivers.set("log", new LogEmailDriver);
+    this.drivers.set("ses", new SESDriver);
+    this.drivers.set("sendgrid", new SendGridDriver);
+    this.drivers.set("mailgun", new MailgunDriver);
+    this.drivers.set("mailtrap", new MailtrapDriver);
+    this.drivers.set("smtp", new SMTPDriver);
+    this.drivers.set("capture", new CaptureEmailDriver);
+  }
+  async send(message) {
+    const driver = this.drivers.get(this.defaultDriver);
+    if (!driver) {
+      const available = [...this.drivers.keys()].sort().join(", ");
+      throw Error(`Email driver '${this.defaultDriver}' is not registered. Available drivers: [${available}]. Check config.email.default or the MAIL_MAILER environment variable.`);
+    }
+    if (message.idempotencyKey) {
+      const cached = await findEmailByIdempotencyKey(message.idempotencyKey);
+      if (cached)
+        return cached;
+    }
+    const suppressionType = await checkSuppressionForFirstRecipient(message);
+    if (suppressionType)
+      return {
+        success: !1,
+        message: `suppressed:${suppressionType}`,
+        provider: "suppression"
+      };
+    const defaultFrom = {
+      name: config.email.from?.name || "Stacks",
+      address: config.email.from?.address || "no-reply@stacksjs.com"
+    }, result = await driver.send({
+      ...message,
+      from: message.from || defaultFrom
+    });
+    if (message.idempotencyKey)
+      await recordEmailIdempotency(message.idempotencyKey, message, result);
+    return result;
+  }
+  use(driver) {
+    if (!this.drivers.has(driver))
+      throw Error(`Email driver '${driver}' is not available`);
+    return new Mail({ defaultDriver: driver });
+  }
+  async queue(message) {
+    await this.dispatchOrFallback(message, async () => {
+      const { job } = await import("@stacksjs/queue");
+      await job("SendEmail", { message, driver: this.defaultDriver }).onQueue("emails").dispatch();
+    }, { context: "queue" });
+  }
+  async later(delaySeconds, message) {
+    await this.dispatchOrFallback(message, async () => {
+      const { job } = await import("@stacksjs/queue");
+      await job("SendEmail", { message, driver: this.defaultDriver }).onQueue("emails").delay(delaySeconds).dispatch();
+    }, { context: "later", delaySeconds });
+  }
+  async queueOn(queueName, message) {
+    await this.dispatchOrFallback(message, async () => {
+      const { job } = await import("@stacksjs/queue");
+      await job("SendEmail", { message, driver: this.defaultDriver }).onQueue(queueName).dispatch();
+    }, { context: "queueOn", queueName });
+  }
+  async dispatchOrFallback(message, dispatch, logExtra) {
+    try {
+      await dispatch();
+      return;
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      log.warn("[email] Queue dispatch failed; falling back to synchronous send. " + "Background email pipeline is degraded \u2014 check the queue worker / broker.", { ...logExtra, reason });
+    }
+    await this.send(message);
+  }
+}
+async function checkSuppressionForFirstRecipient(message) {
+  const recipients = collectRecipientAddresses(message);
+  if (recipients.length === 0)
+    return null;
+  for (const addr of recipients) {
+    const matched = await checkSuppressionFor(addr, message.tag);
+    if (matched)
+      return matched;
+  }
+  return null;
+}
+function collectRecipientAddresses(message) {
+  const out = [], pushOne = (v) => {
+    if (typeof v === "string") {
+      out.push(v);
+      return;
+    }
+    if (v && typeof v === "object" && "address" in v && typeof v.address === "string")
+      out.push(v.address);
+  };
+  for (const field of ["to", "cc", "bcc"]) {
+    const v = message[field];
+    if (!v)
+      continue;
+    if (Array.isArray(v))
+      for (const item of v)
+        pushOne(item);
+    else
+      pushOne(v);
+  }
+  return out;
+}
+let _mail;
+function getMail() {
+  if (!_mail) {
+    const driver = config?.email?.default || process.env.MAIL_MAILER || "ses";
+    _mail = new Mail({ defaultDriver: driver });
+  }
+  return _mail;
+}
+export const mail = new Proxy({}, {
+  get(_t, prop) {
+    return getMail()[prop];
+  },
+  set(_t, prop, value) {
+    getMail()[prop] = value;
+    return !0;
+  }
+});

package/dist/idempotency.d.ts

@@ -0,0 +1,20 @@
+import type { EmailMessage, EmailResult } from '@stacksjs/types';
+/**
+ * Look up a cached EmailResult by idempotency key. Returns the
+ * reconstructed result when this key has been seen before, `null`
+ * when it hasn't. Degrades to "always null" with a startup warn
+ * when the `email_idempotency` dedup table isn't migrated yet.
+ */
+export declare function findEmailByIdempotencyKey(key: string): Promise<EmailResult | null>;
+/**
+ * Record a successful send under its idempotency key. No-op when
+ * the table doesn't exist (warn-once already fired from the lookup
+ * path) and when the result reports failure (failed sends shouldn't
+ * lock out retries).
+ *
+ * Collision (same key inserted concurrently) is intentionally
+ * swallowed: the row already exists, which is exactly what the
+ * lookup will return next time. Throwing here would mask an
+ * otherwise successful send.
+ */
+export declare function recordEmailIdempotency(key: string, message: EmailMessage, result: EmailResult): Promise<void>;

package/dist/idempotency.js

@@ -0,0 +1,56 @@
+import { db } from "@stacksjs/database";
+let warnedAboutMissingEmailIdempotencyTable = !1;
+function warnOnceAboutMissingTable() {
+  if (warnedAboutMissingEmailIdempotencyTable)
+    return;
+  warnedAboutMissingEmailIdempotencyTable = !0;
+  console.warn("[email/idempotency] email_idempotency table missing \u2014 idempotency keys are accepted but NOT enforced. " + "Run migrations to enable dedup.");
+}
+function isMissingTableError(err) {
+  const msg = (err?.message ?? "").toLowerCase();
+  return msg.includes("no such table") || msg.includes("doesn't exist") || msg.includes("connection closed") || msg.includes("unable to open database") || msg.includes("econnrefused") || msg.includes("connection terminated") || msg.includes("no database") || msg.includes("database connection");
+}
+export async function findEmailByIdempotencyKey(key) {
+  try {
+    const row = await db.selectFrom("email_idempotency").where("idempotency_key", "=", key).selectAll().executeTakeFirst();
+    if (!row)
+      return null;
+    return {
+      success: Boolean(row.success),
+      message: `Idempotent replay \u2014 original send recorded ${row.created_at}`,
+      provider: String(row.provider ?? "cache"),
+      messageId: row.message_id ?? void 0
+    };
+  } catch (err) {
+    if (isMissingTableError(err)) {
+      warnOnceAboutMissingTable();
+      return null;
+    }
+    throw err;
+  }
+}
+export async function recordEmailIdempotency(key, message, result) {
+  if (!result.success)
+    return;
+  const recipient = Array.isArray(message.to) ? message.to.map((t) => typeof t === "string" ? t : t.address).join(", ") : typeof message.to === "string" ? message.to : message.to.address;
+  try {
+    await db.insertInto("email_idempotency").values({
+      idempotency_key: key,
+      message_id: result.messageId ?? null,
+      recipient,
+      subject: message.subject,
+      provider: result.provider,
+      success: 1,
+      created_at: new Date().toISOString().slice(0, 19).replace("T", " ")
+    }).execute();
+  } catch (err) {
+    if (isMissingTableError(err)) {
+      warnOnceAboutMissingTable();
+      return;
+    }
+    const msg = err?.message ?? "";
+    if (msg.includes("UNIQUE constraint") || msg.includes("Duplicate entry"))
+      return;
+    throw err;
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export type { InlineCssOptions } from './css-inliner';
+export type { DiscoveredMailable, MailablePreview } from './preview';
+export * from './drivers/index';
+export * from './email';
+export * from './idempotency';
+export * from './suppression';
+export * from './unsubscribe';
+export * from './webhook-dedup';
+export * from './webhook-events';
+export * from './webhook-handlers';
+export * from './webhook-signatures';
+export * from './mailable';
+export * from './template';
+export * from './types';
+export { inlineCss, shouldInlineByDefault } from './css-inliner';
+// Dev-only Mailable preview server (stacksjs/stacks#1900 A3).
+export {
+  discoverMailables,
+  loadSampleProps,
+  renderMailablePreview,
+} from './preview';
+export { renderIndexHtml, renderPreviewHtml } from './preview-ui';

package/dist/index.js

@@ -0,0 +1,19 @@
+export * from "./drivers";
+export * from "./email";
+export * from "./idempotency";
+export * from "./suppression";
+export * from "./unsubscribe";
+export * from "./webhook-dedup";
+export * from "./webhook-events";
+export * from "./webhook-handlers";
+export * from "./webhook-signatures";
+export * from "./mailable";
+export * from "./template";
+export * from "./types";
+export { inlineCss, shouldInlineByDefault } from "./css-inliner";
+export {
+  discoverMailables,
+  loadSampleProps,
+  renderMailablePreview
+} from "./preview";
+export { renderIndexHtml, renderPreviewHtml } from "./preview-ui";