create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/services/__tests__/abandon-email.test.ts

@@ -0,0 +1,489 @@
+/**
+ * @file abandon-email.test.ts
+ * @description Unit tests for the abandon-email sweep service (#3962 D4).
+ *
+ * External dependency boundaries mocked:
+ *   - @working-theory/database (via moduleNameMapper → prisma-client.js mock; prisma singleton via __mocks__/prisma.ts)
+ *   - @working-theory/email sendAbandonEmail
+ *   - @working-theory/observability logger
+ */
+
+// 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 mockSendAbandonEmail = jest.fn();
+jest.mock("@working-theory/email", () => ({
+  sendAbandonEmail: (...args: unknown[]) => mockSendAbandonEmail(...args),
+}));
+
+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 { prisma } from "../../lib/prisma.js";
+import { runAbandonEmailSweep } from "../abandon-email";
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+const en = (s: string) => ({ en: s });
+
+const SITE_ID = "site-abc";
+const DEFINITION_ID = "flow_00000000-0000-7000-8000-0000000000d1";
+const SESSION_ID = "flsess_00000000-0000-7000-8000-0000000000c1";
+const NOW = new Date("2026-08-11T12:00:00.000Z");
+
+function flowDefRow(overrides: Partial<{ abandonEmail: unknown }> = {}) {
+  return {
+    id: DEFINITION_ID,
+    siteId: SITE_ID,
+    slug: "get-a-quote",
+    config: {
+      slug: "get-a-quote",
+      defaultLocale: "en",
+      steps: [
+        {
+          key: "contact",
+          type: "field",
+          copy: { title: en("Let's get started") },
+          fields: [
+            {
+              name: "email",
+              inputType: "email",
+              required: true,
+              mapsTo: "email",
+              copy: { label: en("Email") },
+            },
+          ],
+        },
+      ],
+      ...("abandonEmail" in overrides
+        ? { abandonEmail: overrides.abandonEmail }
+        : {
+            abandonEmail: {
+              mode: "enabled",
+              delayMinutes: 30,
+              copy: {
+                subject: en("Still interested?"),
+                body: en("Come back!"),
+              },
+            },
+          }),
+    },
+  };
+}
+
+function sessionRow(overrides: Partial<Record<string, unknown>> = {}) {
+  return {
+    id: SESSION_ID,
+    siteId: SITE_ID,
+    flowSlug: "get-a-quote",
+    email: "lead@example.com",
+    locale: null,
+    ...overrides,
+  };
+}
+
+describe("runAbandonEmailSweep", () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    process.env = { ...originalEnv };
+    process.env.DATABASE_URL = "postgres://stub";
+    mockSendAbandonEmail.mockResolvedValue({
+      ok: true,
+      messageId: "msg-abandon",
+    });
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  // ── D5 — DB required ────────────────────────────────────────────────────
+
+  it("returns flows_not_configured when DATABASE_URL is unset", async () => {
+    delete process.env.DATABASE_URL;
+    const result = await runAbandonEmailSweep();
+    expect(result).toEqual({
+      ok: false,
+      error: { kind: "flows_not_configured", message: expect.any(String) },
+    });
+    expect(prisma.flowDefinition.findMany).not.toHaveBeenCalled();
+  });
+
+  // ── AC2 — block absent means never selected ─────────────────────────────
+
+  it("never selects a session on a flow with no abandonEmail block", async () => {
+    (prisma.flowDefinition.findMany as jest.Mock).mockResolvedValue([
+      flowDefRow({ abandonEmail: undefined }),
+    ]);
+
+    const result = await runAbandonEmailSweep({ now: NOW });
+
+    expect(result).toEqual({
+      ok: true,
+      summary: {
+        scanned: 0,
+        selected: 0,
+        sent: 0,
+        dark: 0,
+        failed: 0,
+        skipped: 0,
+      },
+    });
+    expect(prisma.flowSession.findMany).not.toHaveBeenCalled();
+  });
+
+  // ── AC1 — selection: partial-not-completed, within-window, no-block, ───
+  // ── already-stamped all excluded by the query itself ────────────────────
+
+  it("queries for email set, completedAt null, abandonEmailStatus null, and the delay-window cutoff", async () => {
+    process.env.AILK_ABANDON_EMAIL_FROM = "noreply@example.com";
+    (prisma.flowDefinition.findMany as jest.Mock).mockResolvedValue([
+      flowDefRow(),
+    ]);
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue([]);
+
+    await runAbandonEmailSweep({ now: NOW });
+
+    expect(prisma.flowSession.findMany).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: {
+          flowId: DEFINITION_ID,
+          email: { not: null },
+          completedAt: null,
+          abandonEmailStatus: null,
+          updatedAt: { lte: new Date(NOW.getTime() - 30 * 60_000) },
+        },
+      }),
+    );
+  });
+
+  // ── AC2 — dark mode: selected + audited, zero send calls ────────────────
+
+  it("dark mode stamps abandonEmailStatus:'dark' and never calls sendAbandonEmail", async () => {
+    (prisma.flowDefinition.findMany as jest.Mock).mockResolvedValue([
+      flowDefRow({
+        abandonEmail: {
+          mode: "dark",
+          delayMinutes: 30,
+          copy: { subject: en("Still interested?"), body: en("Come back!") },
+        },
+      }),
+    ]);
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue([
+      sessionRow(),
+    ]);
+    (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+    const result = await runAbandonEmailSweep({ now: NOW });
+
+    expect(mockSendAbandonEmail).not.toHaveBeenCalled();
+    expect(prisma.flowSession.update).toHaveBeenCalledWith({
+      where: { id: SESSION_ID },
+      data: { abandonEmailStatus: "dark", abandonEmailAt: NOW },
+    });
+    expect(result).toMatchObject({
+      ok: true,
+      summary: {
+        scanned: 1,
+        selected: 1,
+        dark: 1,
+        sent: 0,
+        failed: 0,
+        skipped: 0,
+      },
+    });
+  });
+
+  // ── AC2 — enabled mode: selected + sent ──────────────────────────────────
+
+  it("enabled mode calls sendAbandonEmail and stamps abandonEmailStatus:'sent'", async () => {
+    process.env.AILK_ABANDON_EMAIL_FROM = "noreply@example.com";
+    (prisma.flowDefinition.findMany as jest.Mock).mockResolvedValue([
+      flowDefRow(),
+    ]);
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue([
+      sessionRow(),
+    ]);
+    (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+    const result = await runAbandonEmailSweep({ now: NOW });
+
+    expect(mockSendAbandonEmail).toHaveBeenCalledTimes(1);
+    const [call] = mockSendAbandonEmail.mock.calls;
+    expect(call[0]).toMatchObject({
+      to: "lead@example.com",
+      fromAddress: "noreply@example.com",
+      subject: "Still interested?",
+      body: "Come back!",
+    });
+    expect(prisma.flowSession.update).toHaveBeenCalledWith({
+      where: { id: SESSION_ID },
+      data: { abandonEmailStatus: "sent", abandonEmailAt: NOW },
+    });
+    expect(result).toMatchObject({
+      ok: true,
+      summary: {
+        scanned: 1,
+        selected: 1,
+        sent: 1,
+        dark: 0,
+        failed: 0,
+        skipped: 0,
+      },
+    });
+  });
+
+  it("stamps abandonEmailStatus:'failed' when sendAbandonEmail returns ok:false", async () => {
+    process.env.AILK_ABANDON_EMAIL_FROM = "noreply@example.com";
+    mockSendAbandonEmail.mockResolvedValue({
+      ok: false,
+      error: { kind: "send_failed", message: "boom" },
+    });
+    (prisma.flowDefinition.findMany as jest.Mock).mockResolvedValue([
+      flowDefRow(),
+    ]);
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue([
+      sessionRow(),
+    ]);
+    (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+    const result = await runAbandonEmailSweep({ now: NOW });
+
+    expect(prisma.flowSession.update).toHaveBeenCalledWith({
+      where: { id: SESSION_ID },
+      data: { abandonEmailStatus: "failed", abandonEmailAt: NOW },
+    });
+    expect(result).toMatchObject({
+      ok: true,
+      summary: { selected: 1, sent: 0, failed: 1, skipped: 0 },
+    });
+  });
+
+  // ── From-address guard ───────────────────────────────────────────────────
+
+  it("leaves an enabled candidate UNSTAMPED (skipped, not failed) when no from-address is configured", async () => {
+    // Neither AILK_ABANDON_EMAIL_FROM nor AILK_LEAD_NOTIFICATION_FROM set.
+    (prisma.flowDefinition.findMany as jest.Mock).mockResolvedValue([
+      flowDefRow(),
+    ]);
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue([
+      sessionRow(),
+    ]);
+
+    const result = await runAbandonEmailSweep({ now: NOW });
+
+    expect(mockSendAbandonEmail).not.toHaveBeenCalled();
+    expect(prisma.flowSession.update).not.toHaveBeenCalled();
+    expect(result).toMatchObject({
+      ok: true,
+      summary: { selected: 1, sent: 0, dark: 0, failed: 0, skipped: 1 },
+    });
+  });
+
+  it("falls back to AILK_LEAD_NOTIFICATION_FROM when AILK_ABANDON_EMAIL_FROM is unset", async () => {
+    process.env.AILK_LEAD_NOTIFICATION_FROM = "owner-noreply@example.com";
+    (prisma.flowDefinition.findMany as jest.Mock).mockResolvedValue([
+      flowDefRow(),
+    ]);
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue([
+      sessionRow(),
+    ]);
+    (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+    await runAbandonEmailSweep({ now: NOW });
+
+    const [call] = mockSendAbandonEmail.mock.calls;
+    expect(call[0].fromAddress).toBe("owner-noreply@example.com");
+  });
+
+  // ── AC3 — locale resolution ──────────────────────────────────────────────
+
+  it("resolves copy at the session's persisted locale", async () => {
+    process.env.AILK_ABANDON_EMAIL_FROM = "noreply@example.com";
+    (prisma.flowDefinition.findMany as jest.Mock).mockResolvedValue([
+      flowDefRow({
+        abandonEmail: {
+          mode: "enabled",
+          delayMinutes: 30,
+          copy: {
+            subject: { en: "Still interested?", "pt-BR": "Ainda interessado?" },
+            body: { en: "Come back!", "pt-BR": "Volte!" },
+          },
+        },
+      }),
+    ]);
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue([
+      sessionRow({ locale: "pt-BR" }),
+    ]);
+    (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+    await runAbandonEmailSweep({ now: NOW });
+
+    const [call] = mockSendAbandonEmail.mock.calls;
+    expect(call[0].subject).toBe("Ainda interessado?");
+    expect(call[0].body).toBe("Volte!");
+  });
+
+  it("falls back to the config's defaultLocale when the session's locale has no copy key", async () => {
+    process.env.AILK_ABANDON_EMAIL_FROM = "noreply@example.com";
+    (prisma.flowDefinition.findMany as jest.Mock).mockResolvedValue([
+      flowDefRow({
+        abandonEmail: {
+          mode: "enabled",
+          delayMinutes: 30,
+          copy: { subject: en("Still interested?"), body: en("Come back!") },
+        },
+      }),
+    ]);
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue([
+      sessionRow({ locale: "es" }), // no "es" key in copy
+    ]);
+    (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+    await runAbandonEmailSweep({ now: NOW });
+
+    const [call] = mockSendAbandonEmail.mock.calls;
+    expect(call[0].subject).toBe("Still interested?");
+  });
+
+  it("falls back to the config's defaultLocale when the session has no persisted locale (pre-migration rows)", async () => {
+    process.env.AILK_ABANDON_EMAIL_FROM = "noreply@example.com";
+    (prisma.flowDefinition.findMany as jest.Mock).mockResolvedValue([
+      flowDefRow(),
+    ]);
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue([
+      sessionRow({ locale: null }),
+    ]);
+    (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+    await runAbandonEmailSweep({ now: NOW });
+
+    const [call] = mockSendAbandonEmail.mock.calls;
+    expect(call[0].subject).toBe("Still interested?");
+  });
+
+  // ── AC4 — no PII in the resume link ──────────────────────────────────────
+
+  it("builds the resume link as exactly resumeUrl + '?fs=' + sessionId — no PII", async () => {
+    process.env.AILK_ABANDON_EMAIL_FROM = "noreply@example.com";
+    (prisma.flowDefinition.findMany as jest.Mock).mockResolvedValue([
+      flowDefRow({
+        abandonEmail: {
+          mode: "enabled",
+          delayMinutes: 30,
+          copy: { subject: en("Still interested?"), body: en("Come back!") },
+          resumeUrl: "https://example.com/get-a-quote",
+        },
+      }),
+    ]);
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue([
+      sessionRow({ email: "lead-pii@example.com" }),
+    ]);
+    (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+    await runAbandonEmailSweep({ now: NOW });
+
+    const [call] = mockSendAbandonEmail.mock.calls;
+    expect(call[0].resumeLink).toBe(
+      `https://example.com/get-a-quote?fs=${SESSION_ID}`,
+    );
+    expect(call[0].resumeLink).not.toContain("lead-pii@example.com");
+  });
+
+  it("passes no resumeLink when the config declares no resumeUrl", async () => {
+    process.env.AILK_ABANDON_EMAIL_FROM = "noreply@example.com";
+    (prisma.flowDefinition.findMany as jest.Mock).mockResolvedValue([
+      flowDefRow(),
+    ]);
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue([
+      sessionRow(),
+    ]);
+    (prisma.flowSession.update as jest.Mock).mockResolvedValue({});
+
+    await runAbandonEmailSweep({ now: NOW });
+
+    const [call] = mockSendAbandonEmail.mock.calls;
+    expect(call[0].resumeLink).toBeUndefined();
+  });
+
+  // ── Optional siteId scoping ───────────────────────────────────────────────
+
+  it("scopes flow definitions by opts.siteId when provided", async () => {
+    (prisma.flowDefinition.findMany as jest.Mock).mockResolvedValue([]);
+
+    await runAbandonEmailSweep({ now: NOW, siteId: "site-scoped" });
+
+    expect(prisma.flowDefinition.findMany).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { siteId: "site-scoped" } }),
+    );
+  });
+
+  // ── Malformed stored config — surfaced, not swallowed ───────────────────
+
+  it("logs a warning and skips a flow whose stored config fails schema validation, without touching other flows", async () => {
+    const goodDef = flowDefRow();
+    const badDef = {
+      id: "flow_bad",
+      siteId: SITE_ID,
+      slug: "broken-flow",
+      config: { slug: "broken-flow" /* missing defaultLocale + steps */ },
+    };
+    (prisma.flowDefinition.findMany as jest.Mock).mockResolvedValue([
+      badDef,
+      goodDef,
+    ]);
+    (prisma.flowSession.findMany as jest.Mock).mockResolvedValue([]);
+
+    const result = await runAbandonEmailSweep({ now: NOW });
+
+    expect(mockLoggerWarn).toHaveBeenCalledWith(
+      expect.objectContaining({ siteId: SITE_ID, flowSlug: "broken-flow" }),
+      expect.stringContaining("failed schema validation"),
+    );
+    // The malformed flow never reaches the session query; the good one does.
+    expect(prisma.flowSession.findMany).toHaveBeenCalledTimes(1);
+    expect(prisma.flowSession.findMany).toHaveBeenCalledWith(
+      expect.objectContaining({ where: expect.objectContaining({ flowId: DEFINITION_ID }) }),
+    );
+    expect(result).toEqual({
+      ok: true,
+      summary: { scanned: 0, selected: 0, sent: 0, dark: 0, failed: 0, skipped: 0 },
+    });
+  });
+
+  // ── Mid-sweep failure — degrades to a structured error, never an ────────
+  // ── unhandled rejection (code-review finding on #3962's acceptance PR) ──
+
+  it("returns a structured unexpected_error result when a DB call throws mid-sweep, logging the partial summary", async () => {
+    process.env.AILK_ABANDON_EMAIL_FROM = "noreply@example.com";
+    (prisma.flowDefinition.findMany as jest.Mock).mockResolvedValue([flowDefRow()]);
+    (prisma.flowSession.findMany as jest.Mock).mockRejectedValue(
+      new Error("connection reset"),
+    );
+
+    const result = await runAbandonEmailSweep({ now: NOW });
+
+    expect(result).toEqual({
+      ok: false,
+      error: { kind: "unexpected_error", message: "connection reset" },
+    });
+    expect(mockLoggerError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        err: "connection reset",
+        partialSummary: expect.objectContaining({ scanned: 0, selected: 0 }),
+      }),
+      expect.stringContaining("sweep failed mid-run"),
+    );
+  });
+});