@stacksjs/email 0.70.88 → 0.70.91

package/dist/drivers/mailgun.js

@@ -0,0 +1,127 @@
+import { Buffer } from "node:buffer";
+import { config } from "@stacksjs/config";
+import { log } from "@stacksjs/logging";
+import { template } from "../template";
+import { BaseEmailDriver } from "./base";
+
+export class MailgunDriver extends BaseEmailDriver {
+  name = "mailgun";
+  apiKey = null;
+  domain = null;
+  endpoint = null;
+  getConfig() {
+    if (!this.apiKey || !this.domain || !this.endpoint) {
+      this.apiKey = config.services.mailgun?.apiKey ?? "";
+      this.domain = config.services.mailgun?.domain ?? "";
+      this.endpoint = config.services.mailgun?.endpoint ?? "api.mailgun.net";
+    }
+    return {
+      apiKey: this.apiKey,
+      domain: this.domain,
+      endpoint: this.endpoint
+    };
+  }
+  async send(message, options) {
+    const { domain } = this.getConfig(), logContext = {
+      provider: this.name,
+      to: message.to,
+      subject: message.subject,
+      domain
+    };
+    log.info("Sending email via Mailgun...", 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, formData = new FormData, fromAddress = {
+        address: message.from?.address || config.email.from?.address || "",
+        name: message.from?.name || config.email.from?.name
+      };
+      formData.append("from", this.formatMailgunAddress(fromAddress));
+      this.formatMailgunAddresses(message.to).forEach((to) => formData.append("to", to));
+      if (message.cc)
+        this.formatMailgunAddresses(message.cc).forEach((cc) => formData.append("cc", cc));
+      if (message.bcc)
+        this.formatMailgunAddresses(message.bcc).forEach((bcc) => formData.append("bcc", bcc));
+      formData.append("subject", message.subject);
+      if (message.replyTo) {
+        const formatted = this.formatMailgunAddresses(Array.isArray(message.replyTo) || typeof message.replyTo === "string" ? message.replyTo : [message.replyTo]);
+        if (formatted.length > 0)
+          formData.append("h:Reply-To", formatted.join(", "));
+      }
+      if (message.headers) {
+        for (const [k, v] of Object.entries(message.headers))
+          if (typeof v === "string")
+            formData.append(`h:${k}`, v);
+      }
+      if (finalHtml)
+        formData.append("html", finalHtml);
+      if (message.text)
+        formData.append("text", message.text);
+      if (message.attachments)
+        message.attachments.forEach((attachment) => {
+          const content = typeof attachment.content === "string" ? attachment.content : this.arrayBufferToBase64(attachment.content);
+          formData.append("attachment", new Blob([content], { type: attachment.contentType }), attachment.filename);
+        });
+      const response = await this.sendWithRetry(formData);
+      return this.handleSuccess(message, response.id);
+    } catch (error) {
+      return this.handleError(error, message);
+    }
+  }
+  formatMailgunAddress(address) {
+    return address.name ? `${address.name} <${address.address}>` : address.address;
+  }
+  formatMailgunAddresses(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}>`;
+    });
+  }
+  arrayBufferToBase64(buffer) {
+    let binary = "";
+    const bytes = new Uint8Array(buffer), len = bytes.byteLength;
+    for (let i = 0;i < len; i++)
+      binary += String.fromCharCode(bytes[i] ?? 0);
+    return typeof btoa === "function" ? btoa(binary) : Buffer.from(binary).toString("base64");
+  }
+  async sendWithRetry(formData, attempt = 1) {
+    const { apiKey, domain, endpoint } = this.getConfig(), url = `https://${endpoint}/v3/${domain}/messages`, auth = Buffer.from(`api:${apiKey}`).toString("base64");
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Basic ${auth}`
+        },
+        body: formData
+      });
+      if (!response.ok) {
+        const errorData = await response.json();
+        throw Error(`Mailgun API error: ${response.status} - ${JSON.stringify(errorData)}`);
+      }
+      const data = await response.json();
+      log.info(`[${this.name}] Email sent successfully`, { attempt, messageId: data.id });
+      return data;
+    } catch (error) {
+      if (attempt < (config.services.mailgun?.maxRetries ?? 3)) {
+        const retryTimeout = config.services.mailgun?.retryTimeout ?? 1000;
+        log.warn(`[${this.name}] Email send failed, retrying (${attempt}/${config.services.mailgun?.maxRetries ?? 3})`);
+        await new Promise((resolve) => setTimeout(resolve, retryTimeout));
+        return this.sendWithRetry(formData, attempt + 1);
+      }
+      throw error;
+    }
+  }
+}
+export default MailgunDriver;

package/dist/drivers/mailtrap.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 MailtrapDriver extends BaseEmailDriver {
+  name: string;
+  send(message: EmailMessage, options?: TemplateOptions): Promise<EmailResult>;
+}
+export default MailtrapDriver;

package/dist/drivers/mailtrap.js

@@ -0,0 +1,129 @@
+import { Buffer } from "node:buffer";
+import { config } from "@stacksjs/config";
+import { log } from "@stacksjs/logging";
+import { template } from "../template";
+import { filterStringHeaders } from "../validation";
+import { BaseEmailDriver } from "./base";
+
+export class MailtrapDriver extends BaseEmailDriver {
+  name = "mailtrap";
+  host = null;
+  token = null;
+  inboxId = null;
+  getConfig() {
+    if (this.host === null || this.token === null || this.inboxId === null) {
+      this.host = config.services.mailtrap?.host ?? "https://sandbox.api.mailtrap.io/api/send";
+      this.token = config.services.mailtrap?.token ?? "";
+      this.inboxId = config.services.mailtrap?.inboxId ? Number(config.services.mailtrap.inboxId) : void 0;
+    }
+    return {
+      host: this.host,
+      token: this.token,
+      inboxId: this.inboxId
+    };
+  }
+  async send(message, options) {
+    const { inboxId } = this.getConfig(), logContext = {
+      provider: this.name,
+      to: message.to,
+      subject: message.subject,
+      inboxId
+    };
+    log.info("Sending email via Mailtrap...", logContext);
+    try {
+      this.validateMessage(message);
+      let templ;
+      if (message.template)
+        templ = await template(message.template, options);
+      const htmlContent = templ?.html || message.html, replyTo = this.firstMailtrapAddress(message.replyTo), customHeaders = filterStringHeaders(message.headers), mailtrapPayload = {
+        from: {
+          email: message.from?.address || config.email.from?.address || "",
+          name: message.from?.name || config.email.from?.name
+        },
+        to: this.formatMailtrapAddresses(message.to),
+        ...message.cc && { cc: this.formatMailtrapAddresses(message.cc) },
+        ...message.bcc && { bcc: this.formatMailtrapAddresses(message.bcc) },
+        ...replyTo ? { reply_to: replyTo } : {},
+        ...customHeaders ? { headers: customHeaders } : {},
+        subject: message.subject,
+        ...htmlContent && { html: htmlContent },
+        ...message.text && { text: message.text },
+        ...message.attachments && {
+          attachments: message.attachments.map((attachment) => ({
+            filename: attachment.filename,
+            content: typeof attachment.content === "string" ? attachment.content : this.arrayBufferToBase64(attachment.content),
+            type: attachment.contentType || "application/octet-stream"
+          }))
+        }
+      }, response = await this.sendWithRetry(mailtrapPayload);
+      return this.handleSuccess(message, response.message_ids?.[0]);
+    } catch (error) {
+      return this.handleError(error, message);
+    }
+  }
+  formatMailtrapAddresses(addresses) {
+    if (!addresses)
+      return [];
+    if (typeof addresses === "string")
+      return [{ email: addresses }];
+    return addresses.map((addr) => {
+      if (typeof addr === "string")
+        return { email: addr };
+      return { email: addr.address, ...addr.name && { name: addr.name } };
+    });
+  }
+  firstMailtrapAddress(value) {
+    if (!value)
+      return;
+    if (typeof value === "string")
+      return { email: value };
+    if (Array.isArray(value)) {
+      const first = value[0];
+      if (first === void 0)
+        return;
+      if (typeof first === "string")
+        return { email: first };
+      return { email: first.address, ...first.name && { name: first.name } };
+    }
+    return { email: value.address, ...value.name && { name: value.name } };
+  }
+  arrayBufferToBase64(buffer) {
+    let binary = "";
+    const bytes = new Uint8Array(buffer), len = bytes.byteLength;
+    for (let i = 0;i < len; i++)
+      binary += String.fromCharCode(bytes[i] ?? 0);
+    return typeof btoa === "function" ? btoa(binary) : Buffer.from(binary).toString("base64");
+  }
+  async sendWithRetry(payload, attempt = 1) {
+    const { host, token, inboxId } = this.getConfig();
+    if (!inboxId)
+      throw Error("Mailtrap inbox ID is required but not provided. Please set MAILTRAP_INBOX_ID in your environment variables.");
+    const endpoint = `${host}/${inboxId}`;
+    try {
+      const response = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(payload)
+      });
+      if (!response.ok) {
+        const errorData = await response.json();
+        throw Error(`Mailtrap API error: ${response.status} - ${JSON.stringify(errorData)}`);
+      }
+      const data = await response.json();
+      log.info(`[${this.name}] Email sent successfully`, { attempt, messageId: data.message_ids?.[0] });
+      return data;
+    } catch (error) {
+      if (attempt < (config.services.mailtrap?.maxRetries ?? 3)) {
+        const retryTimeout = config.services.mailtrap?.retryTimeout ?? 1000;
+        log.warn(`[${this.name}] Email send failed, retrying (${attempt}/${config.services.mailtrap?.maxRetries ?? 3})`);
+        await new Promise((resolve) => setTimeout(resolve, retryTimeout));
+        return this.sendWithRetry(payload, attempt + 1);
+      }
+      throw error;
+    }
+  }
+}
+export default MailtrapDriver;

package/dist/drivers/sendgrid.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 SendGridDriver extends BaseEmailDriver {
+  name: string;
+  send(message: EmailMessage, options?: TemplateOptions): Promise<EmailResult>;
+}
+export default SendGridDriver;

package/dist/drivers/sendgrid.js

@@ -0,0 +1,136 @@
+import { Buffer } from "node:buffer";
+import { config } from "@stacksjs/config";
+import { log } from "@stacksjs/logging";
+import { template } from "../template";
+import { filterStringHeaders } from "../validation";
+import { BaseEmailDriver } from "./base";
+
+export class SendGridDriver extends BaseEmailDriver {
+  name = "sendgrid";
+  apiKey = null;
+  getApiKey() {
+    if (!this.apiKey)
+      this.apiKey = config.services.sendgrid?.apiKey ?? "";
+    return this.apiKey;
+  }
+  async send(message, options) {
+    const logContext = {
+      provider: this.name,
+      to: message.to,
+      subject: message.subject
+    };
+    log.info("Sending email via SendGrid...", 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, content = [];
+      if (finalHtml)
+        content.push({
+          type: "text/html",
+          value: finalHtml
+        });
+      if (message.text)
+        content.push({
+          type: "text/plain",
+          value: message.text
+        });
+      if (content.length === 0)
+        throw Error("Email must have either HTML or text content");
+      const replyTo = this.firstSendGridAddress(message.replyTo), customHeaders = filterStringHeaders(message.headers), sendgridPayload = {
+        personalizations: [
+          {
+            to: this.formatSendGridAddresses(message.to),
+            ...message.cc && { cc: this.formatSendGridAddresses(message.cc) },
+            ...message.bcc && { bcc: this.formatSendGridAddresses(message.bcc) },
+            subject: message.subject
+          }
+        ],
+        from: {
+          email: message.from?.address || config.email.from?.address || "",
+          name: message.from?.name || config.email.from?.name
+        },
+        ...replyTo ? { reply_to: replyTo } : {},
+        ...customHeaders ? { headers: customHeaders } : {},
+        content,
+        ...message.attachments && {
+          attachments: message.attachments.map((attachment) => ({
+            filename: attachment.filename,
+            content: typeof attachment.content === "string" ? attachment.content : this.arrayBufferToBase64(attachment.content),
+            type: attachment.contentType,
+            disposition: "attachment"
+          }))
+        }
+      }, response = await this.sendWithRetry(sendgridPayload);
+      return this.handleSuccess(message, response.headers?.get("x-message-id") ?? void 0);
+    } catch (error) {
+      return this.handleError(error, message);
+    }
+  }
+  formatSendGridAddresses(addresses) {
+    if (!addresses)
+      return [];
+    if (typeof addresses === "string")
+      return [{ email: addresses }];
+    return addresses.map((addr) => {
+      if (typeof addr === "string")
+        return { email: addr };
+      return { email: addr.address, ...addr.name && { name: addr.name } };
+    });
+  }
+  firstSendGridAddress(value) {
+    if (!value)
+      return;
+    if (typeof value === "string")
+      return { email: value };
+    if (Array.isArray(value)) {
+      const first = value[0];
+      if (first === void 0)
+        return;
+      if (typeof first === "string")
+        return { email: first };
+      return { email: first.address, ...first.name && { name: first.name } };
+    }
+    return { email: value.address, ...value.name && { name: value.name } };
+  }
+  arrayBufferToBase64(buffer) {
+    let binary = "";
+    const bytes = new Uint8Array(buffer), len = bytes.byteLength;
+    for (let i = 0;i < len; i++)
+      binary += String.fromCharCode(bytes[i] ?? 0);
+    return typeof btoa === "function" ? btoa(binary) : Buffer.from(binary).toString("base64");
+  }
+  async sendWithRetry(payload, attempt = 1) {
+    try {
+      const response = await fetch("https://api.sendgrid.com/v3/mail/send", {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.getApiKey()}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(payload)
+      });
+      if (!response.ok) {
+        const errorData = await response.json(), err = Error(`SendGrid API error: ${response.status} - ${JSON.stringify(errorData)}`);
+        err.status = response.status;
+        throw err;
+      }
+      log.info(`[${this.name}] Email sent successfully`, { attempt });
+      return response;
+    } catch (error) {
+      const status = error?.status;
+      if (!(typeof status === "number" && status >= 400 && status < 500 && status !== 429) && attempt < (config.services.sendgrid?.maxRetries ?? 3)) {
+        const retryTimeout = config.services.sendgrid?.retryTimeout ?? 1000;
+        log.warn(`[${this.name}] Email send failed, retrying (${attempt}/${config.services.sendgrid?.maxRetries ?? 3})`);
+        await new Promise((resolve) => setTimeout(resolve, retryTimeout));
+        return this.sendWithRetry(payload, attempt + 1);
+      }
+      throw error;
+    }
+  }
+}
+export default SendGridDriver;

package/dist/drivers/ses.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 SESDriver extends BaseEmailDriver {
+  name: string;
+  send(message: EmailMessage, options?: TemplateOptions): Promise<EmailResult>;
+}
+export default SESDriver;

package/dist/drivers/ses.js

@@ -0,0 +1,113 @@
+import { config } from "@stacksjs/config";
+import { SESClient } from "@stacksjs/ts-cloud";
+import { template } from "../template";
+import { buildMimeMessage } from "../mime";
+import { filterStringHeaders } from "../validation";
+import { BaseEmailDriver } from "./base";
+
+export class SESDriver extends BaseEmailDriver {
+  name = "ses";
+  client = null;
+  getClient() {
+    if (!this.client) {
+      const sesConfig = config?.services?.ses, explicit = sesConfig?.credentials, hasExplicit = !!(explicit?.accessKeyId && explicit?.secretAccessKey);
+      this.client = new SESClient(sesConfig?.region || "us-east-1", hasExplicit ? {
+        accessKeyId: explicit.accessKeyId,
+        secretAccessKey: explicit.secretAccessKey,
+        sessionToken: explicit.sessionToken
+      } : void 0);
+    }
+    return this.client;
+  }
+  async send(message, options) {
+    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;
+      if (!finalHtml && !message.text)
+        throw Error("Email must have either HTML or text content");
+      const fromAddress = this.formatSourceAddress({
+        address: message.from?.address || config.email.from?.address || "",
+        name: message.from?.name || config.email.from?.name
+      }), toAddresses = this.formatAddresses(message.to), ccAddresses = this.formatAddresses(message.cc), bccAddresses = this.formatAddresses(message.bcc), replyToAddresses = message.replyTo ? this.formatAddressList(message.replyTo) : [], customHeaders = filterStringHeaders(message.headers);
+      if (!!(message.attachments && message.attachments.length > 0) || !!customHeaders) {
+        const raw = buildMimeMessage({
+          from: fromAddress,
+          to: toAddresses.join(", "),
+          cc: ccAddresses.length > 0 ? ccAddresses.join(", ") : void 0,
+          replyTo: replyToAddresses.length > 0 ? replyToAddresses.join(", ") : void 0,
+          customHeaders,
+          subject: message.subject,
+          text: message.text,
+          html: finalHtml,
+          attachments: message.attachments,
+          messageIdDomain: config.email.domain
+        }), result = await this.getClient().sendRawEmail({
+          source: fromAddress,
+          destinations: [...toAddresses, ...ccAddresses, ...bccAddresses],
+          rawMessage: raw
+        });
+        return this.handleSuccess(message, result.MessageId);
+      }
+      const body = {};
+      if (finalHtml)
+        body.Html = { Charset: config.email.charset || "UTF-8", Data: finalHtml };
+      if (message.text)
+        body.Text = { Charset: config.email.charset || "UTF-8", Data: message.text };
+      const result = await this.getClient().sendEmail({
+        FromEmailAddress: fromAddress,
+        Destination: {
+          ToAddresses: toAddresses,
+          CcAddresses: ccAddresses,
+          BccAddresses: bccAddresses
+        },
+        ...replyToAddresses.length > 0 ? { ReplyToAddresses: replyToAddresses } : {},
+        Content: {
+          Simple: {
+            Subject: {
+              Charset: config.email.charset || "UTF-8",
+              Data: message.subject
+            },
+            Body: body
+          }
+        }
+      });
+      return this.handleSuccess(message, result.MessageId);
+    } catch (error) {
+      return this.handleError(this.enrichSesError(error), message);
+    }
+  }
+  formatSourceAddress(from) {
+    if (!from.name)
+      return from.address;
+    return `${/[",()<>[\]:;@\\]/.test(from.name) ? `"${from.name.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"` : from.name} <${from.address}>`;
+  }
+  enrichSesError(error) {
+    const err = error instanceof Error ? error : Error(String(error)), text = `${err.message} ${err.name ?? ""}`.toLowerCase(), region = config?.services?.ses?.region || "us-east-1";
+    if (text.includes("email address is not verified") || text.includes("not authorized to send") || text.includes("messagerejected") && text.includes("verified")) {
+      err.message = `${err.message}
+
+SES sandbox restriction: the From and (in sandbox) every To address must be verified. Verify identities in the SES console under "Verified identities" (region: ${region}), or request production access to lift the recipient restriction.`;
+      return err;
+    }
+    if (text.includes("signaturedoesnotmatch") || text.includes("invalidclienttokenid") || text.includes("unable to locate credentials") || text.includes("the security token included in the request is invalid")) {
+      err.message = `${err.message}
+
+SES authentication failed. Check AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (or services.ses.credentials), and confirm the IAM principal has \`ses:SendEmail\` permission for the From identity.`;
+      return err;
+    }
+    if (text.includes("could not be reached") || text.includes("econnrefused") || text.includes("enotfound")) {
+      err.message = `${err.message}
+
+SES endpoint unreachable. The configured region (\`${region}\`) must match the region where the From identity is verified.`;
+      return err;
+    }
+    return err;
+  }
+}
+export default SESDriver;

package/dist/drivers/smtp.d.ts

@@ -0,0 +1,14 @@
+import { BaseEmailDriver } from './base';
+import type { EmailAddress, EmailMessage, EmailResult } from '@stacksjs/types';
+import type { TemplateOptions } from '../template';
+/**
+ * SMTP Driver for email sending
+ * Works with any SMTP server: Mailtrap, Mailgun, SendGrid, SES, etc.
+ * Supports STARTTLS (port 587) and direct TLS (port 465)
+ */
+export declare class SMTPDriver extends BaseEmailDriver {
+  name: string;
+  send(message: EmailMessage, options?: TemplateOptions): Promise<EmailResult>;
+  protected formatAddresses(addresses: string | string[] | EmailAddress[] | undefined): string[];
+}
+export default SMTPDriver;