@btst/stack 1.6.0 → 1.7.0

package/dist/shared/{stack.ByOugz9d.d.mts → stack.CSce37mX.d.mts}

@@ -2,6 +2,18 @@ import { Route, createRouter } from '@btst/yar';
 import { Adapter, DbPlugin, DatabaseDefinition } from '@btst/db';
 import { Endpoint, Router } from 'better-call';
 
+/**
+ * Context passed to backend plugins during route creation
+ * Provides access to all registered plugins for introspection (used by openAPI plugin)
+ */
+interface BetterStackContext {
+    /** All registered backend plugins */
+    plugins: Record<string, BackendPlugin<any>>;
+    /** The API base path (e.g., "/api/data") */
+    basePath: string;
+    /** The database adapter */
+    adapter: Adapter;
+}
 /**
  * Backend plugin definition
  * Defines API routes and data access for a feature
@@ -20,8 +32,9 @@ interface BackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string
      *
      * @param adapter - Better DB adapter instance with methods:
      *   create, update, updateMany, delete, deleteMany, findOne, findMany, count
+     * @param context - Optional context with access to all plugins (for introspection)
      */
-    routes: (adapter: Adapter) => TRoutes;
+    routes: (adapter: Adapter, context?: BetterStackContext) => TRoutes;
     dbPlugin: DbPlugin;
 }
 /**
@@ -129,4 +142,4 @@ type SitemapEntry = {
 };
 type Sitemap = Array<SitemapEntry>;
 
-export type { BackendPlugin as B, ClientPlugin as C, PluginOverrides as P, Sitemap as S, PluginRoutes as a, ClientLibConfig as b, ClientLib as c, PrefixedPluginRoutes as d, BackendLibConfig as e, BackendLib as f };
+export type { BackendPlugin as B, ClientPlugin as C, PluginOverrides as P, Sitemap as S, BetterStackContext as a, PluginRoutes as b, ClientLibConfig as c, ClientLib as d, PrefixedPluginRoutes as e, BackendLibConfig as f, BackendLib as g };

package/dist/shared/{stack.ByOugz9d.d.ts → stack.CSce37mX.d.ts}

@@ -2,6 +2,18 @@ import { Route, createRouter } from '@btst/yar';
 import { Adapter, DbPlugin, DatabaseDefinition } from '@btst/db';
 import { Endpoint, Router } from 'better-call';
 
+/**
+ * Context passed to backend plugins during route creation
+ * Provides access to all registered plugins for introspection (used by openAPI plugin)
+ */
+interface BetterStackContext {
+    /** All registered backend plugins */
+    plugins: Record<string, BackendPlugin<any>>;
+    /** The API base path (e.g., "/api/data") */
+    basePath: string;
+    /** The database adapter */
+    adapter: Adapter;
+}
 /**
  * Backend plugin definition
  * Defines API routes and data access for a feature
@@ -20,8 +32,9 @@ interface BackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string
      *
      * @param adapter - Better DB adapter instance with methods:
      *   create, update, updateMany, delete, deleteMany, findOne, findMany, count
+     * @param context - Optional context with access to all plugins (for introspection)
      */
-    routes: (adapter: Adapter) => TRoutes;
+    routes: (adapter: Adapter, context?: BetterStackContext) => TRoutes;
     dbPlugin: DbPlugin;
 }
 /**
@@ -129,4 +142,4 @@ type SitemapEntry = {
 };
 type Sitemap = Array<SitemapEntry>;
 
-export type { BackendPlugin as B, ClientPlugin as C, PluginOverrides as P, Sitemap as S, PluginRoutes as a, ClientLibConfig as b, ClientLib as c, PrefixedPluginRoutes as d, BackendLibConfig as e, BackendLib as f };
+export type { BackendPlugin as B, ClientPlugin as C, PluginOverrides as P, Sitemap as S, BetterStackContext as a, PluginRoutes as b, ClientLibConfig as c, ClientLib as d, PrefixedPluginRoutes as e, BackendLibConfig as f, BackendLib as g };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",
@@ -247,6 +247,16 @@
       }
     },
     "./plugins/form-builder/css": "./dist/plugins/form-builder/style.css",
+    "./plugins/open-api/api": {
+      "import": {
+        "types": "./dist/plugins/open-api/api/index.d.ts",
+        "default": "./dist/plugins/open-api/api/index.mjs"
+      },
+      "require": {
+        "types": "./dist/plugins/open-api/api/index.d.cts",
+        "default": "./dist/plugins/open-api/api/index.cjs"
+      }
+    },
     "./dist/*": "./dist/*",
     "./ui/css": "./dist/ui/components.css",
     "./package.json": "./package.json"
@@ -312,6 +322,9 @@
       ],
       "plugins/form-builder/client/hooks": [
         "./dist/plugins/form-builder/client/hooks/index.d.ts"
+      ],
+      "plugins/open-api/api": [
+        "./dist/plugins/open-api/api/index.d.ts"
       ]
     }
   },

package/src/api/index.ts

@@ -3,6 +3,7 @@ import type {
 	BackendLibConfig,
 	BackendLib,
 	PrefixedPluginRoutes,
+	BetterStackContext,
 } from "../types";
 import { defineDb } from "@btst/db";
 
@@ -45,9 +46,19 @@ export function betterStack<
 		betterDbSchema = betterDbSchema.use(plugin.dbPlugin);
 	}
 
+	// Create the adapter instance once
+	const adapterInstance = adapter(betterDbSchema);
+
+	// Create context for plugins that need access to all plugins (e.g., openAPI)
+	const context: BetterStackContext = {
+		plugins,
+		basePath,
+		adapter: adapterInstance,
+	};
+
 	for (const [pluginKey, plugin] of Object.entries(plugins)) {
-		// Pass the adapter directly to plugin routes
-		const pluginRoutes = plugin.routes(adapter(betterDbSchema));
+		// Pass both adapter and context to plugin routes
+		const pluginRoutes = plugin.routes(adapterInstance, context);
 
 		// Prefix route keys with plugin name to avoid collisions
 		for (const [routeKey, endpoint] of Object.entries(pluginRoutes)) {
@@ -72,4 +83,5 @@ export type {
 	BackendPlugin,
 	BackendLibConfig,
 	BackendLib,
+	BetterStackContext,
 } from "../types";

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";