create-ailk 0.5.0 → 0.6.1

package/templates/apps/api/src/openapi/spec.ts

@@ -19,6 +19,7 @@ import { join } from "node:path";
 
 import { SCHEMA_ORG_TYPES } from "@working-theory/content-adapters";
 import { logger } from "@working-theory/observability";
+import { SITE_CATEGORIES } from "@working-theory/schema/categories";
 import { parse as parseYaml } from "yaml";
 
 import { config } from "../config/index.js";
@@ -251,6 +252,29 @@ export function readRegisteredRoutes(source: unknown): RegisteredRoute[] {
   return Array.isArray(routes) ? (routes as RegisteredRoute[]) : [];
 }
 
+/**
+ * The `{ ok: false, error: { code, message } }` envelope (apps/api/CLAUDE.md)
+ * identity-bound tenant routes answer on 400/401/403 — distinct from the
+ * `{ error: string }` shape `ErrorResponse` documents for the anonymous
+ * content routes. Shared here so `/v1/schedule/appointments`'s three error
+ * responses (#6085) reference one literal rather than three copies.
+ */
+const tenantErrorResponseSchema = {
+  type: "object",
+  required: ["ok", "error"],
+  properties: {
+    ok: { type: "boolean", enum: [false] },
+    error: {
+      type: "object",
+      required: ["code", "message"],
+      properties: {
+        code: { type: "string" },
+        message: { type: "string" },
+      },
+    },
+  },
+} as const;
+
 /**
  * Root-index keys this API has already published, by Fastify path (#5314 D6).
  *
@@ -271,9 +295,13 @@ const CURATED_ROOT_INDEX_KEYS: Record<string, string> = {
   "/v1/user/profile": "profile",
   "/v1/user/data/:key": "userData",
   "/v1/content/types": "contentTypes",
+  "/v1/content/search": "contentSearch",
   "/v1/content/:type": "contentList",
   "/v1/content/:type/:slug": "contentPage",
   "/v1/checkout/sessions": "checkoutSessions",
+  // #6084 §4.2 — one entry, so the root index publishes a stable
+  // `checkoutSession` key rather than a `generatedRootIndexKey` fallback.
+  "/v1/checkout/sessions/:id": "checkoutSession",
   "/v1/billing": "billing",
   "/v1/billing/portal-session": "billingPortalSession",
 };
@@ -437,6 +465,9 @@ export function buildOpenApiSpec(
   registeredRoutes: RegisteredRoute[] = [],
 ) {
   const typeEnum = [...SCHEMA_ORG_TYPES];
+  // Derived, never hand-listed: widening the registry widens the documented
+  // enum with no second edit here.
+  const categoryEnum = SITE_CATEGORIES.map((category) => category.slug);
 
   return {
     openapi: "3.1.0",
@@ -544,6 +575,168 @@ export function buildOpenApiSpec(
             },
           },
         },
+        // #6084 — the read half, under the SAME commerce gate as the POST
+        // above (AC-3). PII-free by construction: the response schema names
+        // the D3 six-key allow-list, never a spread.
+        "/v1/checkout/sessions/{id}": {
+          get: {
+            operationId: "getCheckoutSession",
+            summary: "Read a Checkout Session's payment status and paid line items",
+            description:
+              "Reads a Checkout Session's status, payment status, and paid line " +
+              "items. Read-only — never creates or mutates a Stripe object. The " +
+              "response is PII-free: no customer identity, payment method, or " +
+              "metadata field is ever returned.",
+            parameters: [
+              {
+                name: "id",
+                in: "path",
+                required: true,
+                description: "Stripe Checkout Session id (cs_…)",
+                schema: { type: "string", pattern: "^cs_[A-Za-z0-9_]{1,250}$" },
+              },
+            ],
+            responses: {
+              "200": {
+                description: "Checkout Session status, payment status, and paid line items",
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/CheckoutSessionReadResponse",
+                    },
+                  },
+                },
+              },
+              "400": {
+                description: "Validation error — the id fails the shape check",
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/ValidationErrorResponse",
+                    },
+                  },
+                },
+              },
+              "404": {
+                description: "Unknown session — no Checkout Session matches the given id",
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/UnknownSessionResponse",
+                    },
+                  },
+                },
+              },
+              "500": {
+                description:
+                  "Live-mode forbidden — STRIPE_SECRET_KEY is a live key",
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/LiveModeForbiddenResponse",
+                    },
+                  },
+                },
+              },
+              "502": {
+                description:
+                  "Checkout unavailable — Stripe returned an unexpected error",
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/CheckoutUnavailableResponse",
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      }),
+      // Module-conditional (scheduling, #6085 brief H7) — mirrors the
+      // `/v1/checkout/sessions` gate immediately above: without it a build
+      // with the module off would still advertise the operation while
+      // `registeredRoutes` carries no matching entry (surface-drift.test.ts,
+      // #5314). The doc comment below deliberately never names the
+      // scheduling provider (§ 1.12, § 9 SEC-13) — this file is scanned by
+      // `architecture.yaml`'s `cal\.com` forbidden pattern like every other
+      // `apps/api/**` file, which is EXCLUDED from it, but the wording
+      // itself is written provider-neutral anyway since it documents the
+      // AILK-side contract, not the provider's.
+      ...(isModuleEnabled("scheduling") && {
+        "/v1/schedule/appointments": {
+          get: {
+            operationId: "listAppointments",
+            summary: "List this site's own appointments",
+            description:
+              "The tenant-guarded read over this site's normalized booking " +
+              "rows (#6085). Identity-bound: requires an authenticated " +
+              "session carrying an owner|admin role on the active workspace " +
+              "— the rows carry attendee contact PII. `window` selects " +
+              "upcoming (the default), past, or all; `cursor` is the " +
+              "previous page's last row id.",
+            parameters: [
+              {
+                name: "limit",
+                in: "query",
+                required: false,
+                schema: { type: "integer", minimum: 1, maximum: 200, default: 50 },
+              },
+              {
+                name: "cursor",
+                in: "query",
+                required: false,
+                description: "The previous page's last row id.",
+                schema: { type: "string" },
+              },
+              {
+                name: "window",
+                in: "query",
+                required: false,
+                schema: {
+                  type: "string",
+                  enum: ["upcoming", "past", "all"],
+                  default: "upcoming",
+                },
+              },
+            ],
+            responses: {
+              "200": {
+                description: "OK",
+                content: {
+                  "application/json": {
+                    schema: { $ref: "#/components/schemas/AppointmentListResponse" },
+                  },
+                },
+              },
+              // The `{ ok: false, error: { code, message } }` shape
+              // (apps/api/CLAUDE.md) — distinct from the `{ error }` string
+              // shape `ErrorResponse` documents for the anonymous content
+              // routes, so 400/401/403 each get this inline schema rather
+              // than `$ref`ing that one.
+              "400": {
+                description: "Invalid query parameters, or an unresolvable cursor",
+                content: {
+                  "application/json": { schema: tenantErrorResponseSchema },
+                },
+              },
+              "401": {
+                description: "Authentication required",
+                content: {
+                  "application/json": { schema: tenantErrorResponseSchema },
+                },
+              },
+              "403": {
+                description: "Forbidden — caller lacks the owner|admin role floor",
+                content: {
+                  "application/json": { schema: tenantErrorResponseSchema },
+                },
+              },
+              "429": { $ref: "#/components/responses/RateLimited" },
+              "500": { $ref: "#/components/responses/ServerError" },
+            },
+          },
+        },
       }),
       "/v1/leads/submit": {
         post: {
@@ -658,6 +851,150 @@ export function buildOpenApiSpec(
           },
         },
       },
+      "/v1/requests/{id}/confirm": {
+        get: {
+          operationId: "getRequestConfirmForm",
+          summary: "Open a callback request's confirm form",
+          description:
+            "Renders the site owner's confirm form for one callback request " +
+            "(#5970). The `token` query parameter is a one-time, expiring " +
+            "credential emailed to the owner when the request landed; it is " +
+            "the sole gate on this route, so there is no auth header. This " +
+            "operation answers `text/html` rather than JSON — it is a page a " +
+            "person opens from a mail client, not an agent surface. A token " +
+            "that is tampered with, expired, already used, or valid for a " +
+            "different request all answer the same 404. Requires the " +
+            "`commerce` licence claim; without it the route answers 404, " +
+            "indistinguishable from a build without the module.",
+          parameters: [
+            {
+              name: "id",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+              description: "The callback request's id.",
+            },
+            {
+              name: "token",
+              in: "query",
+              required: true,
+              schema: { type: "string" },
+              description: "The one-time confirm credential from the email.",
+            },
+          ],
+          responses: {
+            "200": {
+              description: "The confirm form",
+              content: { "text/html": { schema: { type: "string" } } },
+            },
+            "404": {
+              description:
+                "No live request for that id and token — or the module is not " +
+                "licensed",
+              content: { "text/html": { schema: { type: "string" } } },
+            },
+          },
+        },
+        post: {
+          operationId: "confirmRequest",
+          summary: "Confirm a callback request and send a payment link",
+          description:
+            "Stamps the confirmed time, creates one Stripe Payment Link on " +
+            "the site's own Stripe account, stores its id on the request, and " +
+            "emails the customer that hosted URL (#5970). The credential is " +
+            "spent in the same statement that stamps the confirmation, so a " +
+            "second submission answers 404 and no second Payment Link is ever " +
+            "created. The body carries EITHER `amountMinor` + `currency` (a " +
+            "price set here and now) OR `lookupKey` (a price already in the " +
+            "site's Stripe catalogue) — both, or neither, is a 400 before any " +
+            "Stripe call. Sandbox-only: a live Stripe key is refused before " +
+            "the credential is claimed.",
+          parameters: [
+            {
+              name: "id",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+              description: "The callback request's id.",
+            },
+          ],
+          requestBody: {
+            required: true,
+            content: {
+              "application/x-www-form-urlencoded": {
+                schema: {
+                  type: "object",
+                  required: ["token", "confirmedTime", "buyerEmail"],
+                  properties: {
+                    token: {
+                      type: "string",
+                      description: "The one-time confirm credential.",
+                    },
+                    confirmedTime: {
+                      type: "string",
+                      description:
+                        "The agreed time, as the site owner typed it.",
+                    },
+                    buyerEmail: {
+                      type: "string",
+                      format: "email",
+                      description: "Where the payment link is sent.",
+                    },
+                    amountMinor: {
+                      type: "integer",
+                      minimum: 1,
+                      description:
+                        "The price in MINOR units. Mutually exclusive with " +
+                        "lookupKey, and capped by AILK_REQUEST_CONFIRM_MAX_MINOR.",
+                    },
+                    currency: {
+                      type: "string",
+                      description:
+                        "Lowercase ISO-4217. Defaults to the site's configured " +
+                        "currency. Only meaningful beside amountMinor.",
+                    },
+                    lookupKey: {
+                      type: "string",
+                      description:
+                        "An existing Stripe price's lookup_key. Mutually " +
+                        "exclusive with amountMinor.",
+                    },
+                  },
+                },
+              },
+            },
+          },
+          responses: {
+            "200": {
+              description:
+                "Confirmed — the page carries the hosted Stripe payment URL",
+              content: { "text/html": { schema: { type: "string" } } },
+            },
+            "400": {
+              description:
+                "Invalid form, both or neither price path, an amount above the " +
+                "site's ceiling, or a lookup key no active Stripe price matches",
+              content: { "text/html": { schema: { type: "string" } } },
+            },
+            "404": {
+              description:
+                "No live request for that id and token — or the module is not " +
+                "licensed",
+              content: { "text/html": { schema: { type: "string" } } },
+            },
+            "500": {
+              description: "Stripe is not configured, or the key is not test-mode",
+              content: { "text/html": { schema: { type: "string" } } },
+            },
+            "502": {
+              description:
+                "Stripe could not create the Payment Link. The request is " +
+                "confirmed; the credential is spent.",
+              content: { "text/html": { schema: { type: "string" } } },
+            },
+          },
+        },
+      },
       "/v1/leads/callback": {
         post: {
           operationId: "requestCallback",
@@ -733,6 +1070,70 @@ export function buildOpenApiSpec(
           },
         },
       },
+      "/v1/content/search": {
+        get: {
+          operationId: "searchContent",
+          summary: "Search published pages by keyword",
+          description:
+            "Keyword search across published pages, scored on title, description and body and returned highest-first. The HTTP twin of the `search_content` MCP tool — the same arguments return the same result set. Optional `category` filters to pages whose `categories` frontmatter includes the given LEAF slug from the closed site-category registry; unlike `locale`, a slug outside the registry is a 400 rather than a silent fallback. Optional locale query parameter selects the locale to search; invalid or unknown locales silently fall back to the project's default locale (AC-i18n-07).",
+          parameters: [
+            {
+              name: "q",
+              in: "query",
+              required: true,
+              description:
+                "The search string. 1–200 characters; the ceiling matches the `search_content` MCP tool's own cap.",
+              schema: { type: "string", minLength: 1, maxLength: 200 },
+            },
+            {
+              name: "type",
+              in: "query",
+              required: false,
+              schema: { type: "string", enum: typeEnum },
+            },
+            {
+              name: "category",
+              in: "query",
+              required: false,
+              description:
+                "A leaf slug from the site-category registry. Group slugs are not valid values — a group is always derived from its leaves.",
+              schema: { type: "string", enum: categoryEnum },
+            },
+            {
+              name: "limit",
+              in: "query",
+              required: false,
+              schema: {
+                type: "integer",
+                minimum: 1,
+                maximum: 50,
+                default: 10,
+              },
+            },
+            {
+              name: "locale",
+              in: "query",
+              required: false,
+              description:
+                "BCP-47 locale tag (e.g. `en`, `es`, `zh-CN`). Invalid or unknown locales silently fall back to the project's default locale.",
+              schema: { type: "string", pattern: "^[a-z]{2}(-[A-Z]{2})?$" },
+            },
+          ],
+          responses: {
+            "200": {
+              description: "OK",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/SearchResponse" },
+                },
+              },
+            },
+            "400": { $ref: "#/components/responses/BadRequest" },
+            "429": { $ref: "#/components/responses/RateLimited" },
+            "500": { $ref: "#/components/responses/ServerError" },
+          },
+        },
+      },
       "/v1/content/{type}": {
         get: {
           operationId: "listPagesByType",
@@ -792,7 +1193,7 @@ export function buildOpenApiSpec(
           operationId: "getPageBySlug",
           summary: "Get a single page by type and slug",
           description:
-            "Returns a single page with resolved schema.org JSON-LD spread at the document root, plus the raw frontmatter under `page`. Optional locale query parameter selects the locale to read from; invalid or unknown locales silently fall back to the project's default locale (AC-i18n-07).",
+            "Returns a single page with resolved schema.org JSON-LD spread at the document root, plus the raw frontmatter under `page`. Optional locale query parameter selects the locale to read from; invalid or unknown locales silently fall back to the project's default locale (AC-i18n-07). Optional `include=body` adds the raw published MDX body under `body`; a deployment whose content adapter cannot serve a raw body answers 400.",
           parameters: [
             {
               name: "type",
@@ -814,6 +1215,14 @@ export function buildOpenApiSpec(
                 "BCP-47 locale tag (e.g. `en`, `es`, `zh-CN`). Invalid or unknown locales silently fall back to the project's default locale.",
               schema: { type: "string", pattern: "^[a-z]{2}(-[A-Z]{2})?$" },
             },
+            {
+              name: "include",
+              in: "query",
+              required: false,
+              description:
+                "Opt-in extra field. `body` adds the raw published MDX body under `body`; omitting the parameter serves the base shape unchanged (#5890).",
+              schema: { type: "string", enum: ["body"] },
+            },
           ],
           responses: {
             "200": {
@@ -915,6 +1324,67 @@ export function buildOpenApiSpec(
             error: { type: "string", enum: ["checkout-unavailable"] },
           },
         },
+        // #6084 D3 — the six-key allow-list. Nothing else may appear here;
+        // AC-3's own test asserts set equality against exactly these names.
+        CheckoutSessionReadResponse: {
+          type: "object",
+          required: [
+            "id",
+            "status",
+            "paymentStatus",
+            "currency",
+            "amountTotal",
+            "lineItems",
+          ],
+          properties: {
+            id: {
+              type: "string",
+              description: "The echoed cs_… id, for the buyer to quote to support",
+            },
+            status: {
+              type: "string",
+              enum: ["open", "complete", "expired"],
+            },
+            paymentStatus: {
+              type: "string",
+              enum: ["paid", "unpaid", "no_payment_required"],
+            },
+            currency: {
+              type: "string",
+              description: "ISO-4217 currency code, lowercase",
+            },
+            amountTotal: {
+              type: ["integer", "null"],
+              description: "Session total, in minor currency units",
+            },
+            lineItems: {
+              type: "array",
+              items: {
+                type: "object",
+                required: ["description", "quantity", "amountTotal", "currency"],
+                properties: {
+                  description: {
+                    type: "string",
+                    description: "Stripe's own line-item description (the product name)",
+                  },
+                  quantity: { type: "integer" },
+                  amountTotal: {
+                    type: "integer",
+                    description: "Line total, in minor currency units",
+                  },
+                  currency: { type: "string" },
+                },
+              },
+            },
+          },
+        },
+        UnknownSessionResponse: {
+          type: "object",
+          required: ["error"],
+          properties: {
+            error: { type: "string", enum: ["unknown-session"] },
+          },
+        },
         LeadSubmitRequest: {
           type: "object",
           additionalProperties: false,
@@ -1085,7 +1555,32 @@ export function buildOpenApiSpec(
             },
           },
         },
-        ListResponse: {
+        SearchResult: {
+          type: "object",
+          required: ["slug", "type", "title", "snippet", "score"],
+          properties: {
+            slug: { type: "string" },
+            type: { type: "string", enum: typeEnum },
+            title: { type: "string" },
+            snippet: { type: "string" },
+            score: { type: "number" },
+          },
+        },
+        SearchResponse: {
+          type: "object",
+          required: ["@context", "@type", "query", "items", "totalItems"],
+          properties: {
+            "@context": { type: "string", enum: ["https://schema.org"] },
+            "@type": { type: "string", enum: ["ItemList"] },
+            query: { type: "string" },
+            items: {
+              type: "array",
+              items: { $ref: "#/components/schemas/SearchResult" },
+            },
+            totalItems: { type: "integer", minimum: 0 },
+          },
+        },
+                ListResponse: {
           type: "object",
           required: ["@context", "@type", "type", "items", "pagination"],
           properties: {
@@ -1106,9 +1601,55 @@ export function buildOpenApiSpec(
             "@context": { type: "string", enum: ["https://schema.org"] },
             "@type": { type: "string" },
             page: { $ref: "#/components/schemas/ContentPage" },
+            body: {
+              type: "string",
+              description:
+                "Raw published MDX body. Present only when the request carried `include=body` (#5890).",
+            },
           },
           additionalProperties: true,
         },
+        Appointment: {
+          type: "object",
+          required: [
+            "id",
+            "startTime",
+            "endTime",
+            "title",
+            "attendeeName",
+            "attendeeEmail",
+            "status",
+            "paid",
+          ],
+          properties: {
+            id: { type: "string" },
+            startTime: { type: "string", format: "date-time" },
+            endTime: { type: "string", format: "date-time" },
+            title: { type: "string", nullable: true },
+            attendeeName: { type: "string" },
+            attendeeEmail: { type: "string", format: "email" },
+            status: { type: "string", enum: ["pending", "confirmed", "cancelled"] },
+            paid: { type: "boolean" },
+          },
+        },
+        AppointmentListResponse: {
+          type: "object",
+          required: ["ok", "data"],
+          properties: {
+            ok: { type: "boolean", enum: [true] },
+            data: {
+              type: "object",
+              required: ["appointments", "nextCursor"],
+              properties: {
+                appointments: {
+                  type: "array",
+                  items: { $ref: "#/components/schemas/Appointment" },
+                },
+                nextCursor: { type: "string", nullable: true },
+              },
+            },
+          },
+        },
         ErrorResponse: {
           type: "object",
           required: ["error"],

package/templates/apps/api/src/routes/auth/__tests__/auth-user.functional.test.ts

@@ -176,6 +176,54 @@ describe("user routes — functional via dual-mode preHandler", () => {
     });
   });
 
+  describe("reserved user-data keys — #6034 § D12", () => {
+    it.each([
+      ["GET", "commerce.subscription_dunning"],
+      ["PUT", "commerce.subscription_dunning"],
+      ["DELETE", "commerce.subscription_dunning"],
+      ["GET", "Commerce.Subscription_Dunning"],
+      ["GET", "system.anything"],
+    ])("%s /api/user/data/%s → 403 before any Prisma call", async (method, key) => {
+      withBearer("user_bear");
+
+      app = await buildApp();
+      const res = await app.inject({
+        method: method as "GET" | "PUT" | "DELETE",
+        url: `/v1/user/data/${key}`,
+        headers: { authorization: "Bearer tok_live_xx" },
+        payload: method === "PUT" ? { status: "active" } : undefined,
+      });
+
+      expect(res.statusCode).toBe(403);
+      expect(JSON.parse(res.body)).toEqual({
+        success: false,
+        error: "reserved-key",
+      });
+      expect(prisma.userData.findUnique).not.toHaveBeenCalled();
+      expect(prisma.userData.upsert).not.toHaveBeenCalled();
+      expect(prisma.userData.deleteMany).not.toHaveBeenCalled();
+    });
+
+    it("the unreserved `prefs` path is unchanged", async () => {
+      withBearer("user_bear");
+      (prisma.userData.findUnique as jest.Mock).mockResolvedValue({
+        value: { theme: "dark" },
+      });
+
+      app = await buildApp();
+      const res = await app.inject({
+        method: "GET",
+        url: "/v1/user/data/prefs",
+        headers: { authorization: "Bearer tok_live_xx" },
+      });
+
+      expect(res.statusCode).toBe(200);
+      expect(prisma.userData.findUnique).toHaveBeenCalledWith({
+        where: { userId_key: { userId: "user_bear", key: "prefs" } },
+      });
+    });
+  });
+
   describe("unauthenticated", () => {
     it.each([
       ["GET", "/v1/user/profile", undefined],