@antelopejs/dms-mailing 0.2.2

package/src/test/integration/templates.test.ts

@@ -0,0 +1,229 @@
+import { expect } from "chai";
+import { authorizedClient } from "../helpers/http";
+import { ensureOwnerSession } from "../helpers/owner";
+
+const HTTP_OK = 200;
+const HTTP_BAD_REQUEST = 400;
+const HTTP_NOT_FOUND = 404;
+const TABLE = "/api/mailing/tables/templates";
+
+interface TemplateRow {
+  _id: string;
+  slug: string;
+  status: string;
+  locales: string;
+}
+
+interface BlockRow {
+  type: string;
+}
+
+describe("[integration] templates table", () => {
+  it("creates a blank template with only a footer and lists it", async () => {
+    const session = await ensureOwnerSession();
+    const client = authorizedClient(session.accessToken);
+    const created = await client.post(`${TABLE}/new`, {
+      slug: "order-confirmed",
+      name: "Order confirmed",
+      category: "orders",
+    });
+    expect(created.status, JSON.stringify(created.data)).to.equal(HTTP_OK);
+
+    const list = await client.get(`${TABLE}/list`);
+    expect(list.status).to.equal(HTTP_OK);
+    const row = list.data.results.find(
+      (item: TemplateRow) => item.slug === "order-confirmed",
+    ) as TemplateRow;
+    expect(row.status).to.equal("draft");
+    expect(row.locales).to.equal("en");
+
+    const content = await client.get(
+      `/api/mailing/templates/${row._id}/content`,
+    );
+    expect(content.status).to.equal(HTTP_OK);
+    expect(
+      content.data.content.locales.en.blocks.map(
+        (block: BlockRow) => block.type,
+      ),
+    ).to.deep.equal(["footer"]);
+    expect(content.data.content.locales.en.subject).to.equal("");
+    expect(content.data.variables).to.deep.equal([]);
+  });
+
+  it("creates from an existing template by copying its content", async () => {
+    const session = await ensureOwnerSession();
+    const client = authorizedClient(session.accessToken);
+    const source = await client.post(`${TABLE}/new`, {
+      slug: "copy-source",
+      name: "Copy source",
+      category: "orders",
+    });
+    const sourceId = source.data[0] as string;
+    await client.post(`/api/mailing/templates/${sourceId}/content`, {
+      content: {
+        locales: {
+          en: {
+            subject: "Hello {{customer.firstName}}",
+            preheader: "",
+            blocks: [],
+          },
+        },
+      },
+    });
+    await client.post(`/api/mailing/templates/${sourceId}/variables`, {
+      variables: [
+        { path: "customer.firstName", type: "string", required: true },
+      ],
+    });
+
+    const copy = await client.post(`${TABLE}/new`, {
+      slug: "copy-target",
+      name: "Copy target",
+      sourceTemplateId: sourceId,
+    });
+    expect(copy.status, JSON.stringify(copy.data)).to.equal(HTTP_OK);
+    const content = await client.get(
+      `/api/mailing/templates/${copy.data[0] as string}/content`,
+    );
+    expect(content.data.content.locales.en.subject).to.equal(
+      "Hello {{customer.firstName}}",
+    );
+    expect(content.data.variables).to.deep.equal([
+      { path: "customer.firstName", type: "string", required: true },
+    ]);
+  });
+
+  it("keeps the slug when only the name and category are edited", async () => {
+    const session = await ensureOwnerSession();
+    const client = authorizedClient(session.accessToken);
+    const created = await client.post(`${TABLE}/new`, {
+      slug: "keeps-slug",
+      name: "Keeps slug",
+      category: "orders",
+    });
+    const id = created.data[0] as string;
+    // The data-api `edit` route replaces the writable fields: a body missing
+    // one nulls it. The editor must send the whole writable set.
+    const edited = await client.put(`${TABLE}/edit?id=${id}`, {
+      slug: "keeps-slug",
+      name: "Renamed",
+      category: "billing",
+    });
+    expect(edited.status, JSON.stringify(edited.data)).to.equal(HTTP_OK);
+    const row = await client.get(`${TABLE}/get?id=${id}`);
+    expect(row.data.slug).to.equal("keeps-slug");
+    expect(row.data.name).to.equal("Renamed");
+    expect(row.data.category).to.equal("billing");
+  });
+
+  it("refuses an unknown source template", async () => {
+    const session = await ensureOwnerSession();
+    const client = authorizedClient(session.accessToken);
+    const created = await client.post(`${TABLE}/new`, {
+      slug: "copy-missing",
+      name: "Copy missing",
+      sourceTemplateId: "does-not-exist",
+    });
+    expect(created.status).to.equal(HTTP_NOT_FOUND);
+    expect(JSON.stringify(created.data)).to.contain("template_not_found");
+  });
+
+  it("rejects a duplicate slug", async () => {
+    const session = await ensureOwnerSession();
+    const client = authorizedClient(session.accessToken);
+    const dup = await client.post(`${TABLE}/new`, {
+      slug: "order-confirmed",
+      name: "Again",
+      category: "orders",
+    });
+    expect(dup.status).to.be.at.least(HTTP_BAD_REQUEST);
+  });
+});
+
+describe("[integration] template content and status", () => {
+  async function createTemplate(
+    client: ReturnType<typeof authorizedClient>,
+    slug: string,
+  ): Promise<string> {
+    const created = await client.post(`${TABLE}/new`, {
+      slug,
+      name: slug,
+      category: "orders",
+    });
+    expect(created.status, JSON.stringify(created.data)).to.equal(HTTP_OK);
+    return created.data[0] as string;
+  }
+
+  it("replaces the content, publishes and duplicates", async () => {
+    const session = await ensureOwnerSession();
+    const client = authorizedClient(session.accessToken);
+    const id = await createTemplate(client, "welcome");
+    const before = await client.get(`/api/mailing/templates/${id}/content`);
+    const content = before.data.content;
+    content.locales.en.subject = "Welcome {{customer.firstName}}";
+    const saved = await client.post(`/api/mailing/templates/${id}/content`, {
+      content,
+    });
+    expect(saved.status, JSON.stringify(saved.data)).to.equal(HTTP_OK);
+    expect(saved.data.saved).to.equal(true);
+
+    const publish = await client.post(
+      `/api/mailing/templates/${id}/publish`,
+      {},
+    );
+    expect(publish.status).to.equal(HTTP_OK);
+    const after = await client.get(`/api/mailing/templates/${id}/content`);
+    expect(after.data.template.status).to.equal("live");
+    expect(after.data.content.locales.en.subject).to.equal(
+      "Welcome {{customer.firstName}}",
+    );
+
+    const variables = await client.post(
+      `/api/mailing/templates/${id}/variables`,
+      {
+        variables: [
+          { path: "customer.firstName", type: "string", required: false },
+        ],
+      },
+    );
+    expect(variables.status).to.equal(HTTP_OK);
+    const testData = await client.post(
+      `/api/mailing/templates/${id}/test-data`,
+      { data: { customer: { firstName: "Sofie" } } },
+    );
+    expect(testData.status).to.equal(HTTP_OK);
+
+    const duplicate = await client.post(
+      `/api/mailing/templates/${id}/duplicate`,
+      { slug: "welcome-copy", name: "Welcome copy" },
+    );
+    expect(duplicate.status, JSON.stringify(duplicate.data)).to.equal(HTTP_OK);
+    const copy = await client.get(
+      `/api/mailing/templates/${duplicate.data.id}/content`,
+    );
+    expect(copy.data.template.status).to.equal("draft");
+    expect(copy.data.content.locales.en.subject).to.equal(
+      "Welcome {{customer.firstName}}",
+    );
+    expect(copy.data.variables).to.have.length(1);
+  });
+
+  it("previews the current content with test data and reports missing variables", async () => {
+    const session = await ensureOwnerSession();
+    const client = authorizedClient(session.accessToken);
+    const list = await client.get(`${TABLE}/list`);
+    const id = (
+      list.data.results.find(
+        (item: TemplateRow) => item.slug === "welcome",
+      ) as TemplateRow
+    )._id;
+    const preview = await client.post(`/api/mailing/templates/${id}/preview`, {
+      locale: "en",
+      data: {},
+    });
+    expect(preview.status, JSON.stringify(preview.data)).to.equal(HTTP_OK);
+    expect(preview.data.html).to.include("<!DOCTYPE html>");
+    expect(preview.data.missing).to.include("customer.firstName");
+    expect(preview.data.subject).to.equal("Welcome {{customer.firstName}}");
+  });
+});

package/src/test/integration/tenant-export.test.ts

@@ -0,0 +1,125 @@
+import type { Readable } from "node:stream";
+import { DEFAULT_TENANT_ID } from "@antelopejs/interface-dms/constants";
+import type { TenantExportArchive } from "@antelopejs/interface-dms/hooks";
+import { expect } from "chai";
+import {
+  contributeTenantExport,
+  type ExportedCollection,
+  exportedCollections,
+  jsonArrayChunks,
+} from "../../hooks/tenant-export";
+import { authorizedClient } from "../helpers/http";
+import { ensureOwnerSession } from "../helpers/owner";
+
+const HTTP_OK = 200;
+const TABLE = "/api/mailing/tables/templates";
+const TEMPLATES_ENTRY = "templates.json";
+const SETTINGS_ENTRY = "settings.json";
+const EXPORTED_SLUG = "exported-template";
+const SINGLE_ROW_PAGE = 1;
+const LIST_ALL = 100;
+
+interface TemplateRow {
+  slug: string;
+}
+
+class CollectingArchive implements TenantExportArchive {
+  readonly entries = new Map<string, string>();
+
+  addJson(path: string, data: unknown): Promise<void> {
+    this.entries.set(path, JSON.stringify(data));
+    return Promise.resolve();
+  }
+
+  addFile(path: string): Promise<void> {
+    return Promise.reject(new Error(`Unexpected file entry "${path}"`));
+  }
+
+  async addStream(path: string, stream: Readable): Promise<void> {
+    let text = "";
+    for await (const chunk of stream) text += String(chunk);
+    this.entries.set(path, text);
+  }
+}
+
+function parsed<T>(archive: CollectingArchive, entry: string): T {
+  return JSON.parse(archive.entries.get(entry) as string) as T;
+}
+
+describe("[integration] tenant export", () => {
+  it("streams the mailing data into the archive instead of one blob", async () => {
+    const session = await ensureOwnerSession();
+    const client = authorizedClient(session.accessToken);
+    const created = await client.post(`${TABLE}/new`, {
+      slug: EXPORTED_SLUG,
+      name: "Exported template",
+      category: "orders",
+    });
+    expect(created.status, JSON.stringify(created.data)).to.equal(HTTP_OK);
+
+    const archive = new CollectingArchive();
+    const contribution = await contributeTenantExport(
+      DEFAULT_TENANT_ID,
+      archive,
+      new AbortController().signal,
+    );
+
+    expect(contribution).to.equal(undefined);
+    expect([...archive.entries.keys()]).to.have.members([
+      TEMPLATES_ENTRY,
+      SETTINGS_ENTRY,
+    ]);
+    const templates = parsed<TemplateRow[]>(archive, TEMPLATES_ENTRY);
+    expect(templates.map((template) => template.slug)).to.include(
+      EXPORTED_SLUG,
+    );
+    expect(archive.entries.get(SETTINGS_ENTRY)).to.not.contain("webhookSecret");
+  });
+
+  it("stops contributing when the export is aborted", async () => {
+    const archive = new CollectingArchive();
+    const controller = new AbortController();
+    controller.abort();
+
+    let aborted = false;
+    try {
+      await contributeTenantExport(
+        DEFAULT_TENANT_ID,
+        archive,
+        controller.signal,
+      );
+    } catch {
+      aborted = true;
+    }
+
+    expect(aborted).to.equal(true);
+    expect(archive.entries.size).to.equal(0);
+  });
+
+  it("pages the reads without skipping or repeating a row", async () => {
+    const session = await ensureOwnerSession();
+    const client = authorizedClient(session.accessToken);
+    // The list answers 10 rows unless told otherwise; the export reads them all.
+    const list = await client.get(`${TABLE}/list?limit=${LIST_ALL}`);
+    expect(list.status, JSON.stringify(list.data)).to.equal(HTTP_OK);
+    const slugs = (list.data.results as TemplateRow[]).map(
+      (template) => template.slug,
+    );
+    const [templates] = exportedCollections(DEFAULT_TENANT_ID);
+
+    let text = "";
+    for await (const chunk of jsonArrayChunks(
+      (templates as ExportedCollection).load,
+      new AbortController().signal,
+      SINGLE_ROW_PAGE,
+    )) {
+      text += chunk;
+    }
+
+    const paged = (JSON.parse(text) as TemplateRow[]).map(
+      (template) => template.slug,
+    );
+    expect(paged).to.have.members(slugs);
+    expect(new Set(paged).size).to.equal(paged.length);
+  });
+});

package/src/test/unit/attention.test.ts

@@ -0,0 +1,129 @@
+import { expect } from "chai";
+import type { MailingSend, MailingTemplate } from "../../db";
+import {
+  type AttentionItem,
+  buildAttentionItems,
+} from "../../services/attention";
+
+const send = (isTest: boolean): MailingSend =>
+  ({ status: "sent", templateSlug: "welcome", isTest }) as MailingSend;
+
+const NO_TEMPLATES: MailingTemplate[] = [];
+
+const findExcluded = (items: AttentionItem[]) =>
+  items.find((item) => item.id === "test-only-window");
+
+describe("[unit] services/attention test-only window", () => {
+  it("explains the empty figures when every send in the window is a test", () => {
+    const items = buildAttentionItems({
+      templates: NO_TEMPLATES,
+      sends: [],
+      excluded: [send(true), send(true)],
+      tracking: null,
+    });
+    const item = findExcluded(items);
+    expect(item).to.not.equal(undefined);
+    expect(item).to.deep.include({
+      tone: "neutral",
+      title: "$dms_mailing.attention.test_only_window.title",
+      description: "$dms_mailing.attention.test_only_window.description",
+    });
+    expect(item?.params).to.deep.equal({ count: 2 });
+  });
+
+  it("stays quiet when the window holds real sends too", () => {
+    const items = buildAttentionItems({
+      templates: NO_TEMPLATES,
+      sends: [send(false)],
+      excluded: [send(true)],
+      tracking: null,
+    });
+    expect(findExcluded(items)).to.equal(undefined);
+  });
+
+  it("stays quiet when the window is genuinely empty", () => {
+    const items = buildAttentionItems({
+      templates: NO_TEMPLATES,
+      sends: [],
+      excluded: [],
+      tracking: null,
+    });
+    expect(findExcluded(items)).to.equal(undefined);
+  });
+});
+
+const findUntracked = (items: AttentionItem[]) =>
+  items.find((item) => item.id === "untracked-rates");
+
+const TRACKS_NOTHING = {
+  name: "smtp",
+  openTracking: false,
+  clickTracking: false,
+};
+const TRACKS_EVERYTHING = {
+  name: "postmark",
+  openTracking: true,
+  clickTracking: true,
+};
+
+describe("[unit] services/attention untracked rates", () => {
+  it("explains the flat rates when the provider reports neither opens nor clicks", () => {
+    const items = buildAttentionItems({
+      templates: NO_TEMPLATES,
+      sends: [send(false)],
+      excluded: [],
+      tracking: TRACKS_NOTHING,
+    });
+    const item = findUntracked(items);
+    expect(item).to.not.equal(undefined);
+    expect(item).to.deep.include({
+      tone: "neutral",
+      title: "$dms_mailing.attention.untracked_rates.title",
+      description: "$dms_mailing.attention.untracked_rates.description",
+    });
+    expect(item?.params).to.deep.equal({ provider: "smtp" });
+  });
+
+  it("stays quiet when the provider tracks both", () => {
+    const items = buildAttentionItems({
+      templates: NO_TEMPLATES,
+      sends: [send(false)],
+      excluded: [],
+      tracking: TRACKS_EVERYTHING,
+    });
+    expect(findUntracked(items)).to.equal(undefined);
+  });
+
+  it("still fires when only one of the two is tracked, since a rate stays flat", () => {
+    const items = buildAttentionItems({
+      templates: NO_TEMPLATES,
+      sends: [send(false)],
+      excluded: [],
+      tracking: { ...TRACKS_NOTHING, openTracking: true },
+    });
+    expect(findUntracked(items)).to.not.equal(undefined);
+  });
+
+  // The notice explains figures the window actually shows. With nothing sent
+  // there are no rates on screen to explain, and it would just be noise.
+  it("stays quiet when the window holds no send at all", () => {
+    const items = buildAttentionItems({
+      templates: NO_TEMPLATES,
+      sends: [],
+      excluded: [],
+      tracking: TRACKS_NOTHING,
+    });
+    expect(findUntracked(items)).to.equal(undefined);
+  });
+
+  // The provider may be unreachable; that is the provider card's business.
+  it("stays quiet when the provider capabilities are unknown", () => {
+    const items = buildAttentionItems({
+      templates: NO_TEMPLATES,
+      sends: [send(false)],
+      excluded: [],
+      tracking: null,
+    });
+    expect(findUntracked(items)).to.equal(undefined);
+  });
+});

package/src/test/unit/automation.test.ts

@@ -0,0 +1,130 @@
+import { expect } from "chai";
+import { unregisterAutomationNodes } from "../../automation";
+import {
+  clearEmailEventSubscriptions,
+  type EmailEventPayload,
+  emailEventTrigger,
+  emitEmailEvent,
+} from "../../automation/email-event-trigger";
+import { sendTemplateAction } from "../../automation/send-template-action";
+
+const EVENT: EmailEventPayload = {
+  tenantId: "t",
+  sendId: "s",
+  templateSlug: "x",
+  type: "bounced",
+  recipientEmail: "a@b",
+};
+
+describe("[unit] automation nodes", () => {
+  afterEach(() => {
+    clearEmailEventSubscriptions();
+  });
+
+  it("describes the send-template action", () => {
+    expect(sendTemplateAction.id).to.equal("mailing.send-template");
+    expect(sendTemplateAction.inputSchema).to.deep.include({
+      required: ["tenantId", "slug", "to"],
+    });
+  });
+
+  // The automation module ships no loop node: a procedure cannot call this
+  // action once per contact, so the fan-out has to happen inside it. The port
+  // must therefore accept a list, which `sendTemplate` already handles.
+  it("accepts a list of recipients on the `to` port, not just one address", () => {
+    const properties = (
+      sendTemplateAction.inputSchema as {
+        properties: Record<string, { type?: unknown; items?: unknown }>;
+      }
+    ).properties;
+    const to = properties.to as { type?: unknown; items?: unknown };
+    expect(to.type).to.deep.equal(["string", "array"]);
+    expect(to.items).to.deep.equal({ type: "string" });
+  });
+
+  it("fans e-mail events out to active trigger subscriptions filtered by type", async () => {
+    const received: unknown[] = [];
+    const handle = await emailEventTrigger.activate(
+      { types: ["bounced"] },
+      (payload) => {
+        received.push(payload);
+      },
+    );
+    emitEmailEvent({
+      tenantId: "t",
+      sendId: "s",
+      templateSlug: "x",
+      type: "opened",
+      recipientEmail: "a@b",
+    });
+    emitEmailEvent({
+      tenantId: "t",
+      sendId: "s",
+      templateSlug: "x",
+      type: "bounced",
+      recipientEmail: "a@b",
+    });
+    await emailEventTrigger.deactivate(handle);
+    emitEmailEvent({
+      tenantId: "t",
+      sendId: "s",
+      templateSlug: "x",
+      type: "bounced",
+      recipientEmail: "a@b",
+    });
+    expect(received).to.have.length(1);
+  });
+
+  it("fans every event out to a subscription that filters no type", async () => {
+    const received: unknown[] = [];
+    const handle = await emailEventTrigger.activate({}, (payload) => {
+      received.push(payload);
+    });
+    emitEmailEvent({
+      tenantId: "t",
+      sendId: "s",
+      templateSlug: "x",
+      type: "opened",
+      recipientEmail: "a@b",
+    });
+    await emailEventTrigger.deactivate(handle);
+    expect(received).to.have.length(1);
+  });
+
+  it("keeps fanning out when a subscription throws", async () => {
+    const received: EmailEventPayload[] = [];
+    await emailEventTrigger.activate({}, () => {
+      throw new Error("subscriber exploded");
+    });
+    await emailEventTrigger.activate({}, (payload) => {
+      received.push(payload);
+    });
+
+    expect(() => emitEmailEvent(EVENT)).to.not.throw();
+    expect(received).to.deep.equal([EVENT]);
+  });
+
+  it("stops fanning out once the subscriptions are cleared", async () => {
+    const received: EmailEventPayload[] = [];
+    await emailEventTrigger.activate({}, (payload) => {
+      received.push(payload);
+    });
+
+    clearEmailEventSubscriptions();
+    emitEmailEvent(EVENT);
+
+    expect(received).to.have.length(0);
+  });
+
+  it("clears the subscriptions when the node types are unregistered", async () => {
+    const received: EmailEventPayload[] = [];
+    await emailEventTrigger.activate({}, (payload) => {
+      received.push(payload);
+    });
+
+    unregisterAutomationNodes();
+    emitEmailEvent(EVENT);
+
+    expect(received).to.have.length(0);
+  });
+});

package/src/test/unit/categories.test.ts

@@ -0,0 +1,51 @@
+import { expect } from "chai";
+import {
+  parseCategories,
+  reassignRemovedCategories,
+} from "../../services/categories";
+import type { MailingTemplate } from "../../db";
+import type { TemplateCategory } from "../../types";
+
+const CATEGORIES: TemplateCategory[] = [
+  { id: "orders", label: "Orders", icon: "i-ph-package" },
+  { id: "billing", label: "Billing", icon: "i-ph-file-text" },
+];
+
+const template = (id: string, category?: string): MailingTemplate =>
+  ({ _id: id, category }) as MailingTemplate;
+
+describe("[unit] services/categories parseCategories", () => {
+  it("reads the list the form field stores, as a string or an array", () => {
+    expect(parseCategories(JSON.stringify(CATEGORIES))).to.deep.equal(
+      CATEGORIES,
+    );
+    expect(parseCategories(CATEGORIES)).to.deep.equal(CATEGORIES);
+  });
+
+  it("answers an empty list for blank or broken input", () => {
+    expect(parseCategories("")).to.deep.equal([]);
+    expect(parseCategories("not json")).to.deep.equal([]);
+    expect(parseCategories(undefined)).to.deep.equal([]);
+  });
+});
+
+describe("[unit] services/categories reassignRemovedCategories", () => {
+  it("names the templates whose category no longer exists", () => {
+    const templates = [
+      template("a", "orders"),
+      template("b", "gone"),
+      template("c"),
+      template("d", "gone"),
+    ];
+    expect(reassignRemovedCategories(templates, CATEGORIES)).to.deep.equal([
+      "b",
+      "d",
+    ]);
+  });
+
+  it("names nothing when every category survives", () => {
+    expect(
+      reassignRemovedCategories([template("a", "orders")], CATEGORIES),
+    ).to.deep.equal([]);
+  });
+});

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

@@ -0,0 +1,35 @@
+import { expect } from "chai";
+import { evaluateCondition } from "../../../engine";
+import type { Condition } from "../../../types";
+
+const condition = (operator: Condition["operator"], value = ""): Condition => ({
+  path: "order.total",
+  operator,
+  value,
+});
+
+describe("[unit] engine/conditions", () => {
+  it("treats truthy/falsy with JS semantics and missing as false", () => {
+    expect(
+      evaluateCondition(condition("truthy"), { order: { total: 1 } }),
+    ).to.equal(true);
+    expect(
+      evaluateCondition(condition("truthy"), { order: { total: 0 } }),
+    ).to.equal(false);
+    expect(evaluateCondition(condition("falsy"), {})).to.equal(true);
+  });
+  it("compares as strings for eq/ne and as numbers for gt/lt", () => {
+    expect(
+      evaluateCondition(condition("eq", "42"), { order: { total: 42 } }),
+    ).to.equal(true);
+    expect(
+      evaluateCondition(condition("ne", "42"), { order: { total: "42" } }),
+    ).to.equal(false);
+    expect(
+      evaluateCondition(condition("gt", "10"), { order: { total: 11 } }),
+    ).to.equal(true);
+    expect(
+      evaluateCondition(condition("lt", "10"), { order: { total: "abc" } }),
+    ).to.equal(false);
+  });
+});