@btst/stack 1.6.0 → 1.8.0

package/src/client/index.ts

@@ -4,10 +4,11 @@ import type {
 	ClientLibConfig,
 	ClientLib,
 	ClientPlugin,
+	ClientStackContext,
 	PluginRoutes,
 	Sitemap,
 } from "../types";
-export type { ClientPlugin } from "../types";
+export type { ClientPlugin, ClientStackContext } from "../types";
 
 /**
  * Creates the client library with plugin support
@@ -60,15 +61,21 @@ export function createStackClient<
 	TPlugins extends Record<string, ClientPlugin<any, any>>,
 	TRoutes extends PluginRoutes<TPlugins> = PluginRoutes<TPlugins>,
 >(config: ClientLibConfig<TPlugins>): ClientLib<TRoutes> {
-	const { plugins } = config;
+	const { plugins, basePath } = config;
 
 	// Collect all routes from all plugins
 	// We build this with type assertions to preserve literal keys
 	const allRoutes = {} as TRoutes;
 
+	// Create the context object to pass to plugin routes
+	const clientStackContext: ClientStackContext<TPlugins> = {
+		plugins,
+		basePath,
+	};
+
 	for (const [pluginKey, plugin] of Object.entries(plugins)) {
-		// Add routes
-		const pluginRoutes = plugin.routes();
+		// Add routes - pass the context for plugins that need introspection (e.g., routeDocs)
+		const pluginRoutes = plugin.routes(clientStackContext);
 		Object.assign(allRoutes, pluginRoutes);
 	}
 

package/src/plugins/open-api/api/generator.ts

@@ -0,0 +1,433 @@
+import type { Endpoint } from "better-call";
+import type { BetterStackContext } from "../../../types";
+import * as z from "zod";
+
+/**
+ * OpenAPI path operation object
+ */
+export interface PathOperation {
+	tags?: string[];
+	operationId?: string;
+	description?: string;
+	summary?: string;
+	parameters?: OpenAPIParameter[];
+	requestBody?: {
+		required?: boolean;
+		content: {
+			"application/json": {
+				schema: Record<string, any>;
+			};
+		};
+	};
+	responses: Record<string, any>;
+}
+
+export interface OpenAPIParameter {
+	name: string;
+	in: "query" | "path" | "header";
+	required?: boolean;
+	schema: Record<string, any>;
+	description?: string;
+}
+
+/**
+ * Convert :param to {param} for OpenAPI path format
+ */
+function toOpenApiPath(path: string): string {
+	return path
+		.split("/")
+		.map((part) => (part.startsWith(":") ? `{${part.slice(1)}}` : part))
+		.join("/");
+}
+
+/**
+ * Get the primitive type from a Zod type
+ */
+function getTypeFromZodType(
+	zodType: z.ZodType<any>,
+): "string" | "number" | "boolean" | "array" | "object" | "integer" {
+	// const typeName = zodType._zpiSkeleton?.type || zodType.constructor.name;
+
+	if (zodType instanceof z.ZodString) return "string";
+	if (zodType instanceof z.ZodNumber) return "number";
+	if (zodType instanceof z.ZodBoolean) return "boolean";
+	if (zodType instanceof z.ZodArray) return "array";
+	if (zodType instanceof z.ZodObject) return "object";
+
+	// Fallback based on type property if available
+	const type = (zodType as any).type;
+	if (type === "string") return "string";
+	if (type === "number") return "number";
+	if (type === "boolean") return "boolean";
+	if (type === "array") return "array";
+	if (type === "object") return "object";
+
+	return "string";
+}
+
+/**
+ * Process a Zod type into an OpenAPI schema
+ */
+function processZodType(zodType: z.ZodType<any>): Record<string, any> {
+	// Handle optional - unwrap and process inner type
+	// Optionality is handled by the `required` array in parent object schemas,
+	// NOT by adding `nullable: true` (which would incorrectly allow null values)
+	if (zodType instanceof z.ZodOptional) {
+		const innerType =
+			(zodType as any)._def?.innerType || (zodType as any).unwrap?.();
+		if (innerType) {
+			return processZodType(innerType);
+		}
+	}
+
+	// Handle nullable
+	if (zodType instanceof z.ZodNullable) {
+		const innerType =
+			(zodType as any)._def?.innerType || (zodType as any).unwrap?.();
+		if (innerType) {
+			const innerSchema = processZodType(innerType);
+			return {
+				...innerSchema,
+				nullable: true,
+			};
+		}
+	}
+
+	// Handle default - unwrap and process inner type, including default value
+	if (zodType instanceof z.ZodDefault) {
+		const innerType = (zodType as any)._def?.innerType;
+		const defaultValue = (zodType as any)._def?.defaultValue?.();
+		if (innerType) {
+			const innerSchema = processZodType(innerType);
+			// Include the default value in the OpenAPI schema if it's JSON-serializable
+			if (defaultValue !== undefined) {
+				return {
+					...innerSchema,
+					default: defaultValue,
+				};
+			}
+			return innerSchema;
+		}
+	}
+
+	// Handle object
+	if (zodType instanceof z.ZodObject) {
+		const shape = (zodType as any).shape || (zodType as any)._def?.shape?.();
+		if (shape) {
+			const properties: Record<string, any> = {};
+			const required: string[] = [];
+
+			for (const [key, value] of Object.entries(shape)) {
+				if (value instanceof z.ZodType) {
+					properties[key] = processZodType(value);
+					if (!(value instanceof z.ZodOptional)) {
+						required.push(key);
+					}
+				}
+			}
+
+			return {
+				type: "object",
+				properties,
+				...(required.length > 0 ? { required } : {}),
+			};
+		}
+	}
+
+	// Handle array
+	if (zodType instanceof z.ZodArray) {
+		const elementType = (zodType as any)._def?.type || (zodType as any).element;
+		return {
+			type: "array",
+			items: elementType ? processZodType(elementType) : { type: "string" },
+		};
+	}
+
+	// Handle enum
+	if (zodType instanceof z.ZodEnum) {
+		const values = (zodType as any)._def?.values || (zodType as any).options;
+		return {
+			type: "string",
+			enum: values,
+		};
+	}
+
+	// Handle literal
+	if (zodType instanceof z.ZodLiteral) {
+		const value = (zodType as any)._def?.value || (zodType as any).value;
+		// Map JavaScript typeof to OpenAPI 3.1 types correctly
+		// Note: typeof null === "object" in JS, but OpenAPI 3.1 has "null" type
+		let type: string;
+		if (value === null) {
+			type = "null";
+		} else if (value === undefined) {
+			// undefined is not a valid JSON/OpenAPI value, treat as nullable
+			return { nullable: true };
+		} else {
+			type = typeof value;
+		}
+		return {
+			type,
+			const: value,
+		};
+	}
+
+	// Handle union
+	if (zodType instanceof z.ZodUnion) {
+		const options = (zodType as any)._def?.options || (zodType as any).options;
+		if (options && Array.isArray(options)) {
+			return {
+				oneOf: options.map((opt: z.ZodType<any>) => processZodType(opt)),
+			};
+		}
+	}
+
+	// Handle coerce types
+	if ((zodType as any)._def?.coerce) {
+		const innerType = (zodType as any)._def?.innerType;
+		if (innerType) {
+			return processZodType(innerType);
+		}
+	}
+
+	// Default to primitive type
+	return {
+		type: getTypeFromZodType(zodType),
+	};
+}
+
+/**
+ * Extract query parameters from endpoint options
+ */
+function getParameters(options: any): OpenAPIParameter[] {
+	const parameters: OpenAPIParameter[] = [];
+
+	// Handle query parameters
+	if (options.query instanceof z.ZodObject) {
+		const shape =
+			(options.query as any).shape || (options.query as any)._def?.shape?.();
+		if (shape) {
+			for (const [key, value] of Object.entries(shape)) {
+				if (value instanceof z.ZodType) {
+					parameters.push({
+						name: key,
+						in: "query",
+						required: !(value instanceof z.ZodOptional),
+						schema: processZodType(value),
+					});
+				}
+			}
+		}
+	}
+
+	// Handle path parameters from params schema
+	if (options.params instanceof z.ZodObject) {
+		const shape =
+			(options.params as any).shape || (options.params as any)._def?.shape?.();
+		if (shape) {
+			for (const [key, value] of Object.entries(shape)) {
+				if (value instanceof z.ZodType) {
+					parameters.push({
+						name: key,
+						in: "path",
+						required: true,
+						schema: processZodType(value),
+					});
+				}
+			}
+		}
+	}
+
+	return parameters;
+}
+
+/**
+ * Extract request body schema from endpoint options
+ *
+ * Handles any Zod type as request body including:
+ * - ZodObject (most common)
+ * - ZodArray (batch/bulk operations)
+ * - ZodUnion (multiple accepted formats)
+ * - ZodOptional (optional body)
+ * - ZodNullable, ZodEnum, ZodLiteral, etc.
+ */
+function getRequestBody(
+	options: any,
+): PathOperation["requestBody"] | undefined {
+	if (!options.body) return undefined;
+
+	// Handle any Zod type - processZodType already handles all Zod types
+	if (options.body instanceof z.ZodType) {
+		const schema = processZodType(options.body);
+
+		// Determine if body is required:
+		// - ZodOptional: not required
+		// - ZodNullable: required but can be null (nullable is set in schema)
+		// - Everything else: required
+		const isOptional = options.body instanceof z.ZodOptional;
+
+		return {
+			required: !isOptional,
+			content: {
+				"application/json": {
+					schema,
+				},
+			},
+		};
+	}
+
+	return undefined;
+}
+
+/**
+ * Create a fresh error schema object to avoid circular references in JSON serialization
+ */
+function createErrorSchema(): Record<string, any> {
+	return {
+		type: "object",
+		properties: {
+			message: { type: "string" },
+		},
+		required: ["message"],
+	};
+}
+
+/**
+ * Generate standard error responses (creates fresh objects to avoid circular refs)
+ */
+function getErrorResponses(): Record<string, any> {
+	return {
+		"400": {
+			description: "Bad Request",
+			content: { "application/json": { schema: createErrorSchema() } },
+		},
+		"401": {
+			description: "Unauthorized",
+			content: { "application/json": { schema: createErrorSchema() } },
+		},
+		"403": {
+			description: "Forbidden",
+			content: { "application/json": { schema: createErrorSchema() } },
+		},
+		"404": {
+			description: "Not Found",
+			content: { "application/json": { schema: createErrorSchema() } },
+		},
+		"500": {
+			description: "Internal Server Error",
+			content: { "application/json": { schema: createErrorSchema() } },
+		},
+	};
+}
+
+/**
+ * Generate OpenAPI 3.1 schema from Better Stack context
+ */
+export function generateOpenAPISchema(
+	context: BetterStackContext,
+	options?: { title?: string; description?: string; version?: string },
+): Record<string, any> {
+	const paths: Record<string, Record<string, PathOperation>> = {};
+	const tags: Array<{ name: string; description: string }> = [];
+
+	// Iterate over all plugins
+	for (const [pluginKey, plugin] of Object.entries(context.plugins)) {
+		// Skip the open-api plugin itself
+		if (pluginKey === "openApi" || plugin.name === "open-api") {
+			continue;
+		}
+
+		// Get plugin routes
+		const pluginRoutes = plugin.routes(context.adapter, context);
+
+		// Create tag for this plugin
+		const tagName = pluginKey.charAt(0).toUpperCase() + pluginKey.slice(1);
+		tags.push({
+			name: tagName,
+			description: `${tagName} plugin endpoints`,
+		});
+
+		// Process each endpoint
+		for (const [routeKey, endpoint] of Object.entries(pluginRoutes)) {
+			const ep = endpoint as Endpoint;
+
+			// Access endpoint properties
+			const path = (ep as any).path;
+			const endpointOptions = (ep as any).options || {};
+			const method = (endpointOptions.method || "GET").toLowerCase();
+
+			if (!path) continue;
+
+			const openApiPath = toOpenApiPath(path);
+
+			// Initialize path object if needed
+			if (!paths[openApiPath]) {
+				paths[openApiPath] = {};
+			}
+
+			// Build operation object
+			const operation: PathOperation = {
+				tags: [tagName],
+				operationId: `${pluginKey}_${routeKey}`,
+				summary: endpointOptions.metadata?.openapi?.summary,
+				description: endpointOptions.metadata?.openapi?.description,
+				parameters: getParameters(endpointOptions),
+				responses: {
+					"200": {
+						description: "Successful response",
+						content: {
+							"application/json": {
+								schema: { type: "object" },
+							},
+						},
+					},
+					...getErrorResponses(),
+				},
+			};
+
+			// Add request body for POST/PUT/PATCH
+			if (["post", "put", "patch"].includes(method)) {
+				const requestBody = getRequestBody(endpointOptions);
+				if (requestBody) {
+					operation.requestBody = requestBody;
+				}
+			}
+
+			paths[openApiPath][method] = operation;
+		}
+	}
+
+	return {
+		openapi: "3.1.0",
+		info: {
+			title: options?.title || "Better Stack API",
+			description:
+				options?.description ||
+				"API Reference for your Better Stack application",
+			version: options?.version || "1.0.0",
+		},
+		servers: [
+			{
+				url: context.basePath,
+				description: "API Server",
+			},
+		],
+		tags,
+		paths,
+		components: {
+			securitySchemes: {
+				bearerAuth: {
+					type: "http",
+					scheme: "bearer",
+					description: "Bearer token authentication",
+				},
+				cookieAuth: {
+					type: "apiKey",
+					in: "cookie",
+					name: "session",
+					description: "Session cookie authentication",
+				},
+			},
+		},
+	};
+}

package/src/plugins/open-api/api/index.ts

@@ -0,0 +1,8 @@
+export {
+	openApiBackendPlugin,
+	type OpenAPIOptions,
+	type ScalarTheme,
+	type OpenApiRouter,
+} from "./plugin";
+
+export { generateOpenAPISchema } from "./generator";

package/src/plugins/open-api/api/plugin.ts

@@ -0,0 +1,243 @@
+import { defineBackendPlugin } from "@btst/stack/plugins/api";
+import { createEndpoint } from "@btst/stack/plugins/api";
+import { openApiSchema } from "../db";
+import { generateOpenAPISchema } from "./generator";
+import { logo } from "../logo";
+import type { BetterStackContext } from "../../../types";
+
+/**
+ * Scalar API Reference themes
+ */
+export type ScalarTheme =
+	| "alternate"
+	| "default"
+	| "moon"
+	| "purple"
+	| "solarized"
+	| "bluePlanet"
+	| "saturn"
+	| "kepler"
+	| "mars"
+	| "deepSpace"
+	| "laserwave"
+	| "none";
+
+/**
+ * OpenAPI plugin configuration options
+ */
+export interface OpenAPIOptions {
+	/**
+	 * The path to the OpenAPI reference page
+	 * This path is relative to the API base path
+	 * @default "/reference"
+	 */
+	path?: string;
+
+	/**
+	 * Disable the default HTML reference page
+	 * Only the JSON schema endpoint will be available
+	 * @default false
+	 */
+	disableDefaultReference?: boolean;
+
+	/**
+	 * Theme for the Scalar API Reference page
+	 * @default "default"
+	 */
+	theme?: ScalarTheme;
+
+	/**
+	 * CSP nonce for inline scripts
+	 * Required for strict Content Security Policy
+	 */
+	nonce?: string;
+
+	/**
+	 * Custom title for the API documentation
+	 * @default "Better Stack API"
+	 */
+	title?: string;
+
+	/**
+	 * Custom description for the API documentation
+	 */
+	description?: string;
+
+	/**
+	 * API version string
+	 * @default "1.0.0"
+	 */
+	version?: string;
+}
+
+/**
+ * Escape HTML entities to prevent XSS and ensure proper rendering
+ */
+function escapeHtml(str: string): string {
+	return str
+		.replace(/&/g, "&")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&#39;");
+}
+
+/**
+ * Escape JSON for safe embedding in HTML script tags.
+ * Replaces < with \u003c to prevent </script> from closing the tag prematurely.
+ * This is valid JSON and will be parsed correctly.
+ */
+function escapeJsonForHtml(json: string): string {
+	return json.replace(/</g, "\\u003c");
+}
+
+/**
+ * Generate the HTML page for Scalar API Reference
+ */
+function getScalarHTML(
+	schema: Record<string, any>,
+	theme: ScalarTheme = "default",
+	nonce?: string,
+): string {
+	const nonceAttr = nonce ? ` nonce="${escapeHtml(nonce)}"` : "";
+	const encodedLogo = encodeURIComponent(logo);
+
+	const title = schema.info?.title || "API Reference";
+	const description = schema.info?.description || "API Reference";
+
+	return `<!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"
+      type="application/json"${nonceAttr}>
+    ${escapeJsonForHtml(JSON.stringify(schema))}
+    </script>
+    <script${nonceAttr}>
+      var configuration = {
+        favicon: "data:image/svg+xml;utf8,${encodedLogo}",
+        theme: "${theme}",
+        metaData: {
+          title: ${JSON.stringify(title)},
+          description: ${JSON.stringify(description)},
+        }
+      }
+
+      document.getElementById('api-reference').dataset.configuration =
+        JSON.stringify(configuration)
+    </script>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"${nonceAttr}></script>
+  </body>
+</html>`;
+}
+
+/**
+ * OpenAPI plugin for Better Stack
+ *
+ * Automatically generates OpenAPI 3.1 documentation for all registered plugins.
+ * Provides both a JSON schema endpoint and an interactive Scalar UI reference page.
+ *
+ * @example
+ * ```ts
+ * const { handler } = betterStack({
+ *   basePath: "/api/data",
+ *   plugins: {
+ *     blog: blogBackendPlugin(),
+ *     cms: cmsBackendPlugin({ ... }),
+ *     openApi: openApiBackendPlugin({ theme: "moon" }),
+ *   },
+ *   adapter: (db) => createMemoryAdapter(db)({}),
+ * });
+ *
+ * // Access:
+ * // - GET /api/data/open-api/schema - JSON schema
+ * // - GET /api/data/reference - Interactive Scalar UI
+ * ```
+ */
+export const openApiBackendPlugin = (options?: OpenAPIOptions) => {
+	const referencePath = options?.path ?? "/reference";
+
+	// Store context for use in endpoint handlers
+	let storedContext: BetterStackContext | null = null;
+
+	return defineBackendPlugin({
+		name: "open-api",
+		dbPlugin: openApiSchema,
+
+		routes: (_adapter, context) => {
+			// Store context for endpoint handlers
+			storedContext = context ?? null;
+
+			const generateSchema = createEndpoint(
+				"/open-api/schema",
+				{
+					method: "GET",
+				},
+				async (ctx) => {
+					if (!storedContext) {
+						throw ctx.error(500, {
+							message: "OpenAPI context not available",
+						});
+					}
+
+					const schema = generateOpenAPISchema(storedContext, {
+						title: options?.title,
+						description: options?.description,
+						version: options?.version,
+					});
+
+					return schema;
+				},
+			);
+
+			const reference = createEndpoint(
+				referencePath,
+				{
+					method: "GET",
+				},
+				async (ctx) => {
+					if (options?.disableDefaultReference) {
+						throw ctx.error(404, {
+							message: "Reference page is disabled",
+						});
+					}
+
+					if (!storedContext) {
+						throw ctx.error(500, {
+							message: "OpenAPI context not available",
+						});
+					}
+
+					const schema = generateOpenAPISchema(storedContext, {
+						title: options?.title,
+						description: options?.description,
+						version: options?.version,
+					});
+
+					return new Response(
+						getScalarHTML(schema, options?.theme, options?.nonce),
+						{
+							headers: {
+								"Content-Type": "text/html; charset=utf-8",
+							},
+						},
+					);
+				},
+			);
+
+			return {
+				generateSchema,
+				reference,
+			} as const;
+		},
+	});
+};
+
+export type OpenApiRouter = ReturnType<
+	ReturnType<typeof openApiBackendPlugin>["routes"]
+>;