@voltro/plugin-openapi 0.70.0 → 0.71.1

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,10 +98,10 @@ 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 = "ProblemDetails", y = {
+	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: {
@@ -119,7 +120,76 @@ var i = "/rpc", a = "rpc", o = (e) => e.ast._tag === "NeverKeyword", s = (e, t)
 		"status"
 	],
 	additionalProperties: !0
-}, b = {
+}, 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",
@@ -129,66 +199,98 @@ var i = "/rpc", a = "rpc", o = (e) => e.ast._tag === "NeverKeyword", s = (e, t)
 	422: "Unprocessable Content",
 	429: "Too Many Requests",
 	500: "Internal Server Error"
-}, x = (e, t, n) => {
+}, 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) ?? [];
+		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,
-			schema: r ? { allOf: [{ $ref: `#/components/schemas/${v}` }, {
+			example: l,
+			schema: r ? { allOf: [{ $ref: `#/components/schemas/${y}` }, {
 				type: "object",
 				properties: { type: { const: `urn:voltro:error:${e.tag}` } }
-			}] } : f(e.schema, n)
+			}] } : i
 		}), a.set(e.status, t);
 	}
-	let o = (e, t) => r ? {
-		description: t,
-		content: { [i]: { schema: { $ref: `#/components/schemas/${v}` } } }
-	} : _(t), s = {};
+	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: `${b[e] ?? "Error"} — ${n.join(" | ")}`,
-			content: { [i]: { schema: t.length === 1 ? t[0].schema : { oneOf: t.map((e) => e.schema) } } }
+			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;
-}, S = (e, t, n) => {
-	let r = f(t.input, n), i = r.properties ?? {}, a = new Set(r.required ?? []), o = new Set(t.pathParams), s = [], c = {}, l = [];
+}, 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
+		schema: n,
+		...d(t)
 	}) : e.method === "GET" ? s.push({
 		name: t,
 		in: "query",
 		required: a.has(t),
-		schema: n
+		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,
-				...r.additionalProperties === void 0 ? {} : { additionalProperties: r.additionalProperties }
-			} } }
+			content: {
+				"application/json": { schema: {
+					...r,
+					properties: c,
+					required: l
+				} },
+				"application/x-www-form-urlencoded": { schema: {
+					...r,
+					properties: c,
+					required: l
+				} }
+			}
 		} : void 0
 	};
-}, C = (e, t, n) => {
+}, 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 = f(t.output, n), i = t.format, a = i.encodeSuccess === void 0 ? i.envelope === "data" ? {
+	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,
-			...i.pagination === "link-header" ? { next: {
+			...a ? { next: {
 				type: "string",
 				description: "The next page's cursor, when there is one."
 			} } : {}
@@ -204,8 +306,8 @@ var i = "/rpc", a = "rpc", o = (e) => e.ast._tag === "NeverKeyword", s = (e, t)
 			}
 		},
 		required: ["data"]
-	} : r : { description: `Encoded by the '${i.name}' format.` }, o = i.envelope === "jsonapi" ? "application/vnd.api+json" : "application/json", s = {
-		...i.pagination === "link-header" ? { Link: {
+	} : 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" }
 		} } : {},
@@ -216,45 +318,63 @@ var i = "/rpc", a = "rpc", o = (e) => e.ast._tag === "NeverKeyword", s = (e, t)
 	};
 	return {
 		description: "OK",
-		...Object.keys(s).length > 0 ? { headers: s } : {},
-		content: { [o]: {
-			schema: a,
-			...e.example?.response === void 0 ? {} : { example: e.example.response }
+		...Object.keys(c).length > 0 ? { headers: c } : {},
+		content: { [s]: {
+			schema: o,
+			...O(e.example?.response, o, n)
 		} }
 	};
-}, w = (e) => ({
-	...e.input === void 0 ? {} : { 400: _("Invalid request — the input failed schema decode.") },
+}, 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 T(e, t = {}, n = {}, r = {}) {
-	let i = {}, a = {}, o = e.some((e) => e.guards !== void 0 && e.guards.length > 0), s = e.some((e) => e.projection !== void 0 && e.projection.security !== "none"), c = e.some((e) => e.projection?.format.errors === "problem-details" && e.projection.format.encodeError === void 0), l = /* @__PURE__ */ new Set();
+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 e = t.projection, { parameters: n, requestBody: r } = e === void 0 ? m(t.input, a) : S(t, e, a), o = t.guards !== void 0 && t.guards.length > 0;
-		if (r !== void 0 && t.example?.request !== void 0) {
+		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 s = e === void 0 ? o ? { security: [{ bearerAuth: [] }] } : {} : e.security === "required" ? { security: [{ bearerAuth: [] }] } : e.security === "optional" ? { security: [{ bearerAuth: [] }, {}] } : {}, c = t.tags ?? (t.version === void 0 ? void 0 : [t.version]);
-		for (let e of c ?? []) l.add(e);
-		let u = e?.version ?? t.version, p = {
+		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 },
-			...c === void 0 ? {} : { tags: c },
-			...u === void 0 ? {} : { "x-voltro-api-version": u },
-			...n.length > 0 ? { parameters: n } : {},
+			...m === void 0 ? {} : { tags: m },
+			...g === void 0 ? {} : { "x-voltro-api-version": g },
+			...s.length > 0 ? { parameters: s } : {},
 			...r ? { requestBody: r } : {},
-			...s,
+			...d,
 			responses: e === void 0 ? {
 				200: t.streaming === !0 ? {
 					description: "Server-Sent Events stream (`snapshot`, then `delta` per change)",
@@ -262,52 +382,67 @@ function T(e, t = {}, n = {}, r = {}) {
 				} : {
 					description: "OK",
 					content: { "application/json": {
-						schema: f(t.output, a),
-						...t.example?.response === void 0 ? {} : { example: t.example.response }
+						schema: p(t.output, o),
+						...O(t.example?.response, p(t.output, o), o)
 					} }
 				},
-				...w(t)
+				...k(t),
+				...c
 			} : {
-				200: C(t, e, a),
-				...x(t, e, a)
+				200: E(t, e, o),
+				...c,
+				...w(t, e, o)
 			}
 		};
-		e?.format.describe !== void 0 && (p = e.format.describe(p, {
+		e?.format.describe !== void 0 && (_ = e.format.describe(_, {
 			tag: e.tag,
 			method: t.method,
 			path: t.path
 		}));
-		let h = d(t.path), g = i[h] ?? {};
-		g[t.method.toLowerCase()] = p, i[h] = g;
+		let v = f(t.path), y = a[v] ?? {};
+		y[t.method.toLowerCase()] = _, a[v] = y;
 	}
-	let _ = n.procedures ?? [];
-	if (_.length > 0) {
-		let e = u(_, a);
-		for (let [t, n] of Object.entries(e)) i[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,
-			...i[t] ?? {}
+			...a[t] ?? {}
 		};
 	}
-	let b = [...l].sort().map((e) => ({
+	let x = [...u].sort().map((e) => ({
 		name: e,
-		...r.tagDescriptions?.[e] === void 0 ? {} : { description: r.tagDescriptions[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 }
 		},
-		...b.length > 0 ? { tags: b } : {},
-		paths: p(i),
+		...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(a),
-				[h]: g,
-				...c ? { [v]: y } : {}
+				...m(o),
+				[g]: _,
+				...l ? { [y]: b } : {}
 			},
-			...o || s ? { securitySchemes: { bearerAuth: {
+			...s || c ? { securitySchemes: { bearerAuth: {
 				type: "http",
 				scheme: "bearer"
 			} } } : {}
@@ -316,104 +451,128 @@ function T(e, t = {}, n = {}, r = {}) {
 }
 //#endregion
 //#region src/swaggerUi.ts
-var E = "5.17.14", D = "sha384-wxLW6kwyHktdDGr6Pv1zgm/VGJh99lfUbzSn6HNHBENZlCN7W602k9VkGdxuFvPn", O = "sha384-wmyclcVGX/WhUkdkATwhaK1X1JtiNrr2EoYJ+diV3vj4v6OC5yCeSu+yW13SYJep", k = `https://unpkg.com/swagger-ui-dist@${E}/swagger-ui.css`, A = `https://unpkg.com/swagger-ui-dist@${E}/swagger-ui-bundle.js`, j = (e, t = "API docs", n = {}) => `<!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="${k}" integrity="${D}" 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="${A}" integrity="${O}" crossorigin="anonymous"><\/script>
+  <script src="${F}" integrity="${N}" crossorigin="anonymous"><\/script>
   <script>
     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>`, M = r([{
-	name: "OPENAPI_DOCS_TOKEN",
-	required: !1,
-	secret: !0,
-	description: "Bearer token required on GET /openapi.json + GET /docs; unset leaves them public."
-}]), N = (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"
 	};
-}, P = (e) => e.projection?.version ?? e.version, F = (e) => {
+}, z = (e) => e.projection?.version ?? e.version, B = (e) => {
 	let t = /^v(\d+)$/.exec(e);
 	return t === null ? -1 : Number(t[1]);
-}, I = (e) => [...new Set(e.map(P).filter((e) => e !== void 0))].sort((e, t) => F(t) - F(e) || t.localeCompare(e)), L = (e, t) => {
-	let n = t.filter((t) => P(t) === e && t.sunset !== void 0).map((e) => e.sunset).sort();
+}, 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;
-}, R = (t) => {
-	let r = t.specPath ?? "/openapi.json", i = t.docsPath ?? "/docs", a = M.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.tagDescriptions === void 0 ? {} : { tagDescriptions: t.tagDescriptions }, m = (e) => JSON.stringify(T(e === void 0 ? f : f.filter((t) => P(t) === e), t.info ?? {}, e === void 0 ? { procedures: l } : {}, p), null, 2), h = /* @__PURE__ */ new Map(), g = () => {
-		h = new Map([["", m()], ...I(f).map((e) => [e, m(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)])]);
 	};
-	g();
-	let _ = (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}`));
-		f = [...s, ...n], g();
-	}, v = (e) => {
+		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))], g();
-	}, y = r.endsWith(".json") ? r.slice(0, -5) : `${r}/versions`, b = (e) => `${y}/${e}.json`, x = (e) => ({
+		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: I(f)
+			versions: V(f)
 		})
-	}), S = [{
+	}), T = [{
 		method: "GET",
 		path: r,
 		match: "exact",
 		handle: async (e) => {
-			let t = N(a, e);
+			let t = R(a, e);
 			if (t) return t;
 			let n = new URLSearchParams(e.query).get("version") ?? void 0;
-			return n !== void 0 && !h.has(n) ? x(n) : {
+			return n !== void 0 && !v.has(n) ? w(n) : {
 				status: 200,
-				body: h.get(n ?? ""),
+				body: v.get(n ?? ""),
 				contentType: "application/json"
 			};
 		}
 	}, {
 		method: "GET",
-		path: y,
+		path: S,
 		handle: async (e) => {
-			let t = N(a, e);
+			let t = R(a, e);
 			if (t) return t;
 			let n = /\/([^/]+)\.json$/.exec(e.path)?.[1];
-			return n === void 0 || n === "" || !h.has(n) ? x(n ?? "") : {
+			return n === void 0 || n === "" || !v.has(n) ? w(n ?? "") : {
 				status: 200,
-				body: h.get(n),
+				body: v.get(n),
 				contentType: "application/json"
 			};
 		}
 	}];
-	return i !== !1 && S.push({
+	return i !== !1 && T.push({
 		method: "GET",
 		path: i,
 		match: "exact",
 		handle: async (e) => {
-			let n = N(a, e);
+			let n = R(a, e);
 			if (n) return n;
-			let i = I(f), o = i.length > 1 ? [...i.map((e) => ({
-				url: b(e),
-				name: L(e, f)
+			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: j(r, t.info?.title ?? "API docs", o === void 0 ? {} : {
+				body: I(r, t.info?.title ?? "API docs", o === void 0 ? {} : {
 					urls: o,
 					primaryName: o[0].name
 				}),
@@ -424,10 +583,10 @@ var E = "5.17.14", D = "sha384-wxLW6kwyHktdDGr6Pv1zgm/VGJh99lfUbzSn6HNHBENZlCN7W
 		name: o,
 		description: "OpenAPI 3.1 spec + Swagger-UI docs from defineRestRoute descriptors + rpc procedures.",
 		permissions: [],
-		declaredEnv: M.declared,
-		httpRoutes: S,
-		onRestSurface: _,
-		onProcedureSurface: v,
+		declaredEnv: L.declared,
+		httpRoutes: T,
+		onRestSurface: b,
+		onProcedureSurface: x,
 		onActivate: (t) => e.sync(() => {
 			t.logger.info("openapi docs active", {
 				specPath: r,
@@ -436,11 +595,13 @@ var E = "5.17.14", D = "sha384-wxLW6kwyHktdDGr6Pv1zgm/VGJh99lfUbzSn6HNHBENZlCN7W
 				appRoutes: u ? "included once mounted" : "excluded",
 				procedures: l.length,
 				appProcedures: d ? "included once discovered" : "excluded",
-				versions: I(f),
+				environment: p,
+				servers: h.map((e) => e.url),
+				versions: V(f),
 				tokenGated: !!a
 			});
 		})
 	});
 };
 //#endregion
-export { v as PROBLEM_DETAILS_SCHEMA_NAME, T as generateOpenApiSpec, I as mountedVersions, R as openapiPlugin, j as swaggerUiHtml, L as versionLabel };
+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 };