create-ailk 0.22.0 → 0.23.0

package/templates/apps/web/lib/__tests__/auth-routes.test.ts

@@ -7,7 +7,7 @@
  * and the absent-header fail-safe — and the same for `isAccountPath()` (#7430).
  */
 
-import { AUTH_SEGMENTS, isAccountPath, isAuthPath } from "../auth-routes";
+import { AUTH_SEGMENTS, isAccountPath, isAuthPath, isBookingPath } from "../auth-routes";
 
 const LOCALES = ["en", "fr", "de"];
 
@@ -111,3 +111,29 @@ describe("isAccountPath (#7430, spec 7423 D4)", () => {
     expect(isAccountPath(null, LOCALES)).toBe(false);
   });
 });
+
+// #8843 D10 — the booking pages render without the marketing chrome.
+describe("isBookingPath (#8843)", () => {
+  it("matches /meet, a meeting page and /private, bare or locale-prefixed", () => {
+    for (const path of ["/meet", "/meet/", "/meet/intro", "/en/meet/intro", "/fr/meet", "/private", "/fr/private"]) {
+      expect(isBookingPath(path, LOCALES)).toBe(true);
+    }
+  });
+
+  it("does not match the confirmation page, which keeps the marketing chrome", () => {
+    expect(isBookingPath("/meet/confirmed", LOCALES)).toBe(false);
+    expect(isBookingPath("/fr/meet/confirmed", LOCALES)).toBe(false);
+  });
+
+  it("does not match a near miss or a marketing path", () => {
+    expect(isBookingPath("/meeting", LOCALES)).toBe(false);
+    expect(isBookingPath("/privacy", LOCALES)).toBe(false);
+    expect(isBookingPath("/blog/meet", LOCALES)).toBe(false);
+  });
+
+  it("fails to NOT-a-booking-path for an empty or absent pathname", () => {
+    expect(isBookingPath("", LOCALES)).toBe(false);
+    expect(isBookingPath(undefined, LOCALES)).toBe(false);
+    expect(isBookingPath(null, LOCALES)).toBe(false);
+  });
+});

package/templates/apps/web/lib/__tests__/deck-page.test.ts

@@ -69,8 +69,9 @@ describe("deckCandidates (#8687 D3, AC-2)", () => {
     ]);
   });
 
-  it("/careers (gateable, no DECK_ROUTES entry) falls through to [slug]", () => {
+  it("/careers (sections mode since #8849) resolves the route row, then the [slug] fallback", () => {
     expect(deckCandidates("/careers", LOCALES)).toEqual([
+      { type: "CareersList", slug: "careers" },
       { type: "LandingPage", slug: "careers" },
       { type: "BlogList", slug: "careers" },
     ]);

package/templates/apps/web/lib/__tests__/in-page-magnet.test.ts

@@ -0,0 +1,265 @@
+/**
+ * lib/in-page-magnet.ts — the in-page form shape (#8847 D6, D15; AC-2).
+ *
+ * Pure mapping and loader wrapping; the two hub reads are mocked at
+ * `@working-theory/api-client`, and the Server Action modules are stubbed so
+ * the bound action is asserted by identity.
+ */
+import { LeadCaptureForm } from "@working-theory/ui";
+import {
+  contactFormFlowConfig,
+  newsletterFlowConfig,
+  type FlowConfig,
+} from "@working-theory/validation";
+
+jest.mock("@working-theory/api-client", () => ({
+  flows: { get: jest.fn() },
+  leads: { captureStatus: jest.fn() },
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- test-seam mock: a "use server" boundary the module only binds
+jest.mock("../../app/[locale]/contact/contact.actions", () => ({
+  captureLeadAction: jest.fn(),
+}));
+// eslint-disable-next-line no-restricted-syntax -- test-seam mock: a "use server" boundary the module only binds
+jest.mock("../newsletter.actions", () => ({
+  subscribeNewsletterAction: jest.fn(),
+}));
+
+import { flows } from "@working-theory/api-client";
+
+import { captureLeadAction } from "../../app/[locale]/contact/contact.actions";
+import {
+  fillEndingName,
+  framedSources,
+  inPageView,
+  readServedMagnet,
+  renderInPageMagnet,
+  type InPageView,
+} from "../in-page-magnet";
+
+const mockFlowsGet = flows.get as jest.Mock;
+
+type FieldStep = Extract<FlowConfig["steps"][number], { type: "field" }>;
+
+/** A request-a-quote shaped contact magnet: name, email, need. */
+const QUOTE: FlowConfig = {
+  slug: "quote",
+  defaultLocale: "en",
+  steps: [
+    {
+      key: "quote",
+      type: "field",
+      copy: { title: { en: "Request a quote" }, body: { en: "Tell us the job." }, cta: { en: "Ask" } },
+      fields: [
+        { name: "name", inputType: "text", required: true, mapsTo: "name", copy: { label: { en: "Name" } } },
+        { name: "email", inputType: "email", required: true, mapsTo: "email", copy: { label: { en: "Email" } } },
+        { name: "need", inputType: "textarea", required: false, copy: { label: { en: "What do you need?" } } },
+      ],
+    },
+  ],
+};
+
+const TEXT = {
+  unavailableHeading: "Unavailable",
+  unavailableBody: "Write to {email}.",
+  unavailableNoEmail: "No email.",
+};
+
+describe("fillEndingName (#8841 D1's rule)", () => {
+  it("drops {name} with its comma when there is no name, and fills it when there is", () => {
+    expect(fillEndingName("Thanks, {name}.", "")).toBe("Thanks.");
+    expect(fillEndingName("Thanks, {name}.", "Ada")).toBe("Thanks, Ada.");
+  });
+});
+
+describe("inPageView — the form comes from the caller (C1)", () => {
+  it("a quote-shaped config asked for as contact maps its fields, title and body", () => {
+    const view = inPageView(QUOTE, "en", "contact")!;
+    expect(view.title).toBe("Request a quote");
+    expect(view.body).toBe("Tell us the job.");
+    expect(view.stepKey).toBe("quote");
+    expect("fields" in view.form && view.form.fields.map((f) => f.name)).toEqual(["name", "email", "need"]);
+  });
+
+  it("the newsletter config asked for as contact is null — it has no name field", () => {
+    expect(inPageView(newsletterFlowConfig, "en", "contact")).toBeNull();
+  });
+
+  it("the newsletter shape served at another slug maps when the caller asks for newsletter", () => {
+    const updates = { ...newsletterFlowConfig, slug: "updates" };
+    const view = inPageView(updates, "en", "newsletter")!;
+    expect(view.form).toMatchObject({
+      kind: "newsletter",
+      emailField: "email",
+      label: "Email",
+      placeholder: "you@example.com",
+      consent: { field: "terms", purposes: ["newsletter"], help: "No spam. Unsubscribe any time." },
+      submitLabel: "Subscribe",
+    });
+    expect(view.ending).toEqual({
+      kind: "screen",
+      headline: "Check your inbox",
+      body: "Your welcome email is on its way.",
+    });
+  });
+
+  it("a newsletter view is null with any other field to fill in, or a second step", () => {
+    const extra = JSON.parse(JSON.stringify(newsletterFlowConfig)) as FlowConfig;
+    (extra.steps[0] as FieldStep).fields.push({
+      name: "company",
+      inputType: "text",
+      copy: { label: { en: "Company" } },
+    });
+    expect(inPageView(extra, "en", "newsletter")).toBeNull();
+    const twoSteps = { ...newsletterFlowConfig, steps: [...newsletterFlowConfig.steps, ...QUOTE.steps] };
+    expect(inPageView(twoSteps, "en", "newsletter")).toBeNull();
+  });
+
+  it("the Contact form's ending is its config's; a config with none ends on the caller's line", () => {
+    expect(inPageView(contactFormFlowConfig, "en", "contact")!.ending).toEqual({
+      kind: "screen",
+      headline: "Message sent.",
+      body: "Thanks for getting in touch. I reply within one business day.",
+    });
+    expect(inPageView(QUOTE, "en", "contact", "Thank you!")!.ending).toEqual({
+      kind: "screen",
+      headline: "Thank you!",
+    });
+  });
+
+  it("an off-site redirect or button is dropped, never rendered (security review)", () => {
+    const offSite = {
+      ...QUOTE,
+      ending: { default: { kind: "redirect" as const, href: "https://evil.example/x" } },
+    } as FlowConfig;
+    expect(inPageView(offSite, "en", "contact", "Thanks")!.ending).toEqual({ kind: "screen", headline: "Thanks" });
+    const buttons = {
+      ...QUOTE,
+      ending: {
+        default: {
+          kind: "screen" as const,
+          headline: { en: "Done" },
+          ctas: [
+            { label: { en: "Evil" }, href: "//evil.example" },
+            { label: { en: "Home" }, href: "/" },
+          ],
+        },
+      },
+    } as FlowConfig;
+    expect(inPageView(buttons, "en", "contact")!.ending).toEqual({
+      kind: "screen",
+      headline: "Done",
+      ctas: [{ label: "Home", href: "/" }],
+    });
+  });
+
+  it("a redirect ending and a screen's buttons are localized", () => {
+    const redirect = { ...QUOTE, ending: { default: { kind: "redirect" as const, href: "/thanks" } } };
+    expect(inPageView(redirect, "fr", "contact")!.ending).toEqual({ kind: "redirect", href: "/fr/thanks" });
+  });
+});
+
+describe("framedSources (D6)", () => {
+  const source = { frontmatter: { type: "ContactPage", slug: "contact", title: "Old title" }, body: "" };
+  const view: Pick<InPageView, "title" | "body"> = { title: "Say hello", body: "Two days, tops." };
+
+  it("with no contact-form section both loaders' output is unchanged", async () => {
+    const sections = [{ id: "faq", type: "faq", data: { items: [] } }];
+    const framed = framedSources({
+      getMdxSource: jest.fn().mockResolvedValue(source),
+      getPageSections: jest.fn().mockResolvedValue(sections),
+      view,
+    });
+    expect(await framed.getMdxSource("ContactPage", "contact", "en")).toBe(source);
+    expect(await framed.getPageSections(source.frontmatter)).toBe(sections);
+  });
+
+  it("a leading contact-form section takes the view's title and body, and so does the frontmatter title", async () => {
+    const sections = [
+      { id: "contact", type: "contact-form", data: { variant: "column", headline: "Old", description: "Old line", fields: [] } },
+    ];
+    const framed = framedSources({
+      getMdxSource: jest.fn().mockResolvedValue(source),
+      getPageSections: jest.fn().mockResolvedValue(sections),
+      view,
+    });
+    expect((await framed.getMdxSource("ContactPage", "contact", "en"))!.frontmatter.title).toBe("Say hello");
+    expect((await framed.getPageSections(source.frontmatter))[0]!.data).toMatchObject({
+      headline: "Say hello",
+      description: "Two days, tops.",
+    });
+  });
+
+  it("a view with no body deletes the section's description", async () => {
+    const sections = [{ id: "c", type: "contact-form", data: { description: "Old line", fields: [] } }];
+    const framed = framedSources({
+      getMdxSource: jest.fn().mockResolvedValue(source),
+      getPageSections: jest.fn().mockResolvedValue(sections),
+      view: { title: "Say hello" },
+    });
+    expect((await framed.getPageSections(source.frontmatter))[0]!.data).not.toHaveProperty("description");
+  });
+});
+
+describe("renderInPageMagnet (D15)", () => {
+  it("a quote magnet asked for as contact binds captureLeadAction, stamped with its flow source", () => {
+    const view = inPageView(QUOTE, "en", "contact")!;
+    const element = renderInPageMagnet({
+      slug: "quote",
+      locale: "en",
+      view,
+      text: { ...TEXT } as never,
+      accepting: true,
+    });
+    expect(element.type).toBe(LeadCaptureForm);
+    expect(element.props).toMatchObject({
+      action: captureLeadAction,
+      // captureLeadAction keeps only CONTACT_LEAD_SOURCES, so this lands as contact-form.
+      source: "flow:quote",
+      look: "column",
+      ending: view.ending,
+    });
+  });
+
+  it("capture off is ContactFallback with the site's email", () => {
+    const element = renderInPageMagnet({
+      slug: "quote",
+      locale: "en",
+      view: inPageView(QUOTE, "en", "contact")!,
+      text: { ...TEXT } as never,
+      accepting: false,
+      fallbackEmail: "hi@x.co",
+    });
+    expect(element.props).toMatchObject({ email: "hi@x.co" });
+  });
+});
+
+describe("a config with no ending (review M1)", () => {
+  it("has no ending unless the caller gives a fallback line", () => {
+    expect(inPageView(QUOTE, "en", "contact")).not.toHaveProperty("ending");
+  });
+});
+
+describe("readServedMagnet", () => {
+  it("a hub that never answers is null after the deadline, not a hung page (review H2)", async () => {
+    jest.useFakeTimers();
+    try {
+      mockFlowsGet.mockReturnValueOnce(new Promise(() => undefined));
+      const read = readServedMagnet("stalled");
+      jest.advanceTimersByTime(2_000);
+      expect(await read).toBeNull();
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it("is the served config, and null for a non-2xx or a throw", async () => {
+    mockFlowsGet.mockResolvedValueOnce({ ok: true, status: 200, body: QUOTE });
+    expect(await readServedMagnet("quote")).toBe(QUOTE);
+    mockFlowsGet.mockResolvedValueOnce({ ok: false, status: 404, body: {} });
+    expect(await readServedMagnet("absent")).toBeNull();
+    mockFlowsGet.mockRejectedValueOnce(new Error("hub down"));
+    expect(await readServedMagnet("down")).toBeNull();
+  });
+});

package/templates/apps/web/lib/__tests__/magnet-routes.test.ts

@@ -0,0 +1,57 @@
+/**
+ * #8840 D10, AC-4 — the magnet walk predicate the layout drops the chrome on.
+ */
+import { isMagnetWalkPath } from "../magnet-routes";
+
+const LOCALES = ["en", "fr"];
+
+describe("isMagnetWalkPath (#8840 D10)", () => {
+  it.each([
+    "/diagnostic/start",
+    "/fr/diagnostic/start",
+    "/flows/a/start",
+    "/careers/apply",
+    "/careers/writer/apply",
+    "/fr/careers/writer/apply",
+    "/diagnostic/start?step=2",
+  ])("is a walk: %s", (path) => {
+    expect(isMagnetWalkPath(path, LOCALES)).toBe(true);
+  });
+
+  it.each([
+    "/diagnostic",
+    "/careers",
+    "/careers/writer",
+    "/start-here",
+    "/fr",
+    "/",
+    "",
+    "/apply",
+    "/careers/a/b/apply",
+  ])("is not a walk: %j", (path) => {
+    expect(isMagnetWalkPath(path, LOCALES)).toBe(false);
+  });
+
+  it("answers false for an absent pathname", () => {
+    expect(isMagnetWalkPath(undefined, LOCALES)).toBe(false);
+    expect(isMagnetWalkPath(null, LOCALES)).toBe(false);
+  });
+
+  it("treats a prefix that is not an enabled locale as a first segment", () => {
+    expect(isMagnetWalkPath("/de/careers/apply", LOCALES)).toBe(false);
+    expect(isMagnetWalkPath("/de/start", LOCALES)).toBe(true);
+  });
+});
+
+describe("isMagnetWalkPath — the deliverable pages (#8848 D9, AC-4)", () => {
+  it.each(["/en/reports/q3", "/reports/q3", "/reports/q3/start", "/fr/reports/q3/start"])(
+    "is chrome-free: %s",
+    (path) => {
+      expect(isMagnetWalkPath(path, ["en", "fr"])).toBe(true);
+    },
+  );
+
+  it.each(["/reports", "/en/reports", "/en/reports/"])("keeps the index's chrome: %s", (path) => {
+    expect(isMagnetWalkPath(path, ["en", "fr"])).toBe(false);
+  });
+});

package/templates/apps/web/lib/__tests__/newsletter.actions.test.ts

@@ -0,0 +1,293 @@
+/**
+ * subscribeNewsletterAction (#6730 D9) — the Server Action twin of the
+ * `ailkSubscribeNewsletter` MCP tool.
+ */
+
+import { subscribeNewsletterAction } from "../newsletter.actions.js";
+
+// `visitorForwardHeaders` stays real (#7394) so AC-9 compares the action's
+// `init` with the helper's own output.
+// `flows.get` answers 404 by default — a Free build with no flow route — so
+// the #6730 cases below take `leads.subscribe`; the #8847 cases serve the
+// newsletter magnet.
+jest.mock("@working-theory/api-client", () => ({
+  flows: {
+    get: jest.fn().mockResolvedValue({ ok: false, status: 404, body: {} }),
+    submitStep: jest.fn(),
+  },
+  leads: { subscribe: jest.fn() },
+  visitorForwardHeaders: jest.requireActual("@working-theory/api-client")
+    .visitorForwardHeaders,
+}));
+
+// next/headers' `headers()` is request-scoped in Next; outside it, it is
+// mocked here the way flow.actions.test.ts does (#7394 AC-9).
+jest.mock("next/headers", () => ({
+  __esModule: true,
+  headers: jest.fn().mockResolvedValue({ get: () => null }),
+}));
+
+jest.mock("next-intl/server", () => ({
+  __esModule: true,
+  getLocale: jest.fn().mockResolvedValue("en"),
+}));
+
+import { flows, leads, visitorForwardHeaders } from "@working-theory/api-client";
+import { newsletterFlowConfig } from "@working-theory/validation";
+import { headers } from "next/headers";
+const mockSubscribe = leads.subscribe as jest.Mock;
+const mockFlowsGet = flows.get as jest.Mock;
+const mockSubmitStep = flows.submitStep as jest.Mock;
+
+// The action's magnet read is shared for a few seconds per module instance;
+// each test starts an hour later so none sees another's read.
+let clock = 1_900_000_000_000;
+jest.spyOn(Date, "now").mockImplementation(() => clock);
+beforeEach(() => {
+  clock += 60 * 60 * 1000;
+});
+const mockHeaders = headers as jest.Mock;
+
+function formWith(email: string): FormData {
+  const fd = new FormData();
+  fd.append("email", email);
+  fd.append("consent", "true");
+  return fd;
+}
+
+afterEach(() => {
+  jest.clearAllMocks();
+  mockHeaders.mockResolvedValue({ get: () => null });
+});
+
+describe("subscribeNewsletterAction", () => {
+  it("calls leads.subscribe with source newsletter and the address", async () => {
+    mockSubscribe.mockResolvedValueOnce({ ok: true, body: { id: "subscr_1", persisted: "db" } });
+
+    const result = await subscribeNewsletterAction(null, formWith("ada@example.com"));
+
+    expect(result).toEqual({ kind: "success" });
+    expect(mockSubscribe).toHaveBeenCalledWith(
+      expect.objectContaining({ source: "newsletter", email: "ada@example.com" }),
+    );
+  });
+
+  it("an invalid address → a field error, no API call", async () => {
+    const result = await subscribeNewsletterAction(null, formWith("not-an-email"));
+
+    expect(result).toMatchObject({ kind: "error", fieldErrors: { email: expect.any(String) } });
+    expect(mockSubscribe).not.toHaveBeenCalled();
+  });
+
+  it("503 lead_capture_not_configured → unavailable", async () => {
+    mockSubscribe.mockResolvedValueOnce({
+      ok: false,
+      status: 503,
+      body: { error: "lead_capture_not_configured" },
+    });
+
+    const result = await subscribeNewsletterAction(null, formWith("ada@example.com"));
+
+    expect(result).toEqual({ kind: "unavailable" });
+  });
+
+  it("any other failure → the generic error, never success", async () => {
+    mockSubscribe.mockResolvedValueOnce({ ok: false, status: 503, body: { error: "persist_failed" } });
+    expect(await subscribeNewsletterAction(null, formWith("a@b.co"))).toMatchObject({
+      kind: "error",
+    });
+
+    mockSubscribe.mockRejectedValueOnce(new Error("ECONNREFUSED"));
+    jest.spyOn(console, "error").mockImplementationOnce(() => undefined);
+    expect(await subscribeNewsletterAction(null, formWith("a@b.co"))).toMatchObject({
+      kind: "error",
+    });
+  });
+
+  it("a filled honeypot → success, and nothing is sent", async () => {
+    const fd = formWith("ada@example.com");
+    fd.append("ailk_hp", "spam");
+
+    expect(await subscribeNewsletterAction(null, fd)).toEqual({ kind: "success" });
+    expect(mockSubscribe).not.toHaveBeenCalled();
+  });
+});
+
+// #7394 AC-9 — a spoke forwards its visitor to the hub's leads rate limit.
+describe("subscribeNewsletterAction — visitor forwarding (#7394)", () => {
+  const FORWARD_KEY = "0123456789abcdef".repeat(4); // gitleaks:allow — test fixture, not a credential (#7394)
+  const ENV_KEYS = ["AILK_VISITOR_FORWARD_KEY", "AILK_API_URL"] as const;
+  const priorEnv = new Map(ENV_KEYS.map((name) => [name, process.env[name]]));
+
+  beforeEach(() => {
+    process.env.AILK_VISITOR_FORWARD_KEY = FORWARD_KEY;
+    process.env.AILK_API_URL = "https://hub.example";
+  });
+
+  afterAll(() => {
+    for (const [name, value] of priorEnv) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  });
+
+  it("passes the helper's two headers as init", async () => {
+    const incoming = {
+      get: (name: string) => (name === "x-forwarded-for" ? "203.0.113.5" : null),
+    };
+    mockHeaders.mockResolvedValue(incoming);
+    mockSubscribe.mockResolvedValueOnce({ ok: true, body: { id: "subscr_1", persisted: "db" } });
+
+    const result = await subscribeNewsletterAction(null, formWith("ada@example.com"));
+
+    expect(result).toEqual({ kind: "success" });
+    const expected = visitorForwardHeaders(incoming, FORWARD_KEY);
+    expect(expected).toEqual({
+      "x-ailk-visitor-ip": "203.0.113.5",
+      "x-ailk-visitor-forward-key": FORWARD_KEY,
+    });
+    expect(mockSubscribe).toHaveBeenCalledWith(expect.any(Object), { headers: expected });
+  });
+
+  it("calls leads.subscribe with one argument when headers() throws, and still succeeds", async () => {
+    mockHeaders.mockRejectedValue(new Error("outside a request scope"));
+    mockSubscribe.mockResolvedValueOnce({ ok: true, body: { id: "subscr_1", persisted: "db" } });
+
+    const result = await subscribeNewsletterAction(null, formWith("ada@example.com"));
+
+    expect(result).toEqual({ kind: "success" });
+    expect(mockSubscribe).toHaveBeenCalledTimes(1);
+    expect(mockSubscribe.mock.calls[0]).toHaveLength(1);
+  });
+});
+
+describe("subscribeNewsletterAction — through the newsletter magnet (#8847 D11, AC-6)", () => {
+  function servedMagnet(): void {
+    const { completionEmail: _omitted, ...body } = newsletterFlowConfig;
+    mockFlowsGet.mockResolvedValue({ ok: true, status: 200, body });
+  }
+  afterEach(() => {
+    mockFlowsGet.mockResolvedValue({ ok: false, status: 404, body: {} });
+  });
+
+  it("a ticked post submits the magnet's step once, with the consent purpose, and never leads.subscribe", async () => {
+    servedMagnet();
+    mockSubmitStep.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      body: { sessionId: "s1", nextStepKey: null, completed: true },
+    });
+
+    const result = await subscribeNewsletterAction(null, formWith("a@b.co"));
+
+    expect(result).toEqual({ kind: "success" });
+    expect(mockSubmitStep).toHaveBeenCalledTimes(1);
+    expect(mockSubmitStep).toHaveBeenCalledWith("newsletter", {
+      stepKey: "subscribe",
+      values: { email: "a@b.co", "terms.newsletter": true },
+      locale: "en",
+    });
+    expect(mockSubscribe).not.toHaveBeenCalled();
+  });
+
+  it("a post without consent → fieldErrors.consent, and no API call", async () => {
+    servedMagnet();
+    const fd = new FormData();
+    fd.append("email", "a@b.co");
+
+    const result = await subscribeNewsletterAction(null, fd);
+
+    expect(result).toEqual({
+      kind: "error",
+      fieldErrors: { consent: "Please accept the terms to subscribe." },
+    });
+    expect(mockSubmitStep).not.toHaveBeenCalled();
+    expect(mockSubscribe).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["a 503 lead_capture_not_configured", { ok: false, status: 503, body: { error: "lead_capture_not_configured" } }],
+    ["an unreachable hub (status 0)", { ok: false, status: 0, body: null }],
+    ["a 502", { ok: false, status: 502, body: null }],
+  ])("%s → unavailable", async (_label, answer) => {
+    servedMagnet();
+    mockSubmitStep.mockResolvedValueOnce(answer);
+
+    expect(await subscribeNewsletterAction(null, formWith("a@b.co"))).toEqual({ kind: "unavailable" });
+  });
+
+  it("any other refusal → the generic error", async () => {
+    servedMagnet();
+    mockSubmitStep.mockResolvedValueOnce({ ok: false, status: 400, body: { error: "invalid" } });
+
+    expect(await subscribeNewsletterAction(null, formWith("a@b.co"))).toMatchObject({ kind: "error" });
+  });
+
+  it("a wizard-built newsletter with no consent field submits without one (review H1)", async () => {
+    const { completionEmail: _omitted, ...body } = newsletterFlowConfig;
+    const step = body.steps[0] as { fields: Array<{ name: string }> };
+    mockFlowsGet.mockResolvedValue({
+      ok: true,
+      status: 200,
+      body: { ...body, steps: [{ ...step, fields: step.fields.filter((f) => f.name === "email") }] },
+    });
+    mockSubmitStep.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      body: { sessionId: "s1", nextStepKey: null, completed: true },
+    });
+    const fd = new FormData();
+    fd.append("email", "a@b.co");
+
+    expect(await subscribeNewsletterAction(null, fd)).toEqual({ kind: "success" });
+    expect(mockSubmitStep).toHaveBeenCalledWith("newsletter", {
+      stepKey: "subscribe",
+      values: { email: "a@b.co" },
+      locale: "en",
+    });
+  });
+
+  it("with no magnet, a post without consent is refused and nothing is sent", async () => {
+    const fd = new FormData();
+    fd.append("email", "a@b.co");
+
+    expect(await subscribeNewsletterAction(null, fd)).toMatchObject({
+      kind: "error",
+      fieldErrors: { consent: expect.any(String) },
+    });
+    expect(mockSubscribe).not.toHaveBeenCalled();
+  });
+
+  it("forwards the visitor's address to the step route, and refuses a visitor's 31st post in ten minutes (security review)", async () => {
+    servedMagnet();
+    mockHeaders.mockResolvedValue({
+      get: (name: string) => (name === "x-forwarded-for" ? "203.0.113.9" : null),
+    });
+    mockSubmitStep.mockResolvedValue({
+      ok: true,
+      status: 200,
+      body: { sessionId: "s1", nextStepKey: null, completed: true },
+    });
+
+    for (let i = 0; i < 30; i += 1) {
+      expect(await subscribeNewsletterAction(null, formWith(`a${i}@b.co`))).toEqual({ kind: "success" });
+    }
+    expect(mockSubmitStep.mock.calls[0]![2]).toEqual({
+      headers: expect.objectContaining({ "x-forwarded-for": "203.0.113.9" }),
+    });
+
+    expect(await subscribeNewsletterAction(null, formWith("late@b.co"))).toMatchObject({
+      kind: "error",
+      message: expect.any(String),
+    });
+    expect(mockSubmitStep).toHaveBeenCalledTimes(30);
+  });
+
+  it("with flows.get 404 (a Free build) the same post calls leads.subscribe and not submitStep", async () => {
+    mockSubscribe.mockResolvedValueOnce({ ok: true, body: { id: "subscr_1", persisted: "db" } });
+
+    expect(await subscribeNewsletterAction(null, formWith("a@b.co"))).toEqual({ kind: "success" });
+    expect(mockSubscribe).toHaveBeenCalledTimes(1);
+    expect(mockSubmitStep).not.toHaveBeenCalled();
+  });
+});