@questpie/openapi 2.0.0

package/README.md

@@ -0,0 +1,67 @@
+# @questpie/openapi
+
+Auto-generate an OpenAPI 3.1 spec from a QUESTPIE CMS instance and serve interactive API docs via Scalar UI.
+
+## Installation
+
+```bash
+bun add @questpie/openapi
+```
+
+## Usage
+
+Wrap your fetch handler with `withOpenApi` to add `/openapi.json` and `/docs` routes:
+
+```ts
+import { createFetchHandler } from "questpie";
+import { withOpenApi } from "@questpie/openapi";
+import { cms, appRpc } from "./cms";
+
+const handler = withOpenApi(
+  createFetchHandler(cms, { basePath: "/api/cms", rpc: appRpc }),
+  {
+    cms,
+    rpc: appRpc,
+    basePath: "/api/cms",
+    info: { title: "My API", version: "1.0.0" },
+    scalar: { theme: "purple" },
+  },
+);
+
+// GET /api/cms/openapi.json → OpenAPI spec
+// GET /api/cms/docs         → Scalar UI
+// Everything else           → CMS routes
+```
+
+## What Gets Documented
+
+| Category        | Endpoints                                                                               |
+| --------------- | --------------------------------------------------------------------------------------- |
+| **Collections** | List, create, findOne, update, delete, count, deleteMany, restore, upload, schema, meta |
+| **Globals**     | Get, update, schema                                                                     |
+| **RPC**         | All procedures from the RPC router tree, with input/output from Zod schemas             |
+| **Auth**        | Better Auth endpoints (sign-in, sign-up, session, sign-out)                             |
+| **Search**      | Full-text search and reindex                                                            |
+
+RPC functions with an explicit `outputSchema` get full request/response documentation. Functions without it fall back to `{ type: "object" }`.
+
+## Standalone Spec Generation
+
+Generate the spec without mounting routes:
+
+```ts
+import { generateOpenApiSpec } from "@questpie/openapi";
+
+const spec = generateOpenApiSpec(cms, appRpc, {
+  basePath: "/api/cms",
+  info: { title: "My API", version: "1.0.0" },
+});
+```
+
+## Documentation
+
+Full documentation: [https://questpie.com/docs/client/openapi](https://questpie.com/docs/client/openapi)
+
+## License
+
+MIT

package/dist/server.d.mts

@@ -0,0 +1,142 @@
+import { Questpie, RpcRouterTree } from "questpie";
+
+//#region src/types.d.ts
+
+/**
+ * Configuration for OpenAPI spec generation.
+ */
+interface OpenApiConfig {
+  /** OpenAPI info object */
+  info?: {
+    title?: string;
+    version?: string;
+    description?: string;
+  };
+  /** Server definitions */
+  servers?: Array<{
+    url: string;
+    description?: string;
+  }>;
+  /** Base path for CMS routes (must match your adapter basePath) */
+  basePath?: string;
+  /** Exclude specific collections or globals from the spec */
+  exclude?: {
+    collections?: string[];
+    globals?: string[];
+  };
+  /** Include auth endpoints in the spec */
+  auth?: boolean;
+  /** Include search endpoints in the spec */
+  search?: boolean;
+}
+/**
+ * Scalar UI configuration options.
+ */
+interface ScalarConfig {
+  /** Theme for Scalar UI */
+  theme?: string;
+  /** Page title override */
+  title?: string;
+  /** Custom CSS */
+  customCss?: string;
+  /** Hide the "Download OpenAPI Spec" button */
+  hideDownloadButton?: boolean;
+  /** Default HTTP client for code samples */
+  defaultHttpClient?: {
+    targetKey: string;
+    clientKey: string;
+  };
+}
+/**
+ * Configuration for withOpenApi() handler wrapper.
+ */
+interface WithOpenApiConfig extends OpenApiConfig {
+  /** CMS instance */
+  cms: Questpie<any>;
+  /** RPC router tree (same one passed to createFetchHandler) */
+  rpc?: RpcRouterTree<any>;
+  /** Scalar UI options */
+  scalar?: ScalarConfig;
+  /** Path for the JSON spec (relative to basePath, default: "openapi.json") */
+  specPath?: string;
+  /** Path for the Scalar UI docs (relative to basePath, default: "docs") */
+  docsPath?: string;
+}
+/**
+ * OpenAPI 3.1 spec (simplified type — full spec is a plain object).
+ */
+type OpenApiSpec = {
+  openapi: "3.1.0";
+  info: {
+    title: string;
+    version: string;
+    description?: string;
+  };
+  servers?: Array<{
+    url: string;
+    description?: string;
+  }>;
+  paths: Record<string, Record<string, PathOperation>>;
+  components: {
+    schemas: Record<string, unknown>;
+    securitySchemes?: Record<string, unknown>;
+  };
+  tags?: Array<{
+    name: string;
+    description?: string;
+  }>;
+  security?: Array<Record<string, string[]>>;
+};
+interface PathOperation {
+  operationId?: string;
+  summary?: string;
+  description?: string;
+  tags?: string[];
+  parameters?: unknown[];
+  requestBody?: unknown;
+  responses: Record<string, unknown>;
+  security?: Array<Record<string, string[]>>;
+}
+//#endregion
+//#region src/server.d.ts
+/**
+ * Generate a complete OpenAPI 3.1 spec from a CMS instance and optional RPC router.
+ */
+declare function generateOpenApiSpec(cms: Questpie<any>, rpc?: RpcRouterTree<any>, config?: OpenApiConfig): OpenApiSpec;
+/**
+ * Create request handlers for serving the OpenAPI spec and Scalar UI.
+ */
+declare function createOpenApiHandlers(spec: OpenApiSpec, options?: {
+  scalar?: ScalarConfig;
+}): {
+  /** Returns the OpenAPI spec as JSON */
+  specHandler: () => Response;
+  /** Returns the Scalar UI HTML page */
+  scalarHandler: () => Response;
+};
+/**
+ * Wrap a CMS fetch handler to add OpenAPI spec and Scalar UI routes.
+ *
+ * Intercepts requests to `{basePath}/{specPath}` and `{basePath}/{docsPath}`
+ * before they reach the CMS handler. Everything else passes through unchanged.
+ *
+ * @example
+ * ```ts
+ * const handler = withOpenApi(
+ *   createFetchHandler(cms, { basePath: '/api/cms', rpc: appRpc }),
+ *   {
+ *     cms,
+ *     rpc: appRpc,
+ *     basePath: '/api/cms',
+ *     info: { title: 'My API', version: '1.0.0' },
+ *     scalar: { theme: 'purple' },
+ *   }
+ * )
+ * // GET /api/cms/openapi.json → spec JSON
+ * // GET /api/cms/docs          → Scalar UI
+ * // Everything else            → CMS handler
+ * ```
+ */
+declare function withOpenApi(handler: (request: Request, context?: any) => Promise<Response | null> | Response | null, config: WithOpenApiConfig): (request: Request, context?: any) => Promise<Response | null> | Response | null;
+//#endregion
+export { type OpenApiConfig, type OpenApiSpec, type ScalarConfig, type WithOpenApiConfig, createOpenApiHandlers, generateOpenApiSpec, withOpenApi };

package/dist/server.mjs

@@ -0,0 +1,969 @@
+import { z } from "zod";
+
+//#region src/generator/schemas.ts
+/**
+* Shared schema helpers for OpenAPI spec generation.
+* Provides $ref utilities, common schemas (pagination, errors), and Zod conversion helpers.
+*/
+/**
+* Create a $ref pointer to a component schema.
+*/
+function ref(name) {
+	return { $ref: `#/components/schemas/${name}` };
+}
+/**
+* Standard error response schema.
+*/
+function errorResponseSchema() {
+	return {
+		type: "object",
+		properties: { error: {
+			type: "object",
+			properties: {
+				code: { type: "string" },
+				message: { type: "string" },
+				details: {}
+			},
+			required: ["code", "message"]
+		} },
+		required: ["error"]
+	};
+}
+/**
+* Paginated response wrapper for a given item schema.
+*/
+function paginatedResponseSchema(itemRef) {
+	return {
+		type: "object",
+		properties: {
+			docs: {
+				type: "array",
+				items: itemRef
+			},
+			totalDocs: { type: "integer" },
+			limit: { type: "integer" },
+			page: { type: "integer" },
+			totalPages: { type: "integer" },
+			hasNextPage: { type: "boolean" },
+			hasPrevPage: { type: "boolean" },
+			nextPage: { type: ["integer", "null"] },
+			prevPage: { type: ["integer", "null"] }
+		},
+		required: [
+			"docs",
+			"totalDocs",
+			"limit",
+			"page",
+			"totalPages"
+		]
+	};
+}
+/**
+* Common query parameters for collection list endpoints.
+*/
+function listQueryParameters() {
+	return [
+		{
+			name: "limit",
+			in: "query",
+			schema: {
+				type: "integer",
+				default: 10
+			},
+			description: "Number of records to return"
+		},
+		{
+			name: "page",
+			in: "query",
+			schema: {
+				type: "integer",
+				default: 1
+			},
+			description: "Page number"
+		},
+		{
+			name: "offset",
+			in: "query",
+			schema: { type: "integer" },
+			description: "Number of records to skip"
+		},
+		{
+			name: "where",
+			in: "query",
+			schema: { type: "string" },
+			description: "Filter conditions (JSON encoded)"
+		},
+		{
+			name: "orderBy",
+			in: "query",
+			schema: { type: "string" },
+			description: "Sort configuration (JSON encoded)"
+		},
+		{
+			name: "locale",
+			in: "query",
+			schema: { type: "string" },
+			description: "Content locale"
+		}
+	];
+}
+/**
+* Common query parameters for single-record endpoints.
+*/
+function singleQueryParameters() {
+	return [{
+		name: "locale",
+		in: "query",
+		schema: { type: "string" },
+		description: "Content locale"
+	}];
+}
+/**
+* Standard JSON responses helper.
+*/
+function jsonResponse(schema, description = "Successful response") {
+	return {
+		"200": {
+			description,
+			content: { "application/json": { schema } }
+		},
+		"400": {
+			description: "Bad request",
+			content: { "application/json": { schema: ref("ErrorResponse") } }
+		},
+		"401": {
+			description: "Unauthorized",
+			content: { "application/json": { schema: ref("ErrorResponse") } }
+		},
+		"404": {
+			description: "Not found",
+			content: { "application/json": { schema: ref("ErrorResponse") } }
+		}
+	};
+}
+/**
+* JSON request body helper.
+*/
+function jsonRequestBody(schema, description) {
+	return {
+		description,
+		required: true,
+		content: { "application/json": { schema } }
+	};
+}
+/**
+* Safely convert a Zod schema to JSON Schema.
+* Falls back to a permissive object schema on failure.
+*/
+function zodToJsonSchema(schema) {
+	try {
+		if (schema && typeof schema === "object" && "_def" in schema) return z.toJSONSchema(schema);
+	} catch {}
+	return {
+		type: "object",
+		description: "Schema could not be generated"
+	};
+}
+/**
+* Build the base component schemas shared across all endpoints.
+*/
+function baseComponentSchemas() {
+	return {
+		ErrorResponse: errorResponseSchema(),
+		SuccessResponse: {
+			type: "object",
+			properties: { success: { type: "boolean" } },
+			required: ["success"]
+		},
+		CountResponse: {
+			type: "object",
+			properties: { count: { type: "integer" } },
+			required: ["count"]
+		},
+		DeleteManyResponse: {
+			type: "object",
+			properties: {
+				success: { type: "boolean" },
+				count: { type: "integer" }
+			},
+			required: ["success"]
+		}
+	};
+}
+
+//#endregion
+//#region src/generator/auth.ts
+/**
+* Generate OpenAPI paths for Better Auth endpoints.
+*/
+function generateAuthPaths(config) {
+	if (config.auth === false) return {
+		paths: {},
+		tags: []
+	};
+	const basePath = config.basePath ?? "/cms";
+	const tag = "Auth";
+	const paths = {};
+	paths[`${basePath}/auth/sign-in/email`] = { post: {
+		operationId: "auth_signInEmail",
+		summary: "Sign in with email and password",
+		tags: [tag],
+		requestBody: jsonRequestBody({
+			type: "object",
+			properties: {
+				email: {
+					type: "string",
+					format: "email"
+				},
+				password: { type: "string" }
+			},
+			required: ["email", "password"]
+		}),
+		responses: jsonResponse({
+			type: "object",
+			properties: {
+				user: { type: "object" },
+				session: { type: "object" }
+			}
+		}, "Authentication successful")
+	} };
+	paths[`${basePath}/auth/sign-up/email`] = { post: {
+		operationId: "auth_signUpEmail",
+		summary: "Sign up with email and password",
+		tags: [tag],
+		requestBody: jsonRequestBody({
+			type: "object",
+			properties: {
+				email: {
+					type: "string",
+					format: "email"
+				},
+				password: { type: "string" },
+				name: { type: "string" }
+			},
+			required: [
+				"email",
+				"password",
+				"name"
+			]
+		}),
+		responses: jsonResponse({
+			type: "object",
+			properties: {
+				user: { type: "object" },
+				session: { type: "object" }
+			}
+		}, "Registration successful")
+	} };
+	paths[`${basePath}/auth/get-session`] = { get: {
+		operationId: "auth_getSession",
+		summary: "Get current session",
+		tags: [tag],
+		responses: jsonResponse({
+			type: "object",
+			properties: {
+				user: { type: "object" },
+				session: { type: "object" }
+			}
+		}, "Current session")
+	} };
+	paths[`${basePath}/auth/sign-out`] = { post: {
+		operationId: "auth_signOut",
+		summary: "Sign out",
+		tags: [tag],
+		responses: jsonResponse({
+			type: "object",
+			properties: { success: { type: "boolean" } }
+		}, "Signed out")
+	} };
+	return {
+		paths,
+		tags: [{
+			name: tag,
+			description: "Authentication endpoints (Better Auth)"
+		}]
+	};
+}
+
+//#endregion
+//#region src/generator/collections.ts
+/**
+* Generate OpenAPI paths and component schemas for all collections.
+*/
+function generateCollectionPaths(cms, config) {
+	const collections = cms.getCollections();
+	const basePath = config.basePath ?? "/cms";
+	const excluded = new Set(config.exclude?.collections ?? []);
+	const paths = {};
+	const schemas = {};
+	const tags = [];
+	for (const [name, collection] of Object.entries(collections)) {
+		if (excluded.has(name)) continue;
+		const state = collection.state;
+		if (!state) continue;
+		const tag = `Collections: ${name}`;
+		tags.push({
+			name: tag,
+			description: `CRUD operations for ${name}`
+		});
+		const pascalName = toPascalCase$1(name);
+		const documentSchemaName = `${pascalName}Document`;
+		const insertSchemaName = `${pascalName}Insert`;
+		const updateSchemaName = `${pascalName}Update`;
+		const fieldDefinitionSchema = buildSchemaFromFieldDefinitions(state.fieldDefinitions);
+		if (state.validation?.insertSchema) try {
+			schemas[insertSchemaName] = z.toJSONSchema(state.validation.insertSchema, { unrepresentable: "any" });
+		} catch {
+			schemas[insertSchemaName] = {
+				type: "object",
+				description: `Insert schema for ${name}`
+			};
+		}
+		else if (fieldDefinitionSchema != null) schemas[insertSchemaName] = fieldDefinitionSchema.insert;
+		else schemas[insertSchemaName] = {
+			type: "object",
+			description: `Insert schema for ${name}`
+		};
+		if (state.validation?.updateSchema) try {
+			schemas[updateSchemaName] = z.toJSONSchema(state.validation.updateSchema, { unrepresentable: "any" });
+		} catch {
+			schemas[updateSchemaName] = {
+				type: "object",
+				description: `Update schema for ${name}`
+			};
+		}
+		else if (fieldDefinitionSchema != null) schemas[updateSchemaName] = fieldDefinitionSchema.update;
+		else schemas[updateSchemaName] = {
+			type: "object",
+			description: `Update schema for ${name}`
+		};
+		schemas[documentSchemaName] = buildDocumentSchema(name, state, insertSchemaName);
+		const prefix = `${basePath}/${name}`;
+		paths[prefix] = {
+			get: {
+				operationId: `${name}_find`,
+				summary: `List ${name}`,
+				tags: [tag],
+				parameters: listQueryParameters(),
+				responses: jsonResponse(paginatedResponseSchema(ref(documentSchemaName)), `Paginated list of ${name}`)
+			},
+			post: {
+				operationId: `${name}_create`,
+				summary: `Create ${name}`,
+				tags: [tag],
+				requestBody: jsonRequestBody(ref(insertSchemaName)),
+				responses: jsonResponse(ref(documentSchemaName), `Created ${name} record`)
+			}
+		};
+		paths[`${prefix}/count`] = { get: {
+			operationId: `${name}_count`,
+			summary: `Count ${name}`,
+			tags: [tag],
+			parameters: [{
+				name: "where",
+				in: "query",
+				schema: { type: "string" },
+				description: "Filter conditions (JSON encoded)"
+			}],
+			responses: jsonResponse(ref("CountResponse"), `Count of ${name}`)
+		} };
+		paths[`${prefix}/delete-many`] = { post: {
+			operationId: `${name}_deleteMany`,
+			summary: `Delete many ${name}`,
+			tags: [tag],
+			requestBody: jsonRequestBody({
+				type: "object",
+				properties: { where: {
+					type: "object",
+					description: "Filter conditions for records to delete"
+				} }
+			}),
+			responses: jsonResponse(ref("DeleteManyResponse"), `Delete multiple ${name} records`)
+		} };
+		if (state.upload) paths[`${prefix}/upload`] = { post: {
+			operationId: `${name}_upload`,
+			summary: `Upload file to ${name}`,
+			tags: [tag],
+			requestBody: {
+				required: true,
+				content: { "multipart/form-data": { schema: {
+					type: "object",
+					properties: { file: {
+						type: "string",
+						format: "binary"
+					} },
+					required: ["file"]
+				} } }
+			},
+			responses: jsonResponse(ref(documentSchemaName), `Uploaded file record`)
+		} };
+		paths[`${prefix}/schema`] = { get: {
+			operationId: `${name}_schema`,
+			summary: `Get ${name} introspection schema`,
+			tags: [tag],
+			responses: jsonResponse({
+				type: "object",
+				description: "Introspected collection schema"
+			}, `Introspection schema for ${name}`)
+		} };
+		paths[`${prefix}/meta`] = { get: {
+			operationId: `${name}_meta`,
+			summary: `Get ${name} metadata`,
+			tags: [tag],
+			responses: jsonResponse({
+				type: "object",
+				description: "Collection metadata"
+			}, `Metadata for ${name}`)
+		} };
+		const idParam = {
+			name: "id",
+			in: "path",
+			required: true,
+			schema: { type: "string" },
+			description: "Record ID"
+		};
+		paths[`${prefix}/{id}`] = {
+			get: {
+				operationId: `${name}_findOne`,
+				summary: `Get ${name} by ID`,
+				tags: [tag],
+				parameters: [idParam, ...singleQueryParameters()],
+				responses: jsonResponse(ref(documentSchemaName), `Single ${name} record`)
+			},
+			patch: {
+				operationId: `${name}_update`,
+				summary: `Update ${name}`,
+				tags: [tag],
+				parameters: [idParam],
+				requestBody: jsonRequestBody(ref(updateSchemaName)),
+				responses: jsonResponse(ref(documentSchemaName), `Updated ${name} record`)
+			},
+			delete: {
+				operationId: `${name}_delete`,
+				summary: `Delete ${name}`,
+				tags: [tag],
+				parameters: [idParam],
+				responses: jsonResponse(ref("SuccessResponse"), `Deleted ${name} record`)
+			}
+		};
+		if (state.options?.softDelete) paths[`${prefix}/{id}/restore`] = { post: {
+			operationId: `${name}_restore`,
+			summary: `Restore deleted ${name}`,
+			tags: [tag],
+			parameters: [idParam],
+			responses: jsonResponse(ref(documentSchemaName), `Restored ${name} record`)
+		} };
+	}
+	return {
+		paths,
+		schemas,
+		tags
+	};
+}
+/**
+* Build a document response schema that extends the insert schema with
+* standard fields (id, timestamps).
+*/
+function buildDocumentSchema(name, state, insertSchemaName) {
+	const properties = { id: { type: "string" } };
+	if (state.options?.timestamps !== false) {
+		properties.createdAt = {
+			type: "string",
+			format: "date-time"
+		};
+		properties.updatedAt = {
+			type: "string",
+			format: "date-time"
+		};
+	}
+	if (state.options?.softDelete) properties.deletedAt = {
+		type: ["string", "null"],
+		format: "date-time"
+	};
+	return {
+		allOf: [{
+			type: "object",
+			properties,
+			required: ["id"]
+		}, ref(insertSchemaName)],
+		description: `${name} document`
+	};
+}
+function toPascalCase$1(str) {
+	return str.replace(/[-_](.)/g, (_, c) => c.toUpperCase()).replace(/^(.)/, (_, c) => c.toUpperCase());
+}
+function buildSchemaFromFieldDefinitions(fieldDefinitions) {
+	if (!fieldDefinitions || typeof fieldDefinitions !== "object") return null;
+	const shape = {};
+	for (const [fieldName, fieldDefinition] of Object.entries(fieldDefinitions)) {
+		const toZodSchema = fieldDefinition.toZodSchema;
+		if (typeof toZodSchema !== "function") continue;
+		try {
+			const schema = toZodSchema();
+			if (schema && typeof schema === "object" && "_def" in schema) shape[fieldName] = schema;
+		} catch {}
+	}
+	if (Object.keys(shape).length === 0) return null;
+	const insertSchema = z.object(shape);
+	const updateSchema = insertSchema.partial();
+	return {
+		insert: z.toJSONSchema(insertSchema, { unrepresentable: "any" }),
+		update: z.toJSONSchema(updateSchema, { unrepresentable: "any" })
+	};
+}
+
+//#endregion
+//#region src/generator/globals.ts
+/**
+* Generate OpenAPI paths and component schemas for all globals.
+*/
+function generateGlobalPaths(cms, config) {
+	const globals = cms.getGlobals();
+	const basePath = config.basePath ?? "/cms";
+	const excluded = new Set(config.exclude?.globals ?? []);
+	const paths = {};
+	const schemas = {};
+	const tags = [];
+	for (const [name, global] of Object.entries(globals)) {
+		if (excluded.has(name)) continue;
+		const state = global.state;
+		if (!state) continue;
+		const tag = `Globals: ${name}`;
+		tags.push({
+			name: tag,
+			description: `Operations for ${name} global`
+		});
+		const pascalName = toPascalCase(name);
+		const valueSchemaName = `${pascalName}Global`;
+		const updateSchemaName = `${pascalName}GlobalUpdate`;
+		const fieldDefinitionSchema = buildGlobalSchemaFromFieldDefinitions(state.fieldDefinitions);
+		if (state.validation?.updateSchema) try {
+			schemas[updateSchemaName] = z.toJSONSchema(state.validation.updateSchema, { unrepresentable: "any" });
+		} catch {
+			schemas[updateSchemaName] = {
+				type: "object",
+				description: `Update schema for ${name} global`
+			};
+		}
+		else if (fieldDefinitionSchema != null) schemas[updateSchemaName] = fieldDefinitionSchema;
+		else schemas[updateSchemaName] = {
+			type: "object",
+			description: `Update schema for ${name} global`
+		};
+		const properties = { id: { type: "string" } };
+		if (state.options?.timestamps !== false) {
+			properties.createdAt = {
+				type: "string",
+				format: "date-time"
+			};
+			properties.updatedAt = {
+				type: "string",
+				format: "date-time"
+			};
+		}
+		schemas[valueSchemaName] = {
+			allOf: [{
+				type: "object",
+				properties,
+				required: ["id"]
+			}, ref(updateSchemaName)],
+			description: `${name} global value`
+		};
+		const prefix = `${basePath}/globals/${name}`;
+		paths[prefix] = {
+			get: {
+				operationId: `global_${name}_get`,
+				summary: `Get ${name} global`,
+				tags: [tag],
+				parameters: [{
+					name: "locale",
+					in: "query",
+					schema: { type: "string" },
+					description: "Content locale"
+				}],
+				responses: jsonResponse(ref(valueSchemaName), `Current value of ${name} global`)
+			},
+			patch: {
+				operationId: `global_${name}_update`,
+				summary: `Update ${name} global`,
+				tags: [tag],
+				requestBody: jsonRequestBody(ref(updateSchemaName)),
+				responses: jsonResponse(ref(valueSchemaName), `Updated ${name} global`)
+			}
+		};
+		paths[`${prefix}/schema`] = { get: {
+			operationId: `global_${name}_schema`,
+			summary: `Get ${name} global introspection schema`,
+			tags: [tag],
+			responses: jsonResponse({
+				type: "object",
+				description: "Introspected global schema"
+			}, `Introspection schema for ${name} global`)
+		} };
+	}
+	return {
+		paths,
+		schemas,
+		tags
+	};
+}
+function toPascalCase(str) {
+	return str.replace(/[-_](.)/g, (_, c) => c.toUpperCase()).replace(/^(.)/, (_, c) => c.toUpperCase());
+}
+function buildGlobalSchemaFromFieldDefinitions(fieldDefinitions) {
+	if (!fieldDefinitions || typeof fieldDefinitions !== "object") return null;
+	const shape = {};
+	for (const [fieldName, fieldDefinition] of Object.entries(fieldDefinitions)) {
+		const toZodSchema = fieldDefinition.toZodSchema;
+		if (typeof toZodSchema !== "function") continue;
+		try {
+			const schema = toZodSchema();
+			if (schema && typeof schema === "object" && "_def" in schema) shape[fieldName] = schema;
+		} catch {}
+	}
+	if (Object.keys(shape).length === 0) return null;
+	return z.toJSONSchema(z.object(shape).partial(), { unrepresentable: "any" });
+}
+
+//#endregion
+//#region src/generator/rpc.ts
+/**
+* Flatten an RPC router tree into a list of { path, definition }.
+*/
+function flattenRpcTree(tree, prefix = []) {
+	const entries = [];
+	for (const [key, value] of Object.entries(tree)) {
+		const segments = [...prefix, key];
+		if (value && typeof value === "object" && "handler" in value && typeof value.handler === "function") entries.push({
+			path: segments.join("/"),
+			segments,
+			definition: value
+		});
+		else if (value && typeof value === "object") entries.push(...flattenRpcTree(value, segments));
+	}
+	return entries;
+}
+/**
+* Generate OpenAPI paths for all RPC functions in the router tree.
+*/
+function generateRpcPaths(rpc, config) {
+	const paths = {};
+	const schemas = {};
+	const tags = [];
+	if (!rpc) return {
+		paths,
+		schemas,
+		tags
+	};
+	const basePath = config.basePath ?? "/cms";
+	const entries = flattenRpcTree(rpc);
+	const tagSet = /* @__PURE__ */ new Set();
+	for (const entry of entries) {
+		const def = entry.definition;
+		const isRaw = def.mode === "raw";
+		const topLevel = entry.segments[0] ?? "rpc";
+		if (!tagSet.has(topLevel)) {
+			tagSet.add(topLevel);
+			tags.push({
+				name: `RPC: ${topLevel}`,
+				description: `RPC functions under ${topLevel}`
+			});
+		}
+		const operationId = `rpc_${entry.segments.join("_")}`;
+		const routePath = `${basePath}/rpc/${entry.path}`;
+		const operation = {
+			operationId,
+			summary: entry.path,
+			tags: [`RPC: ${topLevel}`],
+			responses: {}
+		};
+		if (isRaw) {
+			operation.description = "Raw RPC function — accepts any request body and returns a raw response.";
+			operation.requestBody = { content: {
+				"application/json": { schema: {} },
+				"application/octet-stream": { schema: {
+					type: "string",
+					format: "binary"
+				} }
+			} };
+			operation.responses = {
+				"200": { description: "Raw response" },
+				"401": {
+					description: "Unauthorized",
+					content: { "application/json": { schema: { $ref: "#/components/schemas/ErrorResponse" } } }
+				}
+			};
+		} else {
+			let inputSchema = {};
+			let outputSchema = { type: "object" };
+			if (def.schema) {
+				const schemaName = `${operationId}_Input`;
+				schemas[schemaName] = zodToJsonSchema(def.schema);
+				inputSchema = { $ref: `#/components/schemas/${schemaName}` };
+			}
+			if (def.outputSchema) {
+				const schemaName = `${operationId}_Output`;
+				schemas[schemaName] = zodToJsonSchema(def.outputSchema);
+				outputSchema = { $ref: `#/components/schemas/${schemaName}` };
+			}
+			operation.requestBody = jsonRequestBody(inputSchema, "RPC function input");
+			operation.responses = jsonResponse(outputSchema, "RPC function output");
+		}
+		paths[routePath] = { post: operation };
+	}
+	return {
+		paths,
+		schemas,
+		tags
+	};
+}
+
+//#endregion
+//#region src/generator/search.ts
+/**
+* Generate OpenAPI paths for search endpoints.
+*/
+function generateSearchPaths(config) {
+	if (config.search === false) return {
+		paths: {},
+		tags: []
+	};
+	const basePath = config.basePath ?? "/cms";
+	const tag = "Search";
+	const paths = {};
+	paths[`${basePath}/search`] = { post: {
+		operationId: "search",
+		summary: "Search across collections",
+		tags: [tag],
+		requestBody: jsonRequestBody({
+			type: "object",
+			properties: {
+				query: {
+					type: "string",
+					description: "Search query"
+				},
+				collections: {
+					type: "array",
+					items: { type: "string" },
+					description: "Collections to search (omit for all)"
+				},
+				limit: {
+					type: "integer",
+					default: 10
+				},
+				offset: {
+					type: "integer",
+					default: 0
+				}
+			},
+			required: ["query"]
+		}),
+		responses: jsonResponse({
+			type: "object",
+			properties: {
+				results: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: {
+							collection: { type: "string" },
+							doc: { type: "object" },
+							_search: {
+								type: "object",
+								properties: {
+									score: { type: "number" },
+									highlights: { type: "object" },
+									indexedTitle: { type: "string" }
+								}
+							}
+						}
+					}
+				},
+				totalResults: { type: "integer" }
+			}
+		}, "Search results")
+	} };
+	paths[`${basePath}/search/reindex/{collection}`] = { post: {
+		operationId: "search_reindex",
+		summary: "Reindex a collection",
+		description: "Requires admin authentication.",
+		tags: [tag],
+		parameters: [{
+			name: "collection",
+			in: "path",
+			required: true,
+			schema: { type: "string" },
+			description: "Collection name to reindex"
+		}],
+		responses: jsonResponse({
+			type: "object",
+			properties: {
+				success: { type: "boolean" },
+				collection: { type: "string" }
+			}
+		}, "Reindex started")
+	} };
+	return {
+		paths,
+		tags: [{
+			name: tag,
+			description: "Full-text search endpoints"
+		}]
+	};
+}
+
+//#endregion
+//#region src/generator/index.ts
+/**
+* Generate a complete OpenAPI 3.1 spec from a Questpie CMS instance and optional RPC router.
+*/
+function generateOpenApiSpec$1(cms, rpc, config = {}) {
+	const allPaths = {};
+	const allSchemas = { ...baseComponentSchemas() };
+	const allTags = [];
+	const collections = generateCollectionPaths(cms, config);
+	Object.assign(allPaths, collections.paths);
+	Object.assign(allSchemas, collections.schemas);
+	allTags.push(...collections.tags);
+	const globals = generateGlobalPaths(cms, config);
+	Object.assign(allPaths, globals.paths);
+	Object.assign(allSchemas, globals.schemas);
+	allTags.push(...globals.tags);
+	const rpcResult = generateRpcPaths(rpc, config);
+	Object.assign(allPaths, rpcResult.paths);
+	Object.assign(allSchemas, rpcResult.schemas);
+	allTags.push(...rpcResult.tags);
+	const auth = generateAuthPaths(config);
+	Object.assign(allPaths, auth.paths);
+	allTags.push(...auth.tags);
+	const search = generateSearchPaths(config);
+	Object.assign(allPaths, search.paths);
+	allTags.push(...search.tags);
+	return {
+		openapi: "3.1.0",
+		info: {
+			title: config.info?.title ?? "QUESTPIE CMS API",
+			version: config.info?.version ?? "1.0.0",
+			description: config.info?.description
+		},
+		servers: config.servers,
+		paths: allPaths,
+		components: {
+			schemas: allSchemas,
+			securitySchemes: {
+				bearerAuth: {
+					type: "http",
+					scheme: "bearer"
+				},
+				cookieAuth: {
+					type: "apiKey",
+					in: "cookie",
+					name: "better-auth.session_token"
+				}
+			}
+		},
+		tags: allTags,
+		security: [{ bearerAuth: [] }, { cookieAuth: [] }]
+	};
+}
+
+//#endregion
+//#region src/scalar.ts
+/**
+* Generate an HTML page that renders Scalar API reference UI.
+* The spec is inlined as JSON and Scalar is loaded from CDN.
+*/
+function serveScalarUI(spec, config) {
+	const title = config?.title ?? spec.info.title ?? "API Reference";
+	const scalarConfig = JSON.stringify({
+		theme: config?.theme ?? "purple",
+		hideDownloadButton: config?.hideDownloadButton,
+		defaultHttpClient: config?.defaultHttpClient,
+		customCss: config?.customCss,
+		content: spec
+	});
+	const html = `<!DOCTYPE html>
+<html>
+<head>
+  <title>${escapeHtml(title)}</title>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+</head>
+<body>
+  <script id="api-reference" data-configuration='${escapeAttr(scalarConfig)}'><\/script>
+  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"><\/script>
+</body>
+</html>`;
+	return new Response(html, { headers: { "Content-Type": "text/html; charset=utf-8" } });
+}
+function escapeHtml(str) {
+	return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeAttr(str) {
+	return str.replace(/&/g, "&amp;").replace(/'/g, "&#39;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+//#endregion
+//#region src/server.ts
+/**
+* Generate a complete OpenAPI 3.1 spec from a CMS instance and optional RPC router.
+*/
+function generateOpenApiSpec(cms, rpc, config) {
+	return generateOpenApiSpec$1(cms, rpc, config);
+}
+/**
+* Create request handlers for serving the OpenAPI spec and Scalar UI.
+*/
+function createOpenApiHandlers(spec, options) {
+	return {
+		specHandler: () => new Response(JSON.stringify(spec), { headers: {
+			"Content-Type": "application/json",
+			"Access-Control-Allow-Origin": "*"
+		} }),
+		scalarHandler: () => serveScalarUI(spec, options?.scalar)
+	};
+}
+/**
+* Wrap a CMS fetch handler to add OpenAPI spec and Scalar UI routes.
+*
+* Intercepts requests to `{basePath}/{specPath}` and `{basePath}/{docsPath}`
+* before they reach the CMS handler. Everything else passes through unchanged.
+*
+* @example
+* ```ts
+* const handler = withOpenApi(
+*   createFetchHandler(cms, { basePath: '/api/cms', rpc: appRpc }),
+*   {
+*     cms,
+*     rpc: appRpc,
+*     basePath: '/api/cms',
+*     info: { title: 'My API', version: '1.0.0' },
+*     scalar: { theme: 'purple' },
+*   }
+* )
+* // GET /api/cms/openapi.json → spec JSON
+* // GET /api/cms/docs          → Scalar UI
+* // Everything else            → CMS handler
+* ```
+*/
+function withOpenApi(handler, config) {
+	const { cms, rpc, scalar, specPath = "openapi.json", docsPath = "docs", ...openApiConfig } = config;
+	const { specHandler, scalarHandler } = createOpenApiHandlers(generateOpenApiSpec$1(cms, rpc, openApiConfig), { scalar });
+	const basePath = normalizeBasePath(openApiConfig.basePath ?? "/cms");
+	const specRoute = `${basePath}/${specPath}`;
+	const docsRoute = `${basePath}/${docsPath}`;
+	return (request, context) => {
+		const pathname = new URL(request.url).pathname;
+		if (request.method === "GET") {
+			if (pathname === specRoute) return specHandler();
+			if (pathname === docsRoute) return scalarHandler();
+		}
+		return handler(request, context);
+	};
+}
+function normalizeBasePath(path) {
+	return path.endsWith("/") ? path.slice(0, -1) : path;
+}
+
+//#endregion
+export { createOpenApiHandlers, generateOpenApiSpec, withOpenApi };

package/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@questpie/openapi",
+	"version": "2.0.0",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/questpie/questpie-cms.git",
+		"directory": "packages/openapi"
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsdown",
+		"check-types": "tsc --noEmit"
+	},
+	"dependencies": {
+		"questpie": "workspace:*",
+		"zod": "^4.2.1"
+	},
+	"devDependencies": {
+		"bun-types": "latest",
+		"tsdown": "^0.18.3"
+	},
+	"peerDependencies": {
+		"questpie": "^2.0.0"
+	},
+	"exports": {
+		".": "./src/server.ts",
+		"./package.json": "./package.json"
+	},
+	"publishConfig": {
+		"access": "public",
+		"exports": {
+			".": "./dist/server.mjs",
+			"./package.json": "./package.json"
+		}
+	},
+	"main": "./dist/server.mjs",
+	"module": "./dist/server.mjs",
+	"types": "./dist/server.d.mts"
+}