@fonderie/courier 3.0.0 → 5.0.0

package/brain/outcomes.md

@@ -9,6 +9,19 @@ downloading tarballs.
 
 ## Database tables (after all migrations)
 
+### `fonderie_courier_template_revisions`
+
+```sql
+type                     TEXT NOT NULL
+locale                   TEXT
+subject                  TEXT
+html                     TEXT
+text                     TEXT NOT NULL
+version                  INT NOT NULL
+actor                    TEXT
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+```
+
 ### `fonderie_courier_templates`
 
 ```sql
@@ -21,6 +34,8 @@ text                     TEXT NOT NULL
 active                   BOOLEAN NOT NULL DEFAULT true
 created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
 updated_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+version                  INT NOT NULL DEFAULT 1
+updated_by               TEXT
 -- UNIQUE (type, locale)
 ```
 
@@ -48,6 +63,17 @@ bounce_reason            TEXT
 
 Raw SQL ships in `node_modules/@fonderie/courier/dist/migrations/sql/` — read it there if you must; never download tarballs.
 
+## HTTP routes registered
+
+| Method | Path | Middleware chain (auth / validation / handler) |
+|---|---|---|
+| GET | `/admin/templates` | `g(async () => { return setApiResponse(HTTP.OK, 'TEMPLATES_LISTED', 'Templates', await listTemplateEntries(store)); })` |
+| DELETE | `/admin/templates/:type` | `g(async (ctx) => { const ok = await deleteTemplate(typeOf(ctx), localeOf(ctx), store); return setApiResponse(ok ? HTTP.OK : HTTP.NOT_FOUND, ok ? 'DELETED' : 'NOT_FOUND', ok ? 'Deleted' : 'No such template'); })` |
+| GET | `/admin/templates/:type` | `g(async (ctx) => { const row = await getTemplateEntry(typeOf(ctx), localeOf(ctx), store); return row ? setApiResponse(HTTP.OK, 'TEMPLATE', 'Template', row) : setApiResponse(HTTP.NOT_FOUND, 'NOT_FOUND', 'No such template'); })` |
+| PUT | `/admin/templates/:type` | `g(async (ctx) => { const b = body(ctx); if (typeof b['text'] !== 'string') { return setApiResponse(HTTP.UNPROCESSABLE, 'INVALID', 'body.text (string) is required'); } try { const opts: Parameters<typeof setTemplate>[0] = { type: typeOf(ctx), text: b['text'], locale: localeOf(ctx), actor: actorOf(ctx), }; if (typeof b['subject'] === 'string') opts.subject = b['subject']; if (typeof b['html'] === 'string') opts.html = b['html']; if (typeof b['active'] === 'boolean') opts.active = b['active']; if (typeof b['ifVersion'] === 'number') opts.ifVersion = b['ifVersion']; return setApiResponse(HTTP.OK, 'TEMPLATE_SET', 'Template saved', await setTemplate(opts, store)); } catch (err) { return conflictOr(err); } })` |
+| GET | `/admin/templates/:type/revisions` | `g(async (ctx) => { return setApiResponse(HTTP.OK, 'REVISIONS', 'Template revisions', await listTemplateRevisions(typeOf(ctx), localeOf(ctx), store)); })` |
+| POST | `/admin/templates/:type/rollback` | `g(async (ctx) => { const b = body(ctx); const toVersion = Number(b['toVersion']); if (!Number.isInteger(toVersion)) { return setApiResponse(HTTP.UNPROCESSABLE, 'INVALID', 'body.toVersion (int) is required'); } const row = await rollbackTemplate( { type: typeOf(ctx), locale: localeOf(ctx), toVersion, actor: actorOf(ctx) }, store, ); return setApiResponse(HTTP.OK, 'ROLLED_BACK', `Rolled back to v${toVersion}`, row); })` |
+
 ## Migration statements not replayed (verify in raw SQL)
 
 - `ELSE`

package/brain/signatures.md

@@ -11,8 +11,11 @@ new CourierModule(config: ICourierConfig, store?: IStoreAdapter | undefined, bus
   .name: "@fonderie/courier"
   .deps: string[]
   .dispatcher: Dispatcher
+  .checkReadiness(): IReadinessProblem[]
   .install(app: IFonderieApp): void
 
+function validateCourierConfig(config: ICourierConfig, registeredChannels: Iterable<string>): void
+
 function handleSendGridDelivery(req: Request, store: IStoreAdapter, webhookSecret?: string | undefined): Promise<Response>
 
 function handleMailgunDelivery(req: Request, store: IStoreAdapter, signingKey?: string | undefined): Promise<Response>
@@ -21,6 +24,7 @@ function handleMailtrapDelivery(req: Request, store: IStoreAdapter): Promise<Res
 
 new Dispatcher(config: ICourierConfig, resolver: ITemplateResolver, store?: IStoreAdapter | undefined): Dispatcher
   .registerChannel(channel: ICourierChannel): Dispatcher
+  .channelNames(): string[]
   .dispatch(message: ICourierMessage): Promise<void>
 
 new SmsChannel(config: ISmsChannelConfig): SmsChannel
@@ -41,6 +45,43 @@ new DBTemplateResolver(store: IStoreAdapter): DBTemplateResolver
 new FSTemplateResolver(directory: string): FSTemplateResolver
   .resolve(type: string, data: Record<string, unknown>, locale?: string | undefined): Promise<IRenderedTemplate>
 
+function setTemplate(opts: { type: string; text: string; locale?: string | null; subject?: string | null; html?: string | null; active?: boolean; ifVersion?: number; actor?: string; }, store: IStoreAdapter): Promise<...>
+
+function rollbackTemplate(opts: { type: string; locale?: string | null; toVersion: number; actor?: string; }, store: IStoreAdapter): Promise<ITemplateEntry>
+
+function listTemplateRevisions(type: string, locale: string | null, store: IStoreAdapter): Promise<ITemplateRevision[]>
+
+function getTemplateEntry(type: string, locale: string | null, store: IStoreAdapter): Promise<ITemplateEntry | null>
+
+function listTemplateEntries(store: IStoreAdapter): Promise<ITemplateEntry[]>
+
+function deleteTemplate(type: string, locale: string | null, store: IStoreAdapter): Promise<boolean>
+
+function buildTemplateAdminRoutes(store: IStoreAdapter, adminToken: string): [string, string, Middleware][]
+
+interface ITemplateEntry {
+    type: string;
+    locale: string | null;
+    subject: string | null;
+    html: string | null;
+    text: string;
+    active: boolean;
+    version: number;
+    updatedBy: string | null;
+    updatedAt: string;
+}
+
+interface ITemplateRevision {
+    type: string;
+    locale: string | null;
+    subject: string | null;
+    html: string | null;
+    text: string;
+    version: number;
+    actor: string | null;
+    createdAt: string;
+}
+
 interface IMessageLog {
     id: string;
     messageType: string;
@@ -95,6 +136,7 @@ interface ICourierConfig {
     sms?: ISmsChannelConfig;
     push?: IPushChannelConfig;
     email?: IEmailChannelConfig;
+    adminToken?: string;
     templates?: {
         source: 'db' | 'fs';
         directory?: string;

package/dist/index.cjs

@@ -38,9 +38,17 @@ __export(index_exports, {
   FSTemplateResolver: () => FSTemplateResolver,
   PushChannel: () => PushChannel,
   SmsChannel: () => SmsChannel,
+  buildTemplateAdminRoutes: () => buildTemplateAdminRoutes,
+  deleteTemplate: () => deleteTemplate,
+  getTemplateEntry: () => getTemplateEntry,
   handleMailgunDelivery: () => handleMailgunDelivery,
   handleMailtrapDelivery: () => handleMailtrapDelivery,
-  handleSendGridDelivery: () => handleSendGridDelivery
+  handleSendGridDelivery: () => handleSendGridDelivery,
+  listTemplateEntries: () => listTemplateEntries,
+  listTemplateRevisions: () => listTemplateRevisions,
+  rollbackTemplate: () => rollbackTemplate,
+  setTemplate: () => setTemplate,
+  validateCourierConfig: () => validateCourierConfig
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -135,6 +143,11 @@ var Dispatcher = class {
     this.channels.set(channel.name, channel);
     return this;
   }
+  // Names of the currently-registered channels — used by the boot-time config
+  // guard to detect message types routed to a channel with no provider.
+  channelNames() {
+    return [...this.channels.keys()];
+  }
   async dispatch(message) {
     const channelNames = this.config.channels[message.type];
     if (!channelNames || channelNames.length === 0) {
@@ -211,8 +224,8 @@ var SmsChannel = class {
       }
     );
     if (!res.ok) {
-      const body = await res.text();
-      throw new Error(`[courier:sms] Twilio error ${res.status}: ${body}`);
+      const body2 = await res.text();
+      throw new Error(`[courier:sms] Twilio error ${res.status}: ${body2}`);
     }
   }
   async sendViaVonage(to, text) {
@@ -232,8 +245,8 @@ var SmsChannel = class {
       })
     });
     if (!res.ok) {
-      const body = await res.text();
-      throw new Error(`[courier:sms] Vonage error ${res.status}: ${body}`);
+      const body2 = await res.text();
+      throw new Error(`[courier:sms] Vonage error ${res.status}: ${body2}`);
     }
   }
 };
@@ -275,8 +288,8 @@ var PushChannel = class {
       })
     });
     if (!res.ok) {
-      const body = await res.text();
-      throw new Error(`[courier:push] FCM error ${res.status}: ${body}`);
+      const body2 = await res.text();
+      throw new Error(`[courier:push] FCM error ${res.status}: ${body2}`);
     }
   }
 };
@@ -331,8 +344,8 @@ var EmailChannel = class {
       })
     });
     if (!res.ok) {
-      const body = await res.text();
-      throw new Error(`[courier:email] Resend error ${res.status}: ${body}`);
+      const body2 = await res.text();
+      throw new Error(`[courier:email] Resend error ${res.status}: ${body2}`);
     }
   }
   async sendViaSMTP(to, template) {
@@ -568,17 +581,43 @@ var FSTemplateResolver = class {
   }
 };
 
+// src/config-guard.ts
+var MODULE = "@fonderie/courier";
+function collectCourierConfigProblems(config, registeredChannels) {
+  const registered = new Set(registeredChannels);
+  const gaps = /* @__PURE__ */ new Map();
+  for (const [type, channels] of Object.entries(config.channels ?? {})) {
+    for (const channel of channels) {
+      if (!registered.has(channel)) {
+        const types = gaps.get(channel) ?? [];
+        types.push(type);
+        gaps.set(channel, types);
+      }
+    }
+  }
+  return [...gaps].map(([channel, types]) => ({
+    module: MODULE,
+    severity: "warning",
+    message: `${types.length} message type(s) route to the '${channel}' channel but no '${channel}' provider is registered \u2014 these will be silently dropped: ${types.join(", ")}. Configure \`config.${channel}\` (or register a channel).`
+  }));
+}
+function validateCourierConfig(config, registeredChannels) {
+  for (const problem of collectCourierConfigProblems(config, registeredChannels)) {
+    console.warn(`[courier] ${problem.message}`);
+  }
+}
+
 // 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)) {
+    const body2 = await req.text();
+    if (!verifySendGridSignature(webhookSecret, ts, body2, sig)) {
       return Response.json({ error: "INVALID_SIGNATURE" }, { status: 401 });
     }
-    const events2 = parseJson(body);
+    const events2 = parseJson(body2);
     if (!Array.isArray(events2)) return Response.json({ ok: true });
     await processSendGridEvents(events2, store);
     return Response.json({ ok: true });
@@ -588,9 +627,9 @@ async function handleSendGridDelivery(req, store, webhookSecret) {
   await processSendGridEvents(events, store);
   return Response.json({ ok: true });
 }
-function verifySendGridSignature(secret, timestamp, body, signature) {
+function verifySendGridSignature(secret, timestamp, body2, signature) {
   try {
-    const payload = timestamp + body;
+    const payload = timestamp + body2;
     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");
@@ -624,14 +663,14 @@ async function processSendGridEvents(events, store) {
   }
 }
 async function handleMailgunDelivery(req, store, signingKey) {
-  const body = await req.json();
+  const body2 = await req.json();
   if (signingKey) {
-    const { signature } = body;
+    const { signature } = body2;
     if (!signature || !verifyMailgunSignature(signingKey, signature.timestamp, signature.token, signature.signature)) {
       return Response.json({ error: "INVALID_SIGNATURE" }, { status: 401 });
     }
   }
-  const event = body["event-data"];
+  const event = body2["event-data"];
   if (event) {
     await processMailgunEvent(event, store);
   }
@@ -702,6 +741,150 @@ function parseJson(text) {
   }
 }
 
+// src/templates/admin-routes.ts
+var import_core = require("@fonderie/core");
+var import_store2 = require("@fonderie/store");
+
+// src/templates/admin.ts
+var import_store = require("@fonderie/store");
+var ENTRY_COLS = `type, locale, subject, html, text, active, version, updated_by AS "updatedBy", updated_at AS "updatedAt"`;
+var TEMPLATE_RESOURCE = {
+  table: "fonderie_courier_templates",
+  revisions: "fonderie_courier_template_revisions",
+  channel: "fonderie_courier_templates_changed",
+  keyColumns: ["type", "locale"],
+  contentColumns: ["subject", "html", "text"],
+  metaColumns: ["active"],
+  returning: ENTRY_COLS
+};
+async function setTemplate(opts, store) {
+  const data = {
+    subject: opts.subject ?? null,
+    html: opts.html ?? null,
+    text: opts.text
+  };
+  if (opts.active !== void 0) data["active"] = opts.active;
+  return (0, import_store.versionedWrite)(TEMPLATE_RESOURCE, store, {
+    key: opts.type,
+    scope: opts.locale ?? null,
+    data,
+    ...opts.ifVersion !== void 0 ? { ifVersion: opts.ifVersion } : {},
+    actor: opts.actor ?? null
+  });
+}
+async function rollbackTemplate(opts, store) {
+  return (0, import_store.versionedRollback)(TEMPLATE_RESOURCE, store, {
+    key: opts.type,
+    scope: opts.locale ?? null,
+    toVersion: opts.toVersion,
+    actor: opts.actor ?? null
+  });
+}
+async function listTemplateRevisions(type, locale, store) {
+  return store.query(
+    `SELECT type, locale, subject, html, text, version, actor, created_at AS "createdAt"
+		 FROM fonderie_courier_template_revisions
+		 WHERE type = $1 AND locale IS NOT DISTINCT FROM $2
+		 ORDER BY version DESC`,
+    [type, locale]
+  );
+}
+async function getTemplateEntry(type, locale, store) {
+  const [row] = await store.query(
+    `SELECT ${ENTRY_COLS} FROM fonderie_courier_templates WHERE type = $1 AND locale IS NOT DISTINCT FROM $2`,
+    [type, locale]
+  );
+  return row ?? null;
+}
+async function listTemplateEntries(store) {
+  return store.query(
+    `SELECT ${ENTRY_COLS} FROM fonderie_courier_templates ORDER BY type, locale NULLS FIRST`
+  );
+}
+async function deleteTemplate(type, locale, store) {
+  const rows = await store.query(
+    `DELETE FROM fonderie_courier_templates WHERE type = $1 AND locale IS NOT DISTINCT FROM $2 RETURNING type`,
+    [type, locale]
+  );
+  return rows.length > 0;
+}
+
+// src/templates/admin-routes.ts
+function guarded(adminToken, handler) {
+  return async (ctx, next) => {
+    const header = ctx.request.headers.get("authorization") ?? "";
+    const token = header.startsWith("Bearer ") ? header.slice(7) : "";
+    if (!token || token !== adminToken) {
+      return (0, import_core.setApiResponse)(import_core.HTTP.UNAUTHORIZED, "UNAUTHORIZED", "Missing or invalid admin token");
+    }
+    return handler(ctx, next);
+  };
+}
+var actorOf = (ctx) => ctx.request.headers.get("x-actor") || "admin-token";
+var typeOf = (ctx) => ctx.meta.params?.["type"] ?? "";
+var localeOf = (ctx) => new URL(ctx.request.url).searchParams.get("locale");
+var body = (ctx) => ctx.meta["body"] ?? {};
+function conflictOr(err) {
+  if (err instanceof import_store2.VersionConflictError) {
+    return (0, import_core.setApiResponse)(import_core.HTTP.CONFLICT, "VERSION_CONFLICT", err.message, {
+      currentVersion: err.currentVersion
+    });
+  }
+  throw err;
+}
+function buildTemplateAdminRoutes(store, adminToken) {
+  const g = (h) => guarded(adminToken, h);
+  return [
+    ["GET", "/admin/templates", g(async () => {
+      return (0, import_core.setApiResponse)(import_core.HTTP.OK, "TEMPLATES_LISTED", "Templates", await listTemplateEntries(store));
+    })],
+    ["GET", "/admin/templates/:type", g(async (ctx) => {
+      const row = await getTemplateEntry(typeOf(ctx), localeOf(ctx), store);
+      return row ? (0, import_core.setApiResponse)(import_core.HTTP.OK, "TEMPLATE", "Template", row) : (0, import_core.setApiResponse)(import_core.HTTP.NOT_FOUND, "NOT_FOUND", "No such template");
+    })],
+    ["PUT", "/admin/templates/:type", g(async (ctx) => {
+      const b = body(ctx);
+      if (typeof b["text"] !== "string") {
+        return (0, import_core.setApiResponse)(import_core.HTTP.UNPROCESSABLE, "INVALID", "body.text (string) is required");
+      }
+      try {
+        const opts = {
+          type: typeOf(ctx),
+          text: b["text"],
+          locale: localeOf(ctx),
+          actor: actorOf(ctx)
+        };
+        if (typeof b["subject"] === "string") opts.subject = b["subject"];
+        if (typeof b["html"] === "string") opts.html = b["html"];
+        if (typeof b["active"] === "boolean") opts.active = b["active"];
+        if (typeof b["ifVersion"] === "number") opts.ifVersion = b["ifVersion"];
+        return (0, import_core.setApiResponse)(import_core.HTTP.OK, "TEMPLATE_SET", "Template saved", await setTemplate(opts, store));
+      } catch (err) {
+        return conflictOr(err);
+      }
+    })],
+    ["DELETE", "/admin/templates/:type", g(async (ctx) => {
+      const ok = await deleteTemplate(typeOf(ctx), localeOf(ctx), store);
+      return (0, import_core.setApiResponse)(ok ? import_core.HTTP.OK : import_core.HTTP.NOT_FOUND, ok ? "DELETED" : "NOT_FOUND", ok ? "Deleted" : "No such template");
+    })],
+    ["GET", "/admin/templates/:type/revisions", g(async (ctx) => {
+      return (0, import_core.setApiResponse)(import_core.HTTP.OK, "REVISIONS", "Template revisions", await listTemplateRevisions(typeOf(ctx), localeOf(ctx), store));
+    })],
+    ["POST", "/admin/templates/:type/rollback", g(async (ctx) => {
+      const b = body(ctx);
+      const toVersion = Number(b["toVersion"]);
+      if (!Number.isInteger(toVersion)) {
+        return (0, import_core.setApiResponse)(import_core.HTTP.UNPROCESSABLE, "INVALID", "body.toVersion (int) is required");
+      }
+      const row = await rollbackTemplate(
+        { type: typeOf(ctx), locale: localeOf(ctx), toVersion, actor: actorOf(ctx) },
+        store
+      );
+      return (0, import_core.setApiResponse)(import_core.HTTP.OK, "ROLLED_BACK", `Rolled back to v${toVersion}`, row);
+    })]
+  ];
+}
+
 // src/module.ts
 var CourierModule = class {
   constructor(config, store, bus) {
@@ -726,7 +909,12 @@ var CourierModule = class {
   name = "@fonderie/courier";
   deps = ["@fonderie/events"];
   dispatcher;
+  // Report config problems for app.checkProductionReadiness() (data, not warn).
+  checkReadiness() {
+    return collectCourierConfigProblems(this.config, this.dispatcher.channelNames());
+  }
   install(app) {
+    validateCourierConfig(this.config, this.dispatcher.channelNames());
     const store = this.store;
     const signingKeys = this.config.delivery?.signingKeys;
     app.addRoute(
@@ -744,6 +932,14 @@ var CourierModule = class {
       "/courier/delivery/mailtrap",
       (ctx) => handleMailtrapDelivery(ctx.request, store)
     );
+    if (this.config.adminToken) {
+      if (!store) {
+        throw new Error("[courier] adminToken requires @fonderie/store (db templates)");
+      }
+      for (const [method, path, handler] of buildTemplateAdminRoutes(store, this.config.adminToken)) {
+        app.addRoute(method, path, handler);
+      }
+    }
   }
 };
 function createTemplateResolver(source, config, store) {
@@ -772,8 +968,16 @@ var Channel = {
   FSTemplateResolver,
   PushChannel,
   SmsChannel,
+  buildTemplateAdminRoutes,
+  deleteTemplate,
+  getTemplateEntry,
   handleMailgunDelivery,
   handleMailtrapDelivery,
-  handleSendGridDelivery
+  handleSendGridDelivery,
+  listTemplateEntries,
+  listTemplateRevisions,
+  rollbackTemplate,
+  setTemplate,
+  validateCourierConfig
 });
 //# sourceMappingURL=index.cjs.map