@maestro-js/mail 1.0.0-alpha.0

package/dist/index.js

@@ -0,0 +1,554 @@
+// src/index.ts
+import "iso-fns2";
+
+// src/mail-types.ts
+function getEmails(address) {
+  const list = Array.isArray(address) ? address : [address];
+  return list.map((a) => typeof a === "string" ? a.trim() : a.email.trim());
+}
+
+// src/send-grid-mail-driver.ts
+import assert from "assert";
+function sendGridMailDriver(sendGrid) {
+  async function send(envelope) {
+    const allEmails = [
+      ...getEmails(envelope.to),
+      ...envelope.cc ? getEmails(envelope.cc) : [],
+      ...envelope.bcc ? getEmails(envelope.bcc) : []
+    ];
+    const from = envelope.from;
+    assert.ok(from, "missing from address");
+    const result = await new Promise(
+      (resolve, reject) => sendGrid.send(
+        {
+          to: envelope.to,
+          cc: envelope.cc,
+          bcc: envelope.bcc,
+          from,
+          subject: envelope.subject ?? void 0,
+          ...envelope.content,
+          attachments: envelope.attachments,
+          category: envelope.category ?? void 0,
+          customArgs: { ...envelope.extras ?? {}, __extraKeys__: JSON.stringify(Object.keys(envelope.extras ?? {})) }
+        },
+        false,
+        (err, result2) => {
+          if (err) return reject(err);
+          resolve(result2[0]);
+        }
+      )
+    );
+    return {
+      success: result.statusCode < 400,
+      messages: allEmails.map((email) => ({ email, id: result.headers["x-message-id"] })),
+      driverName: "sendgrid"
+    };
+  }
+  return {
+    send,
+    toMailEvent(sgEvent) {
+      const sgEventType = sgEvent.event;
+      if (sgEventType === "processed" || sgEventType === "dropped" || sgEventType === "group_unsubscribe" || sgEventType === "group_resubscribe") {
+        return null;
+      } else {
+        const messageId = sgEvent.sg_message_id.split(".")[0];
+        assert.ok(messageId, "missing messageId");
+        const extraKeys = JSON.parse(sgEvent["__extraKeys__"] ?? "[]");
+        const formatted = {
+          eventId: sgEvent.sg_event_id,
+          event: sgEventType === "delivered" ? "delivery" : sgEventType === "spamreport" ? "spamComplaint" : sgEventType,
+          email: sgEvent.email,
+          messageId,
+          timestamp: sgEvent.timestamp * 1e3,
+          category: Array.isArray(sgEvent.category) ? sgEvent.category[0] ?? null : null,
+          extras: Object.fromEntries(extraKeys.map((key) => [key, sgEvent[key]])),
+          driverName: "sendgrid"
+        };
+        return formatted;
+      }
+    }
+  };
+}
+
+// src/mail-trap-mail-driver.ts
+import { Helpers } from "@maestro-js/helpers";
+import assert2 from "assert";
+function mailTrapMailDriver(mailTrap) {
+  async function send(envelope) {
+    function convertAddress(address) {
+      return Array.isArray(address) ? address.map((a) => typeof a === "string" ? { email: a } : a) : [typeof address === "string" ? { email: address } : address];
+    }
+    assert2.ok(envelope.from, "missing from address");
+    const result = await Helpers.retry(
+      () => mailTrap.send({
+        to: convertAddress(envelope.to),
+        cc: envelope.cc ? convertAddress(envelope.cc) : [],
+        bcc: envelope.bcc ? convertAddress(envelope.bcc) : [],
+        from: typeof envelope.from === "string" ? { email: envelope.from } : envelope.from,
+        subject: envelope.subject ?? "",
+        ...envelope.content,
+        attachments: envelope.attachments,
+        category: envelope.category ?? void 0,
+        custom_variables: Object.fromEntries(Object.entries(envelope.extras ?? {}).filter((e) => e[1] != null))
+      }),
+      {
+        maxAttempts: 10,
+        delay: 1e4,
+        shouldRetry: (e) => {
+          console.log("Trouble with a mailtrap call! Retrying...", e);
+          return true;
+        }
+      }
+    );
+    const emails = [
+      ...getEmails(envelope.to),
+      ...envelope.cc ? getEmails(envelope.cc) : [],
+      ...envelope.bcc ? getEmails(envelope.bcc) : []
+    ];
+    return {
+      success: result.success,
+      messages: result.message_ids.map((id, i) => {
+        assert2.ok(emails[i], `could not match messageId ${id} to an email address`);
+        return { id, email: emails[i] };
+      }),
+      driverName: "mailtrap"
+    };
+  }
+  return {
+    send,
+    toMailEvent(mtEvent) {
+      const formatted = {
+        eventId: mtEvent.event_id,
+        event: mtEvent.event === "soft_bounce" ? "softBounce" : mtEvent.event === "spam_complaint" ? "spamComplaint" : mtEvent.event,
+        email: mtEvent.email,
+        messageId: mtEvent.message_id,
+        timestamp: mtEvent.timestamp * 1e3,
+        category: mtEvent.category ?? null,
+        extras: mtEvent.custom_variables ?? {},
+        driverName: "mailtrap"
+      };
+      return formatted;
+    }
+  };
+}
+
+// src/ses-mail-driver.ts
+import { Helpers as Helpers2 } from "@maestro-js/helpers";
+import assert3 from "assert";
+import MailComposer from "nodemailer/lib/mail-composer/index.js";
+var sesToMaestroEventMapping = {
+  Bounce: "bounce",
+  Complaint: "spamComplaint",
+  Delivery: "delivery",
+  Reject: "reject",
+  Open: "open",
+  Click: "click",
+  Subscription: "unsubscribe"
+};
+function sesMailDriver(ses, configurationSetName) {
+  async function send(envelope) {
+    assert3.ok(envelope.from, "missing from address");
+    function getsComposerAddr(addresses) {
+      const list = Array.isArray(addresses) ? addresses : [addresses];
+      return list.map((a) => typeof a === "string" ? a : a.name ? { name: a.name, address: a.email } : a.email);
+    }
+    const toListComposer = getsComposerAddr(envelope.to);
+    const ccListComposer = envelope.cc ? getsComposerAddr(envelope.cc) : [];
+    const bccListComposer = envelope.bcc ? getsComposerAddr(envelope.bcc) : [];
+    const replyToComposer = envelope.headers?.replyTo ? getsComposerAddr(envelope.headers?.replyTo) : void 0;
+    const composer = new MailComposer({
+      from: typeof envelope.from === "string" ? envelope.from : envelope.from.name ? `${envelope.from.name} <${envelope.from.email}>` : envelope.from.email,
+      to: toListComposer,
+      cc: ccListComposer,
+      bcc: bccListComposer,
+      subject: envelope.subject ?? "",
+      text: "text" in envelope.content ? envelope.content.text : void 0,
+      html: "html" in envelope.content ? envelope.content.html : void 0,
+      replyTo: replyToComposer,
+      headers: {
+        ...envelope.headers?.listUnsubscribe && { "List-Unsubscribe": envelope.headers.listUnsubscribe },
+        ...envelope.headers?.listUnsubscribePost && { "List-Unsubscribe-Post": envelope.headers.listUnsubscribePost }
+      },
+      attachments: envelope.attachments?.map((att) => {
+        const disposition = att.disposition === "inline" ? "inline" : "attachment";
+        const output = {
+          filename: att.filename,
+          content: Buffer.from(att.content, "base64"),
+          contentDisposition: disposition
+        };
+        if (att.type) {
+          output.contentType = att.type;
+        }
+        if (att.contentId) {
+          output.cid = att.contentId;
+        }
+        return output;
+      })
+    });
+    const toList = getEmails(envelope.to);
+    const ccList = envelope.cc ? getEmails(envelope.cc) : [];
+    const bccList = envelope.bcc ? getEmails(envelope.bcc) : [];
+    const allAddresses = [...toList, ...ccList, ...bccList];
+    const messageTags = envelope.extras ? Object.entries(envelope.extras).map(([Name, Value]) => ({
+      Name,
+      Value: String(Value)
+    })) : [];
+    const rawBuffer = await composer.compile().build();
+    const sendPromises = allAddresses.map(async (recipient) => {
+      try {
+        const cmd = {
+          input: {
+            RawMessage: { Data: rawBuffer },
+            Destinations: [recipient],
+            ConfigurationSetName: configurationSetName,
+            Tags: messageTags.length ? messageTags : void 0
+          }
+        };
+        const result = await Helpers2.retry(() => ses.send(cmd), {
+          maxAttempts: 5,
+          delay: 3e3,
+          shouldRetry: () => true
+        });
+        return { id: result.MessageId, email: recipient };
+      } catch (err) {
+        throw err;
+      }
+    });
+    const messages = await Promise.allSettled(sendPromises);
+    if (messages.every((m) => m.status === "rejected")) {
+      throw messages[0]?.reason;
+    } else {
+      return {
+        success: true,
+        driverName: "ses",
+        messages: messages.filter((m) => m.status === "fulfilled").map((m) => m.value)
+      };
+    }
+  }
+  function toMailEvent(raw) {
+    const { mail, eventType, eventId } = raw;
+    const maestroEvent = sesToMaestroEventMapping[eventType];
+    if (!maestroEvent) {
+      console.debug(`Skipping unhandled SES event: ${eventType}`);
+      return null;
+    }
+    const timeStampString = eventType && raw?.[eventType.toLowerCase()]?.timestamp || (/* @__PURE__ */ new Date()).toISOString();
+    const timeStamp = new Date(timeStampString).getTime();
+    const mailTags = raw.mail.tags;
+    const extras = mailTags ? Object.fromEntries(
+      Object.entries(mailTags).filter(([, vs]) => vs.length > 0).map(([k, vs]) => [k, vs[0]])
+    ) : {};
+    return {
+      driverName: "ses",
+      eventId,
+      messageId: mail.messageId,
+      timestamp: timeStamp,
+      category: null,
+      email: raw.bounce?.bouncedRecipients?.[0]?.emailAddress ?? raw.complaint?.complainedRecipients?.[0]?.emailAddress ?? mail.destination[0],
+      event: maestroEvent,
+      extras
+    };
+  }
+  return { send, toMailEvent };
+}
+
+// src/ics-attachment.ts
+import { dateTimeFns, durationFns, instantFns, zonedDateTimeFns } from "iso-fns2";
+import { createEvent } from "ics";
+function icsAttachment(options) {
+  const { value: start, inputType: startInputType, outputType: startOutputType } = parseIsoToDateArray(options.start);
+  const endingOptions = durationFns.isValid(options.end) ? { duration: parseIsoToDurationObject(options.end) } : (() => {
+    const result = parseIsoToDateArray(options.end);
+    return {
+      end: result.value,
+      endInputType: result.inputType,
+      endOutputType: result.outputType
+    };
+  })();
+  const icsMessage = createEvent({
+    ...options,
+    start,
+    startInputType,
+    startOutputType,
+    ...endingOptions,
+    created: options.created ? instantToDateArray(options.created) : void 0,
+    lastModified: options.lastModified ? instantToDateArray(options.lastModified) : void 0,
+    alarms: options.alarms ? options.alarms.map((a) => ({
+      ...a,
+      duration: a.duration ? parseIsoToDurationObject(a.duration) : void 0,
+      trigger: a.trigger ? parseIsoToDurationObject(a.trigger) : void 0
+    })) : void 0
+  });
+  if (!icsMessage.value || icsMessage.error) {
+    throw icsMessage.error ?? new Error("Unknown error generating ics attachment");
+  }
+  const encodedMessage = Buffer.from(icsMessage.value).toString("base64");
+  return {
+    content: encodedMessage,
+    filename: options.filename ?? "event.ics",
+    type: "application/ics",
+    disposition: "attachment"
+  };
+}
+function instantToDateArray(iso) {
+  const value = instantFns.chain(iso).toZonedDateTime("UTC").toDateTime().getFields().value();
+  return [value.year, value.month, value.day, value.hour, value.minute];
+}
+function parseIsoToDateArray(iso) {
+  if (instantFns.isValid(iso)) {
+    const value = instantToDateArray(iso);
+    return { value, inputType: "utc", outputType: "utc" };
+  } else if (zonedDateTimeFns.isValid(iso)) {
+    const value = zonedDateTimeFns.chain(iso).toInstant().toZonedDateTime("UTC").toDateTime().getFields().value();
+    return { value: [value.year, value.month, value.day, value.hour, value.minute], inputType: "utc", outputType: "utc" };
+  } else {
+    const value = dateTimeFns.getFields(iso);
+    return { value: [value.year, value.month, value.day, value.hour, value.minute], inputType: "local", outputType: "local" };
+  }
+}
+function parseIsoToDurationObject(iso) {
+  const value = durationFns.getFields(durationFns.abs(iso));
+  return {
+    weeks: value.weeks,
+    days: value.days,
+    hours: value.hours,
+    minutes: value.minutes,
+    seconds: value.seconds,
+    before: durationFns.getSign(iso) === -1
+  };
+}
+
+// src/index.ts
+import assert5 from "assert";
+import { Log as Log2 } from "@maestro-js/log";
+
+// src/stub-mail-driver.ts
+import assert4 from "assert";
+import { randomUUID } from "crypto";
+import "@maestro-js/log";
+function stubMailDriver({ logger } = {}) {
+  async function send(envelope) {
+    assert4.ok(envelope.from, "missing from address");
+    const emails = [
+      ...getEmails(envelope.to),
+      ...envelope.cc ? getEmails(envelope.cc) : [],
+      ...envelope.bcc ? getEmails(envelope.bcc) : []
+    ];
+    logger?.info(envelope);
+    return {
+      success: true,
+      messages: emails.map((email) => ({ email, id: randomUUID() })),
+      driverName: "stub"
+    };
+  }
+  return {
+    send
+  };
+}
+
+// src/index.ts
+import { ServiceRegistry } from "@maestro-js/service-registry";
+var EMPTY_ENVELOPE = /* @__PURE__ */ Symbol("EMPTY_ENVELOPE");
+function create(config) {
+  const queueService = config.queueService;
+  const mailQueue = queueService.create({
+    name: ["Maestro.Mail", config.name].filter(Boolean).join("."),
+    async workFn(envelope) {
+      return send(envelope);
+    }
+  });
+  const mailableQueue = queueService.create({
+    name: ["Maestro.Mailable", config.name].filter(Boolean).join("."),
+    async workFn(props) {
+      const mailable2 = mailableRegistry.get(props.mailableName);
+      if (!mailable2) {
+        throw new Error(`No mailable found with name ${props.mailableName}`);
+      }
+      const envelope = await mailable2({ ...props.renderArgs });
+      if (envelope === EMPTY_ENVELOPE) {
+        return;
+      }
+      return send(envelope);
+    }
+  });
+  function logMail({
+    envelope,
+    messages,
+    driverName,
+    mailable: mailable2
+  }) {
+    function convertAddress(address) {
+      if (!address) {
+        return [];
+      }
+      return Array.isArray(address) ? address.map((a) => typeof a === "string" ? { email: a } : a) : [typeof address === "string" ? { email: address } : address];
+    }
+    const allEmails = [...convertAddress(envelope.to), ...convertAddress(envelope.cc), ...convertAddress(envelope.bcc)];
+    messages.forEach((message) => {
+      const to = allEmails.find((e) => e.email === message.email);
+      config.logger.info({
+        type: "envelope",
+        to: to || { email: message.email },
+        from: typeof envelope.from === "string" ? { email: envelope.from } : envelope.from,
+        attachments: envelope.attachments ?? [],
+        subject: envelope.subject,
+        mailable: mailable2,
+        content: envelope.content,
+        messageId: message.id,
+        driverName,
+        headers: envelope.headers ?? {},
+        category: envelope.category ?? null,
+        extras: Object.fromEntries(Object.entries(envelope.extras ?? {}).filter((e) => e[1] != null))
+      });
+    });
+  }
+  async function send(envelope) {
+    const formattedEnvelope = formatEnvelope(envelope);
+    try {
+      const { driverName, messages, success } = await config.driver.send(formattedEnvelope);
+      if (success) {
+        logMail({ envelope: formattedEnvelope, messages, driverName, mailable: null });
+      }
+      return { messages, success };
+    } catch (error) {
+      if (config.onMessageSendFailure) {
+        config.onMessageSendFailure(formattedEnvelope, error);
+      }
+      throw error;
+    }
+  }
+  function queue(envelope) {
+    mailQueue.addMessage(envelope, { scheduledDate: null });
+  }
+  function later(envelope, scheduledDate) {
+    mailQueue.addMessage(envelope, { scheduledDate });
+  }
+  async function sendMailable(props) {
+    const mailable2 = mailableRegistry.get(props.mailableName);
+    if (!mailable2) {
+      throw new Error(`No mailable found with name ${props.mailableName}`);
+    }
+    const result = await mailable2({ ...props.renderArgs });
+    if (result === EMPTY_ENVELOPE) {
+      return;
+    }
+    const envelope = formatEnvelope(result);
+    try {
+      const { messages, success, driverName } = await config.driver.send(envelope);
+      if (success) {
+        logMail({ envelope, messages, driverName, mailable: props.mailableName });
+      }
+    } catch (error) {
+      if (config.onMessageSendFailure) {
+        config.onMessageSendFailure(envelope, error);
+      }
+      throw error;
+    }
+  }
+  async function queueMailable(props, options) {
+    await mailableQueue.addMessage(props, options);
+  }
+  function formatEnvelope(envelope) {
+    function formatAddress(mailAddress) {
+      return typeof mailAddress === "string" ? mailAddress.trim().toLowerCase() : { ...mailAddress, email: mailAddress.email.trim().toLowerCase() };
+    }
+    const from = envelope.from ?? config.globalFrom;
+    assert5.ok(from);
+    const formattedTo = Array.isArray(envelope.to) ? envelope.to.map((to) => formatAddress(to)) : [formatAddress(envelope.to)];
+    const formattedToUniq = [...new Set(formattedTo.map((f) => typeof f === "string" ? f : f.email))].map(
+      (email) => formattedTo.find((t) => typeof t === "string" ? t === email : t.email === email)
+    );
+    if (formattedToUniq.length !== formattedTo.length) {
+      Log2.warn({
+        message: "Addresses were not unique in the request. Duplicate email addresses have been removed",
+        original: formattedTo,
+        modified: formattedToUniq
+      });
+    }
+    return {
+      ...envelope,
+      to: formattedToUniq,
+      cc: envelope.cc ? Array.isArray(envelope.cc) ? envelope.cc.map(formatAddress) : [formatAddress(envelope.cc)] : void 0,
+      bcc: envelope.bcc ? Array.isArray(envelope.bcc) ? envelope.bcc.map(formatAddress) : [formatAddress(envelope.bcc)] : void 0,
+      from: formatAddress(from)
+    };
+  }
+  return { send, queue, later, sendMailable, queueMailable };
+}
+var mailableRegistry = /* @__PURE__ */ new Map();
+function mailable(name, fn) {
+  mailableRegistry.set(name, fn);
+  return {
+    /**
+     * Prepares the mailable with the renderArgs so that the mailable
+     * can be sent.
+     */
+    render(renderArgs) {
+      function getFns(mailService) {
+        async function content() {
+          const result = await fn(renderArgs);
+          if (result !== EMPTY_ENVELOPE) {
+            return result.content;
+          } else {
+            return { text: "" };
+          }
+        }
+        async function send() {
+          await mailService.sendMailable({ mailableName: name, renderArgs });
+        }
+        async function queue() {
+          await mailService.queueMailable({ mailableName: name, renderArgs }, { scheduledDate: null });
+        }
+        async function later(scheduledDate) {
+          await mailService.queueMailable({ mailableName: name, renderArgs }, { scheduledDate });
+        }
+        return { content, send, queue, later };
+      }
+      const defaultFns = getFns(registry.resolve("default"));
+      function provider2(key) {
+        return getFns(registry.resolve(key));
+      }
+      return {
+        content: defaultFns.content,
+        send: defaultFns.send,
+        queue: defaultFns.queue,
+        later: defaultFns.later,
+        provider: provider2
+      };
+    }
+  };
+}
+var drivers = {
+  sendGrid: sendGridMailDriver,
+  mailTrap: mailTrapMailDriver,
+  ses: sesMailDriver,
+  stub: stubMailDriver
+};
+var attachments = {
+  ics: icsAttachment
+};
+var registry = ServiceRegistry.createRegistry(ServiceRegistry.proxyFunctionsForObject);
+var Provider = {
+  create,
+  register: registry.register
+};
+function provider(key) {
+  const service = registry.resolve(key);
+  return {
+    send: service.send,
+    later: service.later,
+    queue: service.queue
+  };
+}
+var Mail = {
+  EMPTY_ENVELOPE,
+  mailable,
+  Provider,
+  ...provider("default"),
+  provider,
+  drivers,
+  attachments
+};
+export {
+  Mail
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@maestro-js/mail",
+  "description": "Driver-based email sending with queued delivery, scheduled sending, and mailable templates for the @maestro-js/mail package. Use when working with @maestro-js/mail. Covers creating mail services with SendGrid/SES/MailTrap/Stub drivers, sending emails immediately or via queue, scheduling future delivery, building reusable mailable templates, processing webhook events, generating ICS calendar attachments, and testing with the stub driver.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "ics": "^3.8.1",
+    "iso-fns2": "npm:iso-fns@2.0.0-alpha.26",
+    "nodemailer": "^7.0.5",
+    "@maestro-js/helpers": "1.0.0-alpha.0",
+    "@maestro-js/log": "1.0.0-alpha.0",
+    "@maestro-js/service-registry": "1.0.0-alpha.0"
+  },
+  "devDependencies": {
+    "@react-email/render": "0.0.7",
+    "@types/node": "^22.19.11",
+    "@types/nodemailer": "^6.4.17",
+    "@types/react": "^19.0.0",
+    "@maestro-js/queue": "1.0.0-alpha.0"
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "echo 'No tests yet'",
+    "format": "prettier --write src/",
+    "lint": "prettier --check src/"
+  }
+}