create-ailk 0.1.0 → 0.2.0

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

@@ -0,0 +1,302 @@
+/**
+ * Tests for submitFlowStepAction Server Action (#3957 D8).
+ *
+ * Acceptance criteria verified here:
+ * - submitFlowStepAction(slug, validPayload) calls api-client flows.submitStep
+ *   and returns { ok: true, response } passthrough.
+ * - invalid slug / invalid payload → { ok: false, kind: "invalid_input" }
+ *   without calling api-client.
+ * - api-client 400 → kind "invalid_input"; 409 → kind "step_conflict";
+ *   429 → kind "rate_limited" carrying retryAfterSeconds; other statuses /
+ *   a thrown error → kind "network".
+ * - #4730 — the visitor's `x-forwarded-for` (read from THIS action's own
+ *   incoming request via next/headers) is forwarded on the outbound
+ *   flows.submitStep call; absent entirely when no header is present.
+ * - Parity: submitFlowStepAction is paired with ailkSubmitFlowStep per ADR 0013.
+ */
+
+import { submitFlowStepAction } from "../flow.actions.js";
+
+jest.mock("@working-theory/api-client", () => ({
+  flows: {
+    submitStep: jest.fn(),
+  },
+}));
+
+// #4730 — default: no incoming headers to forward, matching every
+// pre-existing test's 2-arg `flows.submitStep(slug, payload)` expectation
+// byte-for-byte. Individual #4730 tests override with a real x-forwarded-for.
+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 mockSubmitStep = flows.submitStep as jest.Mock;
+const mockHeaders = headers as jest.Mock;
+
+afterEach(() => {
+  jest.clearAllMocks();
+  mockHeaders.mockResolvedValue({ get: () => null });
+});
+
+const VALID_PAYLOAD = {
+  stepKey: "contact",
+  values: { email: "jane@example.com" },
+};
+
+describe("submitFlowStepAction — valid input", () => {
+  it("calls flows.submitStep and returns the response passthrough on success", async () => {
+    mockSubmitStep.mockResolvedValueOnce({
+      ok: true,
+      body: {
+        sessionId: "sess1",
+        landed: "contact",
+        nextStepKey: "budget",
+        completed: false,
+      },
+    });
+
+    const result = await submitFlowStepAction("get-a-quote", VALID_PAYLOAD);
+
+    expect(mockSubmitStep).toHaveBeenCalledWith(
+      "get-a-quote",
+      expect.objectContaining(VALID_PAYLOAD),
+    );
+    expect(result).toEqual({
+      ok: true,
+      response: {
+        sessionId: "sess1",
+        landed: "contact",
+        nextStepKey: "budget",
+        completed: false,
+      },
+    });
+  });
+
+  it("threads sessionId and locale through to the api-client call", async () => {
+    mockSubmitStep.mockResolvedValueOnce({
+      ok: true,
+      body: {
+        sessionId: "sess1",
+        landed: "budget",
+        nextStepKey: "thanks",
+        completed: false,
+      },
+    });
+
+    await submitFlowStepAction("get-a-quote", {
+      sessionId: "sess1",
+      stepKey: "budget",
+      values: { budget: "small" },
+      locale: "en",
+    });
+
+    expect(mockSubmitStep).toHaveBeenCalledWith("get-a-quote", {
+      sessionId: "sess1",
+      stepKey: "budget",
+      values: { budget: "small" },
+      locale: "en",
+    });
+  });
+});
+
+describe("submitFlowStepAction — invalid input", () => {
+  it("returns invalid_input without calling api-client for a malformed slug", async () => {
+    const result = await submitFlowStepAction("Not A Slug!", VALID_PAYLOAD);
+
+    expect(result).toMatchObject({ ok: false, kind: "invalid_input" });
+    expect(mockSubmitStep).not.toHaveBeenCalled();
+  });
+
+  it("returns invalid_input without calling api-client for a missing stepKey", async () => {
+    const result = await submitFlowStepAction("get-a-quote", {
+      stepKey: "",
+      values: {},
+    });
+
+    expect(result).toMatchObject({ ok: false, kind: "invalid_input" });
+    expect(mockSubmitStep).not.toHaveBeenCalled();
+  });
+});
+
+describe("submitFlowStepAction — api-client failure mapping", () => {
+  it("maps a 400 response to kind invalid_input", async () => {
+    mockSubmitStep.mockResolvedValueOnce({ ok: false, status: 400, body: {} });
+
+    const result = await submitFlowStepAction("get-a-quote", VALID_PAYLOAD);
+
+    expect(result).toEqual({ ok: false, kind: "invalid_input" });
+  });
+
+  it("maps a 409 response to kind step_conflict", async () => {
+    mockSubmitStep.mockResolvedValueOnce({ ok: false, status: 409, body: {} });
+
+    const result = await submitFlowStepAction("get-a-quote", VALID_PAYLOAD);
+
+    expect(result).toEqual({ ok: false, kind: "step_conflict" });
+  });
+
+  it("maps a 429 response to kind rate_limited, carrying retryAfterSeconds (#4730)", async () => {
+    mockSubmitStep.mockResolvedValueOnce({
+      ok: false,
+      status: 429,
+      body: { error: "rate_limited", retryAfterSeconds: 37 },
+    });
+
+    const result = await submitFlowStepAction("get-a-quote", VALID_PAYLOAD);
+
+    expect(result).toEqual({
+      ok: false,
+      kind: "rate_limited",
+      retryAfterSeconds: 37,
+    });
+  });
+
+  it("maps a 429 response with no retryAfterSeconds to kind rate_limited alone (#4730)", async () => {
+    mockSubmitStep.mockResolvedValueOnce({ ok: false, status: 429, body: {} });
+
+    const result = await submitFlowStepAction("get-a-quote", VALID_PAYLOAD);
+
+    expect(result).toEqual({ ok: false, kind: "rate_limited" });
+  });
+
+  it("maps any other failing status to kind network", async () => {
+    mockSubmitStep.mockResolvedValueOnce({ ok: false, status: 500, body: {} });
+
+    const result = await submitFlowStepAction("get-a-quote", VALID_PAYLOAD);
+
+    expect(result).toEqual({ ok: false, kind: "network" });
+  });
+
+  it("maps a thrown error to kind network", async () => {
+    mockSubmitStep.mockRejectedValueOnce(new Error("network down"));
+
+    const result = await submitFlowStepAction("get-a-quote", VALID_PAYLOAD);
+
+    expect(result).toEqual({ ok: false, kind: "network" });
+  });
+
+  it("logs a thrown error server-side without leaking submitted values", async () => {
+    const thrown = new Error("network down");
+    mockSubmitStep.mockRejectedValueOnce(thrown);
+    const consoleErrorSpy = jest
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+
+    const result = await submitFlowStepAction("get-a-quote", VALID_PAYLOAD);
+
+    expect(result).toEqual({ ok: false, kind: "network" });
+    expect(consoleErrorSpy).toHaveBeenCalledTimes(1);
+    const [logLine, loggedErr] = consoleErrorSpy.mock.calls[0] as [
+      string,
+      unknown,
+    ];
+    expect(logLine).toContain("[submitFlowStepAction]");
+    expect(logLine).toContain("get-a-quote");
+    expect(logLine).toContain(VALID_PAYLOAD.stepKey);
+    expect(logLine).not.toContain("jane@example.com");
+    expect(loggedErr).toBe(thrown);
+
+    consoleErrorSpy.mockRestore();
+  });
+});
+
+describe("submitFlowStepAction — visitor IP forwarding (#4730)", () => {
+  it("forwards x-forwarded-for from the action's own incoming request as init.headers", async () => {
+    mockHeaders.mockResolvedValueOnce({
+      get: (name: string) =>
+        name === "x-forwarded-for" ? "203.0.113.7, 9.9.9.9" : null,
+    });
+    mockSubmitStep.mockResolvedValueOnce({
+      ok: true,
+      body: {
+        sessionId: "sess1",
+        landed: "contact",
+        nextStepKey: "budget",
+        completed: false,
+      },
+    });
+
+    await submitFlowStepAction("get-a-quote", VALID_PAYLOAD);
+
+    expect(mockSubmitStep).toHaveBeenCalledWith(
+      "get-a-quote",
+      expect.objectContaining(VALID_PAYLOAD),
+      { headers: { "x-forwarded-for": "203.0.113.7, 9.9.9.9" } },
+    );
+  });
+
+  it("falls back to x-real-ip when x-forwarded-for is absent", async () => {
+    mockHeaders.mockResolvedValueOnce({
+      get: (name: string) => (name === "x-real-ip" ? "198.51.100.4" : null),
+    });
+    mockSubmitStep.mockResolvedValueOnce({
+      ok: true,
+      body: {
+        sessionId: "sess1",
+        landed: "contact",
+        nextStepKey: "budget",
+        completed: false,
+      },
+    });
+
+    await submitFlowStepAction("get-a-quote", VALID_PAYLOAD);
+
+    expect(mockSubmitStep).toHaveBeenCalledWith(
+      "get-a-quote",
+      expect.objectContaining(VALID_PAYLOAD),
+      { headers: { "x-forwarded-for": "198.51.100.4" } },
+    );
+  });
+
+  it("calls flows.submitStep with exactly two arguments when no visitor IP header is present", async () => {
+    // Default mock (no x-forwarded-for / x-real-ip) — mirrors every other
+    // test in this file; asserted explicitly here as the #4730 regression
+    // floor: no header ⇒ no third argument, ever an explicit `undefined`.
+    mockSubmitStep.mockResolvedValueOnce({
+      ok: true,
+      body: {
+        sessionId: "sess1",
+        landed: "contact",
+        nextStepKey: "budget",
+        completed: false,
+      },
+    });
+
+    await submitFlowStepAction("get-a-quote", VALID_PAYLOAD);
+
+    expect(mockSubmitStep).toHaveBeenCalledWith(
+      "get-a-quote",
+      expect.objectContaining(VALID_PAYLOAD),
+    );
+    expect(mockSubmitStep.mock.calls[0]).toHaveLength(2);
+  });
+
+  it("degrades to no forwarded header when headers() itself throws", async () => {
+    mockHeaders.mockRejectedValueOnce(new Error("no request scope"));
+    mockSubmitStep.mockResolvedValueOnce({
+      ok: true,
+      body: {
+        sessionId: "sess1",
+        landed: "contact",
+        nextStepKey: "budget",
+        completed: false,
+      },
+    });
+
+    const result = await submitFlowStepAction("get-a-quote", VALID_PAYLOAD);
+
+    expect(result).toEqual({
+      ok: true,
+      response: {
+        sessionId: "sess1",
+        landed: "contact",
+        nextStepKey: "budget",
+        completed: false,
+      },
+    });
+    expect(mockSubmitStep.mock.calls[0]).toHaveLength(2);
+  });
+});

package/templates/apps/web/app/[locale]/flows/[slug]/__tests__/two-route-tool.test.tsx

@@ -0,0 +1,128 @@
+/**
+ * #5053 — an interactive tool is two routes.
+ *
+ * The defect this convention closes is SILENT: a flow mounted at a bare
+ * route renders fine, the walk works, and nothing surfaces that the tool is
+ * invisible to search and to answer engines. So the assertions below are the
+ * only thing standing between the convention and a quiet regression.
+ *
+ * Three claims are pinned here:
+ *   1. The flow route carries `noindex, follow` — and gets it from
+ *      `flowRouteMetadata`, not from a robots line written into the route
+ *      (D4: mounted, not remembered). The source-level assertion is
+ *      deliberate: re-inlining the value would satisfy a value-only test
+ *      while losing the property the decision is actually about.
+ *   2. The landing route sets no `robots` at all, so it indexes.
+ *   3. The landing emits the `Assessment` page type's SINGLE-LAYER
+ *      `@type: "WebApplication"` — no `WebPage` envelope, no `mainEntity`
+ *      (D2, resting on #5019). The consuming site's two-layer shape is not
+ *      adopted, and this is what fails if someone adopts it.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { render } from "@testing-library/react";
+import type { FlowConfig } from "@working-theory/validation";
+
+const mockGet = jest.fn();
+jest.mock("@working-theory/api-client", () => ({
+  __esModule: true,
+  flows: { get: (...args: unknown[]) => mockGet(...args) },
+}));
+
+jest.mock("next/navigation", () => ({
+  __esModule: true,
+  notFound: () => {
+    throw new Error("NEXT_NOT_FOUND");
+  },
+}));
+
+jest.mock("next-intl/server", () => ({
+  __esModule: true,
+  getTranslations: async () => (key: string) => key,
+}));
+
+jest.mock("@working-theory/ui/sections", () => ({
+  __esModule: true,
+  SectionRenderer: () => null,
+}));
+
+import LandingPage, { generateMetadata as landingMetadata } from "../page";
+import { generateMetadata as flowMetadata } from "../start/page";
+
+const SLUG = "readiness-check";
+
+function fixtureConfig(): FlowConfig {
+  return {
+    slug: SLUG,
+    defaultLocale: "en",
+    steps: [
+      {
+        key: "team",
+        type: "segmentation",
+        copy: { title: { en: "How ready is your site?" } },
+        questions: [
+          {
+            name: "team_size",
+            options: [
+              { value: "solo", label: { en: "Solo" } },
+              { value: "agency", label: { en: "Agency" } },
+            ],
+          },
+        ],
+      },
+    ],
+  } as FlowConfig;
+}
+
+beforeEach(() => {
+  mockGet.mockReset();
+  mockGet.mockResolvedValue({ ok: true, body: fixtureConfig() });
+});
+
+const params = Promise.resolve({ locale: "en", slug: SLUG });
+
+describe("the flow route", () => {
+  it("carries noindex, follow", async () => {
+    const metadata = await flowMetadata({ params });
+    expect(metadata.robots).toEqual({ index: false, follow: true });
+  });
+
+  it("still carries noindex, follow when the flow is not configured", async () => {
+    mockGet.mockResolvedValue({ ok: false, error: "flow_not_found" });
+    const metadata = await flowMetadata({ params });
+    expect(metadata.robots).toEqual({ index: false, follow: true });
+  });
+
+  it("gets the value from flowRouteMetadata rather than writing it", () => {
+    const code = readFileSync(
+      join(__dirname, "..", "start", "page.tsx"),
+      "utf8",
+    )
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/\/\/.*$/gm, "");
+    expect(code).toContain("flowRouteMetadata");
+    expect(code).not.toMatch(/robots/i);
+    expect(code).not.toMatch(/noindex/i);
+  });
+});
+
+describe("the landing route", () => {
+  it("sets no robots value, so it indexes", async () => {
+    const metadata = await landingMetadata({ params });
+    expect(metadata.robots).toBeUndefined();
+    expect(metadata.title).toBe("How ready is your site?");
+  });
+
+  it("emits the single-layer WebApplication shape, with no WebPage envelope", async () => {
+    const { container } = render(await LandingPage({ params }));
+    const script = container.querySelector(
+      'script[type="application/ld+json"]',
+    );
+    const emitted = JSON.parse(script!.innerHTML) as Record<string, unknown>;
+
+    expect(emitted["@type"]).toBe("WebApplication");
+    expect(emitted).not.toHaveProperty("mainEntity");
+    expect(emitted["name"]).toBe("How ready is your site?");
+  });
+});

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

@@ -0,0 +1,254 @@
+"use server";
+
+/**
+ * checkout.actions.ts — the recommender's two email-moment Server Actions
+ * (#4842 D7), siblings of `flow.actions.ts` (ADR 0013 `*.actions.ts`):
+ *
+ *   - `startCheckoutAction` — Pay: validates with the shared
+ *     `flowCheckoutInputSchema` (#4841 — a body with NO money field; the
+ *     server recomputes `price()` from the register it served, PRD L104),
+ *     calls `flows.checkout`, and on `ok` hands the visitor to Stripe's
+ *     hosted page via `redirect(url)` (D1 — hosted Checkout, Sam 2026-09-05).
+ *   - `saveRecommendationAction` — "Email me this plan": validates with
+ *     `flowSaveInputSchema`, calls `flows.save`, returns the lead id.
+ *
+ * Both mirror `submitFlowStepAction`'s idiom exactly: shared-schema
+ * validation, 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.
+ *
+ * `redirect()` throws `NEXT_REDIRECT` by design, so it is called OUTSIDE the
+ * try/catch that maps a thrown api-client error to `network` — inside it,
+ * the catch would swallow the very navigation the action exists to perform.
+ *
+ * The Stripe return URLs are BUILT HERE, never accepted from the client
+ * (security review, #4875): a direct caller could otherwise mint a session
+ * that redirects post-payment to an arbitrary host, since the shared
+ * `flowRedirectUrlSchema` pins only `http(s)` + a host. The client hands over
+ * the permalink `payload` it already has; the action decodes it, requires it
+ * to name THIS flow, and composes `<site origin>/<safe locale>/flows/<slug>/
+ * results/<payload>?checkout=success|cancelled` from the app's own configured
+ * origin (`resolveBaseUrl()` — the same source `layout.tsx` / `sitemap.xml`
+ * use for every absolute URL).
+ */
+
+import { flows } from "@working-theory/api-client";
+import type { FlowCheckoutInputRaw, FlowSaveInput } from "@working-theory/validation";
+import {
+  decodePermalink,
+  flowCheckoutInputSchema,
+  flowSaveInputSchema,
+  flowSlugSchema,
+} from "@working-theory/validation";
+import { headers } from "next/headers";
+import { redirect } from "next/navigation";
+
+import { resolveBaseUrl } from "../../../../src/lib/routes";
+
+export type EmailMomentFailureKind =
+  | "invalid_input"
+  | "not_configured"
+  | "rate_limited"
+  | "unavailable"
+  | "network";
+
+export interface EmailMomentFailure {
+  ok: false;
+  kind: EmailMomentFailureKind;
+  retryAfterSeconds?: number;
+}
+
+/** `startCheckoutAction` never returns on success — it `redirect()`s. */
+export type CheckoutActionResult = EmailMomentFailure;
+
+/**
+ * The client-supplied checkout input: the wire body MINUS the two return
+ * URLs (server-built, above) PLUS the permalink `payload` they are built from.
+ */
+export type StartCheckoutInput = Omit<FlowCheckoutInputRaw, "successUrl" | "cancelUrl"> & {
+  payload: string;
+};
+
+// Mirrors `FlowStepperClient.tsx:80–88` (#4707) — the locale segment of a
+// built URL is validated against the same build-time-baked allowlist, never
+// interpolated raw.
+const DEFAULT_LOCALE = "en";
+const ENABLED_LOCALES = (process.env.NEXT_PUBLIC_ENABLED_LOCALES ?? DEFAULT_LOCALE).split(",");
+
+/** Validate a candidate locale against the configured set; unknown → default. */
+function resolveSafeLocale(candidate: string): string {
+  return ENABLED_LOCALES.includes(candidate) ? candidate : DEFAULT_LOCALE;
+}
+
+/**
+ * The permalink's absolute URL on THIS site, or `undefined` when the payload
+ * is not a valid permalink of `slug` (never a URL to somewhere else).
+ */
+function permalinkUrlFor(slug: string, locale: string, payload: string): string | undefined {
+  const decoded = decodePermalink(payload);
+  if (!decoded.ok || decoded.value.flowSlug !== slug) return undefined;
+  const origin = resolveBaseUrl().replace(/\/+$/, "");
+  return `${origin}/${resolveSafeLocale(locale)}/flows/${slug}/results/${payload}`;
+}
+
+export type SaveActionResult = { ok: true; leadId: string } | EmailMomentFailure;
+
+/**
+ * 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).
+ */
+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). */
+function errorName(err: unknown): string {
+  return err instanceof Error ? err.name : "unknown";
+}
+
+/** The shared `status → kind` map (D7). Never throws. */
+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`.
+ */
+function emailMomentFields(parsed: FlowSaveInput): FlowSaveInput {
+  const { answers, email, locale, sessionId } = parsed;
+  return {
+    answers,
+    email,
+    ...(locale !== undefined ? { locale } : {}),
+    ...(sessionId !== undefined ? { sessionId } : {}),
+  };
+}
+
+export async function startCheckoutAction(
+  slug: string,
+  input: StartCheckoutInput,
+): Promise<CheckoutActionResult> {
+  const parsedSlug = flowSlugSchema.safeParse(slug);
+  if (!parsedSlug.success) return { ok: false, kind: "invalid_input" };
+
+  // Only the named fields cross into the wire body — a caller-supplied
+  // `successUrl` / `cancelUrl` (or any other stray key) is dropped here.
+  const { answers, email, locale, sessionId, offerKey, seats, period, creditStop, payload } =
+    input;
+  if (typeof payload !== "string" || payload.length === 0 || payload.length > 4096) {
+    return { ok: false, kind: "invalid_input" };
+  }
+  const permalinkUrl = permalinkUrlFor(parsedSlug.data, locale ?? DEFAULT_LOCALE, payload);
+  if (permalinkUrl === undefined) return { ok: false, kind: "invalid_input" };
+
+  const parsed = flowCheckoutInputSchema.safeParse({
+    answers,
+    email,
+    ...(locale !== undefined ? { locale } : {}),
+    ...(sessionId !== undefined ? { sessionId } : {}),
+    offerKey,
+    seats,
+    period,
+    ...(creditStop !== undefined ? { creditStop } : {}),
+    successUrl: `${permalinkUrl}?checkout=success`,
+    cancelUrl: `${permalinkUrl}?checkout=cancelled`,
+  });
+  if (!parsed.success) return { ok: false, kind: "invalid_input" };
+
+  const wireBody: FlowCheckoutInputRaw = {
+    ...emailMomentFields(parsed.data),
+    offerKey: parsed.data.offerKey,
+    seats: parsed.data.seats,
+    period: parsed.data.period,
+    creditStop: parsed.data.creditStop,
+    successUrl: parsed.data.successUrl,
+    cancelUrl: parsed.data.cancelUrl,
+  };
+
+  let url: string;
+  try {
+    const visitorIpInit = await resolveVisitorIpInit();
+    const res = visitorIpInit
+      ? await flows.checkout(parsedSlug.data, wireBody, visitorIpInit)
+      : await flows.checkout(parsedSlug.data, wireBody);
+    if (!res.ok) {
+      const failure = failureFor(res);
+      console.error(
+        `[startCheckoutAction] slug=${parsedSlug.data} kind=${failure.kind} status=${res.status}`,
+      );
+      return failure;
+    }
+    url = res.body.url;
+  } catch (err) {
+    // Name only — never the error object (it can carry the request payload).
+    console.error(
+      `[startCheckoutAction] slug=${parsedSlug.data} kind=network errName=${errorName(err)}`,
+    );
+    return { ok: false, kind: "network" };
+  }
+
+  // Outside the try/catch on purpose — see the file header.
+  redirect(url);
+}
+
+export async function saveRecommendationAction(
+  slug: string,
+  body: FlowSaveInput,
+): Promise<SaveActionResult> {
+  const parsedSlug = flowSlugSchema.safeParse(slug);
+  if (!parsedSlug.success) return { ok: false, kind: "invalid_input" };
+
+  const parsed = flowSaveInputSchema.safeParse(body);
+  if (!parsed.success) return { ok: false, kind: "invalid_input" };
+
+  const payload = emailMomentFields(parsed.data);
+
+  try {
+    const visitorIpInit = await resolveVisitorIpInit();
+    const res = visitorIpInit
+      ? await flows.save(parsedSlug.data, payload, visitorIpInit)
+      : await flows.save(parsedSlug.data, payload);
+    if (!res.ok) {
+      const failure = failureFor(res);
+      console.error(
+        `[saveRecommendationAction] slug=${parsedSlug.data} kind=${failure.kind} status=${res.status}`,
+      );
+      return failure;
+    }
+    return { ok: true, leadId: res.body.leadId };
+  } catch (err) {
+    console.error(
+      `[saveRecommendationAction] slug=${parsedSlug.data} kind=network errName=${errorName(err)}`,
+    );
+    return { ok: false, kind: "network" };
+  }
+}