appos 0.3.2-0 → 0.3.4-0

package/dist/exports/api/openapi.mjs

@@ -1 +1,507 @@
-import{defineAppContext as e}from"./app-context.mjs";import{APPOS_DIR as t,FILE_EXT as n,PUBLIC_DIR as r,ROUTES_DIR as i}from"./constants.mjs";import{z as a}from"zod";import{join as o,resolve as s}from"node:path";import{access as c,mkdir as l,writeFile as u}from"node:fs/promises";import{remixRoutesOptionAdapter as d}from"@react-router/remix-routes-option-adapter";import{isEmpty as f}from"es-toolkit/compat";import{flatRoutes as p}from"remix-flat-routes";import{createDocument as m}from"zod-openapi";const h=s(r,`openapi`);function g(e){let t={};for(let[n,r]of Object.entries(e)){let e=Number(n),i=_(e);i&&(t[i]=t=>{let n=r.schema;if(n instanceof a.ZodNull||t==null)return{__response:!0,status:e,data:t??null};try{let r=n;if(n instanceof a.ZodObject)r=n.strict();else if(n instanceof a.ZodArray){let e=n.element;e instanceof a.ZodObject&&(r=a.array(e.strict()))}return{__response:!0,status:e,data:r.parse(t)}}catch(n){throw n instanceof a.ZodError?Error(`Response validation failed for status ${e}: ${JSON.stringify(n.issues,null,2)}\n\nData provided: ${JSON.stringify(t,null,2)}`):n}})}return t.status=(t,n)=>{let r=Number(t),i=e[t];if(!i)return{__response:!0,status:r,data:n??null};let o=i.schema;if(!o||o instanceof a.ZodNull||n==null)return{__response:!0,status:r,data:n??null};try{let e=o;if(o instanceof a.ZodObject)e=o.strict();else if(o instanceof a.ZodArray){let t=o.element;t instanceof a.ZodObject&&(e=a.array(t.strict()))}return{__response:!0,status:r,data:e.parse(n)}}catch(e){throw e instanceof a.ZodError?Error(`Response validation failed for status ${r}: ${JSON.stringify(e.issues,null,2)}\n\nData provided: ${JSON.stringify(n,null,2)}`):e}},t}function _(e){return{200:`ok`,201:`created`,202:`accepted`,204:`noContent`,400:`badRequest`,401:`unauthorized`,403:`forbidden`,404:`notFound`,409:`conflict`,422:`unprocessableEntity`,500:`internalServerError`}[e]||null}function v(e){return e}function y(e,t){return e?e.parse(t):t}function b(e,t){let n={};for(let[e,r]of t.searchParams.entries()){let t=n[e];t===void 0?n[e]=r:Array.isArray(t)?t.push(r):n[e]=[t,r]}return e?e.parse(n):n}function x(e,t){let n=t.body;return e?e.parse(n):n}function S(e,t){let n=t.headers;return e?e.parse(n):n}function C(e){switch(e){case`params`:case`query`:case`headers`:return 400;case`body`:return 422;default:return 400}}function w(e,t){let n=C(t);return{__response:!0,status:n,data:{error:`validation_error`,status:n,detail:`Request validation failed`,errors:e.issues.map(e=>({field:e.path.join(`.`),message:e.message,received:`received`in e?e.received:e.input}))}}}function T(t,n){return async(r,i,o)=>{try{let n=new URL(r.url||`/`,`http://${r.headers.host}`),a=y(t.params,r.params),o=b(t.query,n),s=x(t.requestBody,r),c=S(t.headers,r),l=g(t.responses),u=await e({apiKey:r.apiKey,container:r.app.locals.container,request:r,fetchSession:!1}),d=await t.handler({ctx:u,body:s,headers:c,params:a,query:o,request:r,response:l});if(d&&typeof d==`object`&&`__response`in d){let e=d;e.data===null||e.data===void 0?i.status(e.status).end():i.status(e.status).json(e.data)}else i.status(200).json(d)}catch(e){if(e instanceof a.ZodError){let t=w(e,n===`GET`||n===`HEAD`?`query`:`body`);i.status(t.status).json(t.data)}else o(e)}}}function E(e){let t=[];for(let n of[`GET`,`HEAD`,`POST`,`PUT`,`PATCH`,`DELETE`]){let r=e[n];if(!r)continue;let i={};r.params&&(i.params=r.params),r.query&&(i.query=r.query),r.requestBody&&(i.body=r.requestBody),r.headers&&(i.headers=r.headers);let a={};for(let[e,t]of Object.entries(r.responses))a[Number(e)]={description:t.description,content:{"application/json":{schema:t.schema}}};t.push({method:n.toLowerCase(),summary:r.summary,description:r.description,request:Object.keys(i).length>0?i:void 0,responses:a})}return t}function D(e){let t={};for(let n of[`GET`,`HEAD`,`POST`,`PUT`,`PATCH`,`DELETE`]){let r=e[n];r&&(t[n]=T(r,n))}return{handlers:t,openAPISpec:E(e)}}function O(e){return t=>{let n=e(t);return{info:n.info,servers:n.servers,openapi:`3.1.0`}}}function k(e){return e.match(/^\/(v\d+)/)?.[1]}function A(e){return e.replace(/:(\w+)/g,`{$1}`)}function j(e,t){let n=A(e),r={summary:t.summary,description:t.description};(t.request?.params||t.request?.query||t.request?.headers)&&(r.requestParams={},t.request.params&&(r.requestParams.path=t.request.params),t.request.query&&(r.requestParams.query=t.request.query),t.request.headers&&(r.requestParams.header=t.request.headers)),t.request?.body&&(r.requestBody={content:{"application/json":{schema:t.request.body}}}),r.responses={};for(let[e,n]of Object.entries(t.responses))r.responses[e]={description:n.description,content:{"application/json":{schema:n.content[`application/json`].schema}}};return{path:n,config:r}}function M(e,t,n){let r={};for(let n of e){if(n.version!==t)continue;let e=n.path.replace(`/${t}`,``)||`/`;for(let t of n.openAPISpec){let{path:n,config:i}=j(e,t);r[n]||(r[n]={}),r[n][t.method]=i}}return m({openapi:`3.1.0`,info:n?.info||{title:`API ${t.toUpperCase()}`,version:t.replace(`v`,``),description:`OpenAPI specification for ${t} API`},servers:n?.servers||[{url:`http://localhost:8000/${t}`,description:process.env.NODE_ENV===`production`?`Production server`:`Development server`}],paths:r})}async function N(e){let n=s(t,i);try{await c(n)}catch(t){return e.logger.error({error:t},`OpenAPI routes directory not found`),[]}let r=await d(e=>p(i,e,{appDir:t,ignoredRouteFiles:[`**/.*`,`**/*.{spec,test}.{ts,tsx}`,`**/*-????????.{js,ts}`]})),a=[];for(let[n,i]of Object.entries(r)){let n=s(t,i.file).replace(/.ts$/,process.env.NODE_ENV===`production`?`.js`:`.ts`);try{let r=(await import(n)).default;if(!r||f(r)||/\/openapi.(j|t)s$/.test(n))continue;if(!r?.handlers&&!r?.openAPISpec){e.logger.warn(`Missing default export with 'defineOpenAPI' for '${t}/${i.file}'`);continue}let o=`/${i.path}`;a.push({path:o,filePath:n,handlers:r.handlers,openAPISpec:r.openAPISpec,version:k(o)})}catch(t){e.logger.error(t,`Error loading route ${i.file}:`)}}return a}function P(e,t){for(let n of t)for(let[t,r]of Object.entries(n.handlers))e[t.toLowerCase()](n.path,r)}async function F(e,r){let a=s(t,i,`${r}+/openapi.${n}`);try{let t=(await import(a)).default;return t?t(e):void 0}catch{return}}async function I(e,t){let n=[...new Set(t.map(e=>e.version).filter(Boolean))];n.length>0&&await l(h,{recursive:!0});for(let r of n){let n=M(t,r,await F(e,r));await u(o(h,`${r}.json`),JSON.stringify(n,null,2),`utf-8`)}}async function L(e){let t=await N(e.locals.container);P(e,t),process.env.NODE_ENV!==`production`&&await I(e.locals.container,t)}export{D as defineOpenAPI,O as defineOpenAPIConfig,v as defineOpenAPIEndpoint,g as defineTypedResponses,M as generateOpenAPIDocument,L as loadAndRegisterAPIRoutes,P as registerRoutes,N as scanAPIRoutes,I as writeOpenAPISpecs};
+import { defineAppContext } from "./app-context.mjs";
+import { APPOS_DIR, FILE_EXT, PUBLIC_DIR, ROUTES_DIR } from "./constants.mjs";
+import { z } from "zod";
+import { join, resolve } from "node:path";
+import { access, mkdir, writeFile } from "node:fs/promises";
+import { remixRoutesOptionAdapter } from "@react-router/remix-routes-option-adapter";
+import { isEmpty } from "es-toolkit/compat";
+import { flatRoutes } from "remix-flat-routes";
+import { createDocument } from "zod-openapi";
+
+//#region src/api/openapi.ts
+const outputDir = resolve(PUBLIC_DIR, "openapi");
+/**
+* Define typed response builders based on defined response schemas.
+*/
+function defineTypedResponses(responses) {
+	const builder = {};
+	for (const [statusCode, responseSpec] of Object.entries(responses)) {
+		const status = Number(statusCode);
+		const methodName = getMethodNameForStatus(status);
+		const schema = responseSpec.schema;
+		let strictSchema = schema;
+		if (schema instanceof z.ZodObject) strictSchema = schema.strict();
+		else if (schema instanceof z.ZodArray) {
+			const elementSchema = schema.element;
+			if (elementSchema instanceof z.ZodObject) strictSchema = z.array(elementSchema.strict());
+		}
+		if (methodName) builder[methodName] = (data) => {
+			if (schema instanceof z.ZodNull || data === null || data === void 0) return {
+				__response: true,
+				status,
+				data: data ?? null
+			};
+			try {
+				return {
+					__response: true,
+					status,
+					data: strictSchema.parse(data)
+				};
+			} catch (error) {
+				if (error instanceof z.ZodError) throw new Error(`Response validation failed for status ${status}: ${JSON.stringify(error.issues, null, 2)}\n\nData provided: ${JSON.stringify(data, null, 2)}`);
+				throw error;
+			}
+		};
+	}
+	const strictSchemaCache = /* @__PURE__ */ new Map();
+	for (const [statusCode, responseSpec] of Object.entries(responses)) {
+		const status = Number(statusCode);
+		const schema = responseSpec.schema;
+		let strictSchema = schema;
+		if (schema instanceof z.ZodObject) strictSchema = schema.strict();
+		else if (schema instanceof z.ZodArray) {
+			const elementSchema = schema.element;
+			if (elementSchema instanceof z.ZodObject) strictSchema = z.array(elementSchema.strict());
+		}
+		strictSchemaCache.set(status, strictSchema);
+	}
+	builder.status = (statusCode, data) => {
+		const status = Number(statusCode);
+		const responseSpec = responses[statusCode];
+		if (!responseSpec) return {
+			__response: true,
+			status,
+			data: data ?? null
+		};
+		const schema = responseSpec.schema;
+		if (!schema) return {
+			__response: true,
+			status,
+			data: data ?? null
+		};
+		if (schema instanceof z.ZodNull || data === null || data === void 0) return {
+			__response: true,
+			status,
+			data: data ?? null
+		};
+		const strictSchema = strictSchemaCache.get(status) || schema;
+		try {
+			return {
+				__response: true,
+				status,
+				data: strictSchema.parse(data)
+			};
+		} catch (error) {
+			if (error instanceof z.ZodError) throw new Error(`Response validation failed for status ${status}: ${JSON.stringify(error.issues, null, 2)}\n\nData provided: ${JSON.stringify(data, null, 2)}`);
+			throw error;
+		}
+	};
+	return builder;
+}
+function getMethodNameForStatus(status) {
+	return {
+		200: "ok",
+		201: "created",
+		202: "accepted",
+		204: "noContent",
+		400: "badRequest",
+		401: "unauthorized",
+		403: "forbidden",
+		404: "notFound",
+		409: "conflict",
+		422: "unprocessableEntity",
+		500: "internalServerError"
+	}[status] || null;
+}
+/**
+* Helper function to define an OpenAPI endpoint with full type safety.
+*/
+function defineOpenAPIEndpoint(spec) {
+	return spec;
+}
+/**
+* Parse and validate request parameters with Zod schema
+*/
+function parseParams(schema, rawParams) {
+	if (!schema) return rawParams;
+	return schema.parse(rawParams);
+}
+/**
+* Parse and validate query parameters with Zod schema
+*/
+function parseQuery(schema, url) {
+	const queryObj = {};
+	for (const [key, value] of url.searchParams.entries()) {
+		const existing = queryObj[key];
+		if (existing === void 0) queryObj[key] = value;
+		else if (Array.isArray(existing)) existing.push(value);
+		else queryObj[key] = [existing, value];
+	}
+	if (!schema) return queryObj;
+	return schema.parse(queryObj);
+}
+/**
+* Parse and validate request body with Zod schema
+* Note: Express body is already parsed by express.json() middleware
+*/
+function parseBody(schema, req) {
+	const bodyData = req.body;
+	if (!schema) return bodyData;
+	return schema.parse(bodyData);
+}
+/**
+* Parse and validate request headers with Zod schema
+* Note: Express req.headers is already a plain object
+*/
+function parseHeaders(schema, req) {
+	const headersObj = req.headers;
+	if (!schema) return headersObj;
+	return schema.parse(headersObj);
+}
+/**
+* Get appropriate HTTP status code for validation error type
+*/
+function getValidationStatusCode(errorType) {
+	switch (errorType) {
+		case "params":
+		case "query":
+		case "headers": return 400;
+		case "body": return 422;
+		default: return 400;
+	}
+}
+/**
+* Create RFC 9457 compliant validation error response
+*/
+function createValidationErrorResponse(error, errorType) {
+	const status = getValidationStatusCode(errorType);
+	return {
+		__response: true,
+		status,
+		data: {
+			error: "validation_error",
+			status,
+			detail: "Request validation failed",
+			errors: error.issues.map((issue) => ({
+				field: issue.path.join("."),
+				message: issue.message,
+				received: "received" in issue ? issue.received : issue.input
+			}))
+		}
+	};
+}
+/**
+* Define Express handler for a single HTTP method.
+*
+* Builds a unified AppContext from the Express request, including:
+* - container and workflows from app.locals
+* - request metadata (id, ipAddress, userAgent, headers)
+* - auth state (user, session) from Better Auth
+*/
+function defineExpressHandler(spec, method) {
+	const responseBuilder = defineTypedResponses(spec.responses);
+	return async (req, res, next) => {
+		try {
+			const url = new URL(req.url || "/", `http://${req.headers.host}`);
+			const parsedParams = parseParams(spec.params, req.params);
+			const parsedQuery = parseQuery(spec.query, url);
+			const parsedBody = parseBody(spec.requestBody, req);
+			const parsedHeaders = parseHeaders(spec.headers, req);
+			const ctx = await defineAppContext({
+				apiKey: req.apiKey,
+				container: req.app.locals.container,
+				request: req,
+				fetchSession: false
+			});
+			const result = await spec.handler({
+				ctx,
+				body: parsedBody,
+				headers: parsedHeaders,
+				params: parsedParams,
+				query: parsedQuery,
+				request: req,
+				response: responseBuilder
+			});
+			if (result && typeof result === "object" && "__response" in result) {
+				const marker = result;
+				if (marker.data === null || marker.data === void 0) res.status(marker.status).end();
+				else res.status(marker.status).json(marker.data);
+			} else res.status(200).json(result);
+		} catch (error) {
+			if (error instanceof z.ZodError) {
+				const errorResponse = createValidationErrorResponse(error, method === "GET" || method === "HEAD" ? "query" : "body");
+				res.status(errorResponse.status).json(errorResponse.data);
+			} else next(error);
+		}
+	};
+}
+/**
+* Generate OpenAPI specification array for CLI registration.
+*/
+function generateOpenAPISpec(config) {
+	const specs = [];
+	for (const method of [
+		"GET",
+		"HEAD",
+		"POST",
+		"PUT",
+		"PATCH",
+		"DELETE"
+	]) {
+		const spec = config[method];
+		if (!spec) continue;
+		const request = {};
+		if (spec.params) request.params = spec.params;
+		if (spec.query) request.query = spec.query;
+		if (spec.requestBody) request.body = spec.requestBody;
+		if (spec.headers) request.headers = spec.headers;
+		const responses = {};
+		for (const [statusCode, responseSpec] of Object.entries(spec.responses)) responses[Number(statusCode)] = {
+			description: responseSpec.description,
+			content: { "application/json": { schema: responseSpec.schema } }
+		};
+		specs.push({
+			method: method.toLowerCase(),
+			summary: spec.summary,
+			description: spec.description,
+			request: Object.keys(request).length > 0 ? request : void 0,
+			responses
+		});
+	}
+	return specs;
+}
+/**
+* Define OpenAPI-based route handlers with full type safety.
+*
+* @param config Configuration object with HTTP method specifications
+* @returns Object containing Express handlers and openAPISpec
+*
+* @example
+* ```typescript
+* // Basic usage
+* export default defineOpenAPI({
+*   GET: {
+*     summary: "Get user by ID",
+*     params: z.object({ id: z.uuid() }),
+*     responses: {
+*       200: { description: "User data", schema: UserSchema }
+*     },
+*     handler: async ({ params, response }) => {
+*       const user = await getUser(params.id);
+*       return response.ok(user); // Fully typed!
+*     }
+*   },
+*   POST: {
+*     summary: "Create user",
+*     requestBody: CreateUserSchema,
+*     responses: {
+*       201: { description: "User created", schema: UserSchema }
+*     },
+*     handler: async ({ body, response }) => {
+*       const user = await createUser(body);
+*       return response.created(user); // Fully typed!
+*     }
+*   }
+* });
+* ```
+*/
+function defineOpenAPI(config) {
+	const handlers = {};
+	for (const method of [
+		"GET",
+		"HEAD",
+		"POST",
+		"PUT",
+		"PATCH",
+		"DELETE"
+	]) {
+		const spec = config[method];
+		if (spec) handlers[method] = defineExpressHandler(spec, method);
+	}
+	return {
+		handlers,
+		openAPISpec: generateOpenAPISpec(config)
+	};
+}
+/**
+* Define OpenAPI document configuration with improved DX.
+*
+* Only allows specifying info and servers objects, ensuring a consistent
+* OpenAPI v3.1.0 structure while preventing configuration of other fields.
+*
+* @param config Configuration object with info and optional servers
+* @returns Complete OpenAPI configuration object
+*
+* @example
+* ```typescript
+* export const openAPIConfig = defineOpenAPIConfig({
+*   info: {
+*     title: "My API",
+*     version: "1.0.0",
+*     description: "API v1 - Authentication and core features",
+*     contact: {
+*       name: "API Support",
+*       email: "support@example.com",
+*     },
+*   },
+*   servers: [
+*     {
+*       url: process.env.API_URL || "http://localhost:8000",
+*       description: "API Server",
+*     },
+*   ],
+* });
+* ```
+*/
+function defineOpenAPIConfig(config) {
+	return (container) => {
+		const input = config(container);
+		return {
+			info: input.info,
+			servers: input.servers,
+			openapi: "3.1.0"
+		};
+	};
+}
+/**
+* Extract API version from route path.
+*/
+function extractVersion(path) {
+	return path.match(/^\/(v\d+)/)?.[1];
+}
+/**
+* Convert React Router path params (:param) to OpenAPI format ({param}).
+*/
+function convertToOpenAPIPath(reactRouterPath) {
+	return reactRouterPath.replace(/:(\w+)/g, "{$1}");
+}
+/**
+* Build an OpenAPI path object from a route specification.
+*/
+function buildPathObject(path, spec) {
+	const openApiPath = convertToOpenAPIPath(path);
+	const methodConfig = {
+		summary: spec.summary,
+		description: spec.description
+	};
+	if (spec.request?.params || spec.request?.query || spec.request?.headers) {
+		methodConfig.requestParams = {};
+		if (spec.request.params) methodConfig.requestParams.path = spec.request.params;
+		if (spec.request.query) methodConfig.requestParams.query = spec.request.query;
+		if (spec.request.headers) methodConfig.requestParams.header = spec.request.headers;
+	}
+	if (spec.request?.body) methodConfig.requestBody = { content: { "application/json": { schema: spec.request.body } } };
+	methodConfig.responses = {};
+	for (const [statusCode, response] of Object.entries(spec.responses)) methodConfig.responses[statusCode] = {
+		description: response.description,
+		content: { "application/json": { schema: response.content["application/json"].schema } }
+	};
+	return {
+		path: openApiPath,
+		config: methodConfig
+	};
+}
+/**
+* Generate complete OpenAPI 3.1.0 document from routes using zod-openapi
+*/
+function generateOpenAPIDocument(routes, version, config) {
+	const paths = {};
+	for (const route of routes) {
+		if (route.version !== version) continue;
+		const apiPath = route.path.replace(`/${version}`, "") || "/";
+		for (const spec of route.openAPISpec) {
+			const { path: openApiPath, config: methodConfig } = buildPathObject(apiPath, spec);
+			if (!paths[openApiPath]) paths[openApiPath] = {};
+			paths[openApiPath][spec.method] = methodConfig;
+		}
+	}
+	return createDocument({
+		openapi: "3.1.0",
+		info: config?.info || {
+			title: `API ${version.toUpperCase()}`,
+			version: version.replace("v", ""),
+			description: `OpenAPI specification for ${version} API`
+		},
+		servers: config?.servers || [{
+			url: `http://localhost:8000/${version}`,
+			description: process.env.NODE_ENV === "production" ? "Production server" : "Development server"
+		}],
+		paths
+	});
+}
+/**
+* Scan routes directory and convert to Express route paths using remix-flat-routes.
+*/
+async function scanAPIRoutes(container) {
+	const fullPath = resolve(APPOS_DIR, ROUTES_DIR);
+	try {
+		await access(fullPath);
+	} catch (error) {
+		container.logger.error({ error }, "OpenAPI routes directory not found");
+		return [];
+	}
+	const routeManifest = await remixRoutesOptionAdapter((defineRoutes) => {
+		return flatRoutes(ROUTES_DIR, defineRoutes, {
+			appDir: APPOS_DIR,
+			ignoredRouteFiles: [
+				"**/.*",
+				"**/*.{spec,test}.{ts,tsx}",
+				"**/*-????????.{js,ts}"
+			]
+		});
+	});
+	const routes = [];
+	for (const [routeId, route] of Object.entries(routeManifest)) {
+		const absolutePath = resolve(APPOS_DIR, route.file).replace(/\.ts$/, `.${FILE_EXT}`);
+		try {
+			const exported = (await import(absolutePath)).default;
+			if (!exported || isEmpty(exported) || /\/openapi.(j|t)s$/.test(absolutePath)) continue;
+			if (!exported?.handlers && !exported?.openAPISpec) {
+				container.logger.warn(`Missing default export with 'defineOpenAPI' for '${APPOS_DIR}/${route.file}'`);
+				continue;
+			}
+			const routePath = `/${route.path}`;
+			routes.push({
+				path: routePath,
+				filePath: absolutePath,
+				handlers: exported.handlers,
+				openAPISpec: exported.openAPISpec,
+				version: extractVersion(routePath)
+			});
+		} catch (error) {
+			container.logger.error(error, `Error loading route ${route.file}:`);
+		}
+	}
+	return routes;
+}
+/**
+* Register scanned routes with Express app.
+*/
+function registerRoutes(app, routes) {
+	for (const route of routes) for (const [method, handler] of Object.entries(route.handlers)) app[method.toLowerCase()](route.path, handler);
+}
+/**
+* Load version-specific OpenAPI config from openapi.ts file.
+*/
+async function loadVersionConfig(container, version) {
+	const configPath = resolve(APPOS_DIR, ROUTES_DIR, `${version}+/openapi.${FILE_EXT}`);
+	try {
+		const configFn = (await import(configPath)).default;
+		return configFn ? configFn(container) : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Write OpenAPI specs to api/public/openapi directory.
+*/
+async function writeOpenAPISpecs(container, routes) {
+	const versions = [...new Set(routes.map((r) => r.version).filter(Boolean))];
+	if (versions.length > 0) await mkdir(outputDir, { recursive: true });
+	for (const version of versions) {
+		const doc = generateOpenAPIDocument(routes, version, await loadVersionConfig(container, version));
+		await writeFile(join(outputDir, `${version}.json`), JSON.stringify(doc, null, 2), "utf-8");
+	}
+}
+/**
+* Load and register API routes with Express (convenience function).
+* Also auto-generates OpenAPI specs in development mode.
+*/
+async function loadAndRegisterAPIRoutes(app) {
+	const routes = await scanAPIRoutes(app.locals.container);
+	registerRoutes(app, routes);
+	if (process.env.NODE_ENV !== "production") await writeOpenAPISpecs(app.locals.container, routes);
+}
+
+//#endregion
+export { defineOpenAPI, defineOpenAPIConfig, defineOpenAPIEndpoint, defineTypedResponses, generateOpenAPIDocument, loadAndRegisterAPIRoutes, registerRoutes, scanAPIRoutes, writeOpenAPISpecs };

package/dist/exports/api/orm.mjs

@@ -1 +1,43 @@
-import{__export as e,__reExport as t}from"./_virtual/rolldown_runtime.mjs";import{index as n,isPgEnum as r,isPgMaterializedView as i,isPgSchema as a,isPgSequence as o,isPgView as s,numeric as c,parsePgArray as l,parsePgNestedArray as u,pgEnum as d,pgMaterializedView as f,pgPolicy as p,pgRole as m,pgSchema as h,pgSequence as g,pgTable as _,pgTableCreator as v,pgView as y,serial as b,smallint as x,smallserial as S,sparsevec as C,unique as w,uniqueIndex as T,uniqueKeyName as E,withReplicas as D}from"drizzle-orm/pg-core";export*from"drizzle-orm";export*from"drizzle-seed";var O=e({index:()=>n,isPgEnum:()=>r,isPgMaterializedView:()=>i,isPgSchema:()=>a,isPgSequence:()=>o,isPgView:()=>s,numeric:()=>c,parsePgArray:()=>l,parsePgNestedArray:()=>u,pgEnum:()=>d,pgMaterializedView:()=>f,pgPolicy:()=>p,pgRole:()=>m,pgSchema:()=>h,pgSequence:()=>g,pgTable:()=>_,pgTableCreator:()=>v,pgView:()=>y,serial:()=>b,smallint:()=>x,smallserial:()=>S,sparsevec:()=>C,unique:()=>w,uniqueIndex:()=>T,uniqueKeyName:()=>E,withReplicas:()=>D});import*as k from"drizzle-orm";t(O,k);import*as A from"drizzle-seed";t(O,A);export{n as index,r as isPgEnum,i as isPgMaterializedView,a as isPgSchema,o as isPgSequence,s as isPgView,c as numeric,O as orm_exports,l as parsePgArray,u as parsePgNestedArray,d as pgEnum,f as pgMaterializedView,p as pgPolicy,m as pgRole,h as pgSchema,g as pgSequence,_ as pgTable,v as pgTableCreator,y as pgView,b as serial,x as smallint,S as smallserial,C as sparsevec,w as unique,T as uniqueIndex,E as uniqueKeyName,D as withReplicas};
+import { __export, __reExport } from "./_virtual/rolldown_runtime.mjs";
+import { index, isPgEnum, isPgMaterializedView, isPgSchema, isPgSequence, isPgView, numeric, parsePgArray, parsePgNestedArray, pgEnum, pgMaterializedView, pgPolicy, pgRole, pgSchema, pgSequence, pgTable, pgTableCreator, pgView, serial, smallint, smallserial, sparsevec, unique, uniqueIndex, uniqueKeyName, withReplicas } from "drizzle-orm/pg-core";
+
+export * from "drizzle-orm"
+
+export * from "drizzle-seed"
+
+//#region src/api/orm.ts
+var orm_exports = /* @__PURE__ */ __export({
+	index: () => index,
+	isPgEnum: () => isPgEnum,
+	isPgMaterializedView: () => isPgMaterializedView,
+	isPgSchema: () => isPgSchema,
+	isPgSequence: () => isPgSequence,
+	isPgView: () => isPgView,
+	numeric: () => numeric,
+	parsePgArray: () => parsePgArray,
+	parsePgNestedArray: () => parsePgNestedArray,
+	pgEnum: () => pgEnum,
+	pgMaterializedView: () => pgMaterializedView,
+	pgPolicy: () => pgPolicy,
+	pgRole: () => pgRole,
+	pgSchema: () => pgSchema,
+	pgSequence: () => pgSequence,
+	pgTable: () => pgTable,
+	pgTableCreator: () => pgTableCreator,
+	pgView: () => pgView,
+	serial: () => serial,
+	smallint: () => smallint,
+	smallserial: () => smallserial,
+	sparsevec: () => sparsevec,
+	unique: () => unique,
+	uniqueIndex: () => uniqueIndex,
+	uniqueKeyName: () => uniqueKeyName,
+	withReplicas: () => withReplicas
+});
+import * as import_drizzle_orm from "drizzle-orm";
+__reExport(orm_exports, import_drizzle_orm);
+import * as import_drizzle_seed from "drizzle-seed";
+__reExport(orm_exports, import_drizzle_seed);
+
+//#endregion
+export { index, isPgEnum, isPgMaterializedView, isPgSchema, isPgSequence, isPgView, numeric, orm_exports, parsePgArray, parsePgNestedArray, pgEnum, pgMaterializedView, pgPolicy, pgRole, pgSchema, pgSequence, pgTable, pgTableCreator, pgView, serial, smallint, smallserial, sparsevec, unique, uniqueIndex, uniqueKeyName, withReplicas };

package/dist/exports/api/otel.mjs

@@ -1 +1,56 @@
-import{instrumentation_exports as e}from"./instrumentation.mjs";import{getCallSites as t}from"node:util";async function n(n,r){let i=t()[1],a=i.scriptName.replace(process.cwd(),``).replace(`file:///`,``),o=i.functionName,s=e.trace.getTracer(a.replace(`build/`,``)).startSpan(o,{attributes:r}),c=e.trace.setSpan(e.context.active(),s);try{let t=await e.context.with(c,()=>n(s));return s.end(),t}catch(e){throw s.recordException(e),s.end(),e}}export{n as withOtelSpan};
+import { instrumentation_exports } from "./instrumentation.mjs";
+import { getCallSites } from "node:util";
+
+//#region src/api/otel.ts
+/**
+* Wraps an async function with an OpenTelemetry span for distributed tracing.
+*
+* Automatically handles span lifecycle (start/end), error recording, and context propagation.
+* The span will appear as a child of the currently active span (if any).
+*
+* @param tracerName - Fully qualified module path (e.g., "api/routes/payouts", "packages/primitives/mailer")
+* @param spanName - Operation name following {verb} {object} pattern (e.g., "fetch payouts", "send email")
+* @param fn - The async function to execute within the span context. Receives span for custom attributes.
+* @param attributes - Optional span attributes for high-cardinality data (IDs, counts, etc.).
+*                     Use semantic conventions: https://opentelemetry.io/docs/specs/semconv/
+* @returns Promise resolving to the function's return value.
+*
+* @example
+* // Basic usage - simple business operation
+* await withOtelSpan("api/routes/payouts", "fetch payouts", async () => {
+*   return await db.query.payouts.findMany();
+* });
+*
+* @example
+* // With attributes and custom span data
+* const payouts = await withOtelSpan(
+*   "api/routes/payouts",
+*   "fetch payouts",
+*   async (span) => {
+*     const results = await db.query.payouts.findMany();
+*     span.setAttribute("payouts.count", results.length);
+*     span.addEvent("cache.miss");
+*     return results;
+*   },
+*   { "payouts.limit": 100, "payouts.offset": 0 }
+* );
+*/
+async function withOtelSpan(fn, attributes) {
+	const callSite = getCallSites()[1];
+	const tracerName = callSite.scriptName.replace(process.cwd(), "").replace("file:///", "");
+	const spanName = callSite.functionName;
+	const span = instrumentation_exports.trace.getTracer(tracerName.replace("build/", "")).startSpan(spanName, { attributes });
+	const ctx = instrumentation_exports.trace.setSpan(instrumentation_exports.context.active(), span);
+	try {
+		const result = await instrumentation_exports.context.with(ctx, () => fn(span));
+		span.end();
+		return result;
+	} catch (error) {
+		span.recordException(error);
+		span.end();
+		throw error;
+	}
+}
+
+//#endregion
+export { withOtelSpan };

package/dist/exports/api/redis.mjs

@@ -1 +1,41 @@
-import{createClient as e,createCluster as t}from"redis";function n(n){let r=n.url.split(`,`).map(e=>e.trim()).filter(Boolean),i;i=r.length===1?e({url:r[0]}):t({rootNodes:r.map(e=>({url:e}))}),i.on(`error`,e=>n.logger.error({err:e},`Redis error`));let a=null,o=async()=>{i.isOpen||(a??=i.connect(),await a)};return new Proxy(i,{get(e,t,n){let r=Reflect.get(e,t,n);return typeof r==`function`&&t!==`on`&&t!==`once`?async(...t)=>(await o(),r.apply(e,t)):r}})}export{n as defineRedisClient};
+import { createClient, createCluster } from "redis";
+
+//#region src/api/redis.ts
+/**
+* Defines Redis client based on URL format with lazy connection.
+* Single URL → createClient(), comma-separated URLs → createCluster()
+*
+* Algorithm:
+* 1. Split URL by comma to detect cluster vs single
+* 2. Create appropriate client type
+* 3. Attach error handler with label for debugging
+* 4. Wrap in proxy that auto-connects on first use
+*
+* @param opts Options for defining the Redis client.
+* @returns Redis client that auto-connects on first operation.
+*/
+function defineRedisClient(opts) {
+	const urls = opts.url.split(",").map((u) => u.trim()).filter(Boolean);
+	let client;
+	if (urls.length === 1) client = createClient({ url: urls[0] });
+	else client = createCluster({ rootNodes: urls.map((u) => ({ url: u })) });
+	client.on("error", (err) => opts.logger.error({ err }, "Redis error"));
+	let connectPromise = null;
+	const ensureConnected = async () => {
+		if (!client.isOpen) {
+			connectPromise ??= client.connect();
+			await connectPromise;
+		}
+	};
+	return new Proxy(client, { get(target, prop, receiver) {
+		const value = Reflect.get(target, prop, receiver);
+		if (typeof value === "function" && prop !== "on" && prop !== "once") return async (...args) => {
+			await ensureConnected();
+			return value.apply(target, args);
+		};
+		return value;
+	} });
+}
+
+//#endregion
+export { defineRedisClient };