create-ailk 0.5.0 → 0.6.1

package/templates/apps/web/app/[locale]/purchase/success/page.tsx

@@ -0,0 +1,307 @@
+// oss: false
+/**
+ * /[locale]/purchase/success — the order-confirmation return page (#6084).
+ *
+ * NOTE on `// oss: false` — a DELIBERATE correction to the spec's NFR-4,
+ * which assumed this page could ship unmarked like the base-tree checkout
+ * API primitives (`routes/checkout/sessions.ts`, `tools/purchase.ts`). Those
+ * import only OSS `@working-theory/stripe-client`; THIS page renders
+ * `payment-receipt` via `registerCommerceSections()` from the PAID
+ * `@working-theory/ui-commerce` package (D5) — the same shape `/meet`
+ * already has for `@working-theory/ui-scheduling`. The architecture lint's
+ * OSS→paid boundary rule (`architecture.yaml` forbidden_patterns) requires
+ * either no marker + no paid import, or a `paths_excluded` entry PLUS this
+ * marker (the `meet/**` precedent) — never no-marker-with-a-paid-import.
+ * `create-ailk`'s scaffold is UNAFFECTED: `CORE_ROUTE_DIRS`
+ * (`packages/create-ailk/src/surfaces.ts`) governs what a scaffold carries,
+ * not this marker, so AC-4/FR-8 still hold — every scaffold gets this file
+ * regardless. Only the ai-launch-kit-internal → ai-launch-kit PUBLIC-REPO
+ * split (a different mechanism) reads this marker.
+ *
+ * READS the Checkout Session the Stripe webhook already granted (spec §1.2)
+ * — this page never writes: no Prisma call, no Stripe write, no grant, no
+ * stamp (AC-1, FR-3). It is reachable by anyone holding a `cs_…` id, with
+ * no credential at all (D8) — the design below is built around that fact.
+ *
+ * D6 — the paid render is not forgeable. `outcome: "success"` is Stripe's
+ * proof-of-payment status (a green chip, `data-outcome="success"`, and a
+ * schema.org `PaymentComplete` node — `PaymentResult.tsx`), so the
+ * `payment-receipt` section is constructed ONLY on a 2xx read with
+ * `paymentStatus === "paid"`. Every other reachable state — no
+ * `session_id`, an API failure, or a 2xx read that is not yet paid —
+ * renders a DIFFERENT chassis (`content-block` → `cta`, not a
+ * `CheckoutDeliveryPage`) with no badge, no `data-outcome` and no
+ * `PaymentComplete` string anywhere in the DOM (AC-8).
+ *
+ * D12 — base tree, request-time gate. This page ships unconditionally in
+ * every scaffold; whether it SERVES is decided per request by the
+ * `commerce` licence claim (`../../../../src/lib/commerce-claim.ts`,
+ * extracted from `.well-known/mcp.json`'s own check). `notFound()` on no
+ * claim is indistinguishable from a build without the module — before any
+ * API call, before any render.
+ *
+ * The `ui-commerce` package itself is registered LAZILY
+ * (`../../../../src/lib/commerce-sections.ts`), never via a top-level
+ * static import — a keyless scaffold carries no dependency on it by design
+ * (#5581 U6/D5), and a static import would fail every keyless build
+ * regardless of the request-time gate above. When the module genuinely is
+ * not installed, `paidSections()` below falls back to an OSS
+ * `content-block` carrying the same confirmation copy, rather than the bare
+ * `payment-receipt` section `SectionRenderer` would otherwise silently
+ * render as nothing (`ModuleAbsent` in production).
+ *
+ * `noindex`: reachable only by finishing (or trying) a Checkout, never a
+ * page a crawler should list.
+ */
+import { checkout } from "@working-theory/api-client";
+import type { CheckoutSessionReadResponse } from "@working-theory/api-client";
+import { SectionRenderer } from "@working-theory/ui/sections";
+import type { PageSection } from "@working-theory/validation";
+import { formatMoney } from "@working-theory/web-i18n";
+import type { Metadata } from "next";
+import { headers } from "next/headers";
+import { notFound } from "next/navigation";
+import { getTranslations } from "next-intl/server";
+import type { ReactElement } from "react";
+
+import { resolveCommerceClaim } from "../../../../src/lib/commerce-claim";
+import { ensureCommerceSectionsRegistered } from "../../../../src/lib/commerce-sections";
+
+// The success page reads `searchParams` (dynamic by construction); paired
+// with the cancel page's explicit `force-dynamic` so a site that buys
+// commerce after its last deploy is not stuck serving a prerendered 404
+// (D12).
+export const dynamic = "force-dynamic";
+
+/**
+ * `next-intl`'s `getTranslations()` return type, so it can be passed
+ * between the section builders below (this repo has no other precedent
+ * typing it explicitly, since no other page passes `t` across functions).
+ */
+type PurchaseT = Awaited<ReturnType<typeof getTranslations>>;
+
+interface Props {
+  params: Promise<{ locale: string }>;
+  searchParams?: Promise<{ session_id?: string | string[] }>;
+}
+
+/** First value only — a repeated query param must not become an array here. */
+function firstValue(raw: string | string[] | undefined): string | undefined {
+  if (Array.isArray(raw)) return raw[0];
+  return raw;
+}
+
+/**
+ * Reads the visitor's real IP from THIS page's own incoming request —
+ * never from the query string — preferring `x-forwarded-for` and falling
+ * back to `x-real-ip`. Returns `undefined` rather than throwing on any
+ * failure. A local copy of `flows/[slug]/checkout.actions.ts`'s identical
+ * helper (#4730) — every RSC-to-API caller carries its own copy rather than
+ * a shared import, since this one crosses the OSS/paid boundary the other
+ * doesn't. Without it, `apps/api`'s rate limiter
+ * (`middleware/rate-limit.ts`) sees the Next server's own egress IP for
+ * every buyer, collapsing them into one shared bucket (security-review
+ * finding on this issue's PR — #6084).
+ */
+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;
+  }
+}
+
+/** The onward `cta` section every one of D6's five rows carries (AC-7 — never a dead end). */
+function ctaSection(t: PurchaseT): PageSection {
+  return {
+    id: "purchase-success-cta",
+    type: "cta",
+    data: {
+      headline: t("success.ctaHeadline"),
+      description: t("success.ctaDescription"),
+      primaryCta: { label: t("success.ctaLabel"), href: "/services" },
+    },
+  };
+}
+
+/** One card per paid line item — the D5 seam: `items`, not `payment-receipt`, carries the lines. */
+function itemsSection(
+  lineItems: CheckoutSessionReadResponse["lineItems"],
+  t: PurchaseT,
+  locale: string,
+): PageSection {
+  return {
+    id: "purchase-success-items",
+    type: "items",
+    data: {
+      items: lineItems.map((line) => ({
+        title: line.description,
+        description: t("success.lineItem", {
+          quantity: line.quantity,
+          amount: formatMoney(line.amountTotal, line.currency, locale),
+        }),
+      })),
+    },
+  };
+}
+
+/**
+ * D6's degraded-state row: no `session_id`, a shape-gate reject, an API
+ * 404/non-2xx, or a session that isn't yet paid — all render honestly
+ * rather than claiming a payment. `content-block` → `cta`; no
+ * `payment-receipt`, so no badge and no schema.org node exists to be read.
+ */
+function unknownSections(t: PurchaseT): PageSection[] {
+  return [
+    {
+      id: "purchase-success-unknown",
+      type: "content-block",
+      data: {
+        headline: t("success.unknownHeadline"),
+        body: t("success.unknownBody"),
+      },
+    },
+    ctaSection(t),
+  ];
+}
+
+/** 2xx, `paymentStatus` is `"unpaid"` or `"no_payment_required"` — D6 row 2. */
+function pendingSections(
+  session: CheckoutSessionReadResponse,
+  t: PurchaseT,
+  locale: string,
+): PageSection[] {
+  return [
+    {
+      id: "purchase-success-pending",
+      type: "content-block",
+      data: {
+        headline: t("success.pendingHeadline"),
+        body: t("success.pendingBody"),
+      },
+    },
+    itemsSection(session.lineItems, t, locale),
+    ctaSection(t),
+  ];
+}
+
+/**
+ * The OSS degrade for `paidSections()` — carries the same title/message/
+ * status copy as `payment-receipt`, minus its badge/schema.org markers, for
+ * a deployment where `@working-theory/ui-commerce` is genuinely not
+ * installed (a keyless scaffold with a `commerce` licence claim but no
+ * redeploy since buying it — `ensureCommerceSectionsRegistered()`'s own
+ * doc comment).
+ */
+function paidFallbackSection(t: PurchaseT): PageSection {
+  return {
+    id: "purchase-success-receipt-fallback",
+    type: "content-block",
+    data: {
+      headline: t("success.title"),
+      body: `${t("success.message")} ${t("success.statusLabel")}`,
+    },
+  };
+}
+
+/** 2xx AND `paymentStatus === "paid"` — the ONLY row that constructs `payment-receipt` (D6). */
+async function paidSections(
+  session: CheckoutSessionReadResponse,
+  t: PurchaseT,
+  locale: string,
+): Promise<PageSection[]> {
+  const commerceSectionsAvailable = await ensureCommerceSectionsRegistered();
+  const receipt: PageSection = commerceSectionsAvailable
+    ? {
+        id: "purchase-success-receipt",
+        type: "payment-receipt",
+        data: {
+          outcome: "success",
+          title: t("success.title"),
+          message: t("success.message"),
+          statusLabel: t("success.statusLabel"),
+          amount: {
+            amountMinor: session.amountTotal ?? 0,
+            currency: session.currency,
+          },
+          locale,
+          sessionId: session.id,
+          sessionIdLabel: t("success.sessionIdLabel"),
+        },
+      }
+    : paidFallbackSection(t);
+  return [receipt, itemsSection(session.lineItems, t, locale), ctaSection(t)];
+}
+
+/** D6's five-row table, collapsed to the three code paths that produce distinct output. */
+async function sectionsFor(
+  sessionId: string | undefined,
+  t: PurchaseT,
+  locale: string,
+): Promise<PageSection[]> {
+  if (!sessionId) return unknownSections(t);
+
+  // A malformed/oversized id (D8's shape gate) or an unknown session both
+  // answer non-2xx here — the API's failure is logged server-side and never
+  // surfaced to the buyer (spec §3 D6 table). `checkout.getSession()` calls
+  // `fetch()` directly with no try/catch of its own
+  // (`packages/api-client/src/http.ts`), so a network-level failure (the API
+  // unreachable, DNS, a dropped connection) REJECTS rather than resolving
+  // `{ ok: false }` — caught here so it degrades identically to a non-2xx
+  // response instead of crashing the page (AC-7's "never a dead end",
+  // code-review finding on this issue's PR).
+  let res: Awaited<ReturnType<typeof checkout.getSession>>;
+  try {
+    res = await checkout.getSession(sessionId, await resolveVisitorIpInit());
+  } catch {
+    return unknownSections(t);
+  }
+  if (!res.ok) return unknownSections(t);
+
+  if (res.body.paymentStatus !== "paid") {
+    return pendingSections(res.body, t, locale);
+  }
+
+  return await paidSections(res.body, t, locale);
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+  const t = await getTranslations({ locale, namespace: "purchase" });
+  return {
+    title: t("success.title"),
+    description: t("success.message"),
+    robots: { index: false, follow: true },
+  };
+}
+
+export default async function Page({
+  params,
+  searchParams,
+}: Props): Promise<ReactElement> {
+  const { locale } = await params;
+  const t: PurchaseT = await getTranslations({ locale, namespace: "purchase" });
+
+  // D12 — request-time gate, before any API call and before any render.
+  if (!(await resolveCommerceClaim())) {
+    notFound();
+  }
+
+  const query = searchParams ? await searchParams : {};
+  const sessionId = firstValue(query.session_id);
+
+  const sections = await sectionsFor(sessionId, t, locale);
+
+  return (
+    <main>
+      <SectionRenderer sections={sections} locale={locale} />
+    </main>
+  );
+}

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

@@ -0,0 +1,44 @@
+// ReturnsPolicyPage route (#5947). Reads the ReturnsPolicyPage MDX frontmatter, renders sections via
+// SectionRenderer, and emits a JSON-LD <script>.
+import type {
+  getMdxSource as defaultGetMdxSource,
+  getPageSections as defaultGetPageSections} from "@working-theory/page-renderer";
+import {
+  renderPage,
+  renderPageMetadata
+} from "@working-theory/page-renderer";
+import type { Metadata } from "next";
+import type { ReactElement } from "react";
+
+interface Props {
+  params: Promise<{ locale: string }>;
+  getMdxSource?: typeof defaultGetMdxSource;
+  getPageSections?: typeof defaultGetPageSections;
+}
+
+export async function generateMetadata({
+  params,
+}: Pick<Props, "params">): Promise<Metadata> {
+  const { locale } = await params;
+  return renderPageMetadata({ type: "ReturnsPolicyPage", slug: "returns", locale });
+}
+
+export default async function Page({
+  params,
+  getMdxSource,
+  getPageSections,
+}: Props): Promise<ReactElement> {
+  const { locale } = await params;
+  return renderPage({
+    type: "ReturnsPolicyPage",
+    slug: "returns",
+    locale,
+    // Without a namespace `renderPage` 404s on a missing seed — and a scaffold
+    // IS a missing-seed environment, since `build-templates.mjs` snapshots
+    // `apps/` but deliberately not `content/`. The namespace makes this route
+    // render the #4154 authoring empty state at 200, exactly as /terms does.
+    translationsNamespace: "returns",
+    ...(getMdxSource !== undefined && { getMdxSource }),
+    ...(getPageSections !== undefined && { getPageSections }),
+  });
+}

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

@@ -0,0 +1,44 @@
+// ShippingPolicyPage route (#5947). Reads the ShippingPolicyPage MDX frontmatter, renders sections via
+// SectionRenderer, and emits a JSON-LD <script>.
+import type {
+  getMdxSource as defaultGetMdxSource,
+  getPageSections as defaultGetPageSections} from "@working-theory/page-renderer";
+import {
+  renderPage,
+  renderPageMetadata
+} from "@working-theory/page-renderer";
+import type { Metadata } from "next";
+import type { ReactElement } from "react";
+
+interface Props {
+  params: Promise<{ locale: string }>;
+  getMdxSource?: typeof defaultGetMdxSource;
+  getPageSections?: typeof defaultGetPageSections;
+}
+
+export async function generateMetadata({
+  params,
+}: Pick<Props, "params">): Promise<Metadata> {
+  const { locale } = await params;
+  return renderPageMetadata({ type: "ShippingPolicyPage", slug: "shipping", locale });
+}
+
+export default async function Page({
+  params,
+  getMdxSource,
+  getPageSections,
+}: Props): Promise<ReactElement> {
+  const { locale } = await params;
+  return renderPage({
+    type: "ShippingPolicyPage",
+    slug: "shipping",
+    locale,
+    // Without a namespace `renderPage` 404s on a missing seed — and a scaffold
+    // IS a missing-seed environment, since `build-templates.mjs` snapshots
+    // `apps/` but deliberately not `content/`. The namespace makes this route
+    // render the #4154 authoring empty state at 200, exactly as /terms does.
+    translationsNamespace: "shipping",
+    ...(getMdxSource !== undefined && { getMdxSource }),
+    ...(getPageSections !== undefined && { getPageSections }),
+  });
+}