create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/services/__tests__/flow-aggregate.test.ts

@@ -0,0 +1,425 @@
+/**
+ * @file flow-aggregate.test.ts
+ *
+ * Service-level cover for `getFlowAggregate` (#4771 D1/D2/D3). Follows
+ * `waitlist-dashboard.test.ts`'s hand-rolled `jest.mock("../../lib/prisma.js",
+ * …)` in-memory matcher discipline rather than the routes tests' auto-mock —
+ * a small, file-local matcher tailored to the three reads this service
+ * makes (`flowDefinition.findUnique`, `waitlistExperiment.findMany`,
+ * `flowSession.findMany`).
+ */
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../lib/prisma.js", () => ({
+  prisma: {
+    flowDefinition: { findUnique: jest.fn() },
+    waitlistExperiment: { findMany: jest.fn() },
+    flowSession: { findMany: jest.fn() },
+  },
+}));
+
+import { getFlowAggregate } from "../flow-aggregate";
+import { prisma } from "../../lib/prisma.js";
+import { MAX_AGGREGATION_ROWS } from "../answer-distributions.js";
+
+const en = (s: string) => ({ en: s });
+
+const SITE = "wksp_00000000-0000-7000-8000-000000000001";
+const OTHER_SITE = "wksp_00000000-0000-7000-8000-0000000000bb";
+const SLUG = "founder-diagnostic-general";
+
+const CONFIG = {
+  key: "founder-diagnostic",
+  // D1's own no-Lead-until-email premise is mode-independent of the
+  // register schema's own mode-specific requirements (`recommending` needs
+  // an `offers` block, `qualifying` needs a `scoring` block, both out of
+  // scope here) — `lead-capture` exercises the same resultsReveal/single/
+  // multi contract with no extra register fields (mirrors CONFIG_B's own
+  // choice in waitlist-dashboard.test.ts).
+  mode: "lead-capture" as const,
+  status: "live" as const,
+  waitlists: [{ key: "general", flowSlug: SLUG }],
+  questionSet: {
+    version: 1 as const,
+    questions: [
+      {
+        id: "role",
+        prompt: en("Role?"),
+        answerType: "single" as const,
+        options: [
+          { value: "founder", label: en("Founder") },
+          { value: "other", label: en("Other") },
+        ],
+        resultsReveal: true as const,
+      },
+      {
+        id: "channels",
+        prompt: en("Channels?"),
+        answerType: "multi" as const,
+        options: [
+          { value: "search", label: en("Search") },
+          { value: "referral", label: en("Referral") },
+        ],
+        resultsReveal: true as const,
+      },
+      {
+        // Not flagged — must be absent from the response (AC3).
+        id: "team_size",
+        prompt: en("Team size?"),
+        answerType: "single" as const,
+        options: [{ value: "solo", label: en("Solo") }],
+      },
+      {
+        // Never chartable regardless of any flag — schema forbids the flag here anyway.
+        id: "notes",
+        prompt: en("Notes?"),
+        answerType: "text" as const,
+        minLength: 1,
+      },
+    ],
+  },
+  tracking: {
+    version: 1 as const,
+    utm: {
+      source: "utm_source",
+      medium: "utm_medium",
+      campaign: "utm_campaign",
+    },
+    waitlists: { general: { campaign: "gen-campaign", channels: ["organic"] } },
+  },
+  stripeConfigRef: null,
+};
+
+const EXPERIMENTS = [
+  {
+    id: "wlexp_00000000-0000-7000-8000-000000000001",
+    siteId: SITE,
+    config: CONFIG,
+  },
+];
+
+// Three completed sessions + one abandoned (excluded), no Lead created for
+// any of them (D1 — a recommending flow shows the reveal before the email
+// moment).
+const SESSIONS = [
+  {
+    siteId: SITE,
+    flowSlug: SLUG,
+    completedAt: new Date("2026-09-01T00:00:00.000Z"),
+    leadId: null,
+    state: {
+      role_step: { role: "founder" },
+      channels_step: { channels: ["search"] },
+    },
+  },
+  {
+    siteId: SITE,
+    flowSlug: SLUG,
+    completedAt: new Date("2026-09-02T00:00:00.000Z"),
+    leadId: null,
+    state: { role_step: { role: "founder" } },
+  },
+  {
+    siteId: SITE,
+    flowSlug: SLUG,
+    completedAt: new Date("2026-09-03T00:00:00.000Z"),
+    leadId: null,
+    state: {
+      role_step: { role: "other" },
+      channels_step: { channels: ["search", "referral"] },
+    },
+  },
+  {
+    siteId: SITE,
+    flowSlug: SLUG,
+    completedAt: null, // abandoned — must be excluded (AC6).
+    leadId: null,
+    state: { role_step: { role: "founder" } },
+  },
+];
+
+type Row = Record<string, unknown>;
+type Where = Record<string, unknown>;
+
+function matchesWhere(row: Row, where: Where): boolean {
+  for (const [key, cond] of Object.entries(where)) {
+    if (
+      cond !== null &&
+      typeof cond === "object" &&
+      "not" in (cond as Record<string, unknown>)
+    ) {
+      const notVal = (cond as { not: unknown }).not;
+      if (row[key] === notVal) return false;
+      continue;
+    }
+    if (row[key] !== cond) return false;
+  }
+  return true;
+}
+
+function installFixtureMocks(
+  definitions: { siteId: string; slug: string }[],
+  experiments: Row[],
+  sessions: Row[],
+): void {
+  (prisma.flowDefinition.findUnique as jest.Mock).mockImplementation(
+    ({ where }: { where: { siteId_slug: { siteId: string; slug: string } } }) =>
+      Promise.resolve(
+        definitions.some(
+          (d) =>
+            d.siteId === where.siteId_slug.siteId &&
+            d.slug === where.siteId_slug.slug,
+        )
+          ? { id: "flow_00000000-0000-7000-8000-000000000001" }
+          : null,
+      ),
+  );
+  (prisma.waitlistExperiment.findMany as jest.Mock).mockImplementation(
+    ({ where }: { where?: Where }) =>
+      Promise.resolve(experiments.filter((e) => matchesWhere(e, where ?? {}))),
+  );
+  (prisma.flowSession.findMany as jest.Mock).mockImplementation(
+    ({ where, take }: { where?: Where; take?: number }) => {
+      let rows = sessions.filter((s) => matchesWhere(s, where ?? {}));
+      if (typeof take === "number") rows = rows.slice(0, take);
+      return Promise.resolve(rows);
+    },
+  );
+}
+
+describe("getFlowAggregate", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    process.env.DATABASE_URL = "postgres://stub";
+    installFixtureMocks([{ siteId: SITE, slug: SLUG }], EXPERIMENTS, SESSIONS);
+  });
+
+  afterEach(() => {
+    delete process.env.DATABASE_URL;
+  });
+
+  it("AC1/AC5: returns exactly the flagged questions, per-option counts, and a truthful respondents total", async () => {
+    const result = await getFlowAggregate(SITE, SLUG);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.data.slug).toBe(SLUG);
+    // 3 completed sessions; the abandoned one is excluded (AC6).
+    expect(result.data.respondents).toBe(3);
+    expect(result.data.questions.map((q) => q.id).sort()).toEqual([
+      "channels",
+      "role",
+    ]);
+
+    const role = result.data.questions.find((q) => q.id === "role")!;
+    expect(role.answerType).toBe("single");
+    expect(role.answered).toBe(3);
+    const roleByValue = new Map(role.options.map((o) => [o.value, o]));
+    expect(roleByValue.get("founder")).toEqual({
+      value: "founder",
+      label: { en: "Founder" },
+      count: 2,
+    });
+    expect(roleByValue.get("other")).toEqual({
+      value: "other",
+      label: { en: "Other" },
+      count: 1,
+    });
+    // AC1 — for a single question the counts sum to answered.
+    const roleTotal = role.options.reduce((sum, o) => sum + o.count, 0);
+    expect(roleTotal).toBe(role.answered);
+  });
+
+  it("AC2: a multi question's counts do not sum to answered when respondents select more than one", async () => {
+    const result = await getFlowAggregate(SITE, SLUG);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const channels = result.data.questions.find((q) => q.id === "channels")!;
+    expect(channels.answerType).toBe("multi");
+    expect(channels.answered).toBe(2); // sessions 1 and 3 answered it
+    const byValue = new Map(channels.options.map((o) => [o.value, o]));
+    expect(byValue.get("search")?.count).toBe(2);
+    expect(byValue.get("referral")?.count).toBe(1);
+    const total = channels.options.reduce((sum, o) => sum + o.count, 0);
+    expect(total).toBe(3);
+    expect(total).not.toBe(channels.answered);
+  });
+
+  it("AC3: an unflagged single question is absent from the response even when respondents answered it", async () => {
+    const result = await getFlowAggregate(SITE, SLUG);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(
+      result.data.questions.find((q) => q.id === "team_size"),
+    ).toBeUndefined();
+  });
+
+  it("AC5: a known flow with no backing register at all returns questions: [] with a truthful respondents", async () => {
+    installFixtureMocks(
+      [{ siteId: SITE, slug: "no-register-flow" }],
+      [],
+      [
+        {
+          siteId: SITE,
+          flowSlug: "no-register-flow",
+          completedAt: new Date("2026-09-01T00:00:00.000Z"),
+          leadId: null,
+          state: {},
+        },
+      ],
+    );
+    const result = await getFlowAggregate(SITE, "no-register-flow");
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data.questions).toEqual([]);
+    expect(result.data.respondents).toBe(1);
+  });
+
+  it("AC5: a known flow whose register flags no question returns questions: [] with a truthful respondents", async () => {
+    const noFlagConfig = {
+      ...CONFIG,
+      questionSet: {
+        ...CONFIG.questionSet,
+        questions: CONFIG.questionSet.questions.map((q) => ({
+          ...q,
+          resultsReveal: undefined,
+        })),
+      },
+    };
+    installFixtureMocks(
+      [{ siteId: SITE, slug: SLUG }],
+      [{ ...EXPERIMENTS[0]!, config: noFlagConfig }],
+      SESSIONS,
+    );
+    const result = await getFlowAggregate(SITE, SLUG);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data.questions).toEqual([]);
+    expect(result.data.respondents).toBe(3);
+  });
+
+  it("AC5: an unknown slug returns 404 flow_not_found", async () => {
+    const result = await getFlowAggregate(SITE, "does-not-exist");
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.kind).toBe("flow_not_found");
+  });
+
+  it("AC6: respondents are counted from completed FlowSession rows; leadId null does not exclude a session", async () => {
+    const result = await getFlowAggregate(SITE, SLUG);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data.respondents).toBeGreaterThan(0);
+    // Every fixture session carries leadId: null (D1) yet all three
+    // completed ones are counted.
+    expect(result.data.respondents).toBe(3);
+  });
+
+  it("scopes every read to siteId — a foreign site's flow of the same slug is not counted", async () => {
+    installFixtureMocks([{ siteId: SITE, slug: SLUG }], EXPERIMENTS, [
+      ...SESSIONS,
+      {
+        siteId: OTHER_SITE,
+        flowSlug: SLUG,
+        completedAt: new Date("2026-09-01T00:00:00.000Z"),
+        leadId: null,
+        state: { role_step: { role: "founder" } },
+      },
+    ]);
+    const result = await getFlowAggregate(SITE, SLUG);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data.respondents).toBe(3);
+  });
+
+  it("carries no email, name, session id or score at any nesting depth (AC4)", async () => {
+    const result = await getFlowAggregate(SITE, SLUG);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const serialized = JSON.stringify(result.data);
+    expect(serialized).not.toMatch(/email/i);
+    expect(serialized).not.toMatch(/session/i);
+    expect(serialized).not.toMatch(/score/i);
+  });
+
+  it("returns flows_not_configured when DATABASE_URL is unset", async () => {
+    delete process.env.DATABASE_URL;
+    const result = await getFlowAggregate(SITE, SLUG);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.kind).toBe("flows_not_configured");
+  });
+
+  it("skips a corrupted experiment config rather than throwing", async () => {
+    installFixtureMocks(
+      [{ siteId: SITE, slug: SLUG }],
+      [
+        {
+          id: "wlexp_00000000-0000-7000-8000-0000000000cc",
+          siteId: SITE,
+          config: { not: "a valid config" },
+        },
+      ],
+      SESSIONS,
+    );
+    const result = await getFlowAggregate(SITE, SLUG);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    // No valid register matched -> no flagged questions, but respondents
+    // still counts every completed session.
+    expect(result.data.questions).toEqual([]);
+    expect(result.data.respondents).toBe(3);
+  });
+
+  it("reads both experiments and sessions in a deterministic order (code-review finding, #4771)", async () => {
+    await getFlowAggregate(SITE, SLUG);
+    expect(prisma.waitlistExperiment.findMany).toHaveBeenCalledWith(
+      expect.objectContaining({ orderBy: { createdAt: "asc" } }),
+    );
+    expect(prisma.flowSession.findMany).toHaveBeenCalledWith(
+      expect.objectContaining({ orderBy: { completedAt: "asc" } }),
+    );
+  });
+
+  it("caps waitlistExperiment.findMany with take: MAX_AGGREGATION_ROWS, mirroring the sibling flowSession.findMany read (#5109)", async () => {
+    await getFlowAggregate(SITE, SLUG);
+    expect(prisma.waitlistExperiment.findMany).toHaveBeenCalledWith(
+      expect.objectContaining({ take: MAX_AGGREGATION_ROWS }),
+    );
+  });
+
+  it("picks the deterministically-first (oldest) match when a slug resolves to more than one WaitlistExperiment", async () => {
+    // installFixtureMocks' in-memory matcher does not itself sort — it
+    // returns rows in array order — so this exercises the SAME "first
+    // match wins" branch the orderBy above makes deterministic in
+    // production: two experiments both declare SLUG, and the [0]-index
+    // pick is asserted against the array order the fixture declares (the
+    // oldest-first order the real orderBy would also produce).
+    const olderConfig = {
+      ...CONFIG,
+      questionSet: {
+        ...CONFIG.questionSet,
+        questions: CONFIG.questionSet.questions.map((q) =>
+          q.id === "role" ? { ...q, id: "role_from_older" } : q,
+        ),
+      },
+    };
+    installFixtureMocks(
+      [{ siteId: SITE, slug: SLUG }],
+      [
+        { id: "wlexp_older", siteId: SITE, config: olderConfig },
+        { id: "wlexp_newer", siteId: SITE, config: CONFIG },
+      ],
+      SESSIONS,
+    );
+    const result = await getFlowAggregate(SITE, SLUG);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.data.questions.map((q) => q.id)).toContain("role_from_older");
+  });
+
+  // Read-only-ness (spec §5.2: no write verb reachable from this module) is
+  // asserted directly against the source file, not via this mocked-prisma
+  // suite — see the spec's own decisive `grep -cE` probe.
+});