create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/services/__tests__/deliverable-fulfillment.test.ts

@@ -0,0 +1,523 @@
+/**
+ * @file deliverable-fulfillment.test.ts
+ * @description Unit tests for the deliverable-fulfillment service (#3961
+ * D3/D4/D5/D7).
+ *
+ * External dependency boundaries mocked:
+ *   - @working-theory/database (via moduleNameMapper → prisma-client.js mock; prisma singleton via __mocks__/prisma.ts)
+ *   - @working-theory/email sendDeliverableEmail
+ *   - @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 mockSendDeliverableEmail = jest.fn();
+jest.mock("@working-theory/email", () => ({
+  sendDeliverableEmail: (...args: unknown[]) =>
+    mockSendDeliverableEmail(...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 {
+  fulfillDeliverable,
+  type FulfillDeliverableInput,
+} from "../deliverable-fulfillment";
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+const en = (s: string) => ({ en: s });
+
+const SITE_ID = "site-abc";
+const SESSION_ID = "flsess_00000000-0000-7000-8000-0000000000c1";
+const LEAD_ID = "lead_00000000-0000-7000-8000-0000000000e1";
+const GRANT_ID = "dgrant_00000000-0000-7000-8000-0000000000g1";
+
+function deliverablesBlock() {
+  return {
+    assets: [
+      { segment: "small", assetKey: "guide-small" },
+      { segment: "large", assetKey: "guide-large" },
+      { assetKey: "guide-default" },
+    ],
+    copy: {
+      subject: en("Here's your guide"),
+      body: en("Thanks — your download is attached."),
+    },
+  };
+}
+
+function baseConfigSnapshot() {
+  return {
+    slug: "get-a-quote",
+    defaultLocale: "en",
+    steps: [],
+    deliverables: deliverablesBlock(),
+  };
+}
+
+function baseInput(
+  overrides: Partial<FulfillDeliverableInput> = {},
+): FulfillDeliverableInput {
+  return {
+    siteId: SITE_ID,
+    flowSlug: "get-a-quote",
+    configSnapshot: baseConfigSnapshot(),
+    segment: "small",
+    leadId: LEAD_ID,
+    sessionId: SESSION_ID,
+    email: "lead@example.com",
+    locale: "en",
+    ...overrides,
+  };
+}
+
+describe("fulfillDeliverable", () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    process.env = {
+      ...originalEnv,
+      AILK_PUBLIC_API_URL: "https://api.example.com",
+      AILK_DELIVERABLE_EMAIL_FROM: "deliverable-default@example.com",
+    };
+    mockSendDeliverableEmail.mockResolvedValue({
+      ok: true,
+      messageId: "msg-test",
+    });
+    (prisma.deliverableAsset.findUnique as jest.Mock).mockResolvedValue({
+      id: "dasset_00000000-0000-7000-8000-0000000000a1",
+      siteId: SITE_ID,
+      key: "guide-small",
+    });
+    (prisma.deliverableGrant.create as jest.Mock).mockResolvedValue({
+      id: GRANT_ID,
+    });
+    (prisma.deliverableGrant.update as jest.Mock).mockResolvedValue({
+      id: GRANT_ID,
+    });
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  // ── D3 — segment → entry resolution ──────────────────────────────────────
+
+  it("resolves the segment-matched entry and mints a grant for its asset", async () => {
+    await fulfillDeliverable(baseInput({ segment: "small" }));
+
+    expect(prisma.deliverableAsset.findUnique).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { siteId_key: { siteId: SITE_ID, key: "guide-small" } },
+      }),
+    );
+  });
+
+  it("resolves the OTHER segment's entry when segment differs (two-segment divergence, AC1)", async () => {
+    (prisma.deliverableAsset.findUnique as jest.Mock).mockResolvedValue({
+      id: "dasset_00000000-0000-7000-8000-0000000000a2",
+      siteId: SITE_ID,
+      key: "guide-large",
+    });
+
+    await fulfillDeliverable(baseInput({ segment: "large" }));
+
+    expect(prisma.deliverableAsset.findUnique).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { siteId_key: { siteId: SITE_ID, key: "guide-large" } },
+      }),
+    );
+  });
+
+  it("falls back to the default entry when segment is undefined (N=1 degenerate case)", async () => {
+    await fulfillDeliverable(baseInput({ segment: undefined }));
+
+    expect(prisma.deliverableAsset.findUnique).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { siteId_key: { siteId: SITE_ID, key: "guide-default" } },
+      }),
+    );
+  });
+
+  it("falls back to the default entry when segment is derived but unmapped", async () => {
+    await fulfillDeliverable(baseInput({ segment: "unmapped-segment" }));
+
+    expect(prisma.deliverableAsset.findUnique).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { siteId_key: { siteId: SITE_ID, key: "guide-default" } },
+      }),
+    );
+  });
+
+  it("skips (no grant, no send) when no entry matches and there is no default", async () => {
+    await fulfillDeliverable(
+      baseInput({
+        segment: "unmapped-segment",
+        configSnapshot: {
+          ...baseConfigSnapshot(),
+          deliverables: {
+            assets: [{ segment: "small", assetKey: "guide-small" }],
+            copy: deliverablesBlock().copy,
+          },
+        },
+      }),
+    );
+
+    expect(prisma.deliverableAsset.findUnique).not.toHaveBeenCalled();
+    expect(prisma.deliverableGrant.create).not.toHaveBeenCalled();
+    expect(mockSendDeliverableEmail).not.toHaveBeenCalled();
+    // AC4: no_entry is a pre-mint outcome — no grant exists to stamp.
+    expect(prisma.deliverableGrant.update).not.toHaveBeenCalled();
+    expect(mockLoggerInfo).toHaveBeenCalledWith(
+      expect.objectContaining({
+        siteId: SITE_ID,
+        flowSlug: "get-a-quote",
+        sessionId: SESSION_ID,
+      }),
+      expect.any(String),
+    );
+  });
+
+  // ── D3 — missing asset row ────────────────────────────────────────────────
+
+  it("skips (no grant, no send) when the config-referenced asset row is missing", async () => {
+    (prisma.deliverableAsset.findUnique as jest.Mock).mockResolvedValue(null);
+
+    await fulfillDeliverable(baseInput());
+
+    expect(prisma.deliverableGrant.create).not.toHaveBeenCalled();
+    expect(mockSendDeliverableEmail).not.toHaveBeenCalled();
+    // AC4: asset_missing is a pre-mint outcome — no grant exists to stamp.
+    expect(prisma.deliverableGrant.update).not.toHaveBeenCalled();
+    expect(mockLoggerInfo).toHaveBeenCalled();
+  });
+
+  // ── FEAT-074 U4b (#4718) D4 — the playbook: virtual asset ────────────────
+
+  function playbookConfigSnapshot() {
+    return {
+      slug: "targeting-maturity",
+      defaultLocale: "en",
+      steps: [],
+      deliverables: {
+        assets: [{ assetKey: "playbook:targeting-maturity" }],
+        copy: {
+          subject: en("Your Playbook is ready"),
+          body: en("Your Playbook is ready to download."),
+        },
+      },
+    };
+  }
+
+  it("skips the DeliverableAsset lookup and mints the grant with assetId = entry.assetKey when a PlaybookInstance exists (AC-3)", async () => {
+    (prisma.playbookInstance.findFirst as jest.Mock).mockResolvedValue({
+      id: "pbk_00000000-0000-7000-8000-0000000000p1",
+    });
+
+    await fulfillDeliverable(
+      baseInput({ segment: undefined, configSnapshot: playbookConfigSnapshot() }),
+    );
+
+    expect(prisma.playbookInstance.findFirst).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { siteId: SITE_ID, leadId: LEAD_ID, experimentKey: "targeting-maturity" },
+      }),
+    );
+    expect(prisma.deliverableAsset.findUnique).not.toHaveBeenCalled();
+    // AC-3: EXACTLY one grant -- toHaveBeenCalledTimes, not merely
+    // toHaveBeenCalledWith (which would pass even on a second, unasserted
+    // call).
+    expect(prisma.deliverableGrant.create).toHaveBeenCalledTimes(1);
+    expect(prisma.deliverableGrant.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          siteId: SITE_ID,
+          assetId: "playbook:targeting-maturity",
+          leadId: LEAD_ID,
+          sessionId: SESSION_ID,
+        }),
+      }),
+    );
+    // AC-3: the send-and-stamp tail reaches sendStatus = sent WITH the
+    // /v1/deliverables/<grantId> link -- asserted on the actual email call,
+    // not merely "an email was sent."
+    expect(mockSendDeliverableEmail).toHaveBeenCalledTimes(1);
+    expect(mockSendDeliverableEmail).toHaveBeenCalledWith(
+      expect.objectContaining({
+        downloadLink: `https://api.example.com/v1/deliverables/${GRANT_ID}`,
+      }),
+    );
+    expect(prisma.deliverableGrant.update).toHaveBeenCalledWith({
+      where: { id: GRANT_ID },
+      data: { sendStatus: "sent", sendAt: expect.any(Date) },
+    });
+  });
+
+  it("logs playbook_missing, mints no grant, and sends no email when the lead has no PlaybookInstance (AC-4)", async () => {
+    (prisma.playbookInstance.findFirst as jest.Mock).mockResolvedValue(null);
+
+    await fulfillDeliverable(
+      baseInput({ segment: undefined, configSnapshot: playbookConfigSnapshot() }),
+    );
+
+    expect(prisma.deliverableGrant.create).not.toHaveBeenCalled();
+    expect(mockSendDeliverableEmail).not.toHaveBeenCalled();
+    // playbook_missing is a pre-mint outcome — no grant exists to stamp
+    // (the same posture as asset_missing).
+    expect(prisma.deliverableGrant.update).not.toHaveBeenCalled();
+    expect(mockLoggerInfo).toHaveBeenCalledWith(
+      expect.objectContaining({
+        siteId: SITE_ID,
+        sessionId: SESSION_ID,
+        outcome: "playbook_missing",
+      }),
+      expect.any(String),
+    );
+  });
+
+  it("an ordinary (non-playbook:) assetKey never queries playbookInstance (no false-positive branch)", async () => {
+    await fulfillDeliverable(baseInput());
+
+    expect(prisma.playbookInstance.findFirst).not.toHaveBeenCalled();
+    expect(prisma.deliverableAsset.findUnique).toHaveBeenCalled();
+  });
+
+  // ── D5 — grant mint ───────────────────────────────────────────────────────
+
+  it("mints the grant with assetId/leadId/sessionId", async () => {
+    await fulfillDeliverable(baseInput());
+
+    expect(prisma.deliverableGrant.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          siteId: SITE_ID,
+          assetId: "dasset_00000000-0000-7000-8000-0000000000a1",
+          leadId: LEAD_ID,
+          sessionId: SESSION_ID,
+        }),
+      }),
+    );
+  });
+
+  // ── AC5 — mint-before-send is preserved (regression floor) ──────────────
+
+  it("still calls deliverableGrant.create before sendDeliverableEmail (AC5)", async () => {
+    await fulfillDeliverable(baseInput());
+
+    const createOrder = (prisma.deliverableGrant.create as jest.Mock).mock
+      .invocationCallOrder[0];
+    const sendOrder = mockSendDeliverableEmail.mock.invocationCallOrder[0];
+    expect(createOrder).toBeLessThan(sendOrder);
+  });
+
+  // ── AC4 — the three post-mint outcomes all stamp ─────────────────────────
+
+  it("stamps sendStatus: 'sent' + a non-null sendAt on a successful send", async () => {
+    await fulfillDeliverable(baseInput());
+
+    expect(prisma.deliverableGrant.update).toHaveBeenCalledWith({
+      where: { id: GRANT_ID },
+      data: { sendStatus: "sent", sendAt: expect.any(Date) },
+    });
+  });
+
+  // ── AC2 — link = base + grant id, no PII ────────────────────────────────
+
+  it("builds the download link from AILK_PUBLIC_API_URL + the grant id, with no PII", async () => {
+    await fulfillDeliverable(baseInput({ email: "lead-with-pii@example.com" }));
+
+    const [call] = mockSendDeliverableEmail.mock.calls;
+    expect(call[0].downloadLink).toBe(
+      `https://api.example.com/v1/deliverables/${GRANT_ID}`,
+    );
+    expect(call[0].downloadLink).not.toContain("lead-with-pii@example.com");
+    expect(call[0].downloadLink).not.toContain(LEAD_ID);
+  });
+
+  it("sends to the lead's email (recipient)", async () => {
+    await fulfillDeliverable(baseInput());
+
+    const [call] = mockSendDeliverableEmail.mock.calls;
+    expect(call[0].to).toBe("lead@example.com");
+  });
+
+  // ── D7 — copy resolution at locale, with defaultLocale fallback ────────────
+
+  it("resolves copy at the completion request's locale", async () => {
+    const configSnapshot = {
+      ...baseConfigSnapshot(),
+      deliverables: {
+        assets: [{ assetKey: "guide-default" }],
+        copy: {
+          subject: { en: "Here's your guide", "pt-BR": "Aqui está seu guia" },
+          body: {
+            en: "Thanks — your download is attached.",
+            "pt-BR": "Obrigado — seu download está anexado.",
+          },
+        },
+      },
+    };
+
+    await fulfillDeliverable(
+      baseInput({ configSnapshot, locale: "pt-BR", segment: undefined }),
+    );
+
+    const [call] = mockSendDeliverableEmail.mock.calls;
+    expect(call[0].subject).toBe("Aqui está seu guia");
+    expect(call[0].body).toBe("Obrigado — seu download está anexado.");
+  });
+
+  it("falls back to defaultLocale when the completion locale has no copy key", async () => {
+    const configSnapshot = {
+      ...baseConfigSnapshot(),
+      deliverables: {
+        assets: [{ assetKey: "guide-default" }],
+        copy: {
+          subject: { en: "Here's your guide" },
+          body: { en: "Thanks — your download is attached." },
+        },
+      },
+    };
+
+    await fulfillDeliverable(
+      baseInput({ configSnapshot, locale: "fr", segment: undefined }),
+    );
+
+    const [call] = mockSendDeliverableEmail.mock.calls;
+    expect(call[0].subject).toBe("Here's your guide");
+  });
+
+  it("resolves cta when present", async () => {
+    const configSnapshot = {
+      ...baseConfigSnapshot(),
+      deliverables: {
+        assets: [{ assetKey: "guide-default" }],
+        copy: {
+          subject: en("Here's your guide"),
+          body: en("Thanks — your download is attached."),
+          cta: en("Download now"),
+        },
+      },
+    };
+
+    await fulfillDeliverable(baseInput({ configSnapshot, segment: undefined }));
+
+    const [call] = mockSendDeliverableEmail.mock.calls;
+    expect(call[0].cta).toBe("Download now");
+  });
+
+  // ── sender-env fallback chain ────────────────────────────────────────────
+
+  it("uses AILK_DELIVERABLE_EMAIL_FROM when set", async () => {
+    process.env["AILK_DELIVERABLE_EMAIL_FROM"] = "deliverable@example.com";
+
+    await fulfillDeliverable(baseInput());
+
+    const [call] = mockSendDeliverableEmail.mock.calls;
+    expect(call[0].fromAddress).toBe("deliverable@example.com");
+  });
+
+  it("falls back to AILK_LEAD_NOTIFICATION_FROM when AILK_DELIVERABLE_EMAIL_FROM is unset", async () => {
+    delete process.env["AILK_DELIVERABLE_EMAIL_FROM"];
+    process.env["AILK_LEAD_NOTIFICATION_FROM"] = "owner-noreply@example.com";
+
+    await fulfillDeliverable(baseInput());
+
+    const [call] = mockSendDeliverableEmail.mock.calls;
+    expect(call[0].fromAddress).toBe("owner-noreply@example.com");
+  });
+
+  it("skips the send (grant NOT wasted) when neither from-address env is set", async () => {
+    delete process.env["AILK_DELIVERABLE_EMAIL_FROM"];
+    delete process.env["AILK_LEAD_NOTIFICATION_FROM"];
+
+    await fulfillDeliverable(baseInput());
+
+    expect(prisma.deliverableGrant.create).toHaveBeenCalled();
+    expect(mockSendDeliverableEmail).not.toHaveBeenCalled();
+    expect(mockLoggerInfo).toHaveBeenCalled();
+    // AC4: sender_unconfigured is a post-mint outcome — it stamps too.
+    expect(prisma.deliverableGrant.update).toHaveBeenCalledWith({
+      where: { id: GRANT_ID },
+      data: { sendStatus: "sender_unconfigured", sendAt: expect.any(Date) },
+    });
+  });
+
+  // ── D4 — no deliverables block: opt-in per flow ─────────────────────────
+
+  it("does nothing when configSnapshot.deliverables is absent (opt-in per flow)", async () => {
+    await fulfillDeliverable(
+      baseInput({
+        configSnapshot: { ...baseConfigSnapshot(), deliverables: undefined },
+      }),
+    );
+
+    expect(prisma.deliverableAsset.findUnique).not.toHaveBeenCalled();
+    expect(prisma.deliverableGrant.create).not.toHaveBeenCalled();
+    expect(mockSendDeliverableEmail).not.toHaveBeenCalled();
+  });
+
+  // ── PII-safe logging ─────────────────────────────────────────────────────
+
+  it("never logs email or copy values", async () => {
+    delete process.env["AILK_DELIVERABLE_EMAIL_FROM"];
+    delete process.env["AILK_LEAD_NOTIFICATION_FROM"];
+
+    await fulfillDeliverable(baseInput({ email: "sentinel-pii@example.com" }));
+
+    const allLogCalls = [
+      ...mockLoggerInfo.mock.calls,
+      ...mockLoggerWarn.mock.calls,
+      ...mockLoggerError.mock.calls,
+    ];
+    for (const call of allLogCalls) {
+      expect(JSON.stringify(call)).not.toContain("sentinel-pii@example.com");
+    }
+  });
+
+  // ── Email send failure — logged, not thrown ──────────────────────────────
+
+  it("logs (does not throw) when the email send fails", async () => {
+    mockSendDeliverableEmail.mockResolvedValue({
+      ok: false,
+      error: { kind: "send_failed", message: "Resend down" },
+    });
+
+    await expect(fulfillDeliverable(baseInput())).resolves.toBeUndefined();
+    expect(mockLoggerInfo).toHaveBeenCalled();
+    // AC4: send_failed is a post-mint outcome — it stamps too.
+    expect(prisma.deliverableGrant.update).toHaveBeenCalledWith({
+      where: { id: GRANT_ID },
+      data: { sendStatus: "send_failed", sendAt: expect.any(Date) },
+    });
+  });
+
+  // ── #3998 D5 — a stamp failure is caught, never escalated ────────────────
+
+  it("does not throw when the stamp write itself rejects", async () => {
+    (prisma.deliverableGrant.update as jest.Mock).mockRejectedValue(
+      new Error("connection reset"),
+    );
+
+    await expect(fulfillDeliverable(baseInput())).resolves.toBeUndefined();
+    expect(mockSendDeliverableEmail).toHaveBeenCalled();
+    expect(mockLoggerWarn).toHaveBeenCalledWith(
+      expect.objectContaining({ grantId: GRANT_ID, outcome: "sent" }),
+      expect.any(String),
+    );
+  });
+});