create-ailk 0.14.0 → 0.16.0

package/templates/apps/api/src/services/__tests__/lead-routing.test.ts

@@ -33,8 +33,12 @@ import * as fs from "fs/promises";
 import * as os from "os";
 import * as path from "path";
 
+import { logger } from "@working-theory/observability";
+
+import { MOCK_PERSON_ID } from "../../lib/__mocks__/prisma.js";
 import { prisma } from "../../lib/prisma.js";
 import { routeLead } from "../lead-routing";
+import * as personService from "../person";
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 const sourceMeta = {
@@ -747,3 +751,491 @@ describe("#6730 — routeLead delivery modes", () => {
     });
   });
 });
+
+// ── #7869 — the Idempotency-Key on submit (spec D3–D5, D10 cases 9–14) ──────
+//
+// Cases 9–13 run on `inbox` delivery (DATABASE_URL set), where the key is
+// honoured; case 14 drops DATABASE_URL to prove a non-inbox delivery ignores
+// it. A keyed create that loses the race throws P2002 and is answered from a
+// re-read of the winner.
+describe("#7869 — routeLead with an idempotency key", () => {
+  const KEY = "fixture-retry-0000-0000-0001";
+  const WINNER_ID = "lead_00000000-0000-7000-8000-00000000f001";
+  const ENV_KEYS = [
+    "DATABASE_URL",
+    "NODE_ENV",
+    "AILK_INBOX_FALLBACK_DIR",
+    "LEAD_CAPTURE_FILE",
+    "AILK_LEAD_NOTIFICATION_TO",
+    "AILK_LEAD_NOTIFICATION_FROM",
+  ] as const;
+  let saved: Partial<Record<(typeof ENV_KEYS)[number], string | undefined>>;
+  let tmpDir: string;
+
+  const p2002 = () =>
+    Object.assign(
+      new Error(
+        "Unique constraint failed on the fields: (`workspace_id`,`idempotency_key`)",
+      ),
+      { code: "P2002" },
+    );
+  const keyWhere = (workspaceId: string) => ({
+    where: { workspaceId_idempotencyKey: { workspaceId, idempotencyKey: KEY } },
+    select: { id: true, email: true, source: true, payload: true },
+  });
+  const createData = () =>
+    jest.mocked(prisma.lead.create).mock.calls[0]?.[0].data as Record<
+      string,
+      unknown
+    >;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+    saved = {};
+    for (const k of ENV_KEYS) saved[k] = process.env[k];
+    for (const k of ENV_KEYS) delete process.env[k];
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "ailk-idem-test-"));
+    process.env.AILK_INBOX_FALLBACK_DIR = tmpDir;
+    process.env.DATABASE_URL = "postgres://stub";
+    process.env.AILK_LEAD_NOTIFICATION_TO = "owner@example.com";
+    process.env.AILK_LEAD_NOTIFICATION_FROM = "noreply@example.com";
+    (prisma.lead.create as jest.Mock).mockResolvedValue({ id: "lead_db_new" });
+    (prisma.lead.findUnique as jest.Mock).mockResolvedValue(null);
+    mockSendLeadNotification.mockResolvedValue({
+      ok: true,
+      messageId: "msg-1",
+    });
+  });
+
+  afterEach(async () => {
+    for (const k of ENV_KEYS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("case 9 — a P2002 race whose winner matches answers the winner's id: no fallback, no persist_failed, no notification, no capture record", async () => {
+    // Positive control first: a keyed create with no race writes exactly one
+    // line to the capture file, so the negative assertion below is load-bearing.
+    const controlFile = path.join(tmpDir, "control.jsonl");
+    process.env.LEAD_CAPTURE_FILE = controlFile;
+    const control = await routeLead(leadInput, sourceMeta, {
+      idempotencyKey: KEY,
+    });
+    expect(control).toMatchObject({
+      ok: true,
+      id: "lead_db_new",
+      persisted: "db",
+    });
+    expect(
+      (await fs.readFile(controlFile, "utf8")).trim().split("\n"),
+    ).toHaveLength(1);
+    expect(createData()).toMatchObject({ idempotencyKey: KEY });
+
+    jest.clearAllMocks();
+    const raceFile = path.join(tmpDir, "race.jsonl");
+    process.env.LEAD_CAPTURE_FILE = raceFile;
+    (prisma.lead.create as jest.Mock).mockRejectedValue(p2002());
+    (prisma.lead.findUnique as jest.Mock)
+      .mockResolvedValueOnce(null) // the pre-write lookup misses
+      .mockResolvedValueOnce({
+        id: WINNER_ID,
+        email: leadInput.email,
+        source: leadInput.source,
+        payload: { ...leadInput.payload },
+      });
+    const before = await fs.readdir(tmpDir);
+
+    const result = await routeLead(leadInput, sourceMeta, {
+      idempotencyKey: KEY,
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      replayed: true,
+      id: WINNER_ID,
+      persisted: "db",
+      email: { skipped: true, reason: "idempotent_replay" },
+    });
+    expect(prisma.lead.findUnique).toHaveBeenNthCalledWith(
+      2,
+      keyWhere(leadInput.siteId),
+    );
+    expect(mockSendLeadNotification).not.toHaveBeenCalled();
+    await expect(fs.access(raceFile)).rejects.toThrow();
+    expect(await fs.readdir(tmpDir)).toEqual(before); // no file fallback
+  });
+
+  it("case 10 — a P2002 race whose winner carries a different email is idempotency_conflict", async () => {
+    (prisma.lead.create as jest.Mock).mockRejectedValue(p2002());
+    (prisma.lead.findUnique as jest.Mock)
+      .mockResolvedValueOnce(null)
+      .mockResolvedValueOnce({
+        id: WINNER_ID,
+        email: "someone-else@example.com",
+        source: leadInput.source,
+        payload: leadInput.payload,
+      });
+
+    const result = await routeLead(leadInput, sourceMeta, {
+      idempotencyKey: KEY,
+    });
+
+    expect(result).toEqual({
+      ok: false,
+      error: {
+        kind: "idempotency_conflict",
+        message: "idempotency key reused",
+      },
+    });
+    expect(mockSendLeadNotification).not.toHaveBeenCalled();
+  });
+
+  it("case 11 — a P2002 race whose re-read finds nothing takes the existing persist_failed path", async () => {
+    (prisma.lead.create as jest.Mock).mockRejectedValue(p2002());
+
+    const result = (await routeLead(leadInput, sourceMeta, {
+      idempotencyKey: KEY,
+    })) as Extract<RouteLeadResult, { ok: false }>;
+
+    expect(result.ok).toBe(false);
+    expect(result.error.kind).toBe("persist_failed");
+    expect(prisma.lead.findUnique).toHaveBeenCalledTimes(2);
+  });
+
+  it("case 12 — a P2002 with no key passed is persist_failed, as today, with no key lookup", async () => {
+    (prisma.lead.create as jest.Mock).mockRejectedValue(p2002());
+
+    const result = (await routeLead(leadInput, sourceMeta)) as Extract<
+      RouteLeadResult,
+      { ok: false }
+    >;
+
+    expect(result.ok).toBe(false);
+    expect(result.error.kind).toBe("persist_failed");
+    expect(prisma.lead.findUnique).not.toHaveBeenCalled();
+    expect(createData()).not.toHaveProperty("idempotencyKey");
+  });
+
+  it("case 13 — a lookup that throws still reaches the create (the existing path)", async () => {
+    (prisma.lead.findUnique as jest.Mock).mockRejectedValue(
+      new Error("connection reset"),
+    );
+
+    const result = await routeLead(leadInput, sourceMeta, {
+      idempotencyKey: KEY,
+    });
+
+    expect(prisma.lead.create).toHaveBeenCalledTimes(1);
+    expect(result).toMatchObject({
+      ok: true,
+      id: "lead_db_new",
+      persisted: "db",
+    });
+  });
+
+  it("case 14 — a non-inbox delivery ignores the key: no lookup, no key on the create, the existing file path", async () => {
+    delete process.env.DATABASE_URL; // `local` delivery outside production
+    (prisma.lead.create as jest.Mock).mockRejectedValue(
+      new Error("connection refused"),
+    );
+
+    const result = await routeLead(leadInput, sourceMeta, {
+      idempotencyKey: KEY,
+    });
+
+    expect(prisma.lead.findUnique).not.toHaveBeenCalled();
+    expect(createData()).not.toHaveProperty("idempotencyKey");
+    expect(result).toMatchObject({ ok: true, persisted: "file" });
+  });
+});
+
+// ─── #852 D6 — every submitted lead carries its Person ──────────────────────
+//
+// The Person step runs through the shared mock's `person` delegate, whose
+// `findFirst` default resolves one fixed Person (`MOCK_PERSON_ID`). Lead
+// capture is a never-gate surface: an unstorable address or a failed step
+// writes the lead with `personId: null` and changes nothing else.
+describe("#852 — the lead's Person (AC-3)", () => {
+  const ENV_KEYS = [
+    "DATABASE_URL",
+    "NODE_ENV",
+    "AILK_LEAD_NOTIFICATION_TO",
+    "AILK_LEAD_NOTIFICATION_FROM",
+  ] as const;
+  let saved: Partial<Record<(typeof ENV_KEYS)[number], string | undefined>>;
+  const LEAD_ID = "lead_00000000-0000-7000-8000-000000000852";
+  const createData = () =>
+    jest.mocked(prisma.lead.create).mock.calls[0]?.[0].data as Record<string, unknown>;
+  const personDelegate = () => ({
+    findFirst: jest.mocked(prisma.person.findFirst),
+    createMany: jest.mocked(prisma.person.createMany),
+    updateMany: jest.mocked(prisma.person.updateMany),
+  });
+  const personCalls = () =>
+    Object.values(personDelegate()).reduce((n, fn) => n + fn.mock.calls.length, 0);
+  let warn: jest.SpyInstance;
+  let error: jest.SpyInstance;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    saved = {};
+    for (const k of ENV_KEYS) saved[k] = process.env[k];
+    process.env.DATABASE_URL = "postgres://stub";
+    delete process.env.NODE_ENV;
+    process.env.AILK_LEAD_NOTIFICATION_TO = "owner@example.com";
+    process.env.AILK_LEAD_NOTIFICATION_FROM = "noreply@example.com";
+    (prisma.lead.create as jest.Mock).mockResolvedValue({ id: LEAD_ID });
+    mockSendLeadNotification.mockResolvedValue({ ok: true, messageId: "msg-852" });
+    warn = jest.spyOn(logger, "warn").mockImplementation(() => undefined as never);
+    error = jest.spyOn(logger, "error").mockImplementation(() => undefined as never);
+  });
+
+  afterEach(() => {
+    for (const k of ENV_KEYS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+    warn.mockRestore();
+    error.mockRestore();
+  });
+
+  it("a submit writes the Person findOrCreatePerson returned for (siteId, email)", async () => {
+    const result = await routeLead(
+      { ...leadInput, email: "Test@Example.com", payload: { name: "Tess", message: "hi" } },
+      sourceMeta,
+    );
+
+    expect(result).toMatchObject({ ok: true, id: LEAD_ID, persisted: "db" });
+    expect(personDelegate()["findFirst"]).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { workspaceId: "site-abc", email: "test@example.com" } }),
+    );
+    expect(createData()).toEqual(expect.objectContaining({ personId: MOCK_PERSON_ID }));
+  });
+
+  it("subscribe and callback make no person call", async () => {
+    (prisma.subscriber.create as jest.Mock).mockResolvedValue({ id: "subscr_x" });
+    (prisma.callback.create as jest.Mock).mockResolvedValue({ id: "callbk_x" });
+    await routeLead(subscribeInput, sourceMeta);
+    await routeLead(callbackInput, sourceMeta);
+    expect(personCalls()).toBe(0);
+  });
+
+  it("an invalid_email Person result writes the lead with personId: null and one person-skipped warn with no email", async () => {
+    // `leadInputSchema`'s email check refuses most unstorable addresses before
+    // this step, so the Person result is stubbed to reach the branch.
+    jest
+      .spyOn(personService, "findOrCreatePerson")
+      .mockResolvedValueOnce({ ok: false, error: { kind: "invalid_email" } });
+    const result = await routeLead(leadInput, sourceMeta);
+
+    expect(result).toMatchObject({ ok: true, id: LEAD_ID, persisted: "db" });
+    expect(createData()).toEqual(expect.objectContaining({ personId: null }));
+    const skipped = warn.mock.calls.filter(([fields]) => (fields as { event?: string }).event === "person-skipped");
+    expect(skipped).toHaveLength(1);
+    expect(skipped[0]![0]).toEqual({ event: "person-skipped", kind: "invalid_email", siteId: "site-abc" });
+    expect(JSON.stringify(warn.mock.calls)).not.toContain("example.com");
+  });
+
+  it("an internal_error Person result is the same never-gate path as a throwing delegate", async () => {
+    jest
+      .spyOn(personService, "findOrCreatePerson")
+      .mockResolvedValueOnce({ ok: false, error: { kind: "internal_error" } });
+    const result = await routeLead(leadInput, sourceMeta);
+
+    expect(result).toMatchObject({ ok: true, id: LEAD_ID, persisted: "db" });
+    expect(createData()).toEqual(expect.objectContaining({ personId: null }));
+    expect(error.mock.calls.map(([fields]) => fields)).toContainEqual({
+      event: "person-failed",
+      siteId: "site-abc",
+    });
+  });
+
+  it("a Person step that fails writes the lead with personId: null, logs person-failed with no email, and answers like a successful capture", async () => {
+    const ok = await routeLead(leadInput, sourceMeta);
+    jest.mocked(prisma.lead.create).mockClear();
+    mockSendLeadNotification.mockClear();
+    personDelegate()["findFirst"]!.mockRejectedValueOnce(new Error("relation \"people\" does not exist"));
+
+    const failed = await routeLead(leadInput, sourceMeta);
+
+    expect(failed).toEqual(ok);
+    expect(failed).toMatchObject({ ok: true, id: LEAD_ID, persisted: "db", email: { ok: true } });
+    expect(createData()).toEqual(expect.objectContaining({ personId: null }));
+    const lines = error.mock.calls.filter(([fields]) => (fields as { event?: string }).event === "person-failed");
+    expect(lines).toHaveLength(1);
+    expect(lines[0]![0]).toEqual({ event: "person-failed", siteId: "site-abc" });
+    expect(JSON.stringify(error.mock.calls)).not.toContain("test@example.com");
+  });
+});
+
+// ─── #7877 D10 — a spoke's checkout lead sets the Person's plan (AC-5) ──────
+//
+// The plan step runs only after this request's own `lead.create`, for a LIVE,
+// paid checkout lead a registered spoke's server posted with the session id
+// as its key. Every other lead makes no plan call; a failing plan step never
+// changes the lead's result.
+describe("#7877 — the checkout lead sets the plan (AC-5)", () => {
+  const ENV_KEYS = [
+    "DATABASE_URL",
+    "NODE_ENV",
+    "AILK_LEAD_NOTIFICATION_TO",
+    "AILK_LEAD_NOTIFICATION_FROM",
+  ] as const;
+  let saved: Partial<Record<(typeof ENV_KEYS)[number], string | undefined>>;
+  const LEAD_ID = "lead_00000000-0000-7000-8000-000000007877";
+  const WS = "wksp_00000000-0000-7000-8000-000000007877";
+  const KEY = "cs_live_a1B2c3"; // gitleaks:allow -- a synthetic Checkout Session id shape (#7877 AC-5), not a credential
+  const spokeMeta = { ...sourceMeta, viaSpoke: true };
+  const checkoutLead = {
+    kind: "submit" as const,
+    siteId: WS,
+    source: "web",
+    email: "cleo@x.io",
+    payload: { site: "wendi", page: "checkout", offering: "wendi_retainer" } as Record<string, unknown>,
+  };
+  let setPlan: jest.SpyInstance;
+  let info: jest.SpyInstance;
+  let error: jest.SpyInstance;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    saved = {};
+    for (const k of ENV_KEYS) saved[k] = process.env[k];
+    process.env.DATABASE_URL = "postgres://stub";
+    delete process.env.NODE_ENV;
+    process.env.AILK_LEAD_NOTIFICATION_TO = "owner@example.com";
+    process.env.AILK_LEAD_NOTIFICATION_FROM = "noreply@example.com";
+    (prisma.lead.create as jest.Mock).mockResolvedValue({ id: LEAD_ID });
+    (prisma.lead.findUnique as jest.Mock).mockResolvedValue(null);
+    mockSendLeadNotification.mockResolvedValue({ ok: true, messageId: "msg-7877" });
+    setPlan = jest.spyOn(personService, "setPersonPlanOffering").mockResolvedValue("set");
+    info = jest.spyOn(logger, "info").mockImplementation(() => undefined as never);
+    error = jest.spyOn(logger, "error").mockImplementation(() => undefined as never);
+  });
+
+  afterEach(() => {
+    for (const k of ENV_KEYS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+    setPlan.mockRestore();
+    info.mockRestore();
+    error.mockRestore();
+  });
+
+  const planLines = () =>
+    [...info.mock.calls, ...error.mock.calls]
+      .map(([fields]) => fields as Record<string, unknown>)
+      .filter((fields) => fields.event === "checkout-plan");
+
+  it("a live spoke checkout lead sets the plan to the offering minus the <site>_ prefix", async () => {
+    const result = await routeLead(checkoutLead, spokeMeta, { idempotencyKey: KEY });
+    expect(result).toMatchObject({ ok: true, id: LEAD_ID, persisted: "db" });
+    expect(setPlan).toHaveBeenCalledTimes(1);
+    expect(setPlan).toHaveBeenCalledWith(WS, MOCK_PERSON_ID, "retainer");
+    expect(planLines()).toEqual([{ event: "checkout-plan", outcome: "set", siteId: WS }]);
+  });
+
+  it("a bare slug offering is taken as it is", async () => {
+    await routeLead(
+      { ...checkoutLead, payload: { ...checkoutLead.payload, offering: "retainer" } },
+      spokeMeta,
+      { idempotencyKey: KEY },
+    );
+    expect(setPlan).toHaveBeenCalledWith(WS, MOCK_PERSON_ID, "retainer");
+  });
+
+  it("a positive integer amountTotal still qualifies", async () => {
+    await routeLead(
+      { ...checkoutLead, payload: { ...checkoutLead.payload, amountTotal: 4900 } },
+      spokeMeta,
+      { idempotencyKey: KEY },
+    );
+    expect(setPlan).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([
+    ["an anonymous lead (viaSpoke false)", checkoutLead, sourceMeta, KEY],
+    ["a test-mode session key", checkoutLead, spokeMeta, "cs_test_a1B2c3"],
+    [
+      "amountTotal 0",
+      { ...checkoutLead, payload: { ...checkoutLead.payload, amountTotal: 0 } },
+      spokeMeta,
+      KEY,
+    ],
+    [
+      "a negative amountTotal",
+      { ...checkoutLead, payload: { ...checkoutLead.payload, amountTotal: -5 } },
+      spokeMeta,
+      KEY,
+    ],
+    ["a key that is not a session id", checkoutLead, spokeMeta, "abcdefghijklmnop"],
+    ["no key", checkoutLead, spokeMeta, undefined],
+    ["source contact", { ...checkoutLead, source: "contact" }, spokeMeta, KEY],
+    [
+      "page contact",
+      { ...checkoutLead, payload: { ...checkoutLead.payload, page: "contact" } },
+      spokeMeta,
+      KEY,
+    ],
+    [
+      "a numeric offering",
+      { ...checkoutLead, payload: { ...checkoutLead.payload, offering: 42 } },
+      spokeMeta,
+      KEY,
+    ],
+  ] as const)("no plan call for %s", async (_label, input, meta, key) => {
+    const result = await routeLead(
+      input as typeof checkoutLead,
+      meta,
+      key === undefined ? {} : { idempotencyKey: key },
+    );
+    expect(result).toMatchObject({ ok: true, persisted: "db" });
+    expect(setPlan).not.toHaveBeenCalled();
+    expect(jest.mocked(prisma.person.updateMany)).not.toHaveBeenCalled();
+    expect(planLines()).toEqual([]);
+  });
+
+  it("an offering that is not a key after the strip logs skipped and makes no plan call", async () => {
+    await routeLead(
+      { ...checkoutLead, payload: { ...checkoutLead.payload, offering: "Wendi_Retainer!" } },
+      spokeMeta,
+      { idempotencyKey: KEY },
+    );
+    expect(setPlan).not.toHaveBeenCalled();
+    expect(planLines()).toEqual([{ event: "checkout-plan", outcome: "skipped", siteId: WS }]);
+  });
+
+  it("a replayed key writes nothing and sets nothing", async () => {
+    (prisma.lead.findUnique as jest.Mock).mockResolvedValue({
+      id: LEAD_ID,
+      email: checkoutLead.email,
+      source: checkoutLead.source,
+      payload: checkoutLead.payload,
+    });
+    const result = await routeLead(checkoutLead, spokeMeta, { idempotencyKey: KEY });
+    expect(result).toMatchObject({ ok: true, replayed: true, id: LEAD_ID });
+    expect(prisma.lead.create).not.toHaveBeenCalled();
+    expect(setPlan).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["throws", () => setPlan.mockRejectedValueOnce(new Error("down"))],
+    ["answers not_found", () => setPlan.mockResolvedValueOnce("not_found")],
+  ])("a plan step that %s answers exactly like a success, with one failed line naming no offering, email or key", async (_label, arrange) => {
+    const ok = await routeLead(checkoutLead, spokeMeta, { idempotencyKey: KEY });
+    info.mockClear();
+    error.mockClear();
+    arrange();
+    const failed = await routeLead(checkoutLead, spokeMeta, { idempotencyKey: KEY });
+    expect(failed).toEqual(ok);
+    expect(failed).toMatchObject({ ok: true, id: LEAD_ID, persisted: "db" });
+    expect(planLines()).toEqual([{ event: "checkout-plan", outcome: "failed", siteId: WS }]);
+    const logged = JSON.stringify([...info.mock.calls, ...error.mock.calls]);
+    expect(logged).not.toContain("retainer");
+    expect(logged).not.toContain("cleo@x.io");
+    expect(logged).not.toContain(KEY);
+  });
+});