@stacksjs/email 0.70.88 → 0.70.91

package/dist/css-inliner.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Inline `<style>` blocks into per-element `style=""` attributes.
+ *
+ * Simple selectors (class `.x`, id `#x`, tag `p`, and chains like
+ * `p.foo` or `.a.b`) are inlined and removed from the source block.
+ * Rules that can't be safely inlined (`@media`, pseudo-classes,
+ * descendant / sibling combinators) stay in a slimmed-down `<style>`
+ * block so clients that DO honour styles can still apply them.
+ *
+ * Returns the HTML unchanged when `inline: false`. `<style
+ * data-inline="false">` blocks are passed through verbatim regardless
+ * of `inline`.
+ */
+export declare function inlineCss(html: string, options?: InlineCssOptions): string;
+/**
+ * Honour the global production-default. Apps that want explicit
+ * control should pass `inline` through {@link inlineCss} directly.
+ */
+export declare function shouldInlineByDefault(): boolean;
+/**
+ * Options accepted by {@link inlineCss}.
+ */
+export declare interface InlineCssOptions {
+  inline?: boolean
+  important?: boolean
+}

package/dist/css-inliner.js

@@ -0,0 +1,172 @@
+export function inlineCss(html, options = {}) {
+  const { inline = !0, important = !0 } = options;
+  if (!inline)
+    return html;
+  let working = html;
+  const passthroughBlocks = [];
+  working = working.replace(/<style\b[^>]*\bdata-inline=["']false["'][^>]*>[\s\S]*?<\/style>/gi, (match) => {
+    passthroughBlocks.push(match);
+    return `\x00STX_PASSTHROUGH_${passthroughBlocks.length - 1}\x00`;
+  });
+  const styleBlocks = [];
+  working = working.replace(/<style\b[^>]*>([\s\S]*?)<\/style>/gi, (_match, body) => {
+    styleBlocks.push(body);
+    return "";
+  });
+  if (styleBlocks.length === 0)
+    return restorePassthroughs(working, passthroughBlocks);
+  const inlinableRules = [], leftover = [];
+  for (const body of styleBlocks)
+    for (const rule of splitRules(body)) {
+      const { selector, declarations } = rule;
+      if (!selector || !declarations)
+        continue;
+      if (isInlinable(selector))
+        inlinableRules.push({ selector, decls: declarations });
+      else
+        leftover.push(`${selector} { ${declarations.map((d) => `${d.prop}: ${d.value};`).join(" ")} }`);
+    }
+  for (const { selector, decls } of inlinableRules)
+    working = applyRule(working, selector, decls, important);
+  if (leftover.length > 0) {
+    const styleTag = `<style>
+${leftover.join(`
+`)}
+</style>`;
+    working = /<\/head>/i.test(working) ? working.replace(/<\/head>/i, `${styleTag}
+</head>`) : `${styleTag}
+${working}`;
+  }
+  return restorePassthroughs(working, passthroughBlocks);
+}
+function restorePassthroughs(html, blocks) {
+  if (blocks.length === 0)
+    return html;
+  return html.replace(/\u0000STX_PASSTHROUGH_(\d+)\u0000/g, (_match, idx) => {
+    return blocks[Number.parseInt(idx, 10)] ?? "";
+  });
+}
+function splitRules(body) {
+  const cleaned = body.replace(/\/\*[\s\S]*?\*\//g, ""), rules = [];
+  let i = 0;
+  while (i < cleaned.length) {
+    const open = cleaned.indexOf("{", i);
+    if (open === -1)
+      break;
+    const selector = cleaned.slice(i, open).trim();
+    let depth = 1, j = open + 1;
+    while (j < cleaned.length && depth > 0) {
+      const ch = cleaned[j];
+      if (ch === "{")
+        depth++;
+      else if (ch === "}")
+        depth--;
+      j++;
+    }
+    const inner = cleaned.slice(open + 1, j - 1);
+    if (selector.startsWith("@") || inner.includes("{"))
+      rules.push({
+        selector: selector || "@unknown",
+        declarations: parseDeclarationsLoose(inner)
+      });
+    else
+      rules.push({ selector, declarations: parseDeclarations(inner) });
+    i = j;
+  }
+  return rules;
+}
+function parseDeclarations(body) {
+  return body.split(";").map((decl) => decl.trim()).filter(Boolean).map((decl) => {
+    const colon = decl.indexOf(":");
+    if (colon === -1)
+      return null;
+    return {
+      prop: decl.slice(0, colon).trim(),
+      value: decl.slice(colon + 1).trim()
+    };
+  }).filter((d) => d !== null);
+}
+function parseDeclarationsLoose(body) {
+  return [{ prop: "", value: body.trim() }];
+}
+function isInlinable(selector) {
+  if (!selector)
+    return !1;
+  if (selector.includes(","))
+    return selector.split(",").every((s) => isInlinable(s.trim()));
+  if (selector.startsWith("@"))
+    return !1;
+  if (/[\s>+~:[]/.test(selector))
+    return !1;
+  return /^[a-z][a-z0-9-]*?$|^([a-z][a-z0-9-]*)?([.#][a-z][\w-]*)+$/i.test(selector);
+}
+function applyRule(html, selector, decls, important) {
+  if (selector.includes(",")) {
+    let acc = html;
+    for (const branch of selector.split(","))
+      acc = applyRule(acc, branch.trim(), decls, important);
+    return acc;
+  }
+  const { tag, classes, ids } = parseSimpleSelector(selector), tagRe = new RegExp(`<(${tag ?? "[a-z][a-z0-9-]*"})\\b([^>]*?)(/?)>`, "gi"), newDeclString = decls.map((d) => `${d.prop}:${d.value}${important && !/!important\b/i.test(d.value) ? " !important" : ""};`).join("");
+  return html.replace(tagRe, (match, _tagName, attrs) => {
+    if (!elementMatches(attrs, classes, ids))
+      return match;
+    return mergeStyleAttr(match, attrs, newDeclString);
+  });
+}
+function parseSimpleSelector(selector) {
+  let tag = null;
+  const classes = [], ids = [];
+  let i = 0;
+  while (i < selector.length && /[a-z0-9-]/i.test(selector[i])) {
+    tag = (tag ?? "") + selector[i];
+    i++;
+  }
+  if (tag === "")
+    tag = null;
+  while (i < selector.length) {
+    const ch = selector[i];
+    if (ch !== "." && ch !== "#")
+      break;
+    let j = i + 1;
+    while (j < selector.length && /[\w-]/.test(selector[j]))
+      j++;
+    const name = selector.slice(i + 1, j);
+    if (ch === ".")
+      classes.push(name);
+    else
+      ids.push(name);
+    i = j;
+  }
+  return { tag, classes, ids };
+}
+function elementMatches(attrs, classes, ids) {
+  if (classes.length > 0) {
+    const classMatch = attrs.match(/\bclass\s*=\s*["']([^"']*)["']/i);
+    if (!classMatch)
+      return !1;
+    const present = classMatch[1].split(/\s+/).filter(Boolean);
+    if (!classes.every((c) => present.includes(c)))
+      return !1;
+  }
+  if (ids.length > 0) {
+    const idMatch = attrs.match(/\bid\s*=\s*["']([^"']+)["']/i);
+    if (!idMatch)
+      return !1;
+    if (!ids.every((id) => idMatch[1] === id))
+      return !1;
+  }
+  return !0;
+}
+function mergeStyleAttr(originalTag, attrs, newDeclString) {
+  const styleMatch = attrs.match(/\bstyle\s*=\s*["']([^"']*)["']/i);
+  if (styleMatch) {
+    const existing = styleMatch[1].trim(), merged = `${newDeclString}${existing}${existing.endsWith(";") || existing === "" ? "" : ";"}`, replaced = attrs.replace(styleMatch[0], `style="${merged}"`);
+    return originalTag.replace(attrs, replaced);
+  }
+  const extra = ` style="${newDeclString}"`;
+  return originalTag.replace(/(\s*\/?)>$/, `${extra}$1>`);
+}
+export function shouldInlineByDefault() {
+  return (globalThis.process?.env?.APP_ENV ?? globalThis.process?.env?.NODE_ENV ?? "").toLowerCase() === "production";
+}

package/dist/drivers/base.d.ts

@@ -0,0 +1,14 @@
+import type { EmailAddress, EmailDriver, EmailDriverConfig, EmailMessage, EmailResult } from '@stacksjs/types';
+import type { TemplateOptions } from '../template';
+export declare abstract class BaseEmailDriver implements EmailDriver {
+  abstract name: string;
+  protected config: Required<EmailDriverConfig>;
+  constructor(config?: EmailDriverConfig);
+  configure(config: EmailDriverConfig): void;
+  abstract send(message: EmailMessage, options?: TemplateOptions): Promise<EmailResult>;
+  protected validateMessage(message: EmailMessage): boolean;
+  protected formatAddresses(addresses: string | string[] | EmailAddress[] | undefined): string[];
+  protected formatAddressList(value: string | string[] | EmailAddress | EmailAddress[] | undefined): string[];
+  protected handleError(error: unknown, message: EmailMessage): Promise<EmailResult>;
+  protected handleSuccess(message: EmailMessage, messageId?: string): Promise<EmailResult>;
+}

package/dist/drivers/base.js

@@ -0,0 +1,128 @@
+import { config as appConfig } from "@stacksjs/config";
+import { log } from "@stacksjs/logging";
+import { assertEnvelopeAddress, assertHeaderSafeSubject } from "../validation";
+
+export class BaseEmailDriver {
+  config;
+  constructor(config) {
+    this.config = {
+      maxRetries: config?.maxRetries || 3,
+      retryTimeout: config?.retryTimeout || 1000,
+      ...config
+    };
+  }
+  configure(config) {
+    this.config = { ...this.config, ...config };
+  }
+  validateMessage(message) {
+    if (!message.from?.address && !appConfig.email.from?.address)
+      throw Error("Email sender address is required either in message or config");
+    if (!message.to || Array.isArray(message.to) && message.to.length === 0)
+      throw Error("At least one recipient is required");
+    if (!message.subject)
+      throw Error("Email subject is required");
+    assertHeaderSafeSubject(message.subject);
+    const checkAddress = (raw, role) => {
+      if (!raw)
+        return;
+      assertEnvelopeAddress(raw, role);
+    }, flatten = (v) => {
+      if (!v)
+        return [];
+      if (typeof v === "string")
+        return [v];
+      if (Array.isArray(v))
+        return v.flatMap((item) => typeof item === "string" ? [item] : item?.address ? [item.address] : []);
+      const obj = v;
+      return obj.address ? [obj.address] : [];
+    };
+    if (message.from)
+      checkAddress(message.from.address, "from");
+    for (const addr of flatten(message.to))
+      checkAddress(addr, "to");
+    for (const addr of flatten(message.cc))
+      checkAddress(addr, "cc");
+    for (const addr of flatten(message.bcc))
+      checkAddress(addr, "bcc");
+    return !0;
+  }
+  formatAddresses(addresses) {
+    if (!addresses)
+      return [];
+    if (typeof addresses === "string")
+      return [addresses];
+    return addresses.map((_addr) => {
+      if (typeof _addr === "string")
+        return _addr;
+      if (!_addr.name)
+        return _addr.address;
+      return `${/[",()<>[\]:;@\\]/.test(_addr.name) ? `"${_addr.name.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"` : _addr.name} <${_addr.address}>`;
+    });
+  }
+  formatAddressList(value) {
+    if (!value)
+      return [];
+    if (Array.isArray(value))
+      return this.formatAddresses(value);
+    if (typeof value === "string")
+      return this.formatAddresses(value);
+    return this.formatAddresses([value]);
+  }
+  async handleError(error, message) {
+    const err = error instanceof Error ? error : Error(String(error));
+    log.error(`[${this.name}] Email sending failed`, {
+      error: err.message,
+      stack: err.stack,
+      to: message.to,
+      subject: message.subject
+    });
+    let result = {
+      message: `Email sending failed: ${err.message}`,
+      success: !1,
+      provider: this.name
+    };
+    if (message.onError) {
+      const customResult = message.onError(err), handlerResult = customResult instanceof Promise ? await customResult : customResult;
+      result = {
+        ...result,
+        ...handlerResult,
+        success: !1,
+        provider: this.name
+      };
+    }
+    return result;
+  }
+  async handleSuccess(message, messageId) {
+    let result = {
+      message: "Email sent successfully",
+      success: !0,
+      provider: this.name,
+      messageId
+    };
+    try {
+      if (message.handle) {
+        const customResult = message.handle(), handlerResult = customResult instanceof Promise ? await customResult : customResult;
+        result = {
+          ...result,
+          ...handlerResult,
+          success: !0,
+          provider: this.name,
+          messageId
+        };
+      }
+      if (message.onSuccess) {
+        const successResult = message.onSuccess(), handlerResult = successResult instanceof Promise ? await successResult : successResult;
+        result = {
+          ...result,
+          ...handlerResult,
+          success: !0,
+          provider: this.name,
+          messageId
+        };
+      }
+    } catch (error) {
+      return this.handleError(error, message);
+    }
+    return result;
+  }
+}

package/dist/drivers/capture.d.ts

@@ -0,0 +1,55 @@
+import { BaseEmailDriver } from './base';
+import type { EmailMessage, EmailResult } from '@stacksjs/types';
+import type { TemplateOptions } from '../template';
+/**
+ * Test-only capture driver (stacksjs/stacks#1871 M-12).
+ *
+ * Records every `mail.send(...)` payload in memory without opening
+ * a network socket or writing to disk. Lighter-weight than the `log`
+ * driver (which writes inspection files to `storage/logs/mail/` and
+ * does template rendering) — chosen by tests that just need to
+ * assert "this flow sent that email" without any I/O side effect.
+ *
+ * Pick this driver when:
+ *   - running fast unit tests that shouldn't touch the filesystem
+ *   - asserting on the exact message shape (subject/body/headers)
+ *     before any driver-specific transformation
+ *   - writing tests that mutate captured state and need
+ *     `CaptureEmailDriver.clear()` between cases
+ *
+ * The `log` driver remains the better fit for local dev (because
+ * the disk dump makes inspection easy) and for CI smoke tests that
+ * want to surface a render failure visibly. Capture is for unit
+ * tests.
+ *
+ * @example
+ * ```ts
+ * // bunfig.toml or test setup
+ * config.email.default = 'capture'
+ *
+ * // in tests
+ * import { CaptureEmailDriver } from '@stacksjs/email/drivers/capture'
+ *
+ * beforeEach(() => CaptureEmailDriver.clear())
+ *
+ * test('signup sends welcome', async () => {
+ *   await POST('/api/signup', { email: 'a@b.com' })
+ *   const sent = CaptureEmailDriver.all()
+ *   expect(sent).toHaveLength(1)
+ *   expect(sent[0].subject).toContain('Welcome')
+ *   expect(CaptureEmailDriver.last()?.to).toBe('a@b.com')
+ * })
+ * ```
+ */
+export declare interface CapturedMessage extends EmailMessage {
+  sentAt: Date
+  messageId: string
+}
+export declare class CaptureEmailDriver extends BaseEmailDriver {
+  name: string;
+  send(message: EmailMessage, _options?: TemplateOptions): Promise<EmailResult>;
+  static all(): readonly CapturedMessage[];
+  static last(): CapturedMessage | undefined;
+  static count(): number;
+  static clear(): void;
+}

package/dist/drivers/capture.js

@@ -0,0 +1,30 @@
+import { BaseEmailDriver } from "./base";
+const captured = [];
+let nextId = 1;
+
+export class CaptureEmailDriver extends BaseEmailDriver {
+  name = "capture";
+  async send(message, _options) {
+    try {
+      this.validateMessage(message);
+      const sentAt = new Date, messageId = `capture-${sentAt.getTime()}-${nextId++}`;
+      captured.push({ ...message, sentAt, messageId });
+      return this.handleSuccess(message, messageId);
+    } catch (error) {
+      return this.handleError(error, message);
+    }
+  }
+  static all() {
+    return captured;
+  }
+  static last() {
+    return captured[captured.length - 1];
+  }
+  static count() {
+    return captured.length;
+  }
+  static clear() {
+    captured.length = 0;
+    nextId = 1;
+  }
+}

package/dist/drivers/index.d.ts

@@ -0,0 +1,10 @@
+export * as capture from './capture';
+export * as log from './log';
+export * as mailgun from './mailgun';
+export * as mailtrap from './mailtrap';
+// `nodemailer` driver removed — it was a throwing stub that surfaced as a
+// runtime crash on `mail.send()` only after a user had already wired it
+// into config. Use the SMTP driver (`smtp` in MAIL_MAILER) for SMTP-based
+// providers; see stacksjs/stacks#1871 M-7.
+export * as sendgrid from './sendgrid';
+export * as ses from './ses';

package/dist/drivers/index.js

@@ -0,0 +1,6 @@
+export * as capture from "./capture";
+export * as log from "./log";
+export * as mailgun from "./mailgun";
+export * as mailtrap from "./mailtrap";
+export * as sendgrid from "./sendgrid";
+export * as ses from "./ses";

package/dist/drivers/log.d.ts

@@ -0,0 +1,30 @@
+import { BaseEmailDriver } from './base';
+import type { EmailMessage, EmailResult } from '@stacksjs/types';
+import type { TemplateOptions } from '../template';
+declare const captured: CapturedEmail[];
+/**
+ * Local-only email driver that never opens a network socket. Renders
+ * the message to disk so devs can inspect it (and tests can read it),
+ * and remembers the last N sends in-memory so tests can assert against
+ * them without scraping log output.
+ *
+ * Pick this driver when:
+ *   - running tests (no SMTP credentials, deterministic output)
+ *   - local development (no AWS/SendGrid setup, no mailbox spam)
+ *   - CI smoke tests where we want to assert "an email was sent"
+ *
+ * In production, use `ses` / `sendgrid` / `mailgun` / `smtp` instead.
+ */
+declare interface CapturedEmail extends EmailMessage {
+  sentAt: Date
+  rendered?: { html?: string, text?: string }
+}
+export declare class LogEmailDriver extends BaseEmailDriver {
+  name: string;
+  send(message: EmailMessage, options?: TemplateOptions): Promise<EmailResult>;
+  static captured(): readonly CapturedEmail[];
+  static reset(): void;
+}
+// Convenience export to mirror the other drivers' module shape — the
+// drivers/index.ts re-exports each driver namespace (`export * as log`).
+export default LogEmailDriver;

package/dist/drivers/log.js

@@ -0,0 +1,81 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { log } from "@stacksjs/logging";
+import { template } from "../template";
+import { BaseEmailDriver } from "./base";
+const STORE_LIMIT = 100, captured = [];
+
+export class LogEmailDriver extends BaseEmailDriver {
+  name = "log";
+  resolveDir() {
+    const fromEnv = process.env.LOG_MAIL_DIR;
+    if (fromEnv)
+      return resolve(fromEnv);
+    return resolve(join(import.meta.dir, "..", "..", "..", "..", "..", "logs", "mail"));
+  }
+  async send(message, options) {
+    try {
+      this.validateMessage(message);
+      let rendered;
+      if (message.template) {
+        const t = await template(message.template, options);
+        if (t)
+          rendered = { html: t.html, text: t.text };
+      }
+      const html = rendered?.html ?? message.html, text = rendered?.text ?? message.text, stamp = new Date, safeSubject = (message.subject || "no-subject").replace(/[^\w.-]+/g, "-").slice(0, 60), filename = `${stamp.toISOString().replace(/[:.]/g, "-")}-${safeSubject}.html`, dir = this.resolveDir();
+      try {
+        await mkdir(dir, { recursive: !0 });
+        const filePath = join(dir, filename), body = html ? html : text ? `<pre>${escapeHtml(text)}</pre>` : "<em>(empty body)</em>", headerBlock = renderHeader({ stamp, message });
+        await writeFile(filePath, `${headerBlock}
+${body}
+`);
+      } catch (err) {
+        log.warn(`[email:log] could not write inspection file: ${err.message}`);
+      }
+      const flatTo = Array.isArray(message.to) ? message.to.map((t) => typeof t === "string" ? t : t.address).join(", ") : typeof message.to === "string" ? message.to : message.to.address;
+      log.info(`[email:log] would send \u2192 ${flatTo} :: ${message.subject}`);
+      captured.push({ ...message, sentAt: stamp, rendered });
+      if (captured.length > STORE_LIMIT)
+        captured.splice(0, captured.length - STORE_LIMIT);
+      return this.handleSuccess(message, `log-${stamp.getTime()}`);
+    } catch (error) {
+      return this.handleError(error, message);
+    }
+  }
+  static captured() {
+    return captured;
+  }
+  static reset() {
+    captured.length = 0;
+  }
+}
+function renderHeader({ stamp, message }) {
+  return [
+    "<!--",
+    `  Captured by @stacksjs/email log driver at ${stamp.toISOString()}`,
+    `  From:    ${formatAddr(message.from)}`,
+    `  To:      ${formatList(message.to)}`,
+    message.cc ? `  Cc:      ${formatList(message.cc)}` : null,
+    message.bcc ? `  Bcc:     ${formatList(message.bcc)}` : null,
+    `  Subject: ${message.subject}`,
+    "-->"
+  ].filter(Boolean).join(`
+`);
+}
+function formatAddr(v) {
+  if (!v)
+    return "";
+  if (typeof v === "string")
+    return v;
+  const o = v;
+  return o.name ? `${o.name} <${o.address ?? ""}>` : o.address ?? "";
+}
+function formatList(v) {
+  if (Array.isArray(v))
+    return v.map(formatAddr).join(", ");
+  return formatAddr(v);
+}
+function escapeHtml(s) {
+  return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+}
+export default LogEmailDriver;

package/dist/drivers/mailgun.d.ts

@@ -0,0 +1,8 @@
+import { BaseEmailDriver } from './base';
+import type { EmailMessage, EmailResult } from '@stacksjs/types';
+import type { TemplateOptions } from '../template';
+export declare class MailgunDriver extends BaseEmailDriver {
+  name: string;
+  send(message: EmailMessage, options?: TemplateOptions): Promise<EmailResult>;
+}
+export default MailgunDriver;