@voltro/plugin-openapi 0.85.0 → 0.86.0

package/THIRD-PARTY-NOTICES.md

@@ -1,11 +1,11 @@
 # Third-Party Notices — @voltro/plugin-openapi
 
-This package depends on the open-source software listed below. Each is the
+This package uses the open-source software listed below. Each is the
 property of its respective copyright holders and is used under the terms of
 its license. This file is provided for attribution; it grants no rights in
 @voltro/plugin-openapi itself, which is proprietary (see LICENSE).
 
-Generated from the resolved runtime dependency closure (42 packages).
+Generated from the resolved runtime dependency closure (41 packages).
 
 ---
 
@@ -3636,34 +3636,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## layerr@3.0.0
-
-License: MIT
-
-```
-MIT License
-
-Copyright (c) 2020 Perry Mitchell
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
-
 ## lib0@0.2.117
 
 License: MIT
@@ -4013,14 +3985,14 @@ Apache License
    limitations under the License.
 ```
 
-## ulidx@2.4.1
+## ulid@3.0.2
 
 License: MIT
 
 ```
-MIT License
+The MIT License (MIT)
 
-Copyright (c) 2021 Perry Mitchell
+Copyright (c) 2017 Alizain Feerasta
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/generate.js

@@ -0,0 +1,436 @@
+import { rpcPathItems as e } from "./rpc.js";
+import { jsonSchemaDocumentOf as t } from "@voltro/protocol";
+import { publicSurfaceDigest as n } from "@voltro/protocol/rest";
+//#region src/generate.ts
+var r = (e) => e.replace(/:([A-Za-z0-9_]+)/g, "{$1}"), i = (e) => {
+	let t = e.anyOf ?? e.oneOf;
+	if (!Array.isArray(t)) return e;
+	let n = t.filter((e) => e.type !== "null");
+	return n.length === 1 && n.length < t.length ? n[0] : e;
+}, a = (e, n) => {
+	let r = t(e, { closed: !1 });
+	for (let [e, t] of Object.entries(r.definitions)) n[e] = t;
+	return r.schema;
+}, o = (e) => {
+	if (Array.isArray(e)) return e.map(o);
+	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)}` : o(r);
+		return t;
+	}
+	return e;
+}, s = (e, t) => {
+	if (!e) return {
+		parameters: [],
+		requestBody: void 0
+	};
+	let n = a(e, t), r = n.properties ?? {}, i = new Set(n.required ?? []), o = [];
+	for (let [e, t] of [["query", "query"], ["params", "path"]]) {
+		let n = r[e];
+		if (!n || typeof n != "object") continue;
+		let i = n.properties ?? {}, a = new Set(n.required ?? []);
+		for (let [e, n] of Object.entries(i)) o.push({
+			name: e,
+			in: t,
+			required: t === "path" || a.has(e),
+			schema: n
+		});
+	}
+	let s = r.body;
+	return {
+		parameters: o,
+		requestBody: s && typeof s == "object" ? {
+			required: i.has("body"),
+			content: { "application/json": { schema: s } }
+		} : void 0
+	};
+}, c = "VoltroHttpError", l = {
+	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"]
+}, u = (e) => ({
+	description: e,
+	content: { "application/json": { schema: { $ref: `#/components/schemas/${c}` } } }
+}), d = "ProblemDetails", f = {
+	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
+}, p = (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" ? p(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 p(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) => p(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) ? [p(r, t, n + 1)] : [];
+		}
+		case "object": {
+			let r = e.properties ?? {}, i = {};
+			for (let [e, a] of Object.entries(r)) i[e] = p(a, t, n + 1);
+			return i;
+		}
+		default: return typeof e.properties == "object" ? p({
+			...e,
+			type: "object"
+		}, t, n) : null;
+	}
+}, m = {
+	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"
+	}
+}, h = {
+	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"
+}, g = (e, t, n) => {
+	let r = t.format.errors === "problem-details" && t.format.encodeError === void 0, i = r ? "application/problem+json" : "application/json", o = /* @__PURE__ */ new Map();
+	for (let e of t.errorResponses) {
+		let t = o.get(e.status) ?? [], i = a(e.schema, n), s = p(i, n), { _tag: c, ...l } = typeof s == "object" && s ? s : {}, u = r ? {
+			type: `urn:voltro:error:${e.tag}`,
+			title: e.tag.replace(/([a-z0-9])([A-Z])/g, "$1 $2"),
+			status: e.status,
+			...l
+		} : {
+			error: e.tag,
+			...l
+		};
+		t.push({
+			tag: e.tag,
+			example: u,
+			schema: r ? { allOf: [{ $ref: `#/components/schemas/${d}` }, {
+				type: "object",
+				properties: { type: { const: `urn:voltro:error:${e.tag}` } }
+			}] } : i
+		}), o.set(e.status, t);
+	}
+	let s = (e, t) => {
+		if (!r) return u(t);
+		let n = m[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/${d}` },
+				...a
+			} }
+		};
+	}, c = {};
+	c[400] = s(400, "Invalid request — the input failed schema decode."), t.security !== "none" && (c[401] = s(401, "Unauthorized — no valid bearer.")), (t.security === "required" || (e.guards?.length ?? 0) > 0) && (c[403] = s(403, "Forbidden — the caller lacks a required scope."));
+	for (let [e, t] of [...o.entries()].sort((e, t) => e[0] - t[0])) {
+		let n = t.map((e) => e.tag);
+		c[String(e)] = {
+			description: `${h[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 && (c[410] = s(410, `Gone — the route is past its sunset date (${e.sunset}).`)), c[500] = s(500, "Internal Server Error."), c;
+}, _ = (e, t, n) => {
+	let r = a(t.input, n), o = r.properties ?? {}, s = new Set(r.required ?? []), c = new Set(t.pathParams), l = [], u = {}, d = [], f = e.example?.request, p = (e) => typeof f == "object" && f && e in f ? { example: f[e] } : {};
+	for (let [t, n] of Object.entries(o)) {
+		let r = s.has(t) ? n : i(n);
+		c.has(t) ? l.push({
+			name: t,
+			in: "path",
+			required: !0,
+			schema: r,
+			...p(t)
+		}) : e.method === "GET" ? l.push({
+			name: t,
+			in: "query",
+			required: s.has(t),
+			schema: r,
+			...p(t)
+		}) : (u[t] = r, s.has(t) && d.push(t));
+	}
+	return {
+		parameters: l,
+		requestBody: e.method !== "GET" && Object.keys(u).length > 0 ? {
+			required: d.length > 0,
+			content: {
+				"application/json": { schema: {
+					...r,
+					properties: u,
+					required: d
+				} },
+				"application/x-www-form-urlencoded": { schema: {
+					...r,
+					properties: u,
+					required: d
+				} }
+			}
+		} : void 0
+	};
+}, v = (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 = a(t.output, n), i = t.format, o = i.pagination === "link-header" && y(r, n, i.cursorField), s = i.encodeSuccess === void 0 ? i.envelope === "data" ? {
+		type: "object",
+		properties: {
+			data: r,
+			...o ? { 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.` }, c = i.envelope === "jsonapi" ? "application/vnd.api+json" : "application/json", l = {
+		...o ? { 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" }
+		} } : {},
+		...e.cache !== void 0 && e.method === "GET" ? {
+			"Cache-Control": {
+				description: `\`public, max-age=${e.cache.maxAge}\` for a request without a credential; \`private, no-cache\` for one with \`Authorization\` or a cookie.`,
+				schema: { type: "string" }
+			},
+			...e.cache.tags === void 0 ? {} : {
+				"Cache-Tag": {
+					description: "Purge tags, comma-separated (only on a public answer).",
+					schema: { type: "string" }
+				},
+				"Surrogate-Key": {
+					description: "The same purge tags, space-separated (only on a public answer).",
+					schema: { type: "string" }
+				}
+			}
+		} : {}
+	};
+	return {
+		description: "OK",
+		...Object.keys(l).length > 0 ? { headers: l } : {},
+		content: { [c]: {
+			schema: s,
+			...b(e.example?.response, s, n)
+		} }
+	};
+}, y = (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;
+}, b = (e, t, n) => e === void 0 ? {
+	example: p(t, n),
+	"x-voltro-example": "derived"
+} : { example: e }, x = (e) => ({
+	...e.input === void 0 ? {} : { 400: u("Invalid request — the input failed schema decode.") },
+	...e.guards !== void 0 && e.guards.length > 0 ? {
+		401: u("Unauthorized — a guard rejected the unauthenticated request."),
+		403: u("Forbidden — a guard rejected the request (e.g. a required scope is missing).")
+	} : {},
+	...e.sunset === void 0 ? {} : { 410: u(`Gone — the route is past its sunset date (${e.sunset}).`) },
+	500: u("Internal Server Error.")
+});
+function S(t, i = {}, u = {}, p = {}) {
+	let m = {}, h = {}, y = t.some((e) => e.guards !== void 0 && e.guards.length > 0), S = t.some((e) => e.projection !== void 0 && e.projection.security !== "none"), C = t.some((e) => e.projection?.format.errors === "problem-details" && e.projection.format.encodeError === void 0), w = /* @__PURE__ */ new Set();
+	for (let e of t) {
+		let t = e.projection, { parameters: n, requestBody: i } = t === void 0 ? s(e.input, h) : _(e, t, h), o = e.etag === !0 && e.method === "GET" && e.streaming !== !0, c = o ? [...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, l = o ? { 304: {
+			description: "Not Modified",
+			headers: { ETag: {
+				description: "The current representation validator.",
+				schema: { type: "string" }
+			} }
+		} } : {}, u = e.guards !== void 0 && e.guards.length > 0;
+		if (i !== void 0) {
+			let t = i.content;
+			t["application/json"] = {
+				...t["application/json"],
+				...b(e.example?.request, t["application/json"].schema, h)
+			};
+		}
+		let d = t === void 0 ? u ? { security: [{ bearerAuth: [] }] } : {} : t.security === "required" ? { security: [{ bearerAuth: [] }] } : t.security === "optional" ? { security: [{ bearerAuth: [] }, {}] } : {}, f = e.tags ?? (e.version === void 0 ? void 0 : [e.version]);
+		for (let e of f ?? []) w.add(e);
+		let p = t?.version ?? e.version, y = {
+			...e.operationId === void 0 ? {} : { operationId: e.operationId },
+			...e.summary ? { summary: e.summary } : {},
+			...e.description ? { description: e.description } : {},
+			...e.deprecated === void 0 ? {} : { deprecated: !0 },
+			...e.sunset === void 0 ? {} : { "x-sunset": e.sunset },
+			...f === void 0 ? {} : { tags: f },
+			...p === void 0 ? {} : { "x-voltro-api-version": p },
+			...c.length > 0 ? { parameters: c } : {},
+			...i ? { requestBody: i } : {},
+			...d,
+			responses: t === void 0 ? {
+				200: e.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: a(e.output, h),
+						...b(e.example?.response, a(e.output, h), h)
+					} }
+				},
+				...x(e),
+				...l
+			} : {
+				200: v(e, t, h),
+				...l,
+				...g(e, t, h)
+			}
+		};
+		t?.format.describe !== void 0 && (y = t.format.describe(y, {
+			tag: t.tag,
+			method: e.method,
+			path: e.path
+		}));
+		let S = r(e.path), C = m[S] ?? {};
+		C[e.method.toLowerCase()] = y, m[S] = C;
+	}
+	let T = u.procedures ?? [];
+	if (T.length > 0) {
+		let t = e(T, h);
+		for (let [e, n] of Object.entries(t)) m[e] = {
+			...n,
+			...m[e] ?? {}
+		};
+	}
+	let E = [...w].sort().map((e) => ({
+		name: e,
+		...p.tagDescriptions?.[e] === void 0 ? {} : { description: p.tagDescriptions[e] },
+		...p.tagExternalDocs?.[e] === void 0 ? {} : { externalDocs: p.tagExternalDocs[e] }
+	})), D = (p.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: i.title ?? "API",
+			version: i.version ?? "1.0.0",
+			...i.description ? { description: i.description } : {},
+			...i.contact === void 0 ? {} : { contact: i.contact },
+			...i.license === void 0 ? {} : { license: i.license },
+			...i.termsOfService === void 0 ? {} : { termsOfService: i.termsOfService },
+			...i.logo === void 0 ? {} : { "x-logo": i.logo }
+		},
+		...D.length > 0 ? { servers: D } : {},
+		...p.externalDocs === void 0 ? {} : { externalDocs: p.externalDocs },
+		...p.environment === void 0 ? {} : { "x-voltro-environment": p.environment },
+		...t.some((e) => e.projection !== void 0) ? { "x-voltro-surface-digest": n(t) } : {},
+		...E.length > 0 ? { tags: E } : {},
+		paths: o(m),
+		components: {
+			schemas: {
+				...o(h),
+				[c]: l,
+				...C ? { [d]: f } : {}
+			},
+			...y || S ? { securitySchemes: { bearerAuth: {
+				type: "http",
+				scheme: "bearer"
+			} } } : {}
+		}
+	};
+}
+//#endregion
+export { l as HTTP_ERROR_SCHEMA, c as HTTP_ERROR_SCHEMA_NAME, f as PROBLEM_DETAILS_SCHEMA, d as PROBLEM_DETAILS_SCHEMA_NAME, p as deriveExample, u as errorResponse, S as generateOpenApiSpec, o as rewriteRefs, a as toJsonSchema };