@holo-js/mail 0.1.3

package/dist/index.mjs

@@ -0,0 +1,1321 @@
+import {
+  attachContent,
+  attachFromPath,
+  attachFromStorage,
+  createAttachmentMetadata,
+  createAttachmentResolutionPlan,
+  createAttachmentResolutionPlans,
+  defineMail,
+  inferMimeTypeFromName,
+  isAttachmentQueueSafe,
+  isMailDefinition,
+  mailInternals,
+  mergeMailDefinitionInputs,
+  normalizeMailDefinition,
+  resolveAttachmentDefinition,
+  resolveNormalizedAttachment
+} from "./chunk-UB6ANQ2F.mjs";
+
+// src/runtime.ts
+import { randomUUID } from "crypto";
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+import {
+  holoMailDefaults,
+  normalizeAppEnv
+} from "@holo-js/config";
+
+// src/registry.ts
+function normalizeDriverName(value) {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error("[@holo-js/mail] Mail driver names must be non-empty strings.");
+  }
+  return normalized;
+}
+function getRegistry() {
+  const runtime = globalThis;
+  runtime.__holoMailDriverRegistry__ ??= /* @__PURE__ */ new Map();
+  return runtime.__holoMailDriverRegistry__;
+}
+function registerMailDriver(name, driver, options = {}) {
+  const normalizedName = normalizeDriverName(name);
+  if (typeof driver?.send !== "function") {
+    throw new Error(`[@holo-js/mail] Mail driver "${normalizedName}" must define send().`);
+  }
+  const registry = getRegistry();
+  if (registry.has(normalizedName) && options.replaceExisting !== true) {
+    throw new Error(`[@holo-js/mail] Mail driver "${normalizedName}" is already registered.`);
+  }
+  registry.set(normalizedName, Object.freeze({
+    name: normalizedName,
+    driver
+  }));
+}
+function getRegisteredMailDriver(name) {
+  return getRegistry().get(normalizeDriverName(name));
+}
+function listRegisteredMailDrivers() {
+  return Object.freeze([...getRegistry().values()]);
+}
+function resetMailDriverRegistry() {
+  getRegistry().clear();
+}
+var mailRegistryInternals = {
+  getRegistry,
+  normalizeDriverName
+};
+
+// src/runtime.ts
+var HOLO_MAIL_DELIVER_JOB = "holo.mail.deliver";
+var MailError = class extends Error {
+  code;
+  constructor(message, code = "MAIL_ERROR", options) {
+    super(message, options);
+    this.name = "MailError";
+    this.code = code;
+  }
+};
+var MailPreviewDisabledError = class extends MailError {
+  policy;
+  constructor(policy) {
+    super(
+      `[@holo-js/mail] Mail preview is disabled for the "${policy.environment}" environment.`,
+      "MAIL_PREVIEW_DISABLED"
+    );
+    this.name = "MailPreviewDisabledError";
+    this.policy = policy;
+  }
+};
+var MailPreviewFormatUnavailableError = class extends MailError {
+  format;
+  constructor(format) {
+    super(
+      `[@holo-js/mail] Mail ${format} preview is unavailable for this message.`,
+      "MAIL_PREVIEW_FORMAT_UNAVAILABLE"
+    );
+    this.name = "MailPreviewFormatUnavailableError";
+    this.format = format;
+  }
+};
+var MailSendError = class extends MailError {
+  messageId;
+  mailer;
+  driver;
+  constructor(details, options) {
+    super(
+      details.message ?? `[@holo-js/mail] Mail delivery failed for mailer "${details.mailer}" using driver "${details.driver}".`,
+      "MAIL_SEND_FAILED",
+      options
+    );
+    this.name = "MailSendError";
+    this.messageId = details.messageId;
+    this.mailer = details.mailer;
+    this.driver = details.driver;
+  }
+};
+function getRuntimeState() {
+  const runtime = globalThis;
+  runtime.__holoMailRuntime__ ??= {};
+  return runtime.__holoMailRuntime__;
+}
+function getRuntimeBindings() {
+  return getRuntimeState().bindings ?? {};
+}
+function dynamicImport(specifier) {
+  return import(
+    /* webpackIgnore: true */
+    specifier
+  );
+}
+async function loadQueueModule() {
+  const override = getRuntimeState().loadQueueModule;
+  if (override) {
+    try {
+      return await override();
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ERR_MODULE_NOT_FOUND") {
+        throw new MailError(
+          "[@holo-js/mail] Queued or delayed mail delivery requires @holo-js/queue to be installed.",
+          "MAIL_QUEUE_MODULE_MISSING"
+        );
+      }
+      throw error;
+    }
+  }
+  try {
+    return await dynamicImport("@holo-js/queue");
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ERR_MODULE_NOT_FOUND") {
+      throw new MailError(
+        "[@holo-js/mail] Queued or delayed mail delivery requires @holo-js/queue to be installed.",
+        "MAIL_QUEUE_MODULE_MISSING"
+      );
+    }
+    throw error;
+  }
+}
+async function loadDbModule() {
+  const override = getRuntimeState().loadDbModule;
+  if (override) {
+    try {
+      return await override();
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ERR_MODULE_NOT_FOUND") {
+        return null;
+      }
+      throw error;
+    }
+  }
+  try {
+    return await dynamicImport("@holo-js/db");
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ERR_MODULE_NOT_FOUND") {
+      return null;
+    }
+    throw error;
+  }
+}
+function resolveNodemailerModule(module) {
+  if (module && typeof module === "object" && "createTransport" in module && typeof module.createTransport === "function") {
+    return module;
+  }
+  if (module && typeof module === "object" && "default" in module && module.default && typeof module.default?.createTransport === "function") {
+    return module.default;
+  }
+  throw new MailError(
+    "[@holo-js/mail] Nodemailer could not be loaded for SMTP delivery.",
+    "MAIL_SMTP_MODULE_INVALID"
+  );
+}
+async function loadNodemailerModule() {
+  const override = getRuntimeState().loadNodemailerModule;
+  if (override) {
+    try {
+      return resolveNodemailerModule(await override());
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ERR_MODULE_NOT_FOUND") {
+        throw new MailError(
+          "[@holo-js/mail] SMTP delivery requires nodemailer to be installed.",
+          "MAIL_SMTP_MODULE_MISSING",
+          { cause: error }
+        );
+      }
+      throw error;
+    }
+  }
+  try {
+    return resolveNodemailerModule(await dynamicImport("nodemailer"));
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ERR_MODULE_NOT_FOUND") {
+      throw new MailError(
+        "[@holo-js/mail] SMTP delivery requires nodemailer to be installed.",
+        "MAIL_SMTP_MODULE_MISSING",
+        { cause: error }
+      );
+    }
+    throw error;
+  }
+}
+function resolveStorageModule(module) {
+  if (module && typeof module === "object" && "Storage" in module && module.Storage && typeof module.Storage?.disk === "function") {
+    return module;
+  }
+  throw new MailError(
+    "[@holo-js/mail] The storage runtime could not be loaded for storage-backed attachments.",
+    "MAIL_STORAGE_MODULE_INVALID"
+  );
+}
+async function loadStorageModule() {
+  const override = getRuntimeState().loadStorageModule;
+  if (override) {
+    try {
+      return resolveStorageModule(await override());
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ERR_MODULE_NOT_FOUND") {
+        throw new MailError(
+          "[@holo-js/mail] Storage-backed attachments require @holo-js/storage to be installed.",
+          "MAIL_STORAGE_MODULE_MISSING",
+          { cause: error }
+        );
+      }
+      throw error;
+    }
+  }
+  try {
+    return resolveStorageModule(await dynamicImport("@holo-js/storage"));
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ERR_MODULE_NOT_FOUND") {
+      throw new MailError(
+        "[@holo-js/mail] Storage-backed attachments require @holo-js/storage to be installed.",
+        "MAIL_STORAGE_MODULE_MISSING",
+        { cause: error }
+      );
+    }
+    throw error;
+  }
+}
+function getFakeSentState() {
+  const state = getRuntimeState();
+  state.fakeSent ??= [];
+  return state.fakeSent;
+}
+function getPreviewArtifactState() {
+  const state = getRuntimeState();
+  state.previewArtifacts ??= [];
+  return state.previewArtifacts;
+}
+function normalizeExecutionString(value, label) {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(`[@holo-js/mail] ${label} must be a non-empty string.`);
+  }
+  return normalized;
+}
+function normalizeExecutionDelay(value) {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value < 0) {
+      throw new Error("[@holo-js/mail] Mail delays must be finite numbers greater than or equal to 0.");
+    }
+    return value;
+  }
+  if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+    throw new Error("[@holo-js/mail] Mail delays must use valid Date instances.");
+  }
+  return value;
+}
+function getResolvedConfig() {
+  return getRuntimeBindings().config ?? holoMailDefaults;
+}
+function resolveCurrentEnvironment() {
+  return normalizeAppEnv(process.env.APP_ENV ?? process.env.NODE_ENV);
+}
+function createPreviewPolicy(config = getResolvedConfig()) {
+  return Object.freeze({
+    environment: resolveCurrentEnvironment(),
+    allowedEnvironments: config.preview.allowedEnvironments
+  });
+}
+function assertPreviewEnabled(config = getResolvedConfig()) {
+  const policy = createPreviewPolicy(config);
+  if (!policy.allowedEnvironments.includes(policy.environment)) {
+    throw new MailPreviewDisabledError(policy);
+  }
+}
+function createPreviewHtml(preview) {
+  const header = [
+    `<h1>${escapeHtml(preview.subject)}</h1>`,
+    `<p><strong>From:</strong> ${formatAddress(preview.from)}</p>`,
+    `<p><strong>Reply-To:</strong> ${formatAddress(preview.replyTo)}</p>`,
+    `<p><strong>To:</strong> ${preview.to.map(formatAddress).join(", ")}</p>`,
+    preview.cc.length > 0 ? `<p><strong>Cc:</strong> ${preview.cc.map(formatAddress).join(", ")}</p>` : "",
+    preview.bcc.length > 0 ? `<p><strong>Bcc:</strong> ${preview.bcc.map(formatAddress).join(", ")}</p>` : ""
+  ].filter(Boolean).join("");
+  const body = preview.html ? preview.html : preview.text ? `<pre>${escapeHtml(preview.text)}</pre>` : "<p>No rendered content is available.</p>";
+  return `<!doctype html><html><head><meta charset="utf-8"><title>${escapeHtml(preview.subject)}</title></head><body>${header}${body}</body></html>`;
+}
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+}
+function formatAddress(address) {
+  return address.name ? `${escapeHtml(address.name)} &lt;${escapeHtml(address.email)}&gt;` : escapeHtml(address.email);
+}
+function renderPreviewResponse(preview, format) {
+  if (format === "json") {
+    return new Response(JSON.stringify(preview, null, 2), {
+      status: 200,
+      headers: {
+        "content-type": "application/json; charset=utf-8"
+      }
+    });
+  }
+  if (format === "text") {
+    if (typeof preview.text !== "string") {
+      throw new MailPreviewFormatUnavailableError(format);
+    }
+    return new Response(preview.text, {
+      status: 200,
+      headers: {
+        "content-type": "text/plain; charset=utf-8"
+      }
+    });
+  }
+  return new Response(createPreviewHtml(preview), {
+    status: 200,
+    headers: {
+      "content-type": "text/html; charset=utf-8"
+    }
+  });
+}
+function getMailerConfig(mailer, config = getResolvedConfig()) {
+  const mailerConfig = config.mailers[mailer];
+  if (!mailerConfig) {
+    throw new MailError(
+      `[@holo-js/mail] Mailer "${mailer}" is not configured. Available mailers: ${Object.keys(config.mailers).join(", ")}`,
+      "MAILER_NOT_CONFIGURED"
+    );
+  }
+  return mailerConfig;
+}
+function isPreviewMailerConfig(config) {
+  return config.driver === "preview" && typeof config.path === "string";
+}
+function isSmtpMailerConfig(config) {
+  return config.driver === "smtp" && typeof config.host === "string" && typeof config.port === "number" && typeof config.secure === "boolean";
+}
+function isQueueRequested(mail2, mailer, options, config = getResolvedConfig()) {
+  const mailerConfig = getMailerConfig(mailer, config);
+  const mailQueue = mail2.queue;
+  if (typeof options.connection === "string" || typeof options.queue === "string" || typeof options.delay !== "undefined") {
+    return true;
+  }
+  if (mailQueue === true) {
+    return true;
+  }
+  if (mailQueue === false) {
+    return false;
+  }
+  if (typeof mailQueue === "object" && mailQueue !== null) {
+    if (typeof mailQueue.connection === "string" || typeof mailQueue.queue === "string") {
+      return true;
+    }
+    if (typeof mailQueue.queued === "boolean") {
+      return mailQueue.queued;
+    }
+  }
+  return mailerConfig.queue.queued === true || typeof mailerConfig.queue.connection === "string" || typeof mailerConfig.queue.queue === "string" || config.queue.queued === true || typeof config.queue.connection === "string" || typeof config.queue.queue === "string";
+}
+function resolveQueuePlan(mail2, options, mailer, config = getResolvedConfig()) {
+  const mailerConfig = getMailerConfig(mailer, config);
+  const mailQueue = typeof mail2.queue === "object" && mail2.queue !== null ? mail2.queue : void 0;
+  const queued = isQueueRequested(mail2, mailer, options, config);
+  return Object.freeze({
+    queued,
+    connection: queued ? options.connection ?? mailQueue?.connection ?? mailerConfig.queue.connection ?? config.queue.connection : void 0,
+    queue: queued ? options.queue ?? mailQueue?.queue ?? mailerConfig.queue.queue ?? config.queue.queue : void 0,
+    delay: queued ? options.delay ?? mail2.delay : void 0,
+    afterCommit: options.afterCommit ?? mailQueue?.afterCommit ?? mailerConfig.queue.afterCommit ?? config.queue.afterCommit
+  });
+}
+async function prepareMailSend(mail2, queued) {
+  const plans = createAttachmentResolutionPlans(mail2.attachments, { queued });
+  const attachments = Object.freeze(await Promise.all(plans.map((plan) => plan.resolve())));
+  return Object.freeze({
+    attachments
+  });
+}
+function createResolvedMail(preview, attachments) {
+  return Object.freeze({
+    from: preview.from,
+    replyTo: preview.replyTo,
+    to: preview.to,
+    cc: preview.cc,
+    bcc: preview.bcc,
+    subject: preview.subject,
+    ...typeof preview.html === "string" ? { html: preview.html } : {},
+    ...typeof preview.text === "string" ? { text: preview.text } : {},
+    attachments,
+    headers: preview.headers,
+    tags: preview.tags,
+    ...preview.metadata ? { metadata: preview.metadata } : {},
+    ...preview.priority ? { priority: preview.priority } : {}
+  });
+}
+function createSendContext(messageId, resolvedDriver, queued, deferred) {
+  return Object.freeze({
+    messageId,
+    mailer: resolvedDriver.mailer,
+    driver: resolvedDriver.driver,
+    queued,
+    ...typeof deferred === "boolean" ? { deferred } : {}
+  });
+}
+function freezeSendResult(result) {
+  return Object.freeze({
+    ...result,
+    ...result.provider ? { provider: Object.freeze({ ...result.provider }) } : {}
+  });
+}
+function createBaseSendResult(context, overrides = {}) {
+  return freezeSendResult({
+    messageId: context.messageId,
+    mailer: context.mailer,
+    driver: context.driver,
+    queued: context.queued,
+    ...typeof context.deferred === "boolean" ? { deferred: context.deferred } : {},
+    ...overrides
+  });
+}
+function normalizeDriverResult(result, context) {
+  if (!result) {
+    return createBaseSendResult(context);
+  }
+  return freezeSendResult({
+    messageId: result.messageId ?? context.messageId,
+    mailer: result.mailer ?? context.mailer,
+    driver: result.driver ?? context.driver,
+    queued: typeof result.queued === "boolean" ? result.queued : context.queued,
+    ...typeof result.deferred === "boolean" ? { deferred: result.deferred } : {},
+    ...typeof result.providerMessageId === "string" ? { providerMessageId: result.providerMessageId } : {},
+    ...result.provider ? { provider: result.provider } : {}
+  });
+}
+function createMailRecord(context, mail2, result) {
+  return Object.freeze({
+    messageId: context.messageId,
+    createdAt: /* @__PURE__ */ new Date(),
+    mail: mail2,
+    context,
+    result
+  });
+}
+async function persistPreviewArtifact(artifact) {
+  const mailer = getMailerConfig(artifact.context.mailer);
+  if (!isPreviewMailerConfig(mailer)) {
+    return;
+  }
+  await mkdir(mailer.path, { recursive: true });
+  await writeFile(
+    join(mailer.path, `${artifact.messageId}.json`),
+    `${JSON.stringify(artifact, null, 2)}
+`,
+    "utf8"
+  );
+}
+function createSmtpAddress(address) {
+  return Object.freeze({
+    address: address.email,
+    ...typeof address.name === "string" ? { name: address.name } : {}
+  });
+}
+function createSmtpHeaders(mail2) {
+  const headers = { ...mail2.headers };
+  if (mail2.tags.length > 0) {
+    headers["X-Holo-Tags"] = mail2.tags.join(", ");
+  }
+  if (mail2.metadata) {
+    headers["X-Holo-Metadata"] = JSON.stringify(mail2.metadata);
+  }
+  if (mail2.priority === "high") {
+    headers["X-Priority"] = "1";
+    headers.Importance = "high";
+    headers.Priority = "urgent";
+  } else if (mail2.priority === "low") {
+    headers["X-Priority"] = "5";
+    headers.Importance = "low";
+    headers.Priority = "non-urgent";
+  } else if (mail2.priority === "normal") {
+    headers["X-Priority"] = "3";
+    headers.Importance = "normal";
+    headers.Priority = "normal";
+  }
+  return Object.keys(headers).length > 0 ? Object.freeze(headers) : void 0;
+}
+async function createSmtpAttachment(attachment) {
+  const base = {
+    filename: attachment.name,
+    ...typeof attachment.contentType === "string" ? { contentType: attachment.contentType } : {},
+    contentDisposition: attachment.disposition,
+    ...typeof attachment.contentId === "string" ? { cid: attachment.contentId } : {}
+  };
+  if (typeof attachment.path === "string") {
+    return Object.freeze({
+      ...base,
+      path: attachment.path
+    });
+  }
+  if (attachment.storage) {
+    const storageModule = await loadStorageModule();
+    const disk = storageModule.Storage.disk(attachment.storage.disk);
+    if (disk.driver !== "s3") {
+      return Object.freeze({
+        ...base,
+        path: disk.path(attachment.storage.path)
+      });
+    }
+    const bytes = await disk.getBytes(attachment.storage.path);
+    if (!bytes) {
+      throw new MailError(
+        `[@holo-js/mail] Storage attachment "${attachment.storage.path}" could not be read for SMTP delivery.`,
+        "MAIL_STORAGE_ATTACHMENT_MISSING"
+      );
+    }
+    return Object.freeze({
+      ...base,
+      content: bytes
+    });
+  }
+  if (typeof attachment.content !== "undefined") {
+    return Object.freeze({
+      ...base,
+      content: attachment.content
+    });
+  }
+  throw new MailError(
+    `[@holo-js/mail] Attachment "${attachment.name}" could not be translated for SMTP delivery.`,
+    "MAIL_SMTP_ATTACHMENT_INVALID"
+  );
+}
+async function createSmtpMessage(mail2, context) {
+  const attachments = mail2.attachments.length > 0 ? Object.freeze(await Promise.all(mail2.attachments.map(createSmtpAttachment))) : void 0;
+  const headers = createSmtpHeaders(mail2);
+  return Object.freeze({
+    messageId: context.messageId,
+    from: createSmtpAddress(mail2.from),
+    replyTo: createSmtpAddress(mail2.replyTo),
+    to: Object.freeze(mail2.to.map(createSmtpAddress)),
+    ...mail2.cc.length > 0 ? { cc: Object.freeze(mail2.cc.map(createSmtpAddress)) } : {},
+    ...mail2.bcc.length > 0 ? { bcc: Object.freeze(mail2.bcc.map(createSmtpAddress)) } : {},
+    subject: mail2.subject,
+    ...typeof mail2.html === "string" ? { html: mail2.html } : {},
+    ...typeof mail2.text === "string" ? { text: mail2.text } : {},
+    ...attachments ? { attachments } : {},
+    ...headers ? { headers } : {}
+  });
+}
+async function sendViaSmtp(mail2, context) {
+  const nodemailer = await loadNodemailerModule();
+  const mailerConfig = getMailerConfig(context.mailer);
+  if (!isSmtpMailerConfig(mailerConfig)) {
+    throw new MailError(
+      `[@holo-js/mail] Mailer "${context.mailer}" is not configured for SMTP delivery.`,
+      "MAIL_SMTP_MAILER_INVALID"
+    );
+  }
+  const transporter = nodemailer.createTransport({
+    host: mailerConfig.host,
+    port: mailerConfig.port,
+    secure: mailerConfig.secure,
+    ...typeof mailerConfig.user === "string" ? {
+      auth: {
+        user: mailerConfig.user,
+        ...typeof mailerConfig.password === "string" ? { pass: mailerConfig.password } : {}
+      }
+    } : {}
+  });
+  const smtpMessage = await createSmtpMessage(mail2, context);
+  const result = await transporter.sendMail(smtpMessage);
+  return createBaseSendResult(context, {
+    ...typeof result.messageId === "string" ? { providerMessageId: result.messageId } : {},
+    ...typeof result.response === "string" ? {
+      provider: {
+        response: result.response
+      }
+    } : {}
+  });
+}
+var builtInDrivers = Object.freeze({
+  preview: Object.freeze({
+    async send(mail2, context) {
+      const result = createBaseSendResult(context);
+      const artifact = createMailRecord(context, mail2, result);
+      getPreviewArtifactState().push(artifact);
+      await persistPreviewArtifact(artifact);
+      return result;
+    }
+  }),
+  fake: Object.freeze({
+    send(mail2, context) {
+      const result = createBaseSendResult(context);
+      getFakeSentState().push(createMailRecord(context, mail2, result));
+      return result;
+    }
+  }),
+  log: Object.freeze({
+    send(mail2, context) {
+      const mailerConfig = getMailerConfig(context.mailer);
+      const verbose = mailerConfig.driver === "log" ? mailerConfig.logBodies : false;
+      const payload = {
+        messageId: context.messageId,
+        mailer: context.mailer,
+        driver: context.driver,
+        to: mail2.to.map((address) => address.email),
+        subject: mail2.subject,
+        hasHtml: typeof mail2.html === "string",
+        hasText: typeof mail2.text === "string",
+        attachments: mail2.attachments.map((attachment) => ({
+          name: attachment.name,
+          source: attachment.source,
+          disposition: attachment.disposition
+        })),
+        ...mail2.tags.length > 0 ? { tags: [...mail2.tags] } : {},
+        ...mail2.priority ? { priority: mail2.priority } : {},
+        ...verbose ? {
+          html: mail2.html,
+          text: mail2.text
+        } : {}
+      };
+      console.warn("[@holo-js/mail] Logged mail send", payload);
+      return createBaseSendResult(context);
+    }
+  }),
+  smtp: Object.freeze({
+    async send(mail2, context) {
+      return await sendViaSmtp(mail2, context);
+    }
+  })
+});
+function resolveDriver(mail2, options, config) {
+  const selectedMailer = typeof options.mailer === "string" ? options.mailer : resolveMailerName(mail2, config);
+  const mailerConfig = getMailerConfig(selectedMailer, config);
+  const driverName = mailerConfig.driver;
+  const builtIn = builtInDrivers[driverName];
+  if (builtIn) {
+    return Object.freeze({
+      mailer: selectedMailer,
+      driver: driverName,
+      implementation: builtIn
+    });
+  }
+  const registered = getRegisteredMailDriver(driverName);
+  if (!registered) {
+    throw new MailError(
+      `[@holo-js/mail] Mail driver "${driverName}" is not registered.`,
+      "MAIL_DRIVER_NOT_REGISTERED"
+    );
+  }
+  return Object.freeze({
+    mailer: selectedMailer,
+    driver: driverName,
+    implementation: registered.driver
+  });
+}
+function resolveDriverByName(mailer, driver) {
+  const builtIn = builtInDrivers[driver];
+  if (builtIn) {
+    return Object.freeze({
+      mailer,
+      driver,
+      implementation: builtIn
+    });
+  }
+  const registered = getRegisteredMailDriver(driver);
+  if (!registered) {
+    throw new MailError(
+      `[@holo-js/mail] Mail driver "${driver}" is not registered.`,
+      "MAIL_DRIVER_NOT_REGISTERED"
+    );
+  }
+  return Object.freeze({
+    mailer,
+    driver,
+    implementation: registered.driver
+  });
+}
+function serializeQueuedAttachment(attachment) {
+  return Object.freeze({
+    source: attachment.source,
+    name: attachment.name,
+    ...typeof attachment.contentType === "string" ? { contentType: attachment.contentType } : {},
+    disposition: attachment.disposition,
+    ...typeof attachment.contentId === "string" ? { contentId: attachment.contentId } : {},
+    ...typeof attachment.path === "string" ? { path: attachment.path } : {},
+    ...attachment.storage ? { storage: attachment.storage } : {},
+    ...typeof attachment.content === "string" ? { content: attachment.content } : attachment.content instanceof Uint8Array ? {
+      content: Object.freeze({
+        encoding: "base64",
+        value: Buffer.from(attachment.content).toString("base64")
+      })
+    } : {}
+  });
+}
+function deserializeQueuedAttachment(attachment) {
+  return Object.freeze({
+    source: attachment.source,
+    name: attachment.name,
+    ...typeof attachment.contentType === "string" ? { contentType: attachment.contentType } : {},
+    disposition: attachment.disposition,
+    ...typeof attachment.contentId === "string" ? { contentId: attachment.contentId } : {},
+    ...typeof attachment.path === "string" ? { path: attachment.path } : {},
+    ...attachment.storage ? { storage: attachment.storage } : {},
+    ...typeof attachment.content === "string" ? { content: attachment.content } : attachment.content ? { content: new Uint8Array(Buffer.from(attachment.content.value, "base64")) } : {}
+  });
+}
+function createQueuedMailPayload(mail2, context) {
+  return Object.freeze({
+    messageId: context.messageId,
+    mailer: context.mailer,
+    driver: context.driver,
+    queued: true,
+    ...typeof context.deferred === "boolean" ? { deferred: context.deferred } : {},
+    mail: Object.freeze({
+      from: mail2.from,
+      replyTo: mail2.replyTo,
+      to: mail2.to,
+      cc: mail2.cc,
+      bcc: mail2.bcc,
+      subject: mail2.subject,
+      ...typeof mail2.html === "string" ? { html: mail2.html } : {},
+      ...typeof mail2.text === "string" ? { text: mail2.text } : {},
+      attachments: Object.freeze(mail2.attachments.map(serializeQueuedAttachment)),
+      headers: mail2.headers,
+      tags: mail2.tags,
+      ...mail2.metadata ? { metadata: mail2.metadata } : {},
+      ...mail2.priority ? { priority: mail2.priority } : {}
+    })
+  });
+}
+function createResolvedMailFromQueuedPayload(payload) {
+  return Object.freeze({
+    from: payload.mail.from,
+    replyTo: payload.mail.replyTo,
+    to: payload.mail.to,
+    cc: payload.mail.cc,
+    bcc: payload.mail.bcc,
+    subject: payload.mail.subject,
+    ...typeof payload.mail.html === "string" ? { html: payload.mail.html } : {},
+    ...typeof payload.mail.text === "string" ? { text: payload.mail.text } : {},
+    attachments: Object.freeze(payload.mail.attachments.map(deserializeQueuedAttachment)),
+    headers: payload.mail.headers,
+    tags: payload.mail.tags,
+    ...payload.mail.metadata ? { metadata: payload.mail.metadata } : {},
+    ...payload.mail.priority ? { priority: payload.mail.priority } : {}
+  });
+}
+async function deliverResolvedMail(mail2, resolvedDriver, context) {
+  try {
+    const result = await resolvedDriver.implementation.send(mail2, context);
+    return normalizeDriverResult(result, context);
+  } catch (error) {
+    throw new MailSendError({
+      messageId: context.messageId,
+      mailer: context.mailer,
+      driver: context.driver
+    }, {
+      cause: error
+    });
+  }
+}
+async function runQueuedMailDelivery(payload) {
+  const resolvedDriver = resolveDriverByName(payload.mailer, payload.driver);
+  const context = Object.freeze({
+    messageId: payload.messageId,
+    mailer: payload.mailer,
+    driver: payload.driver,
+    queued: true,
+    ...typeof payload.deferred === "boolean" ? { deferred: payload.deferred } : {}
+  });
+  return await deliverResolvedMail(
+    createResolvedMailFromQueuedPayload(payload),
+    resolvedDriver,
+    context
+  );
+}
+async function ensureMailQueueJobRegistered(queueModule) {
+  const resolvedQueueModule = queueModule ?? await loadQueueModule();
+  if (resolvedQueueModule.getRegisteredQueueJob(HOLO_MAIL_DELIVER_JOB)) {
+    return resolvedQueueModule;
+  }
+  resolvedQueueModule.registerQueueJob(
+    resolvedQueueModule.defineJob({
+      async handle(payload) {
+        return await runQueuedMailDelivery(payload);
+      }
+    }),
+    { name: HOLO_MAIL_DELIVER_JOB }
+  );
+  return resolvedQueueModule;
+}
+async function dispatchQueuedMail(mail2, context, plan) {
+  const queueModule = await ensureMailQueueJobRegistered();
+  let pending = queueModule.dispatch(
+    HOLO_MAIL_DELIVER_JOB,
+    createQueuedMailPayload(mail2, context)
+  );
+  if (typeof plan.connection !== "undefined") {
+    pending = pending.onConnection(plan.connection);
+  }
+  if (typeof plan.queue !== "undefined") {
+    pending = pending.onQueue(plan.queue);
+  }
+  if (typeof plan.delay !== "undefined") {
+    pending = pending.delay(plan.delay);
+  }
+  await pending.dispatch();
+  return createBaseSendResult(context);
+}
+async function deferSendUntilCommit(context, callback) {
+  const dbModule = await loadDbModule();
+  const active = dbModule?.connectionAsyncContext.getActive()?.connection;
+  if (!active || active.getScope().kind === "root") {
+    return null;
+  }
+  active.afterCommit(async () => {
+    await callback();
+  });
+  return createBaseSendResult(context);
+}
+async function renderView(input) {
+  const renderer = getRuntimeBindings().renderView;
+  if (!renderer) {
+    throw new MailError(`[@holo-js/mail] Mail view rendering requires a renderView runtime binding for "${input.view}".`, "MAIL_VIEW_RENDERER_MISSING");
+  }
+  const html = await renderer(input);
+  if (typeof html !== "string" || !html.trim()) {
+    throw new MailError(`[@holo-js/mail] Mail view "${input.view}" must render a non-empty HTML string.`, "MAIL_VIEW_RENDER_FAILED");
+  }
+  return html;
+}
+function stripMarkdownSyntax(markdown) {
+  return markdown.replace(/\[([^\]]+)\]\(([^)]+)\)/g, "$1 ($2)").replace(/`([^`]+)`/g, "$1").replace(/\*\*([^*]+)\*\*/g, "$1").replace(/\*([^*]+)\*/g, "$1").replace(/^#{1,6}\s+/gm, "").replace(/^[-*]\s+/gm, "").trim();
+}
+function renderMarkdownInline(markdown) {
+  return escapeHtml(markdown).replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>').replace(/`([^`]+)`/g, "<code>$1</code>").replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>").replace(/\*([^*]+)\*/g, "<em>$1</em>");
+}
+function renderMarkdown(markdown) {
+  const blocks = markdown.trim().split(/\n\s*\n/g).map((block) => block.trim()).filter(Boolean);
+  return blocks.map((block) => {
+    const lines = block.split("\n").map((line) => line.trim()).filter(Boolean);
+    if (lines.length === 0) {
+      return "";
+    }
+    if (lines.every((line) => /^[-*]\s+/.test(line))) {
+      return `<ul>${lines.map((line) => `<li>${renderMarkdownInline(line.replace(/^[-*]\s+/, ""))}</li>`).join("")}</ul>`;
+    }
+    const heading = lines.length === 1 ? lines[0].match(/^(#{1,6})\s+(.+)$/) : null;
+    if (heading) {
+      const [, markers, title] = heading;
+      const level = markers.length;
+      return `<h${level}>${renderMarkdownInline(title)}</h${level}>`;
+    }
+    return `<p>${lines.map(renderMarkdownInline).join("<br />")}</p>`;
+  }).join("\n");
+}
+function resolveSourceKind(mail2) {
+  if (mail2.render) {
+    return "render";
+  }
+  if (typeof mail2.markdown === "string") {
+    return "markdown";
+  }
+  if (typeof mail2.html === "string") {
+    return "html";
+  }
+  return "text";
+}
+function resolveMailerName(mail2, config) {
+  return mail2.mailer ?? config.default;
+}
+function resolveEnvelope(mail2) {
+  const config = getResolvedConfig();
+  const mailer = resolveMailerName(mail2, config);
+  const mailerConfig = getMailerConfig(mailer, config);
+  const from = mail2.from ?? mailerConfig.from ?? config.from;
+  if (!from) {
+    throw new MailError("[@holo-js/mail] Mail preview requires a resolvable from address.", "MAIL_FROM_MISSING");
+  }
+  const replyTo = mail2.replyTo ?? mailerConfig.replyTo ?? config.replyTo ?? from;
+  return Object.freeze({
+    config,
+    mailer,
+    from,
+    replyTo,
+    to: mail2.to,
+    cc: mail2.cc,
+    bcc: mail2.bcc
+  });
+}
+function createMarkdownWrapperProps(mail2, envelope, html, text) {
+  const serializeAddress = (address) => Object.freeze({
+    email: address.email,
+    ...address.name ? { name: address.name } : {}
+  });
+  return Object.freeze({
+    subject: mail2.subject,
+    html,
+    markdown: mail2.markdown,
+    text,
+    from: serializeAddress(envelope.from),
+    replyTo: serializeAddress(envelope.replyTo),
+    to: Object.freeze(envelope.to.map(serializeAddress)),
+    cc: Object.freeze(envelope.cc.map(serializeAddress)),
+    bcc: Object.freeze(envelope.bcc.map(serializeAddress)),
+    headers: Object.freeze({ ...mail2.headers }),
+    tags: Object.freeze([...mail2.tags]),
+    ...mail2.metadata ? { metadata: mail2.metadata } : {},
+    ...mail2.priority ? { priority: mail2.priority } : {}
+  });
+}
+async function renderContent(mail2, envelope) {
+  if (mail2.render) {
+    const html = await renderView(mail2.render);
+    return Object.freeze({
+      kind: "render",
+      html,
+      ...typeof mail2.text === "string" ? { text: mail2.text } : {},
+      source: Object.freeze({
+        kind: "render",
+        render: mail2.render
+      })
+    });
+  }
+  if (typeof mail2.markdown === "string") {
+    const baseHtml = renderMarkdown(mail2.markdown);
+    const text = mail2.text ?? stripMarkdownSyntax(mail2.markdown);
+    const wrapper = mail2.markdownWrapper ?? envelope.config.markdown.wrapper;
+    const html = wrapper ? await renderView({
+      view: wrapper,
+      props: createMarkdownWrapperProps(mail2, envelope, baseHtml, text)
+    }) : baseHtml;
+    return Object.freeze({
+      kind: "markdown",
+      html,
+      text,
+      source: Object.freeze({
+        kind: "markdown",
+        markdown: mail2.markdown
+      })
+    });
+  }
+  if (typeof mail2.html === "string") {
+    return Object.freeze({
+      kind: "html",
+      html: mail2.html,
+      ...typeof mail2.text === "string" ? { text: mail2.text } : {},
+      source: Object.freeze({
+        kind: "html",
+        rawHtml: mail2.html
+      })
+    });
+  }
+  return Object.freeze({
+    kind: "text",
+    text: mail2.text,
+    source: Object.freeze({
+      kind: "text"
+    })
+  });
+}
+async function computePreview(mail2) {
+  const envelope = resolveEnvelope(mail2);
+  const rendered = await renderContent(mail2, envelope);
+  const preview = Object.freeze({
+    from: envelope.from,
+    replyTo: envelope.replyTo,
+    to: envelope.to,
+    cc: envelope.cc,
+    bcc: envelope.bcc,
+    subject: mail2.subject,
+    ...typeof rendered.html === "string" ? { html: rendered.html } : {},
+    ...typeof rendered.text === "string" ? { text: rendered.text } : {},
+    attachments: Object.freeze(mail2.attachments.map((attachment) => createAttachmentMetadata(attachment))),
+    headers: mail2.headers,
+    tags: mail2.tags,
+    ...mail2.metadata ? { metadata: mail2.metadata } : {},
+    ...mail2.priority ? { priority: mail2.priority } : {},
+    source: rendered.source
+  });
+  return Object.freeze({
+    ...envelope,
+    preview
+  });
+}
+var PendingSend = class {
+  #mail;
+  #options;
+  #promise;
+  constructor(mail2, options = {}) {
+    this.#mail = mail2;
+    this.#options = options;
+  }
+  using(name) {
+    this.#options.mailer = normalizeExecutionString(name, "Mail mailer");
+    return this;
+  }
+  onConnection(name) {
+    this.#options.connection = normalizeExecutionString(name, "Mail queue connection");
+    return this;
+  }
+  onQueue(name) {
+    this.#options.queue = normalizeExecutionString(name, "Mail queue name");
+    return this;
+  }
+  delay(value) {
+    this.#options.delay = normalizeExecutionDelay(value);
+    return this;
+  }
+  afterCommit() {
+    this.#options.afterCommit = true;
+    return this;
+  }
+  then(onfulfilled, onrejected) {
+    return this.execute().then(onfulfilled, onrejected);
+  }
+  catch(onrejected) {
+    return this.execute().catch(onrejected);
+  }
+  finally(onfinally) {
+    return this.execute().finally(onfinally);
+  }
+  execute() {
+    if (!this.#promise) {
+      this.#promise = this.#execute();
+    }
+    return this.#promise;
+  }
+  async #execute(execution = {}) {
+    const options = Object.freeze({ ...this.#options });
+    const config = getResolvedConfig();
+    const resolvedDriver = resolveDriver(this.#mail, options, config);
+    const plan = resolveQueuePlan(this.#mail, options, resolvedDriver.mailer, config);
+    const messageId = randomUUID();
+    const prepared = await prepareMailSend(this.#mail, plan.queued);
+    const input = Object.freeze({
+      mail: this.#mail,
+      attachments: prepared.attachments,
+      options
+    });
+    const sendOverride = getRuntimeBindings().send;
+    if (!plan.queued && plan.afterCommit !== true && sendOverride) {
+      const context = createSendContext(messageId, resolvedDriver, false);
+      return normalizeDriverResult(await sendOverride(input), context);
+    }
+    const { preview } = await computePreview(this.#mail);
+    const resolvedMail = createResolvedMail(preview, prepared.attachments);
+    const executionContext = createSendContext(
+      messageId,
+      resolvedDriver,
+      plan.queued,
+      plan.afterCommit ? true : void 0
+    );
+    if (execution.allowAfterCommitDeferral !== false && plan.afterCommit) {
+      const deferredResult = await deferSendUntilCommit(executionContext, async () => {
+        if (plan.queued) {
+          return await dispatchQueuedMail(resolvedMail, executionContext, plan);
+        }
+        return await deliverResolvedMail(resolvedMail, resolvedDriver, executionContext);
+      });
+      if (deferredResult) {
+        return deferredResult;
+      }
+    }
+    if (plan.queued) {
+      return await dispatchQueuedMail(
+        resolvedMail,
+        createSendContext(messageId, resolvedDriver, true),
+        plan
+      );
+    }
+    return await deliverResolvedMail(
+      resolvedMail,
+      resolvedDriver,
+      createSendContext(messageId, resolvedDriver, false)
+    );
+  }
+};
+function listFakeSentMails() {
+  return Object.freeze([...getFakeSentState()]);
+}
+function resetFakeSentMails() {
+  getFakeSentState().length = 0;
+}
+function listPreviewMailArtifacts() {
+  return Object.freeze([...getPreviewArtifactState()]);
+}
+function resetPreviewMailArtifacts() {
+  getPreviewArtifactState().length = 0;
+}
+function resolveMailInput(mail2, overrides) {
+  if (!overrides || Object.keys(overrides).length === 0) {
+    return normalizeMailDefinition(mail2);
+  }
+  return normalizeMailDefinition(mergeMailDefinitionInputs(mail2, overrides));
+}
+function configureMailRuntime(bindings) {
+  getRuntimeState().bindings = bindings;
+}
+function getMailRuntimeBindings() {
+  return getRuntimeBindings();
+}
+function resetMailRuntime() {
+  const state = getRuntimeState();
+  state.bindings = void 0;
+  state.fakeSent = void 0;
+  state.previewArtifacts = void 0;
+  state.loadQueueModule = void 0;
+  state.loadDbModule = void 0;
+  state.loadNodemailerModule = void 0;
+  state.loadStorageModule = void 0;
+}
+function sendMail(mail2, overrides) {
+  return new PendingSend(resolveMailInput(mail2, overrides));
+}
+async function previewMail(mail2, overrides) {
+  const normalizedMail = resolveMailInput(mail2, overrides);
+  const previewHandler = getRuntimeBindings().preview;
+  if (previewHandler) {
+    return Promise.resolve(previewHandler({
+      mail: normalizedMail
+    }));
+  }
+  return (await computePreview(normalizedMail)).preview;
+}
+async function renderMailPreview(mail2, overrides, format = "html") {
+  const normalizedMail = resolveMailInput(mail2, overrides);
+  try {
+    assertPreviewEnabled();
+    const explicitRenderer = getRuntimeBindings().renderPreview;
+    if (explicitRenderer) {
+      return Promise.resolve(explicitRenderer({
+        mail: normalizedMail,
+        format
+      }));
+    }
+    const preview = await previewMail(normalizedMail);
+    return renderPreviewResponse(preview, format);
+  } catch (error) {
+    if (error instanceof MailPreviewDisabledError) {
+      return new Response(error.message, {
+        status: 403,
+        headers: {
+          "content-type": "text/plain; charset=utf-8"
+        }
+      });
+    }
+    if (error instanceof MailPreviewFormatUnavailableError) {
+      return new Response(error.message, {
+        status: 422,
+        headers: {
+          "content-type": "text/plain; charset=utf-8"
+        }
+      });
+    }
+    throw error;
+  }
+}
+function getMailRuntime() {
+  return Object.freeze({
+    sendMail,
+    previewMail,
+    renderMailPreview
+  });
+}
+var mailRuntimeInternals = {
+  HOLO_MAIL_DELIVER_JOB,
+  MailSendError,
+  MailError,
+  MailPreviewDisabledError,
+  MailPreviewFormatUnavailableError,
+  PendingSend,
+  assertPreviewEnabled,
+  builtInDrivers,
+  createBaseSendResult,
+  createMailRecord,
+  createQueuedMailPayload,
+  createResolvedMail,
+  createSmtpAddress,
+  createSmtpAttachment,
+  createSmtpHeaders,
+  createSmtpMessage,
+  createSendContext,
+  createResolvedMailFromQueuedPayload,
+  computePreview,
+  createMarkdownWrapperProps,
+  createPreviewHtml,
+  createPreviewPolicy,
+  deferSendUntilCommit,
+  deliverResolvedMail,
+  deserializeQueuedAttachment,
+  dispatchQueuedMail,
+  dynamicImport,
+  ensureMailQueueJobRegistered,
+  escapeHtml,
+  formatAddress,
+  freezeSendResult,
+  getFakeSentState,
+  getMailerConfig,
+  getPreviewArtifactState,
+  getResolvedConfig,
+  getRuntimeBindings,
+  getRuntimeState,
+  loadDbModule,
+  loadNodemailerModule,
+  loadQueueModule,
+  loadStorageModule,
+  isQueueRequested,
+  normalizeExecutionDelay,
+  normalizeExecutionString,
+  normalizeDriverResult,
+  persistPreviewArtifact,
+  prepareMailSend,
+  renderContent,
+  renderMarkdown,
+  renderMarkdownInline,
+  renderPreviewResponse,
+  renderView,
+  resolveDriver,
+  resolveDriverByName,
+  resolveCurrentEnvironment,
+  resolveEnvelope,
+  resolveQueuePlan,
+  resolveMailInput,
+  resolveMailerName,
+  resolveNodemailerModule,
+  resolveSourceKind,
+  resolveStorageModule,
+  runQueuedMailDelivery,
+  sendViaSmtp,
+  serializeQueuedAttachment,
+  setDbModuleLoader(loader) {
+    getRuntimeState().loadDbModule = loader;
+  },
+  setNodemailerModuleLoader(loader) {
+    getRuntimeState().loadNodemailerModule = loader;
+  },
+  setQueueModuleLoader(loader) {
+    getRuntimeState().loadQueueModule = loader;
+  },
+  setStorageModuleLoader(loader) {
+    getRuntimeState().loadStorageModule = loader;
+  },
+  stripMarkdownSyntax
+};
+
+// src/index.ts
+import { defineMailConfig } from "@holo-js/config";
+var mail = Object.freeze({
+  previewMail,
+  renderMailPreview,
+  sendMail
+});
+var src_default = mail;
+export {
+  MailError,
+  MailPreviewDisabledError,
+  MailPreviewFormatUnavailableError,
+  MailSendError,
+  attachContent,
+  attachFromPath,
+  attachFromStorage,
+  configureMailRuntime,
+  createAttachmentMetadata,
+  createAttachmentResolutionPlan,
+  createAttachmentResolutionPlans,
+  src_default as default,
+  defineMail,
+  defineMailConfig,
+  getMailRuntime,
+  getMailRuntimeBindings,
+  getRegisteredMailDriver,
+  inferMimeTypeFromName,
+  isAttachmentQueueSafe,
+  isMailDefinition,
+  listFakeSentMails,
+  listPreviewMailArtifacts,
+  listRegisteredMailDrivers,
+  mailInternals,
+  mailRegistryInternals,
+  mailRuntimeInternals,
+  mergeMailDefinitionInputs,
+  normalizeMailDefinition,
+  previewMail,
+  registerMailDriver,
+  renderMailPreview,
+  resetFakeSentMails,
+  resetMailDriverRegistry,
+  resetMailRuntime,
+  resetPreviewMailArtifacts,
+  resolveAttachmentDefinition,
+  resolveNormalizedAttachment,
+  sendMail
+};