create-ailk 0.27.0 → 0.28.0

package/templates/apps/web/app/[locale]/flows/[slug]/__tests__/save.actions.test.ts

@@ -0,0 +1,193 @@
+/**
+ * Tests for "Email me this plan" — `saveRecommendationAction` (#4842 D7),
+ * split out of `checkout.actions.ts` with its cases by #6786 so the save half
+ * ships with the results page while checkout stays commerce's.
+ *
+ * AC-4 (the action half) — calls `flows.save` once with
+ *   `{ answers, email, locale }` and returns the lead id.
+ * D7 — the shared status → kind map (`email-moment.ts`), never a throw;
+ *   an invalid body → `invalid_input` without calling the api-client.
+ *
+ * Mock shape: `checkout.actions.test.ts`'s (`@working-theory/api-client` +
+ * `next/headers`).
+ */
+
+import { saveRecommendationAction } from "../save.actions.js";
+
+// #9255 — the write bot check's verdict. `checkBotId` reads Vercel's
+// request context, which jest has none of, so every case decides it here.
+const checkBotIdMock = jest.fn();
+jest.mock("botid/server", () => ({
+  checkBotId: (...args: unknown[]) => checkBotIdMock(...args),
+}));
+
+jest.mock("@working-theory/api-client", () => ({
+  flows: {
+    save: jest.fn(),
+  },
+}));
+
+jest.mock("next/headers", () => ({
+  __esModule: true,
+  headers: jest.fn().mockResolvedValue({ get: () => null }),
+}));
+
+import { flows } from "@working-theory/api-client";
+import { headers } from "next/headers";
+
+const mockSave = flows.save as jest.Mock;
+const mockHeaders = headers as jest.Mock;
+
+const SLUG = "ailk-recommender";
+const ANSWERS = { team_size: "agency", wants_seo: "yes" };
+const SAVE_BODY = { answers: ANSWERS, email: "jane@example.com", locale: "en" };
+
+beforeEach(() => {
+  jest.spyOn(console, "error").mockImplementation(() => undefined);
+});
+
+afterEach(() => {
+  jest.clearAllMocks();
+  jest.restoreAllMocks();
+  mockHeaders.mockResolvedValue({ get: () => null });
+});
+
+describe("saveRecommendationAction — AC-4 (the action half)", () => {
+  it("calls flows.save once with { answers, email, locale } and returns the leadId", async () => {
+    mockSave.mockResolvedValueOnce({
+      ok: true,
+      body: { leadId: "lead_1", sessionId: "fs_1" },
+    });
+    await expect(saveRecommendationAction(SLUG, SAVE_BODY)).resolves.toEqual({
+      ok: true,
+      leadId: "lead_1",
+    });
+    expect(mockSave).toHaveBeenCalledTimes(1);
+    expect(mockSave).toHaveBeenCalledWith(SLUG, SAVE_BODY);
+  });
+
+  it("maps failures exactly as checkout does and never throws", async () => {
+    mockSave.mockResolvedValueOnce({
+      ok: false,
+      status: 429,
+      body: { retryAfterSeconds: 9 },
+    });
+    await expect(saveRecommendationAction(SLUG, SAVE_BODY)).resolves.toEqual({
+      ok: false,
+      kind: "rate_limited",
+      retryAfterSeconds: 9,
+    });
+    mockSave.mockRejectedValueOnce(new Error("boom"));
+    await expect(saveRecommendationAction(SLUG, SAVE_BODY)).resolves.toEqual({
+      ok: false,
+      kind: "network",
+    });
+    await expect(
+      saveRecommendationAction(SLUG, { ...SAVE_BODY, email: "nope" }),
+    ).resolves.toEqual({ ok: false, kind: "invalid_input" });
+    expect(mockSave).toHaveBeenCalledTimes(2);
+  });
+
+  it("forwards the visitor's x-forwarded-for on the outbound call (#4730)", async () => {
+    mockHeaders.mockResolvedValueOnce({
+      get: (name: string) =>
+        name === "x-forwarded-for" ? "203.0.113.7" : null,
+    });
+    mockSave.mockResolvedValueOnce({
+      ok: true,
+      body: { leadId: "lead_1", sessionId: "fs_1" },
+    });
+    await saveRecommendationAction(SLUG, SAVE_BODY);
+    expect(mockSave).toHaveBeenCalledWith(SLUG, SAVE_BODY, {
+      headers: { "x-forwarded-for": "203.0.113.7" },
+    });
+  });
+});
+
+// #9255 D4 — the write bot check runs after the slug and body checks,
+// immediately before the write (spec
+// docs/specs/9255-an-edge-bot-challenge-in-spec.md §5.1 AC-2).
+describe("saveRecommendationAction — the write bot check (#9255)", () => {
+  const BOT = {
+    isHuman: false,
+    isBot: true,
+    isVerifiedBot: false,
+    bypassed: false,
+  };
+  const HUMAN = { ...BOT, isHuman: true, isBot: false };
+  const BOT_ENV_KEYS = [
+    "VERCEL",
+    "AILK_BOT_CHECK",
+    "AILK_BOOKING_BOT_CHECK",
+  ] as const;
+  const priorBotEnv = new Map(
+    BOT_ENV_KEYS.map((name) => [name, process.env[name]]),
+  );
+
+  let botLogSpies: jest.SpyInstance[] = [];
+
+  beforeEach(() => {
+    checkBotIdMock.mockReset();
+    for (const name of BOT_ENV_KEYS) delete process.env[name];
+    process.env.VERCEL = "1";
+    botLogSpies = [
+      jest.spyOn(console, "warn").mockImplementation(() => undefined),
+      jest.spyOn(console, "error").mockImplementation(() => undefined),
+    ];
+  });
+
+  afterEach(() => {
+    for (const [name, value] of priorBotEnv) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+    for (const spy of botLogSpies) spy.mockRestore();
+  });
+
+  it.each([
+    ["a bot", () => checkBotIdMock.mockResolvedValue(BOT)],
+    [
+      "a check that fails",
+      () => checkBotIdMock.mockRejectedValue(new Error("boom")),
+    ],
+  ])(
+    "%s gets kind unavailable, and nothing is sent",
+    async (_label, decide) => {
+      decide();
+      expect(await saveRecommendationAction(SLUG, SAVE_BODY)).toStrictEqual({
+        ok: false,
+        kind: "unavailable",
+      });
+      expect(checkBotIdMock).toHaveBeenCalledTimes(1);
+      expect(mockSave).not.toHaveBeenCalled();
+    },
+  );
+
+  it("a human sends exactly what the check off sends", async () => {
+    checkBotIdMock.mockResolvedValue(HUMAN);
+    mockSave.mockResolvedValue({
+      ok: true,
+      status: 201,
+      body: { leadId: "lead_1" },
+    });
+    delete process.env.VERCEL;
+    await saveRecommendationAction(SLUG, SAVE_BODY);
+    process.env.VERCEL = "1";
+    expect(await saveRecommendationAction(SLUG, SAVE_BODY)).toEqual({
+      ok: true,
+      leadId: "lead_1",
+    });
+    expect(checkBotIdMock).toHaveBeenCalledTimes(1);
+    expect(mockSave).toHaveBeenCalledTimes(2);
+    expect(mockSave.mock.calls[1]).toEqual(mockSave.mock.calls[0]);
+  });
+
+  it("an invalid slug answers invalid_input with no check", async () => {
+    checkBotIdMock.mockResolvedValue(BOT);
+    expect(await saveRecommendationAction("Not A Slug", SAVE_BODY)).toEqual({
+      ok: false,
+      kind: "invalid_input",
+    });
+    expect(checkBotIdMock).not.toHaveBeenCalled();
+  });
+});

package/templates/apps/web/app/[locale]/flows/[slug]/email-moment.ts

@@ -0,0 +1,92 @@
+// oss: false
+/**
+ * email-moment.ts — the helpers the recommender's two email-moment Server
+ * Actions share (#4842 D7): `saveRecommendationAction` (`save.actions.ts`,
+ * shipped with the results page) and `startCheckoutAction`
+ * (`checkout.actions.ts`, commerce's). Split out of `checkout.actions.ts` by
+ * #6786 so the save half ships without the checkout half; a `"use server"`
+ * file may export only async functions, so the shared sync helpers live here.
+ *
+ * Both actions mirror `submitFlowStepAction`'s idiom exactly: the visitor-IP
+ * forwarding helper (duplicated here — the `flow.actions.ts` original is
+ * module-private and that file is this unit's regression floor), a status →
+ * kind map, and NEVER a throw to the client. Logging is PII-safe: slug + kind
+ * only — the email is never logged.
+ */
+import type { FlowSaveInput } from "@working-theory/validation";
+import { headers } from "next/headers";
+
+export type EmailMomentFailureKind =
+  | "invalid_input"
+  | "not_configured"
+  | "rate_limited"
+  | "unavailable"
+  | "network";
+
+export interface EmailMomentFailure {
+  ok: false;
+  kind: EmailMomentFailureKind;
+  retryAfterSeconds?: number;
+}
+
+/**
+ * Reads the visitor's real IP from THIS action's own incoming request —
+ * never from the browser-supplied payload — preferring `x-forwarded-for`
+ * and falling back to `x-real-ip`. Returns `undefined` rather than throwing
+ * on any failure (a local copy of `flow.actions.ts`'s helper, #4730).
+ */
+export async function resolveVisitorIpInit(): Promise<
+  { headers: Record<string, string> } | undefined
+> {
+  try {
+    const incoming = await headers();
+    const visitorIp =
+      incoming.get("x-forwarded-for") ?? incoming.get("x-real-ip");
+    return visitorIp
+      ? { headers: { "x-forwarded-for": visitorIp } }
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** PII-safe error identity for logs — the `recommender.ts` idiom (`err.name` only). */
+export function errorName(err: unknown): string {
+  return err instanceof Error ? err.name : "unknown";
+}
+
+/** The shared `status → kind` map (D7). Never throws. */
+export function failureFor(res: {
+  status: number;
+  body: unknown;
+}): EmailMomentFailure {
+  if (res.status === 400) return { ok: false, kind: "invalid_input" };
+  if (res.status === 409) return { ok: false, kind: "not_configured" };
+  if (res.status === 429) {
+    const body = res.body as { retryAfterSeconds?: number } | null;
+    return {
+      ok: false,
+      kind: "rate_limited",
+      ...(typeof body?.retryAfterSeconds === "number"
+        ? { retryAfterSeconds: body.retryAfterSeconds }
+        : {}),
+    };
+  }
+  return { ok: false, kind: "unavailable" };
+}
+
+/**
+ * exactOptionalPropertyTypes-safe rebuild of the parsed body: Zod's inferred
+ * optional fields type as `T | undefined`, which does not structurally match
+ * the api-client's `sessionId?: string` / `locale?: string` — so an absent
+ * optional key is OMITTED rather than sent as an explicit `undefined`.
+ */
+export function emailMomentFields(parsed: FlowSaveInput): FlowSaveInput {
+  const { answers, email, locale, sessionId } = parsed;
+  return {
+    answers,
+    email,
+    ...(locale !== undefined ? { locale } : {}),
+    ...(sessionId !== undefined ? { sessionId } : {}),
+  };
+}

package/templates/apps/web/app/[locale]/flows/[slug]/flow.actions.ts

@@ -37,6 +37,7 @@ import {
 } from "@working-theory/validation";
 import { cookies, headers } from "next/headers";
 
+import { runBotCheck } from "../../../../lib/bot-check";
 import { consentVisitorHeader, readConsentVisitor } from "../../../../lib/consent-visitor";
 
 /**
@@ -106,6 +107,15 @@ export async function submitFlowStepAction(
     };
   }
 
+  // #9255 D4 — the spoke edge's bot check, after the input checks and before
+  // the write. A refusal is the walk's existing "try again" variant.
+  const botCheck = await runBotCheck({
+    source: "bot-check",
+    target: "submitFlowStepAction",
+    scope: "write",
+  });
+  if (botCheck !== "pass") return { ok: false, kind: "network" };
+
   try {
     // exactOptionalPropertyTypes-safe: submitFlowStepInputSchema's Zod-inferred
     // optional fields type as `T | undefined`, which does not structurally