@voltro/plugin-openapi 0.69.1 → 0.71.0

package/dist/index.js

@@ -1,65 +1,66 @@
 import { Effect as e, JSONSchema as t } from "effect";
 import { definePlugin as n } from "@voltro/protocol";
 import { pluginEnv as r } from "@voltro/env";
+import { publicSurfaceDigest as i } from "@voltro/protocol/rest";
 //#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) => {
+var a = "/rpc", o = "rpc", s = (e) => e.ast._tag === "NeverKeyword", c = (e, t) => `${e} ${t}`, l = (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.`, u = (e, t) => {
 	let { kind: n, name: r } = e, i = {
 		required: !0,
-		content: { "application/json": { schema: f(e.input, t) } }
-	}, l = (() => {
+		content: { "application/json": { schema: p(e.input, t) } }
+	}, a = (() => {
 		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) } }
+			content: { "application/x-ndjson": { schema: p(e.element, t) } }
 		};
-		let r = f(e.output, t);
+		let r = p(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: {
+	})(), u = s(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) } }
+		content: { "application/json": { schema: p(e.error, t) } }
 	} };
 	return {
-		tags: [a],
-		summary: s(n, r),
-		description: c(n),
+		tags: [o],
+		summary: c(n, r),
+		description: l(n),
 		"x-voltro-rpc": {
 			kind: n,
 			procedure: r
 		},
 		requestBody: i,
 		responses: {
-			200: l,
+			200: a,
 			...u,
-			500: _("Internal Server Error — an untyped defect.")
+			500: v("Internal Server Error — an untyped defect.")
 		}
 	};
-}, u = (e, t) => {
+}, d = (e, t) => {
 	let n = {};
 	for (let r of e) {
-		let e = `${i}/${r.name}`;
-		n[e] = { post: l(r, t) };
+		let e = `${a}/${r.name}`;
+		n[e] = { post: u(r, t) };
 	}
 	return n;
-}, d = (e) => e.replace(/:([A-Za-z0-9_]+)/g, "{$1}"), f = (e, n) => {
+}, f = (e) => e.replace(/:([A-Za-z0-9_]+)/g, "{$1}"), p = (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);
+}, m = (e) => {
+	if (Array.isArray(e)) return e.map(m);
 	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);
+		for (let [n, r] of Object.entries(e)) t[n] = n === "$ref" && typeof r == "string" && r.startsWith("#/$defs/") ? `#/components/schemas/${r.slice(8)}` : m(r);
 		return t;
 	}
 	return e;
-}, m = (e, t) => {
+}, h = (e, t) => {
 	if (!e) return {
 		parameters: [],
 		requestBody: void 0
 	};
-	let n = f(e, t), r = n.properties ?? {}, i = new Set(n.required ?? []), a = [];
+	let n = p(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;
@@ -79,7 +80,7 @@ var i = "/rpc", a = "rpc", o = (e) => e.ast._tag === "NeverKeyword", s = (e, t)
 			content: { "application/json": { schema: o } }
 		} : void 0
 	};
-}, h = "VoltroHttpError", g = {
+}, g = "VoltroHttpError", _ = {
 	type: "object",
 	description: "The serve pipeline's error envelope.",
 	properties: {
@@ -97,79 +98,351 @@ var i = "/rpc", a = "rpc", o = (e) => e.ast._tag === "NeverKeyword", s = (e, t)
 		}
 	},
 	required: ["error"]
-}, _ = (e) => ({
+}, v = (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.") },
+	content: { "application/json": { schema: { $ref: `#/components/schemas/${g}` } } }
+}), y = "ProblemDetails", b = {
+	type: "object",
+	description: "RFC 9457 Problem Details. Extension members carry the error's own fields.",
+	properties: {
+		type: {
+			type: "string",
+			format: "uri",
+			description: "The error type — `urn:voltro:error:<Tag>`."
+		},
+		title: { type: "string" },
+		status: { type: "integer" },
+		detail: { type: "string" }
+	},
+	required: [
+		"type",
+		"title",
+		"status"
+	],
+	additionalProperties: !0
+}, x = (e, t, n = 0) => {
+	if (n > 6) return null;
+	let r = e.$ref;
+	if (typeof r == "string") {
+		let e = t[r.split("/").pop() ?? ""];
+		return e !== void 0 && typeof e == "object" ? x(e, t, n + 1) : null;
+	}
+	if (e.example !== void 0) return e.example;
+	if (Array.isArray(e.examples) && e.examples.length > 0) return e.examples[0];
+	if (e.const !== void 0) return e.const;
+	if (Array.isArray(e.enum) && e.enum.length > 0) return e.enum[0];
+	let i = e.anyOf ?? e.oneOf;
+	if (Array.isArray(i) && i.length > 0) return x(i.find((e) => e.type !== "null") ?? i[0], t, n + 1);
+	let a = e.allOf;
+	if (Array.isArray(a) && a.length > 0) {
+		let e = a.map((e) => x(e, t, n + 1));
+		return e.every((e) => typeof e == "object" && !!e && !Array.isArray(e)) ? Object.assign({}, ...e) : e[0];
+	}
+	let o = e.type;
+	switch (Array.isArray(o) ? o.find((e) => e !== "null") : o) {
+		case "string": {
+			let t = e.format;
+			if (t === "date-time") return "2026-01-01T00:00:00.000Z";
+			if (t === "date") return "2026-01-01";
+			if (t === "email") return "user@example.com";
+			if (t === "uri" || t === "url") return "https://example.com";
+			if (t === "uuid") return "00000000-0000-4000-8000-000000000000";
+			let n = typeof e.minLength == "number" ? e.minLength : 0;
+			return "string".padEnd(Math.max(n, 6), "x");
+		}
+		case "integer": return typeof e.minimum == "number" ? e.minimum : 1;
+		case "number": return typeof e.minimum == "number" ? e.minimum : 1;
+		case "boolean": return !0;
+		case "null": return null;
+		case "array": {
+			let r = e.items;
+			return r !== void 0 && typeof r == "object" && !Array.isArray(r) ? [x(r, t, n + 1)] : [];
+		}
+		case "object": {
+			let r = e.properties ?? {}, i = {};
+			for (let [e, a] of Object.entries(r)) i[e] = x(a, t, n + 1);
+			return i;
+		}
+		default: return typeof e.properties == "object" ? x({
+			...e,
+			type: "object"
+		}, t, n) : null;
+	}
+}, S = {
+	400: {
+		tag: "InvalidRequest",
+		detail: "Invalid request"
+	},
+	401: {
+		tag: "Unauthorized",
+		detail: "Authentication required"
+	},
+	403: {
+		tag: "Forbidden",
+		detail: "Missing required scope: <scope>"
+	},
+	410: {
+		tag: "Gone",
+		detail: "Gone"
+	},
+	500: {
+		tag: "InternalServerError",
+		detail: "Internal Server Error"
+	}
+}, C = {
+	400: "Bad Request",
+	401: "Unauthorized",
+	403: "Forbidden",
+	404: "Not Found",
+	409: "Conflict",
+	410: "Gone",
+	422: "Unprocessable Content",
+	429: "Too Many Requests",
+	500: "Internal Server Error"
+}, w = (e, t, n) => {
+	let r = t.format.errors === "problem-details" && t.format.encodeError === void 0, i = r ? "application/problem+json" : "application/json", a = /* @__PURE__ */ new Map();
+	for (let e of t.errorResponses) {
+		let t = a.get(e.status) ?? [], i = p(e.schema, n), o = x(i, n), { _tag: s, ...c } = typeof o == "object" && o ? o : {}, l = r ? {
+			type: `urn:voltro:error:${e.tag}`,
+			title: e.tag.replace(/([a-z0-9])([A-Z])/g, "$1 $2"),
+			status: e.status,
+			...c
+		} : {
+			error: e.tag,
+			...c
+		};
+		t.push({
+			tag: e.tag,
+			example: l,
+			schema: r ? { allOf: [{ $ref: `#/components/schemas/${y}` }, {
+				type: "object",
+				properties: { type: { const: `urn:voltro:error:${e.tag}` } }
+			}] } : i
+		}), a.set(e.status, t);
+	}
+	let o = (e, t) => {
+		if (!r) return v(t);
+		let n = S[e], a = n === void 0 ? {} : { example: {
+			type: `urn:voltro:error:${n.tag}`,
+			title: n.tag.replace(/([a-z])([A-Z])/g, "$1 $2"),
+			status: e,
+			detail: n.detail
+		} };
+		return {
+			description: t,
+			content: { [i]: {
+				schema: { $ref: `#/components/schemas/${y}` },
+				...a
+			} }
+		};
+	}, s = {};
+	s[400] = o(400, "Invalid request — the input failed schema decode."), t.security !== "none" && (s[401] = o(401, "Unauthorized — no valid bearer.")), (t.security === "required" || (e.guards?.length ?? 0) > 0) && (s[403] = o(403, "Forbidden — the caller lacks a required scope."));
+	for (let [e, t] of [...a.entries()].sort((e, t) => e[0] - t[0])) {
+		let n = t.map((e) => e.tag);
+		s[String(e)] = {
+			description: `${C[e] ?? "Error"} — ${n.join(" | ")}`,
+			content: { [i]: {
+				schema: t.length === 1 ? t[0].schema : { oneOf: t.map((e) => e.schema) },
+				example: t[0].example
+			} }
+		};
+	}
+	return e.sunset !== void 0 && (s[410] = o(410, `Gone — the route is past its sunset date (${e.sunset}).`)), s[500] = o(500, "Internal Server Error."), s;
+}, T = (e, t, n) => {
+	let r = p(t.input, n), i = r.properties ?? {}, a = new Set(r.required ?? []), o = new Set(t.pathParams), s = [], c = {}, l = [], u = e.example?.request, d = (e) => typeof u == "object" && u && e in u ? { example: u[e] } : {};
+	for (let [t, n] of Object.entries(i)) o.has(t) ? s.push({
+		name: t,
+		in: "path",
+		required: !0,
+		schema: n,
+		...d(t)
+	}) : e.method === "GET" ? s.push({
+		name: t,
+		in: "query",
+		required: a.has(t),
+		schema: n,
+		...d(t)
+	}) : (c[t] = n, a.has(t) && l.push(t));
+	return {
+		parameters: s,
+		requestBody: e.method !== "GET" && Object.keys(c).length > 0 ? {
+			required: l.length > 0,
+			content: {
+				"application/json": { schema: {
+					...r,
+					properties: c,
+					required: l
+				} },
+				"application/x-www-form-urlencoded": { schema: {
+					...r,
+					properties: c,
+					required: l
+				} }
+			}
+		} : void 0
+	};
+}, E = (e, t, n) => {
+	if (e.streaming === !0) return {
+		description: "Server-Sent Events stream (`snapshot`, then `delta` per change)",
+		content: { "text/event-stream": { schema: { type: "string" } } }
+	};
+	let r = p(t.output, n), i = t.format, a = i.pagination === "link-header" && D(r, n, i.cursorField), o = i.encodeSuccess === void 0 ? i.envelope === "data" ? {
+		type: "object",
+		properties: {
+			data: r,
+			...a ? { next: {
+				type: "string",
+				description: "The next page's cursor, when there is one."
+			} } : {}
+		},
+		required: ["data"]
+	} : i.envelope === "jsonapi" ? {
+		type: "object",
+		properties: {
+			data: { description: "One resource or an array of resources — `{ type, id, attributes }`." },
+			links: {
+				type: "object",
+				properties: { next: { type: "string" } }
+			}
+		},
+		required: ["data"]
+	} : r : { description: `Encoded by the '${i.name}' format.` }, s = i.envelope === "jsonapi" ? "application/vnd.api+json" : "application/json", c = {
+		...a ? { Link: {
+			description: "RFC 8288 — `<url>; rel=\"next\"` when there is a next page.",
+			schema: { type: "string" }
+		} } : {},
+		...e.etag === !0 ? { ETag: {
+			description: "Weak validator; send it back as `If-None-Match` for a 304.",
+			schema: { type: "string" }
+		} } : {}
+	};
+	return {
+		description: "OK",
+		...Object.keys(c).length > 0 ? { headers: c } : {},
+		content: { [s]: {
+			schema: o,
+			...O(e.example?.response, o, n)
+		} }
+	};
+}, D = (e, t, n) => {
+	let r = e.$ref, i = (typeof r == "string" ? t[r.split("/").pop() ?? ""] : e)?.properties;
+	return typeof i == "object" && !!i && n in i;
+}, O = (e, t, n) => e === void 0 ? {
+	example: x(t, n),
+	"x-voltro-example": "derived"
+} : { example: e }, k = (e) => ({
+	...e.input === void 0 ? {} : { 400: v("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).")
+		401: v("Unauthorized — a guard rejected the unauthenticated request."),
+		403: v("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.")
+	...e.sunset === void 0 ? {} : { 410: v(`Gone — the route is past its sunset date (${e.sunset}).`) },
+	500: v("Internal Server Error.")
 });
-function y(e, t = {}, n = {}) {
-	let r = {}, i = {}, a = e.some((e) => e.guards !== void 0 && e.guards.length > 0);
+function A(e, t = {}, n = {}, r = {}) {
+	let a = {}, o = {}, s = e.some((e) => e.guards !== void 0 && e.guards.length > 0), c = e.some((e) => e.projection !== void 0 && e.projection.security !== "none"), l = e.some((e) => e.projection?.format.errors === "problem-details" && e.projection.format.encodeError === void 0), u = /* @__PURE__ */ new Set();
 	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;
+		let e = t.projection, { parameters: n, requestBody: r } = e === void 0 ? h(t.input, o) : T(t, e, o), i = t.etag === !0 && t.method === "GET" && t.streaming !== !0, s = i ? [...n, {
+			name: "If-None-Match",
+			in: "header",
+			required: !1,
+			description: "A previously returned ETag. A matching validator returns 304 without a body.",
+			schema: { type: "string" }
+		}] : n, c = i ? { 304: {
+			description: "Not Modified",
+			headers: { ETag: {
+				description: "The current representation validator.",
+				schema: { type: "string" }
+			} }
+		} } : {}, l = t.guards !== void 0 && t.guards.length > 0;
+		if (r !== void 0) {
+			let e = r.content;
 			e["application/json"] = {
 				...e["application/json"],
-				example: t.example.request
+				...O(t.example?.request, e["application/json"].schema, o)
 			};
 		}
-		let o = {
+		let d = e === void 0 ? l ? { security: [{ bearerAuth: [] }] } : {} : e.security === "required" ? { security: [{ bearerAuth: [] }] } : e.security === "optional" ? { security: [{ bearerAuth: [] }, {}] } : {}, m = t.tags ?? (t.version === void 0 ? void 0 : [t.version]);
+		for (let e of m ?? []) u.add(e);
+		let g = e?.version ?? t.version, _ = {
+			...t.operationId === void 0 ? {} : { operationId: t.operationId },
 			...t.summary ? { summary: t.summary } : {},
 			...t.description ? { description: t.description } : {},
 			...t.deprecated === void 0 ? {} : { deprecated: !0 },
 			...t.sunset === void 0 ? {} : { "x-sunset": t.sunset },
-			...t.version === void 0 ? {} : {
-				tags: [t.version],
-				"x-voltro-api-version": t.version
-			},
-			...e.length > 0 ? { parameters: e } : {},
-			...n ? { requestBody: n } : {},
-			...a ? { security: [{ bearerAuth: [] }] } : {},
-			responses: {
+			...m === void 0 ? {} : { tags: m },
+			...g === void 0 ? {} : { "x-voltro-api-version": g },
+			...s.length > 0 ? { parameters: s } : {},
+			...r ? { requestBody: r } : {},
+			...d,
+			responses: e === void 0 ? {
 				200: t.streaming === !0 ? {
 					description: "Server-Sent Events stream (`snapshot`, then `delta` per change)",
 					content: { "text/event-stream": { schema: { type: "string" } } }
 				} : {
 					description: "OK",
 					content: { "application/json": {
-						schema: f(t.output, i),
-						...t.example?.response === void 0 ? {} : { example: t.example.response }
+						schema: p(t.output, o),
+						...O(t.example?.response, p(t.output, o), o)
 					} }
 				},
-				...v(t)
+				...k(t),
+				...c
+			} : {
+				200: E(t, e, o),
+				...c,
+				...w(t, e, o)
 			}
-		}, s = d(t.path), c = r[s] ?? {};
-		c[t.method.toLowerCase()] = o, r[s] = c;
+		};
+		e?.format.describe !== void 0 && (_ = e.format.describe(_, {
+			tag: e.tag,
+			method: t.method,
+			path: t.path
+		}));
+		let v = f(t.path), y = a[v] ?? {};
+		y[t.method.toLowerCase()] = _, a[v] = y;
 	}
-	let o = n.procedures ?? [];
-	if (o.length > 0) {
-		let e = u(o, i);
-		for (let [t, n] of Object.entries(e)) r[t] = {
+	let v = n.procedures ?? [];
+	if (v.length > 0) {
+		let e = d(v, o);
+		for (let [t, n] of Object.entries(e)) a[t] = {
 			...n,
-			...r[t] ?? {}
+			...a[t] ?? {}
 		};
 	}
+	let x = [...u].sort().map((e) => ({
+		name: e,
+		...r.tagDescriptions?.[e] === void 0 ? {} : { description: r.tagDescriptions[e] },
+		...r.tagExternalDocs?.[e] === void 0 ? {} : { externalDocs: r.tagExternalDocs[e] }
+	})), S = (r.servers ?? []).map((e) => ({
+		url: e.url,
+		...e.description === void 0 ? {} : { description: e.description },
+		...e.environment === void 0 ? {} : { "x-voltro-environment": e.environment }
+	}));
 	return {
 		openapi: "3.1.0",
 		info: {
 			title: t.title ?? "API",
 			version: t.version ?? "1.0.0",
-			...t.description ? { description: t.description } : {}
+			...t.description ? { description: t.description } : {},
+			...t.contact === void 0 ? {} : { contact: t.contact },
+			...t.license === void 0 ? {} : { license: t.license },
+			...t.termsOfService === void 0 ? {} : { termsOfService: t.termsOfService },
+			...t.logo === void 0 ? {} : { "x-logo": t.logo }
 		},
-		paths: p(r),
+		...S.length > 0 ? { servers: S } : {},
+		...r.externalDocs === void 0 ? {} : { externalDocs: r.externalDocs },
+		...r.environment === void 0 ? {} : { "x-voltro-environment": r.environment },
+		...e.some((e) => e.projection !== void 0) ? { "x-voltro-surface-digest": i(e) } : {},
+		...x.length > 0 ? { tags: x } : {},
+		paths: m(a),
 		components: {
 			schemas: {
-				...p(i),
-				[h]: g
+				...m(o),
+				[g]: _,
+				...l ? { [y]: b } : {}
 			},
-			...a ? { securitySchemes: { bearerAuth: {
+			...s || c ? { securitySchemes: { bearerAuth: {
 				type: "http",
 				scheme: "bearer"
 			} } } : {}
@@ -178,73 +451,157 @@ function y(e, t = {}, n = {}) {
 }
 //#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>
+var j = "5.17.14", M = "sha384-wxLW6kwyHktdDGr6Pv1zgm/VGJh99lfUbzSn6HNHBENZlCN7W602k9VkGdxuFvPn", N = "sha384-wmyclcVGX/WhUkdkATwhaK1X1JtiNrr2EoYJ+diV3vj4v6OC5yCeSu+yW13SYJep", P = `https://unpkg.com/swagger-ui-dist@${j}/swagger-ui.css`, F = `https://unpkg.com/swagger-ui-dist@${j}/swagger-ui-bundle.js`, I = (e, t = "API docs", n = {}) => `<!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" />
+  <link rel="stylesheet" href="${P}" integrity="${M}" crossorigin="anonymous" />
   <style>body { margin: 0 }</style>
 </head>
 <body>
   <div id="swagger-ui"></div>
-  <script src="${w}" integrity="${S}" crossorigin="anonymous"><\/script>
+  <script src="${F}" integrity="${N}" crossorigin="anonymous"><\/script>
   <script>
-    window.ui = SwaggerUIBundle({ url: ${JSON.stringify(e)}, dom_id: '#swagger-ui', deepLinking: true });
+    window.ui = SwaggerUIBundle({ ${n.urls !== void 0 && n.urls.length > 0 ? `urls: ${JSON.stringify(n.urls)}, ${n.primaryName === void 0 ? "" : `'urls.primaryName': ${JSON.stringify(n.primaryName)}, `}` : `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) => {
+</html>`, L = r([
+	{
+		name: "OPENAPI_DOCS_TOKEN",
+		required: !1,
+		secret: !0,
+		description: "Bearer token required on GET /openapi.json + GET /docs; unset leaves them public."
+	},
+	{
+		name: "VOLTRO_PUBLIC_API_ORIGIN",
+		required: !1,
+		secret: !1,
+		description: "The public origin of this api (https://api.example.com) — the default servers[0] of the spec."
+	},
+	{
+		name: "VOLTRO_ENVIRONMENT",
+		required: !1,
+		secret: !1,
+		description: "The environment this instance serves (dev | staging | production) — x-voltro-environment on the spec."
+	}
+]), R = (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 = t.includeAppRoutes ?? !0, u = s, d = () => JSON.stringify(y(u, t.info ?? {}, { procedures: c }), null, 2), f = d(), p = (e) => {
-		if (!l) return;
+}, z = (e) => e.projection?.version ?? e.version, B = (e) => {
+	let t = /^v(\d+)$/.exec(e);
+	return t === null ? -1 : Number(t[1]);
+}, V = (e) => [...new Set(e.map(z).filter((e) => e !== void 0))].sort((e, t) => B(t) - B(e) || t.localeCompare(e)), H = (e, t) => {
+	let n = t.filter((t) => z(t) === e && t.sunset !== void 0).map((e) => e.sunset).sort();
+	return n.length > 0 ? `${e} — sunset ${n[0]}` : e;
+}, U = (t) => {
+	let r = t.specPath ?? "/openapi.json", i = t.docsPath ?? "/docs", a = L.read("OPENAPI_DOCS_TOKEN", t.token), o = t.name ? `@voltro/plugin-openapi#${t.name}` : "@voltro/plugin-openapi", s = t.routes ?? [], c = t.procedures ?? [], l = c, u = t.includeAppRoutes ?? !0, d = t.includeAppProcedures ?? !1, f = s, p = t.environment ?? L.read("VOLTRO_ENVIRONMENT", void 0) ?? (process.env.NODE_ENV === "production" ? "production" : "dev"), m = L.read("VOLTRO_PUBLIC_API_ORIGIN", void 0), h = t.servers ?? (m === void 0 ? [] : [{
+		url: m,
+		description: `${p} — this instance`,
+		environment: p
+	}]), g = {
+		...t.tagDescriptions === void 0 ? {} : { tagDescriptions: t.tagDescriptions },
+		...t.tagExternalDocs === void 0 ? {} : { tagExternalDocs: t.tagExternalDocs },
+		...t.externalDocs === void 0 ? {} : { externalDocs: t.externalDocs },
+		...h.length > 0 ? { servers: h } : {},
+		environment: p
+	}, _ = (e) => JSON.stringify(A(e === void 0 ? f : f.filter((t) => z(t) === e), t.info ?? {}, e === void 0 ? { procedures: l } : {}, g), null, 2), v = /* @__PURE__ */ new Map(), y = () => {
+		v = new Map([["", _()], ...V(f).map((e) => [e, _(e)])]);
+	};
+	y();
+	let b = (e) => {
+		if (!u) return;
 		let t = new Set(s.map((e) => `${e.method} ${e.path}`)), n = e.filter((e) => !t.has(`${e.method} ${e.path}`));
-		u = [...s, ...n], f = d();
-	}, m = [{
+		f = [...s, ...n], y();
+	}, x = (e) => {
+		if (!d) return;
+		let t = new Set(c.map((e) => e.name));
+		l = [...c, ...e.filter((e) => !t.has(e.name))], y();
+	}, S = r.endsWith(".json") ? r.slice(0, -5) : `${r}/versions`, C = (e) => `${S}/${e}.json`, w = (e) => ({
+		status: 404,
+		contentType: "application/json",
+		body: JSON.stringify({
+			error: `no API version '${e}' is mounted`,
+			versions: V(f)
+		})
+	}), T = [{
 		method: "GET",
 		path: r,
-		handle: async (e) => D(a, e) ?? {
-			status: 200,
-			body: f,
-			contentType: "application/json"
+		match: "exact",
+		handle: async (e) => {
+			let t = R(a, e);
+			if (t) return t;
+			let n = new URLSearchParams(e.query).get("version") ?? void 0;
+			return n !== void 0 && !v.has(n) ? w(n) : {
+				status: 200,
+				body: v.get(n ?? ""),
+				contentType: "application/json"
+			};
+		}
+	}, {
+		method: "GET",
+		path: S,
+		handle: async (e) => {
+			let t = R(a, e);
+			if (t) return t;
+			let n = /\/([^/]+)\.json$/.exec(e.path)?.[1];
+			return n === void 0 || n === "" || !v.has(n) ? w(n ?? "") : {
+				status: 200,
+				body: v.get(n),
+				contentType: "application/json"
+			};
 		}
 	}];
-	return i !== !1 && m.push({
+	return i !== !1 && T.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"
+		match: "exact",
+		handle: async (e) => {
+			let n = R(a, e);
+			if (n) return n;
+			let i = V(f), o = i.length > 1 ? [...i.map((e) => ({
+				url: C(e),
+				name: H(e, f)
+			})), {
+				url: r,
+				name: "all versions"
+			}] : void 0;
+			return {
+				status: 200,
+				body: I(r, t.info?.title ?? "API docs", o === void 0 ? {} : {
+					urls: o,
+					primaryName: o[0].name
+				}),
+				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: m,
-		onRestSurface: p,
+		declaredEnv: L.declared,
+		httpRoutes: T,
+		onRestSurface: b,
+		onProcedureSurface: x,
 		onActivate: (t) => e.sync(() => {
 			t.logger.info("openapi docs active", {
 				specPath: r,
 				docsPath: i,
-				routes: u.length,
-				appRoutes: l ? "included once mounted" : "excluded",
-				procedures: c.length,
+				routes: f.length,
+				appRoutes: u ? "included once mounted" : "excluded",
+				procedures: l.length,
+				appProcedures: d ? "included once discovered" : "excluded",
+				environment: p,
+				servers: h.map((e) => e.url),
+				versions: V(f),
 				tokenGated: !!a
 			});
 		})
 	});
 };
 //#endregion
-export { y as generateOpenApiSpec, O as openapiPlugin, T as swaggerUiHtml };
+export { y as PROBLEM_DETAILS_SCHEMA_NAME, x as deriveExample, A as generateOpenApiSpec, V as mountedVersions, U as openapiPlugin, I as swaggerUiHtml, H as versionLabel };