create-ailk 0.4.0 → 0.6.0

package/templates/apps/api/src/services/__tests__/dunning-policy.test.ts

@@ -0,0 +1,368 @@
+/**
+ * @file dunning-policy.test.ts
+ * @description Unit tests for the per-tenant dunning grace policy (#6034
+ * §§ D4, D5) — the § D4 resolution table row by row, the key form, the
+ * rejecting query, and both exported predicates across every recorded
+ * state.
+ *
+ * External dependency boundaries mocked:
+ *   - @working-theory/database (via moduleNameMapper → prisma-client.js mock; prisma singleton via __mocks__/prisma.ts)
+ *   - @working-theory/observability logger
+ *
+ * `isModuleEnabled` reads `process.env.AILK_ENABLED_MODULES` directly — the
+ * REAL env boundary, set/restored per `lead-promotion.test.ts`'s convention,
+ * rather than a `jest.mock` of the internal `../../config/modules.js` module
+ * (CONTRIBUTING.md § Test code quality forbids mocking an internal module).
+ */
+
+// eslint-disable-next-line no-restricted-syntax -- prisma is a DB boundary; __mocks__/prisma.ts activates the auto-mock (Jest requires explicit call for local files)
+jest.mock("../../lib/prisma.js");
+
+const mockLoggerInfo = jest.fn();
+const mockLoggerWarn = jest.fn();
+const mockLoggerError = jest.fn();
+jest.mock("@working-theory/observability", () => ({
+  logger: {
+    info: (...args: unknown[]) => mockLoggerInfo(...args),
+    warn: (...args: unknown[]) => mockLoggerWarn(...args),
+    error: (...args: unknown[]) => mockLoggerError(...args),
+    debug: jest.fn(),
+  },
+}));
+
+import {
+  mockNoWorkspace,
+  mockSentinelWorkspaceExists,
+  mockWorkspaceExists,
+  SENTINEL_WORKSPACE_ID,
+} from "../../lib/__mocks__/prisma.js";
+import { prisma } from "../../lib/prisma.js";
+import {
+  DUNNING_GRACE_DAYS_MAX,
+  DUNNING_POLICY_DEFAULTS,
+  dunningPolicyFor,
+  isSubscriberActionRequired,
+  isSubscriberRevoked,
+  type DunningEntry,
+} from "../dunning-policy.js";
+
+const SITE_ID = "site-abc";
+const EXPECTED_KEY = `commerce.dunning_policy:${SITE_ID}`;
+
+const priorEnabledModules = process.env.AILK_ENABLED_MODULES;
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  delete process.env.AILK_ENABLED_MODULES;
+  // #6335 — the shared prisma mock no longer resolves a workspace for any id
+  // asked of it, so this suite states the one it expects. Every case below
+  // reaches `dunningPolicyFor(SITE_ID)`, which resolves the alias before it
+  // reads `site_settings`; without this the resolution returns null and the
+  // read never happens, so the § D4 table would assert nothing.
+  mockWorkspaceExists(prisma, SITE_ID);
+});
+
+afterAll(() => {
+  if (priorEnabledModules === undefined) {
+    delete process.env.AILK_ENABLED_MODULES;
+  } else {
+    process.env.AILK_ENABLED_MODULES = priorEnabledModules;
+  }
+});
+
+// ── § D4's resolution table, row by row ────────────────────────────────────
+
+describe("dunningPolicyFor — the resolution table (§ D4)", () => {
+  it("no row → the platform default, logged info 'no_policy_row'", async () => {
+    (prisma.siteSetting.findUnique as jest.Mock).mockResolvedValue(null);
+
+    const policy = await dunningPolicyFor(SITE_ID);
+
+    expect(policy).toEqual(DUNNING_POLICY_DEFAULTS);
+    expect(mockLoggerInfo).toHaveBeenCalledWith(
+      expect.objectContaining({ outcome: "no_policy_row", key: EXPECTED_KEY }),
+      expect.any(String),
+    );
+    expect(mockLoggerError).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["a string", "not-json"],
+    ["an array", [1, 2, 3]],
+    ["a number", 5],
+    ["null", null],
+  ])(
+    "stored value is %s (not a JSON object) → default, error 'malformed'",
+    async (_label, value) => {
+      (prisma.siteSetting.findUnique as jest.Mock).mockResolvedValue({ value });
+
+      const policy = await dunningPolicyFor(SITE_ID);
+
+      expect(policy).toEqual(DUNNING_POLICY_DEFAULTS);
+      expect(mockLoggerError).toHaveBeenCalledWith(
+        expect.objectContaining({ outcome: "malformed" }),
+        expect.any(String),
+      );
+    },
+  );
+
+  it("graceDays absent → default, error 'malformed'", async () => {
+    (prisma.siteSetting.findUnique as jest.Mock).mockResolvedValue({
+      value: {},
+    });
+
+    const policy = await dunningPolicyFor(SITE_ID);
+
+    expect(policy).toEqual(DUNNING_POLICY_DEFAULTS);
+    expect(mockLoggerError).toHaveBeenCalledWith(
+      expect.objectContaining({ outcome: "malformed" }),
+      expect.any(String),
+    );
+  });
+
+  it.each([
+    ["a string", "14"],
+    ["null", null],
+    ["a bool", true],
+    ["an array", [14]],
+    ["an object", { days: 14 }],
+  ])(
+    "graceDays is %s → default, error 'malformed'",
+    async (_label, graceDays) => {
+      (prisma.siteSetting.findUnique as jest.Mock).mockResolvedValue({
+        value: { graceDays },
+      });
+
+      const policy = await dunningPolicyFor(SITE_ID);
+
+      expect(policy).toEqual(DUNNING_POLICY_DEFAULTS);
+      expect(mockLoggerError).toHaveBeenCalledWith(
+        expect.objectContaining({ outcome: "malformed" }),
+        expect.any(String),
+      );
+    },
+  );
+
+  it("graceDays is a magnitude JSON can hold but JS cannot (1e999 → Infinity) → default, error 'non_finite'", async () => {
+    // `1e999` is the real-world value (a magnitude `JSON.parse` overflows to
+    // `Infinity`); `Number.POSITIVE_INFINITY` is used directly here so the
+    // literal itself doesn't trip `no-loss-of-precision` — both reach the
+    // exact same `Number.isFinite()` guard.
+    (prisma.siteSetting.findUnique as jest.Mock).mockResolvedValue({
+      value: { graceDays: Number.POSITIVE_INFINITY },
+    });
+
+    const policy = await dunningPolicyFor(SITE_ID);
+
+    expect(policy).toEqual(DUNNING_POLICY_DEFAULTS);
+    expect(mockLoggerError).toHaveBeenCalledWith(
+      expect.objectContaining({ outcome: "non_finite" }),
+      expect.any(String),
+    );
+  });
+
+  it("graceDays negative and finite → clamped to 0, error 'clamped_low'", async () => {
+    (prisma.siteSetting.findUnique as jest.Mock).mockResolvedValue({
+      value: { graceDays: -5 },
+    });
+
+    const policy = await dunningPolicyFor(SITE_ID);
+
+    expect(policy).toEqual({ graceDays: 0 });
+    expect(mockLoggerError).toHaveBeenCalledWith(
+      expect.objectContaining({ outcome: "clamped_low", stored: -5 }),
+      expect.any(String),
+    );
+  });
+
+  it("graceDays finite and > the ceiling → clamped to the ceiling, error 'clamped_high'", async () => {
+    (prisma.siteSetting.findUnique as jest.Mock).mockResolvedValue({
+      value: { graceDays: 365 },
+    });
+
+    const policy = await dunningPolicyFor(SITE_ID);
+
+    expect(policy).toEqual({ graceDays: DUNNING_GRACE_DAYS_MAX });
+    expect(mockLoggerError).toHaveBeenCalledWith(
+      expect.objectContaining({ outcome: "clamped_high", stored: 365 }),
+      expect.any(String),
+    );
+  });
+
+  it("graceDays non-integer (e.g. 7.5) → floored, warn 'floored'", async () => {
+    (prisma.siteSetting.findUnique as jest.Mock).mockResolvedValue({
+      value: { graceDays: 7.5 },
+    });
+
+    const policy = await dunningPolicyFor(SITE_ID);
+
+    expect(policy).toEqual({ graceDays: 7 });
+    expect(mockLoggerWarn).toHaveBeenCalledWith(
+      expect.objectContaining({ outcome: "floored", stored: 7.5 }),
+      expect.any(String),
+    );
+    expect(mockLoggerError).not.toHaveBeenCalled();
+  });
+
+  it("the query itself throws → default, error 'read_failed'", async () => {
+    (prisma.siteSetting.findUnique as jest.Mock).mockRejectedValue(
+      new Error("connection reset"),
+    );
+
+    const policy = await dunningPolicyFor(SITE_ID);
+
+    expect(policy).toEqual(DUNNING_POLICY_DEFAULTS);
+    expect(mockLoggerError).toHaveBeenCalledWith(
+      expect.objectContaining({ outcome: "read_failed" }),
+      expect.any(String),
+    );
+  });
+
+  it("a valid integer in [0, DUNNING_GRACE_DAYS_MAX] → that value, no log", async () => {
+    (prisma.siteSetting.findUnique as jest.Mock).mockResolvedValue({
+      value: { graceDays: 21 },
+    });
+
+    const policy = await dunningPolicyFor(SITE_ID);
+
+    expect(policy).toEqual({ graceDays: 21 });
+    expect(mockLoggerInfo).not.toHaveBeenCalled();
+    expect(mockLoggerWarn).not.toHaveBeenCalled();
+    expect(mockLoggerError).not.toHaveBeenCalled();
+  });
+});
+
+// ── The key form ────────────────────────────────────────────────────────────
+
+describe("dunningPolicyFor — the key form", () => {
+  it("queries exactly commerce.dunning_policy:<siteId>, never an unsuffixed key", async () => {
+    (prisma.siteSetting.findUnique as jest.Mock).mockResolvedValue({
+      value: { graceDays: 14 },
+    });
+
+    await dunningPolicyFor(SITE_ID);
+
+    expect(prisma.siteSetting.findUnique).toHaveBeenCalledTimes(1);
+    const call = (prisma.siteSetting.findUnique as jest.Mock).mock.calls[0][0];
+    // #6374 D3 — `site_settings` is now unique on (workspace_id, key), so
+    // the selector is the COMPOUND `workspaceId_key`, not a bare `key`.
+    expect(call).toEqual({
+      where: { workspaceId_key: { workspaceId: SITE_ID, key: EXPECTED_KEY } },
+      select: { value: true },
+    });
+    expect(call.where.workspaceId_key.key).not.toBe("commerce.dunning_policy");
+  });
+
+  // ── #6374 AC-7 — the key is built from the UNRESOLVED siteId ─────────────
+  it("builds `key` from the UNRESOLVED siteId parameter, even when the alias resolves to something else", async () => {
+    // The alias `"default"` resolves to the sentinel workspace id. The KEY
+    // must still read `commerce.dunning_policy:default` — the alias is
+    // embedded in the key STRING because `site_settings` never had a
+    // `site_id` column, and the migration's backfill leaves every key
+    // verbatim. Rebuilding the key from the RESOLVED id would match no row
+    // and hand every seller the built-in default policy, silently. Only the
+    // WORKSPACE half is resolved.
+    mockSentinelWorkspaceExists(prisma);
+    (prisma.siteSetting.findUnique as jest.Mock).mockResolvedValue({
+      value: { graceDays: 14 },
+    });
+
+    await dunningPolicyFor("default");
+
+    const call = (prisma.siteSetting.findUnique as jest.Mock).mock.calls[0][0];
+    expect(call.where.workspaceId_key.key).toBe(
+      "commerce.dunning_policy:default",
+    );
+    expect(call.where.workspaceId_key.workspaceId).toBe(SENTINEL_WORKSPACE_ID);
+  });
+
+  it("an alias that resolves to no workspace returns the platform default and reads nothing", async () => {
+    mockNoWorkspace(prisma);
+
+    const policy = await dunningPolicyFor("no-such-site");
+
+    expect(policy).toEqual(DUNNING_POLICY_DEFAULTS);
+    expect(prisma.siteSetting.findUnique).not.toHaveBeenCalled();
+  });
+
+  it("multi-tenant deployments log the deployment-wide-policy warning once per process", async () => {
+    process.env.AILK_ENABLED_MODULES = "multi-tenant";
+    (prisma.siteSetting.findUnique as jest.Mock).mockResolvedValue({
+      value: { graceDays: 14 },
+    });
+
+    await dunningPolicyFor(SITE_ID);
+    await dunningPolicyFor(SITE_ID);
+
+    const deploymentWideCalls = mockLoggerWarn.mock.calls.filter(
+      ([fields]) => fields?.outcome === "deployment_wide_policy",
+    );
+    expect(deploymentWideCalls).toHaveLength(1);
+  });
+});
+
+// ── The two exported predicates, across every recorded state ───────────────
+
+function entry(overrides: Partial<DunningEntry> = {}): DunningEntry {
+  return {
+    status: "active",
+    accessState: "granted",
+    dunningArmedAt: null,
+    accessRevokesAt: null,
+    lastEventAt: 1_700_000_000,
+    lastEventId: "evt_base",
+    ...overrides,
+  };
+}
+
+const NOW = Date.parse("2026-09-18T00:00:00.000Z");
+
+describe("isSubscriberRevoked / isSubscriberActionRequired — every recorded state", () => {
+  it("active — not revoked, no action required", () => {
+    const e = entry({ status: "active", accessState: "granted" });
+    expect(isSubscriberRevoked(e, NOW)).toBe(false);
+    expect(isSubscriberActionRequired(e, NOW)).toBe(false);
+  });
+
+  it("past_due — not revoked, action required", () => {
+    const e = entry({
+      status: "past_due",
+      accessState: "granted",
+      dunningArmedAt: "2026-09-10T00:00:00.000Z",
+    });
+    expect(isSubscriberRevoked(e, NOW)).toBe(false);
+    expect(isSubscriberActionRequired(e, NOW)).toBe(true);
+  });
+
+  it("in-grace canceled — not yet revoked, but action IS required (§ 9 SEC-09)", () => {
+    const e = entry({
+      status: "canceled",
+      accessState: "granted",
+      dunningArmedAt: "2026-09-10T00:00:00.000Z",
+      accessRevokesAt: "2026-09-24T00:00:00.000Z", // in the future relative to NOW
+    });
+    expect(isSubscriberRevoked(e, NOW)).toBe(false);
+    expect(isSubscriberActionRequired(e, NOW)).toBe(true);
+  });
+
+  it("expired canceled — revoked, no further action predicate (already gone)", () => {
+    const e = entry({
+      status: "canceled",
+      accessState: "revoked",
+      dunningArmedAt: "2026-08-01T00:00:00.000Z",
+      accessRevokesAt: "2026-08-15T00:00:00.000Z", // in the past relative to NOW
+    });
+    expect(isSubscriberRevoked(e, NOW)).toBe(true);
+    expect(isSubscriberActionRequired(e, NOW)).toBe(false);
+  });
+
+  it("accessRevokesAt exactly at `now` is revoked (>=, not >)", () => {
+    const revokesAt = "2026-09-18T00:00:00.000Z";
+    const e = entry({
+      status: "canceled",
+      accessState: "granted",
+      accessRevokesAt: revokesAt,
+    });
+    expect(isSubscriberRevoked(e, Date.parse(revokesAt))).toBe(true);
+  });
+});