@antelopejs/dms-mailing 0.2.2

package/src/test/unit/notify.test.ts

@@ -0,0 +1,71 @@
+import { expect } from "chai";
+import {
+  type BounceNotificationInput,
+  bounceIdempotencyKey,
+  bounceNotification,
+  deliverBounceNotification,
+  type IdempotentNotificationTarget,
+  shouldNotify,
+} from "../../services/notify";
+
+const OWNER_IDS = ["owner-1", "owner-2"];
+
+const INPUT: BounceNotificationInput = {
+  sendId: "send-1",
+  templateSlug: "welcome",
+  recipientEmail: "a@b.test",
+  type: "bounced",
+};
+
+interface RecordedDelivery {
+  userIds: string[];
+  idempotencyKey: string;
+}
+
+function recordingTarget(
+  recorded: RecordedDelivery[],
+): IdempotentNotificationTarget {
+  return {
+    toUsersIdempotently: (userIds, idempotencyKey) => {
+      recorded.push({ userIds, idempotencyKey });
+      return Promise.resolve();
+    },
+  };
+}
+
+describe("[unit] services/notify", () => {
+  it("notifies once per problem status, never for happy events", () => {
+    expect(shouldNotify("bounced")).to.equal(true);
+    expect(shouldNotify("spam")).to.equal(true);
+    expect(shouldNotify("opened")).to.equal(false);
+  });
+
+  it("builds a notification pointing at the sends page", () => {
+    const notification = bounceNotification(INPUT);
+    expect(notification.linkTo).to.equal("/modules/mailing/sends?tab=problems");
+    expect(notification.params).to.deep.equal({
+      slug: "welcome",
+      email: "a@b.test",
+    });
+  });
+
+  it("keys a bounce on the send it belongs to and its event type", () => {
+    expect(bounceIdempotencyKey(INPUT)).to.equal("send-1:bounced");
+    expect(bounceIdempotencyKey({ ...INPUT, type: "spam" })).to.equal(
+      "send-1:spam",
+    );
+  });
+
+  it("delivers through the idempotent path with a stable key", async () => {
+    const recorded: RecordedDelivery[] = [];
+    const target = recordingTarget(recorded);
+
+    await deliverBounceNotification(target, OWNER_IDS, INPUT);
+    await deliverBounceNotification(target, OWNER_IDS, INPUT);
+
+    expect(recorded).to.deep.equal([
+      { userIds: OWNER_IDS, idempotencyKey: "send-1:bounced" },
+      { userIds: OWNER_IDS, idempotencyKey: "send-1:bounced" },
+    ]);
+  });
+});

package/src/test/unit/period.test.ts

@@ -0,0 +1,64 @@
+import type { RequestContext } from "@antelopejs/interface-api";
+import { expect } from "chai";
+import { MAX_WINDOW_DAYS } from "../../constants";
+import {
+  comparisonRange,
+  currentRange,
+  type RangeContext,
+} from "../../routes/period";
+
+const DAY_MS = 86_400_000;
+
+const ctxWith = (query: Record<string, string>): RangeContext => ({
+  url: { searchParams: new URLSearchParams(query) } as RequestContext["url"],
+});
+
+const spanDays = (range: { from: Date; to: Date }) =>
+  (range.to.getTime() - range.from.getTime()) / DAY_MS;
+
+describe("[unit] period range", () => {
+  it("keeps a window the dashboard actually asks for", () => {
+    const range = currentRange(
+      ctxWith({
+        from: "2026-09-04T00:00:00.000Z",
+        to: "2026-09-11T00:00:00.000Z",
+      }),
+    );
+    expect(spanDays(range)).to.equal(7);
+  });
+
+  // `from` and `to` are plain query parameters. Without a ceiling a caller can
+  // ask for centuries, and every daily series then allocates one bucket per day.
+  it("clamps an absurd window instead of allocating a bucket per day", () => {
+    const range = currentRange(
+      ctxWith({
+        from: "1500-01-01T00:00:00.000Z",
+        to: "2500-01-01T00:00:00.000Z",
+      }),
+    );
+    expect(spanDays(range)).to.equal(MAX_WINDOW_DAYS);
+    expect(range.to.toISOString()).to.equal("2500-01-01T00:00:00.000Z");
+  });
+
+  it("leaves a reversed window alone rather than inventing one", () => {
+    const range = currentRange(
+      ctxWith({
+        from: "2026-09-11T00:00:00.000Z",
+        to: "2026-09-04T00:00:00.000Z",
+      }),
+    );
+    expect(spanDays(range)).to.be.lessThan(0);
+  });
+
+  it("derives the comparison window from the clamped current one", () => {
+    const current = currentRange(
+      ctxWith({
+        from: "1500-01-01T00:00:00.000Z",
+        to: "2500-01-01T00:00:00.000Z",
+      }),
+    );
+    const previous = comparisonRange(ctxWith({}), current);
+    expect(spanDays(previous)).to.equal(MAX_WINDOW_DAYS);
+    expect(previous.to.getTime()).to.equal(current.from.getTime());
+  });
+});

package/src/test/unit/provider.test.ts

@@ -0,0 +1,57 @@
+import type { ProviderCapabilities } from "@antelopejs/interface-email";
+import { expect } from "chai";
+import {
+  CAPABILITIES_TTL_MS,
+  readCapabilities,
+  resetCapabilitiesCache,
+} from "../../services/provider";
+
+const CAPABILITIES = {
+  name: "smtp",
+  features: { openTracking: false, clickTracking: false },
+} as ProviderCapabilities;
+
+function countingLoader() {
+  let calls = 0;
+  return {
+    get calls() {
+      return calls;
+    },
+    load: () => {
+      calls += 1;
+      return Promise.resolve(CAPABILITIES);
+    },
+  };
+}
+
+describe("[unit] provider capabilities cache", () => {
+  beforeEach(resetCapabilitiesCache);
+  afterEach(resetCapabilitiesCache);
+
+  it("asks the provider once inside the window", async () => {
+    const loader = countingLoader();
+    await readCapabilities(loader.load, 1000);
+    await readCapabilities(loader.load, 1000 + CAPABILITIES_TTL_MS - 1);
+    expect(loader.calls).to.equal(1);
+  });
+
+  it("asks again once the window has passed", async () => {
+    const loader = countingLoader();
+    await readCapabilities(loader.load, 1000);
+    await readCapabilities(loader.load, 1000 + CAPABILITIES_TTL_MS);
+    expect(loader.calls).to.equal(2);
+  });
+
+  // An unreachable provider is polled by the dashboard like any other: retrying
+  // on every request would turn one outage into a burst of failing calls.
+  it("memoises a failure instead of retrying on every request", async () => {
+    let calls = 0;
+    const failing = () => {
+      calls += 1;
+      return Promise.reject(new Error("down"));
+    };
+    expect(await readCapabilities(failing, 1000)).to.equal(null);
+    expect(await readCapabilities(failing, 1500)).to.equal(null);
+    expect(calls).to.equal(1);
+  });
+});

package/src/test/unit/realtime.test.ts

@@ -0,0 +1,11 @@
+import { expect } from "chai";
+import { realtimePageIds } from "../../realtime";
+
+describe("[unit] realtime", () => {
+  it("resolves the full page ids the sends topic is registered on", () => {
+    expect(realtimePageIds()).to.deep.equal([
+      "modules.mailing.sends",
+      "modules.mailing.overview",
+    ]);
+  });
+});

package/src/test/unit/render.test.ts

@@ -0,0 +1,23 @@
+import { expect } from "chai";
+import { setConfig } from "../../config";
+import { renderEmailHtml } from "../../services/render";
+import type { ResolvedEmail } from "../../types";
+
+const EMAIL: ResolvedEmail = {
+  subject: "S",
+  preheader: "",
+  blocks: [
+    { id: "h", type: "heading", text: "Hello", align: "left", size: 23 },
+  ],
+  missing: [],
+  hiddenBlockIds: [],
+};
+
+describe("[unit] services/render", () => {
+  it("uses the fallback renderer when the DMS html-render chain is disabled", async () => {
+    setConfig({ useHtmlRender: false });
+    const html = await renderEmailHtml(EMAIL, "en");
+    expect(html).to.include("<title>S</title>");
+    expect(html).to.include("Hello");
+  });
+});

package/src/test/unit/retention.test.ts

@@ -0,0 +1,91 @@
+import { expect } from "chai";
+import cron from "node-cron";
+import {
+  RETENTION_LIMITS,
+  type RetentionLimits,
+  type RetentionPass,
+  purgeInPages,
+  retentionLimit,
+  scheduleRetention,
+  stopRetention,
+} from "../../crons/retention";
+
+const EXTRA_ROW = 1;
+const SMALL_LIMITS: RetentionLimits = { pageSize: 2, maxRows: 5 };
+const BACKLOG = 100;
+
+interface FakePass extends RetentionPass {
+  readonly pageSizes: number[];
+  readonly purged: string[];
+}
+
+function fakePass(rowCount: number): FakePass {
+  const remaining = Array.from({ length: rowCount }, (_row, index) =>
+    String(index),
+  );
+  const pageSizes: number[] = [];
+  const purged: string[] = [];
+  return {
+    pageSizes,
+    purged,
+    loadPage(size) {
+      pageSizes.push(size);
+      return Promise.resolve(remaining.slice(0, size));
+    },
+    purgeSend(sendId) {
+      purged.push(sendId);
+      remaining.splice(remaining.indexOf(sendId), 1);
+      return Promise.resolve(1);
+    },
+  };
+}
+
+describe("[unit] crons/retention", () => {
+  it("computes the cutoff from the retention days", () => {
+    const now = new Date("2026-09-09T00:00:00.000Z");
+    expect(retentionLimit(90, now).toISOString()).to.equal(
+      "2026-06-11T00:00:00.000Z",
+    );
+  });
+
+  it("purges a backlog page by page", async () => {
+    const rowCount = RETENTION_LIMITS.pageSize * 2 + EXTRA_ROW;
+    const pass = fakePass(rowCount);
+
+    const purged = await purgeInPages(pass);
+
+    expect(purged).to.equal(rowCount);
+    expect(pass.purged).to.have.length(rowCount);
+    expect(pass.pageSizes).to.deep.equal([
+      RETENTION_LIMITS.pageSize,
+      RETENTION_LIMITS.pageSize,
+      RETENTION_LIMITS.pageSize,
+    ]);
+  });
+
+  it("stops at the bounded number of rows per run", async () => {
+    const pass = fakePass(BACKLOG);
+
+    const purged = await purgeInPages(pass, SMALL_LIMITS);
+
+    expect(purged).to.equal(SMALL_LIMITS.maxRows);
+    expect(pass.pageSizes).to.deep.equal([2, 2, 1]);
+  });
+
+  it("counts actual deletes and bounds work even when every candidate loses a race", async () => {
+    const pass = fakePass(BACKLOG);
+    pass.purgeSend = () => Promise.resolve(0);
+
+    expect(await purgeInPages(pass, SMALL_LIMITS)).to.equal(0);
+    expect(pass.pageSizes).to.deep.equal([2, 2, 1]);
+  });
+
+  it("drops the task from the node-cron registry when it is stopped", async () => {
+    const task = scheduleRetention();
+    expect(cron.getTasks().has(task.id)).to.equal(true);
+
+    await stopRetention(task);
+
+    expect(cron.getTasks().has(task.id)).to.equal(false);
+  });
+});

package/src/test/unit/send-batch.test.ts

@@ -0,0 +1,72 @@
+import type { BatchEmailMessageResponse } from "@antelopejs/interface-email";
+import { expect } from "chai";
+import { matchBatchResponses } from "../../services/send";
+
+const BATCH_LATENCY_MS = 12;
+const PER_MESSAGE_LATENCY_MS = 6;
+const QUARTER_LATENCY_MS = 3;
+
+const response = (
+  index: number,
+  overrides: Partial<BatchEmailMessageResponse> = {},
+): BatchEmailMessageResponse => ({
+  index,
+  recipient: `r${index}@test.local`,
+  success: true,
+  status: "sent",
+  messageId: `m${index}`,
+  ...overrides,
+});
+
+describe("[unit] services/send batch matching", () => {
+  it("pairs every recipient with the response carrying its index", () => {
+    const delivered = matchBatchResponses(
+      ["a@test.local", "b@test.local"],
+      [response(1), response(0)],
+      BATCH_LATENCY_MS,
+    );
+    expect(delivered.map((message) => message.to)).to.deep.equal([
+      "a@test.local",
+      "b@test.local",
+    ]);
+    expect(
+      delivered.map((message) => message.outcome.providerMessageId),
+    ).to.deep.equal(["m0", "m1"]);
+    expect(delivered.every((message) => message.status === "sent")).to.equal(
+      true,
+    );
+  });
+
+  it("fails the recipients the provider left out or rejected", () => {
+    const delivered = matchBatchResponses(
+      ["a@test.local", "b@test.local"],
+      [
+        response(0, {
+          success: false,
+          status: "failed",
+          error: { code: "rejected", message: "Mailbox unavailable" },
+        }),
+      ],
+      BATCH_LATENCY_MS,
+    );
+    expect(delivered[0]?.status).to.equal("failed");
+    expect(delivered[0]?.outcome.error).to.equal("Mailbox unavailable");
+    expect(delivered[1]?.status).to.equal("failed");
+    expect(delivered[1]?.outcome.latencyMs).to.equal(PER_MESSAGE_LATENCY_MS);
+  });
+
+  it("splits the batch wall-clock over the messages it covered", () => {
+    const recipients = ["a", "b", "c", "d"].map((id) => `${id}@test.local`);
+    const responses = recipients.map((_to, index) => response(index));
+
+    const delivered = matchBatchResponses(
+      recipients,
+      responses,
+      BATCH_LATENCY_MS,
+    );
+
+    expect(delivered.map((message) => message.outcome.latencyMs)).to.deep.equal(
+      recipients.map(() => QUARTER_LATENCY_MS),
+    );
+  });
+});

package/src/test/unit/send.test.ts

@@ -0,0 +1,161 @@
+import type { EmailParams, EmailResponse } from "@antelopejs/interface-email";
+import { expect } from "chai";
+import type { SendTemplateParams } from "@antelopejs/interface-dms-mailing";
+import {
+  aggregateResults,
+  deliverBatch,
+  type DeliveredMessage,
+  type DeliveryInput,
+  deliverEach,
+  type PreparedSend,
+  recordAll,
+  type SendRecordInput,
+} from "../../services/send";
+import { DEFAULT_CATEGORIES, type MailingSettingsValues } from "../../types";
+
+const TRANSPORT_FAILURE = "socket hang up";
+const INSERT_FAILURE = "insert rejected";
+const RECIPIENTS = ["first@test.local", "second@test.local"];
+
+const PREPARED: PreparedSend = {
+  content: { locales: {} },
+  locale: "en",
+  templateId: "template-1",
+  slug: "welcome",
+  tenantId: "tenant-1",
+};
+
+const SETTINGS: MailingSettingsValues = {
+  fallbackLocale: "en",
+  logRetentionDays: 90,
+  blockOnMissingVariables: false,
+  senderName: "Sender",
+  senderEmail: "sender@test.local",
+  replyTo: "",
+  webhookSecret: "secret",
+  categories: DEFAULT_CATEGORIES,
+};
+
+const PARAMS: SendTemplateParams = {
+  tenantId: PREPARED.tenantId,
+  to: RECIPIENTS,
+};
+
+const input = (recipients: string[]): DeliveryInput => ({
+  prepared: PREPARED,
+  settings: SETTINGS,
+  subject: "Hello",
+  html: "<p>Hello</p>",
+  recipients,
+});
+
+const accepted = (messageId: string): EmailResponse => ({
+  success: true,
+  status: "sent",
+  messageId,
+  provider: "test",
+});
+
+const delivered = (
+  to: string,
+  overrides: Partial<DeliveredMessage> = {},
+): DeliveredMessage => ({
+  to,
+  status: "sent",
+  outcome: { latencyMs: 1, providerMessageId: `m-${to}` },
+  ...overrides,
+});
+
+describe("[unit] services/send delivery", () => {
+  it("keeps the messages the provider accepted when a later send throws", async () => {
+    const seen: string[] = [];
+    const send = async (params: EmailParams): Promise<EmailResponse> => {
+      const to = params.to as string;
+      seen.push(to);
+      if (to === RECIPIENTS[1]) throw new Error(TRANSPORT_FAILURE);
+      return accepted("m-1");
+    };
+
+    const messages = await deliverEach(input(RECIPIENTS), send);
+
+    expect(seen).to.deep.equal(RECIPIENTS);
+    expect(messages.map((message) => message.status)).to.deep.equal([
+      "sent",
+      "failed",
+    ]);
+    expect(messages[0]?.outcome.providerMessageId).to.equal("m-1");
+    expect(messages[1]?.outcome.error).to.contain(TRANSPORT_FAILURE);
+  });
+
+  it("keeps the sends it could record when a later insert throws", async () => {
+    const save = async (
+      _tenantId: string,
+      record: SendRecordInput,
+    ): Promise<string> => {
+      if (record.to === RECIPIENTS[1]) throw new Error(INSERT_FAILURE);
+      return "send-1";
+    };
+
+    const results = await recordAll(
+      PREPARED,
+      PARAMS,
+      RECIPIENTS.map((to) => delivered(to)),
+      save,
+    );
+
+    expect(results).to.have.length(2);
+    expect(results[0]?.sendId).to.equal("send-1");
+    expect(results[1]?.status).to.equal("failed");
+    expect(results[1]?.error).to.contain(INSERT_FAILURE);
+  });
+
+  it("fails every recipient when the batch call itself throws", async () => {
+    const messages = await deliverBatch(input(RECIPIENTS), () =>
+      Promise.reject(new Error(TRANSPORT_FAILURE)),
+    );
+
+    expect(messages.map((message) => message.status)).to.deep.equal([
+      "failed",
+      "failed",
+    ]);
+    expect(messages[0]?.outcome.error).to.contain(TRANSPORT_FAILURE);
+  });
+});
+
+describe("[unit] services/send result aggregation", () => {
+  it("reports the whole call while keeping the single-recipient shape", () => {
+    const single = aggregateResults([
+      { sendId: "send-1", status: "sent", messageId: "m-1" },
+    ]);
+
+    expect(single.sendId).to.equal("send-1");
+    expect(single.status).to.equal("sent");
+    expect(single.messageId).to.equal("m-1");
+    expect(single.error).to.equal(undefined);
+    expect(single.results).to.have.length(1);
+  });
+
+  it("degrades to the worst recipient outcome and surfaces its error", () => {
+    const results = [
+      { sendId: "send-1", status: "sent" as const, messageId: "m-1" },
+      { sendId: "send-2", status: "failed" as const, error: "Mailbox full" },
+    ];
+
+    const aggregated = aggregateResults(results);
+
+    expect(aggregated.sendId).to.equal("send-1");
+    expect(aggregated.messageId).to.equal("m-1");
+    expect(aggregated.status).to.equal("failed");
+    expect(aggregated.error).to.equal("Mailbox full");
+    expect(aggregated.results).to.deep.equal(results);
+  });
+
+  it("prefers the least advanced status when nothing failed", () => {
+    const aggregated = aggregateResults([
+      { sendId: "send-1", status: "sent" },
+      { sendId: "send-2", status: "queued" },
+    ]);
+
+    expect(aggregated.status).to.equal("queued");
+  });
+});

package/src/test/unit/smoke.test.ts

@@ -0,0 +1,8 @@
+import { expect } from "chai";
+import { MODULE_ID } from "../../constants";
+
+describe("[unit] smoke", () => {
+  it("exposes the module id", () => {
+    expect(MODULE_ID).to.equal("mailing");
+  });
+});

package/src/test/unit/status.test.ts

@@ -0,0 +1,14 @@
+import { expect } from "chai";
+import { toSendStatus } from "../../services/status";
+
+describe("[unit] services/status", () => {
+  it("maps provider statuses onto send statuses", () => {
+    expect(toSendStatus("queued")).to.equal("queued");
+    expect(toSendStatus("sent")).to.equal("sent");
+    expect(toSendStatus("delivered")).to.equal("delivered");
+    expect(toSendStatus("rejected")).to.equal("bounced");
+    expect(toSendStatus("scheduled")).to.equal("queued");
+    expect(toSendStatus("failed")).to.equal("failed");
+    expect(toSendStatus("unknown")).to.equal("sent");
+  });
+});

package/src/test/unit/templates.test.ts

@@ -0,0 +1,52 @@
+import { expect } from "chai";
+import { blankContent, localesOf } from "../../services/templates";
+import type { LocaleContent, TemplateContent } from "../../types";
+
+const emptyLocale = (): LocaleContent => ({
+  subject: "",
+  preheader: "",
+  blocks: [],
+});
+
+describe("[unit] services/templates localesOf", () => {
+  it("lists the locale codes present in the content", () => {
+    const content: TemplateContent = {
+      locales: { en: emptyLocale(), fr: emptyLocale() },
+    };
+    expect(localesOf(content)).to.equal("en,fr");
+  });
+
+  it("answers an empty string for content without locales", () => {
+    const content: TemplateContent = { locales: {} };
+    expect(localesOf(content)).to.equal("");
+  });
+});
+
+describe("[unit] services/templates blankContent", () => {
+  it("carries only a footer with the unsubscribe and preferences labels", () => {
+    const content = blankContent("en");
+    const locale = content.locales.en as LocaleContent;
+    expect(Object.keys(content.locales)).to.deep.equal(["en"]);
+    expect(locale.blocks).to.have.lengthOf(1);
+    const [footer] = locale.blocks;
+    expect(footer?.type).to.equal("footer");
+    expect(footer).to.include({
+      unsubscribeLabel: "Unsubscribe",
+      preferencesLabel: "Preferences",
+    });
+  });
+
+  it("invents no subject, preheader or footer prose", () => {
+    const locale = blankContent("en").locales.en as LocaleContent;
+    expect(locale.subject).to.equal("");
+    expect(locale.preheader).to.equal("");
+    expect(locale.blocks[0]).to.include({ text: "" });
+  });
+
+  it("localises the labels and falls back to English", () => {
+    const french = blankContent("fr").locales.fr as LocaleContent;
+    expect(french.blocks[0]).to.include({ unsubscribeLabel: "Se désinscrire" });
+    const unknown = blankContent("de").locales.de as LocaleContent;
+    expect(unknown.blocks[0]).to.include({ unsubscribeLabel: "Unsubscribe" });
+  });
+});