create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/services/__tests__/waitlist-scoring.test.ts

@@ -0,0 +1,474 @@
+/**
+ * @file waitlist-scoring.test.ts
+ * @description Unit tests for the waitlist-scoring glue service (#4662 D6).
+ *
+ * External dependency boundary mocked: @working-theory/database (auto-mock
+ * via `../../lib/__mocks__/prisma.ts`, mirroring waitlist-experiments.test.ts).
+ * `@working-theory/observability`'s logger is mocked to a spyable stub
+ * (mirrors deliverable-fulfillment.test.ts / abandon-email.test.ts) so the
+ * PII-safety of the error logs is directly assertable.
+ *
+ * `@working-theory/validation`'s `evaluateWaitlistScoring` is a PARTIAL mock
+ * (every other export runs real, incl. `waitlistExperimentConfigSchema` and
+ * `answersFromPayload`) — every one of the pure evaluator's own defensive
+ * throws (unresolvable ref/score/sum term, a ref cycle) is on a register
+ * shape `waitlistExperimentConfigSchema`'s own superRefine already rejects
+ * (waitlist-scoring.test.ts, packages/validation, covers those exhaustively
+ * against a register that bypasses the schema entirely). So the ONLY way to
+ * observe this glue's `evaluation_failed` outcome against a schema-VALID
+ * config is to make the (already schema-validated, already unit-tested)
+ * evaluator itself throw for one call — not to hand-craft an "invalid but
+ * schema-valid" register, which cannot exist by construction.
+ */
+// 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 mockLoggerError = jest.fn();
+jest.mock("@working-theory/observability", () => ({
+  logger: {
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: (...args: unknown[]) => mockLoggerError(...args),
+    debug: jest.fn(),
+  },
+}));
+
+jest.mock("@working-theory/validation", () => {
+  const actual = jest.requireActual("@working-theory/validation");
+  return { ...actual, evaluateWaitlistScoring: jest.fn(actual.evaluateWaitlistScoring) };
+});
+
+import { evaluateWaitlistScoring } from "@working-theory/validation";
+
+import { prisma } from "../../lib/prisma.js";
+import { scoreCompletedSignup } from "../waitlist-scoring";
+
+const en = (s: string) => ({ en: s });
+const SITE_ID = "site-abc";
+const LEAD_ID = "lead-1";
+const EXPERIMENT_KEY = "my-experiment";
+const WAITLIST_KEY = "main";
+
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+function noScoringConfig() {
+  return {
+    key: EXPERIMENT_KEY,
+    mode: "lead-capture" as const,
+    status: "draft" as const,
+    waitlists: [{ key: WAITLIST_KEY, flowSlug: EXPERIMENT_KEY }],
+    questionSet: {
+      version: 1 as const,
+      questions: [
+        {
+          id: "email",
+          prompt: en("Your email"),
+          answerType: "email" as const,
+          mapsTo: "email" as const,
+        },
+      ],
+    },
+    tracking: {
+      version: 1 as const,
+      utm: { source: "utm_source", medium: "utm_medium", campaign: "utm_campaign" },
+      waitlists: { [WAITLIST_KEY]: { campaign: "launch", channels: ["organic"] } },
+    },
+    stripeConfigRef: null,
+  };
+}
+
+function validQualifyingConfig() {
+  return {
+    key: EXPERIMENT_KEY,
+    mode: "qualifying" as const,
+    status: "draft" as const,
+    waitlists: [{ key: WAITLIST_KEY, flowSlug: EXPERIMENT_KEY }],
+    questionSet: {
+      version: 1 as const,
+      questions: [
+        {
+          id: "email",
+          prompt: en("Your email"),
+          answerType: "email" as const,
+          mapsTo: "email" as const,
+        },
+        {
+          id: "budget",
+          prompt: en("What's your budget?"),
+          answerType: "single" as const,
+          options: [
+            { value: "small", label: en("Small") },
+            { value: "large", label: en("Large") },
+          ],
+        },
+      ],
+    },
+    scoring: {
+      version: 1 as const,
+      points: [
+        {
+          name: "budget_points",
+          question: "budget",
+          kind: "optionWeights" as const,
+          weights: { small: 1, large: 10 },
+        },
+      ],
+      scores: { total: { sum: ["budget_points"] } },
+      tiers: [{ key: "hot", when: { score: "total", gte: 5 } }],
+      default: "hot",
+    },
+    tracking: {
+      version: 1 as const,
+      utm: { source: "utm_source", medium: "utm_medium", campaign: "utm_campaign" },
+      waitlists: { [WAITLIST_KEY]: { campaign: "launch", channels: ["organic"] } },
+    },
+    stripeConfigRef: null,
+  };
+}
+
+describe("scoreCompletedSignup (D6)", () => {
+  it("no experiment row ⇒ skipped: no_experiment, no upsert", async () => {
+    (prisma.waitlistExperiment.findUnique as jest.Mock).mockResolvedValue(null);
+
+    const result = await scoreCompletedSignup({
+      siteId: SITE_ID,
+      leadId: LEAD_ID,
+      experimentKey: EXPERIMENT_KEY,
+      waitlistKey: WAITLIST_KEY,
+      payload: {},
+    });
+
+    expect(result).toEqual({ ok: true, skipped: "no_experiment" });
+    expect(prisma.waitlistScore.upsert).not.toHaveBeenCalled();
+  });
+
+  it("a config with no scoring block ⇒ skipped: no_scoring, no upsert (a lead-capture experiment)", async () => {
+    (prisma.waitlistExperiment.findUnique as jest.Mock).mockResolvedValue({
+      config: noScoringConfig(),
+    });
+
+    const result = await scoreCompletedSignup({
+      siteId: SITE_ID,
+      leadId: LEAD_ID,
+      experimentKey: EXPERIMENT_KEY,
+      waitlistKey: WAITLIST_KEY,
+      payload: {},
+    });
+
+    expect(result).toEqual({ ok: true, skipped: "no_scoring" });
+    expect(prisma.waitlistScore.upsert).not.toHaveBeenCalled();
+  });
+
+  it("an invalid stored config (defensive — the row was validated on write) ⇒ invalid_config, no upsert", async () => {
+    (prisma.waitlistExperiment.findUnique as jest.Mock).mockResolvedValue({
+      config: { not: "a config" },
+    });
+
+    const result = await scoreCompletedSignup({
+      siteId: SITE_ID,
+      leadId: LEAD_ID,
+      experimentKey: EXPERIMENT_KEY,
+      waitlistKey: WAITLIST_KEY,
+      payload: {},
+    });
+
+    expect(result).toEqual({ ok: false, error: { kind: "invalid_config" } });
+    expect(prisma.waitlistScore.upsert).not.toHaveBeenCalled();
+  });
+
+  it("a valid qualifying config ⇒ exactly one upsert on {leadId, experimentKey} carrying the evaluator's output", async () => {
+    (prisma.waitlistExperiment.findUnique as jest.Mock).mockResolvedValue({
+      config: validQualifyingConfig(),
+    });
+    (prisma.waitlistScore.upsert as jest.Mock).mockResolvedValue({ id: "wlscore_1" });
+
+    const result = await scoreCompletedSignup({
+      siteId: SITE_ID,
+      leadId: LEAD_ID,
+      experimentKey: EXPERIMENT_KEY,
+      waitlistKey: WAITLIST_KEY,
+      payload: { budget: "large" },
+    });
+
+    expect(result).toEqual({ ok: true, tier: "hot" });
+    expect(prisma.waitlistScore.upsert).toHaveBeenCalledTimes(1);
+    expect(prisma.waitlistScore.upsert).toHaveBeenCalledWith(
+      expect.objectContaining({
+        // The composite key since #5036 D6d — `{ leadId }` alone scoped one
+        // score per LEAD, which silently erased a founder's evidence the
+        // moment a visitor joined a second listing's waitlist.
+        where: { leadId_experimentKey: { leadId: LEAD_ID, experimentKey: EXPERIMENT_KEY } },
+        create: expect.objectContaining({
+          siteId: SITE_ID,
+          leadId: LEAD_ID,
+          experimentKey: EXPERIMENT_KEY,
+          waitlistKey: WAITLIST_KEY,
+          tier: "hot",
+          score: 10,
+          categoryScores: { total: 10 },
+        }),
+        update: expect.objectContaining({
+          tier: "hot",
+          score: 10,
+          categoryScores: { total: 10 },
+        }),
+      }),
+    );
+  });
+
+  it("a second call on the same lead re-scores via the same upsert call — update, never a second row", async () => {
+    (prisma.waitlistExperiment.findUnique as jest.Mock).mockResolvedValue({
+      config: validQualifyingConfig(),
+    });
+    (prisma.waitlistScore.upsert as jest.Mock).mockResolvedValue({ id: "wlscore_1" });
+
+    await scoreCompletedSignup({
+      siteId: SITE_ID,
+      leadId: LEAD_ID,
+      experimentKey: EXPERIMENT_KEY,
+      waitlistKey: WAITLIST_KEY,
+      payload: { budget: "large" },
+    });
+    await scoreCompletedSignup({
+      siteId: SITE_ID,
+      leadId: LEAD_ID,
+      experimentKey: EXPERIMENT_KEY,
+      waitlistKey: WAITLIST_KEY,
+      payload: { budget: "small" },
+    });
+
+    expect(prisma.waitlistScore.upsert).toHaveBeenCalledTimes(2);
+    const calls = (prisma.waitlistScore.upsert as jest.Mock).mock.calls;
+    // Same lead, same experiment ⇒ the SAME composite key both times, so the
+    // second write lands as an update. Re-scoring overwriting is the intended
+    // behaviour; #5036 D6d only scoped it per experiment, it did not remove it.
+    const key = { leadId_experimentKey: { leadId: LEAD_ID, experimentKey: EXPERIMENT_KEY } };
+    expect(calls[0]![0]).toMatchObject({ where: key });
+    expect(calls[1]![0]).toMatchObject({ where: key });
+  });
+
+  // ── #5036 D6d — one lead, two experiments, two surviving rows ───────────
+
+  /**
+   * The correctness defect D6d straightened, asserted from the outside.
+   *
+   * `WaitlistScore` carried `@@unique([leadId])` — "one row per lead". Right
+   * for a single instrument, wrong for a marketplace of them: a visitor who
+   * joins two founders' waitlists is one lead with TWO scores, and under
+   * `where: { leadId }` the second upsert resolved the SAME row as the first
+   * and overwrote it. One founder's evidence vanished into a CSV that
+   * reported fewer signups than actually happened, with no error raised
+   * anywhere.
+   *
+   * What makes the two rows survive is that the two writes address DIFFERENT
+   * keys, so this test asserts exactly that and nothing about Prisma's own
+   * upsert semantics.
+   */
+  it("scores one lead against two experiments — the two upserts carry DIFFERENT keys, so neither can overwrite the other", async () => {
+    (prisma.waitlistExperiment.findUnique as jest.Mock).mockResolvedValue({
+      config: validQualifyingConfig(),
+    });
+    (prisma.waitlistScore.upsert as jest.Mock).mockResolvedValue({ id: "wlscore_1" });
+
+    for (const experimentKey of ["exp-a", "exp-b"]) {
+      await scoreCompletedSignup({
+        siteId: SITE_ID,
+        leadId: LEAD_ID,
+        experimentKey,
+        waitlistKey: WAITLIST_KEY,
+        payload: { budget: "large" },
+      });
+    }
+
+    expect(prisma.waitlistScore.upsert).toHaveBeenCalledTimes(2);
+    const [first, second] = (prisma.waitlistScore.upsert as jest.Mock).mock.calls.map(
+      (call) => call[0] as { where: unknown },
+    );
+
+    expect(first!.where).toEqual({
+      leadId_experimentKey: { leadId: LEAD_ID, experimentKey: "exp-a" },
+    });
+    expect(second!.where).toEqual({
+      leadId_experimentKey: { leadId: LEAD_ID, experimentKey: "exp-b" },
+    });
+    // The load-bearing assertion: two distinct addresses, so the second write
+    // cannot resolve the first row. Under the old `where: { leadId }` both of
+    // these were `{ leadId: "lead-1" }` and this comparison would be equal.
+    expect(first!.where).not.toEqual(second!.where);
+  });
+
+  it("an evaluator throw ⇒ evaluation_failed, no upsert", async () => {
+    // The evaluator's own defensive throws (WaitlistEvaluationError, for an
+    // unresolvable ref/score/sum term or a ref cycle) are exhaustively
+    // covered against a register that bypasses the schema, in
+    // packages/validation/src/schemas/__tests__/waitlist-scoring.test.ts — a
+    // schema-VALID config cannot reach any of them (waitlistExperimentConfigSchema's
+    // own superRefine already rejects every such shape). So this glue-level
+    // test forces the (real, unit-tested) evaluator to throw for one call,
+    // to prove the glue's own catch → `evaluation_failed` → no upsert path.
+    (evaluateWaitlistScoring as jest.Mock).mockImplementationOnce(() => {
+      throw new Error("boom");
+    });
+    (prisma.waitlistExperiment.findUnique as jest.Mock).mockResolvedValue({
+      config: validQualifyingConfig(),
+    });
+
+    const result = await scoreCompletedSignup({
+      siteId: SITE_ID,
+      leadId: LEAD_ID,
+      experimentKey: EXPERIMENT_KEY,
+      waitlistKey: WAITLIST_KEY,
+      payload: { budget: "large" },
+    });
+
+    expect(result).toEqual({ ok: false, error: { kind: "evaluation_failed" } });
+    expect(prisma.waitlistScore.upsert).not.toHaveBeenCalled();
+  });
+
+  it("a persist (Prisma) failure ⇒ persist_failed", async () => {
+    (prisma.waitlistExperiment.findUnique as jest.Mock).mockResolvedValue({
+      config: validQualifyingConfig(),
+    });
+    (prisma.waitlistScore.upsert as jest.Mock).mockRejectedValue(new Error("db down"));
+
+    const result = await scoreCompletedSignup({
+      siteId: SITE_ID,
+      leadId: LEAD_ID,
+      experimentKey: EXPERIMENT_KEY,
+      waitlistKey: WAITLIST_KEY,
+      payload: { budget: "large" },
+    });
+
+    expect(result).toEqual({ ok: false, error: { kind: "persist_failed" } });
+  });
+
+  it("the log line carries no answer value — PII-safe outcome logs only", async () => {
+    (evaluateWaitlistScoring as jest.Mock).mockImplementationOnce(() => {
+      throw new Error("boom");
+    });
+    (prisma.waitlistExperiment.findUnique as jest.Mock).mockResolvedValue({
+      config: validQualifyingConfig(),
+    });
+
+    await scoreCompletedSignup({
+      siteId: SITE_ID,
+      leadId: LEAD_ID,
+      experimentKey: EXPERIMENT_KEY,
+      waitlistKey: WAITLIST_KEY,
+      payload: { budget: "large" },
+    });
+
+    expect(mockLoggerError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        siteId: SITE_ID,
+        experimentKey: EXPERIMENT_KEY,
+        leadId: LEAD_ID,
+        kind: "evaluation_failed",
+      }),
+      expect.any(String),
+    );
+    const [logMeta] = mockLoggerError.mock.calls[0]!;
+    expect(JSON.stringify(logMeta)).not.toContain("large");
+    expect(JSON.stringify(logMeta)).not.toContain("budget");
+  });
+});
+
+describe("scoreCompletedSignup — FEAT-074 U4a playbook compile hook (#4715)", () => {
+  // Exercises the REAL compileAndStorePlaybook (no jest.mock of the internal
+  // module — CONTRIBUTING.md § Test code quality / #507 forbids mocking an
+  // internal module; the real boundary is prisma + observability, both
+  // already mocked above). The tier must be a real `level_N` the VENDORED
+  // library declares (Level 1) so the real compile succeeds — this mirrors
+  // validQualifyingConfig()'s own register shape, only its tiers/default
+  // differ, so it stays a minimal diff from the existing fixture.
+  const TARGETING_MATURITY_KEY = "targeting-maturity";
+
+  function targetingMaturityConfig() {
+    const base = validQualifyingConfig();
+    return {
+      ...base,
+      key: TARGETING_MATURITY_KEY,
+      scoring: {
+        ...base.scoring,
+        tiers: [{ key: "level_1", when: { score: "total", gte: 0 } }],
+        default: "level_1",
+      },
+    };
+  }
+
+  it("experimentKey === targeting-maturity ⇒ a PlaybookInstance row is created from the upserted score's id and tier (AC-3)", async () => {
+    (prisma.waitlistExperiment.findUnique as jest.Mock).mockResolvedValue({
+      config: targetingMaturityConfig(),
+    });
+    (prisma.waitlistScore.upsert as jest.Mock).mockResolvedValue({ id: "wlscore_playbook_1" });
+    (prisma.playbookInstance.create as jest.Mock).mockResolvedValue({ id: "pbk_1" });
+
+    const result = await scoreCompletedSignup({
+      siteId: SITE_ID,
+      leadId: LEAD_ID,
+      experimentKey: TARGETING_MATURITY_KEY,
+      waitlistKey: WAITLIST_KEY,
+      payload: { budget: "large" },
+    });
+
+    expect(result).toEqual({ ok: true, tier: "level_1" });
+    expect(prisma.playbookInstance.create).toHaveBeenCalledTimes(1);
+    const [call] = (prisma.playbookInstance.create as jest.Mock).mock.calls[0]!;
+    expect(call.data).toMatchObject({
+      siteId: SITE_ID,
+      leadId: LEAD_ID,
+      experimentKey: TARGETING_MATURITY_KEY,
+      scoreId: "wlscore_playbook_1",
+      tier: "level_1",
+      level: 1,
+    });
+  });
+
+  it("any other experimentKey ⇒ no PlaybookInstance row is created", async () => {
+    (prisma.waitlistExperiment.findUnique as jest.Mock).mockResolvedValue({
+      config: validQualifyingConfig(),
+    });
+    (prisma.waitlistScore.upsert as jest.Mock).mockResolvedValue({ id: "wlscore_1" });
+
+    const result = await scoreCompletedSignup({
+      siteId: SITE_ID,
+      leadId: LEAD_ID,
+      experimentKey: EXPERIMENT_KEY,
+      waitlistKey: WAITLIST_KEY,
+      payload: { budget: "large" },
+    });
+
+    expect(result).toEqual({ ok: true, tier: "hot" });
+    expect(prisma.playbookInstance.create).not.toHaveBeenCalled();
+  });
+
+  it("a compile/store failure leaves the score intact — scoreCompletedSignup still resolves ok:true, never throws to its caller (AC-4)", async () => {
+    (prisma.waitlistExperiment.findUnique as jest.Mock).mockResolvedValue({
+      config: targetingMaturityConfig(),
+    });
+    (prisma.waitlistScore.upsert as jest.Mock).mockResolvedValue({ id: "wlscore_playbook_2" });
+    (prisma.playbookInstance.create as jest.Mock).mockRejectedValueOnce(new Error("db down"));
+
+    const result = await scoreCompletedSignup({
+      siteId: SITE_ID,
+      leadId: LEAD_ID,
+      experimentKey: TARGETING_MATURITY_KEY,
+      waitlistKey: WAITLIST_KEY,
+      payload: { budget: "large" },
+    });
+
+    expect(result).toEqual({ ok: true, tier: "level_1" });
+    expect(prisma.waitlistScore.upsert).toHaveBeenCalledTimes(1);
+    expect(mockLoggerError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        siteId: SITE_ID,
+        experimentKey: TARGETING_MATURITY_KEY,
+        leadId: LEAD_ID,
+        kind: "playbook_compile_failed",
+      }),
+      expect.any(String),
+    );
+  });
+});