create-ailk 0.1.0 → 0.2.0

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

@@ -0,0 +1,144 @@
+"use server";
+
+/**
+ * submitFlowStepAction — Server Action paired with ailkSubmitFlowStep MCP
+ * tool (#3957 D8; #3956 D7).
+ *
+ * Validates `slug` + `submitFlowStepInputSchema` (shared schema per ADR 0013,
+ * mirroring `contact.actions.ts` / `purchase.actions.ts`), calls
+ * `flows.submitStep` via `@working-theory/api-client`, and returns the
+ * discriminated `FlowStepSubmitResult` `FlowStepper` (`@working-theory/ui`)
+ * expects — never throws to the client. Invoked IMPERATIVELY from the
+ * client wrapper (React 19 direct Server Action calls; no `useFormState` —
+ * the stepper needs the response payload on every call, per step).
+ *
+ * Canonical filename: flow.actions.ts (*.actions.ts per ADR 0013 / U0 spec
+ * parity-test regex `ACTION_FILE_RE = /\.actions\.ts$/`).
+ *
+ * Visitor-IP forwarding (#4730): this Server Action runs on the WEB
+ * FUNCTION'S own server — every visitor's step submission calls the API
+ * from the same process, so `apps/api`'s rate limiter would otherwise see
+ * one shared egress IP for every visitor of this site. `resolveVisitorIp`
+ * reads THIS action's own incoming request headers (via Next's `headers()`)
+ * for the real visitor IP and forwards it on the outbound `flows.submitStep`
+ * call, so the API's per-scope rate limiter (apps/api/src/middleware/
+ * rate-limit.ts) keys on the real visitor. A read failure (or no header
+ * present, e.g. local dev with no reverse proxy) degrades to forwarding
+ * nothing — the API then falls back to its own `req.ip`, exactly as before
+ * this fix.
+ */
+
+import { flows } from "@working-theory/api-client";
+import type { FlowStepSubmitResult } from "@working-theory/ui";
+import {
+  flowSlugSchema,
+  submitFlowStepInputSchema,
+} from "@working-theory/validation";
+import { headers } from "next/headers";
+
+/**
+ * Reads the visitor's real IP from THIS action's own incoming request —
+ * never from the browser-supplied payload — preferring `x-forwarded-for`
+ * (the standard multi-hop chain Fastify's `trustProxy` on `apps/api`
+ * understands) and falling back to `x-real-ip`. Returns `undefined` (no
+ * header to forward) rather than throwing on any failure, so an inability
+ * to read headers never blocks a step submission.
+ */
+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;
+  }
+}
+
+export async function submitFlowStepAction(
+  slug: string,
+  payload: {
+    sessionId?: string;
+    stepKey: string;
+    values: Record<string, unknown>;
+    locale?: string;
+  },
+): Promise<FlowStepSubmitResult> {
+  const parsedSlug = flowSlugSchema.safeParse(slug);
+  if (!parsedSlug.success) {
+    return {
+      ok: false,
+      kind: "invalid_input",
+      message: parsedSlug.error.issues[0]?.message ?? "Invalid flow slug.",
+    };
+  }
+
+  const parsedPayload = submitFlowStepInputSchema.safeParse(payload);
+  if (!parsedPayload.success) {
+    return {
+      ok: false,
+      kind: "invalid_input",
+      message:
+        parsedPayload.error.issues[0]?.message ?? "Invalid step submission.",
+    };
+  }
+
+  try {
+    // exactOptionalPropertyTypes-safe: submitFlowStepInputSchema's Zod-inferred
+    // optional fields type as `T | undefined`, which does not structurally
+    // match api-client's `sessionId?: string` (no explicit `| undefined`) —
+    // rebuild the payload, omitting an absent optional key rather than
+    // passing an explicit `undefined` value for it.
+    const { sessionId, stepKey, values, locale } = parsedPayload.data;
+    const stepPayload = {
+      ...(sessionId !== undefined ? { sessionId } : {}),
+      stepKey,
+      values,
+      ...(locale !== undefined ? { locale } : {}),
+    };
+    const visitorIpInit = await resolveVisitorIpInit();
+    // Two call shapes, not one call + a conditional spread: this keeps the
+    // call at EXACTLY 2 args when there's no header to forward (never an
+    // explicit `undefined` 3rd arg) — collapsing it into a spread-args form
+    // would silently change call arity for every existing caller/test.
+    const res = visitorIpInit
+      ? await flows.submitStep(parsedSlug.data, stepPayload, visitorIpInit)
+      : await flows.submitStep(parsedSlug.data, stepPayload);
+    if (!res.ok) {
+      if (res.status === 400) {
+        return { ok: false, kind: "invalid_input" };
+      }
+      if (res.status === 409) {
+        return { ok: false, kind: "step_conflict" };
+      }
+      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: "network" };
+    }
+
+    return { ok: true, response: res.body };
+  } catch (err) {
+    // Log server-side for observability — narrowly, no submitted `values`
+    // (PII care, #3989): the api-client's `post()` never attaches the
+    // request payload to a thrown error (packages/api-client/src/http.ts),
+    // so logging `err` itself is safe, but slug/stepKey are the only
+    // request-identifying fields included on purpose.
+    console.error(
+      `[submitFlowStepAction] slug=${parsedSlug.data} stepKey=${parsedPayload.data.stepKey}`,
+      err,
+    );
+    return { ok: false, kind: "network" };
+  }
+}

package/templates/apps/web/app/[locale]/flows/[slug]/page.tsx

@@ -0,0 +1,108 @@
+/**
+ * /[locale]/flows/[slug] — the tool's LANDING route (#5053 D3/D5).
+ *
+ * An interactive tool is TWO routes. This is the indexed half: the document
+ * that describes the tool, carries its structured data, and links to the
+ * flow. The flow itself is one segment deeper — `start/page.tsx` — and
+ * carries `noindex, follow` by mounting `flowRouteMetadata` (D4).
+ *
+ * Until #5053 this route WAS the flow, which is the exact defect the
+ * convention closes: a page whose entire indexable content is one visible
+ * question, with the `WebApplication` page type going unused. The defect is
+ * silent — the page renders and the flow works — so the split is what makes
+ * the tool visible to search and to answer engines at all.
+ *
+ * Structured data is the `Assessment` page type's own emit, unchanged:
+ * single-layer `@type: "WebApplication"` with no `WebPage` envelope (D2,
+ * resting on #5019, which names `assessment` and `calculator` among the
+ * builders that keep that shape byte for byte).
+ *
+ * Copy: a served `FlowConfig` carries no tool-level name or description, so
+ * the landing derives its name from the flow's own first-step title — the
+ * same string this route already used as its page title before the split —
+ * and takes its supporting line and CTA label from the site's `flow`
+ * message namespace. No consuming site's wording ships here.
+ *
+ * Same `flows.get` fetch and same 404-on-`!res.ok` as the flow route: a flow
+ * that is absent or unconfigured has no landing either. Dynamic rendering
+ * for the same reason — the config is DB-backed live data.
+ */
+import { flows } from "@working-theory/api-client";
+import { JsonLd } from "@working-theory/jsonld";
+import { buildJsonLd } from "@working-theory/schema";
+import { SectionRenderer } from "@working-theory/ui/sections";
+import type { FlowConfig, PageSection } from "@working-theory/validation";
+import { resolveLocalizedString } from "@working-theory/validation";
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import type { ReactElement } from "react";
+
+export const dynamic = "force-dynamic";
+
+interface Props {
+  params: Promise<{ locale: string; slug: string }>;
+}
+
+/** The tool's name — the flow's own first-step title in the active locale. */
+function toolName(config: FlowConfig, locale: string): string {
+  return resolveLocalizedString(
+    config.steps[0]!.copy.title,
+    locale,
+    config.defaultLocale,
+  );
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale, slug } = await params;
+  const res = await flows.get(slug);
+  if (!res.ok) return {};
+
+  const t = await getTranslations({ locale, namespace: "flow" });
+  return {
+    title: toolName(res.body, locale),
+    description: t("landingIntro"),
+  };
+}
+
+export default async function Page({ params }: Props): Promise<ReactElement> {
+  const { locale, slug } = await params;
+  const res = await flows.get(slug);
+  if (!res.ok) {
+    notFound();
+  }
+
+  const t = await getTranslations({ locale, namespace: "flow" });
+  const name = toolName(res.body, locale);
+  const intro = t("landingIntro");
+  const startHref = `/flows/${res.body.slug}/start`;
+
+  const sections: PageSection[] = [
+    {
+      id: "flow-landing-hero",
+      type: "hero",
+      data: {
+        headline: name,
+        subheadline: intro,
+        primaryCta: { label: t("getStarted"), href: startHref },
+      },
+    },
+  ];
+
+  return (
+    <>
+      <JsonLd
+        schema={buildJsonLd({
+          type: "Assessment",
+          slug: res.body.slug,
+          title: name,
+          description: intro,
+          locale,
+        })}
+      />
+      <main>
+        <SectionRenderer sections={sections} locale={locale} />
+      </main>
+    </>
+  );
+}