create-ailk 0.1.0

package/templates/apps/api/src/openapi/__tests__/openapi.test.ts

@@ -0,0 +1,129 @@
+/**
+ * @file openapi.test.ts
+ * GET /api/openapi.json — OpenAPI 3.x spec describing the public content API.
+ */
+import { openapiRoutes } from "../index";
+
+describe("GET /api/openapi.json", () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #506/#507: pre-existing test-hygiene violation
+  let app: any;
+
+  beforeEach(async () => {
+    app = require("fastify")();
+    await app.register(openapiRoutes);
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it("returns 200 with a valid OpenAPI 3.x document", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/openapi.json",
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.headers["content-type"]).toMatch(/application\/json/);
+
+    const spec = JSON.parse(res.body);
+    expect(spec.openapi).toBe("3.1.0");
+    expect(spec.info).toMatchObject({
+      title: "AI Launch Kit — Public Content API",
+      version: "1.0.0",
+    });
+    expect(spec.info.version).toBe("1.0.0");
+    expect(typeof spec.paths).toBe("object");
+  });
+
+  it("documents all three content endpoints", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/openapi.json",
+    });
+
+    const spec = JSON.parse(res.body);
+    expect(spec.paths["/v1/content/types"].get.operationId).toBe(
+      "listContentTypes",
+    );
+    expect(spec.paths["/v1/content/{type}"].get.operationId).toBe(
+      "listPagesByType",
+    );
+    expect(spec.paths["/v1/content/{type}/{slug}"].get.operationId).toBe(
+      "getPageBySlug",
+    );
+  });
+
+  it("documents the checkout sessions endpoint with operationId createCheckoutSession", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/openapi.json",
+    });
+
+    const spec = JSON.parse(res.body);
+    expect(spec.paths["/v1/checkout/sessions"].post.operationId).toBe(
+      "createCheckoutSession",
+    );
+  });
+
+  it("documents 201, 400, 404, 500, 502 responses for the checkout endpoint", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/openapi.json",
+    });
+
+    const spec = JSON.parse(res.body);
+    const responses = spec.paths["/v1/checkout/sessions"].post.responses;
+    expect(responses["201"].description).toBe("Checkout session created");
+    expect(responses["400"].description).toBe(
+      "Validation error — invalid request body",
+    );
+    expect(responses["404"].description).toBe(
+      "Unknown product code — no active Stripe price for the given productCode",
+    );
+    expect(responses["500"].description).toBe(
+      "Live-mode forbidden — STRIPE_SECRET_KEY is a live key",
+    );
+    expect(responses["502"].description).toBe(
+      "Checkout unavailable — Stripe returned an unexpected error",
+    );
+  });
+
+  it("declares query and path parameters for content endpoints", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/openapi.json",
+    });
+
+    const spec = JSON.parse(res.body);
+    const listOp = spec.paths["/v1/content/{type}"].get;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #506/#507: pre-existing test-hygiene violation
+    const paramNames = (listOp.parameters || []).map((p: any) => p.name);
+    expect(paramNames).toEqual(
+      expect.arrayContaining(["type", "page", "pageSize"]),
+    );
+
+    const getOp = spec.paths["/v1/content/{type}/{slug}"].get;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #506/#507: pre-existing test-hygiene violation
+    const getParams = (getOp.parameters || []).map((p: any) => p.name);
+    expect(getParams).toEqual(expect.arrayContaining(["type", "slug"]));
+  });
+
+  it("declares 200, 400, 404 responses where appropriate", async () => {
+    const res = await app.inject({
+      method: "GET",
+      url: "/v1/openapi.json",
+    });
+
+    const spec = JSON.parse(res.body);
+    expect(
+      spec.paths["/v1/content/{type}/{slug}"].get.responses["200"].description,
+    ).toBe("OK");
+    expect(
+      spec.paths["/v1/content/{type}/{slug}"].get.responses["404"],
+    ).toMatchObject({ $ref: "#/components/responses/NotFound" });
+    expect(
+      spec.paths["/v1/content/{type}"].get.responses["400"],
+    ).toMatchObject({ $ref: "#/components/responses/BadRequest" });
+  });
+});

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

@@ -0,0 +1,12 @@
+/**
+ * Mounts the OpenAPI spec at GET /v1/openapi.json.
+ */
+import type { FastifyPluginAsync } from "fastify";
+
+import { buildOpenApiSpec } from "./spec.js";
+
+export const openapiRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.get("/v1/openapi.json", async (_request, reply) => {
+    return reply.send(buildOpenApiSpec());
+  });
+};

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

@@ -0,0 +1,408 @@
+/**
+ * OpenAPI 3.1 spec for the public content API.
+ *
+ * Hand-authored rather than generated from Zod schemas. Three endpoints
+ * with stable shapes is small enough that a literal spec is faster to read
+ * and review than a generated one.
+ *
+ * When this surface grows beyond a handful of routes, swap in a generator
+ * and delete this file; the route handlers don't depend on the spec shape.
+ */
+import { SCHEMA_ORG_TYPES } from "@working-theory/content-adapters";
+
+export const API_VERSION = "1.0.0";
+
+export function buildOpenApiSpec() {
+  const typeEnum = [...SCHEMA_ORG_TYPES];
+
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: "AI Launch Kit — Public Content API",
+      version: API_VERSION,
+      description:
+        "Read-only HTTP API exposing AILK content as schema.org JSON-LD. " +
+        "Designed for agent consumption (AX) — every response carries " +
+        "`@context` and `@type` at the document root.",
+      license: { name: "MIT" },
+    },
+    servers: [
+      { url: "http://localhost:3002", description: "Local development" },
+      { url: "https://api.ailaunchkit.ai", description: "Production" },
+    ],
+    paths: {
+      "/v1/checkout/sessions": {
+        post: {
+          operationId: "createCheckoutSession",
+          summary: "Create a Stripe hosted-page checkout session",
+          description:
+            "Resolves a productCode to a Stripe price via lookup_key and creates a " +
+            "hosted-page checkout session. Returns the session ID and redirect URL. " +
+            "Sandbox-only: live Stripe keys are rejected at runtime.",
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: {
+                  $ref: "#/components/schemas/CheckoutSessionRequest",
+                },
+              },
+            },
+          },
+          responses: {
+            "201": {
+              description: "Checkout session created",
+              content: {
+                "application/json": {
+                  schema: {
+                    $ref: "#/components/schemas/CheckoutSessionResponse",
+                  },
+                },
+              },
+            },
+            "400": {
+              description: "Validation error — invalid request body",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ValidationErrorResponse" },
+                },
+              },
+            },
+            "404": {
+              description:
+                "Unknown product code — no active Stripe price for the given productCode",
+              content: {
+                "application/json": {
+                  schema: {
+                    $ref: "#/components/schemas/UnknownProductCodeResponse",
+                  },
+                },
+              },
+            },
+            "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",
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      "/v1/content/types": {
+        get: {
+          operationId: "listContentTypes",
+          summary: "List supported page types",
+          description:
+            "Returns the canonical schema.org page types this content API can serve.",
+          responses: {
+            "200": {
+              description: "OK",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/TypesResponse" },
+                },
+              },
+            },
+            "429": { $ref: "#/components/responses/RateLimited" },
+          },
+        },
+      },
+      "/v1/content/{type}": {
+        get: {
+          operationId: "listPagesByType",
+          summary: "List pages of a given type",
+          description:
+            "Paginated list of pages for the given schema.org type. Defaults: page=1, pageSize=20. pageSize is capped at 100. Optional locale query parameter selects the locale to list from; invalid or unknown locales silently fall back to the project's default locale (AC-i18n-07).",
+          parameters: [
+            {
+              name: "type",
+              in: "path",
+              required: true,
+              schema: { type: "string", enum: typeEnum },
+            },
+            {
+              name: "page",
+              in: "query",
+              required: false,
+              schema: { type: "integer", minimum: 1, default: 1 },
+            },
+            {
+              name: "pageSize",
+              in: "query",
+              required: false,
+              schema: {
+                type: "integer",
+                minimum: 1,
+                maximum: 100,
+                default: 20,
+              },
+            },
+            {
+              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/ListResponse" },
+                },
+              },
+            },
+            "400": { $ref: "#/components/responses/BadRequest" },
+            "429": { $ref: "#/components/responses/RateLimited" },
+            "500": { $ref: "#/components/responses/ServerError" },
+          },
+        },
+      },
+      "/v1/content/{type}/{slug}": {
+        get: {
+          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).",
+          parameters: [
+            {
+              name: "type",
+              in: "path",
+              required: true,
+              schema: { type: "string", enum: typeEnum },
+            },
+            {
+              name: "slug",
+              in: "path",
+              required: true,
+              schema: { type: "string", minLength: 1 },
+            },
+            {
+              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/PageResponse" },
+                },
+              },
+            },
+            "400": { $ref: "#/components/responses/BadRequest" },
+            "404": { $ref: "#/components/responses/NotFound" },
+            "429": { $ref: "#/components/responses/RateLimited" },
+            "500": { $ref: "#/components/responses/ServerError" },
+          },
+        },
+      },
+    },
+    components: {
+      schemas: {
+        CheckoutSessionRequest: {
+          type: "object",
+          required: ["productCode", "successUrl", "cancelUrl"],
+          properties: {
+            productCode: {
+              type: "string",
+              pattern: "^[A-Za-z0-9._-]{1,200}$",
+              description:
+                "Consumer-defined product code; resolved to a Stripe price via lookup_key",
+            },
+            successUrl: {
+              type: "string",
+              description:
+                "Redirect URL on successful payment (must be a valid http:// or https:// URL)",
+            },
+            cancelUrl: {
+              type: "string",
+              description:
+                "Redirect URL when customer cancels checkout (must be a valid http:// or https:// URL)",
+            },
+            quantity: {
+              type: "integer",
+              minimum: 1,
+              maximum: 999,
+              default: 1,
+              description: "Line-item quantity; defaults to 1",
+            },
+          },
+        },
+        CheckoutSessionResponse: {
+          type: "object",
+          required: ["sessionId", "url"],
+          properties: {
+            sessionId: {
+              type: "string",
+              description: "Stripe Checkout Session ID (cs_test_… / cs_…)",
+            },
+            url: {
+              type: "string",
+              description: "Hosted Checkout page URL",
+            },
+          },
+        },
+        ValidationErrorResponse: {
+          type: "object",
+          required: ["error"],
+          properties: {
+            error: { type: "string", enum: ["validation-error"] },
+            details: {
+              type: "array",
+              items: { type: "object", additionalProperties: true },
+              description: "Zod validation issue list",
+            },
+          },
+        },
+        UnknownProductCodeResponse: {
+          type: "object",
+          required: ["error"],
+          properties: {
+            error: { type: "string", enum: ["unknown-product-code"] },
+          },
+        },
+        LiveModeForbiddenResponse: {
+          type: "object",
+          required: ["error"],
+          properties: {
+            error: { type: "string", enum: ["live-mode-forbidden"] },
+          },
+        },
+        CheckoutUnavailableResponse: {
+          type: "object",
+          required: ["error"],
+          properties: {
+            error: { type: "string", enum: ["checkout-unavailable"] },
+          },
+        },
+        ContentPage: {
+          type: "object",
+          required: ["type", "slug", "title", "description"],
+          properties: {
+            type: { type: "string", enum: typeEnum },
+            slug: { type: "string" },
+            title: { type: "string" },
+            description: { type: "string" },
+            publishedAt: { type: "string" },
+            updatedAt: { type: "string" },
+            image: { type: "string" },
+            schema: { type: "object", additionalProperties: true },
+          },
+        },
+        Pagination: {
+          type: "object",
+          required: ["page", "pageSize", "totalItems", "totalPages"],
+          properties: {
+            page: { type: "integer", minimum: 1 },
+            pageSize: { type: "integer", minimum: 1 },
+            totalItems: { type: "integer", minimum: 0 },
+            totalPages: { type: "integer", minimum: 1 },
+          },
+        },
+        TypesResponse: {
+          type: "object",
+          required: ["@context", "@type", "types"],
+          properties: {
+            "@context": { type: "string", enum: ["https://schema.org"] },
+            "@type": { type: "string", enum: ["ItemList"] },
+            types: {
+              type: "array",
+              items: { type: "string", enum: typeEnum },
+            },
+          },
+        },
+        ListResponse: {
+          type: "object",
+          required: ["@context", "@type", "type", "items", "pagination"],
+          properties: {
+            "@context": { type: "string", enum: ["https://schema.org"] },
+            "@type": { type: "string", enum: ["ItemList"] },
+            type: { type: "string", enum: typeEnum },
+            items: {
+              type: "array",
+              items: { $ref: "#/components/schemas/ContentPage" },
+            },
+            pagination: { $ref: "#/components/schemas/Pagination" },
+          },
+        },
+        PageResponse: {
+          type: "object",
+          required: ["@context", "@type", "page"],
+          properties: {
+            "@context": { type: "string", enum: ["https://schema.org"] },
+            "@type": { type: "string" },
+            page: { $ref: "#/components/schemas/ContentPage" },
+          },
+          additionalProperties: true,
+        },
+        ErrorResponse: {
+          type: "object",
+          required: ["error"],
+          properties: {
+            error: { type: "string" },
+            details: {},
+          },
+        },
+      },
+      responses: {
+        BadRequest: {
+          description: "Invalid request parameters",
+          content: {
+            "application/json": {
+              schema: { $ref: "#/components/schemas/ErrorResponse" },
+            },
+          },
+        },
+        NotFound: {
+          description: "Resource not found",
+          content: {
+            "application/json": {
+              schema: { $ref: "#/components/schemas/ErrorResponse" },
+            },
+          },
+        },
+        RateLimited: {
+          description: "Too many requests — rate limit exceeded",
+          content: {
+            "application/json": {
+              schema: { $ref: "#/components/schemas/ErrorResponse" },
+            },
+          },
+        },
+        ServerError: {
+          description: "Internal server error",
+          content: {
+            "application/json": {
+              schema: { $ref: "#/components/schemas/ErrorResponse" },
+            },
+          },
+        },
+      },
+    },
+  };
+}