create-ailk 0.21.0 → 0.23.0

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

@@ -0,0 +1,202 @@
+"use server";
+
+/**
+ * subscribeNewsletterAction — Server Action paired with the
+ * `ailkSubscribeNewsletter` MCP tool (#6730 D9).
+ *
+ * `/newsletter` and the footer render the newsletter magnet's
+ * `NewsletterFormInline` bound to this action. Validates the address with
+ * the tool's own input schema, calls `POST /v1/leads/subscribe` through
+ * `@working-theory/api-client`, and maps the outcome the same way
+ * `captureLeadAction` does: the API's 503 `lead_capture_not_configured` →
+ * `unavailable`; any other non-2xx or thrown error → the generic `error`;
+ * only a 2xx is `success`.
+ *
+ * Visitor forwarding (#7394): forwards the visitor exactly as
+ * `captureLeadAction` does, through `visitorForwardHeaders` and the
+ * server-only `AILK_VISITOR_FORWARD_KEY`; without them the call is made
+ * with one argument, as before.
+ *
+ * Through the magnet (#8847 D11): /newsletter, /unsubscribe's sibling footer
+ * signup and the page itself all render the workspace's `newsletter`
+ * magnet, so a signup goes through it. The action re-reads the magnet; a post
+ * without `consent=true` while that magnet has a consent field (or, with no
+ * magnet, ever) answers a `consent` field error and nothing is sent. When the
+ * magnet maps, the
+ * address and the consent go to `POST /v1/flows/newsletter/steps` — the step
+ * key, the email field's name and the consent field's purposes all come from
+ * the server's own read, never the post (SEC-8847-A) — which writes the lead,
+ * the consent ledger row and the magnet's welcome email. A 2xx that completes
+ * is success; a 503 `lead_capture_not_configured` or an unreachable API
+ * (status 0, 502, 504) is `unavailable`. Otherwise (a Free build has no flow
+ * route) it posts `leads.subscribe`, as before.
+ */
+
+import { flows, leads, visitorForwardHeaders } from "@working-theory/api-client";
+import { LEAD_CAPTURE_HONEYPOT, type LeadCaptureFormState } from "@working-theory/ui";
+import {
+  NEWSLETTER_FLOW_SLUG,
+  subscribeNewsletterInputSchema,
+} from "@working-theory/validation";
+import { cookies, headers } from "next/headers";
+import { getLocale } from "next-intl/server";
+
+import { checkRateLimit, clientIpFromHeaders } from "../src/lib/rate-limit";
+
+import { consentVisitorHeader, readConsentVisitor } from "./consent-visitor";
+import { inPageView, readServedMagnet } from "./in-page-magnet";
+
+const GENERIC_ERROR = "Something went wrong, please try again.";
+const CONSENT_REQUIRED = "Please accept the terms to subscribe.";
+const RATE_LIMITED = "Too many signups from here. Please try again in a few minutes.";
+// #8847 (security review) — the contact action's per-visitor budget: the hub
+// sees this site's egress address on the step route, so one visitor must not
+// spend the bucket every visitor shares.
+const RATE_LIMIT_MAX_CALLS = 30;
+const RATE_LIMIT_WINDOW_MS = 10 * 60 * 1000;
+
+/** The API's 503 for a deployment with nowhere to keep a lead. */
+function isNotConfigured(res: { status: number; body: unknown }): boolean {
+  return (
+    res.status === 503 &&
+    typeof res.body === "object" &&
+    res.body !== null &&
+    (res.body as { error?: unknown }).error === "lead_capture_not_configured"
+  );
+}
+
+/** An API that could not be reached: a thrown call (0), a 502 or a 504. */
+function isApiUnreachable(res: { status: number }): boolean {
+  return res.status === 0 || res.status === 502 || res.status === 504;
+}
+
+/**
+ * The signup through the served newsletter magnet, or `null` when it does not
+ * map (absent, draft, a Free build with no flow route, or not a one-field
+ * signup) — the caller then posts `leads.subscribe`.
+ */
+async function submitThroughMagnet(
+  email: string,
+  consented: boolean,
+  init: { headers: Record<string, string> } | undefined,
+): Promise<LeadCaptureFormState | null> {
+  const magnet = await readServedMagnet(NEWSLETTER_FLOW_SLUG);
+  let locale = "en";
+  try {
+    locale = await getLocale();
+  } catch {
+    // No request-scoped locale — the default locale.
+  }
+  const view = magnet ? inPageView(magnet, locale, "newsletter") : null;
+  if (view === null || !("kind" in view.form)) return null;
+  const { emailField, consent } = view.form;
+  // A magnet without a consent field (a wizard-built newsletter) asks for none.
+  if (consent !== undefined && !consented) {
+    return { kind: "error", fieldErrors: { consent: CONSENT_REQUIRED } };
+  }
+  const values: Record<string, unknown> = { [emailField]: email };
+  if (consent !== undefined) {
+    for (const purpose of consent.purposes) values[`${consent.field}.${purpose}`] = true;
+  }
+  const payload = { stepKey: view.stepKey, values, locale };
+  try {
+    const res = init
+      ? await flows.submitStep(NEWSLETTER_FLOW_SLUG, payload, init)
+      : await flows.submitStep(NEWSLETTER_FLOW_SLUG, payload);
+    if (res.ok) return res.body.completed ? { kind: "success" } : { kind: "error", message: GENERIC_ERROR };
+    if (isNotConfigured(res) || isApiUnreachable(res)) return { kind: "unavailable" };
+    return { kind: "error", message: GENERIC_ERROR };
+  } catch (err) {
+    // The api-client never attaches the request payload to a thrown error.
+    console.error("[subscribeNewsletterAction]", err);
+    return { kind: "unavailable" };
+  }
+}
+
+export async function subscribeNewsletterAction(
+  _prevState: LeadCaptureFormState,
+  formData: FormData,
+): Promise<LeadCaptureFormState> {
+  // Honeypot: a bot that fills the hidden field gets a person's answer, and
+  // nothing is sent.
+  const honeypot = formData.get(LEAD_CAPTURE_HONEYPOT);
+  if (typeof honeypot === "string" && honeypot !== "") return { kind: "success" };
+
+  const parsed = subscribeNewsletterInputSchema.safeParse({
+    email: formData.get("email"),
+  });
+  if (!parsed.success) {
+    return {
+      kind: "error",
+      fieldErrors: { email: parsed.error.issues[0]?.message ?? "Invalid email" },
+    };
+  }
+
+  let requestHeaders: Awaited<ReturnType<typeof headers>> | undefined;
+  try {
+    requestHeaders = await headers();
+  } catch {
+    // No request scope to read — no forwarding, and the visitor is "unknown".
+  }
+
+  // No readable address: skip the per-visitor limit rather than put every
+  // visitor in one shared bucket (the contact action's rule).
+  const visitor = requestHeaders ? clientIpFromHeaders(requestHeaders) : "unknown";
+  if (
+    visitor !== "unknown" &&
+    !checkRateLimit(`newsletter:${visitor}`, RATE_LIMIT_MAX_CALLS, RATE_LIMIT_WINDOW_MS)
+  ) {
+    return { kind: "error", message: RATE_LIMITED };
+  }
+
+  let init: { headers: Record<string, string> } | undefined;
+  if (requestHeaders) {
+    const forwarded = visitorForwardHeaders(requestHeaders, process.env.AILK_VISITOR_FORWARD_KEY);
+    if (forwarded) init = { headers: forwarded };
+  }
+
+  // #8438 D12 — the banner's visitor id, so a later subscribe links its
+  // cookie choices to the client record. Absent or invalid → no header.
+  try {
+    const visitorId = readConsentVisitor(await cookies());
+    if (visitorId) init = { headers: { ...(init?.headers ?? {}), ...consentVisitorHeader(visitorId) } };
+  } catch {
+    // No request scope to read — subscribe with no visitor-link header.
+  }
+
+  const consented = formData.get("consent") === "true";
+  // The step route keys its limit on the forwarded address, as the walk's
+  // action sends it (flow.actions.ts).
+  const stepInit =
+    visitor !== "unknown"
+      ? { headers: { "x-forwarded-for": visitor, ...(init?.headers ?? {}) } }
+      : init;
+  const viaMagnet = await submitThroughMagnet(parsed.data.email, consented, stepInit);
+  if (viaMagnet !== null) return viaMagnet;
+  // The Free path renders the seeded config, whose consent box gates the post.
+  if (!consented) return { kind: "error", fieldErrors: { consent: CONSENT_REQUIRED } };
+
+  const siteId = process.env.AILK_SITE_ID ?? "default";
+  const body = { siteId, source: "newsletter", email: parsed.data.email };
+  try {
+    const res = init
+      ? await leads.subscribe(body, init)
+      : await leads.subscribe(body);
+    if (!res.ok) {
+      const error =
+        typeof res.body === "object" && res.body !== null
+          ? (res.body as { error?: unknown }).error
+          : undefined;
+      if (res.status === 503 && error === "lead_capture_not_configured") {
+        return { kind: "unavailable" };
+      }
+      return { kind: "error", message: GENERIC_ERROR };
+    }
+    return { kind: "success" };
+  } catch (err) {
+    // The api-client never attaches the request payload to a thrown error,
+    // so logging `err` carries no subscriber address.
+    console.error("[subscribeNewsletterAction]", err);
+    return { kind: "error", message: GENERIC_ERROR };
+  }
+}

package/templates/apps/web/lib/offerings-pricing.ts

@@ -0,0 +1,326 @@
+/**
+ * The workspace shown set → the Pricing section's data (#8925, spec
+ * docs/specs/8925-map-the-workspace-shown-set-spec.md).
+ *
+ * One pure function, `offeringsPricing`, turns the Offerings shown set (spec
+ * 8876 D4, served by #8924) into two Pricing section fragments: one plan card
+ * per `ailkGroup: "plan"` Product and one add-on tile per `"addon"` Product,
+ * in the snapshot's order, each keyed by the Product's `{plan}` so `?plan=`
+ * (#8842) can match it. #8927 places the fragments into `/pricing`.
+ *
+ * This is the one place Stripe text crosses into page markup, so contract
+ * docs/specs/8879-the-offerings-security-contract-key-spec.md binds it:
+ *   - T2 — every Stripe string is emitted as a plain text field, with format
+ *     characters removed; nothing is parsed as HTML or Markdown (D8).
+ *   - T3 — every link is `OFFERINGS_CHECKOUT_PATH` plus a lookup key that
+ *     `parseLookupKey` accepts; no href is built from any other field (D5).
+ *   - §3.7 — `yearly` reads as annual and `once` as one-time at render, never
+ *     in the key (D2).
+ *
+ * The module holds no user-visible copy: the CTA label, the recommended label
+ * and the period phrasings arrive in `labels` (D9, customer-facing-i18n).
+ */
+import {
+  parseLookupKey,
+  lookupKeyPeriodSchema,
+  workspaceShownSetSchema,
+  type LookupKeyPeriod,
+  type OfferingsPrice,
+  type OfferingsProduct,
+  type PageSection,
+} from "@working-theory/validation";
+
+/** The period words, read by name from their one home (#8876 AC-9). */
+const PERIOD = lookupKeyPeriodSchema.enum;
+
+type PricingSectionData = Extract<PageSection, { type: "pricing" }>["data"];
+type PricingPlanCard = PricingSectionData["plans"][number];
+/** `AddonCard` ignores `key`; it is carried so a tile names its `{plan}` too. */
+type PricingAddonTile = NonNullable<PricingSectionData["addons"]>[number] & {
+  key: string;
+};
+
+export interface OfferingsPricingLabels {
+  /** The CTA label on every card and tile. */
+  cta: string;
+  /** The recommended plan's pill and the recommended add-on's eyebrow. */
+  recommended: string;
+  /** A formatted amount → its monthly, annual and one-time phrasings. */
+  monthly(amount: string): string;
+  annual(amount: string): string;
+  oneTime(amount: string): string;
+}
+
+export interface OfferingsPricing {
+  plans: PricingSectionData | null;
+  addons: PricingSectionData | null;
+}
+
+/** The route every Offerings CTA links to, followed by a grammar key. */
+export const OFFERINGS_CHECKOUT_PATH = "/api/offerings/checkout";
+
+/**
+ * The CTA target for `lookupKey`, or `null` when the key is outside the
+ * grammar. A grammar key is `[a-z0-9_-]` only, so it needs no encoding.
+ */
+export function offeringsCheckoutHref(lookupKey: string): string | null {
+  return parseLookupKey(lookupKey)
+    ? `${OFFERINGS_CHECKOUT_PATH}/${lookupKey}`
+    : null;
+}
+
+/**
+ * Whether `lookupKey` is a grammar key of a Price in a current, non-empty
+ * shown set — the keys `/pricing`'s cards are built from (#9051 D4).
+ */
+export function isShownLookupKey(
+  shownSet: unknown,
+  lookupKey: string,
+): boolean {
+  if (!parseLookupKey(lookupKey)) return false;
+  const parsed = shownSetSchema.safeParse(shownSet);
+  if (!parsed.success) return false;
+  const { state, offerings } = parsed.data;
+  if (state !== "current" || offerings.length === 0) return false;
+  return offerings.some((o) => o.prices.some((p) => p.lookupKey === lookupKey));
+}
+
+// Stripe's zero- and three-decimal currencies. The spoke's legacy buy route
+// held the only other copy across apps/web and @working-theory/spoke-checkout,
+// and is retired (#9142). The table stays here, not in that package: a hub and
+// a spoke without commerce carry /pricing but not the package.
+const ZERO_DECIMAL_CURRENCIES = new Set([
+  "bif",
+  "clp",
+  "djf",
+  "gnf",
+  "jpy",
+  "kmf",
+  "krw",
+  "mga",
+  "pyg",
+  "rwf",
+  "ugx",
+  "vnd",
+  "vuv",
+  "xaf",
+  "xof",
+  "xpf",
+]);
+const THREE_DECIMAL_CURRENCIES = new Set(["bhd", "jod", "kwd", "omr", "tnd"]);
+
+function currencyExponent(currency: string): number {
+  if (ZERO_DECIMAL_CURRENCIES.has(currency)) return 0;
+  if (THREE_DECIMAL_CURRENCIES.has(currency)) return 3;
+  return 2;
+}
+
+/**
+ * An amount in Stripe's minor units, formatted for `locale` (D7). A whole
+ * amount drops its fraction digits; a locale `Intl` refuses falls back to `en`.
+ */
+export function formatMinorUnits(
+  amount: number,
+  currency: string,
+  locale: string,
+): string {
+  const code = currency.toLowerCase();
+  const exponent = currencyExponent(code);
+  const value = amount / 10 ** exponent;
+  const options: Intl.NumberFormatOptions = {
+    style: "currency",
+    currency: code.toUpperCase(),
+    maximumFractionDigits: exponent,
+    minimumFractionDigits: Number.isInteger(value) ? 0 : exponent,
+  };
+  let format: Intl.NumberFormat;
+  try {
+    format = new Intl.NumberFormat(locale, options);
+  } catch {
+    format = new Intl.NumberFormat("en", options);
+  }
+  return format.format(value);
+}
+
+// Cc, Cf, Zl, Zp and Cs — the T1 classes. The input was normalized once by
+// #8876, so this changes nothing there; it is the last guard before markup.
+const FORMAT_CHARACTERS = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Cs}]/gu;
+
+function stripFormatCharacters(text: string, keepNewlines = false): string {
+  return text.replace(FORMAT_CHARACTERS, (ch) =>
+    keepNewlines && ch === "\n" ? ch : "",
+  );
+}
+
+function features(product: OfferingsProduct): string[] {
+  return product.marketingFeatures
+    .map((feature) => stripFormatCharacters(feature))
+    .filter((feature) => feature.length > 0);
+}
+
+function priceFor(
+  product: OfferingsProduct,
+  period: LookupKeyPeriod,
+): OfferingsPrice | undefined {
+  return product.prices.find((p) => p.period === period);
+}
+
+/** The Price a card shows in monthly mode: `monthly`, else `yearly`, else `once`. */
+function shownPrice(product: OfferingsProduct): OfferingsPrice | undefined {
+  return (
+    priceFor(product, PERIOD.monthly) ??
+    priceFor(product, PERIOD.yearly) ??
+    priceFor(product, PERIOD.once)
+  );
+}
+
+function phrase(
+  price: OfferingsPrice,
+  locale: string,
+  labels: OfferingsPricingLabels,
+): string {
+  const amount = formatMinorUnits(price.amount, price.currency, locale);
+  if (price.period === PERIOD.monthly) return labels.monthly(amount);
+  if (price.period === PERIOD.yearly) return labels.annual(amount);
+  return labels.oneTime(amount);
+}
+
+/**
+ * Only the first `recommended` Product of a group is highlighted (D4). Each
+ * offering's own flag is read; the shown set's top-level `recommended` ids
+ * carry the same fact and are deliberately not consulted a second time.
+ */
+function firstRecommended(products: OfferingsProduct[]): string | undefined {
+  return products.find((p) => p.recommended)?.plan;
+}
+
+function planCard(
+  product: OfferingsProduct,
+  highlighted: boolean,
+  locale: string,
+  labels: OfferingsPricingLabels,
+): PricingPlanCard | null {
+  const shown = shownPrice(product);
+  const href = shown ? offeringsCheckoutHref(shown.lookupKey) : null;
+  if (!href) return null;
+
+  const monthly = priceFor(product, PERIOD.monthly);
+  const yearly = priceFor(product, PERIOD.yearly);
+  const once = priceFor(product, PERIOD.once);
+  const price: PricingPlanCard["price"] = {};
+  if (monthly) price.monthly = phrase(monthly, locale, labels);
+  if (yearly) price.annual = phrase(yearly, locale, labels);
+  if (once && !monthly && !yearly) price.custom = phrase(once, locale, labels);
+
+  const card: PricingPlanCard = {
+    key: product.plan,
+    name: stripFormatCharacters(product.name),
+    price,
+    features: features(product),
+    cta: { label: labels.cta, href },
+  };
+  const description =
+    product.description && stripFormatCharacters(product.description, true);
+  if (description) card.description = description;
+  if (product.unitLabel)
+    card.priceUnit = stripFormatCharacters(product.unitLabel);
+  if (product.note) card.priceSubhead = stripFormatCharacters(product.note);
+  if (product.termsNote)
+    card.priceFootnote = stripFormatCharacters(product.termsNote);
+  // Annual mode shows the yearly Price only when a monthly one is beside it,
+  // so only then does the card need a second link (D5, D6).
+  const annualHref =
+    monthly && yearly && offeringsCheckoutHref(yearly.lookupKey);
+  if (annualHref) card.annualCtaHref = annualHref;
+  if (highlighted) {
+    card.highlighted = true;
+    card.highlightStyle = "pill";
+    card.highlightLabel = labels.recommended;
+  }
+  return card;
+}
+
+function addonTile(
+  product: OfferingsProduct,
+  highlighted: boolean,
+  locale: string,
+  labels: OfferingsPricingLabels,
+): PricingAddonTile | null {
+  const shown = shownPrice(product);
+  const href = shown && offeringsCheckoutHref(shown.lookupKey);
+  if (!shown || !href) return null;
+
+  const tile: PricingAddonTile = {
+    key: product.plan,
+    name: stripFormatCharacters(product.name),
+    price: phrase(shown, locale, labels),
+    features: features(product),
+    cta: { label: labels.cta, href },
+  };
+  if (product.unitLabel)
+    tile.qualifier = stripFormatCharacters(product.unitLabel);
+  if (highlighted) {
+    tile.eyebrow = labels.recommended;
+    tile.checkTone = "primary";
+  }
+  return tile;
+}
+
+// #8927 D3 — `GET /v1/content/shown-offerings` sends the shown set without
+// `workspaceId` and `organizationId` (spec 8924 D3), which the strict schema
+// requires. Both ids become optional; an id that is present is still
+// validated, every other field is still required and an unknown key is still
+// refused.
+const shownSetSchema = workspaceShownSetSchema.partial({
+  workspaceId: true,
+  organizationId: true,
+});
+
+function isPresent<T>(value: T | null): value is T {
+  return value !== null;
+}
+
+/**
+ * The shown set as Pricing section data, or `null` when there is nothing to
+ * show: a value the shown-set schema refuses, a snapshot that is not
+ * `current`, or no offerings. Each fragment is `null` when its group is empty.
+ */
+export function offeringsPricing(
+  shownSet: unknown,
+  options: { locale: string; labels: OfferingsPricingLabels },
+): OfferingsPricing | null {
+  const parsed = shownSetSchema.safeParse(shownSet);
+  if (!parsed.success) return null;
+  const { state, offerings } = parsed.data;
+  if (state !== "current" || offerings.length === 0) return null;
+  const { locale, labels } = options;
+
+  const planProducts = offerings.filter((o) => o.ailkGroup === "plan");
+  const addonProducts = offerings.filter((o) => o.ailkGroup === "addon");
+  const recommendedPlan = firstRecommended(planProducts);
+  const recommendedAddon = firstRecommended(addonProducts);
+
+  const plans = planProducts
+    .map((p) => planCard(p, p.plan === recommendedPlan, locale, labels))
+    .filter(isPresent);
+  const addons = addonProducts
+    .map((p) => addonTile(p, p.plan === recommendedAddon, locale, labels))
+    .filter(isPresent);
+
+  return {
+    plans:
+      plans.length > 0
+        ? {
+            variant: "three-tiers-with-toggle",
+            cardLayout: "centered",
+            billingToggle: plans.some(
+              (card) =>
+                card.price.monthly !== undefined &&
+                card.price.annual !== undefined,
+            ),
+            plans,
+          }
+        : null,
+    addons: addons.length > 0 ? { variant: "addons", plans: [], addons } : null,
+  };
+}

package/templates/apps/web/lib/posting-title.ts

@@ -0,0 +1,17 @@
+/**
+ * The posting a `/careers/<slug>/apply` page applies to, read by its title
+ * (#8840 D11). The read sits here, not in a page, so the structured-data walk
+ * does not take an apply page for a JobPosting page: the posting's own JSON-LD
+ * is `/careers/<slug>`'s. In `lib/` (#8849 D9), not a route directory, so
+ * every scaffold carries it: the `signal-collectors` walk and the Free apply
+ * page (`careers/[slug]/[action]`) both read it.
+ */
+import { getMdxSource } from "@working-theory/page-renderer";
+
+/** The posting's title in `locale`, or `null` when no posting has this slug. */
+export async function postingTitle(slug: string, locale: string): Promise<string | null> {
+  const source = await getMdxSource("JobPosting", slug, locale);
+  if (source === null) return null;
+  const title = (source.frontmatter as { title?: unknown }).title;
+  return typeof title === "string" && title.trim() !== "" ? title : null;
+}

package/templates/apps/web/lib/prisma-for-auth.ts

@@ -9,6 +9,14 @@
  * `lib/license-key-store.ts`, which hands `prismaForAuth.siteSetting` to the
  * licence client's SiteSetting store for the ONE deployment-wide
  * `license.renewed_key` row (#6677 DD-6 — a narrow, named exception).
+ *
+ * A third use rides on `auth.ts`'s own (#8765 D4, SEC-8765-K):
+ * `lib/sign-up-agreements.ts`'s account hook writes the new user's `sign_up`
+ * consent grants through `consentGrant.createMany` on the transaction client
+ * Better Auth's sign-up transaction runs on — only rows for the user that
+ * transaction is creating, never a read and never any other row. It imports
+ * nothing from here; it reaches the client through the adapter.
+ *
  * Every other business-logic caller goes through apps/api, never the
  * database directly (architecture.yaml `apps/web` may_not_import_from
  * `database`; the single-file singleton here is the documented exception,