@voltro/plugin-openapi 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+import { ProcedureDescriptor } from '@voltro/protocol';
+import { RestRouteDescriptor } from '@voltro/protocol/rest';
+import { VoltroPlugin } from '@voltro/protocol';
+
+/**
+ * Build the full OpenAPI 3.1 document from a list of REST descriptors and,
+ * optionally, the rpc procedure descriptors.
+ *
+ * Overloads keep the original `(routes, info)` shape working while adding the
+ * `(routes, info, sources)` form that folds in rpc procedures.
+ */
+export declare function generateOpenApiSpec(routes: ReadonlyArray<RestRouteDescriptor<any, any>>, info?: OpenApiInfo): OpenApiDocument;
+
+export declare function generateOpenApiSpec(routes: ReadonlyArray<RestRouteDescriptor<any, any>>, info: OpenApiInfo, sources: OpenApiSources): OpenApiDocument;
+
+/** A minimal OpenAPI 3.1 document — the shape `generateOpenApiSpec` returns.
+ *  Deliberately narrow: it names the top-level keys a consumer reads (so the
+ *  public `.d.ts` documents the contract) while leaving the per-operation
+ *  `paths` / `components.schemas` values open — those are full OpenAPI objects
+ *  the JSON-Schema converter assembles, not worth re-typing here. */
+export declare interface OpenApiDocument {
+    readonly openapi: '3.1.0';
+    readonly info: {
+        readonly title: string;
+        readonly version: string;
+        readonly description?: string;
+    };
+    readonly paths: Record<string, Record<string, unknown>>;
+    readonly components: {
+        readonly schemas: Record<string, unknown>;
+        readonly securitySchemes?: Record<string, unknown>;
+    };
+}
+
+export declare interface OpenApiInfo {
+    readonly title?: string;
+    readonly version?: string;
+    readonly description?: string;
+}
+
+export declare const openapiPlugin: (options: OpenApiPluginOptions) => VoltroPlugin;
+
+export declare interface OpenApiPluginOptions {
+    /** The REST descriptors to document (the same array you pass to `restRoutes`).
+     *  Optional — a spec of ONLY rpc procedures is valid (pass `procedures`). */
+    readonly routes?: ReadonlyArray<RestRouteDescriptor<any, any>>;
+    /**
+     * rpc procedure descriptors to project into the spec — the queries /
+     * mutations / actions / streams your app defines. Each becomes a
+     * `POST /rpc/<name>` operation. Opt-in: omit to keep the spec REST-only.
+     * (Mixing rpc + REST in one spec is fine — the rpc ops are tagged `rpc` and
+     * flagged `x-voltro-rpc` so consumers can tell them apart.)
+     */
+    readonly procedures?: ReadonlyArray<ProcedureDescriptor>;
+    /** Spec metadata. */
+    readonly info?: OpenApiInfo;
+    /** Path to serve the JSON spec. Default `/openapi.json`. */
+    readonly specPath?: string;
+    /** Path to serve the Swagger-UI page. Default `/docs`. `false` disables it. */
+    readonly docsPath?: string | false;
+    /**
+     * Require `Authorization: Bearer <token>` on BOTH the spec and the docs
+     * route. Default `OPENAPI_DOCS_TOKEN` env; unset → open (the spec/docs are
+     * public — gate at the network layer, or set this for a public deployment).
+     */
+    readonly token?: string;
+    readonly name?: string;
+}
+
+/** Extra sources to fold into the spec beyond the REST `routes`. Today: the
+ *  rpc procedure descriptors (queries / mutations / actions / streams). */
+export declare interface OpenApiSources {
+    /** rpc procedure descriptors to project into the spec. Each becomes a POST
+     *  operation under `/rpc/<name>` (see `rpc.ts`). Opt-in — omit to keep the
+     *  spec REST-only. */
+    readonly procedures?: ReadonlyArray<ProcedureDescriptor>;
+}
+
+export declare const swaggerUiHtml: (specUrl: string, title?: string) => string;
+
+export { }

package/dist/index.js

@@ -0,0 +1,237 @@
+import { Effect as e, JSONSchema as t } from "effect";
+import { definePlugin as n } from "@voltro/protocol";
+import { pluginEnv as r } from "@voltro/env";
+//#region src/rpc.ts
+var i = "/rpc", a = "rpc", o = (e) => e.ast._tag === "NeverKeyword", s = (e, t) => `${e} ${t}`, c = (e) => `Voltro rpc ${e}. This \`/rpc/<name>\` path is a documentation projection of the procedure's input/output schemas — live calls go through ${e === "query" || e === "stream" ? "the batched `POST /rpc` endpoint (first snapshot / element) or the WebSocket rpc channel (reactive/streaming)" : "the batched `POST /rpc` endpoint"}, NOT a REST request to this path. The request body below is the rpc payload.`, l = (e, t) => {
+	let { kind: n, name: r } = e, i = {
+		required: !0,
+		content: { "application/json": { schema: f(e.input, t) } }
+	}, l = (() => {
+		if (n === "stream") return {
+			description: "Stream of elements. The rpc transport pushes each element as it is produced (WebSocket) or drains to the first element over `POST /rpc`. The schema below is ONE element, not the whole response.",
+			content: { "application/x-ndjson": { schema: f(e.element, t) } }
+		};
+		let r = f(e.output, t);
+		return {
+			description: n === "query" ? "OK — the query snapshot (the first/initial snapshot over `POST /rpc`; the WebSocket channel then pushes reactive updates)." : "OK",
+			content: { "application/json": { schema: r } }
+		};
+	})(), u = o(e.error) ? {} : { 422: {
+		description: "A typed error from the procedure — one of its declared error variants (the rpc failure channel).",
+		content: { "application/json": { schema: f(e.error, t) } }
+	} };
+	return {
+		tags: [a],
+		summary: s(n, r),
+		description: c(n),
+		"x-voltro-rpc": {
+			kind: n,
+			procedure: r
+		},
+		requestBody: i,
+		responses: {
+			200: l,
+			...u,
+			500: _("Internal Server Error — an untyped defect.")
+		}
+	};
+}, u = (e, t) => {
+	let n = {};
+	for (let r of e) {
+		let e = `${i}/${r.name}`;
+		n[e] = { post: l(r, t) };
+	}
+	return n;
+}, d = (e) => e.replace(/:([A-Za-z0-9_]+)/g, "{$1}"), f = (e, n) => {
+	let { $schema: r, $defs: i, ...a } = t.make(e);
+	if (i && typeof i == "object") for (let [e, t] of Object.entries(i)) n[e] = t;
+	return a;
+}, p = (e) => {
+	if (Array.isArray(e)) return e.map(p);
+	if (e && typeof e == "object") {
+		let t = {};
+		for (let [n, r] of Object.entries(e)) t[n] = n === "$ref" && typeof r == "string" && r.startsWith("#/$defs/") ? `#/components/schemas/${r.slice(8)}` : p(r);
+		return t;
+	}
+	return e;
+}, m = (e, t) => {
+	if (!e) return {
+		parameters: [],
+		requestBody: void 0
+	};
+	let n = f(e, t), r = n.properties ?? {}, i = new Set(n.required ?? []), a = [];
+	for (let [e, t] of [["query", "query"], ["params", "path"]]) {
+		let n = r[e];
+		if (!n || typeof n != "object") continue;
+		let i = n.properties ?? {}, o = new Set(n.required ?? []);
+		for (let [e, n] of Object.entries(i)) a.push({
+			name: e,
+			in: t,
+			required: t === "path" || o.has(e),
+			schema: n
+		});
+	}
+	let o = r.body;
+	return {
+		parameters: a,
+		requestBody: o && typeof o == "object" ? {
+			required: i.has("body"),
+			content: { "application/json": { schema: o } }
+		} : void 0
+	};
+}, h = "VoltroHttpError", g = {
+	type: "object",
+	description: "The serve pipeline's error envelope.",
+	properties: {
+		error: {
+			type: "string",
+			description: "Human-readable error message."
+		},
+		detail: {
+			type: "string",
+			description: "Decode failure detail (400 only)."
+		},
+		replacement: {
+			type: "string",
+			description: "Replacement endpoint hint (410 only)."
+		}
+	},
+	required: ["error"]
+}, _ = (e) => ({
+	description: e,
+	content: { "application/json": { schema: { $ref: `#/components/schemas/${h}` } } }
+}), v = (e) => ({
+	...e.input === void 0 ? {} : { 400: _("Invalid request — the input failed schema decode.") },
+	...e.guards !== void 0 && e.guards.length > 0 ? {
+		401: _("Unauthorized — a guard rejected the unauthenticated request."),
+		403: _("Forbidden — a guard rejected the request (e.g. a required scope is missing).")
+	} : {},
+	...e.sunset === void 0 ? {} : { 410: _(`Gone — the route is past its sunset date (${e.sunset}).`) },
+	500: _("Internal Server Error.")
+});
+function y(e, t = {}, n = {}) {
+	let r = {}, i = {}, a = e.some((e) => e.guards !== void 0 && e.guards.length > 0);
+	for (let t of e) {
+		let { parameters: e, requestBody: n } = m(t.input, i), a = t.guards !== void 0 && t.guards.length > 0;
+		if (n !== void 0 && t.example?.request !== void 0) {
+			let e = n.content;
+			e["application/json"] = {
+				...e["application/json"],
+				example: t.example.request
+			};
+		}
+		let o = {
+			...t.summary ? { summary: t.summary } : {},
+			...t.description ? { description: t.description } : {},
+			...t.deprecated === void 0 ? {} : { deprecated: !0 },
+			...t.sunset === void 0 ? {} : { "x-sunset": t.sunset },
+			...e.length > 0 ? { parameters: e } : {},
+			...n ? { requestBody: n } : {},
+			...a ? { security: [{ bearerAuth: [] }] } : {},
+			responses: {
+				200: {
+					description: "OK",
+					content: { "application/json": {
+						schema: f(t.output, i),
+						...t.example?.response === void 0 ? {} : { example: t.example.response }
+					} }
+				},
+				...v(t)
+			}
+		}, s = d(t.path), c = r[s] ?? {};
+		c[t.method.toLowerCase()] = o, r[s] = c;
+	}
+	let o = n.procedures ?? [];
+	if (o.length > 0) {
+		let e = u(o, i);
+		for (let [t, n] of Object.entries(e)) r[t] = {
+			...n,
+			...r[t] ?? {}
+		};
+	}
+	return {
+		openapi: "3.1.0",
+		info: {
+			title: t.title ?? "API",
+			version: t.version ?? "1.0.0",
+			...t.description ? { description: t.description } : {}
+		},
+		paths: p(r),
+		components: {
+			schemas: {
+				...p(i),
+				[h]: g
+			},
+			...a ? { securitySchemes: { bearerAuth: {
+				type: "http",
+				scheme: "bearer"
+			} } } : {}
+		}
+	};
+}
+//#endregion
+//#region src/swaggerUi.ts
+var b = "5.17.14", x = "sha384-wxLW6kwyHktdDGr6Pv1zgm/VGJh99lfUbzSn6HNHBENZlCN7W602k9VkGdxuFvPn", S = "sha384-wmyclcVGX/WhUkdkATwhaK1X1JtiNrr2EoYJ+diV3vj4v6OC5yCeSu+yW13SYJep", C = `https://unpkg.com/swagger-ui-dist@${b}/swagger-ui.css`, w = `https://unpkg.com/swagger-ui-dist@${b}/swagger-ui-bundle.js`, T = (e, t = "API docs") => `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${t}</title>
+  <link rel="stylesheet" href="${C}" integrity="${x}" crossorigin="anonymous" />
+  <style>body { margin: 0 }</style>
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="${w}" integrity="${S}" crossorigin="anonymous"><\/script>
+  <script>
+    window.ui = SwaggerUIBundle({ url: ${JSON.stringify(e)}, dom_id: '#swagger-ui', deepLinking: true });
+  <\/script>
+</body>
+</html>`, E = r([{
+	name: "OPENAPI_DOCS_TOKEN",
+	required: !1,
+	secret: !0,
+	description: "Bearer token required on GET /openapi.json + GET /docs; unset leaves them public."
+}]), D = (e, t) => {
+	if (e) return (t.headers.authorization ?? t.headers.Authorization) === `Bearer ${e}` ? void 0 : {
+		status: 401,
+		body: "unauthorized",
+		contentType: "text/plain"
+	};
+}, O = (t) => {
+	let r = t.specPath ?? "/openapi.json", i = t.docsPath ?? "/docs", a = E.read("OPENAPI_DOCS_TOKEN", t.token), o = t.name ? `@voltro/plugin-openapi#${t.name}` : "@voltro/plugin-openapi", s = t.routes ?? [], c = t.procedures ?? [], l = JSON.stringify(y(s, t.info ?? {}, { procedures: c }), null, 2), u = [{
+		method: "GET",
+		path: r,
+		handle: async (e) => D(a, e) ?? {
+			status: 200,
+			body: l,
+			contentType: "application/json"
+		}
+	}];
+	return i !== !1 && u.push({
+		method: "GET",
+		path: i,
+		handle: async (e) => D(a, e) ?? {
+			status: 200,
+			body: T(r, t.info?.title ?? "API docs"),
+			contentType: "text/html; charset=utf-8"
+		}
+	}), n({
+		name: o,
+		description: "OpenAPI 3.1 spec + Swagger-UI docs from defineRestRoute descriptors + rpc procedures.",
+		permissions: [],
+		declaredEnv: E.declared,
+		httpRoutes: u,
+		onActivate: (t) => e.sync(() => {
+			t.logger.info("openapi docs active", {
+				specPath: r,
+				docsPath: i,
+				routes: s.length,
+				procedures: c.length,
+				tokenGated: !!a
+			});
+		})
+	});
+};
+//#endregion
+export { y as generateOpenApiSpec, O as openapiPlugin, T as swaggerUiHtml };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@voltro/plugin-openapi",
+  "version": "0.1.0",
+  "description": "Generate an OpenAPI 3.1 spec from defineRestRoute descriptors and serve it + a Swagger-UI docs page. Zero hand-maintained API docs — the REST descriptors ARE the source of truth.",
+  "keywords": [
+    "voltro",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@voltro/env": "0.1.0",
+    "@voltro/protocol": "0.1.0"
+  },
+  "peerDependencies": {
+    "effect": "^3.21.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}