@holo-js/mail 0.1.3

package/dist/chunk-UB6ANQ2F.mjs

@@ -0,0 +1,552 @@
+// src/contracts.ts
+import { defineMailConfig } from "@holo-js/config";
+var HOLO_MAIL_DEFINITION_MARKER = /* @__PURE__ */ Symbol.for("holo-js.mail.definition");
+var BUILT_IN_MAIL_DRIVERS = ["preview", "log", "fake", "smtp"];
+var MAIL_PRIORITY_VALUES = ["high", "normal", "low"];
+var MAIL_ATTACHMENT_DISPOSITIONS = ["attachment", "inline"];
+function isObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeOptionalString(value, label) {
+  if (typeof value === "undefined") {
+    return void 0;
+  }
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(`[@holo-js/mail] ${label} must be a non-empty string when provided.`);
+  }
+  return normalized;
+}
+function normalizeRequiredString(value, label) {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(`[@holo-js/mail] ${label} must be a non-empty string.`);
+  }
+  return normalized;
+}
+function normalizeDelayValue(value, label) {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || value < 0) {
+      throw new Error(`[@holo-js/mail] ${label} must be a finite number greater than or equal to 0.`);
+    }
+    return value;
+  }
+  if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+    throw new Error(`[@holo-js/mail] ${label} dates must be valid Date instances.`);
+  }
+  return value;
+}
+function normalizeJsonValue(value, label) {
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return Object.freeze(value.map((entry, index) => normalizeJsonValue(entry, `${label}[${index}]`)));
+  }
+  if (isObject(value)) {
+    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, entry]) => {
+      return [key, normalizeJsonValue(entry, `${label}.${key}`)];
+    })));
+  }
+  throw new Error(`[@holo-js/mail] ${label} must be JSON-serializable.`);
+}
+function normalizeHeaders(headers) {
+  if (!headers) {
+    return Object.freeze({});
+  }
+  if (!isObject(headers)) {
+    throw new Error("[@holo-js/mail] Mail headers must be a plain object when provided.");
+  }
+  return Object.freeze(Object.fromEntries(Object.entries(headers).map(([key, value]) => {
+    const normalizedKey = normalizeRequiredString(key, "Mail header name");
+    if (typeof value !== "string") {
+      throw new Error(`[@holo-js/mail] Mail header "${normalizedKey}" must be a string.`);
+    }
+    return [normalizedKey, value];
+  })));
+}
+function normalizeTags(tags) {
+  if (typeof tags === "undefined") {
+    return Object.freeze([]);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const normalized = [];
+  for (const tag of tags) {
+    const value = normalizeRequiredString(tag, "Mail tag");
+    if (!seen.has(value)) {
+      seen.add(value);
+      normalized.push(value);
+    }
+  }
+  return Object.freeze(normalized);
+}
+function normalizeViewIdentifier(value, label) {
+  const normalized = normalizeRequiredString(value, label);
+  if (normalized.startsWith("/") || normalized.includes("\\")) {
+    throw new Error(`[@holo-js/mail] ${label} must be a relative mail view identifier.`);
+  }
+  const segments = normalized.split("/");
+  if (segments.some((segment) => segment === "." || segment === ".." || !segment.trim())) {
+    throw new Error(`[@holo-js/mail] ${label} must not include empty, "." or ".." path segments.`);
+  }
+  return normalized;
+}
+function isValidEmail(value) {
+  if (value.includes(" ")) {
+    return false;
+  }
+  const parts = value.split("@");
+  return parts.length === 2 && parts[0].length > 0 && parts[1].length > 0;
+}
+function normalizeAddress(input, label) {
+  const value = typeof input === "string" ? { email: input } : input;
+  if (!isObject(value) || typeof value.email !== "string") {
+    throw new Error(`[@holo-js/mail] ${label} must be an email string or an object with email.`);
+  }
+  const email = normalizeRequiredString(value.email, `${label} email`).toLowerCase();
+  if (!isValidEmail(email)) {
+    throw new Error(`[@holo-js/mail] ${label} email must be a valid email address.`);
+  }
+  const name = typeof value.name === "string" ? normalizeOptionalString(value.name, `${label} name`) : void 0;
+  return Object.freeze({
+    email,
+    ...name ? { name } : {}
+  });
+}
+function normalizeRecipients(value, label, required) {
+  if (typeof value === "undefined") {
+    if (required) {
+      throw new Error(`[@holo-js/mail] ${label} must include at least one recipient.`);
+    }
+    return Object.freeze([]);
+  }
+  const inputs = Array.isArray(value) ? value : [value];
+  const recipients = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of inputs) {
+    const normalized = normalizeAddress(entry, label);
+    if (!seen.has(normalized.email)) {
+      seen.add(normalized.email);
+      recipients.push(normalized);
+    }
+  }
+  if (required && recipients.length === 0) {
+    throw new Error(`[@holo-js/mail] ${label} must include at least one recipient.`);
+  }
+  return Object.freeze(recipients);
+}
+function normalizePriority(value) {
+  if (typeof value === "undefined") {
+    return void 0;
+  }
+  if (MAIL_PRIORITY_VALUES.includes(value)) {
+    return value;
+  }
+  throw new Error(`[@holo-js/mail] Mail priority must be one of: ${MAIL_PRIORITY_VALUES.join(", ")}.`);
+}
+function normalizeAttachmentDisposition(value) {
+  return value === "inline" ? "inline" : "attachment";
+}
+function normalizeAttachmentContentId(value, disposition) {
+  if (typeof value === "undefined") {
+    if (disposition === "inline") {
+      throw new Error("[@holo-js/mail] Inline attachments must define a contentId.");
+    }
+    return void 0;
+  }
+  const normalized = normalizeRequiredString(value.replace(/^<|>$/g, ""), "Mail attachment contentId");
+  if (disposition === "inline" && !normalized) {
+    throw new Error("[@holo-js/mail] Inline attachments must define a contentId.");
+  }
+  return normalized;
+}
+function inferAttachmentName(value) {
+  if (typeof value.name === "string" && value.name.trim()) {
+    return value.name.trim();
+  }
+  if ("path" in value) {
+    const parts = value.path.split("/");
+    return parts[parts.length - 1]?.trim() || void 0;
+  }
+  if ("storage" in value) {
+    const parts = value.storage.path.split("/");
+    return parts[parts.length - 1]?.trim() || void 0;
+  }
+  return void 0;
+}
+var ATTACHMENT_MIME_TYPES = Object.freeze({
+  csv: "text/csv",
+  gif: "image/gif",
+  htm: "text/html",
+  html: "text/html",
+  jpeg: "image/jpeg",
+  jpg: "image/jpeg",
+  json: "application/json",
+  md: "text/markdown",
+  pdf: "application/pdf",
+  png: "image/png",
+  svg: "image/svg+xml",
+  txt: "text/plain",
+  webp: "image/webp",
+  xml: "application/xml"
+});
+function inferMimeTypeFromName(name) {
+  if (!name) {
+    return void 0;
+  }
+  const extension = name.split(".").pop()?.trim().toLowerCase();
+  if (!extension) {
+    return void 0;
+  }
+  return ATTACHMENT_MIME_TYPES[extension];
+}
+function inferAttachmentSource(value) {
+  if ("path" in value) {
+    return "path";
+  }
+  if ("storage" in value) {
+    return "storage";
+  }
+  if ("content" in value) {
+    return "content";
+  }
+  return "resolve";
+}
+function createAttachmentMetadata(attachment) {
+  return Object.freeze({
+    source: inferAttachmentSource(attachment),
+    name: inferAttachmentName(attachment),
+    contentType: attachment.contentType ?? inferMimeTypeFromName(inferAttachmentName(attachment)),
+    disposition: attachment.disposition ?? "attachment",
+    contentId: attachment.contentId
+  });
+}
+function normalizeAttachment(input, index) {
+  if (!isObject(input)) {
+    throw new Error(`[@holo-js/mail] Mail attachment #${index + 1} must be a plain object.`);
+  }
+  const disposition = normalizeAttachmentDisposition(input.disposition);
+  const contentId = normalizeAttachmentContentId(input.contentId, disposition);
+  const name = inferAttachmentName(input);
+  const contentType = typeof input.contentType === "string" ? normalizeRequiredString(input.contentType, `Mail attachment #${index + 1} contentType`) : inferMimeTypeFromName(name);
+  const base = {
+    ...name ? { name } : {},
+    ...contentType ? { contentType } : {},
+    disposition,
+    ...contentId ? { contentId } : {}
+  };
+  if ("path" in input) {
+    if (typeof input.path !== "string") {
+      throw new Error(`[@holo-js/mail] Mail attachment #${index + 1} path attachments must include a path.`);
+    }
+    return Object.freeze({
+      ...base,
+      path: normalizeRequiredString(input.path, `Mail attachment #${index + 1} path`)
+    });
+  }
+  if ("storage" in input) {
+    if (!isObject(input.storage) || typeof input.storage.path !== "string") {
+      throw new Error(`[@holo-js/mail] Mail attachment #${index + 1} storage attachments must include a path.`);
+    }
+    return Object.freeze({
+      ...base,
+      storage: Object.freeze({
+        path: normalizeRequiredString(input.storage.path, `Mail attachment #${index + 1} storage path`),
+        ...typeof input.storage.disk === "string" ? { disk: normalizeRequiredString(input.storage.disk, `Mail attachment #${index + 1} storage disk`) } : {}
+      })
+    });
+  }
+  if ("content" in input) {
+    if (!(typeof input.content === "string" || input.content instanceof Uint8Array)) {
+      throw new Error(`[@holo-js/mail] Mail attachment #${index + 1} content attachments must use a string or Uint8Array.`);
+    }
+    const attachmentName = name ?? normalizeOptionalString(input.name, `Mail attachment #${index + 1} name`);
+    if (!attachmentName) {
+      throw new Error(`[@holo-js/mail] Mail attachment #${index + 1} content attachments must define a name.`);
+    }
+    return Object.freeze({
+      ...base,
+      name: attachmentName,
+      content: input.content
+    });
+  }
+  if ("resolve" in input) {
+    if (typeof input.resolve !== "function") {
+      throw new Error(`[@holo-js/mail] Mail attachment #${index + 1} resolve attachments must define resolve().`);
+    }
+    return Object.freeze({
+      ...base,
+      resolve: input.resolve
+    });
+  }
+  throw new Error(`[@holo-js/mail] Mail attachment #${index + 1} must define path, storage, content, or resolve.`);
+}
+function normalizeAttachments(attachments) {
+  if (typeof attachments === "undefined") {
+    return Object.freeze([]);
+  }
+  return Object.freeze(attachments.map((attachment, index) => normalizeAttachment(attachment, index)));
+}
+function resolveNormalizedAttachment(attachment) {
+  const metadata = createAttachmentMetadata(attachment);
+  const name = metadata.name;
+  if (!name) {
+    throw new Error("[@holo-js/mail] Attachments must resolve to a named attachment before sending.");
+  }
+  if ("path" in attachment) {
+    return Object.freeze({
+      ...metadata,
+      name,
+      path: attachment.path
+    });
+  }
+  if ("storage" in attachment) {
+    return Object.freeze({
+      ...metadata,
+      name,
+      storage: attachment.storage
+    });
+  }
+  if ("content" in attachment) {
+    return Object.freeze({
+      ...metadata,
+      name,
+      content: attachment.content
+    });
+  }
+  throw new Error("[@holo-js/mail] Resolver attachments must be resolved before creating transport attachments.");
+}
+function isAttachmentQueueSafe(attachment) {
+  return !("resolve" in attachment);
+}
+async function resolveAttachmentDefinition(attachment) {
+  if (!("resolve" in attachment)) {
+    return attachment;
+  }
+  const resolvedPayload = await attachment.resolve();
+  if (!isObject(resolvedPayload)) {
+    throw new Error("[@holo-js/mail] Attachment resolvers must return a plain object payload.");
+  }
+  const merged = {
+    ...resolvedPayload,
+    ...attachment.name ? { name: attachment.name } : {},
+    ...attachment.contentType ? { contentType: attachment.contentType } : {},
+    ...attachment.disposition ? { disposition: attachment.disposition } : {},
+    ...attachment.contentId ? { contentId: attachment.contentId } : {}
+  };
+  const normalized = normalizeAttachment(merged, 0);
+  if ("resolve" in normalized) {
+    throw new Error("[@holo-js/mail] Attachment resolvers must resolve to a path, storage, or content attachment.");
+  }
+  return normalized;
+}
+function createAttachmentResolutionPlan(attachment, context) {
+  const metadata = createAttachmentMetadata(attachment);
+  const queuedSafe = isAttachmentQueueSafe(attachment);
+  if (context.queued && !queuedSafe) {
+    throw new Error("[@holo-js/mail] Resolver attachments are not queue-safe and cannot be used when queueing is requested.");
+  }
+  return Object.freeze({
+    ...metadata,
+    queuedSafe,
+    async resolve() {
+      const normalized = await resolveAttachmentDefinition(attachment);
+      return resolveNormalizedAttachment(normalized);
+    }
+  });
+}
+function createAttachmentResolutionPlans(attachments, context) {
+  return Object.freeze(attachments.map((attachment) => createAttachmentResolutionPlan(attachment, context)));
+}
+function normalizeRenderSource(render) {
+  if (typeof render === "undefined") {
+    return void 0;
+  }
+  if (!isObject(render)) {
+    throw new Error("[@holo-js/mail] Mail render sources must be plain objects when provided.");
+  }
+  return Object.freeze({
+    view: normalizeViewIdentifier(render.view, "Mail render view"),
+    ...typeof render.props === "undefined" ? {} : { props: normalizeJsonValue(render.props, "Mail render props") }
+  });
+}
+function normalizeQueueOptions(value) {
+  if (typeof value === "undefined" || typeof value === "boolean") {
+    return value;
+  }
+  return Object.freeze({
+    ...typeof value.queued === "boolean" ? { queued: value.queued } : {},
+    ...typeof value.connection === "string" ? { connection: normalizeRequiredString(value.connection, "Mail queue connection") } : {},
+    ...typeof value.queue === "string" ? { queue: normalizeRequiredString(value.queue, "Mail queue name") } : {},
+    ...typeof value.afterCommit === "boolean" ? { afterCommit: value.afterCommit } : {}
+  });
+}
+function normalizeTextLikeContent(value, label) {
+  if (typeof value === "undefined") {
+    return void 0;
+  }
+  return normalizeRequiredString(value, label);
+}
+function normalizeContentSource(input) {
+  const text = normalizeTextLikeContent(input.text, "Mail text");
+  const html = normalizeTextLikeContent(input.html, "Mail html");
+  const markdown = normalizeTextLikeContent(input.markdown, "Mail markdown");
+  const render = normalizeRenderSource(input.render);
+  const markdownWrapper = typeof input.markdownWrapper === "string" ? normalizeViewIdentifier(input.markdownWrapper, "Mail markdown wrapper") : void 0;
+  const primaryKinds = [
+    typeof html === "string" ? "html" : void 0,
+    typeof markdown === "string" ? "markdown" : void 0,
+    render ? "render" : void 0,
+    typeof text === "string" && !html && !markdown && !render ? "text" : void 0
+  ].filter(Boolean);
+  if (primaryKinds.length !== 1) {
+    throw new Error("[@holo-js/mail] Mail definitions must define exactly one primary content source.");
+  }
+  if (markdownWrapper && !markdown) {
+    throw new Error("[@holo-js/mail] Mail markdown wrappers are only valid for markdown mails.");
+  }
+  return {
+    ...typeof text === "string" ? { text } : {},
+    ...typeof html === "string" ? { html } : {},
+    ...typeof markdown === "string" ? { markdown } : {},
+    ...render ? { render } : {},
+    ...markdownWrapper ? { markdownWrapper } : {}
+  };
+}
+function isMailDefinition(value) {
+  return !!value && typeof value === "object" && value[HOLO_MAIL_DEFINITION_MARKER] === true;
+}
+function mergeMailDefinitionInputs(base, overrides) {
+  if (!overrides || Object.keys(overrides).length === 0) {
+    return isMailDefinition(base) ? { ...base } : { ...base };
+  }
+  return {
+    ...base,
+    ...overrides,
+    headers: {
+      ...base.headers ?? {},
+      ...overrides.headers ?? {}
+    },
+    metadata: {
+      ...base.metadata ?? {},
+      ...overrides.metadata ?? {}
+    }
+  };
+}
+function normalizeMailDefinition(input) {
+  if (isMailDefinition(input)) {
+    return input;
+  }
+  if (!isObject(input)) {
+    throw new Error("[@holo-js/mail] Mail definitions must be plain objects.");
+  }
+  const subject = normalizeRequiredString(input.subject, "Mail subject");
+  const mailer = typeof input.mailer === "string" ? normalizeRequiredString(input.mailer, "Mail mailer") : void 0;
+  const from = typeof input.from !== "undefined" ? normalizeAddress(input.from, "Mail from") : void 0;
+  const replyTo = typeof input.replyTo !== "undefined" ? normalizeAddress(input.replyTo, "Mail replyTo") : void 0;
+  const metadata = typeof input.metadata === "undefined" ? void 0 : normalizeJsonValue(input.metadata, "Mail metadata");
+  const normalized = {
+    ...mailer ? { mailer } : {},
+    ...from ? { from } : {},
+    ...replyTo ? { replyTo } : {},
+    to: normalizeRecipients(input.to, "Mail to", true),
+    cc: normalizeRecipients(input.cc, "Mail cc", false),
+    bcc: normalizeRecipients(input.bcc, "Mail bcc", false),
+    subject,
+    ...normalizeContentSource(input),
+    attachments: normalizeAttachments(input.attachments),
+    headers: normalizeHeaders(input.headers),
+    tags: normalizeTags(input.tags),
+    ...metadata ? { metadata } : {},
+    ...normalizePriority(input.priority) ? { priority: normalizePriority(input.priority) } : {},
+    ...typeof input.queue === "undefined" ? {} : { queue: normalizeQueueOptions(input.queue) },
+    ...typeof input.delay === "undefined" ? {} : { delay: normalizeDelayValue(input.delay, "Mail delay") }
+  };
+  Object.defineProperty(normalized, HOLO_MAIL_DEFINITION_MARKER, {
+    value: true,
+    enumerable: false
+  });
+  return Object.freeze(normalized);
+}
+function defineMail(input) {
+  return normalizeMailDefinition(input);
+}
+function attachFromPath(path, options = {}) {
+  return Object.freeze({
+    path,
+    ...options
+  });
+}
+function attachFromStorage(path, options = {}) {
+  return Object.freeze({
+    storage: Object.freeze({
+      path,
+      ...typeof options.disk === "string" ? { disk: options.disk } : {}
+    }),
+    ...typeof options.name === "string" ? { name: options.name } : {},
+    ...typeof options.contentType === "string" ? { contentType: options.contentType } : {},
+    ...typeof options.disposition === "string" ? { disposition: options.disposition } : {},
+    ...typeof options.contentId === "string" ? { contentId: options.contentId } : {}
+  });
+}
+function attachContent(content, options) {
+  return Object.freeze({
+    content,
+    ...options
+  });
+}
+var mailInternals = {
+  BUILT_IN_MAIL_DRIVERS,
+  HOLO_MAIL_DEFINITION_MARKER,
+  MAIL_ATTACHMENT_DISPOSITIONS,
+  MAIL_PRIORITY_VALUES,
+  attachContent,
+  attachFromPath,
+  attachFromStorage,
+  createAttachmentMetadata,
+  createAttachmentResolutionPlan,
+  createAttachmentResolutionPlans,
+  inferMimeTypeFromName,
+  inferAttachmentName,
+  inferAttachmentSource,
+  isObject,
+  isAttachmentQueueSafe,
+  isValidEmail,
+  mergeMailDefinitionInputs,
+  normalizeAddress,
+  normalizeAttachment,
+  normalizeAttachments,
+  normalizeDelayValue,
+  normalizeHeaders,
+  normalizeJsonValue,
+  normalizeMailDefinition,
+  normalizeOptionalString,
+  normalizePriority,
+  normalizeQueueOptions,
+  normalizeRecipients,
+  normalizeRenderSource,
+  normalizeRequiredString,
+  resolveAttachmentDefinition,
+  resolveNormalizedAttachment,
+  normalizeTags,
+  normalizeViewIdentifier
+};
+
+export {
+  defineMailConfig,
+  inferMimeTypeFromName,
+  createAttachmentMetadata,
+  resolveNormalizedAttachment,
+  isAttachmentQueueSafe,
+  resolveAttachmentDefinition,
+  createAttachmentResolutionPlan,
+  createAttachmentResolutionPlans,
+  isMailDefinition,
+  mergeMailDefinitionInputs,
+  normalizeMailDefinition,
+  defineMail,
+  attachFromPath,
+  attachFromStorage,
+  attachContent,
+  mailInternals
+};