@fonderie/courier 5.1.0 → 5.2.0

package/brain/signatures.md

@@ -39,12 +39,18 @@ new EmailChannel(config: IEmailChannelConfig): EmailChannel
   .name: "email"
   .send(message: ICourierMessage, template: IRenderedTemplate): Promise<void>
 
-new DBTemplateResolver(store: IStoreAdapter): DBTemplateResolver
+new DBTemplateResolver(store: IStoreAdapter, defaults?: DefaultTemplates | undefined): DBTemplateResolver
   .resolve(type: string, data: Record<string, unknown>, locale?: string | undefined): Promise<IRenderedTemplate>
 
-new FSTemplateResolver(directory: string): FSTemplateResolver
+new FSTemplateResolver(directory: string, defaults?: DefaultTemplates | undefined): FSTemplateResolver
   .resolve(type: string, data: Record<string, unknown>, locale?: string | undefined): Promise<IRenderedTemplate>
 
+new DefaultTemplates(maps?: DefaultTemplateMap[]): DefaultTemplates
+  .get(type: string): IDefaultTemplate | undefined
+  .size: number
+
+function renderFragment(frag: { subject?: string | null; text: string; html?: string | null; }, layoutHtml: string | undefined, data: Record<string, unknown>): 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>
@@ -129,6 +135,14 @@ interface ITemplateResolver {
     resolve(type: string, data: Record<string, unknown>, locale?: string): Promise<IRenderedTemplate>;
 }
 
+interface IDefaultTemplate {
+    subject?: string;
+    text: string;
+    html?: string;
+}
+
+type DefaultTemplateMap = Record<string, IDefaultTemplate>;
+
 const Channel: { readonly EMAIL: "email"; readonly SMS: "sms"; readonly PUSH: "push"; }
 
 interface ICourierConfig {
@@ -140,6 +154,7 @@ interface ICourierConfig {
     templates?: {
         source: 'db' | 'fs';
         directory?: string;
+        defaults?: DefaultTemplateMap | DefaultTemplateMap[];
     };
     delivery?: {
         signingKeys?: {

package/dist/index.cjs

@@ -33,6 +33,7 @@ __export(index_exports, {
   Channel: () => Channel,
   CourierModule: () => CourierModule,
   DBTemplateResolver: () => DBTemplateResolver,
+  DefaultTemplates: () => DefaultTemplates,
   Dispatcher: () => Dispatcher,
   EmailChannel: () => EmailChannel,
   FSTemplateResolver: () => FSTemplateResolver,
@@ -46,6 +47,7 @@ __export(index_exports, {
   handleSendGridDelivery: () => handleSendGridDelivery,
   listTemplateEntries: () => listTemplateEntries,
   listTemplateRevisions: () => listTemplateRevisions,
+  renderFragment: () => renderFragment,
   rollbackTemplate: () => rollbackTemplate,
   setTemplate: () => setTemplate,
   validateCourierConfig: () => validateCourierConfig
@@ -503,11 +505,35 @@ function composeHtml(bodyHtml, layoutHtml, subject, data) {
   const wrapped = wrapLayout(bodyHtml, layoutHtml);
   return render(wrapped, { subject: subject ?? "", preheader: "", ...data });
 }
+function renderFragment(frag, layoutHtml, data) {
+  const subject = frag.subject ? render(frag.subject, data) : void 0;
+  return {
+    text: render(frag.text, data),
+    ...subject ? { subject } : {},
+    ...frag.html ? { html: composeHtml(frag.html, layoutHtml, subject, data) } : {}
+  };
+}
+var DefaultTemplates = class {
+  map = /* @__PURE__ */ new Map();
+  constructor(maps = []) {
+    for (const m of maps) {
+      for (const [key, tmpl] of Object.entries(m)) this.map.set(key, tmpl);
+    }
+  }
+  get(type) {
+    return this.map.get(type);
+  }
+  get size() {
+    return this.map.size;
+  }
+};
 var DBTemplateResolver = class {
-  constructor(store) {
+  constructor(store, defaults) {
     this.store = store;
+    this.defaults = defaults;
   }
   store;
+  defaults;
   async resolve(type, data, locale) {
     const [row] = await this.store.query(
       // Serve the exact locale, else the neutral NULL default — never a
@@ -521,15 +547,14 @@ var DBTemplateResolver = class {
       [type, locale ?? null]
     );
     if (!row) {
+      const def = this.defaults?.get(type);
+      if (def) {
+        return renderFragment(def, def.html ? await this.layout(locale) : void 0, data);
+      }
       return { text: `${type}: ${JSON.stringify(data)}` };
     }
-    const subject = row.subject ? render(row.subject, data) : void 0;
     const layoutHtml = row.html ? await this.layout(locale) : void 0;
-    return {
-      text: render(row.text, data),
-      ...subject ? { subject } : {},
-      ...row.html ? { html: composeHtml(row.html, layoutHtml, subject, data) } : {}
-    };
+    return renderFragment(row, layoutHtml, data);
   }
   // Optional founder-supplied layout shell; undefined → built-in default.
   async layout(locale) {
@@ -545,10 +570,12 @@ var DBTemplateResolver = class {
   }
 };
 var FSTemplateResolver = class {
-  constructor(directory) {
+  constructor(directory, defaults) {
     this.directory = directory;
+    this.defaults = defaults;
   }
   directory;
+  defaults;
   async resolve(type, data, locale) {
     const { readFile } = await import("fs/promises");
     const { join } = await import("path");
@@ -575,6 +602,13 @@ var FSTemplateResolver = class {
         (v) => v ?? readOptional(join(this.directory, `${LAYOUT_TYPE}.html`))
       ) : readOptional(join(this.directory, `${LAYOUT_TYPE}.html`))
     ]);
+    if (text === null && html === null && subject === null) {
+      const def = this.defaults?.get(type);
+      if (def) {
+        return renderFragment(def, def.html ? layout ?? void 0 : void 0, data);
+      }
+      return { text: `${type}: ${JSON.stringify(data)}` };
+    }
     const renderedSubject = subject ? render(subject, data) : void 0;
     return {
       text: text ? render(text, data) : `${type}: ${JSON.stringify(data)}`,
@@ -612,6 +646,7 @@ function validateCourierConfig(config, registeredChannels) {
 
 // src/delivery.ts
 var import_node_crypto = require("crypto");
+var import_core = require("@fonderie/core");
 async function handleSendGridDelivery(req, store, webhookSecret) {
   if (webhookSecret) {
     const sig = req.headers.get("x-twilio-email-event-webhook-signature") ?? "";
@@ -634,10 +669,7 @@ function verifySendGridSignature(secret, timestamp, body2, signature) {
   try {
     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");
-    if (sigBuf.length !== expBuf.length) return false;
-    return (0, import_node_crypto.timingSafeEqual)(sigBuf, expBuf);
+    return (0, import_core.constantTimeEqual)(Buffer.from(signature, "base64"), Buffer.from(expected, "base64"));
   } catch {
     return false;
   }
@@ -683,10 +715,7 @@ 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);
+    return (0, import_core.constantTimeEqual)(Buffer.from(expected, "hex"), Buffer.from(signature, "hex"));
   } catch {
     return false;
   }
@@ -745,7 +774,7 @@ function parseJson(text) {
 }
 
 // src/templates/admin-routes.ts
-var import_core = require("@fonderie/core");
+var import_core2 = require("@fonderie/core");
 var import_middlewares = require("@fonderie/core/middlewares");
 var import_store2 = require("@fonderie/store");
 
@@ -824,7 +853,7 @@ 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, {
+    return (0, import_core2.setApiResponse)(import_core2.HTTP.CONFLICT, "VERSION_CONFLICT", err.message, {
       currentVersion: err.currentVersion
     });
   }
@@ -834,16 +863,16 @@ 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));
+      return (0, import_core2.setApiResponse)(import_core2.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");
+      return row ? (0, import_core2.setApiResponse)(import_core2.HTTP.OK, "TEMPLATE", "Template", row) : (0, import_core2.setApiResponse)(import_core2.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");
+        return (0, import_core2.setApiResponse)(import_core2.HTTP.UNPROCESSABLE, "INVALID", "body.text (string) is required");
       }
       try {
         const opts = {
@@ -856,29 +885,29 @@ function buildTemplateAdminRoutes(store, adminToken) {
         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));
+        return (0, import_core2.setApiResponse)(import_core2.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");
+      return (0, import_core2.setApiResponse)(ok ? import_core2.HTTP.OK : import_core2.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));
+      return (0, import_core2.setApiResponse)(import_core2.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");
+        return (0, import_core2.setApiResponse)(import_core2.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);
+      return (0, import_core2.setApiResponse)(import_core2.HTTP.OK, "ROLLED_BACK", `Rolled back to v${toVersion}`, row);
     })]
   ];
 }
@@ -946,13 +975,15 @@ var CourierModule = class {
   }
 };
 function createTemplateResolver(source, config, store) {
+  const input = config.templates?.defaults;
+  const defaults = new DefaultTemplates(input ? Array.isArray(input) ? input : [input] : []);
   if (source === "fs") {
-    return new FSTemplateResolver(config.templates?.directory ?? "./templates");
+    return new FSTemplateResolver(config.templates?.directory ?? "./templates", defaults);
   }
   if (!store) {
     throw new Error("[courier] store is required for DB template resolution");
   }
-  return new DBTemplateResolver(store);
+  return new DBTemplateResolver(store, defaults);
 }
 
 // src/config.ts
@@ -966,6 +997,7 @@ var Channel = {
   Channel,
   CourierModule,
   DBTemplateResolver,
+  DefaultTemplates,
   Dispatcher,
   EmailChannel,
   FSTemplateResolver,
@@ -979,6 +1011,7 @@ var Channel = {
   handleSendGridDelivery,
   listTemplateEntries,
   listTemplateRevisions,
+  renderFragment,
   rollbackTemplate,
   setTemplate,
   validateCourierConfig