@stacksjs/email 0.70.88 → 0.70.91

package/dist/sdk/index.d.ts

@@ -0,0 +1,81 @@
+// Export singleton instance
+export declare const emailSDK: EmailSDK;
+// Export convenience functions
+export declare const sendEmail: (message: EmailMessage) => unknown;
+export declare const getInbox: (mailbox: string, options?: { limit?: number; offset?: number }) => unknown;
+export declare const searchEmails: (mailbox: string, options: EmailSearchOptions) => unknown;
+export declare const deleteEmail: (mailbox: string, messageId: string) => unknown;
+export declare interface EmailAddress {
+  name?: string
+  address: string
+}
+export declare interface EmailMessage {
+  from?: EmailAddress | string
+  to: string | string[] | EmailAddress[]
+  cc?: string | string[] | EmailAddress[]
+  bcc?: string | string[] | EmailAddress[]
+  replyTo?: string | EmailAddress
+  subject: string
+  text?: string
+  html?: string
+  attachments?: EmailAttachment[]
+}
+export declare interface EmailAttachment {
+  filename: string
+  content: string | Buffer
+  contentType?: string
+  encoding?: 'base64' | 'binary'
+}
+export declare interface InboxEmail {
+  messageId: string
+  from: string
+  fromName?: string
+  to: string
+  subject: string
+  date: string
+  read: boolean
+  preview?: string
+  hasAttachments?: boolean
+  path: string
+}
+export declare interface EmailSearchOptions {
+  from?: string
+  to?: string
+  subject?: string
+  after?: Date
+  before?: Date
+  hasAttachments?: boolean
+  limit?: number
+  offset?: number
+}
+export declare interface SendResult {
+  success: boolean
+  messageId?: string
+  error?: string
+}
+/**
+ * Email SDK class for Stacks applications
+ */
+export declare class EmailSDK {
+  constructor(options?: { bucket?: string; region?: string; domain?: string });
+  send(message: EmailMessage): Promise<SendResult>;
+  sendTemplate(options: {
+    to: string | string[]
+    template: string
+    data: Record<string, any>
+    from?: EmailAddress | string
+    subject?: string
+  }): Promise<SendResult>;
+  getInbox(mailbox: string, options?: { limit?: number; offset?: number }): Promise<InboxEmail[]>;
+  getEmail(mailbox: string, messageId: string): Promise<{
+    metadata: Record<string, any>
+    html?: string
+    text?: string
+    raw?: string
+  } | null>;
+  search(mailbox: string, options: EmailSearchOptions): Promise<InboxEmail[]>;
+  delete(mailbox: string, messageId: string): Promise<boolean>;
+  markAsRead(mailbox: string, messageId: string): Promise<boolean>;
+  markAsUnread(mailbox: string, messageId: string): Promise<boolean>;
+}
+export default EmailSDK;

package/dist/sdk/index.js

@@ -0,0 +1,219 @@
+import { email as emailConfig } from "@stacksjs/config";
+import { getErrorMessage } from "@stacksjs/utils";
+
+export class EmailSDK {
+  bucket;
+  region;
+  domain;
+  constructor(options) {
+    this.bucket = options?.bucket || `${process.env.APP_NAME?.toLowerCase() || "stacks"}-emails`;
+    this.region = options?.region || process.env.AWS_REGION || "us-east-1";
+    const fromAddress = emailConfig?.from?.address, parsedDomain = fromAddress?.includes("@") ? fromAddress.split("@")[1] : void 0;
+    this.domain = options?.domain || parsedDomain || "stacksjs.com";
+  }
+  async send(message) {
+    try {
+      const { SESClient } = await import("@stacksjs/ts-cloud"), ses = new SESClient(this.region), from = this.normalizeAddress(message.from || emailConfig?.from || { address: `noreply@${this.domain}` }), toAddresses = this.normalizeAddresses(message.to), ccAddresses = message.cc ? this.normalizeAddresses(message.cc) : void 0, bccAddresses = message.bcc ? this.normalizeAddresses(message.bcc) : void 0;
+      return {
+        success: !0,
+        messageId: (await ses.sendEmail({
+          FromEmailAddress: typeof from === "string" ? from : `${from.name} <${from.address}>`,
+          Destination: {
+            ToAddresses: toAddresses,
+            CcAddresses: ccAddresses,
+            BccAddresses: bccAddresses
+          },
+          ReplyToAddresses: message.replyTo ? [typeof message.replyTo === "string" ? message.replyTo : message.replyTo.address] : void 0,
+          Content: {
+            Simple: {
+              Subject: {
+                Data: message.subject,
+                Charset: "UTF-8"
+              },
+              Body: {
+                ...message.html && {
+                  Html: {
+                    Data: message.html,
+                    Charset: "UTF-8"
+                  }
+                },
+                ...message.text && {
+                  Text: {
+                    Data: message.text,
+                    Charset: "UTF-8"
+                  }
+                }
+              }
+            }
+          }
+        })).MessageId
+      };
+    } catch (error) {
+      return {
+        success: !1,
+        error: getErrorMessage(error)
+      };
+    }
+  }
+  async sendTemplate(options) {
+    const html = this.renderTemplate(options.template, options.data), subject = options.subject || options.template;
+    return this.send({
+      to: options.to,
+      from: options.from,
+      subject,
+      html
+    });
+  }
+  async getInbox(mailbox, options) {
+    try {
+      const { S3Client } = await import("@stacksjs/ts-cloud"), s3 = new S3Client(this.region), [localPart, domain] = mailbox.includes("@") ? mailbox.split("@") : [mailbox, this.domain], indexKey = `mailboxes/${domain}/${localPart}/inbox.json`, result = await s3.getObject(this.bucket, indexKey);
+      if (!result)
+        return [];
+      let inbox = JSON.parse(result);
+      const offset = options?.offset || 0, limit = options?.limit || 50;
+      return inbox.slice(offset, offset + limit);
+    } catch (error) {
+      if (getErrorMessage(error).includes("NoSuchKey") || getErrorMessage(error).includes("404"))
+        return [];
+      throw error;
+    }
+  }
+  async getEmail(mailbox, messageId) {
+    try {
+      const { S3Client } = await import("@stacksjs/ts-cloud"), s3 = new S3Client(this.region), [localPart, domain] = mailbox.includes("@") ? mailbox.split("@") : [mailbox, this.domain], email = (await this.getInbox(mailbox, { limit: 1000 })).find((e) => e.messageId === messageId);
+      if (!email)
+        return null;
+      const basePath = email.path, metaResult = await s3.getObject(this.bucket, `${basePath}/metadata.json`);
+      let metadata = {};
+      if (metaResult)
+        try {
+          metadata = JSON.parse(metaResult);
+        } catch (parseError) {
+          console.debug(`[email-sdk] Failed to parse email metadata: ${parseError.message}`);
+        }
+      let html;
+      try {
+        html = await s3.getObject(this.bucket, `${basePath}/body.html`) || void 0;
+      } catch (error) {
+        if (!getErrorMessage(error)?.includes("NoSuchKey") && !getErrorMessage(error)?.includes("404"))
+          console.debug(`[email-sdk] Failed to fetch HTML body: ${getErrorMessage(error)}`);
+      }
+      let text;
+      try {
+        text = await s3.getObject(this.bucket, `${basePath}/body.txt`) || void 0;
+      } catch (error) {
+        if (!getErrorMessage(error)?.includes("NoSuchKey") && !getErrorMessage(error)?.includes("404"))
+          console.debug(`[email-sdk] Failed to fetch text body: ${getErrorMessage(error)}`);
+      }
+      return { metadata, html, text };
+    } catch (error) {
+      if (getErrorMessage(error).includes("NoSuchKey") || getErrorMessage(error).includes("404"))
+        return null;
+      throw error;
+    }
+  }
+  async search(mailbox, options) {
+    let results = await this.getInbox(mailbox, { limit: 1000 });
+    if (options.from) {
+      const fromLower = options.from.toLowerCase();
+      results = results.filter((e) => e.from.toLowerCase().includes(fromLower));
+    }
+    if (options.subject) {
+      const subjectLower = options.subject.toLowerCase();
+      results = results.filter((e) => e.subject.toLowerCase().includes(subjectLower));
+    }
+    if (options.after)
+      results = results.filter((e) => new Date(e.date) >= options.after);
+    if (options.before)
+      results = results.filter((e) => new Date(e.date) <= options.before);
+    if (options.hasAttachments !== void 0)
+      results = results.filter((e) => e.hasAttachments === options.hasAttachments);
+    const offset = options.offset || 0, limit = options.limit || 50;
+    return results.slice(offset, offset + limit);
+  }
+  async delete(mailbox, messageId) {
+    try {
+      const { S3Client } = await import("@stacksjs/ts-cloud"), s3 = new S3Client(this.region), [localPart, domain] = mailbox.includes("@") ? mailbox.split("@") : [mailbox, this.domain], inbox = await this.getInbox(mailbox, { limit: 1000 }), emailIndex = inbox.findIndex((e) => e.messageId === messageId);
+      if (emailIndex === -1)
+        return !1;
+      const email = inbox[emailIndex];
+      if (!email)
+        return !1;
+      const basePath = email.path, keysToDelete = [
+        `${basePath}/metadata.json`,
+        `${basePath}/raw.eml`,
+        `${basePath}/body.html`,
+        `${basePath}/body.txt`,
+        `${basePath}/preview.txt`
+      ];
+      for (const key of keysToDelete)
+        try {
+          await s3.deleteObject(this.bucket, key);
+        } catch (error) {
+          if (!getErrorMessage(error)?.includes("NoSuchKey") && !getErrorMessage(error)?.includes("404"))
+            console.debug(`[email-sdk] Failed to delete ${key}: ${getErrorMessage(error)}`);
+        }
+      inbox.splice(emailIndex, 1);
+      await s3.putObject({
+        bucket: this.bucket,
+        key: `mailboxes/${domain}/${localPart}/inbox.json`,
+        body: JSON.stringify(inbox, null, 2),
+        contentType: "application/json"
+      });
+      return !0;
+    } catch (error) {
+      console.debug(`[email-sdk] Failed to delete email ${messageId}: ${getErrorMessage(error)}`);
+      return !1;
+    }
+  }
+  async markAsRead(mailbox, messageId) {
+    return this.updateEmailStatus(mailbox, messageId, { read: !0 });
+  }
+  async markAsUnread(mailbox, messageId) {
+    return this.updateEmailStatus(mailbox, messageId, { read: !1 });
+  }
+  async updateEmailStatus(mailbox, messageId, updates) {
+    try {
+      const { S3Client } = await import("@stacksjs/ts-cloud"), s3 = new S3Client(this.region), [localPart, domain] = mailbox.includes("@") ? mailbox.split("@") : [mailbox, this.domain], inbox = await this.getInbox(mailbox, { limit: 1000 }), emailIndex = inbox.findIndex((e) => e.messageId === messageId);
+      if (emailIndex === -1)
+        return !1;
+      Object.assign(inbox[emailIndex], updates);
+      await s3.putObject({
+        bucket: this.bucket,
+        key: `mailboxes/${domain}/${localPart}/inbox.json`,
+        body: JSON.stringify(inbox, null, 2),
+        contentType: "application/json"
+      });
+      return !0;
+    } catch (error) {
+      console.debug(`[email-sdk] Failed to update email status for ${messageId}: ${getErrorMessage(error)}`);
+      return !1;
+    }
+  }
+  normalizeAddress(addr) {
+    if (typeof addr === "string") {
+      const match = addr.match(/^(.+?)\s*<(.+)>$/);
+      if (match)
+        return { name: match[1].trim(), address: match[2].trim() };
+      return { address: addr };
+    }
+    return addr;
+  }
+  normalizeAddresses(addrs) {
+    return (Array.isArray(addrs) ? addrs : [addrs]).map((a) => {
+      if (typeof a === "string")
+        return a;
+      return a.name ? `${a.name} <${a.address}>` : a.address;
+    });
+  }
+  renderTemplate(template, data) {
+    let result = template;
+    for (const [key, value] of Object.entries(data)) {
+      const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      result = result.replace(new RegExp(`{{\\s*${escapedKey}\\s*}}`, "g"), String(value));
+    }
+    return result;
+  }
+}
+export const emailSDK = new EmailSDK, sendEmail = (message) => emailSDK.send(message), getInbox = (mailbox, options) => emailSDK.getInbox(mailbox, options), searchEmails = (mailbox, options) => emailSDK.search(mailbox, options), deleteEmail = (mailbox, messageId) => emailSDK.delete(mailbox, messageId);
+export default EmailSDK;

package/dist/send.d.ts

@@ -0,0 +1 @@
+

package/dist/server/converter.d.ts

@@ -0,0 +1 @@
+

package/dist/server/inbound.d.ts

@@ -0,0 +1 @@
+

package/dist/server/outbound.d.ts

@@ -0,0 +1 @@
+

package/dist/suppression.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Does this error mean the backing table simply hasn't been migrated yet?
+ * Exported for direct unit coverage across dialects.
+ *
+ * Each supported database phrases "missing table" differently, and the
+ * suppression layer is fail-open — so a matcher that only knows sqlite/mysql
+ * would let Postgres's wording slip through and hard-fail every send on an
+ * un-migrated Postgres DB (stacksjs/stacks#1976). We scope the Postgres check
+ * to `undefined_table` specifically (SQLSTATE 42P01 / `relation "..." does not
+ * exist`) rather than a bare `does not exist`, so a genuine `column ... does
+ * not exist` schema bug still surfaces instead of being silently swallowed.
+ */
+export declare function isMissingTableError(err: unknown): boolean;
+/**
+ * Is the address suppressed? Pass a specific `type` to check only
+ * one kind (e.g. unsubscribe-only — bounces from the same address
+ * don't count). Omit to match any suppression.
+ *
+ * Returns `false` when the table doesn't exist yet — apps that
+ * haven't run the migration aren't broken by the new behavior, and
+ * a one-shot warn lets the operator know the table is missing.
+ */
+export declare function isSuppressed(email: string, type?: SuppressionType): Promise<boolean>;
+/**
+ * Look up the full suppression record(s) for an address — useful
+ * for admin tools that want to show the reason/timestamp alongside
+ * the suppression status. Returns an empty array on missing-table
+ * (same warn-once degrade).
+ */
+export declare function getSuppressions(email: string): Promise<SuppressionRecord[]>;
+/**
+ * Record a suppression. Idempotent — a duplicate (email, type)
+ * pair silently no-ops (the unique constraint catches it).
+ *
+ * Called by:
+ *   - the framework's bounce/complaint webhook handlers (#1881)
+ *   - the unsubscribe route handler (this PR)
+ *   - admin tooling (`SuppressionType: 'manual'`)
+ */
+export declare function suppress(email: string, type: SuppressionType, reason?: string): Promise<void>;
+/**
+ * Remove a suppression record (admin recovery, user-initiated
+ * resubscribe). Idempotent — removing something that isn't there
+ * is a no-op.
+ */
+export declare function unsuppress(email: string, type: SuppressionType): Promise<void>;
+export declare function getSuppressionPolicy(): Promise<SuppressionPolicy>;
+/**
+ * Decide whether a `mail.send()` should proceed for a given
+ * recipient. Returns `null` to indicate "allowed"; otherwise
+ * returns the matched suppression type so the caller can surface
+ * it in the error message.
+ *
+ * Called from `Mail.send()` after idempotency lookup, before the
+ * driver dispatch.
+ */
+export declare function checkSuppressionFor(email: string, tag: 'transactional' | 'broadcast' | undefined): Promise<SuppressionType | null>;
+export declare interface SuppressionRecord {
+  email: string
+  type: SuppressionType
+  reason: string | null
+  created_at: string
+}
+export type SuppressionType = 'bounce' | 'complaint' | 'unsubscribe' | 'manual';
+/**
+ * Suppression-policy resolution for `mail.send()` (stacksjs/stacks#1880).
+ *
+ * Reads the policy from `config.email.suppressionPolicy` with a
+ * sensible default and decides whether the message should be
+ * allowed through given its tag.
+ *
+ * Policy semantics:
+ *   - `'strict'`                  — block all sends to suppressed addresses
+ *   - `'transactional-allowed'`   — block broadcasts; allow `tag: 'transactional'`
+ *   - `'off'`                     — never block (table is only used for tracking)
+ *
+ * Default is `'strict'` — the safest behavior for compliance, and
+ * apps that don't run the migration are unaffected because the
+ * lookup falls through to "not suppressed" when the table is
+ * missing.
+ */
+export type SuppressionPolicy = 'strict' | 'transactional-allowed' | 'off';

package/dist/suppression.js

@@ -0,0 +1,104 @@
+import { db } from "@stacksjs/database";
+let warnedAboutMissingTable = !1;
+function warnOnceAboutMissingTable() {
+  if (warnedAboutMissingTable)
+    return;
+  warnedAboutMissingTable = !0;
+  console.warn("[email/suppression] email_suppressions table missing \u2014 suppression checks accepted but NOT enforced. " + "Run migrations to enable enforcement.");
+}
+export function isMissingTableError(err) {
+  const e = err, msg = e?.message ?? "";
+  return e?.code === "42P01" || msg.includes("no such table") || msg.includes("doesn't exist") || /relation "[^"]*" does not exist/i.test(msg);
+}
+function isSuppressionStoreUnavailable(err) {
+  if (isMissingTableError(err))
+    return !0;
+  const msg = (err?.message ?? "").toLowerCase();
+  return 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");
+}
+function canonicalize(email) {
+  return String(email).trim().toLowerCase();
+}
+export async function isSuppressed(email, type) {
+  const canon = canonicalize(email);
+  try {
+    let query = db.selectFrom("email_suppressions").where("email", "=", canon).select(["email"]);
+    if (type)
+      query = query.where("type", "=", type);
+    const row = await query.executeTakeFirst();
+    return Boolean(row);
+  } catch (err) {
+    if (isSuppressionStoreUnavailable(err)) {
+      warnOnceAboutMissingTable();
+      return !1;
+    }
+    throw err;
+  }
+}
+export async function getSuppressions(email) {
+  const canon = canonicalize(email);
+  try {
+    return await db.selectFrom("email_suppressions").where("email", "=", canon).selectAll().execute() ?? [];
+  } catch (err) {
+    if (isSuppressionStoreUnavailable(err)) {
+      warnOnceAboutMissingTable();
+      return [];
+    }
+    throw err;
+  }
+}
+export async function suppress(email, type, reason) {
+  const canon = canonicalize(email), createdAt = new Date().toISOString().slice(0, 19).replace("T", " ");
+  try {
+    await db.insertInto("email_suppressions").values({
+      email: canon,
+      type,
+      reason: reason ?? null,
+      created_at: createdAt
+    }).execute();
+  } catch (err) {
+    if (isSuppressionStoreUnavailable(err)) {
+      warnOnceAboutMissingTable();
+      return;
+    }
+    const msg = err?.message ?? "";
+    if (msg.includes("UNIQUE constraint") || msg.includes("Duplicate entry"))
+      return;
+    throw err;
+  }
+}
+export async function unsuppress(email, type) {
+  const canon = canonicalize(email);
+  try {
+    await db.deleteFrom("email_suppressions").where("email", "=", canon).where("type", "=", type).execute();
+  } catch (err) {
+    if (isSuppressionStoreUnavailable(err)) {
+      warnOnceAboutMissingTable();
+      return;
+    }
+    throw err;
+  }
+}
+export async function getSuppressionPolicy() {
+  try {
+    const { config } = await import("@stacksjs/config"), policy = config?.email?.suppressionPolicy;
+    if (policy === "strict" || policy === "transactional-allowed" || policy === "off")
+      return policy;
+  } catch {}
+  return "strict";
+}
+export async function checkSuppressionFor(email, tag) {
+  const policy = await getSuppressionPolicy();
+  if (policy === "off")
+    return null;
+  if (policy === "transactional-allowed" && tag === "transactional")
+    return null;
+  const suppressions = await getSuppressions(email);
+  if (suppressions.length === 0)
+    return null;
+  const priority = ["unsubscribe", "complaint", "bounce", "manual"];
+  for (const p of priority)
+    if (suppressions.some((s) => s.type === p))
+      return p;
+  return suppressions[0].type;
+}

package/dist/template.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Mark a string as pre-rendered HTML so {@link replaceVariables} splices
+ * it in verbatim instead of escaping. Use ONLY for content that you
+ * authored (or that came from a trusted renderer like the framework's
+ * own layout-slot resolution) — never for user input.
+ *
+ * @example
+ * ```ts
+ * mail.send({
+ *   template: 'invoice',
+ *   variables: {
+ *     // User-supplied — escaped automatically (good)
+ *     userName: req.input('name'),
+ *     // Pre-rendered HTML you built yourself — opt out of escaping
+ *     invoiceTable: safe(renderInvoiceTable(rows)),
+ *   },
+ * })
+ * ```
+ */
+export declare function safe(html: string): SafeHtml;
+/**
+ * Render an email template with optional layout
+ *
+ * Supports both .stx and .html templates. When a .stx template
+ * is found, it uses the STX engine for rendering (with directives,
+ * server scripts, etc.). When an .html template is found, it uses
+ * simple {{ variable }} replacement with layout wrapping.
+ *
+ * Templates resolve from userland `resources/emails/` first, then
+ * fall back to the framework-shipped defaults in
+ * `storage/framework/defaults/resources/emails/` — so the prebaked
+ * mailers (password-reset, password-changed, email-verification)
+ * work out of the box on a default install while any userland file
+ * with the same name always wins (stacksjs/stacks#1944).
+ *
+ * Within each directory, .stx templates are preferred over .html
+ * when both exist.
+ *
+ * @example
+ * ```typescript
+ * // STX template (resources/emails/welcome.stx)
+ * const { html, text } = await template('welcome', {
+ *   variables: { userName: 'John' }
+ * })
+ *
+ * // HTML template with layout
+ * const { html, text } = await template('notification', {
+ *   layout: 'base',
+ *   variables: { message: 'Hello' }
+ * })
+ *
+ * // Without layout (HTML templates only)
+ * const { html, text } = await template('simple', {
+ *   layout: false
+ * })
+ * ```
+ */
+export declare function template(templateName: string, options?: TemplateOptions): Promise<TemplateResult>;
+/**
+ * Render a raw HTML string with variables (no file loading)
+ */
+export declare function renderHtml(htmlContent: string, variables?: TemplateVariables): TemplateResult;
+/**
+ * Check if a template exists (.stx or .html)
+ */
+export declare function templateExists(templateName: string): boolean;
+/**
+ * List available templates (.stx and .html)
+ */
+export declare function listTemplates(): string[];
+export declare interface TemplateResult {
+  html: string
+  text: string
+}
+export declare interface TemplateOptions {
+  variables?: TemplateVariables
+  layout?: string | false
+  subject?: string
+  inline?: boolean
+}
+/** Allowed types for email template variable values */
+export type TemplateVariableValue = string | number | boolean | undefined | null | SafeHtml;
+/** Map of variable names to their values for template replacement */
+export type TemplateVariables = Record<string, TemplateVariableValue>;
+/**
+ * Marker wrapper for variable values that contain pre-rendered HTML and
+ * should NOT be escaped during {@link replaceVariables}. Constructed via
+ * the {@link safe} helper.
+ *
+ * Anything that isn't a `SafeHtml` instance (or `safe`-marked) is treated
+ * as untrusted text and runs through HTML escaping — this is the M-1
+ * fix for stacksjs/stacks#1871 (template XSS via unescaped variable
+ * interpolation).
+ */
+export declare class SafeHtml {
+  readonly __safeHtml: true;
+  public readonly value: string;
+  constructor(value: string);
+}