ts-mailkit 0.1.0

package/dist/index.cjs

@@ -0,0 +1,794 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ConfigurationError: () => ConfigurationError,
+  ConsoleEmailSender: () => ConsoleEmailSender,
+  DefaultEmailRenderer: () => DefaultEmailRenderer,
+  EmailService: () => EmailService,
+  EmailTemplateFactory: () => EmailTemplateFactory,
+  MailKit: () => MailKit,
+  MailKitError: () => MailKitError,
+  MemoryEmailSender: () => MemoryEmailSender,
+  TemplateError: () => TemplateError,
+  TransportError: () => TransportError,
+  ZeptoMailSender: () => ZeptoMailSender,
+  buildHtml: () => buildHtml,
+  buildPlainText: () => buildPlainText,
+  createMailKit: () => createMailKit,
+  decodeHtmlEntities: () => decodeHtmlEntities,
+  htmlToPlainText: () => htmlToPlainText,
+  normalizeRecipient: () => normalizeRecipient,
+  normalizeRecipients: () => normalizeRecipients
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/types.ts
+function normalizeRecipient(recipient) {
+  if (typeof recipient === "string") {
+    return { address: recipient.trim() };
+  }
+  if ("email" in recipient) {
+    return {
+      address: (recipient.email ?? "").trim(),
+      name: recipient.name?.trim()
+    };
+  }
+  return {
+    address: (recipient.address ?? "").trim(),
+    name: recipient.name?.trim()
+  };
+}
+function normalizeRecipients(recipients) {
+  if (!recipients) return [];
+  const list = Array.isArray(recipients) ? recipients : [recipients];
+  return list.map(normalizeRecipient).filter((r) => r.address.length > 0);
+}
+
+// src/core/errors.ts
+var MailKitError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MailKitError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ConfigurationError = class extends MailKitError {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigurationError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var TransportError = class extends MailKitError {
+  transportName;
+  statusCode;
+  responseBody;
+  cause;
+  constructor(message, options) {
+    super(message);
+    this.name = "TransportError";
+    this.transportName = options.transportName;
+    this.statusCode = options.statusCode;
+    this.responseBody = options.responseBody;
+    this.cause = options.cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var TemplateError = class extends MailKitError {
+  constructor(message) {
+    super(message);
+    this.name = "TemplateError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/renderers/utils/html-to-plaintext.ts
+function decodeHtmlEntities(text) {
+  return text.replace(/&nbsp;/gi, " ").replace(/&amp;/gi, "&").replace(/&lt;/gi, "<").replace(/&gt;/gi, ">").replace(/&quot;/gi, '"').replace(/&#39;/gi, "'").replace(/&copy;/gi, "\xA9").replace(/&reg;/gi, "\xAE").replace(/&trade;/gi, "\u2122");
+}
+function htmlToPlainText(html) {
+  if (!html) return "";
+  return decodeHtmlEntities(
+    html.replace(/<br\s*\/?>/gi, "\n").replace(/<\/p>/gi, "\n\n").replace(/<\/div>/gi, "\n").replace(/<\/h[1-6]>/gi, "\n\n").replace(/<[^>]*>/g, "")
+  ).replace(/[ \t]+/g, " ").replace(/\n\s*\n\s*\n+/g, "\n\n").trim();
+}
+
+// src/renderers/default/default-renderer.ts
+function buildPlainText(dto) {
+  if (dto.noHtmlMessage) {
+    return dto.noHtmlMessage;
+  }
+  const divider = "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500";
+  const parts = [];
+  if (dto.header) {
+    parts.push(dto.header, divider);
+  }
+  if (dto.body) {
+    parts.push(htmlToPlainText(dto.body));
+  }
+  if (dto.otpCode) {
+    parts.push(`Verification Code: ${dto.otpCode}`);
+  }
+  if (dto.actionText && dto.actionUrl) {
+    parts.push(`${dto.actionText}: ${dto.actionUrl}`);
+  }
+  if (dto.extraMessage) {
+    parts.push(htmlToPlainText(dto.extraMessage));
+  }
+  if (dto.footer) {
+    parts.push(`${divider}
+${htmlToPlainText(dto.footer)}`);
+  }
+  return parts.join("\n\n");
+}
+function buildHtml(dto, options = {}) {
+  const primaryColor = options.primaryColor || "#4f46e5";
+  const fontFamily = options.fontFamily || "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif";
+  const maxWidth = options.maxWidth || "600px";
+  const parts = [
+    `<!DOCTYPE html>`,
+    `<html lang="en">`,
+    `<head>`,
+    `<meta charset="UTF-8">`,
+    `<meta name="viewport" content="width=device-width, initial-scale=1.0">`,
+    `<title>${dto.subject}</title>`,
+    `</head>`,
+    `<body style="margin:0;padding:24px 16px;background-color:#f9fafb;font-family:${fontFamily};color:#1f2937;line-height:1.6;">`,
+    `<div style="max-width:${maxWidth};margin:0 auto;background-color:#ffffff;padding:32px 28px;border-radius:8px;box-shadow:0 1px 3px rgba(0,0,0,0.1);border:1px solid #f3f4f6;">`
+  ];
+  if (dto.imageUrl) {
+    parts.push(
+      `<div style="margin-bottom:24px;text-align:center;">`,
+      `  <img src="${dto.imageUrl}" alt="Header" style="max-width:100%;height:auto;border-radius:6px;" />`,
+      `</div>`
+    );
+  }
+  if (dto.header) {
+    parts.push(
+      `<h2 style="margin:0 0 16px;font-size:1.5rem;font-weight:700;color:#111827;letter-spacing:-0.025em;">${dto.header}</h2>`
+    );
+  }
+  if (dto.body) {
+    parts.push(`<div style="margin:0 0 20px;font-size:1rem;color:#374151;">${dto.body}</div>`);
+  }
+  if (dto.otpCode) {
+    parts.push(
+      `<div style="margin:24px 0;padding:20px;background-color:#f3f4f6;border-radius:8px;text-align:center;">`,
+      `  <span style="font-size:2rem;letter-spacing:0.5rem;font-weight:700;color:#111827;font-family:monospace;">${dto.otpCode}</span>`,
+      `</div>`
+    );
+  }
+  if (dto.actionUrl && dto.actionText) {
+    parts.push(
+      `<div style="margin:24px 0;text-align:center;">`,
+      `  <a href="${dto.actionUrl}" style="display:inline-block;padding:12px 28px;background-color:${primaryColor};color:#ffffff;border-radius:6px;text-decoration:none;font-weight:600;font-size:1rem;text-align:center;box-sizing:border-box;">${dto.actionText}</a>`,
+      `</div>`
+    );
+  }
+  if (dto.extraMessage) {
+    parts.push(
+      `<div style="margin:20px 0 0;font-size:0.875rem;color:#6b7280;line-height:1.5;">${dto.extraMessage}</div>`
+    );
+  }
+  if (dto.footer) {
+    parts.push(
+      `<div style="margin-top:32px;padding-top:20px;border-top:1px solid #e5e7eb;font-size:0.75rem;color:#9ca3af;text-align:center;">${dto.footer}</div>`
+    );
+  }
+  parts.push(`</div>`, `</body>`, `</html>`);
+  return parts.join("\n");
+}
+var DefaultEmailRenderer = class {
+  options;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  render(dto) {
+    return {
+      html: buildHtml(dto, this.options),
+      text: buildPlainText(dto)
+    };
+  }
+};
+
+// src/core/client.ts
+var MailKit = class {
+  transport;
+  renderer;
+  defaultFrom;
+  defaultBrandName;
+  brandNameResolver;
+  constructor(options) {
+    if (!options.transport) {
+      throw new ConfigurationError("MailKit: A transport adapter (IEmailSender) is required.");
+    }
+    this.transport = options.transport;
+    this.renderer = options.renderer ?? new DefaultEmailRenderer();
+    this.defaultFrom = options.defaultFrom;
+    this.defaultBrandName = options.defaultBrandName;
+    this.brandNameResolver = options.brandNameResolver;
+  }
+  /**
+   * Returns the underlying transport instance.
+   */
+  getTransport() {
+    return this.transport;
+  }
+  /**
+   * Renders an email DTO to HTML and plain text without dispatching.
+   */
+  async render(template) {
+    return await this.renderer.render(template);
+  }
+  /**
+   * Returns the plain-text fallback for an email DTO without sending.
+   */
+  buildPlainTextMessage(template) {
+    return template.noHtmlMessage ?? buildPlainText(template);
+  }
+  async send(optionsOrTo, maybeTemplate, maybeToName) {
+    let opts;
+    if (typeof optionsOrTo === "string") {
+      if (!maybeTemplate) {
+        throw new ConfigurationError("MailKit.send: Missing required template DTO argument.");
+      }
+      opts = {
+        to: optionsOrTo,
+        template: maybeTemplate,
+        toName: maybeToName
+      };
+    } else {
+      opts = optionsOrTo;
+    }
+    const template = opts.template;
+    const recipientName = opts.toName ?? template.userName;
+    let resolvedFromName = opts.fromName ?? template.fromName;
+    if (!resolvedFromName && this.brandNameResolver) {
+      resolvedFromName = await this.brandNameResolver();
+    }
+    if (!resolvedFromName) {
+      resolvedFromName = this.defaultBrandName;
+    }
+    const rendered = await this.renderer.render(template);
+    const plaintextBody = template.noHtmlMessage ?? rendered.text;
+    let toRecipients;
+    if (typeof opts.to === "string" && recipientName) {
+      toRecipients = { address: opts.to, name: recipientName };
+    } else {
+      toRecipients = opts.to;
+    }
+    let from = opts.from ?? this.defaultFrom;
+    if (resolvedFromName && from) {
+      const normalizedFrom = normalizeRecipient(from);
+      from = { address: normalizedFrom.address, name: resolvedFromName };
+    }
+    return await this.sendRaw({
+      to: toRecipients,
+      from,
+      subject: template.subject,
+      html: rendered.html,
+      text: plaintextBody,
+      cc: opts.cc,
+      bcc: opts.bcc,
+      replyTo: opts.replyTo,
+      attachments: opts.attachments,
+      headers: opts.headers,
+      tags: opts.tags,
+      metadata: opts.metadata
+    });
+  }
+  /**
+   * Dispatches a raw, pre-rendered email directly through the transport.
+   */
+  async sendRaw(options) {
+    const from = options.from ?? this.defaultFrom;
+    return await this.transport.send({
+      ...options,
+      from
+    });
+  }
+  /**
+   * Sends a raw plain-text email with basic HTML pre-formatting.
+   * Useful for plain notifications, alerts, or simple text messages.
+   */
+  async sendSimpleMessage(to, subject, text, toName = "") {
+    const html = `<pre style="font-family:monospace;white-space:pre-wrap;">${text}</pre>`;
+    return await this.sendRaw({
+      to: { address: to, name: toName },
+      subject,
+      html,
+      text
+    });
+  }
+};
+var EmailService = MailKit;
+function createMailKit(options) {
+  return new MailKit(options);
+}
+
+// src/transports/zeptomail/zeptomail-sender.ts
+var ZeptoMailSender = class {
+  name = "zeptomail";
+  apiUrl;
+  authHeader;
+  defaultFrom;
+  fetchImpl;
+  constructor(config) {
+    if (!config.apiToken || typeof config.apiToken !== "string") {
+      throw new ConfigurationError("ZeptoMailSender: Missing or invalid apiToken.");
+    }
+    if (!config.from) {
+      throw new ConfigurationError("ZeptoMailSender: Missing required default from address.");
+    }
+    const host = (config.apiHost || "api.zeptomail.com").replace(/^https?:\/\//, "").replace(/\/+$/, "");
+    this.apiUrl = `https://${host}/v1.1/email`;
+    const token = config.apiToken.trim();
+    this.authHeader = token.startsWith("Zoho-") ? token : `Zoho-enczapikey ${token}`;
+    this.defaultFrom = normalizeRecipient(config.from);
+    if (!this.defaultFrom.address) {
+      throw new ConfigurationError("ZeptoMailSender: Configured from address must not be empty.");
+    }
+    this.fetchImpl = config.fetch ?? globalThis.fetch;
+    if (typeof this.fetchImpl !== "function") {
+      throw new ConfigurationError(
+        "ZeptoMailSender: No global fetch implementation found. Pass a custom fetch to ZeptoMailConfig if running on Node < 18."
+      );
+    }
+  }
+  /**
+   * Dispatches an email using Zoho ZeptoMail API v1.1.
+   */
+  async send(options) {
+    const toRecipients = normalizeRecipients(options.to);
+    if (toRecipients.length === 0) {
+      throw new TransportError("ZeptoMailSender: At least one recipient (to) must be specified.", {
+        transportName: this.name
+      });
+    }
+    const resolvedFrom = options.from ? normalizeRecipient(options.from) : this.defaultFrom;
+    const payload = {
+      from: {
+        address: resolvedFrom.address,
+        name: resolvedFrom.name
+      },
+      to: toRecipients.map((r) => ({
+        email_address: {
+          address: r.address,
+          name: r.name || ""
+        }
+      })),
+      subject: options.subject,
+      htmlbody: options.html,
+      textbody: options.text
+    };
+    if (options.cc) {
+      const ccList = normalizeRecipients(options.cc);
+      if (ccList.length > 0) {
+        payload.cc = ccList.map((r) => ({
+          email_address: { address: r.address, name: r.name || "" }
+        }));
+      }
+    }
+    if (options.bcc) {
+      const bccList = normalizeRecipients(options.bcc);
+      if (bccList.length > 0) {
+        payload.bcc = bccList.map((r) => ({
+          email_address: { address: r.address, name: r.name || "" }
+        }));
+      }
+    }
+    if (options.replyTo) {
+      const replyToList = normalizeRecipients(options.replyTo);
+      if (replyToList.length > 0) {
+        payload.reply_to = replyToList.map((r) => ({
+          address: r.address,
+          name: r.name
+        }));
+      }
+    }
+    if (options.attachments && options.attachments.length > 0) {
+      payload.attachments = options.attachments.map((att) => {
+        let contentBase64;
+        if (typeof att.content === "string") {
+          contentBase64 = att.content;
+        } else {
+          if (typeof Buffer !== "undefined") {
+            contentBase64 = Buffer.from(att.content).toString("base64");
+          } else {
+            let binary = "";
+            const bytes = new Uint8Array(att.content);
+            for (let i = 0; i < bytes.byteLength; i++) {
+              binary += String.fromCharCode(bytes[i]);
+            }
+            contentBase64 = btoa(binary);
+          }
+        }
+        return {
+          name: att.filename,
+          content: contentBase64,
+          mime_type: att.mimeType || att.contentType || "application/octet-stream",
+          cid: att.cid
+        };
+      });
+    }
+    let response;
+    try {
+      response = await this.fetchImpl(this.apiUrl, {
+        method: "POST",
+        headers: {
+          Accept: "application/json",
+          "Content-Type": "application/json",
+          Authorization: this.authHeader
+        },
+        body: JSON.stringify(payload)
+      });
+    } catch (err) {
+      throw new TransportError(`ZeptoMailSender: Network request failed: ${err instanceof Error ? err.message : String(err)}`, {
+        transportName: this.name,
+        cause: err
+      });
+    }
+    const responseText = await response.text();
+    let responseData;
+    try {
+      responseData = responseText ? JSON.parse(responseText) : {};
+    } catch {
+      responseData = { raw: responseText };
+    }
+    if (!response.ok) {
+      const errorMessage = responseData?.error?.message || responseData?.message || `HTTP ${response.status}: ${responseText || response.statusText}`;
+      throw new TransportError(`ZeptoMailSender: Failed to send email - ${errorMessage}`, {
+        transportName: this.name,
+        statusCode: response.status,
+        responseBody: responseText
+      });
+    }
+    const messageId = responseData?.data?.[0]?.message_id;
+    return {
+      success: true,
+      messageId,
+      response: responseData
+    };
+  }
+  /**
+   * Backward-compatible helper method matching legacy signature:
+   * `sendEmail(to, htmlBody, subject, toName?, plaintextBody?, fromName?)`
+   */
+  async sendEmail(to, htmlBody, subject, toName = "", plaintextBody, fromName) {
+    await this.send({
+      to: { address: to, name: toName },
+      from: fromName ? { address: this.defaultFrom.address, name: fromName } : this.defaultFrom,
+      subject,
+      html: htmlBody,
+      text: plaintextBody
+    });
+  }
+};
+
+// src/transports/memory/memory-sender.ts
+var MemoryEmailSender = class {
+  name = "memory";
+  sentMails = [];
+  nextId = 1;
+  async send(options) {
+    this.sentMails.push({ ...options });
+    const messageId = `mem-${this.nextId++}-${Date.now()}`;
+    return {
+      success: true,
+      messageId,
+      response: { id: messageId }
+    };
+  }
+  /**
+   * Returns a copy of all emails sent through this transport instance.
+   */
+  getSentMails() {
+    return [...this.sentMails];
+  }
+  /**
+   * Returns the most recent email sent, or undefined if no emails have been sent.
+   */
+  getLastMail() {
+    return this.sentMails.length > 0 ? { ...this.sentMails[this.sentMails.length - 1] } : void 0;
+  }
+  /**
+   * Clears all recorded sent emails.
+   */
+  clear() {
+    this.sentMails = [];
+  }
+  /**
+   * Returns the total count of sent emails.
+   */
+  count() {
+    return this.sentMails.length;
+  }
+};
+
+// src/transports/console/console-sender.ts
+var ConsoleEmailSender = class {
+  name = "console";
+  log;
+  includeHtml;
+  nextId = 1;
+  constructor(options = {}) {
+    this.log = options.logger ?? console.log;
+    this.includeHtml = options.includeHtml ?? false;
+  }
+  async send(options) {
+    const to = normalizeRecipients(options.to).map((r) => r.name ? `${r.name} <${r.address}>` : r.address).join(", ");
+    const from = options.from ? JSON.stringify(options.from) : "(default)";
+    const messageId = `console-${this.nextId++}-${Date.now()}`;
+    const separator = "\u2500".repeat(60);
+    const lines = [
+      `
+\u250C${separator}\u2510`,
+      `\u2502 [ts-mailkit:console] DISPATCHED EMAIL (${messageId})`,
+      `\u251C${separator}\u2524`,
+      `\u2502 From:    ${from}`,
+      `\u2502 To:      ${to}`,
+      `\u2502 Subject: ${options.subject}`,
+      `\u251C${separator}\u2524`
+    ];
+    if (options.text) {
+      lines.push("\u2502 Text Body:");
+      for (const line of options.text.split("\n")) {
+        lines.push(`\u2502   ${line}`);
+      }
+    }
+    if (this.includeHtml && options.html) {
+      lines.push("\u2502 HTML Body:");
+      for (const line of options.html.split("\n")) {
+        lines.push(`\u2502   ${line}`);
+      }
+    }
+    lines.push(`\u2514${separator}\u2518
+`);
+    this.log(lines.join("\n"));
+    return {
+      success: true,
+      messageId,
+      response: { logged: true }
+    };
+  }
+};
+
+// src/templates/factory.ts
+var DEFAULT_SECURITY_MESSAGE = "If you did not request this, please ignore this email or contact support if you have concerns.";
+function defaultFooter(brandName) {
+  return `&copy; ${(/* @__PURE__ */ new Date()).getFullYear()} ${brandName}. All rights reserved.`;
+}
+var EmailTemplateFactory = class _EmailTemplateFactory {
+  defaultBrandName;
+  defaultSecurityMessage;
+  footerResolver;
+  constructor(config = {}) {
+    this.defaultBrandName = config.brandName || "Application";
+    this.defaultSecurityMessage = config.securityMessage || DEFAULT_SECURITY_MESSAGE;
+    if (typeof config.footer === "function") {
+      this.footerResolver = config.footer;
+    } else if (typeof config.footer === "string") {
+      const fixedFooter = config.footer;
+      this.footerResolver = () => fixedFooter;
+    } else {
+      this.footerResolver = defaultFooter;
+    }
+  }
+  resolveBrand(override) {
+    return override || this.defaultBrandName;
+  }
+  buildFooter(brandName) {
+    return this.footerResolver(brandName);
+  }
+  /**
+   * Welcome / email-verification email sent after registration.
+   */
+  createEmailVerification(username, verificationUrl, otp, brandName) {
+    const brand = this.resolveBrand(brandName);
+    const body = `Hi ${username},<br/>Thank you for signing up. Use the code below or click the button to verify your email address.`;
+    return {
+      subject: "Verify Your Email Address",
+      header: `Welcome to ${brand}!`,
+      body,
+      otpCode: otp,
+      actionUrl: verificationUrl,
+      actionText: "Verify Email",
+      extraMessage: this.defaultSecurityMessage,
+      footer: this.buildFooter(brand),
+      userName: username,
+      fromName: brand,
+      noHtmlMessage: htmlToPlainText(body) + `
+
+Your verification code is: ${otp}
+
+Alternatively, verify here:
+${verificationUrl}`
+    };
+  }
+  /**
+   * Password-reset email with an optional OTP code and action link.
+   */
+  createPasswordReset(username, resetUrl, otp = "", brandName) {
+    const brand = this.resolveBrand(brandName);
+    const body = `Hi ${username},<br/>We received a request to reset your password. Use the OTP code below or click the button to proceed.`;
+    const plainTextOtp = otp ? `
+
+Your OTP code is: ${otp}` : "";
+    return {
+      subject: "Password Reset Request",
+      header: "Reset Your Password",
+      body,
+      otpCode: otp || void 0,
+      actionUrl: resetUrl,
+      actionText: "Reset Password",
+      extraMessage: this.defaultSecurityMessage,
+      footer: this.buildFooter(brand),
+      userName: username,
+      fromName: brand,
+      noHtmlMessage: htmlToPlainText(body) + plainTextOtp + `
+
+Alternatively, you can use the following link to reset your password:
+${resetUrl}`
+    };
+  }
+  /**
+   * Generic plain message email (no action button, no OTP).
+   */
+  createSimpleMessage(subject, header, body, brandName) {
+    const brand = this.resolveBrand(brandName);
+    return {
+      subject,
+      header,
+      body,
+      footer: this.buildFooter(brand),
+      fromName: brand,
+      noHtmlMessage: htmlToPlainText(body)
+    };
+  }
+  /**
+   * Newsletter / announcement email with an optional hero image and CTA button.
+   */
+  createNewsLetter(subject, header, body, imageUrl, actionUrl, actionText, brandName) {
+    const brand = this.resolveBrand(brandName);
+    let noHtmlMessage = htmlToPlainText(body);
+    if (actionUrl) {
+      noHtmlMessage += `
+
+${actionText || "Learn more"}: ${actionUrl}`;
+    }
+    return {
+      subject,
+      header,
+      body,
+      imageUrl,
+      actionUrl,
+      actionText,
+      footer: this.buildFooter(brand),
+      fromName: brand,
+      noHtmlMessage
+    };
+  }
+  /**
+   * Two-factor authentication email with OTP code and optional magic link.
+   */
+  create2FAEmail(username, otp, magicLink = "", brandName) {
+    const brand = this.resolveBrand(brandName);
+    const body = `Hi ${username},<br/>Use the code below or click the button to complete your login.`;
+    const plainLink = magicLink ? `
+
+Alternatively, verify here:
+${magicLink}` : "";
+    return {
+      subject: "Your Login Verification Code",
+      header: "Two-Factor Authentication",
+      body,
+      otpCode: otp,
+      actionUrl: magicLink || void 0,
+      actionText: magicLink ? "Verify Login" : void 0,
+      extraMessage: this.defaultSecurityMessage,
+      footer: this.buildFooter(brand),
+      userName: username,
+      fromName: brand,
+      noHtmlMessage: htmlToPlainText(body) + `
+
+Your verification code is: ${otp}` + plainLink
+    };
+  }
+  /**
+   * Magic link sign-in email (no OTP, button only).
+   */
+  createMagicLinkEmail(username, magicLink, brandName) {
+    const brand = this.resolveBrand(brandName);
+    const body = `Hi ${username},<br/>Click the button below to sign in. No password needed.`;
+    return {
+      subject: "Your Magic Link",
+      header: `Sign In to ${brand}`,
+      body,
+      actionUrl: magicLink,
+      actionText: "Sign In",
+      extraMessage: this.defaultSecurityMessage,
+      footer: this.buildFooter(brand),
+      userName: username,
+      fromName: brand,
+      noHtmlMessage: htmlToPlainText(body) + `
+
+Sign in here:
+${magicLink}`
+    };
+  }
+  // ─── Default Static Instance ──────────────────────────────────────────────
+  static _defaultInstance;
+  static get defaultInstance() {
+    if (!this._defaultInstance) {
+      this._defaultInstance = new _EmailTemplateFactory();
+    }
+    return this._defaultInstance;
+  }
+  static createEmailVerification(username, verificationUrl, otp, brandName) {
+    return this.defaultInstance.createEmailVerification(username, verificationUrl, otp, brandName);
+  }
+  static createPasswordReset(username, resetUrl, otp, brandName) {
+    return this.defaultInstance.createPasswordReset(username, resetUrl, otp, brandName);
+  }
+  static createSimpleMessage(subject, header, body, brandName) {
+    return this.defaultInstance.createSimpleMessage(subject, header, body, brandName);
+  }
+  static createNewsLetter(subject, header, body, imageUrl, actionUrl, actionText, brandName) {
+    return this.defaultInstance.createNewsLetter(
+      subject,
+      header,
+      body,
+      imageUrl,
+      actionUrl,
+      actionText,
+      brandName
+    );
+  }
+  static create2FAEmail(username, otp, magicLink, brandName) {
+    return this.defaultInstance.create2FAEmail(username, otp, magicLink, brandName);
+  }
+  static createMagicLinkEmail(username, magicLink, brandName) {
+    return this.defaultInstance.createMagicLinkEmail(username, magicLink, brandName);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConfigurationError,
+  ConsoleEmailSender,
+  DefaultEmailRenderer,
+  EmailService,
+  EmailTemplateFactory,
+  MailKit,
+  MailKitError,
+  MemoryEmailSender,
+  TemplateError,
+  TransportError,
+  ZeptoMailSender,
+  buildHtml,
+  buildPlainText,
+  createMailKit,
+  decodeHtmlEntities,
+  htmlToPlainText,
+  normalizeRecipient,
+  normalizeRecipients
+});
+//# sourceMappingURL=index.cjs.map