@fonderie/courier 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fonderie, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @fonderie/courier
+
+Transactional messaging: one brick that delivers email, SMS, and push
+through pluggable channels, with templates resolved from the database or
+the filesystem and every send logged.
+
+## Install
+
+```sh
+npm install @fonderie/courier
+```
+
+## Use
+
+```ts
+import { FonderieApp, defineConfig } from '@fonderie/core';
+import { CourierModule } from '@fonderie/courier';
+
+const app = await new FonderieApp(defineConfig({}))
+  .register(new CourierModule())
+  .boot();
+```
+
+```ts
+import { EmailChannel, SmsChannel, PushChannel, DBTemplateResolver } from '@fonderie/courier';
+```
+
+Delivery webhooks for SendGrid, Mailgun, and Mailtrap are handled by the
+exported `handle*Delivery` functions; `IMessageLog` tracks status per send.
+
+## Why this exists
+
+You've shipped this plumbing before — auth, teams, billing, messaging —
+and the next project will ask for it again. Fonderie packages it once:
+plain TypeScript modules for
+[`@fonderie/core`](https://github.com/fonderie-js/sdk/tree/main/packages/core),
+PostgreSQL-backed, self-hosted, MIT. No external control plane, no
+per-seat anything. Register the modules you need; skip the ones you don't.
+
+**This package owns** how the product speaks to humans. Outbound email, SMS, and push
+with templates and delivery logs — other bricks emit intents, this one
+delivers them.
+
+Browse the whole set at
+[fonderie-js/sdk](https://github.com/fonderie-js/sdk) · follow
+[@fonderiejs](https://x.com/fonderiejs)
+
+## License
+
+MIT © Fonderie, Inc.

package/dist/index.cjs

@@ -0,0 +1,626 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Channel: () => Channel,
+  CourierModule: () => CourierModule,
+  DBTemplateResolver: () => DBTemplateResolver,
+  Dispatcher: () => Dispatcher,
+  EmailChannel: () => EmailChannel,
+  FSTemplateResolver: () => FSTemplateResolver,
+  PushChannel: () => PushChannel,
+  SmsChannel: () => SmsChannel,
+  handleMailgunDelivery: () => handleMailgunDelivery,
+  handleMailtrapDelivery: () => handleMailtrapDelivery,
+  handleSendGridDelivery: () => handleSendGridDelivery
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/module.ts
+var import_events = require("@fonderie/events");
+
+// src/log.ts
+async function insertMessageLog(entry, store) {
+  const [row] = await store.query(
+    `INSERT INTO fonderie_message_log
+			(message_type, channel, recipient, locale, provider, provider_message_id)
+		 VALUES ($1, $2, $3, $4, $5, $6)
+		 RETURNING id`,
+    [
+      entry.messageType,
+      entry.channel,
+      entry.recipient,
+      entry.locale ?? null,
+      entry.provider ?? null,
+      entry.providerMessageId ?? null
+    ]
+  );
+  return row?.id ?? "";
+}
+async function markMessageSent(id, store) {
+  await store.query(
+    `UPDATE fonderie_message_log
+		 SET status = 'sent', sent_at = now(), attempts = attempts + 1
+		 WHERE id = $1`,
+    [id]
+  );
+}
+async function markMessageFailed(id, error, store) {
+  await store.query(
+    `UPDATE fonderie_message_log
+		 SET status = 'failed', error = $2, attempts = attempts + 1
+		 WHERE id = $1`,
+    [id, error]
+  );
+}
+async function markMessageDelivered(providerMessageId, store) {
+  await store.query(
+    `UPDATE fonderie_message_log
+		 SET status = 'delivered'
+		 WHERE provider_message_id = $1`,
+    [providerMessageId]
+  );
+}
+async function markMessageOpened(providerMessageId, store) {
+  await store.query(
+    `UPDATE fonderie_message_log
+		 SET status = 'opened', opened_at = now()
+		 WHERE provider_message_id = $1 AND opened_at IS NULL`,
+    [providerMessageId]
+  );
+}
+async function markMessageClicked(providerMessageId, store) {
+  await store.query(
+    `UPDATE fonderie_message_log
+		 SET status = 'clicked', clicked_at = now()
+		 WHERE provider_message_id = $1 AND clicked_at IS NULL`,
+    [providerMessageId]
+  );
+}
+async function markMessageBounced(providerMessageId, reason, store) {
+  await store.query(
+    `UPDATE fonderie_message_log
+		 SET status = 'bounced', bounced_at = now(), bounce_reason = $2
+		 WHERE provider_message_id = $1`,
+    [providerMessageId, reason]
+  );
+}
+
+// src/dispatcher.ts
+function resolveRecipient(message, channel) {
+  if (channel === "email") return message.recipient.email ?? "";
+  if (channel === "sms") return message.recipient.phone ?? "";
+  if (channel === "push") return message.recipient.deviceToken ?? "";
+  return message.recipient.email ?? message.recipient.phone ?? "";
+}
+var Dispatcher = class {
+  constructor(config, resolver, store) {
+    this.config = config;
+    this.resolver = resolver;
+    this.store = store;
+  }
+  config;
+  resolver;
+  store;
+  channels = /* @__PURE__ */ new Map();
+  registerChannel(channel) {
+    this.channels.set(channel.name, channel);
+    return this;
+  }
+  async dispatch(message) {
+    const channelNames = this.config.channels[message.type];
+    if (!channelNames || channelNames.length === 0) {
+      console.warn(`[courier] no channels configured for message type: ${message.type}`);
+      return;
+    }
+    const template = await this.resolver.resolve(message.type, message.data, message.locale);
+    await Promise.allSettled(
+      channelNames.map(async (name) => {
+        const channel = this.channels.get(name);
+        if (!channel) {
+          console.warn(`[courier] channel "${name}" not registered`);
+          return;
+        }
+        const logEntry = {
+          messageType: message.type,
+          channel: name,
+          recipient: resolveRecipient(message, name)
+        };
+        if (message.locale) logEntry.locale = message.locale;
+        const logId = this.store ? await insertMessageLog(logEntry, this.store).catch(() => "") : "";
+        try {
+          await channel.send(message, template);
+          if (this.store && logId) {
+            markMessageSent(logId, this.store).catch(() => void 0);
+          }
+        } catch (err) {
+          const errMsg = err instanceof Error ? err.message : String(err);
+          console.error(`[courier:${name}] failed to send ${message.type}:`, err);
+          if (this.store && logId) {
+            markMessageFailed(logId, errMsg, this.store).catch(() => void 0);
+          }
+        }
+      })
+    );
+  }
+};
+
+// src/channels/sms.ts
+var SmsChannel = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  name = "sms";
+  async send(message, template) {
+    const to = message.recipient.phone;
+    if (!to) {
+      console.warn("[courier:sms] no phone number for recipient \u2014 skipping");
+      return;
+    }
+    if (this.config.provider === "twilio") {
+      await this.sendViaTwilio(to, template.text);
+    } else if (this.config.provider === "vonage") {
+      await this.sendViaVonage(to, template.text);
+    } else {
+      console.warn(`[courier:sms] provider ${this.config.provider} not implemented`);
+    }
+  }
+  async sendViaTwilio(to, text) {
+    const { accountSid, authToken } = this.config;
+    if (!accountSid || !authToken) {
+      throw new Error("Twilio accountSid and authToken required");
+    }
+    const res = await fetch(
+      `https://api.twilio.com/2010-04-01/Accounts/${accountSid}/Messages.json`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Basic ${Buffer.from(`${accountSid}:${authToken}`).toString("base64")}`,
+          "Content-Type": "application/x-www-form-urlencoded"
+        },
+        body: new URLSearchParams({ From: this.config.from, To: to, Body: text })
+      }
+    );
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`[courier:sms] Twilio error ${res.status}: ${body}`);
+    }
+  }
+  async sendViaVonage(to, text) {
+    const { apiKey, apiSecret } = this.config;
+    if (!apiKey || !apiSecret) {
+      throw new Error("Vonage apiKey and apiSecret required");
+    }
+    const res = await fetch("https://rest.nexmo.com/sms/json", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        api_key: apiKey,
+        api_secret: apiSecret,
+        from: this.config.from,
+        to,
+        text
+      })
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`[courier:sms] Vonage error ${res.status}: ${body}`);
+    }
+  }
+};
+
+// src/channels/push.ts
+var PushChannel = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  name = "push";
+  async send(message, template) {
+    const token = message.recipient.deviceToken;
+    if (!token) {
+      console.warn("[courier:push] no device token for recipient \u2014 skipping");
+      return;
+    }
+    if (this.config.provider === "fcm") {
+      await this.sendViaFCM(token, template);
+    }
+  }
+  async sendViaFCM(token, template) {
+    const apiKey = this.config.serviceAccount["apiKey"];
+    if (!apiKey) {
+      throw new Error("[courier:push] FCM apiKey is required in serviceAccount");
+    }
+    const res = await fetch("https://fcm.googleapis.com/fcm/send", {
+      method: "POST",
+      headers: {
+        Authorization: `key=${apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        to: token,
+        notification: {
+          title: template.subject,
+          body: template.text
+        }
+      })
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`[courier:push] FCM error ${res.status}: ${body}`);
+    }
+  }
+};
+
+// src/channels/email.ts
+var import_nodemailer = __toESM(require("nodemailer"), 1);
+var EmailChannel = class {
+  constructor(config) {
+    this.config = config;
+    if (config.provider === "smtp" && config.smtp) {
+      this.transport = import_nodemailer.default.createTransport({
+        host: config.smtp.host,
+        port: config.smtp.port,
+        secure: config.smtp.secure,
+        auth: { user: config.smtp.user, pass: config.smtp.pass }
+      });
+    }
+  }
+  config;
+  name = "email";
+  transport = null;
+  async send(message, template) {
+    const to = message.recipient.email;
+    if (!to) {
+      console.warn("[courier:email] no email address for recipient \u2014 skipping");
+      return;
+    }
+    if (this.config.provider === "resend") {
+      await this.sendViaResend(to, template);
+    } else if (this.config.provider === "smtp") {
+      await this.sendViaSMTP(to, template);
+    } else {
+      console.warn(`[courier:email] provider ${this.config.provider} not implemented`);
+    }
+  }
+  async sendViaResend(to, template) {
+    if (!this.config.apiKey) {
+      throw new Error("Resend apiKey is required");
+    }
+    const res = await fetch("https://api.resend.com/emails", {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.config.apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        from: this.config.from,
+        to,
+        subject: template.subject ?? "(no subject)",
+        html: template.html,
+        text: template.text
+      })
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`[courier:email] Resend error ${res.status}: ${body}`);
+    }
+  }
+  async sendViaSMTP(to, template) {
+    if (!this.transport) {
+      throw new Error("SMTP transport not initialised \u2014 check smtp config");
+    }
+    await this.transport.sendMail({
+      from: this.config.from,
+      to,
+      subject: template.subject ?? "(no subject)",
+      html: template.html,
+      text: template.text
+    });
+  }
+};
+
+// src/templates/resolver.ts
+function render(template, data) {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+    const value = data[key];
+    return value !== void 0 && value !== null ? String(value) : "";
+  });
+}
+var DBTemplateResolver = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  async resolve(type, data, locale) {
+    const [row] = await this.store.query(
+      `SELECT subject, html, text
+			 FROM fonderie_courier_templates
+			 WHERE type = $1 AND active = true
+			 ORDER BY (locale = $2)::int DESC, (locale IS NULL)::int DESC
+			 LIMIT 1`,
+      [type, locale ?? null]
+    );
+    if (!row) {
+      return { text: `${type}: ${JSON.stringify(data)}` };
+    }
+    return {
+      text: render(row.text, data),
+      ...row.subject ? { subject: render(row.subject, data) } : {},
+      ...row.html ? { html: render(row.html, data) } : {}
+    };
+  }
+};
+var FSTemplateResolver = class {
+  constructor(directory) {
+    this.directory = directory;
+  }
+  directory;
+  async resolve(type, data, locale) {
+    const { readFile } = await import("fs/promises");
+    const { join } = await import("path");
+    const readOptional = async (path) => {
+      try {
+        return await readFile(path, "utf8");
+      } catch {
+        return null;
+      }
+    };
+    const localePrefix = locale ? `${type}.${locale}` : null;
+    const [text, html, subject] = await Promise.all([
+      localePrefix ? readOptional(join(this.directory, `${localePrefix}.txt`)).then(
+        (v) => v ?? readOptional(join(this.directory, `${type}.txt`))
+      ) : readOptional(join(this.directory, `${type}.txt`)),
+      localePrefix ? readOptional(join(this.directory, `${localePrefix}.html`)).then(
+        (v) => v ?? readOptional(join(this.directory, `${type}.html`))
+      ) : readOptional(join(this.directory, `${type}.html`)),
+      localePrefix ? readOptional(join(this.directory, `${localePrefix}.subject.txt`)).then(
+        (v) => v ?? readOptional(join(this.directory, `${type}.subject.txt`))
+      ) : readOptional(join(this.directory, `${type}.subject.txt`))
+    ]);
+    return {
+      text: text ? render(text, data) : `${type}: ${JSON.stringify(data)}`,
+      ...subject ? { subject: render(subject, data) } : {},
+      ...html ? { html: render(html, data) } : {}
+    };
+  }
+};
+
+// src/delivery.ts
+var import_node_crypto = require("crypto");
+async function handleSendGridDelivery(req, store, webhookSecret) {
+  if (webhookSecret) {
+    const sig = req.headers.get("x-twilio-email-event-webhook-signature") ?? "";
+    const ts = req.headers.get("x-twilio-email-event-webhook-timestamp") ?? "";
+    const body = await req.text();
+    if (!verifySendGridSignature(webhookSecret, ts, body, sig)) {
+      return Response.json({ error: "INVALID_SIGNATURE" }, { status: 401 });
+    }
+    const events2 = parseJson(body);
+    if (!Array.isArray(events2)) return Response.json({ ok: true });
+    await processSendGridEvents(events2, store);
+    return Response.json({ ok: true });
+  }
+  const events = await req.json();
+  if (!Array.isArray(events)) return Response.json({ ok: true });
+  await processSendGridEvents(events, store);
+  return Response.json({ ok: true });
+}
+function verifySendGridSignature(secret, timestamp, body, signature) {
+  try {
+    const payload = timestamp + body;
+    const expected = (0, import_node_crypto.createHmac)("sha256", secret).update(payload).digest("base64");
+    const sigBuf = Buffer.from(signature, "base64");
+    const expBuf = Buffer.from(expected, "base64");
+    if (sigBuf.length !== expBuf.length) return false;
+    return (0, import_node_crypto.timingSafeEqual)(sigBuf, expBuf);
+  } catch {
+    return false;
+  }
+}
+async function processSendGridEvents(events, store) {
+  for (const ev of events) {
+    const msgId = ev["sg_message_id"];
+    if (!msgId || typeof msgId !== "string") continue;
+    const id = msgId.split(".")[0] ?? msgId;
+    switch (ev.event) {
+      case "delivered":
+        await markMessageDelivered(id, store);
+        break;
+      case "open":
+        await markMessageOpened(id, store);
+        break;
+      case "click":
+        await markMessageClicked(id, store);
+        break;
+      case "bounce":
+      case "blocked":
+      case "dropped":
+        await markMessageBounced(id, typeof ev["reason"] === "string" ? ev["reason"] : ev.event, store);
+        break;
+    }
+  }
+}
+async function handleMailgunDelivery(req, store, signingKey) {
+  const body = await req.json();
+  if (signingKey) {
+    const { signature } = body;
+    if (!signature || !verifyMailgunSignature(signingKey, signature.timestamp, signature.token, signature.signature)) {
+      return Response.json({ error: "INVALID_SIGNATURE" }, { status: 401 });
+    }
+  }
+  const event = body["event-data"];
+  if (event) {
+    await processMailgunEvent(event, store);
+  }
+  return Response.json({ ok: true });
+}
+function verifyMailgunSignature(signingKey, timestamp, token, signature) {
+  try {
+    const value = timestamp + token;
+    const expected = (0, import_node_crypto.createHmac)("sha256", signingKey).update(value).digest("hex");
+    const expBuf = Buffer.from(expected, "hex");
+    const sigBuf = Buffer.from(signature, "hex");
+    if (expBuf.length !== sigBuf.length) return false;
+    return (0, import_node_crypto.timingSafeEqual)(expBuf, sigBuf);
+  } catch {
+    return false;
+  }
+}
+async function processMailgunEvent(event, store) {
+  const msgId = event.message?.headers?.["message-id"];
+  if (!msgId) return;
+  switch (event.event) {
+    case "delivered":
+      await markMessageDelivered(msgId, store);
+      break;
+    case "opened":
+      await markMessageOpened(msgId, store);
+      break;
+    case "clicked":
+      await markMessageClicked(msgId, store);
+      break;
+    case "failed":
+    case "bounced": {
+      const reason = event["delivery-status"]?.message ?? event.event;
+      await markMessageBounced(msgId, reason, store);
+      break;
+    }
+  }
+}
+async function handleMailtrapDelivery(req, store) {
+  const events = await req.json();
+  if (!Array.isArray(events)) return Response.json({ ok: true });
+  for (const ev of events) {
+    const msgId = ev.message_id;
+    if (!msgId) continue;
+    switch (ev.event) {
+      case "delivery":
+        await markMessageDelivered(msgId, store);
+        break;
+      case "open":
+        await markMessageOpened(msgId, store);
+        break;
+      case "click":
+        await markMessageClicked(msgId, store);
+        break;
+      case "bounce":
+      case "soft_bounce":
+        await markMessageBounced(msgId, ev.event, store);
+        break;
+    }
+  }
+  return Response.json({ ok: true });
+}
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+// src/module.ts
+var CourierModule = class {
+  constructor(config, store, bus) {
+    this.config = config;
+    this.store = store;
+    const templateSource = config.templates?.source ?? "db";
+    const resolver = createTemplateResolver(templateSource, config, store);
+    this.dispatcher = new Dispatcher(config, resolver, store);
+    if (config.email) this.dispatcher.registerChannel(new EmailChannel(config.email));
+    if (config.sms) this.dispatcher.registerChannel(new SmsChannel(config.sms));
+    if (config.push) this.dispatcher.registerChannel(new PushChannel(config.push));
+    bus?.on(
+      import_events.NOTIFICATION_EVENT,
+      async (msg) => {
+        await this.dispatcher.dispatch(msg);
+      },
+      "courier"
+    );
+  }
+  config;
+  store;
+  name = "@fonderie/courier";
+  deps = ["@fonderie/events"];
+  dispatcher;
+  install(app) {
+    const store = this.store;
+    const signingKeys = this.config.delivery?.signingKeys;
+    app.addRoute(
+      "POST",
+      "/courier/delivery/sendgrid",
+      (ctx) => handleSendGridDelivery(ctx.request, store, signingKeys?.sendgrid)
+    );
+    app.addRoute(
+      "POST",
+      "/courier/delivery/mailgun",
+      (ctx) => handleMailgunDelivery(ctx.request, store, signingKeys?.mailgun)
+    );
+    app.addRoute(
+      "POST",
+      "/courier/delivery/mailtrap",
+      (ctx) => handleMailtrapDelivery(ctx.request, store)
+    );
+  }
+};
+function createTemplateResolver(source, config, store) {
+  if (source === "fs") {
+    return new FSTemplateResolver(config.templates?.directory ?? "./templates");
+  }
+  if (!store) {
+    throw new Error("[courier] store is required for DB template resolution");
+  }
+  return new DBTemplateResolver(store);
+}
+
+// src/config.ts
+var Channel = {
+  EMAIL: "email",
+  SMS: "sms",
+  PUSH: "push"
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Channel,
+  CourierModule,
+  DBTemplateResolver,
+  Dispatcher,
+  EmailChannel,
+  FSTemplateResolver,
+  PushChannel,
+  SmsChannel,
+  handleMailgunDelivery,
+  handleMailtrapDelivery,
+  handleSendGridDelivery
+});
+//# sourceMappingURL=index.cjs.map