@antelopejs/dms-mailing 0.2.2

package/src/test/unit/engine/coverage.test.ts

@@ -0,0 +1,118 @@
+import { expect } from "chai";
+import {
+  collectContentVariablePaths,
+  collectVariablePaths,
+  missingRequiredVariables,
+} from "../../../engine";
+import type {
+  LocaleContent,
+  TemplateContent,
+  VariableDefinition,
+} from "../../../types";
+
+const CONTENT: LocaleContent = {
+  subject: "Order {{order.ref}}",
+  preheader: "",
+  blocks: [
+    {
+      id: "h",
+      type: "heading",
+      text: "Hi {{customer.firstName}}",
+      align: "left",
+      size: 23,
+      visibleIf: null,
+    },
+    {
+      id: "l",
+      type: "list",
+      source: "order.lines",
+      labelPath: "label",
+      valuePath: "total",
+      visibleIf: null,
+    },
+    {
+      id: "i",
+      type: "if",
+      condition: { path: "order.hasGift", operator: "truthy", value: "" },
+      visibleIf: null,
+      children: [
+        {
+          id: "p",
+          type: "paragraph",
+          text: "{{gift.note}}",
+          align: "left",
+          visibleIf: null,
+        },
+      ],
+      elseChildren: null,
+    },
+    {
+      id: "b",
+      type: "button",
+      text: "Track",
+      href: "{{order.trackUrl}}",
+      align: "left",
+      visibleIf: { path: "order.shipped", operator: "truthy", value: "" },
+    },
+    {
+      id: "f",
+      type: "footer",
+      text: "",
+      unsubscribeLabel: "u",
+      preferencesLabel: "p",
+      visibleIf: null,
+    },
+  ],
+};
+
+describe("[unit] engine/coverage", () => {
+  it("collects every referenced path once, sorted, ignoring list item paths and system paths", () => {
+    expect(collectVariablePaths(CONTENT)).to.deep.equal([
+      "customer.firstName",
+      "gift.note",
+      "order.hasGift",
+      "order.lines",
+      "order.ref",
+      "order.shipped",
+      "order.trackUrl",
+    ]);
+  });
+  it("lists declared required variables missing from a data set", () => {
+    const declared: VariableDefinition[] = [
+      { path: "order.ref", type: "string", required: true },
+      { path: "order.lines[]", type: "array", required: true },
+      { path: "customer.firstName", type: "string", required: false },
+    ];
+    expect(
+      missingRequiredVariables(declared, { order: { ref: "X" } }),
+    ).to.deep.equal(["order.lines"]);
+  });
+});
+
+describe("[unit] engine/coverage across locales", () => {
+  it("unions the paths of every locale, sorted and deduplicated", () => {
+    const french: LocaleContent = {
+      subject: "Commande {{order.ref}}",
+      preheader: "",
+      blocks: [
+        {
+          id: "p",
+          type: "paragraph",
+          text: "Bonjour {{customer.lastName}}",
+          align: "left",
+          visibleIf: null,
+        },
+      ],
+    };
+    const content: TemplateContent = { locales: { en: CONTENT, fr: french } };
+    const paths = collectContentVariablePaths(content);
+    expect(paths).to.include("customer.lastName");
+    expect(paths).to.include("order.ref");
+    expect(paths.filter((path) => path === "order.ref")).to.have.lengthOf(1);
+    expect(paths).to.deep.equal([...paths].sort());
+  });
+
+  it("answers an empty list for content with no locale", () => {
+    expect(collectContentVariablePaths({ locales: {} })).to.deep.equal([]);
+  });
+});

package/src/test/unit/engine/fallback-html.test.ts

@@ -0,0 +1,86 @@
+import { expect } from "chai";
+import { renderFallbackHtml } from "../../../engine";
+import type { ResolvedEmail } from "../../../types";
+
+const EMAIL: ResolvedEmail = {
+  subject: "Hello",
+  preheader: "Pre",
+  missing: [],
+  hiddenBlockIds: [],
+  blocks: [
+    { id: "h", type: "heading", text: "Hi <Sofie>", align: "left", size: 23 },
+    {
+      id: "b",
+      type: "button",
+      text: "Go",
+      href: "https://x.test/?a=1&b=2",
+      align: "center",
+    },
+    { id: "l", type: "list", rows: [{ label: "Chair", value: "64" }] },
+    {
+      id: "f",
+      type: "footer",
+      text: "Antelope",
+      unsubscribeLabel: "Unsub",
+      preferencesLabel: "Prefs",
+      unsubscribeUrl: "https://u",
+      preferencesUrl: "",
+    },
+  ],
+};
+
+describe("[unit] engine/fallback-html", () => {
+  const html = renderFallbackHtml(EMAIL, "en");
+  it("produces a full document with the subject as title and escaped content", () => {
+    expect(html).to.match(/^<!DOCTYPE html>/);
+    expect(html).to.include("<title>Hello</title>");
+    expect(html).to.include("Hi &lt;Sofie&gt;");
+    expect(html).to.include('href="https://x.test/?a=1&amp;b=2"');
+  });
+  it("renders list rows and only the footer links that have a url", () => {
+    expect(html).to.include("Chair");
+    expect(html).to.include('href="https://u"');
+    expect(html).to.not.include("Prefs");
+  });
+});
+
+const withHref = (href: string): ResolvedEmail => ({
+  subject: "S",
+  preheader: "P",
+  missing: [],
+  hiddenBlockIds: [],
+  blocks: [{ id: "b", type: "button", text: "Go", href, align: "left" }],
+});
+
+describe("[unit] engine/fallback-html link schemes", () => {
+  // A link target can come straight from an interpolated variable, so it is
+  // recipient-supplied data. Escaping the entities is not enough: the scheme
+  // itself has to be one a mail client may follow.
+  it("keeps the schemes an e-mail legitimately uses", () => {
+    for (const href of [
+      "https://x.test/a?b=1",
+      "http://x.test",
+      "mailto:a@b.test",
+      "/relative/path",
+      "{{order.trackUrl}}",
+    ]) {
+      expect(renderFallbackHtml(withHref(href), "en")).to.contain("href=");
+      expect(renderFallbackHtml(withHref(href), "en")).to.not.contain(
+        'href="#"',
+      );
+    }
+  });
+
+  it("neutralises a scheme that carries code", () => {
+    for (const href of [
+      "javascript:alert(1)",
+      "JavaScript:alert(1)",
+      " javascript:alert(1)",
+      "data:text/html,<script>alert(1)</script>",
+      "vbscript:msgbox",
+    ]) {
+      expect(renderFallbackHtml(withHref(href), "en")).to.contain('href="#"');
+      expect(renderFallbackHtml(withHref(href), "en")).to.not.contain("alert");
+    }
+  });
+});

package/src/test/unit/engine/paths.test.ts

@@ -0,0 +1,39 @@
+import { expect } from "chai";
+import { getPath, normalizePath } from "../../../engine";
+
+const DATA = {
+  order: { ref: "CMD-1", lines: [{ label: "A" }] },
+  customer: { firstName: "Sofie" },
+};
+
+describe("[unit] engine/paths", () => {
+  it("reads nested values", () => {
+    expect(getPath(DATA, "order.ref")).to.equal("CMD-1");
+    expect(getPath(DATA, "order.lines")).to.deep.equal([{ label: "A" }]);
+  });
+  it("returns undefined for missing segments without throwing", () => {
+    expect(getPath(DATA, "order.missing.deep")).to.equal(undefined);
+    expect(getPath(null, "a")).to.equal(undefined);
+  });
+  it("strips the array suffix used in declarations", () => {
+    expect(normalizePath("order.lines[]")).to.equal("order.lines");
+  });
+});
+
+describe("[unit] engine/paths reserved keys", () => {
+  // A token path is authored, not recipient-supplied, but `{{constructor}}`
+  // still resolved to the Object constructor and String()'d its source into the
+  // e-mail. Nothing legitimate walks through these.
+  it("refuses to walk the prototype chain", () => {
+    expect(getPath({ a: 1 }, "constructor")).to.equal(undefined);
+    expect(getPath({ a: 1 }, "__proto__")).to.equal(undefined);
+    expect(getPath({ a: 1 }, "prototype")).to.equal(undefined);
+    expect(
+      getPath({ a: { __proto__: { leaked: 1 } } }, "a.__proto__"),
+    ).to.equal(undefined);
+  });
+
+  it("still reads an ordinary path", () => {
+    expect(getPath({ a: { b: 2 } }, "a.b")).to.equal(2);
+  });
+});

package/src/test/unit/engine/resolve.test.ts

@@ -0,0 +1,176 @@
+import { expect } from "chai";
+import { resolveEmail } from "../../../engine";
+import type { LocaleContent } from "../../../types";
+
+const CONTENT: LocaleContent = {
+  subject: "Order {{order.ref}}",
+  preheader: "Thanks {{customer.firstName}}",
+  blocks: [
+    {
+      id: "h",
+      type: "heading",
+      text: "Thanks {{customer.firstName}}",
+      align: "left",
+      size: 23,
+      visibleIf: null,
+    },
+    {
+      id: "l",
+      type: "list",
+      source: "order.lines",
+      labelPath: "label",
+      valuePath: "total",
+      visibleIf: null,
+    },
+    {
+      id: "t",
+      type: "total",
+      label: "Total",
+      value: "{{order.total}}",
+      visibleIf: null,
+    },
+    {
+      id: "i",
+      type: "if",
+      condition: { path: "order.hasGift", operator: "truthy", value: "" },
+      visibleIf: null,
+      children: [
+        {
+          id: "gift",
+          type: "paragraph",
+          text: "Gift inside",
+          align: "left",
+          visibleIf: null,
+        },
+      ],
+      elseChildren: [
+        {
+          id: "nogift",
+          type: "paragraph",
+          text: "No gift",
+          align: "left",
+          visibleIf: null,
+        },
+      ],
+    },
+    {
+      id: "b",
+      type: "button",
+      text: "Track",
+      href: "{{order.trackUrl}}",
+      align: "center",
+      visibleIf: { path: "order.shipped", operator: "truthy", value: "" },
+    },
+    {
+      id: "f",
+      type: "footer",
+      text: "Antelope",
+      unsubscribeLabel: "Unsubscribe",
+      preferencesLabel: "Preferences",
+      visibleIf: null,
+    },
+  ],
+};
+
+const DATA = {
+  customer: { firstName: "Sofie" },
+  order: {
+    ref: "CMD-1",
+    total: "70,50 €",
+    hasGift: true,
+    lines: [
+      { label: "Chair", total: "64" },
+      { label: "Shipping", total: "6,50" },
+    ],
+  },
+  unsubscribeUrl: "https://u",
+};
+
+describe("[unit] engine/resolve", () => {
+  const email = resolveEmail(CONTENT, DATA);
+  it("interpolates subject and preheader", () => {
+    expect(email.subject).to.equal("Order CMD-1");
+    expect(email.preheader).to.equal("Thanks Sofie");
+  });
+  it("expands lists, picks the if branch and flattens it", () => {
+    expect(email.blocks.map((block) => block.id)).to.deep.equal([
+      "h",
+      "l",
+      "t",
+      "gift",
+      "f",
+    ]);
+    const list = email.blocks[1]!;
+    expect(list.type === "list" && list.rows).to.deep.equal([
+      { label: "Chair", value: "64" },
+      { label: "Shipping", value: "6,50" },
+    ]);
+  });
+  it("hides blocks whose visibleIf is false and reports them", () => {
+    expect(email.hiddenBlockIds).to.deep.equal(["nogift", "b"]);
+  });
+  // The only unresolved user path in this fixture is the tracking URL of the
+  // button, which `order.shipped` hides — so it is not reported. The two
+  // directions of that rule are covered below.
+  it("resolves the footer's system urls without reporting them missing", () => {
+    expect(email.missing).to.deep.equal([]);
+    const footer = email.blocks[4]!;
+    expect(footer.type === "footer" && footer.unsubscribeUrl).to.equal(
+      "https://u",
+    );
+    expect(footer.type === "footer" && footer.preferencesUrl).to.equal("");
+  });
+});
+
+describe("[unit] engine/resolve hidden blocks", () => {
+  const hiddenParagraph = {
+    subject: "S",
+    preheader: "",
+    blocks: [
+      {
+        id: "p1",
+        type: "paragraph" as const,
+        align: "left" as const,
+        text: "A gift: {{order.giftMessage}}",
+        visibleIf: {
+          path: "order.hasGift",
+          operator: "truthy" as const,
+          value: "",
+        },
+      },
+    ],
+  };
+
+  // `blockOnMissingVariables` refuses a send whose resolved e-mail reports a
+  // missing variable. A block the condition hides is never rendered, so what it
+  // references must not count — otherwise conditional content makes that
+  // setting unusable.
+  it("does not report a variable only a hidden block references", () => {
+    const email = resolveEmail(hiddenParagraph, { order: { hasGift: false } });
+    expect(email.blocks).to.have.lengthOf(0);
+    expect(email.hiddenBlockIds).to.deep.equal(["p1"]);
+    expect(email.missing).to.deep.equal([]);
+  });
+
+  it("still reports it when the block is shown", () => {
+    const email = resolveEmail(hiddenParagraph, { order: { hasGift: true } });
+    expect(email.blocks).to.have.lengthOf(1);
+    expect(email.missing).to.deep.equal(["order.giftMessage"]);
+  });
+});
+
+describe("[unit] engine/resolve system variables", () => {
+  // `unsubscribeUrl` and `preferencesUrl` are filled by the runtime, so a
+  // template referencing one must not ask the author to declare it.
+  it("keeps system paths out of the missing list, unlike user paths", () => {
+    const email = resolveEmail(
+      {
+        subject: "{{unsubscribeUrl}} {{preferencesUrl}} {{order.ref}}",
+        preheader: "",
+        blocks: [],
+      },
+      {},
+    );
+    expect(email.missing).to.deep.equal(["order.ref"]);
+  });
+});

package/src/test/unit/engine/tokens.test.ts

@@ -0,0 +1,26 @@
+import { expect } from "chai";
+import { extractTokens, interpolate } from "../../../engine";
+
+describe("[unit] engine/tokens", () => {
+  it("extracts unique trimmed token paths in order", () => {
+    expect(
+      extractTokens("Hi {{ customer.firstName }}, {{order.ref}} {{order.ref}}"),
+    ).to.deep.equal(["customer.firstName", "order.ref"]);
+  });
+  it("interpolates known paths and reports missing ones", () => {
+    const result = interpolate("Hi {{customer.firstName}}, ref {{order.ref}}", {
+      customer: { firstName: "Sofie" },
+    });
+    expect(result.text).to.equal("Hi Sofie, ref {{order.ref}}");
+    expect(result.missing).to.deep.equal(["order.ref"]);
+  });
+  it("renders numbers and booleans as text and treats null as missing", () => {
+    const result = interpolate("{{count}}-{{flag}}-{{nothing}}", {
+      count: 3,
+      flag: false,
+      nothing: null,
+    });
+    expect(result.text).to.equal("3-false-{{nothing}}");
+    expect(result.missing).to.deep.equal(["nothing"]);
+  });
+});

package/src/test/unit/events.test.ts

@@ -0,0 +1,19 @@
+import { expect } from "chai";
+import { applyEvent } from "../../services/events";
+
+describe("[unit] services/events", () => {
+  it("promotes the status forward only and counts opens/clicks", () => {
+    expect(
+      applyEvent({ status: "sent", opens: 0, clicks: 0 }, "opened"),
+    ).to.deep.equal({ status: "opened", opens: 1, clicks: 0 });
+    expect(
+      applyEvent({ status: "clicked", opens: 1, clicks: 1 }, "opened"),
+    ).to.deep.equal({ status: "clicked", opens: 2, clicks: 1 });
+    expect(
+      applyEvent({ status: "delivered", opens: 0, clicks: 0 }, "bounced"),
+    ).to.deep.equal({ status: "bounced", opens: 0, clicks: 0 });
+    expect(
+      applyEvent({ status: "bounced", opens: 0, clicks: 0 }, "delivered"),
+    ).to.deep.equal({ status: "bounced", opens: 0, clicks: 0 });
+  });
+});

package/src/test/unit/metrics.test.ts

@@ -0,0 +1,170 @@
+import { expect } from "chai";
+import type { MailingSend } from "../../db";
+import {
+  aggregate,
+  dailySeries,
+  deltaPercent,
+  domainOf,
+  forAudience,
+  readAudience,
+} from "../../services/metrics";
+
+const LATENCY_MS = 100;
+const YEAR = 2026;
+const MONTH = 8;
+
+const send = (
+  status: MailingSend["status"],
+  email: string,
+  day: number,
+  opens = 0,
+  clicks = 0,
+): MailingSend =>
+  ({
+    status,
+    recipientEmail: email,
+    createdAt: new Date(Date.UTC(YEAR, MONTH, day)),
+    opens,
+    clicks,
+    latencyMs: LATENCY_MS,
+  }) as MailingSend;
+
+const SENDS = [
+  send("delivered", "a@gmail.com", 1, 1),
+  send("opened", "b@gmail.com", 1, 1, 0),
+  send("clicked", "c@outlook.com", 2, 2, 1),
+  send("bounced", "d@bad.tld", 2),
+  send("failed", "e@gmail.com", 3),
+];
+
+const TOLERANCE = 0.01;
+const EXPECTED_DELIVERABILITY = 60;
+const EXPECTED_OPEN_RATE = 66.67;
+const EXPECTED_DELTA = 20;
+
+describe("[unit] services/metrics", () => {
+  it("aggregates the funnel counters", () => {
+    const totals = aggregate(SENDS);
+    expect(totals).to.deep.include({
+      sends: 5,
+      delivered: 3,
+      opened: 2,
+      clicked: 1,
+      bounced: 1,
+      failed: 1,
+      unsubscribed: 0,
+      queued: 0,
+    });
+    expect(totals.deliverability).to.be.closeTo(
+      EXPECTED_DELIVERABILITY,
+      TOLERANCE,
+    );
+    expect(totals.openRate).to.be.closeTo(EXPECTED_OPEN_RATE, TOLERANCE);
+  });
+
+  it("computes deltas and daily series", () => {
+    expect(deltaPercent(120, LATENCY_MS)).to.equal(EXPECTED_DELTA);
+    expect(deltaPercent(5, 0)).to.equal(0);
+    expect(
+      dailySeries(
+        SENDS,
+        new Date(Date.UTC(YEAR, MONTH, 1)),
+        new Date(Date.UTC(YEAR, MONTH, 4)),
+      ).map((point) => point.y),
+    ).to.deep.equal([2, 2, 1]);
+    expect(domainOf("x@Gmail.com")).to.equal("gmail.com");
+  });
+});
+
+const testSend = (): MailingSend =>
+  ({
+    status: "sent",
+    recipientEmail: "t@gmail.com",
+    createdAt: new Date(Date.UTC(YEAR, MONTH, 1)),
+    opens: 0,
+    clicks: 0,
+    latencyMs: LATENCY_MS,
+    isTest: true,
+  }) as MailingSend;
+
+const MIXED = [...SENDS, testSend()];
+
+describe("[unit] services/metrics audience", () => {
+  it("reads the audience from the query, defaulting to the business view", () => {
+    expect(readAudience("operational")).to.equal("operational");
+    expect(readAudience("business")).to.equal("business");
+    expect(readAudience(null)).to.equal("business");
+    expect(readAudience("nonsense")).to.equal("business");
+  });
+
+  it("hides test sends from the business view", () => {
+    expect(forAudience(MIXED, "business")).to.have.lengthOf(SENDS.length);
+    expect(aggregate(forAudience(MIXED, "business")).sends).to.equal(
+      SENDS.length,
+    );
+  });
+
+  it("counts every send in the operational view", () => {
+    expect(forAudience(MIXED, "operational")).to.have.lengthOf(MIXED.length);
+    expect(aggregate(forAudience(MIXED, "operational")).sends).to.equal(
+      MIXED.length,
+    );
+  });
+});
+
+// The DMS period selector sends local day boundaries: for a UTC+2 tenant,
+// "last 7 days" arrives as 2026-09-03T22:00Z → 2026-09-10T21:59:59.999Z.
+const WINDOW_FROM = new Date("2026-09-03T22:00:00.000Z");
+const WINDOW_TO = new Date("2026-09-10T21:59:59.999Z");
+const DAYS_IN_WINDOW = 7;
+
+const sentAt = (iso: string): MailingSend =>
+  ({
+    status: "sent",
+    recipientEmail: "a@gmail.com",
+    createdAt: new Date(iso),
+    opens: 0,
+    clicks: 0,
+    latencyMs: LATENCY_MS,
+  }) as MailingSend;
+
+describe("[unit] services/metrics daily series over a DMS period", () => {
+  it("covers every day of the window, last one included", () => {
+    const points = dailySeries([], WINDOW_FROM, WINDOW_TO);
+    expect(points).to.have.lengthOf(DAYS_IN_WINDOW);
+    expect(points[0]?.x).to.equal("2026-09-04");
+    expect(points[points.length - 1]?.x).to.equal("2026-09-10");
+  });
+
+  // The KPI counts this send through `aggregate`; the chart must agree.
+  it("counts a send made on the last day of the window", () => {
+    const points = dailySeries(
+      [sentAt("2026-09-10T12:30:00.000Z")],
+      WINDOW_FROM,
+      WINDOW_TO,
+    );
+    expect(points.find((point) => point.x === "2026-09-10")?.y).to.equal(1);
+    expect(points.reduce((total, point) => total + point.y, 0)).to.equal(1);
+  });
+
+  // Boundaries are local, keys must follow them: a send just after local
+  // midnight belongs to the local day that just started, not the UTC one that
+  // is still running.
+  it("buckets a send by the local day the window is cut on", () => {
+    const points = dailySeries(
+      [sentAt("2026-09-06T22:30:00.000Z")],
+      WINDOW_FROM,
+      WINDOW_TO,
+    );
+    expect(points.find((point) => point.x === "2026-09-07")?.y).to.equal(1);
+  });
+
+  it("ignores a send outside the window rather than folding it into an edge", () => {
+    const points = dailySeries(
+      [sentAt("2026-09-03T10:00:00.000Z"), sentAt("2026-09-11T10:00:00.000Z")],
+      WINDOW_FROM,
+      WINDOW_TO,
+    );
+    expect(points.reduce((total, point) => total + point.y, 0)).to.equal(0);
+  });
+});