@antelopejs/dms-mailing 0.3.4 → 0.4.1

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

@@ -1,170 +0,0 @@
-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);
-  });
-});

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

@@ -1,71 +0,0 @@
-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

@@ -1,91 +0,0 @@
-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());
-  });
-
-  // `compareFrom`/`compareTo` are plain query parameters too, and every metric
-  // reads its comparison window from the send log in full.
-  it("clamps an explicit comparison window like the current one", () => {
-    const current = currentRange(ctxWith({}));
-    const previous = comparisonRange(
-      ctxWith({
-        compareFrom: "1970-01-01T00:00:00.000Z",
-        compareTo: "2026-09-01T00:00:00.000Z",
-      }),
-      current,
-    );
-    expect(spanDays(previous)).to.equal(MAX_WINDOW_DAYS);
-    expect(previous.to.toISOString()).to.equal("2026-09-01T00:00:00.000Z");
-  });
-
-  it("keeps an explicit comparison window within the cap", () => {
-    const current = currentRange(ctxWith({}));
-    const previous = comparisonRange(
-      ctxWith({
-        compareFrom: "2026-08-01T00:00:00.000Z",
-        compareTo: "2026-09-01T00:00:00.000Z",
-      }),
-      current,
-    );
-    expect(previous.from.toISOString()).to.equal("2026-08-01T00:00:00.000Z");
-  });
-});

package/src/test/unit/permissions.test.ts

@@ -1,30 +0,0 @@
-import { expect } from "chai";
-import { GetPermission } from "@antelopejs/interface-dms/permissions";
-import { MAILING_SEND_PERMISSION } from "../../constants";
-
-const SENDS_PAGE_PERMISSION = "modules.mailing.sends";
-const SETTINGS_PAGE_PERMISSION = "settings.mailing.settings";
-const REMOVED_PERMISSIONS = [
-  "mailing.access",
-  "mailing.templates.manage",
-  "mailing.settings.manage",
-];
-
-describe("[unit] permissions", () => {
-  it("makes the send permission depend on the sends page permission", async () => {
-    const permission = await GetPermission(MAILING_SEND_PERMISSION);
-    expect(permission?.dependencies).to.deep.equal([SENDS_PAGE_PERMISSION]);
-  });
-
-  it("registers the settings page default permission", async () => {
-    expect(await GetPermission(SETTINGS_PAGE_PERMISSION)).to.not.equal(
-      undefined,
-    );
-  });
-
-  it("no longer registers the page-access permissions", async () => {
-    for (const id of REMOVED_PERMISSIONS) {
-      expect(await GetPermission(id), id).to.equal(undefined);
-    }
-  });
-});

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

@@ -1,57 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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

@@ -1,91 +0,0 @@
-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

@@ -1,72 +0,0 @@
-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),
-    );
-  });
-});