create-ailk 0.21.0 → 0.23.0

package/templates/apps/api/src/routes/leads/__tests__/magnet-completion.test.ts

@@ -0,0 +1,515 @@
+/**
+ * @file magnet-completion.test.ts
+ *
+ * #8757 AC-5 (the API half) and AC-7 (spec
+ * docs/specs/8757-a-per-magnet-completion-setting-spec.md D6, NFR3–NFR6):
+ * `POST /v1/leads/submit` answers a written `flow:<slug>` lead's completion.
+ * On `invite` the 201 gains `next` and the submitter gets one confirmation
+ * email whose link starts sign-in with their address prefilled, capped per
+ * recipient and per magnet; on `lead` neither; on `checkout` a `next` naming
+ * the offering, re-checked at submit time. A `source: "mcp"` submit — the
+ * `capture_lead` tool's own argument — answers exactly as before.
+ *
+ * The world: the route over the in-memory Prisma double, holding one
+ * workspace (`WS`, the site alias) and its live `contact` magnet (setting per
+ * case). `routeLead` is the route's seam to persistence and is replaced by a
+ * double that writes one `Lead` row per first write into the same in-memory
+ * table — so the caps count real rows — and answers a replay for a repeated
+ * `Idempotency-Key`, as `services/lead-routing.ts` does. `FRONTEND_URL` is
+ * `https://site.example` with the `workspace` module on;
+ * `@working-theory/email`'s `sendDeliverableEmail` is mocked. The spoke case
+ * resolves spoke `S1`, whose sign-in client's callback is
+ * `https://spoke.example/api/hub-session/callback`.
+ *
+ * #8757 AC-11 (D14): a checkout fulfilment's submit carries the caller's
+ * account origin into `routeLead` as `accountOrigin` — the spoke's for `S1`,
+ * `FRONTEND_URL`'s for a keyless caller, none for a spoke with no client.
+ */
+import Fastify from "fastify";
+import type { FastifyInstance } from "fastify";
+
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../lib/prisma.js", () =>
+  jest
+    .requireActual<typeof import("../../../__tests__/factories/in-memory-prisma")>(
+      "../../../__tests__/factories/in-memory-prisma",
+    )
+    .createInMemoryPrisma(),
+);
+
+const mockSendDeliverableEmail = jest.fn();
+jest.mock("@working-theory/email", () => ({
+  sendDeliverableEmail: (...args: unknown[]) => mockSendDeliverableEmail(...args),
+}));
+jest.mock("@working-theory/analytics/server", () => ({ track: jest.fn() }));
+
+const mockRouteLead = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../services/lead-routing.js", () => ({
+  routeLead: (...args: unknown[]) => mockRouteLead(...args),
+}));
+
+const mockResolveCallerSite = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../services/public-site-resolver.js", () => ({
+  ...jest.requireActual("../../../services/public-site-resolver.js"),
+  resolveCallerSite: (...args: unknown[]) => mockResolveCallerSite(...args),
+}));
+
+const mockFindClientByClientId = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../lib/hub-sign-in-store.js", () => ({
+  findClientByClientId: (...args: unknown[]) => mockFindClientByClientId(...args),
+}));
+
+const mockResolveCommerceClaim = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../lib/require-commerce-claim.js", () => ({
+  ...jest.requireActual("../../../lib/require-commerce-claim.js"),
+  resolveCommerceClaim: () => mockResolveCommerceClaim(),
+}));
+
+const mockListPlanOfferings = jest.fn();
+// eslint-disable-next-line no-restricted-syntax -- jest mock factory must be hoisted
+jest.mock("../../../services/plan-offerings.js", () => ({
+  listPlanOfferings: (...args: unknown[]) => mockListPlanOfferings(...args),
+}));
+
+import { logger } from "@working-theory/observability";
+import {
+  INVITE_EMAILS_PER_SITE_PER_HOUR,
+  contactFormFlowConfig,
+} from "@working-theory/validation";
+
+import { prisma } from "../../../lib/prisma.js";
+import { __resetSiteWorkspaceCacheForTests } from "../../../lib/site.js";
+import { leadSubmitRoute } from "../index.js";
+
+type Row = Record<string, unknown>;
+// eslint-disable-next-line no-restricted-syntax -- the in-memory double exposes its store on keys the real client type does not declare
+const fake = prisma as unknown as {
+  __db: Record<string, Row[]>;
+  __calls: Array<{ model: string; op: string }>;
+};
+
+const WS = "wksp_00000000-0000-7000-8000-0000000000c1";
+const S1 = "spoke_00000000-0000-7000-8000-0000000000d1";
+const MAGNET = "flow_00000000-0000-7000-8000-000000000001";
+const SITE_LINK = "https://site.example/sign-in?next=%2Faccount&email=a%40b.example";
+const SPOKE_LINK =
+  "https://spoke.example/api/hub-session/sign-in?next=%2Faccount&email=a%40b.example";
+
+let leadSeq = 0;
+const keysSeen = new Map<string, string>();
+
+/** `routeLead`'s double: one Lead row per first write, a replay per repeated key. */
+function routeLeadDouble(
+  input: { siteId: string; source: string; email: string },
+  _meta: unknown,
+  options: { idempotencyKey?: string },
+) {
+  const key = options.idempotencyKey;
+  if (key !== undefined && keysSeen.has(key)) {
+    return Promise.resolve({
+      ok: true,
+      id: keysSeen.get(key),
+      persisted: "db",
+      email: { skipped: true },
+      replayed: true,
+    });
+  }
+  const id = `lead_00000000-0000-7000-8000-${String(++leadSeq).padStart(12, "0")}`;
+  fake.__db.lead!.push({
+    id,
+    siteId: input.siteId,
+    workspaceId: input.siteId,
+    source: input.source,
+    email: input.email,
+    createdAt: new Date(),
+  });
+  if (key !== undefined) keysSeen.set(key, id);
+  return Promise.resolve({ ok: true, id, persisted: "db", email: { skipped: true } });
+}
+
+function setMagnet(completion: string, checkoutOffering: string | null = null, extra: Row = {}) {
+  fake.__db.flowDefinition = [
+    {
+      id: MAGNET,
+      siteId: WS,
+      workspaceId: WS,
+      slug: "contact",
+      config: contactFormFlowConfig,
+      kind: "contact",
+      title: "Contact form",
+      landingPage: "/contact",
+      status: "live",
+      listingId: null,
+      customersEnabled: false,
+      completion,
+      checkoutOffering,
+      ...extra,
+    },
+  ];
+}
+
+let app: FastifyInstance;
+const originalEnv = process.env;
+
+function submit(email = "a@b.example", source = "flow:contact", headers: Record<string, string> = {}) {
+  return app.inject({
+    method: "POST",
+    url: "/v1/leads/submit",
+    headers,
+    payload: {
+      kind: "submit",
+      siteId: "default",
+      source,
+      email,
+      consent: true,
+      payload: { name: "Ada", message: "Hello there, a question." },
+    },
+  });
+}
+
+const sends = () => mockSendDeliverableEmail.mock.calls.map((call) => call[0] as Row);
+/** The invite email is fired with `void`; let it settle before asserting on it. */
+const settle = () => new Promise((resolve) => setImmediate(resolve));
+const inviteOutcomes = (spy: jest.SpyInstance) =>
+  spy.mock.calls
+    .map((call) => call[0] as Row)
+    .filter((fields) => fields?.event === "magnet-invite")
+    .map((fields) => fields.outcome);
+
+beforeEach(async () => {
+  jest.clearAllMocks();
+  process.env = {
+    ...originalEnv,
+    DATABASE_URL: "postgres://stub",
+    AILK_SITE_ID: WS,
+    FRONTEND_URL: "https://site.example",
+    AILK_ENABLED_MODULES: "workspace",
+    AILK_DELIVERABLE_EMAIL_FROM: "hello@site.example",
+  };
+  for (const key of Object.keys(fake.__db)) delete fake.__db[key];
+  fake.__db.workspace = [{ id: WS, organizationId: "org_x", name: "W", slug: "w" }];
+  fake.__db.lead = [];
+  setMagnet("invite");
+  leadSeq = 0;
+  keysSeen.clear();
+  __resetSiteWorkspaceCacheForTests();
+  mockRouteLead.mockImplementation(routeLeadDouble);
+  mockResolveCallerSite.mockResolvedValue({ kind: "anonymous" });
+  mockSendDeliverableEmail.mockResolvedValue({ ok: true, messageId: "m1" });
+  mockResolveCommerceClaim.mockResolvedValue("claimed");
+  mockListPlanOfferings.mockResolvedValue([{ key: "retainer", name: "Retainer", type: "service" }]);
+  mockFindClientByClientId.mockResolvedValue({
+    id: "oauthc_1",
+    clientId: S1,
+    clientSecret: "x",
+    redirectUris: ["https://spoke.example/api/hub-session/callback"],
+    enabled: true,
+  });
+  app = Fastify();
+  await app.register(leadSubmitRoute);
+  await app.ready();
+});
+
+afterEach(async () => {
+  await app.close();
+  process.env = originalEnv;
+});
+
+describe("#8757 AC-5 — invite carries the link on the 201 and in one email", () => {
+  it("a flow:contact submit answers next: invite and sends one email with the prefilled sign-in link", async () => {
+    const res = await submit();
+    expect(res.statusCode).toBe(201);
+    expect(res.json().next).toEqual({ completion: "invite" });
+    await settle();
+    expect(sends()).toHaveLength(1);
+    expect(sends()[0]).toMatchObject({
+      to: "a@b.example",
+      fromAddress: "hello@site.example",
+      subject: "We received your Contact form",
+      cta: "Track this in your account",
+      downloadLink: SITE_LINK,
+    });
+  });
+
+  it("on lead: no next and no email", async () => {
+    setMagnet("lead");
+    const res = await submit();
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).not.toHaveProperty("next");
+    await settle();
+    expect(sends()).toHaveLength(0);
+  });
+
+  it("the same Idempotency-Key replayed answers next and sends no second email", async () => {
+    const headers = { "idempotency-key": "test-replay-key-not-a-secret" };
+    await submit("a@b.example", "flow:contact", headers);
+    const replay = await submit("a@b.example", "flow:contact", headers);
+    expect(replay.statusCode).toBe(201);
+    expect(replay.json().next).toEqual({ completion: "invite" });
+    await settle();
+    expect(sends()).toHaveLength(1);
+  });
+
+  it("a second unkeyed submit within a day is capped per recipient; another address is still sent", async () => {
+    const info = jest.spyOn(logger, "info");
+    await submit();
+    await settle();
+    const second = await submit();
+    expect(second.json().next).toEqual({ completion: "invite" });
+    await settle();
+    expect(sends()).toHaveLength(1);
+    expect(inviteOutcomes(info)).toContain("capped_recipient");
+
+    await submit("c@d.example");
+    await settle();
+    expect(sends()).toHaveLength(2);
+    expect(sends()[1]!.to).toBe("c@d.example");
+    info.mockRestore();
+  });
+
+  it("with the per-site hourly cap already reached, a new address gets next and no email", async () => {
+    const info = jest.spyOn(logger, "info");
+    for (let n = 0; n < INVITE_EMAILS_PER_SITE_PER_HOUR; n += 1) {
+      fake.__db.lead!.push({
+        id: `lead_prior_${n}`,
+        siteId: WS,
+        workspaceId: WS,
+        source: "flow:contact",
+        email: `prior-${n}@example.com`,
+        createdAt: new Date(Date.now() - 10 * 60 * 1000),
+      });
+    }
+    const res = await submit("new@example.com");
+    expect(res.json().next).toEqual({ completion: "invite" });
+    await settle();
+    expect(sends()).toHaveLength(0);
+    expect(inviteOutcomes(info)).toContain("capped_site");
+    info.mockRestore();
+  });
+
+  it("with no sender address: next and no email", async () => {
+    delete process.env.AILK_DELIVERABLE_EMAIL_FROM;
+    delete process.env.AILK_LEAD_NOTIFICATION_FROM;
+    const res = await submit();
+    expect(res.json().next).toEqual({ completion: "invite" });
+    await settle();
+    expect(sends()).toHaveLength(0);
+  });
+
+  it("the email send rejecting still answers 201 with next", async () => {
+    mockSendDeliverableEmail.mockRejectedValue(new Error("resend down"));
+    const res = await submit();
+    expect(res.statusCode).toBe(201);
+    expect(res.json().next).toEqual({ completion: "invite" });
+    await settle();
+  });
+
+  it("a flow:job-application submit answers next: invite and sends the Job application email (#8771 AC-6)", async () => {
+    setMagnet("invite", null, {
+      slug: "job-application",
+      kind: "diagnostic",
+      title: "Job application",
+      landingPage: "/careers",
+    });
+    const res = await submit("ada@example.com", "flow:job-application");
+    expect(res.statusCode).toBe(201);
+    expect(res.json().next).toEqual({ completion: "invite" });
+    await settle();
+    expect(sends()).toHaveLength(1);
+    expect(sends()[0]).toMatchObject({
+      to: "ada@example.com",
+      subject: "We received your Job application",
+      cta: "Track this in your account",
+      downloadLink: expect.stringContaining("https://site.example/sign-in"),
+    });
+    expect((sends()[0] as { downloadLink: string }).downloadLink).toContain("ada%40example.com");
+  });
+
+  it("a magnet declaring completionEmail sends its own subject and body with the same link", async () => {
+    setMagnet("invite", null, {
+      config: {
+        ...contactFormFlowConfig,
+        completionEmail: {
+          subject: { en: "Thanks from Acme" },
+          body: { en: "We will reply within a day." },
+        },
+      },
+    });
+    await submit();
+    await settle();
+    expect(sends()[0]).toMatchObject({
+      subject: "Thanks from Acme",
+      body: "We will reply within a day.",
+      cta: "Track this in your account",
+      downloadLink: SITE_LINK,
+    });
+  });
+});
+
+describe("#8757 AC-5 — no next and no email where the invite does not apply", () => {
+  it.each([
+    ["a draft magnet", () => setMagnet("invite", null, { status: "draft" }), "flow:contact"],
+    ["a contact-form source", () => undefined, "contact-form"],
+    ["a build with neither workspace nor multi-tenant", () => {
+      process.env.AILK_ENABLED_MODULES = "signal-collectors";
+    }, "flow:contact"],
+  ])("%s", async (_label, arrange, source) => {
+    arrange();
+    const res = await submit("a@b.example", source);
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).not.toHaveProperty("next");
+    await settle();
+    expect(sends()).toHaveLength(0);
+  });
+});
+
+describe("#8757 AC-5 — a spoke's link points at the spoke", () => {
+  beforeEach(() => {
+    mockResolveCallerSite.mockResolvedValue({ kind: "spoke", spokeId: S1, workspaceId: WS });
+  });
+
+  it("links the spoke's own hub sign-in start", async () => {
+    const res = await submit();
+    expect(res.json().next).toEqual({ completion: "invite" });
+    await settle();
+    expect(sends()[0]!.downloadLink).toBe(SPOKE_LINK);
+    expect(mockFindClientByClientId).toHaveBeenCalledWith(S1);
+  });
+
+  it.each([
+    ["no client", () => mockFindClientByClientId.mockResolvedValue(null)],
+    ["a disabled client", () =>
+      mockFindClientByClientId.mockResolvedValue({
+        id: "oauthc_1",
+        clientId: S1,
+        clientSecret: "x",
+        redirectUris: ["https://spoke.example/api/hub-session/callback"],
+        enabled: false,
+      })],
+    ["an http loopback callback in production", () => {
+      process.env.NODE_ENV = "production";
+      mockFindClientByClientId.mockResolvedValue({
+        id: "oauthc_1",
+        clientId: S1,
+        clientSecret: "x",
+        redirectUris: ["http://localhost:3000/api/hub-session/callback"],
+        enabled: true,
+      });
+    }],
+  ])("%s: no next and no email", async (_label, arrange) => {
+    arrange();
+    const res = await submit();
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).not.toHaveProperty("next");
+    await settle();
+    expect(sends()).toHaveLength(0);
+  });
+});
+
+describe("#8757 AC-5 — checkout names the offering only while it is claimed and listed", () => {
+  beforeEach(() => setMagnet("checkout", "retainer"));
+
+  it("retainer listed and the claim claimed → next: checkout, retainer; no email", async () => {
+    const res = await submit();
+    expect(res.json().next).toEqual({ completion: "checkout", checkoutOffering: "retainer" });
+    await settle();
+    expect(sends()).toHaveLength(0);
+  });
+
+  it.each([
+    ["the offering since unpublished", () => mockListPlanOfferings.mockResolvedValue([])],
+    ["the lister failing", () => mockListPlanOfferings.mockResolvedValue({ failed: "Error" })],
+    ["an unclaimed licence", () => mockResolveCommerceClaim.mockResolvedValue("unclaimed")],
+    ["an undetermined licence", () => mockResolveCommerceClaim.mockResolvedValue("undetermined")],
+  ])("%s: no next, still 201", async (_label, arrange) => {
+    arrange();
+    const res = await submit();
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).not.toHaveProperty("next");
+  });
+});
+
+describe("#8757 AC-7 — capture_lead's own arguments get today's answer", () => {
+  it("a source: mcp submit answers exactly id, persisted and email, with no store read", async () => {
+    fake.__calls.length = 0;
+    const res = await submit("a@b.example", "mcp");
+    expect(res.statusCode).toBe(201);
+    expect(Object.keys(res.json()).sort()).toEqual(["email", "id", "persisted"]);
+    expect(fake.__calls.filter((call) => call.model === "flowDefinition")).toEqual([]);
+    await settle();
+    expect(sends()).toHaveLength(0);
+  });
+});
+
+describe("#8757 AC-11 — a checkout submit carries the caller's account origin into routeLead", () => {
+  const CHECKOUT_KEY = "cs_live_ac11RouteKey"; // gitleaks:allow -- a synthetic Checkout Session id shape (#8757 AC-11), not a credential
+
+  function checkoutSubmit() {
+    return app.inject({
+      method: "POST",
+      url: "/v1/leads/submit",
+      headers: { "idempotency-key": CHECKOUT_KEY },
+      payload: {
+        kind: "submit",
+        siteId: "default",
+        source: "web",
+        email: "cleo@x.io",
+        payload: { site: "wendi", page: "checkout", offering: "wendi_retainer" },
+      },
+    });
+  }
+
+  const routeLeadOptions = () => {
+    expect(mockRouteLead).toHaveBeenCalledTimes(1);
+    return mockRouteLead.mock.calls[0]![2] as Record<string, unknown>;
+  };
+
+  it("a spoke S1 submit calls routeLead with the spoke's origin", async () => {
+    mockResolveCallerSite.mockResolvedValue({ kind: "spoke", spokeId: S1, workspaceId: WS });
+    const res = await checkoutSubmit();
+    expect(res.statusCode).toBe(201);
+    expect(routeLeadOptions()).toEqual({
+      idempotencyKey: CHECKOUT_KEY,
+      accountOrigin: "https://spoke.example",
+    });
+    expect(mockFindClientByClientId).toHaveBeenCalledWith(S1);
+  });
+
+  it("a keyless submit under workspace calls routeLead with the site's origin", async () => {
+    const res = await checkoutSubmit();
+    expect(res.statusCode).toBe(201);
+    expect(routeLeadOptions()).toEqual({
+      idempotencyKey: CHECKOUT_KEY,
+      accountOrigin: "https://site.example",
+    });
+  });
+
+  it.each([
+    ["has no client", () => mockFindClientByClientId.mockResolvedValue(null)],
+    ["fails its client read", () => mockFindClientByClientId.mockRejectedValue(new Error("down"))],
+  ])("a spoke that %s calls routeLead with no accountOrigin, and still answers 201", async (_label, arrange) => {
+    mockResolveCallerSite.mockResolvedValue({ kind: "spoke", spokeId: S1, workspaceId: WS });
+    arrange();
+    const res = await checkoutSubmit();
+    expect(res.statusCode).toBe(201);
+    expect(routeLeadOptions()).toEqual({ idempotencyKey: CHECKOUT_KEY });
+  });
+
+  it("a submit that is not a checkout makes no origin read and passes no accountOrigin", async () => {
+    mockResolveCallerSite.mockResolvedValue({ kind: "spoke", spokeId: S1, workspaceId: WS });
+    const res = await submit("a@b.example", "contact-form");
+    expect(res.statusCode).toBe(201);
+    expect(routeLeadOptions()).toEqual({});
+    expect(mockFindClientByClientId).not.toHaveBeenCalled();
+  });
+
+  it("the 201 body is unchanged", async () => {
+    mockResolveCallerSite.mockResolvedValue({ kind: "spoke", spokeId: S1, workspaceId: WS });
+    const res = await checkoutSubmit();
+    expect(Object.keys(res.json()).sort()).toEqual(["email", "id", "persisted"]);
+  });
+});