create-ailk 0.22.0 → 0.24.0

package/templates/apps/api/src/routes/content/pricing.ts

@@ -0,0 +1,176 @@
+/**
+ * GET /v1/content/pricing
+ *
+ * The site's pricing tiers, read from a `Product` page's `offers` (#7178).
+ * The HTTP twin of the `get_pricing` MCP tool: same arguments, parsed with
+ * the same `@working-theory/validation` schema, and the same result, produced
+ * by the same function — `getPricingTiers` in `@working-theory/content-adapters`,
+ * the shared seam the tool also answers through. That is the API ↔ MCP parity
+ * contract in the root CLAUDE.md; the parity guard's `get_pricing` row is a
+ * `twin` naming this route.
+ *
+ * Query:
+ *   slug    optional — lowercase alphanumeric and hyphens; default `pricing`
+ *   locale  optional — BCP-47 (`xx` or `xx-XX`). A well-formed tag outside the
+ *           project's allowlist silently falls back to the default locale
+ *           (AC-i18n-07), matching every other content read; a malformed one
+ *           is a 400, as the tool refuses it.
+ *
+ * Success: `{ ok: true, data: { tiers } | null }` — the API's documented
+ * envelope, not the JSON-LD `ItemList` the older content routes answer. "No
+ * pricing" is a 200 with `data: null`, exactly as the tool answers it.
+ * Refusals: `400 validation_failed` (issues are not echoed), `404 not_found`
+ * when no public site resolves, `500 internal_error`.
+ *
+ * Registered BEFORE `/v1/content/:type` in `index.ts`. Fastify's radix router
+ * prefers a static segment over a parametric one regardless of order — the
+ * ordering is belt-and-braces, as it is for search. `/v1/content/Pricing`
+ * (the page type, capitalised) stays the type list.
+ *
+ * Rate limiting is inherited: `server.ts` registers the limiter GLOBALLY with
+ * the content ceiling, so this route is covered without one of its own.
+ *
+ * Which site this read serves is resolved BEFORE any content query (#5852)
+ * through the same `resolvePublicContentAdapter(request)` seam the sibling
+ * content reads use. The resolver reads `x-ailk-spoke-key`, so every answer
+ * past the query parse appends that header to `Vary`: a cache keyed on the
+ * URL alone must never share one site's answer — or one bad key's 404 — with
+ * another. It appends rather than sets, because `@fastify/cors` has already
+ * written `Vary: Origin`.
+ *
+ * Offerings (#8933, spec D4): on a connected workspace with a current shown
+ * set, the `pricing` page (the default slug) answers that set instead — one
+ * tier per Stripe Price, through `readShownOfferings` (#8924's read, the one
+ * code path every agent surface shares) and `pricingTiersFromShownSet` in
+ * `@working-theory/content-adapters`, the mapping the tool answers through
+ * too. Each tier then also carries `interval` and the full `lookupKey`. Every
+ * other slug, and every workspace with no connection, no claim or no current
+ * set, answers page content exactly as before; a failed shown-set read takes
+ * the content path too. The read refreshes, or not, exactly as the
+ * shown-offerings route does (`options`, D5): never with the owner's
+ * override, never per request (T7).
+ *
+ * Anonymous and identity-blind: no `Authorization`, cookie, session or user
+ * id is read.
+ */
+import {
+  currentShownSet,
+  getPricingTiers,
+  pricingTiersFromShownSet,
+  shownSetAnswersPricing,
+} from "@working-theory/content-adapters";
+import {
+  getPricingInputSchema,
+  type GetPricingOutput,
+} from "@working-theory/validation";
+import type {
+  FastifyPluginAsync,
+  FastifyReply,
+  FastifyRequest,
+} from "fastify";
+
+import { resolveLocale } from "../../lib/locales.js";
+import { resolvePublicContentAdapter } from "../../services/public-site-resolver.js";
+
+import {
+  readShownOfferings,
+  type ShownOfferingsRouteOptions,
+} from "./shown-offerings.js";
+
+/** The request header the resolver picks the site's workspace from. */
+const SPOKE_KEY_HEADER = "x-ailk-spoke-key";
+
+/** Adds the spoke-key header to `Vary`, keeping every value already there. */
+function varyOnSpokeKey(reply: FastifyReply): void {
+  const existing = reply.getHeader("vary");
+  const values = (
+    Array.isArray(existing) ? existing.join(",") : String(existing ?? "")
+  )
+    .split(",")
+    .map((value) => value.trim())
+    .filter((value) => value !== "");
+  if (!values.some((value) => value.toLowerCase() === SPOKE_KEY_HEADER)) {
+    values.push(SPOKE_KEY_HEADER);
+  }
+  reply.header("Vary", values.join(", "));
+}
+
+/** An error's class name only — never its message, which may carry Stripe text. */
+function errName(err: unknown): string {
+  return err instanceof Error ? err.constructor.name : typeof err;
+}
+
+/**
+ * The connected workspace's shown set as tiers, or `null` for the content
+ * path (#8933 D4). A failed read or mapping is one fixed `warn` line and the
+ * content path, never a 500 and never an `{ err }` line.
+ */
+async function shownSetTiers(
+  request: FastifyRequest,
+  options: ShownOfferingsRouteOptions,
+): Promise<NonNullable<GetPricingOutput> | null> {
+  try {
+    const shownSet = currentShownSet(
+      await readShownOfferings(request, options),
+    );
+    return shownSet === null ? null : pricingTiersFromShownSet(shownSet);
+  } catch (err) {
+    request.log.warn(
+      { outcome: "shown_set_failed", errName: errName(err) },
+      "[Content] pricing: shown set unavailable, answering page content",
+    );
+    return null;
+  }
+}
+
+export const pricingRoute: FastifyPluginAsync<
+  ShownOfferingsRouteOptions
+> = async (fastify, options) => {
+  fastify.get<{
+    Querystring: { slug?: string; locale?: string };
+  }>("/v1/content/pricing", async (request, reply) => {
+    const query = getPricingInputSchema.safeParse(request.query);
+    if (!query.success) {
+      return reply.status(400).send({
+        ok: false,
+        error: {
+          code: "validation_failed",
+          message: "Invalid query parameters",
+        },
+      });
+    }
+
+    const locale = resolveLocale(query.data.locale);
+    // Every answer from here on depends on the spoke key — the 404 and 500
+    // included — so each carries the Vary.
+    varyOnSpokeKey(reply);
+
+    try {
+      const adapter = await resolvePublicContentAdapter(request);
+      if (adapter === null) {
+        return reply.status(404).send({
+          ok: false,
+          error: { code: "not_found", message: "Page not found" },
+        });
+      }
+
+      if (shownSetAnswersPricing(query.data.slug)) {
+        const tiers = await shownSetTiers(request, options);
+        if (tiers !== null) return reply.send({ ok: true, data: tiers });
+      }
+
+      const data = await getPricingTiers(adapter, {
+        slug: query.data.slug,
+        locale,
+      });
+
+      return reply.send({ ok: true, data });
+    } catch (error) {
+      request.log.error({ err: error }, "[Content] getPricingTiers failed");
+      return reply.status(500).send({
+        ok: false,
+        error: { code: "internal_error", message: "Internal server error" },
+      });
+    }
+  });
+};

package/templates/apps/api/src/routes/content/search.ts

@@ -7,11 +7,12 @@
  * parity contract in the root CLAUDE.md. Until this route existed the parity
  * was one-sided, the tool having no endpoint to map to.
  *
- * Query:
- *   q        required, 1..200 chars — the search string. The ceiling matches
- *            the `search_content` MCP tool's own cap (`searchContentInputSchema`)
- *            so the pair rejects the same inputs, and bounds the work an
- *            unauthenticated caller can ask of the scorer per request.
+ * Query — parsed with `contentSearchQuerySchema` (`@working-theory/validation`),
+ * the export the `search_content` MCP tool parses with too, so the pair
+ * accepts and rejects the same inputs (#7167):
+ *   q        required, 1..200 chars — the search string. The ceiling bounds
+ *            the work an unauthenticated caller can ask of the scorer per
+ *            request.
  *   type     optional — a schema.org page type
  *   category optional — a LEAF slug from the site-category registry. Outside
  *            the registry is a 400, not an empty result: the registry is
@@ -26,10 +27,10 @@
  * ordering is belt-and-braces, and `/v1/content/types` is the same shape that
  * already proves it.
  *
- * The response is an `ItemList` JSON-LD document. `items` is the adapter's own
- * `SearchResult[]`, unreshaped: a caller comparing this route against the MCP
- * tool must see the same objects, and a projection here would be the place
- * they silently diverged.
+ * The response is an `ItemList` JSON-LD document, built by
+ * `searchContentItemList` in `@working-theory/content-adapters` — the shared
+ * seam the MCP tool answers through, so the pair cannot diverge. `items` is
+ * the adapter's own `SearchResult[]`, unreshaped.
  *
  * Rate limiting is inherited: `server.ts` registers the limiter GLOBALLY with
  * the content ceiling (`rate-limit.ts`'s `CONTENT_RATE_LIMIT_UNAUTH` /
@@ -46,30 +47,13 @@
  * carries no detail an unauthenticated caller could use to tell it apart
  * from "nothing matched" (AC-WCE-05).
  */
-import {
-  SCHEMA_ORG_TYPES,
-  type SearchOptions,
-} from "@working-theory/content-adapters";
-import { CategorySlugSchema } from "@working-theory/schema/categories";
+import { searchContentItemList } from "@working-theory/content-adapters";
+import { contentSearchQuerySchema } from "@working-theory/validation";
 import type { FastifyPluginAsync } from "fastify";
-import { z } from "zod";
 
 import { resolveLocale } from "../../lib/locales.js";
 import { resolvePublicContentAdapter } from "../../services/public-site-resolver.js";
 
-const LIMIT_MAX = 50;
-const LIMIT_DEFAULT = 10;
-/** Mirrors `searchContentInputSchema`'s `query` cap — the pair rejects alike. */
-const QUERY_MAX = 200;
-
-const querySchema = z.object({
-  q: z.string().min(1).max(QUERY_MAX),
-  type: z.enum(SCHEMA_ORG_TYPES).optional(),
-  category: CategorySlugSchema.optional(),
-  limit: z.coerce.number().int().min(1).max(LIMIT_MAX).default(LIMIT_DEFAULT),
-  locale: z.string().optional(),
-});
-
 export const searchContentRoute: FastifyPluginAsync = async (fastify) => {
   fastify.get<{
     Querystring: {
@@ -80,7 +64,7 @@ export const searchContentRoute: FastifyPluginAsync = async (fastify) => {
       locale?: string;
     };
   }>("/v1/content/search", async (request, reply) => {
-    const query = querySchema.safeParse(request.query);
+    const query = contentSearchQuerySchema.safeParse(request.query);
     if (!query.success) {
       return reply.status(400).send({
         error: "Invalid query parameters",
@@ -91,13 +75,6 @@ export const searchContentRoute: FastifyPluginAsync = async (fastify) => {
     const { q, type, category, limit } = query.data;
     const locale = resolveLocale(query.data.locale);
 
-    const options: SearchOptions = {
-      limit,
-      ...(type !== undefined && { type }),
-      ...(category !== undefined && { category }),
-      locale,
-    };
-
     try {
       // Site resolution precedes any content query (#5852, #5910). A refusal
       // is a 404 sharing the same "Page not found" error string a
@@ -112,15 +89,9 @@ export const searchContentRoute: FastifyPluginAsync = async (fastify) => {
         });
       }
 
-      const items = await adapter.searchPages(q, options);
-
-      return reply.send({
-        "@context": "https://schema.org",
-        "@type": "ItemList",
-        query: q,
-        items,
-        totalItems: items.length,
-      });
+      return reply.send(
+        await searchContentItemList(adapter, { q, type, category, limit, locale }),
+      );
     } catch (error) {
       request.log.error({ err: error }, "[Content] searchPages failed");
       return reply.status(500).send({ error: "Internal server error" });

package/templates/apps/api/src/routes/content/shown-offerings.ts

@@ -0,0 +1,229 @@
+/**
+ * GET /v1/content/shown-offerings
+ *
+ * The `/pricing` page's Offerings read (#8924, spec
+ * docs/specs/8924-the-anonymous-pricing-read-the-spec.md): the resolved
+ * workspace's shown set, read from its persisted Stripe snapshot through
+ * #8876's `getWorkspaceShownSet`. No argument — no path parameter, query or
+ * body, and a query string is ignored.
+ *
+ * Answers (D2), each in the `{ ok, data }` envelope, never a JSON-LD root:
+ *   `{ status: "shown", shownSet }` — a resolved, connected workspace with
+ *       the `commerce` claim. `shownSet` is the service's parsed result less
+ *       `workspaceId` and `organizationId`: `productIds`, `recommended`,
+ *       `offerings`, `state` and `snapshotAt`, as the service answered them.
+ *   `{ status: "unconnected" }` — render the page content as today: the
+ *       content adapter is not `database` (the resolver's `not-required`),
+ *       the licence lacks the claim, or the workspace has no connection or
+ *       no `WorkspaceOfferings` row.
+ *   `{ status: "empty" }` — fail closed, show no prices at all: the resolver
+ *       answered `unresolved` (a refused spoke key, an ambiguous or unmatched
+ *       host), or the licence is configured but cannot be read.
+ *   `500 internal_error` — the resolver, the claim read or the first read
+ *       threw. A refresh never turns an answer into a 500.
+ *
+ * T7 — an anonymous read never reaches Stripe per request (D6). A snapshot
+ * that is not `current`, or is at least `SHOWN_OFFERINGS_REFRESH_AFTER_MS`
+ * old, triggers `refreshWorkspaceSnapshot` on its bounded path only: the
+ * service joins the Organization's read in flight, reuses a read under a
+ * minute old and holds a failed one for a minute. This route never passes
+ * the owner's override, keeps no state of its own, and waits at most
+ * `SHOWN_OFFERINGS_REFRESH_BUDGET_MS`; a refresh that fails, stalls or
+ * throws leaves the first read served. `server.ts` registers it with the
+ * Organization's Stripe catalog source (#8922, #9124); registered with no
+ * `sourceFor` (D7) it serves the persisted snapshot and never refreshes.
+ *
+ * The workspace comes only from `resolvePublicWorkspace(request)`, whose one
+ * request input is a hub spoke's `x-ailk-spoke-key`; so every answer, the
+ * 500 included, appends that header to `Vary`. No `Cache-Control` is set.
+ * The claim is read in the handler, not by the `requireCommerceClaim`
+ * preHandler, so a refused spoke key answers `empty` rather than a 404 (D4),
+ * and the services are imported only after it reads `claimed` (D5).
+ *
+ * T6 — a log line carries only the resolver's `reason`, a fixed `outcome`,
+ * `workspaceId` and an error's class name: never a product or price id, a
+ * name, any Stripe text or an error message (D9).
+ *
+ * Rate limiting is inherited from the server's global content ceiling. No
+ * MCP twin, by decision (`tests/parity/README.md`, D8): agents read offerings
+ * through `get_pricing` and `get_offerings`, whose HTTP twins answer through
+ * this file's `readShownOfferings` (#8933 D1) — the one read of the snapshot
+ * every agent surface shares.
+ *
+ * Anonymous and identity-blind: no `Authorization`, cookie, session or user
+ * id is read.
+ */
+import type { ShownOfferingsAnswer } from "@working-theory/validation";
+import type {
+  FastifyPluginAsync,
+  FastifyReply,
+  FastifyRequest,
+} from "fastify";
+
+import { resolveCommerceClaim } from "../../lib/require-commerce-claim.js";
+import type { OfferingsSourceFor } from "../../services/offerings/index.js";
+import { resolvePublicWorkspace } from "../../services/public-site-resolver.js";
+
+/** A snapshot at least this old is refreshed, on the service's own bound. */
+export const SHOWN_OFFERINGS_REFRESH_AFTER_MS = 60_000;
+/** The longest one request waits on a refresh before serving its first read. */
+export const SHOWN_OFFERINGS_REFRESH_BUDGET_MS = 3000;
+
+export interface ShownOfferingsRouteOptions {
+  /** The Stripe-backed catalog source; without it the route never refreshes. */
+  sourceFor?: OfferingsSourceFor;
+  now?: () => Date;
+}
+
+/** The request header the resolver picks the site's workspace from. */
+const SPOKE_KEY_HEADER = "x-ailk-spoke-key";
+
+/** Adds the spoke-key header to `Vary`, keeping every value already there. */
+function varyOnSpokeKey(reply: FastifyReply): void {
+  const existing = reply.getHeader("vary");
+  const values = (
+    Array.isArray(existing) ? existing.join(",") : String(existing ?? "")
+  )
+    .split(",")
+    .map((value) => value.trim())
+    .filter((value) => value !== "");
+  if (!values.some((value) => value.toLowerCase() === SPOKE_KEY_HEADER)) {
+    values.push(SPOKE_KEY_HEADER);
+  }
+  reply.header("Vary", values.join(", "));
+}
+
+/** An error's class name only — never its message, which may carry Stripe text. */
+function errName(err: unknown): string {
+  return err instanceof Error ? err.constructor.name : typeof err;
+}
+
+const OVER_BUDGET = Symbol("over-budget");
+
+/**
+ * The read itself (#8933 D1), shared by this route and the two agent twins
+ * (`GET /v1/content/pricing` and `GET /v1/content/offerings`): the
+ * resolver's arms, the claim gate, the late import and the bounded refresh,
+ * answering one of the three answers. It sets no header and writes no reply;
+ * a resolver, claim or first-read error rejects. Its log lines go through
+ * `request.log`, so a twin's request emits them too.
+ */
+export async function readShownOfferings(
+  request: FastifyRequest,
+  { sourceFor, now: clock = () => new Date() }: ShownOfferingsRouteOptions,
+): Promise<ShownOfferingsAnswer> {
+  const now = clock();
+
+  const resolution = await resolvePublicWorkspace(request);
+  if (resolution.kind === "unresolved") {
+    request.log.warn(
+      { reason: resolution.reason },
+      "[content] shown-offerings: workspace unresolved",
+    );
+    return { status: "empty" };
+  }
+  if (resolution.kind === "not-required") {
+    return { status: "unconnected" };
+  }
+
+  const claim = await resolveCommerceClaim();
+  if (claim === "unclaimed") {
+    return { status: "unconnected" };
+  }
+  if (claim === "undetermined") {
+    request.log.warn(
+      { outcome: "license_undetermined" },
+      "[content] shown-offerings: licence unreadable",
+    );
+    return { status: "empty" };
+  }
+
+  const { workspaceId } = resolution;
+  const { getWorkspaceShownSet, refreshWorkspaceSnapshot } =
+    await import("../../services/offerings/index.js");
+  let shown = await getWorkspaceShownSet(workspaceId, { now });
+  if (shown === null) {
+    return { status: "unconnected" };
+  }
+
+  const stale =
+    shown.state !== "current" ||
+    shown.snapshotAt === null ||
+    now.getTime() - Date.parse(shown.snapshotAt) >=
+      SHOWN_OFFERINGS_REFRESH_AFTER_MS;
+  if (sourceFor && stale) {
+    // Caught before the race, so a rejection after the budget is logged
+    // the same way and is never unhandled.
+    const refresh = refreshWorkspaceSnapshot(workspaceId, sourceFor, {
+      now,
+    }).catch((err: unknown) => {
+      request.log.warn(
+        { workspaceId, outcome: "refresh_failed", errName: errName(err) },
+        "[content] shown-offerings: refresh failed",
+      );
+      return null;
+    });
+    let timer: NodeJS.Timeout | undefined;
+    const budget = new Promise<typeof OVER_BUDGET>((resolve) => {
+      timer = setTimeout(
+        () => resolve(OVER_BUDGET),
+        SHOWN_OFFERINGS_REFRESH_BUDGET_MS,
+      );
+    });
+    let outcome: Awaited<typeof refresh> | typeof OVER_BUDGET;
+    try {
+      outcome = await Promise.race([refresh, budget]);
+    } finally {
+      clearTimeout(timer);
+    }
+
+    if (outcome === OVER_BUDGET) {
+      request.log.warn(
+        { workspaceId, outcome: "refresh_over_budget" },
+        "[content] shown-offerings: refresh over budget",
+      );
+    } else if (outcome === "refreshed") {
+      try {
+        const reread = await getWorkspaceShownSet(workspaceId, { now });
+        if (reread === null) {
+          return { status: "unconnected" };
+        }
+        shown = reread;
+      } catch (err) {
+        request.log.warn(
+          { workspaceId, outcome: "reread_failed", errName: errName(err) },
+          "[content] shown-offerings: re-read failed",
+        );
+      }
+    }
+  }
+
+  const {
+    workspaceId: _workspaceId,
+    organizationId: _organizationId,
+    ...shownSet
+  } = shown;
+  return { status: "shown", shownSet };
+}
+
+export const shownOfferingsRoute: FastifyPluginAsync<
+  ShownOfferingsRouteOptions
+> = async (fastify, options) => {
+  fastify.get("/v1/content/shown-offerings", async (request, reply) => {
+    varyOnSpokeKey(reply);
+
+    try {
+      const data = await readShownOfferings(request, options);
+      return reply.send({ ok: true, data });
+    } catch (err) {
+      request.log.error(
+        { errName: errName(err) },
+        "[content] shown-offerings read failed",
+      );
+      return reply.status(500).send({
+        ok: false,
+        error: { code: "internal_error", message: "Internal server error" },
+      });
+    }
+  });
+};