@stacksjs/email 0.70.88 → 0.70.91

package/dist/template.js

@@ -0,0 +1,170 @@
+import { config } from "@stacksjs/config";
+import { log } from "@stacksjs/logging";
+import { fs } from "@stacksjs/storage";
+import { defaultsResourcesPath, resourcesPath } from "@stacksjs/path";
+import { join } from "node:path";
+import { inlineCss, shouldInlineByDefault } from "./css-inliner";
+
+export class SafeHtml {
+  value;
+  __safeHtml = !0;
+  constructor(value) {
+    this.value = value;
+  }
+}
+export function safe(html) {
+  return new SafeHtml(html);
+}
+function getDefaultVariables() {
+  const primaryColor = config.app.primaryColor || "#3b82f6";
+  return {
+    appName: config.app.name || "Stacks",
+    appUrl: config.app.url || "https://localhost",
+    primaryColor,
+    primaryColorDark: darkenColor(primaryColor, 15),
+    year: new Date().getFullYear()
+  };
+}
+function darkenColor(hex, percent) {
+  const num = Number.parseInt(hex.replace("#", ""), 16), amt = Math.round(2.55 * percent), R = Math.max(0, (num >> 16) - amt), G = Math.max(0, (num >> 8 & 255) - amt), B = Math.max(0, (num & 255) - amt);
+  return `#${(16777216 + R * 65536 + G * 256 + B).toString(16).slice(1)}`;
+}
+function escapeHtml(input) {
+  return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function replaceVariables(html, variables) {
+  let result = html;
+  for (const [key, value] of Object.entries(variables)) {
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), regex = new RegExp(`\\{\\{\\s*${escapedKey}\\s*\\}\\}`, "g");
+    result = result.replace(regex, renderTemplateValue(value));
+  }
+  return result;
+}
+function renderTemplateValue(value) {
+  if (value === null || value === void 0)
+    return "";
+  if (value instanceof SafeHtml)
+    return value.value;
+  return escapeHtml(String(value));
+}
+const templateRoots = [
+  (relativePath) => resourcesPath(join("emails", relativePath)),
+  (relativePath) => defaultsResourcesPath(join("emails", relativePath))
+];
+function resolveTemplatePath(templateName) {
+  for (const root of templateRoots) {
+    if (templateName.endsWith(".stx")) {
+      const fullPath = root(templateName);
+      if (fs.existsSync(fullPath))
+        return { path: fullPath, type: "stx" };
+      continue;
+    }
+    if (templateName.endsWith(".html")) {
+      const fullPath = root(templateName);
+      if (fs.existsSync(fullPath))
+        return { path: fullPath, type: "html" };
+      continue;
+    }
+    const stxPath = root(`${templateName}.stx`);
+    if (fs.existsSync(stxPath))
+      return { path: stxPath, type: "stx" };
+    const htmlPath = root(`${templateName}.html`);
+    if (fs.existsSync(htmlPath))
+      return { path: htmlPath, type: "html" };
+  }
+  return null;
+}
+function loadHtmlTemplate(templatePath) {
+  const path = templatePath.endsWith(".html") ? templatePath : `${templatePath}.html`;
+  for (const root of templateRoots) {
+    const fullPath = root(path);
+    if (fs.existsSync(fullPath))
+      return fs.readFileSync(fullPath, "utf-8");
+  }
+  return null;
+}
+function loadLayout(layoutName) {
+  return loadHtmlTemplate(`layouts/${layoutName}`);
+}
+function htmlToText(html) {
+  return html.replace(/<br\s*\/?>/gi, `
+`).replace(/<\/(p|div|h[1-6]|li|tr)>/gi, `
+`).replace(/<\/td>/gi, "\t").replace(/<[^>]*>/g, "").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&copy;/g, "(c)").replace(/\n\s*\n\s*\n/g, `
+
+`).trim();
+}
+export async function template(templateName, options = {}) {
+  const {
+    variables = {},
+    layout = "base",
+    subject = "",
+    inline = shouldInlineByDefault()
+  } = options, allVariables = {
+    ...getDefaultVariables(),
+    subject,
+    ...variables
+  }, resolved = resolveTemplatePath(templateName);
+  if (!resolved) {
+    console.warn(`[Email Template] Template "${templateName}" not found`);
+    return { html: "", text: "" };
+  }
+  if (resolved.type === "stx")
+    try {
+      const { renderEmail } = await import("@stacksjs/stx"), result = await renderEmail(resolved.path, allVariables, {
+        componentsDir: defaultsResourcesPath("components/Email")
+      });
+      return {
+        ...result,
+        html: inlineCss(result.html, { inline })
+      };
+    } catch (error) {
+      log.warn(`[email] STX template rendering failed for ${templateName}: ${error instanceof Error ? error.message : String(error)}`);
+      return { html: "", text: "" };
+    }
+  let content = fs.readFileSync(resolved.path, "utf-8");
+  content = replaceVariables(content, allVariables);
+  let html;
+  if (layout !== !1) {
+    const layoutHtml = loadLayout(layout);
+    if (!layoutHtml) {
+      console.warn(`[Email Template] Layout "${layout}" not found, using content only`);
+      html = content;
+    } else {
+      allVariables.content = safe(content);
+      html = replaceVariables(layoutHtml, allVariables);
+    }
+  } else
+    html = content;
+  html = inlineCss(html, { inline });
+  const text = htmlToText(html);
+  return { html, text };
+}
+export function renderHtml(htmlContent, variables = {}) {
+  const allVariables = {
+    ...getDefaultVariables(),
+    ...variables
+  }, html = replaceVariables(htmlContent, allVariables), text = htmlToText(html);
+  return { html, text };
+}
+export function templateExists(templateName) {
+  return resolveTemplatePath(templateName) !== null;
+}
+export function listTemplates() {
+  const emailsPath = resourcesPath("emails");
+  if (!fs.existsSync(emailsPath))
+    return [];
+  const templates = [];
+  function scanDir(dir, prefix = "") {
+    const entries = fs.readdirSync(dir, { withFileTypes: !0 });
+    for (const entry of entries)
+      if (entry.isDirectory() && entry.name !== "layouts")
+        scanDir(join(dir, entry.name), `${prefix}${entry.name}/`);
+      else if (entry.isFile() && (entry.name.endsWith(".html") || entry.name.endsWith(".stx"))) {
+        const name = entry.name.replace(/\.(html|stx)$/, "");
+        if (!templates.includes(`${prefix}${name}`))
+          templates.push(`${prefix}${name}`);
+      }
+  }
+  scanDir(emailsPath);
+  return templates;
+}

package/dist/types.d.ts

@@ -0,0 +1,37 @@
+export declare interface Message {
+  name: string
+  subject: string
+  to: string | string[]
+  from?: {
+    name: string
+    address: string
+  }
+  template: string
+  handle?: () => Promise<{ message: string }>
+  onError?: (error: Error) => Promise<{ message: string }>
+  onSuccess?: () => void
+}
+export declare interface SendEmailParams {
+  Source: string
+  Destination: {
+    ToAddresses: string[]
+  }
+  Message: {
+    Body: {
+      Html: {
+        Charset: 'UTF-8'
+        Data: string
+      }
+    }
+    Subject: {
+      Charset: 'UTF-8'
+      Data: string
+    }
+  }
+}
+export declare interface EmailParams {
+  to: string
+  from: string
+  subject: string
+  html: string
+}

package/dist/unsubscribe.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Mint a signed unsubscribe token for `email`. Default expiry is
+ * 30 days — long enough that the link in an archived email still
+ * works months later, short enough that a leaked URL doesn't grant
+ * indefinite control. Tighter caps available via `ttlSeconds`.
+ */
+export declare function createUnsubscribeToken(email: string, ttlSeconds?: number): string;
+/**
+ * Verify a signed unsubscribe token. Returns the email + a
+ * discriminated outcome — callers map invalid results to a 400/410
+ * response and the success case writes the suppression record.
+ */
+export declare function verifyUnsubscribeToken(token: string): UnsubscribeVerification;
+/**
+ * Build the full opt-out URL for `email`. Combines the configured
+ * route prefix (`email.unsubscribeRoute`, defaults to
+ * `/_stacks/email/unsubscribe`) with the app's public URL (`APP_URL`
+ * env var) and the signed token.
+ *
+ * Pass the result into email bodies / `List-Unsubscribe` headers —
+ * see {@link buildListUnsubscribeHeaders} for RFC 8058
+ * (one-click) compatibility.
+ */
+export declare function buildUnsubscribeUrl(email: string, ttlSeconds?: number, options?: { baseUrl?: string, routePrefix?: string }): string;
+/**
+ * Build a `List-Unsubscribe` / `List-Unsubscribe-Post` header
+ * pair (RFC 8058). Gmail/Apple Mail use these for the native
+ * "Unsubscribe" button — without them the user has to find your
+ * footer link.
+ *
+ * Returns a map suitable for passing into `EmailMessage.headers`
+ * (or merging with existing headers).
+ */
+export declare function buildListUnsubscribeHeaders(email: string, ttlSeconds?: number, options?: { baseUrl?: string, routePrefix?: string }): Record<string, string>;
+export declare interface UnsubscribeVerification {
+  valid: boolean
+  reason?: 'malformed' | 'bad_signature' | 'expired'
+  email?: string
+}

package/dist/unsubscribe.js

@@ -0,0 +1,65 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import process from "node:process";
+import { Buffer } from "node:buffer";
+const DEFAULT_TTL_SECONDS = 2592000, DEFAULT_ROUTE = "/_stacks/email/unsubscribe";
+function getAppKey() {
+  const k = process.env.APP_KEY;
+  if (!k || k.length < 16) {
+    if (process.env.APP_ENV === "production" || process.env.NODE_ENV === "production")
+      throw Error("[email/unsubscribe] APP_KEY is missing or too short (need \u226516 chars). Cannot sign unsubscribe URL.");
+  }
+  return k || "stacks-default-key-dev-only-do-not-use-prod";
+}
+function b64UrlEncode(buf) {
+  return buf.toString("base64url");
+}
+function b64UrlDecode(s) {
+  return Buffer.from(s, "base64url");
+}
+export function createUnsubscribeToken(email, ttlSeconds = DEFAULT_TTL_SECONDS) {
+  if (!email)
+    throw Error("[email/unsubscribe] email is required");
+  const exp = Math.floor(Date.now() / 1000) + Math.floor(ttlSeconds), claims = {
+    email: String(email).trim().toLowerCase(),
+    exp,
+    iss: "stacks"
+  }, payload = b64UrlEncode(Buffer.from(JSON.stringify(claims))), sig = b64UrlEncode(createHmac("sha256", getAppKey()).update(payload).digest());
+  return `${payload}.${sig}`;
+}
+export function verifyUnsubscribeToken(token) {
+  if (typeof token !== "string")
+    return { valid: !1, reason: "malformed" };
+  const parts = token.split(".");
+  if (parts.length !== 2)
+    return { valid: !1, reason: "malformed" };
+  const [payload, sig] = parts, expectedSig = createHmac("sha256", getAppKey()).update(payload).digest();
+  let provided;
+  try {
+    provided = b64UrlDecode(sig);
+  } catch {
+    return { valid: !1, reason: "malformed" };
+  }
+  if (provided.length !== expectedSig.length || !timingSafeEqual(provided, expectedSig))
+    return { valid: !1, reason: "bad_signature" };
+  let claims;
+  try {
+    claims = JSON.parse(b64UrlDecode(payload).toString("utf8"));
+  } catch {
+    return { valid: !1, reason: "malformed" };
+  }
+  if (typeof claims.exp !== "number" || Math.floor(Date.now() / 1000) >= claims.exp)
+    return { valid: !1, reason: "expired" };
+  if (!claims.email || typeof claims.email !== "string")
+    return { valid: !1, reason: "malformed" };
+  return { valid: !0, email: claims.email };
+}
+export function buildUnsubscribeUrl(email, ttlSeconds, options = {}) {
+  const token = createUnsubscribeToken(email, ttlSeconds), base = (options.baseUrl || process.env.APP_URL || "http://localhost").replace(/\/$/, ""), route = (options.routePrefix || DEFAULT_ROUTE).replace(/\/$/, "");
+  return `${base}${route}/${token}`;
+}
+export function buildListUnsubscribeHeaders(email, ttlSeconds, options) {
+  return {
+    "List-Unsubscribe": `<${buildUnsubscribeUrl(email, ttlSeconds, options)}>`,
+    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
+  };
+}

package/dist/utils/config.d.ts

@@ -0,0 +1,3 @@
+import { notification } from '@stacksjs/config';
+export declare const email: typeof notification.email;
+export default email;

package/dist/utils/config.js

@@ -0,0 +1,3 @@
+import { notification } from "@stacksjs/config";
+export const email = notification.email;
+export default email;

package/dist/validation.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Throw if `addr` isn't a clean envelope address. The error message
+ * includes the role (`to` / `cc` / etc.) so log scrapers can grep for
+ * the offending slot without parsing the rest.
+ */
+export declare function assertEnvelopeAddress(addr: unknown, role: string): void;
+/**
+ * Reject subject lines containing CR or LF — they become header
+ * fields on the wire, and a newline in the value lets an attacker
+ * inject additional headers (BCC leak, Reply-To override).
+ *
+ * Centralized here so the check applies uniformly across drivers
+ * (stacksjs/stacks#1871 M-6).
+ */
+export declare function assertHeaderSafeSubject(subject: string): void;
+/**
+ * Filter a `message.headers` map down to entries whose value is a
+ * string and whose name/value contain no CR/LF (header injection
+ * vector). Returns undefined when nothing usable remains so caller-
+ * sites can spread the result without sending an empty `headers: {}`
+ * payload field.
+ *
+ * Used by every driver that consumes {@link EmailMessage.headers}
+ * (stacksjs/stacks#1871 M-5). Centralizing the CR/LF guard ensures
+ * the SES `Headers` slot, the SendGrid `headers` field, and the
+ * Mailtrap `headers` map all reject the same injection-shaped values.
+ */
+export declare function filterStringHeaders(headers: Record<string, string> | undefined): Record<string, string> | undefined;
+/**
+ * Email validation primitives shared by every driver + the base
+ * driver class. Pulled into a module so the `ENVELOPE_ADDRESS` regex
+ * lives in exactly one place — the audit (stacksjs/stacks#1871 M-6)
+ * called out a copy in `drivers/base.ts` and a copy in `drivers/smtp.ts`,
+ * and they were already starting to drift.
+ */
+/**
+ * RFC 5321-ish envelope-address shape. Intentionally tighter than the
+ * full RFC because the broader form (display names, comments, source
+ * routes) has no business in the envelope slots that hit the wire as
+ * raw header values: `to` / `cc` / `bcc` / `from` / `replyTo`.
+ *
+ * Rejects:
+ *   - whitespace, including CR / LF / tab (header-injection vectors)
+ *   - angle brackets / quotes / backslashes (header parser confusion)
+ *
+ * Requires a single `@` separating local part and domain.
+ */
+export declare const ENVELOPE_ADDRESS: unknown;

package/dist/validation.js

@@ -0,0 +1,22 @@
+export const ENVELOPE_ADDRESS = /^[^\s<>"\\\r\n\t]+@[^\s<>"\\\r\n\t]+$/;
+export function assertEnvelopeAddress(addr, role) {
+  if (typeof addr !== "string" || !ENVELOPE_ADDRESS.test(addr))
+    throw Error(`Email ${role} address is malformed or contains forbidden characters: ${JSON.stringify(addr)}`);
+}
+export function assertHeaderSafeSubject(subject) {
+  if (/[\r\n]/.test(subject))
+    throw Error("Email subject contains forbidden line break characters (CR/LF)");
+}
+export function filterStringHeaders(headers) {
+  if (!headers)
+    return;
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (typeof v !== "string")
+      continue;
+    if (/[\r\n]/.test(k) || /[\r\n]/.test(v))
+      continue;
+    out[k] = v;
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}

package/dist/webhook-dedup.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Record an event-id as processed. Returns `true` if this is the
+ * first time we've seen the id (caller should process), `false`
+ * if it's a duplicate (caller should ack-and-skip).
+ *
+ * When the table doesn't exist, falls through to "always first" +
+ * warn-once — apps without the migration still work; they just
+ * double-process if the provider retries.
+ */
+export declare function recordWebhookEventOrSkip(provider: 'mailgun' | 'postmark' | 'ses' | 'sendgrid', eventId: string): Promise<boolean>;

package/dist/webhook-dedup.js

@@ -0,0 +1,33 @@
+import { db } from "@stacksjs/database";
+let warnedAboutMissingTable = !1;
+function warnOnceAboutMissingTable() {
+  if (warnedAboutMissingTable)
+    return;
+  warnedAboutMissingTable = !0;
+  console.warn("[email/webhook-dedup] email_webhook_events table missing \u2014 webhook idempotency NOT enforced. " + "Providers may double-deliver retries; run migrations to enable dedup.");
+}
+function isMissingTableError(err) {
+  const msg = err?.message ?? "";
+  return msg.includes("no such table") || msg.includes("doesn't exist");
+}
+export async function recordWebhookEventOrSkip(provider, eventId) {
+  if (!eventId)
+    return !0;
+  try {
+    await db.insertInto("email_webhook_events").values({
+      provider,
+      event_id: eventId,
+      processed_at: new Date().toISOString().slice(0, 19).replace("T", " ")
+    }).execute();
+    return !0;
+  } catch (err) {
+    if (isMissingTableError(err)) {
+      warnOnceAboutMissingTable();
+      return !0;
+    }
+    const msg = err?.message ?? "";
+    if (msg.includes("UNIQUE constraint") || msg.includes("Duplicate entry"))
+      return !1;
+    throw err;
+  }
+}

package/dist/webhook-events.d.ts

@@ -0,0 +1,34 @@
+import type { SuppressionType } from './suppression';
+/** Fired when a provider reports a hard bounce. */
+export declare function emitEmailBounceHard(payload: EmailEventPayload): Promise<void>;
+/** Fired when a provider reports a soft bounce (transient). */
+export declare function emitEmailBounceSoft(payload: EmailEventPayload): Promise<void>;
+/** Fired when a provider reports a complaint (user marked spam). */
+export declare function emitEmailComplaint(payload: EmailEventPayload): Promise<void>;
+/**
+ * Fired when the user clicks the framework's signed unsubscribe URL
+ * AND when a provider's "unsubscribed" webhook event arrives. Both
+ * sources land in the same listener so apps only have to wire up
+ * one code path.
+ */
+export declare function emitEmailUnsubscribe(payload: EmailEventPayload): Promise<void>;
+/**
+ * Map a classified event to the suppression type that should be
+ * recorded. Soft bounces are intentionally NOT auto-suppressed —
+ * they're transient and the next send is likely to succeed.
+ */
+export declare function suppressionTypeFor(classification: EmailEventClassification): SuppressionType | null;
+/**
+ * Payload shape every email-event listener receives. Always
+ * includes the recipient + provider + the provider's raw event
+ * payload so listeners can branch on provider-specific fields
+ * without re-parsing.
+ */
+export declare interface EmailEventPayload {
+  email: string
+  provider: 'mailgun' | 'postmark' | 'ses' | 'sendgrid'
+  reason?: string
+  raw: unknown
+}
+export type EmailBounceType = 'hard' | 'soft';
+export type EmailEventClassification = 'bounce-hard' | 'bounce-soft' | 'complaint' | 'unsubscribe' | 'delivered';

package/dist/webhook-events.js

@@ -0,0 +1,37 @@
+async function emit(event, payload) {
+  try {
+    const mod = await import("@stacksjs/events").catch(() => null);
+    if (!mod)
+      return;
+    const dispatch = mod.dispatch;
+    if (typeof dispatch !== "function")
+      return;
+    dispatch(event, payload);
+  } catch {}
+}
+export async function emitEmailBounceHard(payload) {
+  await emit("email:bounce-hard", payload);
+  await emit("email:bounce", payload);
+}
+export async function emitEmailBounceSoft(payload) {
+  await emit("email:bounce-soft", payload);
+  await emit("email:bounce", payload);
+}
+export async function emitEmailComplaint(payload) {
+  await emit("email:complaint", payload);
+}
+export async function emitEmailUnsubscribe(payload) {
+  await emit("email:unsubscribe", payload);
+}
+export function suppressionTypeFor(classification) {
+  switch (classification) {
+    case "bounce-hard":
+      return "bounce";
+    case "complaint":
+      return "complaint";
+    case "unsubscribe":
+      return "unsubscribe";
+    default:
+      return null;
+  }
+}

package/dist/webhook-handlers.d.ts

@@ -0,0 +1,27 @@
+import type { EmailEventClassification } from './webhook-events';
+export declare function handleMailgunWebhook(rawBody: string, config: MailgunWebhookConfig): Promise<WebhookResult>;
+export declare function handlePostmarkWebhook(rawBody: string, authorizationHeader: string | null, sourceIp: string | undefined, config: PostmarkWebhookConfig): Promise<WebhookResult>;
+export declare function handleSesWebhook(rawBody: string, config?: SesWebhookConfig): Promise<WebhookResult>;
+export declare function handleSendgridWebhook(rawBody: string, signatureHeader: string | null, timestampHeader: string | null, config: SendgridWebhookConfig): Promise<WebhookResult>;
+export declare interface WebhookResult {
+  status: number
+  body: { ok: boolean, reason?: string, processed?: boolean, classification?: EmailEventClassification }
+}
+export declare interface MailgunWebhookConfig {
+  signingKey: string
+  toleranceSeconds?: number
+}
+export declare interface PostmarkWebhookConfig {
+  username: string
+  password: string
+  ipAllowlist?: ReadonlyArray<string>
+}
+export declare interface SesWebhookConfig {
+  certUrlHostAllowlist?: RegExp
+  fetchCert?: (url: string) => Promise<string>
+  autoConfirmSubscriptions?: boolean
+}
+export declare interface SendgridWebhookConfig {
+  publicKeyPem: string
+  toleranceSeconds?: number
+}