@antelopejs/dms-mailing 0.2.2

package/src/engine/fallback-html.ts

@@ -0,0 +1,116 @@
+import type { ResolvedBlock, ResolvedEmail } from "../types";
+
+const ESCAPES: Record<string, string> = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;",
+};
+
+export const escapeHtml = (value: string): string =>
+  value.replace(/[&<>"']/g, (char) => ESCAPES[char] ?? char);
+
+const SAFE_SCHEMES = ["http:", "https:", "mailto:"];
+const BLOCKED_HREF = "#";
+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.
+ */
+export const safeUrl = (value: string): string => {
+  const scheme = SCHEME_PATTERN.exec(value);
+  if (!scheme) return value;
+  return SAFE_SCHEMES.includes(scheme[1]!.toLowerCase() + ":")
+    ? value
+    : BLOCKED_HREF;
+};
+
+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";
+const CONTENT_WIDTH = 600;
+
+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>`
+    : "";
+
+const cellStyle = (weight: string, color: string): string =>
+  `${FONT};font-size:13px;font-weight:${weight};padding:11px 14px;color:${color}`;
+
+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>`
+      : "",
+  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>`
+      : "",
+  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>`
+      : "",
+  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>`
+      : "",
+};
+
+const LAYOUT_RENDERERS: Record<string, BlockHtml> = {
+  hero: (block) =>
+    block.type === "hero" && block.imageUrl
+      ? `<img src="${escapeHtml(safeUrl(block.imageUrl))}" alt="${escapeHtml(block.alt)}" style="display:block;width:100%;border-radius:8px;margin:0 0 20px">`
+      : "",
+  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>`
+      : "",
+  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>`
+      : "",
+};
+
+const RENDERERS: Record<ResolvedBlock["type"], BlockHtml> = {
+  ...TEXT_RENDERERS,
+  ...LAYOUT_RENDERERS,
+} as Record<ResolvedBlock["type"], BlockHtml>;
+
+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>`;
+}

package/src/engine/index.ts

@@ -0,0 +1,7 @@
+export * from "./conditions";
+export * from "./coverage";
+export * from "./fallback-html";
+export * from "./paths";
+export * from "./resolve";
+export * from "./tokens";
+export * from "./walk";

package/src/engine/paths.ts

@@ -0,0 +1,33 @@
+const PATH_SEPARATOR = ".";
+const ARRAY_SUFFIX = "[]";
+
+export function normalizePath(path: string): string {
+  const trimmed = path.trim();
+  return trimmed.endsWith(ARRAY_SUFFIX)
+    ? trimmed.slice(0, -ARRAY_SUFFIX.length)
+    : trimmed;
+}
+
+/**
+ * Segments that would leave the data and walk the prototype chain. A path is
+ * authored rather than recipient-supplied, but `{{constructor}}` still resolved
+ * to the Object constructor and stringified its source into the e-mail.
+ */
+const RESERVED_SEGMENTS = ["__proto__", "constructor", "prototype"];
+
+function readSegment(current: unknown, segment: string): unknown {
+  if (current === null || current === undefined) return undefined;
+  if (typeof current !== "object") return undefined;
+  if (RESERVED_SEGMENTS.includes(segment)) return undefined;
+  return (current as Record<string, unknown>)[segment];
+}
+
+export function getPath(data: unknown, path: string): unknown {
+  return normalizePath(path)
+    .split(PATH_SEPARATOR)
+    .reduce<unknown>(readSegment, data);
+}
+
+export function isPresent(value: unknown): boolean {
+  return value !== undefined && value !== null;
+}

package/src/engine/resolve.ts

@@ -0,0 +1,178 @@
+import { SYSTEM_VARIABLE_PATHS } from "../constants";
+import type {
+  Block,
+  IfBlock,
+  ListBlock,
+  LocaleContent,
+  ResolvedBlock,
+  ResolvedEmail,
+  ResolvedListRow,
+} from "../types";
+import { evaluateCondition } from "./conditions";
+import { getPath, isPresent } from "./paths";
+import { interpolate } from "./tokens";
+
+type Data = Record<string, unknown>;
+
+interface ResolveState {
+  data: Data;
+  missing: Set<string>;
+  hidden: string[];
+}
+
+type BlockResolver = (block: Block, state: ResolveState) => ResolvedBlock[];
+
+function text(state: ResolveState, value: string): string {
+  const result = interpolate(value, state.data);
+  for (const path of result.missing) state.missing.add(path);
+  return result.text;
+}
+
+function systemUrl(state: ResolveState, path: string): string {
+  const value = getPath(state.data, path);
+  return isPresent(value) ? String(value) : "";
+}
+
+function cell(item: unknown, path: string): string {
+  const value = getPath(item, path);
+  return isPresent(value) ? String(value) : "";
+}
+
+function listRows(block: ListBlock, state: ResolveState): ResolvedListRow[] {
+  const source = getPath(state.data, block.source);
+  if (!Array.isArray(source)) {
+    state.missing.add(block.source);
+    return [];
+  }
+  return source.map((item) => ({
+    label: cell(item, block.labelPath),
+    value: cell(item, block.valuePath),
+  }));
+}
+
+function branch(block: IfBlock, state: ResolveState): ResolvedBlock[] {
+  const isTrue = evaluateCondition(block.condition, state.data);
+  const chosen = isTrue ? block.children : (block.elseChildren ?? []);
+  const skipped = isTrue ? (block.elseChildren ?? []) : block.children;
+  for (const child of skipped) state.hidden.push(child.id);
+  return resolveBlocks(chosen, state);
+}
+
+const RESOLVERS: Record<Block["type"], BlockResolver> = {
+  hero: (block, state) =>
+    block.type === "hero"
+      ? [
+          {
+            id: block.id,
+            type: "hero",
+            imageUrl: text(state, block.imageUrl),
+            alt: text(state, block.alt),
+          },
+        ]
+      : [],
+  heading: (block, state) =>
+    block.type === "heading"
+      ? [
+          {
+            id: block.id,
+            type: "heading",
+            text: text(state, block.text),
+            align: block.align,
+            size: block.size,
+          },
+        ]
+      : [],
+  paragraph: (block, state) =>
+    block.type === "paragraph"
+      ? [
+          {
+            id: block.id,
+            type: "paragraph",
+            text: text(state, block.text),
+            align: block.align,
+          },
+        ]
+      : [],
+  code: (block, state) =>
+    block.type === "code"
+      ? [{ id: block.id, type: "code", text: text(state, block.text) }]
+      : [],
+  list: (block, state) =>
+    block.type === "list"
+      ? [{ id: block.id, type: "list", rows: listRows(block, state) }]
+      : [],
+  total: (block, state) =>
+    block.type === "total"
+      ? [
+          {
+            id: block.id,
+            type: "total",
+            label: text(state, block.label),
+            value: text(state, block.value),
+          },
+        ]
+      : [],
+  button: (block, state) =>
+    block.type === "button"
+      ? [
+          {
+            id: block.id,
+            type: "button",
+            text: text(state, block.text),
+            href: text(state, block.href),
+            align: block.align,
+          },
+        ]
+      : [],
+  if: (block, state) => (block.type === "if" ? branch(block, state) : []),
+  divider: (block) => [{ id: block.id, type: "divider" }],
+  footer: (block, state) =>
+    block.type === "footer"
+      ? [
+          {
+            id: block.id,
+            type: "footer",
+            text: text(state, block.text),
+            unsubscribeLabel: block.unsubscribeLabel,
+            preferencesLabel: block.preferencesLabel,
+            unsubscribeUrl: systemUrl(state, "unsubscribeUrl"),
+            preferencesUrl: systemUrl(state, "preferencesUrl"),
+          },
+        ]
+      : [],
+};
+
+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 [];
+    }
+    return RESOLVERS[block.type](block, state);
+  });
+}
+
+const isUserPath = (path: string): boolean =>
+  !SYSTEM_VARIABLE_PATHS.includes(path);
+
+export function resolveEmail(
+  content: LocaleContent,
+  data: Data,
+): ResolvedEmail {
+  const state: ResolveState = { data, missing: new Set(), hidden: [] };
+  const subject = text(state, content.subject);
+  const preheader = text(state, content.preheader);
+  const blocks = resolveBlocks(content.blocks, state);
+  return {
+    subject,
+    preheader,
+    blocks,
+    missing: [...state.missing].filter(isUserPath).sort(),
+    hiddenBlockIds: state.hidden,
+  };
+}

package/src/engine/tokens.ts

@@ -0,0 +1,35 @@
+import { getPath, isPresent } from "./paths";
+
+export const TOKEN_PATTERN = /\{\{\s*([A-Za-z0-9_.[\]]+)\s*\}\}/g;
+
+export interface InterpolationResult {
+  text: string;
+  missing: string[];
+}
+
+export function extractTokens(text: string): string[] {
+  const found = new Set<string>();
+  for (const match of text.matchAll(TOKEN_PATTERN))
+    found.add(match[1] as string);
+  return [...found];
+}
+
+function formatValue(value: unknown): string {
+  return value instanceof Date ? value.toISOString() : String(value);
+}
+
+export function interpolate(
+  text: string,
+  data: Record<string, unknown>,
+): 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 formatValue(value);
+  });
+  return { text: output, missing: [...missing] };
+}

package/src/engine/walk.ts

@@ -0,0 +1,18 @@
+import type { Block, IfBlock } from "../types";
+
+export type BlockVisitor = (block: Block, depth: number) => void;
+
+const isIfBlock = (block: Block): block is IfBlock => block.type === "if";
+
+export function walkBlocks(
+  blocks: Block[],
+  visit: BlockVisitor,
+  depth = 0,
+): void {
+  for (const block of blocks) {
+    visit(block, depth);
+    if (!isIfBlock(block)) continue;
+    walkBlocks(block.children, visit, depth + 1);
+    walkBlocks(block.elseChildren ?? [], visit, depth + 1);
+  }
+}

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export * from "./tenant-export";

package/src/hooks/tenant-export.ts

@@ -0,0 +1,127 @@
+import { Readable } from "node:stream";
+import type { Table } from "@antelopejs/interface-database";
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import {
+  Hook,
+  type HookHandler,
+  RegisterTenantDataExportContributor,
+  type TenantExportArchive,
+  UnregisterHook,
+} from "@antelopejs/interface-dms/hooks";
+import { MODULE_ID } from "../constants";
+import { SettingsModel, TemplateModel } from "../db";
+import type { MailingSettingsValues } from "../types";
+
+export type ExportedSettings = Omit<MailingSettingsValues, "webhookSecret">;
+
+export type ExportPageLoader<T> = (
+  offset: number,
+  size: number,
+) => Promise<T[]>;
+
+interface RowCodec<T> {
+  fromDatabase(row: unknown): T | undefined;
+}
+
+export interface ExportedCollection {
+  entry: string;
+  load: ExportPageLoader<object>;
+}
+
+/** How many rows one archive entry reads at a time while it streams. */
+export const TENANT_EXPORT_PAGE_SIZE = 200;
+
+const TEMPLATES_ENTRY = "templates.json";
+const SETTINGS_ENTRY = "settings.json";
+
+const ARRAY_OPEN = "[";
+const ARRAY_CLOSE = "]";
+const ROW_SEPARATOR = ",";
+const NO_SEPARATOR = "";
+const FIRST_OFFSET = 0;
+
+export async function* jsonArrayChunks<T>(
+  load: ExportPageLoader<T>,
+  signal: AbortSignal,
+  pageSize: number = TENANT_EXPORT_PAGE_SIZE,
+): AsyncGenerator<string> {
+  yield ARRAY_OPEN;
+  let offset = FIRST_OFFSET;
+  let separator = NO_SEPARATOR;
+  for (;;) {
+    signal.throwIfAborted();
+    const page = await load(offset, pageSize);
+    for (const row of page) {
+      yield `${separator}${JSON.stringify(row)}`;
+      separator = ROW_SEPARATOR;
+    }
+    if (page.length < pageSize) break;
+    offset += page.length;
+  }
+  yield ARRAY_CLOSE;
+}
+
+async function exportedSettings(
+  tenantId: string,
+): Promise<ExportedSettings | null> {
+  const row = await GetModel(SettingsModel, tenantId).getSingleton();
+  if (!row) return null;
+  return {
+    fallbackLocale: row.fallbackLocale,
+    logRetentionDays: row.logRetentionDays,
+    blockOnMissingVariables: row.blockOnMissingVariables,
+    senderName: row.senderName,
+    senderEmail: row.senderEmail,
+    replyTo: row.replyTo,
+    categories: JSON.parse(
+      row.json_categories,
+    ) as ExportedSettings["categories"],
+  };
+}
+
+async function loadPage<T extends object>(
+  table: Table<T>,
+  codec: RowCodec<T>,
+  offset: number,
+  size: number,
+): Promise<T[]> {
+  const rows = await table.slice(offset, size).run();
+  return rows
+    .map((row) => codec.fromDatabase(row))
+    .filter((row): row is T => row !== undefined);
+}
+
+export function exportedCollections(tenantId: string): ExportedCollection[] {
+  const templates = GetModel(TemplateModel, tenantId);
+  return [
+    {
+      entry: TEMPLATES_ENTRY,
+      load: (offset, size) =>
+        loadPage(templates.table, TemplateModel, offset, size),
+    },
+  ];
+}
+
+export const contributeTenantExport: HookHandler<
+  Hook.TENANT_DATA_EXPORT
+> = async (tenantId, archive: TenantExportArchive, signal: AbortSignal) => {
+  for (const collection of exportedCollections(tenantId)) {
+    signal.throwIfAborted();
+    await archive.addStream(
+      collection.entry,
+      Readable.from(jsonArrayChunks(collection.load, signal), {
+        objectMode: false,
+      }),
+    );
+  }
+  signal.throwIfAborted();
+  await archive.addJson(SETTINGS_ENTRY, await exportedSettings(tenantId));
+};
+
+export function registerTenantExport(): void {
+  RegisterTenantDataExportContributor(MODULE_ID, contributeTenantExport);
+}
+
+export function unregisterTenantExport(): void {
+  UnregisterHook(Hook.TENANT_DATA_EXPORT, contributeTenantExport);
+}

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

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

package/src/index.ts

@@ -0,0 +1,62 @@
+import "./permissions";
+import "./db";
+import path from "node:path";
+import { ImplementInterface } from "@antelopejs/interface-core";
+import { Logging } from "@antelopejs/interface-core/logging";
+import { AddFrontendModule } from "@antelopejs/interface-dms/page";
+import type { ScheduledTask } from "node-cron";
+import {
+  registerAutomationNodes,
+  unregisterAutomationNodes,
+} from "./automation";
+import { type DmsMailingConfig, setConfig } from "./config";
+import { FRONTEND_MODULE_NAME } from "./constants";
+import { RETENTION_CRON_NAME, scheduleRetention, stopRetention } from "./crons";
+import { registerTenantExport, unregisterTenantExport } from "./hooks";
+import { registerRealtimeTopics } from "./realtime";
+
+export * from "./data";
+export * from "./data-types";
+export * from "./pages";
+export * from "./quick-actions";
+export * from "./routes";
+export type { DmsMailingConfig } from "./config";
+
+let retentionTask: ScheduledTask | undefined;
+
+export async function construct(config: DmsMailingConfig = {}): Promise<void> {
+  setConfig(config);
+  ImplementInterface(
+    await import("@antelopejs/interface-dms-mailing"),
+    await import("./implementations/dms-mailing"),
+  );
+  registerAutomationNodes();
+  registerTenantExport();
+  registerRealtimeTopics();
+  await AddFrontendModule({
+    name: FRONTEND_MODULE_NAME,
+    sourcePath: path.join(__dirname, "../frontend-vue"),
+    renderer: { name: "vue", version: "3" },
+    options: { dmsMailing: {} },
+    priority: 0,
+  });
+}
+
+export function destroy(): void {
+  unregisterAutomationNodes();
+  unregisterTenantExport();
+}
+
+export function start(): void {
+  retentionTask = scheduleRetention();
+}
+
+export async function stop(): Promise<void> {
+  const task = retentionTask;
+  retentionTask = undefined;
+  try {
+    await stopRetention(task);
+  } catch (error) {
+    Logging.Error(`Cron '${RETENTION_CRON_NAME}' failed to stop:`, error);
+  }
+}

package/src/pages/editor.ts

@@ -0,0 +1,23 @@
+import { PageController, RegisterPage } from "@antelopejs/interface-dms/page";
+import { CustomComponent } from "@antelopejs/interface-dms/base/custom";
+import { DefaultLayout } from "@antelopejs/interface-dms/base/layouts";
+import { MAILING_TEMPLATES_MANAGE_PERMISSION, MODULE_ID } from "../constants";
+
+const EDITOR_PAGE_ORDER = 2;
+
+@RegisterPage()
+export class MailingEditorController extends PageController(
+  "editor",
+  {
+    displayName: "$dms_mailing.editor.title",
+    description: "$dms_mailing.editor.description",
+    icon: "i-ph-pencil-simple",
+    module: MODULE_ID,
+    order: EDITOR_PAGE_ORDER,
+    hidden: true,
+    permission: { id: MAILING_TEMPLATES_MANAGE_PERMISSION },
+  },
+  DefaultLayout({ fullWidth: true }),
+) {
+  static editor = CustomComponent("DmsMailingEditor");
+}

package/src/pages/index.ts

@@ -0,0 +1,11 @@
+// `./module` is imported first so RegisterModule fires before any
+// @RegisterPage decorator runs: pages look their module up synchronously
+// when the decorator is invoked at import time.
+import "./module";
+
+export * from "./module";
+export * from "./overview";
+export * from "./editor";
+export * from "./sends";
+export * from "./settings";
+export * from "./templates";

package/src/pages/module.ts

@@ -0,0 +1,9 @@
+import { RegisterModule } from "@antelopejs/interface-dms/page";
+
+export const mailingModule = RegisterModule({
+  id: "mailing",
+  title: "$dms_mailing.title",
+  description: "$dms_mailing.description",
+  icon: "i-ph-envelope-simple",
+  landingPage: "overview",
+});