@seshuk/payload-plugin-openapi 0.2.2 → 1.0.0-beta.1

package/dist/server/endpoints/spec.d.ts

@@ -0,0 +1,5 @@
+import { ResolvedOptions } from "../../shared/types/index.js";
+import { PayloadHandler } from "payload";
+type SpecHandler = (options: ResolvedOptions) => PayloadHandler;
+export declare const specHandler: SpecHandler;
+//# sourceMappingURL=spec.d.ts.map

package/dist/server/endpoints/spec.js

@@ -0,0 +1,39 @@
+import { buildOpenApiDocument, staticServers } from "../spec/build.js";
+import { Forbidden } from "payload";
+const requestServers = async (req, options) => {
+	if (typeof options.servers === "function") return options.servers({ req });
+	const host = req.headers.get("host")?.toLowerCase();
+	if (!options.servers && host && options.trustedHosts.includes(host)) return [{ url: `${host.startsWith("localhost") || host.startsWith("127.") ? "http" : "https"}://${host}` }];
+	return staticServers(options, req.payload.config);
+};
+const requestedLang = (req) => {
+	const raw = new URL(req.url ?? "", "http://localhost").searchParams.get("lang");
+	if (!raw) return void 0;
+	const supported = req.payload.config.i18n?.supportedLanguages;
+	return !supported || raw in supported ? raw : void 0;
+};
+const specHandler = (options) => {
+	const cache = /* @__PURE__ */ new Map();
+	return async (req) => {
+		if (options.access && await options.access({ req }) !== true) throw new Forbidden(req.t);
+		const requested = requestedLang(req);
+		const lang = requested ?? req.i18n?.language ?? req.payload.config.i18n?.fallbackLanguage ?? "en";
+		let doc = cache.get(lang);
+		if (!options.cache || !doc) {
+			doc = await buildOpenApiDocument({
+				payload: req.payload,
+				options,
+				language: lang,
+				i18n: requested ? void 0 : req.i18n
+			});
+			cache.set(lang, doc);
+		}
+		return Response.json({
+			...doc,
+			servers: await requestServers(req, options)
+		});
+	};
+};
+export { specHandler };
+
+//# sourceMappingURL=spec.js.map

package/dist/server/endpoints/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","names":[],"sources":["../../../src/server/endpoints/spec.ts"],"sourcesContent":["import type { Document, ServerObject } from '@scalar/openapi-types/3.2'\nimport { Forbidden } from 'payload'\nimport type { PayloadHandler, PayloadRequest } from 'payload'\n\nimport { buildOpenApiDocument, staticServers } from '@/server/spec/build.js'\nimport type { ResolvedOptions } from '@/shared/types/index.js'\n\ntype SpecHandler = (options: ResolvedOptions) => PayloadHandler\n\nconst requestServers = async (req: PayloadRequest, options: ResolvedOptions): Promise<ServerObject[]> => {\n  if (typeof options.servers === 'function') return options.servers({ req })\n  const host = req.headers.get('host')?.toLowerCase()\n  if (!options.servers && host && options.trustedHosts.includes(host)) {\n    const protocol = host.startsWith('localhost') || host.startsWith('127.') ? 'http' : 'https'\n    return [{ url: `${protocol}://${host}` }]\n  }\n  return staticServers(options, req.payload.config)\n}\n\nconst requestedLang = (req: PayloadRequest): string | undefined => {\n  const raw = new URL(req.url ?? '', 'http://localhost').searchParams.get('lang')\n  if (!raw) return undefined\n  const supported = req.payload.config.i18n?.supportedLanguages\n  return !supported || raw in supported ? raw : undefined\n}\n\nexport const specHandler: SpecHandler = (options) => {\n  const cache = new Map<string, Document>()\n\n  return async (req: PayloadRequest) => {\n    if (options.access && (await options.access({ req })) !== true) throw new Forbidden(req.t)\n    const requested = requestedLang(req)\n    const lang = requested ?? req.i18n?.language ?? req.payload.config.i18n?.fallbackLanguage ?? 'en'\n\n    let doc = cache.get(lang)\n    if (!options.cache || !doc) {\n      doc = await buildOpenApiDocument({\n        payload: req.payload,\n        options,\n        language: lang,\n        i18n: requested ? undefined : req.i18n,\n      })\n      cache.set(lang, doc)\n    }\n    return Response.json({ ...doc, servers: await requestServers(req, options) })\n  }\n}\n"],"mappings":";;AASA,MAAM,iBAAiB,OAAO,KAAqB,YAAsD;CACvG,IAAI,OAAO,QAAQ,YAAY,YAAY,OAAO,QAAQ,QAAQ,EAAE,IAAI,CAAC;CACzE,MAAM,OAAO,IAAI,QAAQ,IAAI,MAAM,CAAC,EAAE,YAAY;CAClD,IAAI,CAAC,QAAQ,WAAW,QAAQ,QAAQ,aAAa,SAAS,IAAI,GAEhE,OAAO,CAAC,EAAE,KAAK,GADE,KAAK,WAAW,WAAW,KAAK,KAAK,WAAW,MAAM,IAAI,SAAS,QACzD,KAAK,OAAO,CAAC;CAE1C,OAAO,cAAc,SAAS,IAAI,QAAQ,MAAM;AAClD;AAEA,MAAM,iBAAiB,QAA4C;CACjE,MAAM,MAAM,IAAI,IAAI,IAAI,OAAO,IAAI,kBAAkB,CAAC,CAAC,aAAa,IAAI,MAAM;CAC9E,IAAI,CAAC,KAAK,OAAO,KAAA;CACjB,MAAM,YAAY,IAAI,QAAQ,OAAO,MAAM;CAC3C,OAAO,CAAC,aAAa,OAAO,YAAY,MAAM,KAAA;AAChD;AAEA,MAAa,eAA4B,YAAY;CACnD,MAAM,wBAAQ,IAAI,IAAsB;CAExC,OAAO,OAAO,QAAwB;EACpC,IAAI,QAAQ,UAAW,MAAM,QAAQ,OAAO,EAAE,IAAI,CAAC,MAAO,MAAM,MAAM,IAAI,UAAU,IAAI,CAAC;EACzF,MAAM,YAAY,cAAc,GAAG;EACnC,MAAM,OAAO,aAAa,IAAI,MAAM,YAAY,IAAI,QAAQ,OAAO,MAAM,oBAAoB;EAE7F,IAAI,MAAM,MAAM,IAAI,IAAI;EACxB,IAAI,CAAC,QAAQ,SAAS,CAAC,KAAK;GAC1B,MAAM,MAAM,qBAAqB;IAC/B,SAAS,IAAI;IACb;IACA,UAAU;IACV,MAAM,YAAY,KAAA,IAAY,IAAI;GACpC,CAAC;GACD,MAAM,IAAI,MAAM,GAAG;EACrB;EACA,OAAO,SAAS,KAAK;GAAE,GAAG;GAAK,SAAS,MAAM,eAAe,KAAK,OAAO;EAAE,CAAC;CAC9E;AACF"}

package/dist/server/options/resolveOptions.d.ts

@@ -0,0 +1,4 @@
+import { OpenApiPluginOptions, ResolvedOptions } from "../../shared/types/index.js";
+export declare const assertNoRemovedKeys: (removed: Array<[unknown, string]>) => void;
+export declare const resolveOptions: (options: OpenApiPluginOptions) => ResolvedOptions;
+//# sourceMappingURL=resolveOptions.d.ts.map

package/dist/server/options/resolveOptions.js

@@ -0,0 +1,65 @@
+import { isPlainObject } from "../../shared/utils.js";
+import { PLUGIN_NAME } from "../../shared/constants.js";
+const resolveFilters = (filters = {}) => ({
+	include: filters.include ?? [],
+	exclude: filters.exclude ?? [],
+	includeHidden: filters.includeHidden ?? false,
+	includeSystem: filters.includeSystem ?? false,
+	includeCustom: filters.includeCustom ?? true,
+	includeAuth: filters.includeAuth ?? true,
+	includeAdminAuth: filters.includeAdminAuth ?? false,
+	includeVersions: filters.includeVersions ?? true,
+	includeJobs: filters.includeJobs ?? true,
+	excludeOperations: filters.excludeOperations ?? []
+});
+const DEFAULT_AUTH_PATH = "/openapi-auth";
+const resolveInteractiveAuth = (option) => {
+	if (!option) return {
+		enabled: false,
+		path: DEFAULT_AUTH_PATH
+	};
+	if (option === true) return {
+		enabled: true,
+		path: DEFAULT_AUTH_PATH
+	};
+	return {
+		enabled: true,
+		path: option.path ?? DEFAULT_AUTH_PATH,
+		collection: option.collection
+	};
+};
+const assertNoRemovedKeys = (removed) => {
+	for (const [value, message] of removed) if (value !== void 0) throw new Error(`[${PLUGIN_NAME}] ${message}`);
+};
+const resolveOptions = (options) => {
+	const legacy = options;
+	const legacyFilters = isPlainObject(legacy.filters) ? legacy.filters : {};
+	const legacyAuth = isPlainObject(legacy.interactiveAuth) ? legacy.interactiveAuth : {};
+	assertNoRemovedKeys([
+		[legacy.metadata, "metadata was renamed to info"],
+		[legacy.specEndpoint, "specEndpoint was renamed to path"],
+		[legacy.securityWhen, "securityWhen was removed, use security (return 'public' or 'secured', not true or false)"],
+		[legacyFilters.excludeWhen, "filters.excludeWhen was removed, use a function in filters.excludeOperations"],
+		[legacyAuth.endpoint, "interactiveAuth.endpoint was renamed to interactiveAuth.path"],
+		[options.extensions?.some((extension) => (extension.transform?.length ?? 0) > 1) || void 0, "extensions[].transform takes one object now, use ({ doc, payload }) instead of (doc, ctx)"]
+	]);
+	if (!options.info?.title || !options.info?.version) throw new Error(`[${PLUGIN_NAME}] info.title and info.version are required`);
+	return {
+		info: options.info,
+		openapiVersion: options.openapiVersion ?? "3.2",
+		path: options.path ?? "/openapi.json",
+		serve: options.serve ?? true,
+		access: options.access,
+		servers: options.servers,
+		trustedHosts: (options.trustedHosts ?? []).map((host) => host.toLowerCase()),
+		filters: resolveFilters(options.filters),
+		interactiveAuth: resolveInteractiveAuth(options.interactiveAuth),
+		nestedTags: options.nestedTags ?? false,
+		security: options.security,
+		cache: options.cache ?? true,
+		extensions: options.extensions ?? []
+	};
+};
+export { assertNoRemovedKeys, resolveOptions };
+
+//# sourceMappingURL=resolveOptions.js.map

package/dist/server/options/resolveOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveOptions.js","names":[],"sources":["../../../src/server/options/resolveOptions.ts"],"sourcesContent":["import { PLUGIN_NAME } from '@/shared/constants.js'\nimport type { FilterOptions, OpenApiPluginOptions, ResolvedFilters, ResolvedOptions } from '@/shared/types/index.js'\nimport { isPlainObject } from '@/shared/utils.js'\n\nconst resolveFilters = (filters: FilterOptions = {}): ResolvedFilters => ({\n  include: filters.include ?? [],\n  exclude: filters.exclude ?? [],\n  includeHidden: filters.includeHidden ?? false,\n  includeSystem: filters.includeSystem ?? false,\n  includeCustom: filters.includeCustom ?? true,\n  includeAuth: filters.includeAuth ?? true,\n  includeAdminAuth: filters.includeAdminAuth ?? false,\n  includeVersions: filters.includeVersions ?? true,\n  includeJobs: filters.includeJobs ?? true,\n  excludeOperations: filters.excludeOperations ?? [],\n})\n\nconst DEFAULT_AUTH_PATH = '/openapi-auth'\n\nconst resolveInteractiveAuth = (\n  option: OpenApiPluginOptions['interactiveAuth'],\n): ResolvedOptions['interactiveAuth'] => {\n  if (!option) return { enabled: false, path: DEFAULT_AUTH_PATH }\n  if (option === true) return { enabled: true, path: DEFAULT_AUTH_PATH }\n  return { enabled: true, path: option.path ?? DEFAULT_AUTH_PATH, collection: option.collection }\n}\n\nexport const assertNoRemovedKeys = (removed: Array<[unknown, string]>): void => {\n  for (const [value, message] of removed) {\n    if (value !== undefined) throw new Error(`[${PLUGIN_NAME}] ${message}`)\n  }\n}\n\nexport const resolveOptions = (options: OpenApiPluginOptions): ResolvedOptions => {\n  const legacy = options as Record<string, unknown>\n  const legacyFilters = isPlainObject(legacy.filters) ? legacy.filters : {}\n  const legacyAuth = isPlainObject(legacy.interactiveAuth) ? legacy.interactiveAuth : {}\n  assertNoRemovedKeys([\n    [legacy.metadata, 'metadata was renamed to info'],\n    [legacy.specEndpoint, 'specEndpoint was renamed to path'],\n    [legacy.securityWhen, \"securityWhen was removed, use security (return 'public' or 'secured', not true or false)\"],\n    [legacyFilters.excludeWhen, 'filters.excludeWhen was removed, use a function in filters.excludeOperations'],\n    [legacyAuth.endpoint, 'interactiveAuth.endpoint was renamed to interactiveAuth.path'],\n    [\n      options.extensions?.some((extension) => (extension.transform?.length ?? 0) > 1) || undefined,\n      'extensions[].transform takes one object now, use ({ doc, payload }) instead of (doc, ctx)',\n    ],\n  ])\n\n  if (!options.info?.title || !options.info?.version) {\n    throw new Error(`[${PLUGIN_NAME}] info.title and info.version are required`)\n  }\n\n  return {\n    info: options.info,\n    openapiVersion: options.openapiVersion ?? '3.2',\n    path: options.path ?? '/openapi.json',\n    serve: options.serve ?? true,\n    access: options.access,\n    servers: options.servers,\n    trustedHosts: (options.trustedHosts ?? []).map((host) => host.toLowerCase()),\n    filters: resolveFilters(options.filters),\n    interactiveAuth: resolveInteractiveAuth(options.interactiveAuth),\n    nestedTags: options.nestedTags ?? false,\n    security: options.security,\n    cache: options.cache ?? true,\n    extensions: options.extensions ?? [],\n  }\n}\n"],"mappings":";;AAIA,MAAM,kBAAkB,UAAyB,CAAC,OAAwB;CACxE,SAAS,QAAQ,WAAW,CAAC;CAC7B,SAAS,QAAQ,WAAW,CAAC;CAC7B,eAAe,QAAQ,iBAAiB;CACxC,eAAe,QAAQ,iBAAiB;CACxC,eAAe,QAAQ,iBAAiB;CACxC,aAAa,QAAQ,eAAe;CACpC,kBAAkB,QAAQ,oBAAoB;CAC9C,iBAAiB,QAAQ,mBAAmB;CAC5C,aAAa,QAAQ,eAAe;CACpC,mBAAmB,QAAQ,qBAAqB,CAAC;AACnD;AAEA,MAAM,oBAAoB;AAE1B,MAAM,0BACJ,WACuC;CACvC,IAAI,CAAC,QAAQ,OAAO;EAAE,SAAS;EAAO,MAAM;CAAkB;CAC9D,IAAI,WAAW,MAAM,OAAO;EAAE,SAAS;EAAM,MAAM;CAAkB;CACrE,OAAO;EAAE,SAAS;EAAM,MAAM,OAAO,QAAQ;EAAmB,YAAY,OAAO;CAAW;AAChG;AAEA,MAAa,uBAAuB,YAA4C;CAC9E,KAAK,MAAM,CAAC,OAAO,YAAY,SAC7B,IAAI,UAAU,KAAA,GAAW,MAAM,IAAI,MAAM,IAAI,YAAY,IAAI,SAAS;AAE1E;AAEA,MAAa,kBAAkB,YAAmD;CAChF,MAAM,SAAS;CACf,MAAM,gBAAgB,cAAc,OAAO,OAAO,IAAI,OAAO,UAAU,CAAC;CACxE,MAAM,aAAa,cAAc,OAAO,eAAe,IAAI,OAAO,kBAAkB,CAAC;CACrF,oBAAoB;EAClB,CAAC,OAAO,UAAU,8BAA8B;EAChD,CAAC,OAAO,cAAc,kCAAkC;EACxD,CAAC,OAAO,cAAc,0FAA0F;EAChH,CAAC,cAAc,aAAa,8EAA8E;EAC1G,CAAC,WAAW,UAAU,8DAA8D;EACpF,CACE,QAAQ,YAAY,MAAM,eAAe,UAAU,WAAW,UAAU,KAAK,CAAC,KAAK,KAAA,GACnF,2FACF;CACF,CAAC;CAED,IAAI,CAAC,QAAQ,MAAM,SAAS,CAAC,QAAQ,MAAM,SACzC,MAAM,IAAI,MAAM,IAAI,YAAY,2CAA2C;CAG7E,OAAO;EACL,MAAM,QAAQ;EACd,gBAAgB,QAAQ,kBAAkB;EAC1C,MAAM,QAAQ,QAAQ;EACtB,OAAO,QAAQ,SAAS;EACxB,QAAQ,QAAQ;EAChB,SAAS,QAAQ;EACjB,eAAe,QAAQ,gBAAgB,CAAC,EAAA,CAAG,KAAK,SAAS,KAAK,YAAY,CAAC;EAC3E,SAAS,eAAe,QAAQ,OAAO;EACvC,iBAAiB,uBAAuB,QAAQ,eAAe;EAC/D,YAAY,QAAQ,cAAc;EAClC,UAAU,QAAQ;EAClB,OAAO,QAAQ,SAAS;EACxB,YAAY,QAAQ,cAAc,CAAC;CACrC;AACF"}

package/dist/server/spec/build.d.ts

@@ -0,0 +1,14 @@
+import { ResolvedOptions } from "../../shared/types/index.js";
+import { BasePayload, SanitizedConfig } from "payload";
+import { I18n } from "@payloadcms/translations";
+import { Document, ServerObject } from "@scalar/openapi-types/3.2";
+export interface BuildOpenApiInput {
+  payload: BasePayload;
+  options: ResolvedOptions;
+  language?: string;
+  i18n?: I18n;
+  servers?: ServerObject[];
+}
+export declare const staticServers: (options: ResolvedOptions, config: SanitizedConfig) => ServerObject[];
+export declare const buildOpenApiDocument: (input: BuildOpenApiInput) => Promise<Document>;
+//# sourceMappingURL=build.d.ts.map

package/dist/server/spec/build.js

@@ -0,0 +1,40 @@
+import { buildDocument } from "./buildDocument.js";
+import { toOpenApi30, toOpenApi31 } from "./downconvert.js";
+import { getLocalI18n } from "payload";
+const staticServers = (options, config) => {
+	if (Array.isArray(options.servers)) return options.servers;
+	return config.serverURL ? [{ url: config.serverURL }] : [];
+};
+const buildOpenApiDocument = async (input) => {
+	const { payload, options, language, servers } = input;
+	const { config } = payload;
+	const locales = config.localization === false ? [] : config.localization.locales.map((locale) => locale.code);
+	const i18n = input.i18n ?? await getLocalI18n({
+		config,
+		language: language ?? config.i18n?.fallbackLanguage
+	});
+	const supported = Object.keys(config.i18n?.supportedLanguages ?? {});
+	const docLanguages = supported.length > 0 ? supported : ["en"];
+	const ctx = {
+		defaultIDType: payload.db.defaultIDType,
+		locales,
+		apiRoute: config.routes?.api ?? "/api",
+		docLanguages,
+		i18n
+	};
+	const doc = await buildDocument({
+		payload,
+		options,
+		servers: servers ?? staticServers(options, config),
+		collections: Object.values(payload.collections).map((collection) => collection.config),
+		globals: config.globals,
+		config,
+		ctx
+	});
+	if (options.openapiVersion === "3.0") return toOpenApi30(doc);
+	if (options.openapiVersion === "3.1") return toOpenApi31(doc);
+	return doc;
+};
+export { buildOpenApiDocument, staticServers };
+
+//# sourceMappingURL=build.js.map

package/dist/server/spec/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","names":[],"sources":["../../../src/server/spec/build.ts"],"sourcesContent":["import type { AcceptedLanguages, I18n } from '@payloadcms/translations'\nimport type { Document, ServerObject } from '@scalar/openapi-types/3.2'\nimport { getLocalI18n } from 'payload'\nimport type { BasePayload, SanitizedConfig } from 'payload'\n\nimport type { BuildContext, ResolvedOptions } from '@/shared/types/index.js'\n\nimport { buildDocument } from './buildDocument.js'\nimport { toOpenApi30, toOpenApi31 } from './downconvert.js'\n\nexport interface BuildOpenApiInput {\n  payload: BasePayload\n  options: ResolvedOptions\n  language?: string\n  i18n?: I18n\n  servers?: ServerObject[]\n}\n\nexport const staticServers = (options: ResolvedOptions, config: SanitizedConfig): ServerObject[] => {\n  if (Array.isArray(options.servers)) return options.servers\n  return config.serverURL ? [{ url: config.serverURL }] : []\n}\n\nexport const buildOpenApiDocument = async (input: BuildOpenApiInput): Promise<Document> => {\n  const { payload, options, language, servers } = input\n  const { config } = payload\n\n  const locales = config.localization === false ? [] : config.localization.locales.map((locale) => locale.code)\n\n  const i18n =\n    input.i18n ??\n    (await getLocalI18n({ config, language: (language ?? config.i18n?.fallbackLanguage) as AcceptedLanguages }))\n\n  const supported = Object.keys(config.i18n?.supportedLanguages ?? {})\n  const docLanguages = supported.length > 0 ? supported : ['en']\n\n  const ctx: BuildContext = {\n    defaultIDType: payload.db.defaultIDType,\n    locales,\n    apiRoute: config.routes?.api ?? '/api',\n    docLanguages,\n    i18n,\n  }\n\n  const doc = await buildDocument({\n    payload,\n    options,\n    servers: servers ?? staticServers(options, config),\n    collections: Object.values(payload.collections).map((collection) => collection.config),\n    globals: config.globals,\n    config,\n    ctx,\n  })\n\n  if (options.openapiVersion === '3.0') return toOpenApi30(doc)\n  if (options.openapiVersion === '3.1') return toOpenApi31(doc)\n  return doc\n}\n"],"mappings":";;;AAkBA,MAAa,iBAAiB,SAA0B,WAA4C;CAClG,IAAI,MAAM,QAAQ,QAAQ,OAAO,GAAG,OAAO,QAAQ;CACnD,OAAO,OAAO,YAAY,CAAC,EAAE,KAAK,OAAO,UAAU,CAAC,IAAI,CAAC;AAC3D;AAEA,MAAa,uBAAuB,OAAO,UAAgD;CACzF,MAAM,EAAE,SAAS,SAAS,UAAU,YAAY;CAChD,MAAM,EAAE,WAAW;CAEnB,MAAM,UAAU,OAAO,iBAAiB,QAAQ,CAAC,IAAI,OAAO,aAAa,QAAQ,KAAK,WAAW,OAAO,IAAI;CAE5G,MAAM,OACJ,MAAM,QACL,MAAM,aAAa;EAAE;EAAQ,UAAW,YAAY,OAAO,MAAM;CAAuC,CAAC;CAE5G,MAAM,YAAY,OAAO,KAAK,OAAO,MAAM,sBAAsB,CAAC,CAAC;CACnE,MAAM,eAAe,UAAU,SAAS,IAAI,YAAY,CAAC,IAAI;CAE7D,MAAM,MAAoB;EACxB,eAAe,QAAQ,GAAG;EAC1B;EACA,UAAU,OAAO,QAAQ,OAAO;EAChC;EACA;CACF;CAEA,MAAM,MAAM,MAAM,cAAc;EAC9B;EACA;EACA,SAAS,WAAW,cAAc,SAAS,MAAM;EACjD,aAAa,OAAO,OAAO,QAAQ,WAAW,CAAC,CAAC,KAAK,eAAe,WAAW,MAAM;EACrF,SAAS,OAAO;EAChB;EACA;CACF,CAAC;CAED,IAAI,QAAQ,mBAAmB,OAAO,OAAO,YAAY,GAAG;CAC5D,IAAI,QAAQ,mBAAmB,OAAO,OAAO,YAAY,GAAG;CAC5D,OAAO;AACT"}

package/dist/server/spec/buildDocument.d.ts

@@ -0,0 +1,16 @@
+import { BuildContext, ResolvedOptions } from "../../shared/types/index.js";
+import { BasePayload, SanitizedCollectionConfig, SanitizedConfig, SanitizedGlobalConfig } from "payload";
+import { Document } from "@scalar/openapi-types/3.2";
+export interface BuildInput {
+  options: ResolvedOptions;
+  servers: {
+    url: string;
+  }[];
+  collections: SanitizedCollectionConfig[];
+  globals: SanitizedGlobalConfig[];
+  config: SanitizedConfig;
+  ctx: BuildContext;
+  payload: BasePayload;
+}
+export declare const buildDocument: (input: BuildInput) => Promise<Document>;
+//# sourceMappingURL=buildDocument.d.ts.map

package/dist/server/spec/buildDocument.js

@@ -0,0 +1,287 @@
+import { deepMerge } from "../../shared/utils.js";
+import { blockSchemaName, createSchemaName, globalSchemaName, joinsSchemaName, listSchemaName, populateSchemaName, querySchemaName, schemaName, selectSchemaName, updateSchemaName } from "./names.js";
+import { ERROR_SCHEMA_NAME, INTERACTIVE_SCHEME_NAME, SECURITY_SCHEME_NAME, buildErrorResponseSchema, buildListEnvelopeSchema, interactiveSecurityScheme, securityScheme } from "./components.js";
+import { buildTagHierarchy } from "./tags.js";
+import { PLUGIN_NAME } from "../../shared/constants.js";
+import { makeT } from "../../shared/translations/index.js";
+import { buildAuthPaths } from "./paths/auth.js";
+import { buildParamSchemas, buildQueryOperationsSchema, collectionHasFilters } from "./params.js";
+import { buildCollectionPaths } from "./paths/collections.js";
+import { buildCustomEndpointPaths } from "./paths/custom.js";
+import { buildGlobalPaths } from "./paths/globals.js";
+import { buildJobsPaths } from "./paths/jobs.js";
+import { buildSystemPaths } from "./paths/system.js";
+import { buildVersionPaths, versionComponentSchemas } from "./paths/versions.js";
+import { buildBlockSchema, buildEntitySchemas } from "./entitySchemas.js";
+import { filterOperations, shouldIncludeCollection, shouldIncludeGlobal } from "./filters.js";
+import { applyHierarchy } from "./hierarchy.js";
+import { applySecurity, evaluateAccess, resolveEntitySecurity, securedRequirement } from "./security.js";
+import { getTranslation } from "@payloadcms/translations";
+const resolveDescription = (description, ctx) => {
+	if (description == null) return void 0;
+	const resolved = getTranslation(description, ctx.i18n);
+	return typeof resolved === "string" && resolved.length > 0 ? resolved : void 0;
+};
+const registerParamSchemas = (schemas, base, fields, ctx) => {
+	const { select, populate, joins } = buildParamSchemas({
+		fields,
+		ctx
+	});
+	schemas[selectSchemaName(base)] = select;
+	if (populate) schemas[populateSchemaName(base)] = populate;
+	if (joins) schemas[joinsSchemaName(base)] = joins;
+};
+const buildDocument = async (input) => {
+	const { options, ctx, config, payload } = input;
+	const { logger } = payload;
+	const t = makeT(ctx.i18n);
+	const paths = {};
+	const schemas = {};
+	const { filters } = options;
+	const login = options.serve && options.interactiveAuth.enabled;
+	const finalize = async (group, kind, slug) => applySecurity({
+		paths: await filterOperations({
+			paths: group,
+			slug,
+			kind,
+			filters
+		}),
+		slug,
+		kind,
+		security: options.security,
+		login
+	});
+	const access = filters.includeAuth && filters.includeAdminAuth;
+	const collections = input.collections.filter((c) => shouldIncludeCollection(c, filters));
+	const globals = input.globals.filter((g) => shouldIncludeGlobal(g, filters));
+	const collectionTagInfos = [];
+	const globalTagInfos = [];
+	for (const block of config.blocks ?? []) try {
+		schemas[blockSchemaName(block.slug)] = buildBlockSchema(block, config);
+	} catch (error) {
+		logger.warn(`${PLUGIN_NAME}: skipped block "${block.slug}": ${error.message}`);
+	}
+	for (const collection of collections) try {
+		const { read, create, update } = await buildEntitySchemas({
+			entity: collection,
+			config,
+			ctx
+		});
+		const base = schemaName(collection.slug);
+		collectionTagInfos.push({
+			base,
+			hasAuth: filters.includeAuth && Boolean(collection.auth),
+			hasVersions: Boolean(filters.includeVersions && collection.versions),
+			description: resolveDescription(collection.admin?.description, ctx)
+		});
+		schemas[base] = read;
+		schemas[createSchemaName(base)] = create;
+		schemas[updateSchemaName(base)] = update;
+		schemas[listSchemaName(base)] = buildListEnvelopeSchema(base);
+		if (collectionHasFilters(collection.fields)) schemas[querySchemaName(base)] = buildQueryOperationsSchema({
+			base,
+			fields: collection.fields,
+			ctx
+		});
+		registerParamSchemas(schemas, base, collection.fields, ctx);
+		const security = await resolveEntitySecurity({
+			entity: collection,
+			operations: [
+				"read",
+				"create",
+				"update",
+				"delete",
+				"validate",
+				"readVersions"
+			],
+			locale: ctx.locales[0],
+			baseAccess: config.baseAccess
+		});
+		const collectionPaths = { ...buildCollectionPaths({
+			collection,
+			ctx,
+			security,
+			access
+		}) };
+		if (filters.includeAuth) Object.assign(collectionPaths, buildAuthPaths({
+			collection,
+			ctx,
+			includeAdmin: filters.includeAdminAuth,
+			nestedTags: options.nestedTags
+		}));
+		if (filters.includeVersions && collection.versions) {
+			const { version, versionList } = versionComponentSchemas({
+				docBase: base,
+				base,
+				idType: ctx.defaultIDType
+			});
+			schemas[`${base}Version`] = version;
+			schemas[`${base}VersionList`] = versionList;
+			Object.assign(collectionPaths, buildVersionPaths({
+				entity: collection,
+				pathBase: `${ctx.apiRoute}/${collection.slug}`,
+				ctx,
+				schemaBase: base,
+				nestedTags: options.nestedTags,
+				security
+			}));
+		}
+		applyHierarchy({
+			collection,
+			base,
+			paths: collectionPaths,
+			schemas,
+			ctx
+		});
+		Object.assign(paths, await finalize(collectionPaths, "collection", collection.slug));
+	} catch (error) {
+		logger.warn(`${PLUGIN_NAME}: skipped collection "${collection.slug}": ${error.message}`);
+	}
+	for (const global of globals) try {
+		const { read, update } = await buildEntitySchemas({
+			entity: global,
+			config,
+			ctx
+		});
+		const gbase = globalSchemaName(global.slug);
+		globalTagInfos.push({
+			base: gbase,
+			hasVersions: Boolean(filters.includeVersions && global.versions),
+			description: resolveDescription(global.admin?.description, ctx)
+		});
+		schemas[gbase] = read;
+		schemas[updateSchemaName(gbase)] = update;
+		registerParamSchemas(schemas, gbase, global.fields, ctx);
+		const security = await resolveEntitySecurity({
+			entity: global,
+			operations: [
+				"read",
+				"update",
+				"validate",
+				"readVersions"
+			],
+			locale: ctx.locales[0],
+			baseAccess: config.baseAccess
+		});
+		const globalPaths = { ...buildGlobalPaths({
+			global,
+			ctx,
+			security,
+			access
+		}) };
+		if (filters.includeVersions && global.versions) {
+			const { version, versionList } = versionComponentSchemas({
+				docBase: gbase,
+				base: gbase,
+				idType: ctx.defaultIDType
+			});
+			schemas[`${gbase}Version`] = version;
+			schemas[`${gbase}VersionList`] = versionList;
+			Object.assign(globalPaths, buildVersionPaths({
+				entity: global,
+				pathBase: `${ctx.apiRoute}/globals/${global.slug}`,
+				ctx,
+				schemaBase: gbase,
+				nestedTags: options.nestedTags,
+				security,
+				global: true
+			}));
+		}
+		Object.assign(paths, await finalize(globalPaths, "global", global.slug));
+	} catch (error) {
+		logger.warn(`${PLUGIN_NAME}: skipped global "${global.slug}": ${error.message}`);
+	}
+	if (filters.includeCustom) try {
+		Object.assign(paths, await finalize(buildCustomEndpointPaths({
+			config,
+			collections,
+			globals,
+			ctx
+		}), "custom"));
+	} catch (error) {
+		logger.warn(`${PLUGIN_NAME}: failed to collect custom endpoints: ${error.message}`);
+	}
+	const jobsConfig = config.jobs;
+	const hasJobs = filters.includeJobs && Boolean((jobsConfig?.tasks)?.length || (jobsConfig?.workflows)?.length);
+	if (filters.includeJobs) try {
+		const runAccess = (jobsConfig?.access)?.run;
+		const jobsSecurity = await evaluateAccess(runAccess, { baseAccess: config.baseAccess }) ? void 0 : securedRequirement();
+		Object.assign(paths, await finalize(buildJobsPaths({
+			config,
+			ctx,
+			security: jobsSecurity
+		}), "jobs"));
+	} catch (error) {
+		logger.warn(`${PLUGIN_NAME}: failed to add jobs endpoint: ${error.message}`);
+	}
+	const uploadSlugs = collections.filter((c) => c.upload).map((c) => c.slug);
+	Object.assign(paths, await finalize(buildSystemPaths({
+		ctx,
+		access,
+		uploadSlugs
+	}), "system"));
+	const systemTags = [];
+	if (hasJobs) systemTags.push("Jobs");
+	if (uploadSlugs.length > 0) systemTags.push("Uploads");
+	if (access) systemTags.push("Access");
+	const supportedTimezones = config.admin?.timezones?.supportedTimezones;
+	if (Array.isArray(supportedTimezones) && supportedTimezones.length > 0) schemas[schemaName("supportedTimezones")] = {
+		type: "string",
+		description: t("schemaSupportedTimezones"),
+		enum: supportedTimezones.map((tz) => typeof tz === "string" ? tz : tz.value)
+	};
+	schemas[ERROR_SCHEMA_NAME] = buildErrorResponseSchema();
+	const cookiePrefix = config.cookiePrefix || "payload";
+	const securitySchemes = { [SECURITY_SCHEME_NAME]: securityScheme({
+		cookiePrefix,
+		t
+	}) };
+	if (login) securitySchemes[INTERACTIVE_SCHEME_NAME] = interactiveSecurityScheme({
+		tokenUrl: `${ctx.apiRoute}${options.interactiveAuth.path}`,
+		t
+	});
+	const localeNote = ctx.locales.length > 0 ? `\n\n## ${t("localizationHeading")}\n\n` + t("localizationNote", { locales: ctx.locales.map((l) => `\`${l}\``).join(", ") }) : "";
+	const docLanguagesNote = ctx.docLanguages.length > 1 ? `\n\n${t("docLanguagesNote", { languages: ctx.docLanguages.map((l) => `\`${l}\``).join(", ") })}` : "";
+	let doc = {
+		openapi: "3.2.0",
+		info: {
+			...options.info,
+			description: `${resolveDescription(options.info.description, ctx) ?? ""}${localeNote}${docLanguagesNote}`.trim() || void 0
+		},
+		servers: input.servers,
+		paths,
+		components: {
+			schemas,
+			securitySchemes
+		},
+		tags: buildTagHierarchy({
+			collections: collectionTagInfos,
+			globals: globalTagInfos,
+			systemTags,
+			t,
+			nested: options.nestedTags
+		}),
+		"x-doc-languages": ctx.docLanguages
+	};
+	for (const ext of options.extensions) {
+		if (ext.paths) doc.paths = deepMerge(doc.paths ?? {}, ext.paths);
+		if (ext.components) doc.components = deepMerge(doc.components ?? {}, ext.components);
+		if (ext.tags) {
+			const seen = new Set((doc.tags ?? []).map((tag) => tag.name));
+			doc.tags = [...doc.tags ?? [], ...ext.tags.filter((tag) => !seen.has(tag.name))];
+		}
+		if (ext.transform) {
+			doc = await ext.transform({
+				...ctx,
+				doc,
+				payload,
+				options
+			});
+			if (typeof doc?.openapi !== "string" || "payload" in doc) throw new Error(`[${PLUGIN_NAME}] extensions[].transform must return the document, it gets ({ doc, payload })`);
+		}
+	}
+	return doc;
+};
+export { buildDocument };
+
+//# sourceMappingURL=buildDocument.js.map

package/dist/server/spec/buildDocument.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildDocument.js","names":[],"sources":["../../../src/server/spec/buildDocument.ts"],"sourcesContent":["import { getTranslation } from '@payloadcms/translations'\nimport type {\n  ComponentsObject,\n  Document,\n  PathsObject,\n  SchemaObject,\n  SecuritySchemeObject,\n  TagObject,\n} from '@scalar/openapi-types/3.2'\nimport type {\n  Access,\n  BasePayload,\n  Field,\n  SanitizedCollectionConfig,\n  SanitizedConfig,\n  SanitizedGlobalConfig,\n} from 'payload'\n\nimport { buildAuthPaths } from '@/server/spec/paths/auth.js'\nimport { buildCollectionPaths } from '@/server/spec/paths/collections.js'\nimport { buildCustomEndpointPaths } from '@/server/spec/paths/custom.js'\nimport { buildGlobalPaths } from '@/server/spec/paths/globals.js'\nimport { buildJobsPaths } from '@/server/spec/paths/jobs.js'\nimport { buildSystemPaths } from '@/server/spec/paths/system.js'\nimport { buildVersionPaths, versionComponentSchemas } from '@/server/spec/paths/versions.js'\nimport { PLUGIN_NAME } from '@/shared/constants.js'\nimport { makeT } from '@/shared/translations/index.js'\nimport type { BuildContext, OperationKind, ResolvedOptions } from '@/shared/types/index.js'\nimport { deepMerge } from '@/shared/utils.js'\n\nimport {\n  ERROR_SCHEMA_NAME,\n  INTERACTIVE_SCHEME_NAME,\n  SECURITY_SCHEME_NAME,\n  buildErrorResponseSchema,\n  buildListEnvelopeSchema,\n  interactiveSecurityScheme,\n  securityScheme,\n} from './components.js'\nimport { buildBlockSchema, buildEntitySchemas } from './entitySchemas.js'\nimport { filterOperations, shouldIncludeCollection, shouldIncludeGlobal } from './filters.js'\nimport { applyHierarchy } from './hierarchy.js'\nimport {\n  blockSchemaName,\n  createSchemaName,\n  globalSchemaName,\n  joinsSchemaName,\n  listSchemaName,\n  populateSchemaName,\n  querySchemaName,\n  schemaName,\n  selectSchemaName,\n  updateSchemaName,\n} from './names.js'\nimport { buildParamSchemas, buildQueryOperationsSchema, collectionHasFilters } from './params.js'\nimport { applySecurity, evaluateAccess, resolveEntitySecurity, securedRequirement } from './security.js'\nimport { buildTagHierarchy, type CollectionTagInfo, type GlobalTagInfo, type SystemTag } from './tags.js'\n\nconst resolveDescription = (description: unknown, ctx: BuildContext): string | undefined => {\n  if (description == null) return undefined\n  const resolved: unknown = getTranslation(description as string, ctx.i18n)\n  return typeof resolved === 'string' && resolved.length > 0 ? resolved : undefined\n}\n\nconst registerParamSchemas = (\n  schemas: Record<string, SchemaObject>,\n  base: string,\n  fields: Field[],\n  ctx: BuildContext,\n): void => {\n  const { select, populate, joins } = buildParamSchemas({ fields, ctx })\n  schemas[selectSchemaName(base)] = select\n  if (populate) schemas[populateSchemaName(base)] = populate\n  if (joins) schemas[joinsSchemaName(base)] = joins\n}\n\nexport interface BuildInput {\n  options: ResolvedOptions\n  servers: { url: string }[]\n  collections: SanitizedCollectionConfig[]\n  globals: SanitizedGlobalConfig[]\n  config: SanitizedConfig\n  ctx: BuildContext\n  payload: BasePayload\n}\n\nexport const buildDocument = async (input: BuildInput): Promise<Document> => {\n  const { options, ctx, config, payload } = input\n  const { logger } = payload\n  const t = makeT(ctx.i18n)\n  const paths: PathsObject = {}\n  const schemas: Record<string, SchemaObject> = {}\n\n  const { filters } = options\n  const login = options.serve && options.interactiveAuth.enabled\n  const finalize = async (group: PathsObject, kind: OperationKind, slug?: string): Promise<PathsObject> =>\n    applySecurity({\n      paths: await filterOperations({ paths: group, slug, kind, filters }),\n      slug,\n      kind,\n      security: options.security,\n      login,\n    })\n  const access = filters.includeAuth && filters.includeAdminAuth\n  const collections = input.collections.filter((c) => shouldIncludeCollection(c, filters))\n  const globals = input.globals.filter((g) => shouldIncludeGlobal(g, filters))\n\n  const collectionTagInfos: CollectionTagInfo[] = []\n  const globalTagInfos: GlobalTagInfo[] = []\n\n  for (const block of config.blocks ?? []) {\n    try {\n      schemas[blockSchemaName(block.slug)] = buildBlockSchema(block, config)\n    } catch (error) {\n      logger.warn(`${PLUGIN_NAME}: skipped block \"${block.slug}\": ${(error as Error).message}`)\n    }\n  }\n\n  for (const collection of collections) {\n    try {\n      const { read, create, update } = await buildEntitySchemas({ entity: collection, config, ctx })\n      const base = schemaName(collection.slug)\n      collectionTagInfos.push({\n        base,\n        hasAuth: filters.includeAuth && Boolean(collection.auth),\n        hasVersions: Boolean(filters.includeVersions && collection.versions),\n        description: resolveDescription(collection.admin?.description, ctx),\n      })\n      schemas[base] = read\n      schemas[createSchemaName(base)] = create\n      schemas[updateSchemaName(base)] = update\n      schemas[listSchemaName(base)] = buildListEnvelopeSchema(base)\n      if (collectionHasFilters(collection.fields)) {\n        schemas[querySchemaName(base)] = buildQueryOperationsSchema({ base, fields: collection.fields, ctx })\n      }\n      registerParamSchemas(schemas, base, collection.fields, ctx)\n\n      const security = await resolveEntitySecurity({\n        entity: collection,\n        operations: ['read', 'create', 'update', 'delete', 'validate', 'readVersions'],\n        locale: ctx.locales[0],\n        baseAccess: config.baseAccess,\n      })\n      const collectionPaths: PathsObject = { ...buildCollectionPaths({ collection, ctx, security, access }) }\n\n      if (filters.includeAuth) {\n        Object.assign(\n          collectionPaths,\n          buildAuthPaths({\n            collection,\n            ctx,\n            includeAdmin: filters.includeAdminAuth,\n            nestedTags: options.nestedTags,\n          }),\n        )\n      }\n\n      if (filters.includeVersions && collection.versions) {\n        const { version, versionList } = versionComponentSchemas({ docBase: base, base, idType: ctx.defaultIDType })\n        schemas[`${base}Version`] = version\n        schemas[`${base}VersionList`] = versionList\n        Object.assign(\n          collectionPaths,\n          buildVersionPaths({\n            entity: collection,\n            pathBase: `${ctx.apiRoute}/${collection.slug}`,\n            ctx,\n            schemaBase: base,\n            nestedTags: options.nestedTags,\n            security,\n          }),\n        )\n      }\n\n      applyHierarchy({ collection, base, paths: collectionPaths, schemas, ctx })\n      Object.assign(paths, await finalize(collectionPaths, 'collection', collection.slug))\n    } catch (error) {\n      logger.warn(`${PLUGIN_NAME}: skipped collection \"${collection.slug}\": ${(error as Error).message}`)\n    }\n  }\n\n  for (const global of globals) {\n    try {\n      const { read, update } = await buildEntitySchemas({ entity: global, config, ctx })\n      const gbase = globalSchemaName(global.slug)\n      globalTagInfos.push({\n        base: gbase,\n        hasVersions: Boolean(filters.includeVersions && global.versions),\n        description: resolveDescription(global.admin?.description, ctx),\n      })\n      schemas[gbase] = read\n      schemas[updateSchemaName(gbase)] = update\n      registerParamSchemas(schemas, gbase, global.fields, ctx)\n\n      const security = await resolveEntitySecurity({\n        entity: global,\n        operations: ['read', 'update', 'validate', 'readVersions'],\n        locale: ctx.locales[0],\n        baseAccess: config.baseAccess,\n      })\n      const globalPaths: PathsObject = { ...buildGlobalPaths({ global, ctx, security, access }) }\n\n      if (filters.includeVersions && global.versions) {\n        const { version, versionList } = versionComponentSchemas({\n          docBase: gbase,\n          base: gbase,\n          idType: ctx.defaultIDType,\n        })\n        schemas[`${gbase}Version`] = version\n        schemas[`${gbase}VersionList`] = versionList\n        Object.assign(\n          globalPaths,\n          buildVersionPaths({\n            entity: global,\n            pathBase: `${ctx.apiRoute}/globals/${global.slug}`,\n            ctx,\n            schemaBase: gbase,\n            nestedTags: options.nestedTags,\n            security,\n            global: true,\n          }),\n        )\n      }\n\n      Object.assign(paths, await finalize(globalPaths, 'global', global.slug))\n    } catch (error) {\n      logger.warn(`${PLUGIN_NAME}: skipped global \"${global.slug}\": ${(error as Error).message}`)\n    }\n  }\n\n  if (filters.includeCustom) {\n    try {\n      Object.assign(paths, await finalize(buildCustomEndpointPaths({ config, collections, globals, ctx }), 'custom'))\n    } catch (error) {\n      logger.warn(`${PLUGIN_NAME}: failed to collect custom endpoints: ${(error as Error).message}`)\n    }\n  }\n\n  const jobsConfig = config.jobs as Record<string, unknown> | undefined\n  const hasJobs =\n    filters.includeJobs &&\n    Boolean((jobsConfig?.tasks as unknown[])?.length || (jobsConfig?.workflows as unknown[])?.length)\n\n  if (filters.includeJobs) {\n    try {\n      const runAccess = (jobsConfig?.access as { run?: Access } | undefined)?.run\n      const jobsSecurity = (await evaluateAccess(runAccess, { baseAccess: config.baseAccess }))\n        ? undefined\n        : securedRequirement()\n      Object.assign(paths, await finalize(buildJobsPaths({ config, ctx, security: jobsSecurity }), 'jobs'))\n    } catch (error) {\n      logger.warn(`${PLUGIN_NAME}: failed to add jobs endpoint: ${(error as Error).message}`)\n    }\n  }\n\n  const uploadSlugs = collections.filter((c) => c.upload).map((c) => c.slug)\n  Object.assign(paths, await finalize(buildSystemPaths({ ctx, access, uploadSlugs }), 'system'))\n\n  const systemTags: SystemTag[] = []\n  if (hasJobs) systemTags.push('Jobs')\n  if (uploadSlugs.length > 0) systemTags.push('Uploads')\n  if (access) systemTags.push('Access')\n\n  const supportedTimezones = config.admin?.timezones?.supportedTimezones\n  if (Array.isArray(supportedTimezones) && supportedTimezones.length > 0) {\n    schemas[schemaName('supportedTimezones')] = {\n      type: 'string',\n      description: t('schemaSupportedTimezones'),\n      enum: supportedTimezones.map((tz) => (typeof tz === 'string' ? tz : tz.value)),\n    }\n  }\n\n  schemas[ERROR_SCHEMA_NAME] = buildErrorResponseSchema()\n\n  const cookiePrefix = config.cookiePrefix || 'payload'\n  const securitySchemes: Record<string, SecuritySchemeObject> = {\n    [SECURITY_SCHEME_NAME]: securityScheme({ cookiePrefix, t }),\n  }\n  if (login) {\n    securitySchemes[INTERACTIVE_SCHEME_NAME] = interactiveSecurityScheme({\n      tokenUrl: `${ctx.apiRoute}${options.interactiveAuth.path}`,\n      t,\n    })\n  }\n\n  const localeNote =\n    ctx.locales.length > 0\n      ? `\\n\\n## ${t('localizationHeading')}\\n\\n` +\n        t('localizationNote', {\n          locales: ctx.locales.map((l) => `\\`${l}\\``).join(', '),\n        })\n      : ''\n  const docLanguagesNote =\n    ctx.docLanguages.length > 1\n      ? `\\n\\n${t('docLanguagesNote', { languages: ctx.docLanguages.map((l) => `\\`${l}\\``).join(', ') })}`\n      : ''\n  const info = {\n    ...options.info,\n    description:\n      `${resolveDescription(options.info.description, ctx) ?? ''}${localeNote}${docLanguagesNote}`.trim() || undefined,\n  }\n\n  let doc = {\n    openapi: '3.2.0',\n    info,\n    servers: input.servers,\n    paths,\n    components: {\n      schemas,\n      securitySchemes,\n    },\n    tags: buildTagHierarchy({\n      collections: collectionTagInfos,\n      globals: globalTagInfos,\n      systemTags,\n      t,\n      nested: options.nestedTags,\n    }),\n    'x-doc-languages': ctx.docLanguages,\n  } as Document\n\n  for (const ext of options.extensions) {\n    if (ext.paths) {\n      doc.paths = deepMerge(doc.paths ?? {}, ext.paths) as PathsObject\n    }\n    if (ext.components) {\n      doc.components = deepMerge(\n        (doc.components ?? {}) as Record<string, unknown>,\n        ext.components as Record<string, unknown>,\n      ) as ComponentsObject\n    }\n    if (ext.tags) {\n      const seen = new Set((doc.tags ?? []).map((tag: TagObject) => tag.name))\n      doc.tags = [...(doc.tags ?? []), ...ext.tags.filter((tag: TagObject) => !seen.has(tag.name))]\n    }\n    if (ext.transform) {\n      doc = await ext.transform({ ...ctx, doc, payload, options })\n      if (typeof doc?.openapi !== 'string' || 'payload' in doc) {\n        throw new Error(`[${PLUGIN_NAME}] extensions[].transform must return the document, it gets ({ doc, payload })`)\n      }\n    }\n  }\n\n  return doc\n}\n"],"mappings":"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"}

package/dist/server/spec/components.d.ts

@@ -0,0 +1,61 @@
+import { Translate } from "../../shared/translations/types.js";
+import { OperationObject, ParameterObject, ReferenceObject, RequestBodyObject, ResponseObject, ResponsesObject, SchemaObject, SecurityRequirementObject, SecuritySchemeObject } from "@scalar/openapi-types/3.2";
+type SchemaOrRef = SchemaObject | ReferenceObject;
+export declare const nullableType: (type: 'integer' | 'string' | 'number' | 'boolean') => SchemaObject;
+export declare const jsonResponse: (description: string, schema: SchemaOrRef) => ResponseObject;
+export declare const jsonOk: (description: string, schema: SchemaOrRef) => ResponsesObject;
+export declare const jsonBody: (schema: SchemaOrRef) => RequestBodyObject;
+export declare const messageResponse: (description: string) => ResponsesObject;
+export type ErrorCode = '400' | '401' | '403' | '404' | '500';
+export declare const docAccessOperation: ({ tag, operationId, operations, bodyRef, errors, t }: {
+  tag: string;
+  operationId: string;
+  operations: string[];
+  bodyRef: ReferenceObject;
+  errors: ErrorCode[];
+  t: Translate;
+}) => OperationObject;
+export declare const validateOperation: ({ tag, operationId, parameters, requestBody, errors, security, t }: {
+  tag: string;
+  operationId: string;
+  parameters: ParameterObject[];
+  requestBody: RequestBodyObject;
+  errors: ErrorCode[];
+  security?: SecurityRequirementObject[];
+  t: Translate;
+}) => OperationObject;
+export declare const ERROR_SCHEMA_NAME = "ErrorResponse";
+export declare const ERRORS: {
+  readonly list: ErrorCode[];
+  readonly read: ErrorCode[];
+  readonly create: ErrorCode[];
+  readonly update: ErrorCode[];
+  readonly delete: ErrorCode[];
+  readonly globalRead: ErrorCode[];
+  readonly globalUpdate: ErrorCode[];
+  readonly login: ErrorCode[];
+  readonly session: ErrorCode[];
+  readonly authAction: ErrorCode[];
+  readonly versionList: ErrorCode[];
+  readonly versionRead: ErrorCode[];
+  readonly versionRestore: ErrorCode[];
+};
+export declare const buildErrorResponseSchema: () => SchemaObject;
+export declare const errorResponses: (codes: ErrorCode[], t: Translate) => ResponsesObject;
+export declare const buildListEnvelopeSchema: (base: string) => SchemaObject;
+export declare const uploadRequestBody: ({ bodyRef, fileRequired, t }: {
+  bodyRef: ReferenceObject;
+  fileRequired: boolean;
+  t: Translate;
+}) => RequestBodyObject;
+export declare const SECURITY_SCHEME_NAME = "PayloadToken";
+export declare const INTERACTIVE_SCHEME_NAME = "PayloadLogin";
+export declare const interactiveSecurityScheme: ({ tokenUrl, t }: {
+  tokenUrl: string;
+  t: Translate;
+}) => SecuritySchemeObject;
+export declare const securityScheme: ({ cookiePrefix, t }: {
+  cookiePrefix: string;
+  t: Translate;
+}) => SecuritySchemeObject;
+//# sourceMappingURL=components.d.ts.map