@antelopejs/dms-mailing 0.3.4 → 0.4.0

package/src/engine/coverage.ts

@@ -35,7 +35,8 @@ const COLLECTORS: Record<Block["type"], PathCollector> = {
 const isUserPath = (path: string): boolean =>
   !SYSTEM_VARIABLE_PATHS.includes(path);
 
-export function collectVariablePaths(content: LocaleContent): string[] {
+/** Every path the content references, the system ones included. */
+export function collectReferencedPaths(content: LocaleContent): string[] {
   const paths = new Set<string>(textTokens(content.subject, content.preheader));
   walkBlocks(content.blocks, (block) => {
     for (const path of COLLECTORS[block.type](block)) {
@@ -43,7 +44,11 @@ export function collectVariablePaths(content: LocaleContent): string[] {
     }
     if (block.visibleIf) paths.add(normalizePath(block.visibleIf.path));
   });
-  return [...paths].filter(isUserPath).sort();
+  return [...paths].sort();
+}
+
+export function collectVariablePaths(content: LocaleContent): string[] {
+  return collectReferencedPaths(content).filter(isUserPath);
 }
 
 /** Every variable path the content references, across all of its locales. */

package/src/engine/fallback-html.ts

@@ -11,6 +11,12 @@ const ESCAPES: Record<string, string> = {
 export const escapeHtml = (value: string): string =>
   value.replace(/[&<>"']/g, (char) => ESCAPES[char] ?? char);
 
+const LINE_BREAK = /\r?\n/g;
+
+/** Escaped text whose line breaks survive as `<br>`, as typed in the editor. */
+const escapeLines = (value: string): string =>
+  escapeHtml(value).replace(LINE_BREAK, "<br>");
+
 const SAFE_SCHEMES = ["http:", "https:", "mailto:"];
 const BLOCKED_HREF = "#";
 const SCHEME_PATTERN = /^\s*([a-z][a-z0-9+.-]*):/i;
@@ -19,56 +25,90 @@ const SCHEME_PATTERN = /^\s*([a-z][a-z0-9+.-]*):/i;
  * A link target can be an interpolated variable, so it is data the sender does
  * not control. Escaping the entities keeps it inside the attribute; this keeps
  * the scheme to one a mail client may follow. A target with no scheme is
- * relative (or still an unresolved token) and passes through.
+ * relative (or still an unresolved token) and passes through; a blocked one
+ * becomes `blocked`.
  */
-export const safeUrl = (value: string): string => {
+export const safeUrl = (
+  value: string,
+  blocked: string = BLOCKED_HREF,
+): string => {
   const scheme = SCHEME_PATTERN.exec(value);
   if (!scheme) return value;
   return SAFE_SCHEMES.includes(scheme[1]!.toLowerCase() + ":")
     ? value
-    : BLOCKED_HREF;
+    : blocked;
 };
 
+/**
+ * The font, palette and spacing below are those of the DMS e-mail layout
+ * (`emailStyles` of the dms-layout), so an e-mail looks the same whichever
+ * renderer drew it.
+ */
 const FONT =
-  "font-family:-apple-system,Segoe UI,Roboto,Helvetica,Arial,sans-serif";
-const TEXT_COLOR = "#4c545c";
-const HEADING_COLOR = "#16181b";
-const BORDER_COLOR = "#e7e9ec";
-const MUTED_COLOR = "#98a0a8";
-const SURFACE_COLOR = "#f7f8fa";
-const BUTTON_STYLE =
-  "display:inline-block;padding:12px 22px;border-radius:6px;background:#111417;color:#ffffff;text-decoration:none;font-weight:600";
+  "font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif";
+const WRAP = "overflow-wrap:anywhere;word-break:break-word";
+const TEXT_COLOR = "#525252";
+const HEADING_COLOR = "#1a1a1a";
+const BORDER_COLOR = "#e4e4e7";
+const MUTED_COLOR = "#71717a";
+const PAGE_COLOR = "#f6f9fc";
+const CODE_SURFACE = "#f4f4f5";
+const CODE_COLOR = "#18181b";
+const CODE_FONT = "font-family:'SF Mono',Monaco,'Courier New',monospace";
+const TEXT_STYLE = `${FONT};font-size:15px;line-height:1.6;color:${TEXT_COLOR};${WRAP}`;
+const BLOCK_SPACING = "margin:0 0 16px";
+const BUTTON_STYLE = `display:inline-block;padding:12px 24px;border-radius:6px;background:${CODE_COLOR};color:#ffffff;text-decoration:none;font-size:15px;font-weight:600`;
+const DIVIDER = `<hr style="border:0;border-top:1px solid ${BORDER_COLOR};margin:32px 0">`;
+const FOOTER_STYLE = `${FONT};font-size:12px;line-height:1.5;color:${MUTED_COLOR};text-align:center;margin:0;${WRAP}`;
+const FOOTER_LINK_SEPARATOR = " · ";
 const CONTENT_WIDTH = 600;
+const VIEWPORT = "width=device-width, initial-scale=1";
 
 type BlockHtml = (block: ResolvedBlock) => string;
 
 const link = (label: string, href: string): string =>
   href
-    ? `<a href="${escapeHtml(safeUrl(href))}" style="color:${TEXT_COLOR}">${escapeHtml(label)}</a>`
+    ? `<a href="${escapeHtml(safeUrl(href))}" style="color:${MUTED_COLOR};text-decoration:underline">${escapeHtml(label)}</a>`
     : "";
 
-const cellStyle = (weight: string, color: string): string =>
-  `${FONT};font-size:13px;font-weight:${weight};padding:11px 14px;color:${color}`;
+const row = (label: string, value: string, weight: string): string =>
+  `<tr><td style="${TEXT_STYLE};font-weight:${weight}">${escapeHtml(label)}</td><td align="right" style="${TEXT_STYLE};font-weight:${weight};text-align:right">${escapeHtml(value)}</td></tr>`;
+
+const table = (rows: string): string =>
+  `<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="${BLOCK_SPACING}">${rows}</table>`;
 
 const TEXT_RENDERERS: Record<string, BlockHtml> = {
   heading: (block) =>
     block.type === "heading"
-      ? `<h1 style="${FONT};font-size:${block.size}px;color:${HEADING_COLOR};text-align:${block.align};margin:0 0 12px">${escapeHtml(block.text)}</h1>`
+      ? `<h1 style="${FONT};font-size:${block.size}px;font-weight:600;color:${HEADING_COLOR};text-align:${block.align};margin:0 0 24px;${WRAP}">${escapeLines(block.text)}</h1>`
       : "",
   paragraph: (block) =>
     block.type === "paragraph"
-      ? `<p style="${FONT};font-size:14px;line-height:1.6;color:${TEXT_COLOR};text-align:${block.align};margin:0 0 18px">${escapeHtml(block.text)}</p>`
+      ? `<p style="${TEXT_STYLE};text-align:${block.align};${BLOCK_SPACING}">${escapeLines(block.text)}</p>`
       : "",
   code: (block) =>
     block.type === "code"
-      ? `<div style="${FONT};font-size:27px;letter-spacing:.32em;text-align:center;padding:18px;border:1px dashed ${BORDER_COLOR};border-radius:8px;margin:0 0 16px">${escapeHtml(block.text)}</div>`
+      ? `<div style="background:${CODE_SURFACE};border-radius:6px;margin:24px 0;padding:20px;text-align:center"><p style="${CODE_FONT};font-size:32px;font-weight:700;letter-spacing:6px;color:${CODE_COLOR};margin:0;${WRAP}">${escapeHtml(block.text)}</p></div>`
       : "",
   button: (block) =>
     block.type === "button"
-      ? `<div style="text-align:${block.align};margin:0 0 18px"><a href="${escapeHtml(safeUrl(block.href))}" style="${FONT};${BUTTON_STYLE}">${escapeHtml(block.text)}</a></div>`
+      ? `<div style="text-align:${block.align};margin:24px 0"><a href="${escapeHtml(safeUrl(block.href))}" style="${FONT};${BUTTON_STYLE}">${escapeHtml(block.text)}</a></div>`
       : "",
 };
 
+const footerHtml = (block: ResolvedBlock): string => {
+  if (block.type !== "footer") return "";
+  const links = [
+    link(block.unsubscribeLabel, block.unsubscribeUrl),
+    link(block.preferencesLabel, block.preferencesUrl),
+  ]
+    .filter(Boolean)
+    .join(FOOTER_LINK_SEPARATOR);
+  if (!block.text.trim() && !links) return "";
+  const linkLine = links ? `<br>${links}` : "";
+  return `${DIVIDER}<p style="${FOOTER_STYLE}">${escapeLines(block.text)}${linkLine}</p>`;
+};
+
 const LAYOUT_RENDERERS: Record<string, BlockHtml> = {
   hero: (block) =>
     block.type === "hero" && block.imageUrl
@@ -76,28 +116,14 @@ const LAYOUT_RENDERERS: Record<string, BlockHtml> = {
       : "",
   list: (block) =>
     block.type === "list"
-      ? `<table role="presentation" width="100%" style="border:1px solid ${BORDER_COLOR};border-radius:8px;margin:0 0 18px">${block.rows
-          .map(
-            (row) =>
-              `<tr><td style="${cellStyle("400", TEXT_COLOR)}">${escapeHtml(row.label)}</td><td align="right" style="${cellStyle("400", HEADING_COLOR)}">${escapeHtml(row.value)}</td></tr>`,
-          )
-          .join("")}</table>`
+      ? table(
+          block.rows.map((item) => row(item.label, item.value, "400")).join(""),
+        )
       : "",
   total: (block) =>
-    block.type === "total"
-      ? `<table role="presentation" width="100%" style="margin:0 0 18px"><tr><td style="${cellStyle("600", HEADING_COLOR)};background:${SURFACE_COLOR}">${escapeHtml(block.label)}</td><td align="right" style="${cellStyle("600", HEADING_COLOR)};background:${SURFACE_COLOR}">${escapeHtml(block.value)}</td></tr></table>`
-      : "",
-  divider: () =>
-    `<hr style="border:0;border-top:1px solid ${BORDER_COLOR};margin:10px 0 18px">`,
-  footer: (block) =>
-    block.type === "footer"
-      ? `<div style="${FONT};font-size:11px;line-height:1.6;color:${MUTED_COLOR};border-top:1px solid ${BORDER_COLOR};padding:16px 0 0">${escapeHtml(block.text)}<br>${[
-          link(block.unsubscribeLabel, block.unsubscribeUrl),
-          link(block.preferencesLabel, block.preferencesUrl),
-        ]
-          .filter(Boolean)
-          .join(" · ")}</div>`
-      : "",
+    block.type === "total" ? table(row(block.label, block.value, "600")) : "",
+  divider: () => DIVIDER,
+  footer: footerHtml,
 };
 
 const RENDERERS: Record<ResolvedBlock["type"], BlockHtml> = {
@@ -105,12 +131,24 @@ const RENDERERS: Record<ResolvedBlock["type"], BlockHtml> = {
   ...LAYOUT_RENDERERS,
 } as Record<ResolvedBlock["type"], BlockHtml>;
 
+const FOOTER_TYPE = "footer";
+
+const renderBlocks = (blocks: ResolvedBlock[]): string =>
+  blocks.map((block) => RENDERERS[block.type](block)).join("");
+
+/**
+ * The e-mail without the DMS front end: the same blocks, in the same order and
+ * look as the Vue template, the footer last, under its divider.
+ */
 export function renderFallbackHtml(
   email: ResolvedEmail,
   locale: string,
 ): string {
-  const body = email.blocks
-    .map((block) => RENDERERS[block.type](block))
-    .join("");
-  return `<!DOCTYPE html><html lang="${escapeHtml(locale)}"><head><meta charset="utf-8"><title>${escapeHtml(email.subject)}</title></head><body style="margin:0;background:${SURFACE_COLOR}"><span style="display:none;max-height:0;overflow:hidden">${escapeHtml(email.preheader)}</span><table role="presentation" width="100%"><tr><td align="center" style="padding:26px"><table role="presentation" width="${CONTENT_WIDTH}" style="max-width:${CONTENT_WIDTH}px;background:#ffffff;border-radius:10px"><tr><td style="padding:26px">${body}</td></tr></table></td></tr></table></body></html>`;
+  const body = renderBlocks(
+    email.blocks.filter((block) => block.type !== FOOTER_TYPE),
+  );
+  const footer = renderBlocks(
+    email.blocks.filter((block) => block.type === FOOTER_TYPE),
+  );
+  return `<!DOCTYPE html><html lang="${escapeHtml(locale)}"><head><meta charset="utf-8"><meta name="viewport" content="${VIEWPORT}"><title>${escapeHtml(email.subject)}</title></head><body style="margin:0;background:${PAGE_COLOR};${FONT}"><span style="display:none;max-height:0;overflow:hidden">${escapeHtml(email.preheader)}</span><table role="presentation" width="100%"><tr><td align="center" style="padding:20px 0 48px"><table role="presentation" width="${CONTENT_WIDTH}" style="max-width:${CONTENT_WIDTH}px;width:100%;background:#ffffff;border-radius:8px;box-shadow:0 1px 3px rgba(0,0,0,0.1)"><tr><td style="padding:40px">${body}${footer}</td></tr></table></td></tr></table></body></html>`;
 }

package/src/engine/index.ts

@@ -1,7 +1,10 @@
+export * from "./changes";
 export * from "./conditions";
 export * from "./coverage";
 export * from "./fallback-html";
 export * from "./paths";
+export * from "./plain-text";
 export * from "./resolve";
+export * from "./system-variables";
 export * from "./tokens";
 export * from "./walk";

package/src/engine/plain-text.ts

@@ -0,0 +1,86 @@
+import type { ResolvedBlock, ResolvedEmail } from "../types";
+
+type BlockText = (block: ResolvedBlock, separator: string) => string;
+
+const PARAGRAPH_BREAK = "\n\n";
+const LINE_BREAK = "\n";
+const DEFAULT_LABEL_SEPARATOR = ": ";
+const LOCALE_PARTS = /[-_]/;
+const DIVIDER = "----------";
+const FOOTER_TYPE = "footer";
+
+/**
+ * Languages whose typography spaces a colon off its label, with a no-break
+ * space so the colon never starts a line ("Total : 64,00 €").
+ */
+const LABEL_SEPARATORS: Record<string, string> = {
+  fr: " : ",
+};
+
+/** What goes between a label and its value in the e-mail's language. */
+export function labelSeparatorOf(locale = ""): string {
+  const language = locale.toLowerCase().split(LOCALE_PARTS)[0] ?? "";
+  return LABEL_SEPARATORS[language] ?? DEFAULT_LABEL_SEPARATOR;
+}
+
+const linked = (label: string, href: string, separator: string): string =>
+  href ? `${label}${separator}${href}` : "";
+
+const rowsText = (rows: string[][], separator: string): string =>
+  rows
+    .map((cells) => cells.filter(Boolean).join(separator))
+    .filter(Boolean)
+    .join(LINE_BREAK);
+
+const footerText = (block: ResolvedBlock, separator: string): string => {
+  if (block.type !== FOOTER_TYPE) return "";
+  const lines = [
+    block.text,
+    linked(block.unsubscribeLabel, block.unsubscribeUrl, separator),
+    linked(block.preferencesLabel, block.preferencesUrl, separator),
+  ].filter((line) => line.trim());
+  return lines.length ? [DIVIDER, ...lines].join(LINE_BREAK) : "";
+};
+
+const BLOCK_TEXT: Record<ResolvedBlock["type"], BlockText> = {
+  hero: (block) => (block.type === "hero" && block.imageUrl ? block.alt : ""),
+  heading: (block) => (block.type === "heading" ? block.text : ""),
+  paragraph: (block) => (block.type === "paragraph" ? block.text : ""),
+  code: (block) => (block.type === "code" ? block.text : ""),
+  list: (block, separator) =>
+    block.type === "list"
+      ? rowsText(
+          block.rows.map((row) => [row.label, row.value]),
+          separator,
+        )
+      : "",
+  total: (block, separator) =>
+    block.type === "total"
+      ? rowsText([[block.label, block.value]], separator)
+      : "",
+  button: (block, separator) =>
+    block.type === "button" ? linked(block.text, block.href, separator) : "",
+  divider: () => DIVIDER,
+  footer: footerText,
+};
+
+const blocksText = (blocks: ResolvedBlock[], separator: string): string[] =>
+  blocks
+    .map((block) => BLOCK_TEXT[block.type](block, separator).trim())
+    .filter(Boolean);
+
+/**
+ * The plain-text part of the e-mail: the same blocks as the HTML, in the same
+ * order, footer last, punctuated the way the e-mail's language writes it.
+ * Mail clients that show no HTML, and spam filters that weigh a missing text
+ * part, read this one.
+ */
+export function renderPlainText(email: ResolvedEmail, locale = ""): string {
+  const separator = labelSeparatorOf(locale);
+  const body = email.blocks.filter((block) => block.type !== FOOTER_TYPE);
+  const footer = email.blocks.filter((block) => block.type === FOOTER_TYPE);
+  return [
+    ...blocksText(body, separator),
+    ...blocksText(footer, separator),
+  ].join(PARAGRAPH_BREAK);
+}

package/src/engine/resolve.ts

@@ -1,6 +1,11 @@
-import { SYSTEM_VARIABLE_PATHS } from "../constants";
+import {
+  PREFERENCES_URL_PATH,
+  SYSTEM_VARIABLE_PATHS,
+  UNSUBSCRIBE_URL_PATH,
+} from "../constants";
 import type {
   Block,
+  FooterBlock,
   IfBlock,
   ListBlock,
   LocaleContent,
@@ -9,28 +14,51 @@ import type {
   ResolvedListRow,
 } from "../types";
 import { evaluateCondition } from "./conditions";
+import { safeUrl } from "./fallback-html";
 import { getPath, isPresent } from "./paths";
-import { interpolate } from "./tokens";
+import { footerLinkPaths } from "./system-variables";
+import { type InterpolationMode, interpolate } from "./tokens";
 
 type Data = Record<string, unknown>;
 
 interface ResolveState {
   data: Data;
+  mode: InterpolationMode;
   missing: Set<string>;
   hidden: string[];
 }
 
+/** A blocked image source: the hero is left out rather than drawn broken. */
+const BLOCKED_IMAGE = "";
+
 type BlockResolver = (block: Block, state: ResolveState) => ResolvedBlock[];
 
 function text(state: ResolveState, value: string): string {
-  const result = interpolate(value, state.data);
+  const result = interpolate(value, state.data, state.mode);
   for (const path of result.missing) state.missing.add(path);
   return result.text;
 }
 
-function systemUrl(state: ResolveState, path: string): string {
+/**
+ * A link or image target, filtered here so both renderers (the Vue e-mail
+ * and the fallback) receive a scheme a mail client may follow.
+ */
+function url(state: ResolveState, value: string, blocked?: string): string {
+  return safeUrl(text(state, value), blocked);
+}
+
+/**
+ * A footer link's target, read from the data the caller passed. A link whose
+ * label was cleared is left out, whatever URL the caller gave.
+ */
+function systemUrl(
+  state: ResolveState,
+  block: FooterBlock,
+  path: string,
+): string {
+  if (!footerLinkPaths(block).includes(path)) return "";
   const value = getPath(state.data, path);
-  return isPresent(value) ? String(value) : "";
+  return isPresent(value) ? safeUrl(String(value)) : "";
 }
 
 function cell(item: unknown, path: string): string {
@@ -65,7 +93,7 @@ const RESOLVERS: Record<Block["type"], BlockResolver> = {
           {
             id: block.id,
             type: "hero",
-            imageUrl: text(state, block.imageUrl),
+            imageUrl: url(state, block.imageUrl, BLOCKED_IMAGE),
             alt: text(state, block.alt),
           },
         ]
@@ -119,7 +147,7 @@ const RESOLVERS: Record<Block["type"], BlockResolver> = {
             id: block.id,
             type: "button",
             text: text(state, block.text),
-            href: text(state, block.href),
+            href: url(state, block.href),
             align: block.align,
           },
         ]
@@ -135,20 +163,21 @@ const RESOLVERS: Record<Block["type"], BlockResolver> = {
             text: text(state, block.text),
             unsubscribeLabel: block.unsubscribeLabel,
             preferencesLabel: block.preferencesLabel,
-            unsubscribeUrl: systemUrl(state, "unsubscribeUrl"),
-            preferencesUrl: systemUrl(state, "preferencesUrl"),
+            unsubscribeUrl: systemUrl(state, block, UNSUBSCRIBE_URL_PATH),
+            preferencesUrl: systemUrl(state, block, PREFERENCES_URL_PATH),
           },
         ]
       : [],
 };
 
+/**
+ * Visibility decides before a block is resolved, not after: resolving first
+ * would record a hidden block's unresolved paths in `state.missing`, and
+ * `blockOnMissingVariables` refuses a send on that set, so a hidden block
+ * could block a send over a variable it never rendered.
+ */
 function resolveBlocks(blocks: Block[], state: ResolveState): ResolvedBlock[] {
   return blocks.flatMap((block) => {
-    // Visibility decides before the block is resolved, not after. Resolving
-    // first recorded the block's unresolved paths in `state.missing` even
-    // though it was then discarded — and `blockOnMissingVariables` refuses a
-    // send on that set, so a hidden block could block a send over a variable
-    // it never rendered.
     if (block.visibleIf && !evaluateCondition(block.visibleIf, state.data)) {
       state.hidden.push(block.id);
       return [];
@@ -160,11 +189,16 @@ function resolveBlocks(blocks: Block[], state: ResolveState): ResolvedBlock[] {
 const isUserPath = (path: string): boolean =>
   !SYSTEM_VARIABLE_PATHS.includes(path);
 
+/**
+ * Resolves `content` against `data`. A real send passes `send` so a missing
+ * value leaves a blank; previews keep the token visible.
+ */
 export function resolveEmail(
   content: LocaleContent,
   data: Data,
+  mode: InterpolationMode = "preview",
 ): ResolvedEmail {
-  const state: ResolveState = { data, missing: new Set(), hidden: [] };
+  const state: ResolveState = { data, mode, missing: new Set(), hidden: [] };
   const subject = text(state, content.subject);
   const preheader = text(state, content.preheader);
   const blocks = resolveBlocks(content.blocks, state);

package/src/engine/system-variables.ts

@@ -0,0 +1,124 @@
+import {
+  PREFERENCES_URL_PATH,
+  SYSTEM_VARIABLE_PATHS,
+  UNSUBSCRIBE_URL_PATH,
+} from "../constants";
+import type {
+  Block,
+  FooterBlock,
+  LocaleContent,
+  TemplateContent,
+  VariableDefinition,
+} from "../types";
+import { collectReferencedPaths } from "./coverage";
+import { getPath, isPresent } from "./paths";
+import { walkBlocks } from "./walk";
+
+/**
+ * The category whose e-mails are campaigns; every other one is transactional.
+ * The settings keep it: it can be renamed, never removed.
+ */
+export const MARKETING_CATEGORY = "marketing";
+
+const SYSTEM_VARIABLE_TYPE = "url";
+
+type FooterLabelKey = "unsubscribeLabel" | "preferencesLabel";
+
+/** Each footer link: the label that shows it and the URL the caller passes. */
+const FOOTER_LINKS: Record<FooterLabelKey, string> = {
+  unsubscribeLabel: UNSUBSCRIBE_URL_PATH,
+  preferencesLabel: PREFERENCES_URL_PATH,
+};
+
+const LABEL_KEYS = Object.keys(FOOTER_LINKS) as FooterLabelKey[];
+
+export function isMarketingCategory(category?: string | null): boolean {
+  return category === MARKETING_CATEGORY;
+}
+
+/**
+ * Whether a new footer of this category carries the unsubscribe and
+ * preferences links: a transactional e-mail (an order, a password reset…)
+ * is not subscribed to, so only an uncategorised or marketing one does.
+ */
+export function hasFooterLinksByDefault(category?: string | null): boolean {
+  return !category || isMarketingCategory(category);
+}
+
+const isFooter = (block: Block): block is FooterBlock =>
+  block.type === "footer";
+
+/** The URL paths a footer shows a link for: the ones with a label. */
+export function footerLinkPaths(block: FooterBlock): string[] {
+  return LABEL_KEYS.filter((key) => block[key].trim()).map(
+    (key) => FOOTER_LINKS[key],
+  );
+}
+
+/** The system paths a locale uses: footer links, then `{{…}}` references. */
+export function localeSystemPaths(content: LocaleContent): string[] {
+  const paths = new Set<string>();
+  walkBlocks(content.blocks, (block) => {
+    if (isFooter(block)) footerLinkPaths(block).forEach((p) => paths.add(p));
+  });
+  collectReferencedPaths(content)
+    .filter((path) => SYSTEM_VARIABLE_PATHS.includes(path))
+    .forEach((path) => paths.add(path));
+  return SYSTEM_VARIABLE_PATHS.filter((path) => paths.has(path));
+}
+
+/** The system paths any locale of the content uses. */
+export function contentSystemPaths(content: TemplateContent): string[] {
+  const used = new Set(
+    Object.values(content.locales).flatMap(localeSystemPaths),
+  );
+  return SYSTEM_VARIABLE_PATHS.filter((path) => used.has(path));
+}
+
+/**
+ * The URLs a template's caller passes for the links its content shows,
+ * declared like any variable of its contract: a marketing e-mail must carry a
+ * working unsubscribe link, so they are required there.
+ */
+export function systemVariables(
+  paths: string[],
+  category?: string | null,
+): VariableDefinition[] {
+  const required = isMarketingCategory(category);
+  return paths.map((path) => ({ path, type: SYSTEM_VARIABLE_TYPE, required }));
+}
+
+/** The required system URLs `data` does not provide. */
+export function missingSystemVariables(
+  content: LocaleContent,
+  category: string | null | undefined,
+  data: Record<string, unknown>,
+): string[] {
+  return systemVariables(localeSystemPaths(content), category)
+    .filter((variable) => variable.required)
+    .map((variable) => variable.path)
+    .filter((path) => !isPresent(getPath(data, path)));
+}
+
+const withoutLinks = (block: Block): Block =>
+  isFooter(block)
+    ? { ...block, unsubscribeLabel: "", preferencesLabel: "" }
+    : block;
+
+/**
+ * The content with the footers its category calls for: a transactional
+ * template loses the unsubscribe and preferences links.
+ */
+export function footerForCategory(
+  content: TemplateContent,
+  category?: string | null,
+): TemplateContent {
+  if (hasFooterLinksByDefault(category)) return content;
+  const locales = Object.fromEntries(
+    Object.entries(content.locales).map(([code, locale]) => [
+      code,
+      { ...locale, blocks: locale.blocks.map(withoutLinks) },
+    ]),
+  );
+  return { ...content, locales };
+}

package/src/engine/tokens.ts

@@ -2,11 +2,22 @@ import { getPath, isPresent } from "./paths";
 
 export const TOKEN_PATTERN = /\{\{\s*([A-Za-z0-9_.[\]]+)\s*\}\}/g;
 
+/**
+ * How a token without a value prints. `preview` keeps it visible so an author
+ * sees what is missing; `send` blanks it, so a recipient never reads braces.
+ */
+export type InterpolationMode = "preview" | "send";
+
 export interface InterpolationResult {
   text: string;
   missing: string[];
 }
 
+const MISSING_TOKEN: Record<InterpolationMode, (token: string) => string> = {
+  preview: (token) => token,
+  send: () => "",
+};
+
 export function extractTokens(text: string): string[] {
   const found = new Set<string>();
   for (const match of text.matchAll(TOKEN_PATTERN))
@@ -21,13 +32,14 @@ function formatValue(value: unknown): string {
 export function interpolate(
   text: string,
   data: Record<string, unknown>,
+  mode: InterpolationMode = "preview",
 ): InterpolationResult {
   const missing = new Set<string>();
   const output = text.replace(TOKEN_PATTERN, (token, path: string) => {
     const value = getPath(data, path);
     if (!isPresent(value)) {
       missing.add(path);
-      return token;
+      return MISSING_TOKEN[mode](token);
     }
     return formatValue(value);
   });

package/src/hooks/tenant-export.ts

@@ -9,7 +9,12 @@ import {
   UnregisterHook,
 } from "@antelopejs/interface-dms/hooks";
 import { MODULE_ID } from "../constants";
-import { SettingsModel, TemplateModel } from "../db";
+import {
+  SettingsModel,
+  SuppressionModel,
+  TemplateModel,
+  TemplateVersionModel,
+} from "../db";
 import type { MailingSettingsValues } from "../types";
 
 export type ExportedSettings = Omit<MailingSettingsValues, "webhookSecret">;
@@ -32,7 +37,9 @@ export interface ExportedCollection {
 export const TENANT_EXPORT_PAGE_SIZE = 200;
 
 const TEMPLATES_ENTRY = "templates.json";
+const TEMPLATE_VERSIONS_ENTRY = "template-versions.json";
 const SETTINGS_ENTRY = "settings.json";
+const SUPPRESSIONS_ENTRY = "suppressions.json";
 
 const ARRAY_OPEN = "[";
 const ARRAY_CLOSE = "]";
@@ -64,7 +71,7 @@ export async function* jsonArrayChunks<T>(
 async function exportedSettings(
   tenantId: string,
 ): Promise<ExportedSettings | null> {
-  const row = await GetModel(SettingsModel, tenantId).getSingleton(tenantId);
+  const row = await GetModel(SettingsModel, tenantId).get(tenantId);
   if (!row) return null;
   return {
     fallbackLocale: row.fallbackLocale,
@@ -93,12 +100,24 @@ async function loadPage<T extends object>(
 
 export function exportedCollections(tenantId: string): ExportedCollection[] {
   const templates = GetModel(TemplateModel, tenantId);
+  const versions = GetModel(TemplateVersionModel, tenantId);
+  const suppressions = GetModel(SuppressionModel, tenantId);
   return [
     {
       entry: TEMPLATES_ENTRY,
       load: (offset, size) =>
         loadPage(templates.table, TemplateModel, offset, size),
     },
+    {
+      entry: TEMPLATE_VERSIONS_ENTRY,
+      load: (offset, size) =>
+        loadPage(versions.table, TemplateVersionModel, offset, size),
+    },
+    {
+      entry: SUPPRESSIONS_ENTRY,
+      load: (offset, size) =>
+        loadPage(suppressions.table, SuppressionModel, offset, size),
+    },
   ];
 }
 

package/src/implementations/dms-mailing/index.ts

@@ -1,2 +1,2 @@
 export { recordEmailEvent as RecordEmailEvent } from "../../services/events";
-export { sendTemplate as SendTemplate } from "../../services/send";
+export { sendUnlessSuppressed as SendTemplate } from "../../services/checked-send";