@dotpress/mailer 0.0.0-stage → 2.0.0-alpha.1

package/dist/index.js

@@ -0,0 +1,649 @@
+import {
+  MailDataError,
+  MailMessageError,
+  MailRenderError,
+  MailSendError,
+  MailerError,
+  checkKeys,
+  formatAddress,
+  parseAddress,
+  parseEnvelope,
+  parseRecipients,
+  toSubject
+} from "./chunk-QYVN5N3B.js";
+
+// src/render.ts
+import mustache from "mustache";
+
+// src/locales.ts
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var collectLocales = (prefix, entries) => {
+  let locales;
+  let reference = "";
+  for (const [label, value] of entries) {
+    if (!isRecord(value)) {
+      throw new TypeError(
+        `${prefix}: ${label} must be an object of texts by locale.`
+      );
+    }
+    const keys = Object.keys(value).sort();
+    if (keys.length === 0) {
+      throw new TypeError(`${prefix}: ${label} has no locale.`);
+    }
+    for (const key of keys) {
+      if (typeof value[key] !== "string") {
+        throw new TypeError(`${prefix}: ${label}.${key} must be a string.`);
+      }
+    }
+    if (locales === void 0) {
+      locales = keys;
+      reference = label;
+    } else if (keys.join() !== locales.join()) {
+      throw new TypeError(
+        `${prefix}: ${label} has the locales ${keys.join(", ")}, but ${reference} has ${locales.join(", ")}. Every text needs the same locales.`
+      );
+    }
+  }
+  return locales ?? [];
+};
+var translationEntries = (prefix, translations) => {
+  if (translations === void 0) return [];
+  if (!isRecord(translations)) {
+    throw new TypeError(`${prefix}: translations must be an object.`);
+  }
+  return Object.entries(translations).map(([key, value]) => [
+    `translations.${key}`,
+    value
+  ]);
+};
+var baseOf = (locale) => locale.split(/[-_]/)[0] ?? locale;
+var resolveLocale = (available, requested, defaultLocale) => {
+  const candidates = [requested, defaultLocale].flatMap(
+    (locale) => locale ? [locale, baseOf(locale)] : []
+  );
+  for (const candidate of candidates) {
+    const lower = candidate.toLowerCase();
+    const match = available.find((locale) => locale.toLowerCase() === lower);
+    if (match !== void 0) return match;
+  }
+  return void 0;
+};
+
+// src/template.ts
+var layouts = /* @__PURE__ */ new WeakMap();
+var templates = /* @__PURE__ */ new WeakMap();
+var definitionOf = (template) => templates.get(template);
+var LAYOUT_OPTIONS = /* @__PURE__ */ new Set(["translations", "mjml", "html"]);
+var TEMPLATE_OPTIONS = /* @__PURE__ */ new Set([
+  "name",
+  "layout",
+  "schema",
+  "subject",
+  "translations",
+  "text",
+  "mjml",
+  "html"
+]);
+var checkOptions = (prefix, options, allowed) => {
+  if (typeof options !== "object" || options === null || Array.isArray(options)) {
+    throw new TypeError(`${prefix}: expected an object.`);
+  }
+  for (const key of Object.keys(options)) {
+    if (!allowed.has(key)) {
+      throw new TypeError(`${prefix}: unknown option "${key}".`);
+    }
+  }
+  return options;
+};
+var formatOf = (prefix, options, isValid, expected) => {
+  const formats = ["mjml", "html"].filter(
+    (format2) => options[format2] !== void 0
+  );
+  const [format] = formats;
+  if (format === void 0 || formats.length > 1) {
+    throw new TypeError(`${prefix}: set exactly one of mjml and html.`);
+  }
+  if (!isValid(options[format])) {
+    throw new TypeError(`${prefix}: ${format} must be ${expected}.`);
+  }
+  return format;
+};
+var isSource = (source) => typeof source === "string" || typeof source === "function";
+var defineLayout = (options) => {
+  const prefix = "Invalid mail layout";
+  const values = checkOptions(prefix, options, LAYOUT_OPTIONS);
+  const format = formatOf(
+    prefix,
+    values,
+    (source) => typeof source === "function",
+    "a function that receives the template content"
+  );
+  const locales = collectLocales(
+    prefix,
+    translationEntries(prefix, values.translations)
+  );
+  const layout = Object.freeze({
+    format,
+    locales: Object.freeze(locales)
+  });
+  layouts.set(layout, {
+    format,
+    translations: values.translations ?? {},
+    render: values[format]
+  });
+  return layout;
+};
+var defineTemplate = (options) => {
+  const name = options?.name;
+  const prefix = typeof name === "string" && name !== "" ? `Invalid mail template "${name}"` : "Invalid mail template";
+  const values = checkOptions(prefix, options, TEMPLATE_OPTIONS);
+  if (typeof name !== "string" || name === "") {
+    throw new TypeError(`${prefix}: name must be a non-empty string.`);
+  }
+  const format = formatOf(prefix, values, isSource, "a string or a function");
+  const { layout, schema, subject, text } = values;
+  let layoutDefinition;
+  if (layout !== void 0) {
+    layoutDefinition = layouts.get(layout);
+    if (!layoutDefinition) {
+      throw new TypeError(
+        `${prefix}: layout must be created by defineLayout().`
+      );
+    }
+    if (layoutDefinition.format !== format) {
+      throw new TypeError(
+        `${prefix}: the template is in ${format}, but its layout is in ${layoutDefinition.format}.`
+      );
+    }
+  }
+  if (schema !== void 0 && typeof schema?.safeParseAsync !== "function") {
+    throw new TypeError(`${prefix}: schema must be a Zod schema.`);
+  }
+  if (typeof subject !== "string" && typeof subject !== "object") {
+    throw new TypeError(
+      `${prefix}: subject must be a string or an object of texts by locale.`
+    );
+  }
+  if (text !== void 0 && !isSource(text)) {
+    throw new TypeError(`${prefix}: text must be a string or a function.`);
+  }
+  const own = collectLocales(prefix, [
+    ...typeof subject === "object" ? [["subject", subject]] : [],
+    ...translationEntries(prefix, values.translations)
+  ]);
+  const layoutLocales = layout ? layout.locales : [];
+  if (own.length > 0 && layoutLocales.length > 0) {
+    const missing = own.filter((locale) => !layoutLocales.includes(locale));
+    if (missing.length > 0) {
+      throw new TypeError(
+        `${prefix}: its layout has no translations in ${missing.join(", ")}.`
+      );
+    }
+  }
+  const locales = own.length > 0 ? own : [...layoutLocales];
+  const template = Object.freeze({
+    name,
+    format,
+    locales: Object.freeze(locales)
+  });
+  templates.set(template, {
+    name,
+    format,
+    locales,
+    source: values[format],
+    layout: layoutDefinition,
+    schema,
+    subject,
+    translations: values.translations ?? {},
+    text,
+    cache: /* @__PURE__ */ new Map()
+  });
+  return template;
+};
+
+// src/render.ts
+var HTML_ENTITIES = {
+  "&": "&",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;"
+};
+var escapeHtml = (value) => String(value).replace(/[&<>"']/g, (char) => HTML_ENTITIES[char]);
+var noEscape = (value) => String(value);
+var mjmlModule;
+var htmlToTextModule;
+var loadMjml = () => mjmlModule ??= import("mjml").then(
+  (module) => module.default,
+  (error) => {
+    mjmlModule = void 0;
+    throw error;
+  }
+);
+var loadHtmlToText = () => htmlToTextModule ??= import("html-to-text").then(
+  (module) => module,
+  (error) => {
+    htmlToTextModule = void 0;
+    throw error;
+  }
+);
+var isMjmlMissing = (error) => error instanceof Error && (error.code === "ERR_MODULE_NOT_FOUND" && error.message.includes("'mjml'") || isMjmlMissing(error.cause));
+var describeMjmlError = (error) => {
+  const issues = error?.errors;
+  if (Array.isArray(issues) && issues.length > 0) {
+    return issues.map(
+      ({ line, tagName, message }) => `line ${line} (${tagName}): ${message}`
+    ).join("; ");
+  }
+  return error instanceof Error ? error.message : String(error);
+};
+var compileMjml = async (name, source) => {
+  let mjml;
+  try {
+    mjml = await loadMjml();
+  } catch (error) {
+    throw new MailRenderError(
+      name,
+      isMjmlMissing(error) ? "MJML is not installed. Install the mjml package, or use html templates." : "MJML could not be loaded.",
+      { cause: error }
+    );
+  }
+  try {
+    const { html } = await mjml(source, {
+      validationLevel: "strict",
+      ignoreIncludes: true
+    });
+    return html;
+  } catch (error) {
+    throw new MailRenderError(
+      name,
+      `invalid MJML: ${describeMjmlError(error)}`,
+      { cause: error }
+    );
+  }
+};
+var toText = async (html) => {
+  const { convert } = await loadHtmlToText();
+  return convert(html, {
+    wordwrap: 78,
+    selectors: [
+      { selector: "img", format: "skip" },
+      // Preview text and other content hidden from readers.
+      { selector: '[style*="display:none"]', format: "skip" },
+      { selector: '[style*="display: none"]', format: "skip" },
+      { selector: "a", options: { hideLinkHrefIfSameAsText: true } }
+    ]
+  });
+};
+var translator = (name, owner, translations, locale) => (key) => {
+  const entry = Object.hasOwn(translations, key) ? translations[key] : void 0;
+  const text = entry?.[locale];
+  if (text === void 0) {
+    throw new MailRenderError(
+      name,
+      `unknown translation key "${key}" in the ${owner}.`
+    );
+  }
+  return text;
+};
+var produce = (name, owner, source, context) => {
+  if (typeof source === "string") return source;
+  let result;
+  try {
+    result = source(context);
+  } catch (error) {
+    if (error instanceof MailRenderError) throw error;
+    throw new MailRenderError(name, `the ${owner} source function failed.`, {
+      cause: error
+    });
+  }
+  if (typeof result !== "string") {
+    throw new MailRenderError(
+      name,
+      `the ${owner} source function must return a string.`
+    );
+  }
+  return result;
+};
+var contextOf = (definition, locale) => ({
+  locale,
+  t: translator(definition.name, "template", definition.translations, locale)
+});
+var compile = async (definition, locale) => {
+  const { name, layout } = definition;
+  let source = produce(
+    name,
+    "template",
+    definition.source,
+    contextOf(definition, locale)
+  );
+  if (layout) {
+    source = produce(name, "layout", layout.render, {
+      locale,
+      t: translator(name, "layout", layout.translations, locale),
+      content: source
+    });
+  }
+  return definition.format === "mjml" ? compileMjml(name, source) : source;
+};
+var compiled = (definition, locale) => {
+  const key = locale ?? "";
+  let html = definition.cache.get(key);
+  if (!html) {
+    html = compile(definition, locale);
+    definition.cache.set(key, html);
+    html.catch(() => definition.cache.delete(key));
+  }
+  return html;
+};
+var renderMustache = (name, part, source, data, escape) => {
+  try {
+    return mustache.render(source, data, {}, { escape });
+  } catch (error) {
+    throw new MailRenderError(
+      name,
+      `invalid Mustache in the ${part}: ${error.message}`,
+      { cause: error }
+    );
+  }
+};
+var parseData = async (definition, data) => {
+  const { name, schema } = definition;
+  if (!schema) {
+    if (data !== void 0) {
+      throw new MailDataError(name, [
+        { path: [], message: "the template has no schema and accepts no data" }
+      ]);
+    }
+    return {};
+  }
+  const result = await schema.safeParseAsync(data);
+  if (!result.success) {
+    throw new MailDataError(
+      name,
+      result.error.issues.map(({ path, message }) => ({
+        path: path.map((key) => typeof key === "symbol" ? String(key) : key),
+        message
+      }))
+    );
+  }
+  const parsed = result.data;
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new MailDataError(name, [
+      { path: [], message: "the schema must produce an object" }
+    ]);
+  }
+  return parsed;
+};
+var subjectSource = (definition, locale) => {
+  const { subject } = definition;
+  if (typeof subject === "string") return subject;
+  return subject[locale];
+};
+var renderMail = async (template, options) => {
+  const definition = definitionOf(template);
+  if (!definition) {
+    throw new TypeError(
+      "renderMail(): expected a template created by defineTemplate()."
+    );
+  }
+  const { name, locales } = definition;
+  const { locale: requested, defaultLocale } = options ?? {};
+  const data = await parseData(definition, options?.data);
+  let locale;
+  if (locales.length > 0) {
+    locale = resolveLocale(locales, requested, defaultLocale);
+    if (locale === void 0) {
+      const asked = [requested, defaultLocale].filter(Boolean);
+      throw new MailRenderError(
+        name,
+        asked.length > 0 ? `no translations for ${asked.join(" or ")} (available: ${locales.join(", ")}).` : `no locale requested and no default locale (available: ${locales.join(", ")}).`
+      );
+    }
+  }
+  const html = renderMustache(
+    name,
+    "HTML",
+    await compiled(definition, locale),
+    data,
+    escapeHtml
+  );
+  const subject = toSubject(
+    renderMustache(
+      name,
+      "subject",
+      subjectSource(definition, locale),
+      data,
+      noEscape
+    )
+  );
+  const text = definition.text ? renderMustache(
+    name,
+    "text",
+    produce(name, "text", definition.text, contextOf(definition, locale)),
+    data,
+    noEscape
+  ) : await toText(html);
+  return { template: name, locale, subject, html, text };
+};
+
+// src/mailer.ts
+var MAILER_OPTIONS = /* @__PURE__ */ new Set([
+  "provider",
+  "from",
+  "replyTo",
+  "defaultLocale",
+  "logger"
+]);
+var ENVELOPE_OPTIONS = [
+  "to",
+  "cc",
+  "bcc",
+  "replyTo",
+  "from",
+  "attachments",
+  "headers",
+  "tags",
+  "metadata",
+  "subject"
+];
+var SEND_OPTIONS = /* @__PURE__ */ new Set([...ENVELOPE_OPTIONS, "locale", "data"]);
+var MESSAGE_OPTIONS = /* @__PURE__ */ new Set([...ENVELOPE_OPTIONS, "html", "text"]);
+var checkLogger = (logger) => {
+  if (typeof logger?.info !== "function") {
+    throw new TypeError("Invalid mailer logger: expected an info() method.");
+  }
+};
+var freeze = (message) => {
+  for (const value of Object.values(message)) {
+    if (typeof value === "object" && value !== null) Object.freeze(value);
+  }
+  return Object.freeze(message);
+};
+var createMailer = (options) => {
+  const values = checkKeys("Invalid mailer options", options, MAILER_OPTIONS);
+  const { provider, defaultLocale, logger } = values;
+  if (typeof provider?.name !== "string" || provider.name === "" || typeof provider.send !== "function") {
+    throw new TypeError(
+      "Invalid mailer options: provider must have a name and a send() method."
+    );
+  }
+  if (defaultLocale !== void 0 && (typeof defaultLocale !== "string" || defaultLocale === "")) {
+    throw new TypeError(
+      "Invalid mailer options: defaultLocale must be a non-empty string."
+    );
+  }
+  if (logger !== void 0) checkLogger(logger);
+  if (values.from === void 0) {
+    throw new TypeError("Invalid mailer options: from is required.");
+  }
+  const defaults = {
+    from: parseAddress(values.from, "from"),
+    replyTo: parseRecipients(values.replyTo, "replyTo")
+  };
+  const create = (logger2) => {
+    const deliver = async (envelope, content) => {
+      const message = freeze({ ...envelope, ...content });
+      let result;
+      try {
+        result = await provider.send(message);
+      } catch (error) {
+        if (error instanceof MailerError) throw error;
+        throw new MailSendError(
+          provider.name,
+          error instanceof Error ? error.message : String(error),
+          { cause: error }
+        );
+      }
+      const messageId = typeof result?.messageId === "string" ? result.messageId : void 0;
+      logger2?.info(
+        {
+          provider: provider.name,
+          template: message.template,
+          messageId,
+          recipients: message.to.length + message.cc.length + message.bcc.length
+        },
+        "Mail sent"
+      );
+      return { messageId };
+    };
+    const render = (template, renderOptions) => renderMail(template, {
+      defaultLocale,
+      ...renderOptions
+    });
+    const mailer = {
+      provider,
+      render,
+      send: async (template, sendOptions) => {
+        const { subject, locale, data, ...envelopeOptions } = checkKeys(
+          "mailer.send()",
+          sendOptions,
+          SEND_OPTIONS
+        );
+        if (subject !== void 0 && typeof subject !== "string") {
+          throw new TypeError("mailer.send(): subject must be a string.");
+        }
+        const envelope = parseEnvelope(envelopeOptions, defaults);
+        const mail = await render(template, { locale, data });
+        return deliver(envelope, {
+          subject: subject === void 0 ? mail.subject : toSubject(subject),
+          html: mail.html,
+          text: mail.text,
+          template: mail.template,
+          locale: mail.locale
+        });
+      },
+      sendMessage: async (messageOptions) => {
+        const { subject, html, text, ...envelopeOptions } = checkKeys(
+          "mailer.sendMessage()",
+          messageOptions,
+          MESSAGE_OPTIONS
+        );
+        if (typeof subject !== "string") {
+          throw new TypeError("mailer.sendMessage(): subject must be a string.");
+        }
+        for (const [key, value] of [
+          ["html", html],
+          ["text", text]
+        ]) {
+          if (value !== void 0 && typeof value !== "string") {
+            throw new TypeError(
+              `mailer.sendMessage(): ${key} must be a string.`
+            );
+          }
+        }
+        if (html === void 0 && text === void 0) {
+          throw new TypeError("mailer.sendMessage(): set html, text, or both.");
+        }
+        const envelope = parseEnvelope(envelopeOptions, defaults);
+        return deliver(envelope, {
+          subject: toSubject(subject),
+          html,
+          text: text ?? await toText(html),
+          template: void 0,
+          locale: void 0
+        });
+      },
+      withLogger: (other) => {
+        checkLogger(other);
+        return create(other);
+      }
+    };
+    return Object.freeze(mailer);
+  };
+  return create(logger);
+};
+
+// src/providers/console.ts
+var list = (addresses) => addresses.map(formatAddress).join(", ");
+var createConsoleProvider = (options = {}) => {
+  const { body = false, write = (output) => console.log(output) } = options;
+  return {
+    name: "console",
+    send: async (message) => {
+      const lines = [
+        `[mail] ${message.template ?? "message"}${message.locale ? ` (${message.locale})` : ""}`,
+        `From: ${formatAddress(message.from)}`,
+        `To: ${list(message.to)}`
+      ];
+      for (const [label, addresses] of [
+        ["Cc", message.cc],
+        ["Bcc", message.bcc],
+        ["Reply-To", message.replyTo]
+      ]) {
+        if (addresses.length > 0) lines.push(`${label}: ${list(addresses)}`);
+      }
+      lines.push(`Subject: ${message.subject}`);
+      if (message.attachments.length > 0) {
+        lines.push(
+          `Attachments: ${message.attachments.map(({ filename }) => filename).join(", ")}`
+        );
+      }
+      if (message.tags.length > 0) {
+        lines.push(`Tags: ${message.tags.join(", ")}`);
+      }
+      const metadata = Object.entries(message.metadata);
+      if (metadata.length > 0) {
+        lines.push(
+          `Metadata: ${metadata.map(([key, value]) => `${key}=${value}`).join(", ")}`
+        );
+      }
+      if (body) lines.push("", message.text);
+      write(lines.join("\n"));
+    }
+  };
+};
+
+// src/providers/memory.ts
+var createMemoryProvider = () => {
+  const sent = [];
+  let count = 0;
+  return {
+    name: "memory",
+    sent,
+    send: async (message) => {
+      sent.push(message);
+      count += 1;
+      return { messageId: `memory-${count}` };
+    },
+    last: () => sent.at(-1),
+    clear: () => {
+      sent.length = 0;
+    }
+  };
+};
+export {
+  MailDataError,
+  MailMessageError,
+  MailRenderError,
+  MailSendError,
+  MailerError,
+  createConsoleProvider,
+  createMailer,
+  createMemoryProvider,
+  defineLayout,
+  defineTemplate,
+  formatAddress,
+  renderMail
+};
+//# sourceMappingURL=index.js.map