@warlock.js/core 5.26.0 → 5.28.0

package/esm/openapi/postman/openapi-to-postman-collection.mjs

@@ -0,0 +1,109 @@
+import { buildRequestBody } from "./build-request-body.mjs";
+import { buildHeaderParameters, buildRequestUrl } from "./build-request-url.mjs";
+import { buildSavedResponses } from "./build-saved-responses.mjs";
+import { collectionBearerAuth, hasBearerScheme, resolveOperationAuth } from "./resolve-operation-auth.mjs";
+import { uuidV5 } from "./uuid-v5.mjs";
+
+//#region ../core/src/openapi/postman/openapi-to-postman-collection.ts
+/** `info.schema` of every collection this converter produces. */
+const POSTMAN_COLLECTION_SCHEMA = "https://schema.getpostman.com/json/collection/v2.1.0/collection.json";
+/** `{{baseUrl}}` when neither the options nor the document name a server. */
+const DEFAULT_POSTMAN_BASE_URL = "http://localhost:3000";
+const OPERATION_METHODS = [
+	"get",
+	"put",
+	"post",
+	"delete",
+	"options",
+	"head",
+	"patch",
+	"trace"
+];
+function buildRequestItem(path, method, operation, document) {
+	const components = document.components?.schemas;
+	const parameters = operation.parameters ?? [];
+	const body = buildRequestBody(operation.requestBody, components);
+	const { auth, note } = resolveOperationAuth(operation, document.components);
+	const description = [operation.description, note].filter((line) => Boolean(line)).join("\n\n");
+	const header = [...body?.contentType ? [{
+		key: "Content-Type",
+		value: body.contentType,
+		type: "text"
+	}] : [], ...buildHeaderParameters(parameters, components)];
+	const originalRequest = {
+		method: method.toUpperCase(),
+		header,
+		...body ? { body: body.body } : {},
+		url: buildRequestUrl(path, parameters, components)
+	};
+	return {
+		name: operation.summary ?? operation.operationId,
+		request: {
+			...originalRequest,
+			...auth ? { auth } : {},
+			...description ? { description } : {}
+		},
+		response: buildSavedResponses(operation.responses, originalRequest, components)
+	};
+}
+function normalizeBaseUrl(baseUrl) {
+	return baseUrl.replace(/\/+$/, "");
+}
+/**
+* Convert an OpenAPI document into a Postman Collection v2.1.0 object.
+*
+* Pure and deterministic (the collection id is a UUIDv5 of the title), derived only from the
+* document so the collection can never disagree with the OpenAPI output. Each tag becomes a
+* folder in order of first appearance and untagged operations stay at the root; each
+* operation becomes a request with example bodies generated from its schemas and a saved
+* response per declared status. `{{baseUrl}}` and `{{token}}` are collection variables; a
+* bearer scheme becomes collection-level bearer auth and public operations opt out of it.
+*/
+function openApiToPostmanCollection(document, options = {}) {
+	const name = options.title ?? document.info.title;
+	const baseUrl = normalizeBaseUrl(options.baseUrl ?? document.servers?.[0]?.url ?? "http://localhost:3000");
+	const root = [];
+	const folders = /* @__PURE__ */ new Map();
+	for (const [path, pathItem] of Object.entries(document.paths)) for (const [method, operation] of Object.entries(pathItem)) {
+		if (!OPERATION_METHODS.includes(method)) continue;
+		const item = buildRequestItem(path, method, operation, document);
+		const tag = operation.tags?.[0];
+		if (tag === void 0) {
+			root.push(item);
+			continue;
+		}
+		let folder = folders.get(tag);
+		if (!folder) {
+			folder = {
+				name: tag,
+				item: []
+			};
+			folders.set(tag, folder);
+			root.push(folder);
+		}
+		folder.item.push(item);
+	}
+	return {
+		info: {
+			_postman_id: uuidV5(name),
+			name,
+			...document.info.description ? { description: document.info.description } : {},
+			schema: POSTMAN_COLLECTION_SCHEMA
+		},
+		item: root,
+		...hasBearerScheme(document.components) ? { auth: collectionBearerAuth() } : {},
+		variable: [{
+			key: "baseUrl",
+			value: baseUrl,
+			type: "string"
+		}, {
+			key: "token",
+			value: "",
+			type: "string"
+		}]
+	};
+}
+
+//#endregion
+export { DEFAULT_POSTMAN_BASE_URL, POSTMAN_COLLECTION_SCHEMA, openApiToPostmanCollection };
+//# sourceMappingURL=openapi-to-postman-collection.mjs.map

package/esm/openapi/postman/openapi-to-postman-collection.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-to-postman-collection.mjs","names":[],"sources":["../../../../../../../../core/src/openapi/postman/openapi-to-postman-collection.ts"],"sourcesContent":["import type { OpenApiDocument, OpenApiOperation } from \"../types\";\nimport { buildRequestBody } from \"./build-request-body\";\nimport { buildHeaderParameters, buildRequestUrl } from \"./build-request-url\";\nimport { buildSavedResponses } from \"./build-saved-responses\";\nimport type {\n  PostmanCollection,\n  PostmanCollectionOptions,\n  PostmanFolder,\n  PostmanHeader,\n  PostmanItem,\n  PostmanRequestItem,\n} from \"./postman-types\";\nimport { collectionBearerAuth, hasBearerScheme, resolveOperationAuth } from \"./resolve-operation-auth\";\nimport { uuidV5 } from \"./uuid-v5\";\n\n/** `info.schema` of every collection this converter produces. */\nexport const POSTMAN_COLLECTION_SCHEMA = \"https://schema.getpostman.com/json/collection/v2.1.0/collection.json\";\n\n/** `{{baseUrl}}` when neither the options nor the document name a server. */\nexport const DEFAULT_POSTMAN_BASE_URL = \"http://localhost:3000\";\n\nconst OPERATION_METHODS = [\"get\", \"put\", \"post\", \"delete\", \"options\", \"head\", \"patch\", \"trace\"];\n\nfunction buildRequestItem(\n  path: string,\n  method: string,\n  operation: OpenApiOperation,\n  document: OpenApiDocument,\n): PostmanRequestItem {\n  const components = document.components?.schemas;\n  const parameters = operation.parameters ?? [];\n  const body = buildRequestBody(operation.requestBody, components);\n  const { auth, note } = resolveOperationAuth(operation, document.components);\n  const description = [operation.description, note].filter((line): line is string => Boolean(line)).join(\"\\n\\n\");\n\n  const header: PostmanHeader[] = [\n    ...(body?.contentType ? [{ key: \"Content-Type\", value: body.contentType, type: \"text\" as const }] : []),\n    ...buildHeaderParameters(parameters, components),\n  ];\n\n  const originalRequest = {\n    method: method.toUpperCase(),\n    header,\n    ...(body ? { body: body.body } : {}),\n    url: buildRequestUrl(path, parameters, components),\n  };\n\n  return {\n    name: operation.summary ?? operation.operationId,\n    request: {\n      ...originalRequest,\n      ...(auth ? { auth } : {}),\n      ...(description ? { description } : {}),\n    },\n    response: buildSavedResponses(operation.responses, originalRequest, components),\n  };\n}\n\nfunction normalizeBaseUrl(baseUrl: string): string {\n  return baseUrl.replace(/\\/+$/, \"\");\n}\n\n/**\n * Convert an OpenAPI document into a Postman Collection v2.1.0 object.\n *\n * Pure and deterministic (the collection id is a UUIDv5 of the title), derived only from the\n * document so the collection can never disagree with the OpenAPI output. Each tag becomes a\n * folder in order of first appearance and untagged operations stay at the root; each\n * operation becomes a request with example bodies generated from its schemas and a saved\n * response per declared status. `{{baseUrl}}` and `{{token}}` are collection variables; a\n * bearer scheme becomes collection-level bearer auth and public operations opt out of it.\n */\nexport function openApiToPostmanCollection(\n  document: OpenApiDocument,\n  options: PostmanCollectionOptions = {},\n): PostmanCollection {\n  const name = options.title ?? document.info.title;\n  const baseUrl = normalizeBaseUrl(options.baseUrl ?? document.servers?.[0]?.url ?? DEFAULT_POSTMAN_BASE_URL);\n  const root: PostmanItem[] = [];\n  const folders = new Map<string, PostmanFolder>();\n\n  for (const [path, pathItem] of Object.entries(document.paths)) {\n    for (const [method, operation] of Object.entries(pathItem)) {\n      if (!OPERATION_METHODS.includes(method)) {\n        continue;\n      }\n\n      const item = buildRequestItem(path, method, operation, document);\n      const tag = operation.tags?.[0];\n\n      if (tag === undefined) {\n        root.push(item);\n\n        continue;\n      }\n\n      let folder = folders.get(tag);\n\n      if (!folder) {\n        folder = { name: tag, item: [] };\n        folders.set(tag, folder);\n        root.push(folder);\n      }\n\n      folder.item.push(item);\n    }\n  }\n\n  return {\n    info: {\n      _postman_id: uuidV5(name),\n      name,\n      ...(document.info.description ? { description: document.info.description } : {}),\n      schema: POSTMAN_COLLECTION_SCHEMA,\n    },\n    item: root,\n    ...(hasBearerScheme(document.components) ? { auth: collectionBearerAuth() } : {}),\n    variable: [\n      { key: \"baseUrl\", value: baseUrl, type: \"string\" },\n      { key: \"token\", value: \"\", type: \"string\" },\n    ],\n  };\n}\n"],"mappings":";;;;;;;;AAgBA,MAAa,4BAA4B;;AAGzC,MAAa,2BAA2B;AAExC,MAAM,oBAAoB;CAAC;CAAO;CAAO;CAAQ;CAAU;CAAW;CAAQ;CAAS;AAAO;AAE9F,SAAS,iBACP,MACA,QACA,WACA,UACoB;CACpB,MAAM,aAAa,SAAS,YAAY;CACxC,MAAM,aAAa,UAAU,cAAc,CAAC;CAC5C,MAAM,OAAO,iBAAiB,UAAU,aAAa,UAAU;CAC/D,MAAM,EAAE,MAAM,SAAS,qBAAqB,WAAW,SAAS,UAAU;CAC1E,MAAM,cAAc,CAAC,UAAU,aAAa,IAAI,CAAC,CAAC,QAAQ,SAAyB,QAAQ,IAAI,CAAC,CAAC,CAAC,KAAK,MAAM;CAE7G,MAAM,SAA0B,CAC9B,GAAI,MAAM,cAAc,CAAC;EAAE,KAAK;EAAgB,OAAO,KAAK;EAAa,MAAM;CAAgB,CAAC,IAAI,CAAC,GACrG,GAAG,sBAAsB,YAAY,UAAU,CACjD;CAEA,MAAM,kBAAkB;EACtB,QAAQ,OAAO,YAAY;EAC3B;EACA,GAAI,OAAO,EAAE,MAAM,KAAK,KAAK,IAAI,CAAC;EAClC,KAAK,gBAAgB,MAAM,YAAY,UAAU;CACnD;CAEA,OAAO;EACL,MAAM,UAAU,WAAW,UAAU;EACrC,SAAS;GACP,GAAG;GACH,GAAI,OAAO,EAAE,KAAK,IAAI,CAAC;GACvB,GAAI,cAAc,EAAE,YAAY,IAAI,CAAC;EACvC;EACA,UAAU,oBAAoB,UAAU,WAAW,iBAAiB,UAAU;CAChF;AACF;AAEA,SAAS,iBAAiB,SAAyB;CACjD,OAAO,QAAQ,QAAQ,QAAQ,EAAE;AACnC;;;;;;;;;;;AAYA,SAAgB,2BACd,UACA,UAAoC,CAAC,GAClB;CACnB,MAAM,OAAO,QAAQ,SAAS,SAAS,KAAK;CAC5C,MAAM,UAAU,iBAAiB,QAAQ,WAAW,SAAS,UAAU,EAAE,EAAE,8BAA+B;CAC1G,MAAM,OAAsB,CAAC;CAC7B,MAAM,0BAAU,IAAI,IAA2B;CAE/C,KAAK,MAAM,CAAC,MAAM,aAAa,OAAO,QAAQ,SAAS,KAAK,GAC1D,KAAK,MAAM,CAAC,QAAQ,cAAc,OAAO,QAAQ,QAAQ,GAAG;EAC1D,IAAI,CAAC,kBAAkB,SAAS,MAAM,GACpC;EAGF,MAAM,OAAO,iBAAiB,MAAM,QAAQ,WAAW,QAAQ;EAC/D,MAAM,MAAM,UAAU,OAAO;EAE7B,IAAI,QAAQ,QAAW;GACrB,KAAK,KAAK,IAAI;GAEd;EACF;EAEA,IAAI,SAAS,QAAQ,IAAI,GAAG;EAE5B,IAAI,CAAC,QAAQ;GACX,SAAS;IAAE,MAAM;IAAK,MAAM,CAAC;GAAE;GAC/B,QAAQ,IAAI,KAAK,MAAM;GACvB,KAAK,KAAK,MAAM;EAClB;EAEA,OAAO,KAAK,KAAK,IAAI;CACvB;CAGF,OAAO;EACL,MAAM;GACJ,aAAa,OAAO,IAAI;GACxB;GACA,GAAI,SAAS,KAAK,cAAc,EAAE,aAAa,SAAS,KAAK,YAAY,IAAI,CAAC;GAC9E,QAAQ;EACV;EACA,MAAM;EACN,GAAI,gBAAgB,SAAS,UAAU,IAAI,EAAE,MAAM,qBAAqB,EAAE,IAAI,CAAC;EAC/E,UAAU,CACR;GAAE,KAAK;GAAW,OAAO;GAAS,MAAM;EAAS,GACjD;GAAE,KAAK;GAAS,OAAO;GAAI,MAAM;EAAS,CAC5C;CACF;AACF"}

package/esm/openapi/postman/postman-types.d.mts

@@ -0,0 +1,119 @@
+//#region ../core/src/openapi/postman/postman-types.d.ts
+/**
+ * The slice of the Postman Collection Format v2.1.0 the converter emits.
+ * Schema: https://schema.getpostman.com/json/collection/v2.1.0/collection.json
+ */
+type PostmanVariable = {
+  key: string;
+  value: string;
+  type?: "string";
+  description?: string;
+};
+type PostmanAuthEntry = {
+  key: string;
+  value: string;
+  type: "string";
+};
+type PostmanAuth = {
+  type: "noauth";
+} | {
+  type: "bearer";
+  bearer: PostmanAuthEntry[];
+};
+type PostmanHeader = {
+  key: string;
+  value: string;
+  type?: "text";
+  description?: string;
+  disabled?: boolean;
+};
+type PostmanQueryParam = {
+  key: string;
+  value: string;
+  description?: string;
+  disabled?: boolean;
+};
+type PostmanUrl = {
+  raw: string;
+  host: string[];
+  path: string[];
+  variable?: PostmanVariable[];
+  query?: PostmanQueryParam[];
+};
+type PostmanFormParam = {
+  key: string;
+  value: string;
+  type: "text";
+  description?: string;
+} | {
+  key: string;
+  type: "file";
+  src: string[];
+  description?: string;
+};
+type PostmanBody = {
+  mode: "raw";
+  raw: string;
+  options: {
+    raw: {
+      language: "json" | "text";
+    };
+  };
+} | {
+  mode: "formdata";
+  formdata: PostmanFormParam[];
+} | {
+  mode: "urlencoded";
+  urlencoded: {
+    key: string;
+    value: string;
+    type: "text";
+  }[];
+};
+type PostmanOriginalRequest = {
+  method: string;
+  header: PostmanHeader[];
+  body?: PostmanBody;
+  url: PostmanUrl;
+};
+type PostmanRequest = PostmanOriginalRequest & {
+  auth?: PostmanAuth;
+  description?: string;
+};
+type PostmanResponse = {
+  name: string;
+  originalRequest: PostmanOriginalRequest;
+  status: string;
+  code: number;
+  _postman_previewlanguage: "json" | "html" | "text";
+  header: PostmanHeader[];
+  body: string;
+};
+type PostmanRequestItem = {
+  name: string;
+  request: PostmanRequest;
+  response: PostmanResponse[];
+};
+type PostmanFolder = {
+  name: string;
+  item: PostmanItem[];
+};
+type PostmanItem = PostmanFolder | PostmanRequestItem;
+type PostmanCollection = {
+  info: {
+    _postman_id: string;
+    name: string;
+    description?: string;
+    schema: "https://schema.getpostman.com/json/collection/v2.1.0/collection.json";
+  };
+  item: PostmanItem[];
+  auth?: PostmanAuth;
+  variable: PostmanVariable[];
+};
+type PostmanCollectionOptions = {
+  /** Collection name. Defaults to `info.title` of the document. */title?: string; /** Value of the `{{baseUrl}}` variable. Defaults to `servers[0].url`, else `http://localhost:3000`. */
+  baseUrl?: string;
+};
+//#endregion
+export { PostmanAuth, PostmanAuthEntry, PostmanBody, PostmanCollection, PostmanCollectionOptions, PostmanFolder, PostmanFormParam, PostmanHeader, PostmanItem, PostmanOriginalRequest, PostmanQueryParam, PostmanRequest, PostmanRequestItem, PostmanResponse, PostmanUrl, PostmanVariable };
+//# sourceMappingURL=postman-types.d.mts.map

package/esm/openapi/postman/postman-types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postman-types.d.mts","names":[],"sources":["../../../../../../../../core/src/openapi/postman/postman-types.ts"],"mappings":";;AAKA;;;KAAY,eAAA;EACV,GAAA;EACA,KAAA;EACA,IAAA;EACA,WAAA;AAAA;AAAA,KAGU,gBAAA;EAAqB,GAAA;EAAa,KAAA;EAAe,IAAA;AAAA;AAAA,KAEjD,WAAA;EAAgB,IAAA;AAAA;EAAqB,IAAA;EAAgB,MAAA,EAAQ,gBAAgB;AAAA;AAAA,KAE7E,aAAA;EACV,GAAA;EACA,KAAA;EACA,IAAA;EACA,WAAA;EACA,QAAA;AAAA;AAAA,KAGU,iBAAA;EACV,GAAA;EACA,KAAA;EACA,WAAA;EACA,QAAA;AAAA;AAAA,KAGU,UAAA;EACV,GAAA;EACA,IAAA;EACA,IAAA;EACA,QAAA,GAAW,eAAA;EACX,KAAA,GAAQ,iBAAiB;AAAA;AAAA,KAGf,gBAAA;EACN,GAAA;EAAa,KAAA;EAAe,IAAA;EAAc,WAAA;AAAA;EAC1C,GAAA;EAAa,IAAA;EAAc,GAAA;EAAe,WAAA;AAAA;AAAA,KAEpC,WAAA;EACN,IAAA;EAAa,GAAA;EAAa,OAAA;IAAW,GAAA;MAAO,QAAA;IAAA;EAAA;AAAA;EAC5C,IAAA;EAAkB,QAAA,EAAU,gBAAgB;AAAA;EAC5C,IAAA;EAAoB,UAAA;IAAc,GAAA;IAAa,KAAA;IAAe,IAAA;EAAA;AAAA;AAAA,KAExD,sBAAA;EACV,MAAA;EACA,MAAA,EAAQ,aAAA;EACR,IAAA,GAAO,WAAA;EACP,GAAA,EAAK,UAAA;AAAA;AAAA,KAGK,cAAA,GAAiB,sBAAA;EAC3B,IAAA,GAAO,WAAW;EAClB,WAAA;AAAA;AAAA,KAGU,eAAA;EACV,IAAA;EACA,eAAA,EAAiB,sBAAA;EACjB,MAAA;EACA,IAAA;EACA,wBAAA;EACA,MAAA,EAAQ,aAAa;EACrB,IAAA;AAAA;AAAA,KAGU,kBAAA;EACV,IAAA;EACA,OAAA,EAAS,cAAA;EACT,QAAA,EAAU,eAAe;AAAA;AAAA,KAGf,aAAA;EACV,IAAA;EACA,IAAA,EAAM,WAAW;AAAA;AAAA,KAGP,WAAA,GAAc,aAAA,GAAgB,kBAAkB;AAAA,KAEhD,iBAAA;EACV,IAAA;IACE,WAAA;IACA,IAAA;IACA,WAAA;IACA,MAAA;EAAA;EAEF,IAAA,EAAM,WAAA;EACN,IAAA,GAAO,WAAA;EACP,QAAA,EAAU,eAAA;AAAA;AAAA,KAGA,wBAAA;EA3CK,iEA6Cf,KAAA,WA1CU;EA4CV,OAAO;AAAA"}

package/esm/openapi/postman/resolve-operation-auth.mjs

@@ -0,0 +1,51 @@
+//#region ../core/src/openapi/postman/resolve-operation-auth.ts
+/** The collection-level auth: a bearer token read from the `{{token}}` variable. */
+function collectionBearerAuth() {
+	return {
+		type: "bearer",
+		bearer: [{
+			key: "token",
+			value: "{{token}}",
+			type: "string"
+		}]
+	};
+}
+function isBearer(scheme) {
+	return scheme?.type === "http" && scheme.scheme.toLowerCase() === "bearer";
+}
+/**
+* Whether the document declares an HTTP bearer scheme, which is what the collection-level
+* auth stands for.
+*/
+function hasBearerScheme(components) {
+	return Object.values(components?.securitySchemes ?? {}).some(isBearer);
+}
+/**
+* How one operation relates to the collection-level bearer auth.
+*
+* - No `security` (a public route): `noauth`, so the token is not sent.
+* - A bearer requirement: inherits the collection auth.
+* - Cookie-only: `noauth` plus a note, because Postman keeps cookies per domain instead of
+*   in collection auth.
+*/
+function resolveOperationAuth(operation, components) {
+	const bearerDocument = hasBearerScheme(components);
+	const schemes = components?.securitySchemes ?? {};
+	const names = (operation.security ?? []).flatMap((requirement) => Object.keys(requirement));
+	if (names.some((name) => isBearer(schemes[name]))) return {};
+	const cookies = names.flatMap((name) => {
+		const scheme = schemes[name];
+		return scheme?.type === "apiKey" && scheme.in === "cookie" ? [scheme.name] : [];
+	});
+	const auth = bearerDocument ? { auth: { type: "noauth" } } : {};
+	if (cookies.length === 0) return auth;
+	const cookieList = cookies.map((cookie) => `"${cookie}"`).join(", ");
+	return {
+		...auth,
+		note: `Authenticates with the ${cookieList} cookie. Postman keeps cookies per domain, so sign in against {{baseUrl}} first or add the cookie in the Cookies manager.`
+	};
+}
+
+//#endregion
+export { collectionBearerAuth, hasBearerScheme, resolveOperationAuth };
+//# sourceMappingURL=resolve-operation-auth.mjs.map

package/esm/openapi/postman/resolve-operation-auth.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-operation-auth.mjs","names":[],"sources":["../../../../../../../../core/src/openapi/postman/resolve-operation-auth.ts"],"sourcesContent":["import type { OpenApiComponents, OpenApiOperation, OpenApiSecurityScheme } from \"../types\";\nimport type { PostmanAuth } from \"./postman-types\";\n\nexport type OperationAuth = {\n  /** Set only when the operation must not inherit the collection auth. */\n  auth?: PostmanAuth;\n  /** Text appended to the request description. */\n  note?: string;\n};\n\n/** The collection-level auth: a bearer token read from the `{{token}}` variable. */\nexport function collectionBearerAuth(): PostmanAuth {\n  return { type: \"bearer\", bearer: [{ key: \"token\", value: \"{{token}}\", type: \"string\" }] };\n}\n\nfunction isBearer(scheme: OpenApiSecurityScheme | undefined): boolean {\n  return scheme?.type === \"http\" && scheme.scheme.toLowerCase() === \"bearer\";\n}\n\n/**\n * Whether the document declares an HTTP bearer scheme, which is what the collection-level\n * auth stands for.\n */\nexport function hasBearerScheme(components: OpenApiComponents | undefined): boolean {\n  return Object.values(components?.securitySchemes ?? {}).some(isBearer);\n}\n\n/**\n * How one operation relates to the collection-level bearer auth.\n *\n * - No `security` (a public route): `noauth`, so the token is not sent.\n * - A bearer requirement: inherits the collection auth.\n * - Cookie-only: `noauth` plus a note, because Postman keeps cookies per domain instead of\n *   in collection auth.\n */\nexport function resolveOperationAuth(\n  operation: OpenApiOperation,\n  components: OpenApiComponents | undefined,\n): OperationAuth {\n  const bearerDocument = hasBearerScheme(components);\n  const schemes = components?.securitySchemes ?? {};\n  const names = (operation.security ?? []).flatMap((requirement) => Object.keys(requirement));\n\n  if (names.some((name) => isBearer(schemes[name]))) {\n    return {};\n  }\n\n  const cookies = names.flatMap((name) => {\n    const scheme = schemes[name];\n\n    return scheme?.type === \"apiKey\" && scheme.in === \"cookie\" ? [scheme.name] : [];\n  });\n\n  const auth = bearerDocument ? { auth: { type: \"noauth\" } as const } : {};\n\n  if (cookies.length === 0) {\n    return auth;\n  }\n\n  const cookieList = cookies.map((cookie) => `\"${cookie}\"`).join(\", \");\n\n  return {\n    ...auth,\n    note: `Authenticates with the ${cookieList} cookie. Postman keeps cookies per domain, so sign in against {{baseUrl}} first or add the cookie in the Cookies manager.`,\n  };\n}\n"],"mappings":";;AAWA,SAAgB,uBAAoC;CAClD,OAAO;EAAE,MAAM;EAAU,QAAQ,CAAC;GAAE,KAAK;GAAS,OAAO;GAAa,MAAM;EAAS,CAAC;CAAE;AAC1F;AAEA,SAAS,SAAS,QAAoD;CACpE,OAAO,QAAQ,SAAS,UAAU,OAAO,OAAO,YAAY,MAAM;AACpE;;;;;AAMA,SAAgB,gBAAgB,YAAoD;CAClF,OAAO,OAAO,OAAO,YAAY,mBAAmB,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ;AACvE;;;;;;;;;AAUA,SAAgB,qBACd,WACA,YACe;CACf,MAAM,iBAAiB,gBAAgB,UAAU;CACjD,MAAM,UAAU,YAAY,mBAAmB,CAAC;CAChD,MAAM,SAAS,UAAU,YAAY,CAAC,EAAC,CAAE,SAAS,gBAAgB,OAAO,KAAK,WAAW,CAAC;CAE1F,IAAI,MAAM,MAAM,SAAS,SAAS,QAAQ,KAAK,CAAC,GAC9C,OAAO,CAAC;CAGV,MAAM,UAAU,MAAM,SAAS,SAAS;EACtC,MAAM,SAAS,QAAQ;EAEvB,OAAO,QAAQ,SAAS,YAAY,OAAO,OAAO,WAAW,CAAC,OAAO,IAAI,IAAI,CAAC;CAChF,CAAC;CAED,MAAM,OAAO,iBAAiB,EAAE,MAAM,EAAE,MAAM,SAAS,EAAW,IAAI,CAAC;CAEvE,IAAI,QAAQ,WAAW,GACrB,OAAO;CAGT,MAAM,aAAa,QAAQ,KAAK,WAAW,IAAI,OAAO,EAAE,CAAC,CAAC,KAAK,IAAI;CAEnE,OAAO;EACL,GAAG;EACH,MAAM,0BAA0B,WAAW;CAC7C;AACF"}

package/esm/openapi/postman/schema-refs.d.mts

@@ -0,0 +1,7 @@
+import { OpenApiSchema } from "../types.mjs";
+
+//#region ../core/src/openapi/postman/schema-refs.d.ts
+type SchemaComponents = Record<string, OpenApiSchema> | undefined;
+//#endregion
+export { SchemaComponents };
+//# sourceMappingURL=schema-refs.d.mts.map

package/esm/openapi/postman/schema-refs.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-refs.d.mts","names":[],"sources":["../../../../../../../../core/src/openapi/postman/schema-refs.ts"],"mappings":";;;KAEY,gBAAA,GAAmB,MAAM,SAAS,aAAA"}

package/esm/openapi/postman/schema-refs.mjs

@@ -0,0 +1,41 @@
+//#region ../core/src/openapi/postman/schema-refs.ts
+const REF_PREFIX = "#/components/schemas/";
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Component name a `$ref` schema points at, or `undefined` for a schema that is not a local
+* component reference.
+*/
+function refName(schema) {
+	const ref = schema.$ref;
+	return typeof ref === "string" && ref.startsWith(REF_PREFIX) ? ref.slice(21) : void 0;
+}
+/**
+* Follow `$ref`s (with a hop limit, so a ref loop cannot hang) to the schema they name.
+* An unknown component resolves to `{}`.
+*/
+function resolveSchema(schema, components) {
+	let current = schema;
+	for (let hop = 0; hop < 32; hop++) {
+		const name = refName(current);
+		if (name === void 0) return current;
+		current = components?.[name] ?? {};
+	}
+	return {};
+}
+/**
+* The effective JSON Schema type: `type`, or the first non-null member of a `type` array
+* (the 3.1 nullable form), or one inferred from `properties` / `items`.
+*/
+function primaryType(schema) {
+	const { type } = schema;
+	if (typeof type === "string") return type;
+	if (Array.isArray(type)) return type.find((member) => typeof member === "string" && member !== "null") ?? (type.includes("null") ? "null" : void 0);
+	if (isRecord(schema.properties)) return "object";
+	if (isRecord(schema.items)) return "array";
+}
+
+//#endregion
+export { isRecord, primaryType, refName, resolveSchema };
+//# sourceMappingURL=schema-refs.mjs.map

package/esm/openapi/postman/schema-refs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-refs.mjs","names":[],"sources":["../../../../../../../../core/src/openapi/postman/schema-refs.ts"],"sourcesContent":["import type { OpenApiSchema } from \"../types\";\n\nexport type SchemaComponents = Record<string, OpenApiSchema> | undefined;\n\nconst REF_PREFIX = \"#/components/schemas/\";\n\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * Component name a `$ref` schema points at, or `undefined` for a schema that is not a local\n * component reference.\n */\nexport function refName(schema: OpenApiSchema): string | undefined {\n  const ref = schema.$ref;\n\n  return typeof ref === \"string\" && ref.startsWith(REF_PREFIX) ? ref.slice(REF_PREFIX.length) : undefined;\n}\n\n/**\n * Follow `$ref`s (with a hop limit, so a ref loop cannot hang) to the schema they name.\n * An unknown component resolves to `{}`.\n */\nexport function resolveSchema(schema: OpenApiSchema, components: SchemaComponents): OpenApiSchema {\n  let current = schema;\n\n  for (let hop = 0; hop < 32; hop++) {\n    const name = refName(current);\n\n    if (name === undefined) {\n      return current;\n    }\n\n    current = components?.[name] ?? {};\n  }\n\n  return {};\n}\n\n/**\n * The effective JSON Schema type: `type`, or the first non-null member of a `type` array\n * (the 3.1 nullable form), or one inferred from `properties` / `items`.\n */\nexport function primaryType(schema: OpenApiSchema): string | undefined {\n  const { type } = schema;\n\n  if (typeof type === \"string\") {\n    return type;\n  }\n\n  if (Array.isArray(type)) {\n    const concrete = type.find((member): member is string => typeof member === \"string\" && member !== \"null\");\n\n    return concrete ?? (type.includes(\"null\") ? \"null\" : undefined);\n  }\n\n  if (isRecord(schema.properties)) {\n    return \"object\";\n  }\n\n  if (isRecord(schema.items)) {\n    return \"array\";\n  }\n\n  return undefined;\n}\n"],"mappings":";AAIA,MAAM,aAAa;AAEnB,SAAgB,SAAS,OAAkD;CACzE,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;;;;;AAMA,SAAgB,QAAQ,QAA2C;CACjE,MAAM,MAAM,OAAO;CAEnB,OAAO,OAAO,QAAQ,YAAY,IAAI,WAAW,UAAU,IAAI,IAAI,MAAM,EAAiB,IAAI;AAChG;;;;;AAMA,SAAgB,cAAc,QAAuB,YAA6C;CAChG,IAAI,UAAU;CAEd,KAAK,IAAI,MAAM,GAAG,MAAM,IAAI,OAAO;EACjC,MAAM,OAAO,QAAQ,OAAO;EAE5B,IAAI,SAAS,QACX,OAAO;EAGT,UAAU,aAAa,SAAS,CAAC;CACnC;CAEA,OAAO,CAAC;AACV;;;;;AAMA,SAAgB,YAAY,QAA2C;CACrE,MAAM,EAAE,SAAS;CAEjB,IAAI,OAAO,SAAS,UAClB,OAAO;CAGT,IAAI,MAAM,QAAQ,IAAI,GAGpB,OAFiB,KAAK,MAAM,WAA6B,OAAO,WAAW,YAAY,WAAW,MAEpF,MAAM,KAAK,SAAS,MAAM,IAAI,SAAS;CAGvD,IAAI,SAAS,OAAO,UAAU,GAC5B,OAAO;CAGT,IAAI,SAAS,OAAO,KAAK,GACvB,OAAO;AAIX"}

package/esm/openapi/postman/uuid-v5.mjs

@@ -0,0 +1,29 @@
+import { createHash } from "node:crypto";
+
+//#region ../core/src/openapi/postman/uuid-v5.ts
+/**
+* Namespace of every id the Postman converter derives. Fixed forever: changing it would
+* change the `_postman_id` of every collection already imported.
+*/
+const POSTMAN_ID_NAMESPACE = "8f1c2b64-3d7a-4c59-9a0e-5b6d1e47c2a3";
+/**
+* RFC 4122 version 5 (SHA-1, name based) UUID, so the same name always yields the same id.
+*/
+function uuidV5(name, namespace = POSTMAN_ID_NAMESPACE) {
+	const digest = createHash("sha1").update(Buffer.from(namespace.replace(/-/g, ""), "hex")).update(name, "utf8").digest();
+	const bytes = Buffer.from(digest.subarray(0, 16));
+	bytes.writeUInt8(bytes.readUInt8(6) & 15 | 80, 6);
+	bytes.writeUInt8(bytes.readUInt8(8) & 63 | 128, 8);
+	const hex = bytes.toString("hex");
+	return [
+		hex.slice(0, 8),
+		hex.slice(8, 12),
+		hex.slice(12, 16),
+		hex.slice(16, 20),
+		hex.slice(20, 32)
+	].join("-");
+}
+
+//#endregion
+export { uuidV5 };
+//# sourceMappingURL=uuid-v5.mjs.map

package/esm/openapi/postman/uuid-v5.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid-v5.mjs","names":[],"sources":["../../../../../../../../core/src/openapi/postman/uuid-v5.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\n\n/**\n * Namespace of every id the Postman converter derives. Fixed forever: changing it would\n * change the `_postman_id` of every collection already imported.\n */\nexport const POSTMAN_ID_NAMESPACE = \"8f1c2b64-3d7a-4c59-9a0e-5b6d1e47c2a3\";\n\n/**\n * RFC 4122 version 5 (SHA-1, name based) UUID, so the same name always yields the same id.\n */\nexport function uuidV5(name: string, namespace: string = POSTMAN_ID_NAMESPACE): string {\n  const digest = createHash(\"sha1\")\n    .update(Buffer.from(namespace.replace(/-/g, \"\"), \"hex\"))\n    .update(name, \"utf8\")\n    .digest();\n  const bytes = Buffer.from(digest.subarray(0, 16));\n\n  bytes.writeUInt8((bytes.readUInt8(6) & 0x0f) | 0x50, 6);\n  bytes.writeUInt8((bytes.readUInt8(8) & 0x3f) | 0x80, 8);\n\n  const hex = bytes.toString(\"hex\");\n\n  return [hex.slice(0, 8), hex.slice(8, 12), hex.slice(12, 16), hex.slice(16, 20), hex.slice(20, 32)].join(\"-\");\n}\n"],"mappings":";;;;;;;AAMA,MAAa,uBAAuB;;;;AAKpC,SAAgB,OAAO,MAAc,YAAoB,sBAA8B;CACrF,MAAM,SAAS,WAAW,MAAM,CAAC,CAC9B,OAAO,OAAO,KAAK,UAAU,QAAQ,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CACvD,OAAO,MAAM,MAAM,CAAC,CACpB,OAAO;CACV,MAAM,QAAQ,OAAO,KAAK,OAAO,SAAS,GAAG,EAAE,CAAC;CAEhD,MAAM,WAAY,MAAM,UAAU,CAAC,IAAI,KAAQ,IAAM,CAAC;CACtD,MAAM,WAAY,MAAM,UAAU,CAAC,IAAI,KAAQ,KAAM,CAAC;CAEtD,MAAM,MAAM,MAAM,SAAS,KAAK;CAEhC,OAAO;EAAC,IAAI,MAAM,GAAG,CAAC;EAAG,IAAI,MAAM,GAAG,EAAE;EAAG,IAAI,MAAM,IAAI,EAAE;EAAG,IAAI,MAAM,IAAI,EAAE;EAAG,IAAI,MAAM,IAAI,EAAE;CAAC,CAAC,CAAC,KAAK,GAAG;AAC9G"}

package/esm/openapi/request-schemas.mjs

@@ -0,0 +1,138 @@
+import { extractPathParamNames, isBodylessMethod } from "./paths.mjs";
+
+//#region ../core/src/openapi/request-schemas.ts
+const VALIDATING_LOCATIONS = [
+	"body",
+	"query",
+	"params",
+	"headers"
+];
+/**
+* Convert a Seal validator to a JSON Schema object (`draft-2020-12`, the OpenAPI 3.1 dialect)
+* and split it into properties and required keys. Never throws: a validator that cannot be
+* converted is reported through `warn` and yields `undefined`.
+*/
+function readObjectSchema(validator, what, warn) {
+	const convert = validator?.toJsonSchema;
+	if (typeof convert !== "function") return;
+	let schema;
+	try {
+		schema = convert.call(validator, "draft-2020-12");
+	} catch (error) {
+		warn(`${what} could not be converted to JSON Schema and is not documented: ${error instanceof Error ? error.message : String(error)}`);
+		return;
+	}
+	const properties = schema?.properties;
+	if (typeof schema !== "object" || schema === null || !isRecord(properties)) {
+		warn(`${what} is not an object schema and is not documented.`);
+		return;
+	}
+	const required = schema.required;
+	return {
+		schema,
+		properties,
+		required: new Set(Array.isArray(required) ? required.filter((key) => typeof key === "string") : [])
+	};
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function describeParameter(name, location, schema, required) {
+	const parameter = {
+		name,
+		in: location,
+		required,
+		schema
+	};
+	if (typeof schema.description === "string") parameter.description = schema.description;
+	if (location === "query" && schema.type === "object") {
+		parameter.style = "deepObject";
+		parameter.explode = true;
+	}
+	return parameter;
+}
+/**
+* Where an unscoped or scoped `validating` puts the non-path properties.
+*
+* `validateAll` merges body and query (unset) or exactly the listed sources. The OpenAPI
+* placement follows: unset -> by method, a single source -> that source, `body` + `query`
+* -> body for verbs that carry one, query for the rest (and a warning, it is ambiguous).
+*/
+function resolvePrimaryLocation(method, validating, warn) {
+	if (validating.length === 0) return isBodylessMethod(method) ? "query" : "body";
+	const hasBody = validating.includes("body");
+	const hasQuery = validating.includes("query");
+	if (hasBody && hasQuery) {
+		warn(`validating lists both "body" and "query"; the properties are documented as ${isBodylessMethod(method) ? "query parameters" : "the request body"}.`);
+		return isBodylessMethod(method) ? "query" : "body";
+	}
+	if (hasBody) return "body";
+	if (hasQuery) return "query";
+	if (validating.includes("headers")) return "header";
+}
+/**
+* Map a handler's `validation` to OpenAPI parameters and a request body.
+*
+* - `validation.params` -> one required path parameter per property.
+* - Path segments without a declared schema -> required string path parameters.
+* - `validation.schema` -> request body (verbs that carry one) or query parameters, placed by
+*   `validating` exactly as `validateAll` reads the request; a property named like a path
+*   segment is a path parameter whenever `params` is validated (unset counts).
+*/
+function buildRequestParts(input) {
+	const { method, path, validation, warn } = input;
+	const validating = (validation?.validating ?? []).filter((location) => VALIDATING_LOCATIONS.includes(location));
+	const pathNames = extractPathParamNames(path);
+	const paramsSchema = validation?.params ? readObjectSchema(validation.params, "validation.params", warn) : void 0;
+	const mainSchema = validation?.schema ? readObjectSchema(validation.schema, "validation.schema", warn) : void 0;
+	const pathSchemas = /* @__PURE__ */ new Map();
+	const primary = resolvePrimaryLocation(method, validating, warn);
+	const takesPathNames = validating.length === 0 || validating.includes("params");
+	const located = {
+		body: [],
+		query: [],
+		header: []
+	};
+	if (paramsSchema) {
+		for (const name of pathNames) if (paramsSchema.properties[name]) pathSchemas.set(name, paramsSchema.properties[name]);
+	}
+	if (mainSchema) for (const [key, propertySchema] of Object.entries(mainSchema.properties)) {
+		if (takesPathNames && pathNames.includes(key)) {
+			if (!pathSchemas.has(key)) pathSchemas.set(key, propertySchema);
+			continue;
+		}
+		if (!primary) {
+			warn(`validation.schema property "${key}" is not a path parameter and is not documented.`);
+			continue;
+		}
+		located[primary].push({
+			key,
+			schema: propertySchema
+		});
+	}
+	const requiredKeys = mainSchema?.required ?? /* @__PURE__ */ new Set();
+	const parameters = pathNames.map((name) => describeParameter(name, "path", pathSchemas.get(name) ?? { type: "string" }, true));
+	for (const { key, schema } of located.query) parameters.push(describeParameter(key, "query", schema, requiredKeys.has(key)));
+	for (const { key, schema } of located.header) parameters.push(describeParameter(key.toLowerCase(), "header", schema, requiredKeys.has(key)));
+	if (located.body.length === 0 || !mainSchema) return { parameters };
+	const properties = {};
+	for (const { key, schema } of located.body) properties[key] = schema;
+	const required = located.body.filter(({ key }) => mainSchema.required.has(key)).map(({ key }) => key);
+	const bodySchema = {
+		...mainSchema.schema,
+		properties
+	};
+	if (required.length > 0) bodySchema.required = required;
+	else delete bodySchema.required;
+	return {
+		parameters,
+		requestBody: {
+			required: required.length > 0,
+			content: { "application/json": { schema: bodySchema } }
+		}
+	};
+}
+
+//#endregion
+export { buildRequestParts };
+//# sourceMappingURL=request-schemas.mjs.map

package/esm/openapi/request-schemas.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-schemas.mjs","names":[],"sources":["../../../../../../../core/src/openapi/request-schemas.ts"],"sourcesContent":["import type { RequestHandlerValidation } from \"../router/types\";\nimport { extractPathParamNames, isBodylessMethod, type OpenApiMethod } from \"./paths\";\nimport type {\n  OpenApiParameter,\n  OpenApiRequestBody,\n  OpenApiSchema,\n  WarningSink,\n} from \"./types\";\n\ntype ValidatingLocation = \"body\" | \"query\" | \"params\" | \"headers\";\n\ntype ObjectSchemaParts = {\n  schema: OpenApiSchema;\n  properties: Record<string, OpenApiSchema>;\n  required: Set<string>;\n};\n\n/** A `validation.schema` property placed in a request location, with its JSON Schema. */\ntype LocatedProperty = {\n  key: string;\n  schema: OpenApiSchema;\n};\n\nexport type RequestParts = {\n  parameters: OpenApiParameter[];\n  requestBody?: OpenApiRequestBody;\n};\n\nexport type BuildRequestPartsInput = {\n  method: OpenApiMethod;\n  /** Warlock path, with `:param` segments. */\n  path: string;\n  validation: RequestHandlerValidation | undefined;\n  warn: WarningSink;\n};\n\nconst VALIDATING_LOCATIONS: readonly string[] = [\"body\", \"query\", \"params\", \"headers\"];\n\n/**\n * Convert a Seal validator to a JSON Schema object (`draft-2020-12`, the OpenAPI 3.1 dialect)\n * and split it into properties and required keys. Never throws: a validator that cannot be\n * converted is reported through `warn` and yields `undefined`.\n */\nfunction readObjectSchema(\n  validator: unknown,\n  what: string,\n  warn: WarningSink,\n): ObjectSchemaParts | undefined {\n  const convert = (validator as { toJsonSchema?: unknown } | undefined)?.toJsonSchema;\n\n  if (typeof convert !== \"function\") {\n    return undefined;\n  }\n\n  let schema: unknown;\n\n  try {\n    schema = convert.call(validator, \"draft-2020-12\");\n  } catch (error) {\n    warn(\n      `${what} could not be converted to JSON Schema and is not documented: ${\n        error instanceof Error ? error.message : String(error)\n      }`,\n    );\n\n    return undefined;\n  }\n\n  const properties = (schema as { properties?: unknown } | undefined)?.properties;\n\n  if (typeof schema !== \"object\" || schema === null || !isRecord(properties)) {\n    warn(`${what} is not an object schema and is not documented.`);\n\n    return undefined;\n  }\n\n  const required = (schema as { required?: unknown }).required;\n\n  return {\n    schema: schema as OpenApiSchema,\n    properties: properties as Record<string, OpenApiSchema>,\n    required: new Set(Array.isArray(required) ? required.filter((key) => typeof key === \"string\") : []),\n  };\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction describeParameter(\n  name: string,\n  location: OpenApiParameter[\"in\"],\n  schema: OpenApiSchema,\n  required: boolean,\n): OpenApiParameter {\n  const parameter: OpenApiParameter = { name, in: location, required, schema };\n\n  if (typeof schema.description === \"string\") {\n    parameter.description = schema.description;\n  }\n\n  if (location === \"query\" && schema.type === \"object\") {\n    parameter.style = \"deepObject\";\n    parameter.explode = true;\n  }\n\n  return parameter;\n}\n\n/**\n * Where an unscoped or scoped `validating` puts the non-path properties.\n *\n * `validateAll` merges body and query (unset) or exactly the listed sources. The OpenAPI\n * placement follows: unset -> by method, a single source -> that source, `body` + `query`\n * -> body for verbs that carry one, query for the rest (and a warning, it is ambiguous).\n */\nfunction resolvePrimaryLocation(\n  method: OpenApiMethod,\n  validating: ValidatingLocation[],\n  warn: WarningSink,\n): \"body\" | \"query\" | \"header\" | undefined {\n  if (validating.length === 0) {\n    return isBodylessMethod(method) ? \"query\" : \"body\";\n  }\n\n  const hasBody = validating.includes(\"body\");\n  const hasQuery = validating.includes(\"query\");\n\n  if (hasBody && hasQuery) {\n    warn(\n      `validating lists both \"body\" and \"query\"; the properties are documented as ${\n        isBodylessMethod(method) ? \"query parameters\" : \"the request body\"\n      }.`,\n    );\n\n    return isBodylessMethod(method) ? \"query\" : \"body\";\n  }\n\n  if (hasBody) {\n    return \"body\";\n  }\n\n  if (hasQuery) {\n    return \"query\";\n  }\n\n  if (validating.includes(\"headers\")) {\n    return \"header\";\n  }\n\n  return undefined;\n}\n\n/**\n * Map a handler's `validation` to OpenAPI parameters and a request body.\n *\n * - `validation.params` -> one required path parameter per property.\n * - Path segments without a declared schema -> required string path parameters.\n * - `validation.schema` -> request body (verbs that carry one) or query parameters, placed by\n *   `validating` exactly as `validateAll` reads the request; a property named like a path\n *   segment is a path parameter whenever `params` is validated (unset counts).\n */\nexport function buildRequestParts(input: BuildRequestPartsInput): RequestParts {\n  const { method, path, validation, warn } = input;\n  const validating = (validation?.validating ?? []).filter((location): location is ValidatingLocation =>\n    VALIDATING_LOCATIONS.includes(location),\n  );\n  const pathNames = extractPathParamNames(path);\n\n  const paramsSchema = validation?.params\n    ? readObjectSchema(validation.params, \"validation.params\", warn)\n    : undefined;\n  const mainSchema = validation?.schema\n    ? readObjectSchema(validation.schema, \"validation.schema\", warn)\n    : undefined;\n\n  const pathSchemas = new Map<string, OpenApiSchema>();\n  const primary = resolvePrimaryLocation(method, validating, warn);\n  const takesPathNames = validating.length === 0 || validating.includes(\"params\");\n\n  const located: Record<\"body\" | \"query\" | \"header\", LocatedProperty[]> = {\n    body: [],\n    query: [],\n    header: [],\n  };\n\n  if (paramsSchema) {\n    for (const name of pathNames) {\n      if (paramsSchema.properties[name]) {\n        pathSchemas.set(name, paramsSchema.properties[name]);\n      }\n    }\n  }\n\n  if (mainSchema) {\n    for (const [key, propertySchema] of Object.entries(mainSchema.properties)) {\n      if (takesPathNames && pathNames.includes(key)) {\n        if (!pathSchemas.has(key)) {\n          pathSchemas.set(key, propertySchema);\n        }\n\n        continue;\n      }\n\n      if (!primary) {\n        warn(`validation.schema property \"${key}\" is not a path parameter and is not documented.`);\n\n        continue;\n      }\n\n      located[primary].push({ key, schema: propertySchema });\n    }\n  }\n\n  const requiredKeys = mainSchema?.required ?? new Set<string>();\n\n  const parameters: OpenApiParameter[] = pathNames.map((name) =>\n    describeParameter(name, \"path\", pathSchemas.get(name) ?? { type: \"string\" }, true),\n  );\n\n  for (const { key, schema } of located.query) {\n    parameters.push(describeParameter(key, \"query\", schema, requiredKeys.has(key)));\n  }\n\n  for (const { key, schema } of located.header) {\n    parameters.push(describeParameter(key.toLowerCase(), \"header\", schema, requiredKeys.has(key)));\n  }\n\n  if (located.body.length === 0 || !mainSchema) {\n    return { parameters };\n  }\n\n  const properties: Record<string, OpenApiSchema> = {};\n\n  for (const { key, schema } of located.body) {\n    properties[key] = schema;\n  }\n\n  const required = located.body.filter(({ key }) => mainSchema.required.has(key)).map(({ key }) => key);\n  const bodySchema: OpenApiSchema = { ...mainSchema.schema, properties };\n\n  if (required.length > 0) {\n    bodySchema.required = required;\n  } else {\n    delete bodySchema.required;\n  }\n\n  return {\n    parameters,\n    requestBody: {\n      required: required.length > 0,\n      content: { \"application/json\": { schema: bodySchema } },\n    },\n  };\n}\n"],"mappings":"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"}

package/esm/openapi/response-schemas.mjs

@@ -0,0 +1,85 @@
+//#region ../core/src/openapi/response-schemas.ts
+const STATUS_TEXT = {
+	"200": "Successful response",
+	"201": "Created",
+	"202": "Accepted",
+	"204": "No content",
+	"301": "Moved permanently",
+	"302": "Found",
+	"304": "Not modified",
+	"400": "Bad request",
+	"401": "Unauthorized",
+	"403": "Forbidden",
+	"404": "Not found",
+	"405": "Method not allowed",
+	"409": "Conflict",
+	"410": "Gone",
+	"422": "Validation failed",
+	"429": "Too many requests",
+	"500": "Internal server error",
+	"503": "Service unavailable"
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Human description of a status code for the required `description` of a response.
+*/
+function describeStatus(status) {
+	return STATUS_TEXT[status] ?? `Status ${status}`;
+}
+/**
+* JSON Schema of one response body value: a cast string, a resource class, `[Resource]`
+* (array of it) or a nested plain object of those. Anything else (a resolver function, a
+* builder) is `{}` plus a warning.
+*/
+function bodyValueSchema(value, path, registry, warn) {
+	if (typeof value === "string") return registry.cast(value, path, warn);
+	if (typeof value === "function") {
+		if (registry.isResourceClass(value)) return registry.resourceRef(value);
+		warn(`${path}: a function that is not a resource class has no static shape and is documented as {}.`);
+		return {};
+	}
+	if (Array.isArray(value)) return {
+		type: "array",
+		items: bodyValueSchema(value[0], `${path}[]`, registry, warn)
+	};
+	if (isRecord(value)) return objectSchema(value, path, registry, warn);
+	warn(`${path}: unsupported response value is documented as {}.`);
+	return {};
+}
+function objectSchema(body, path, registry, warn) {
+	const properties = {};
+	for (const [key, member] of Object.entries(body)) properties[key] = bodyValueSchema(member, `${path}.${key}`, registry, warn);
+	return {
+		type: "object",
+		properties,
+		required: Object.keys(properties)
+	};
+}
+/**
+* Map a handler's `responseSchema` to OpenAPI responses, one per declared status code.
+*
+* `routeLabel` prefixes warnings (for example `POST /login`). A status without a usable
+* `body` becomes a description-only response.
+*/
+function buildDeclaredResponses(responseSchema, registry, warn) {
+	const responses = {};
+	if (!isRecord(responseSchema)) return responses;
+	for (const [status, entry] of Object.entries(responseSchema)) {
+		const body = isRecord(entry) ? entry.body : void 0;
+		if (!isRecord(body)) {
+			responses[status] = { description: describeStatus(status) };
+			continue;
+		}
+		responses[status] = {
+			description: describeStatus(status),
+			content: { "application/json": { schema: objectSchema(body, `response ${status}`, registry, warn) } }
+		};
+	}
+	return responses;
+}
+
+//#endregion
+export { buildDeclaredResponses, describeStatus };
+//# sourceMappingURL=response-schemas.mjs.map