vite-plugin-openapi-codegen 3.2.0 → 3.3.0

package/dist/cli.mjs

@@ -268,7 +268,81 @@ function collectOperations(spec, pathPrefix = "/api/", stripPrefix = true) {
 			});
 		}
 	}
-	return entries;
+	const publicEntries = excludeInternalOperations(entries, spec);
+	if (entries.length > 0 && publicEntries.length === 0) throw new Error(`All ${entries.length} operation(s) matching prefix "${pathPrefix}" are internal-only and were excluded`);
+	const excludedCount = entries.length - publicEntries.length;
+	if (excludedCount > 0) console.info(`[openapi-codegen] excluded ${excludedCount} internal-only operation(s) from generated artifacts.`);
+	return publicEntries;
+}
+function excludeInternalOperations(entries, spec) {
+	const securitySchemes = spec.components?.securitySchemes;
+	if (!securitySchemes) return entries;
+	return entries.filter((entry) => readSecurityRequirement(entry, securitySchemes, spec.security)?.kind !== "internal");
+}
+function excludeInternalOperationsFromSpec(spec) {
+	const securitySchemes = spec.components?.securitySchemes;
+	if (!securitySchemes || !spec.paths) return {
+		excludedCount: 0,
+		spec
+	};
+	const clone = structuredClone(spec);
+	let excludedCount = 0;
+	for (const [path, pathItem] of Object.entries(clone.paths ?? {})) {
+		let removedFromPath = 0;
+		for (const method of HTTP_METHODS) {
+			const operation = pathItem[method];
+			if (!operation) continue;
+			if (readSecurityRequirement({
+				operation,
+				operationId: operation.operationId ?? `${method.toUpperCase()} ${path}`
+			}, securitySchemes, clone.security)?.kind !== "internal") continue;
+			delete pathItem[method];
+			removedFromPath += 1;
+		}
+		excludedCount += removedFromPath;
+		if (removedFromPath > 0 && !HTTP_METHODS.some((method) => pathItem[method])) delete clone.paths?.[path];
+	}
+	return {
+		excludedCount,
+		spec: clone
+	};
+}
+function readSecurityRequirement(entry, securitySchemes, topLevelSecurity) {
+	const security = entry.operation.security ?? topLevelSecurity;
+	if (security === void 0) return null;
+	if (!Array.isArray(security)) throw new Error(`Operation "${entry.operationId}" has invalid security`);
+	if (security.length === 0) return { kind: "public" };
+	if (security.length > 1) throw new Error(`Operation "${entry.operationId}" declares ${security.length} security requirements; the backend contract emits at most one`);
+	const requirement = security[0];
+	if (!isRecord(requirement)) throw new Error(`Operation "${entry.operationId}" has an invalid security requirement`);
+	const schemeEntries = Object.entries(requirement);
+	if (schemeEntries.length > 1) throw new Error(`Operation "${entry.operationId}" declares ${schemeEntries.length} schemes in one security requirement; the backend contract emits exactly one`);
+	const schemeEntry = schemeEntries[0];
+	if (schemeEntry) {
+		const [schemeName, scopes] = schemeEntry;
+		const scheme = securitySchemes?.[schemeName];
+		if (scheme?.type === "apiKey" && scheme.in === "header") return { kind: "internal" };
+		if (scheme?.type === "http" || scheme?.type === "apiKey" && scheme.in === "cookie") {
+			const roles = readSecurityScopes(entry, schemeName, scopes);
+			return roles.length === 0 ? { kind: "authenticated" } : {
+				kind: "role",
+				roles
+			};
+		}
+	}
+	throw new Error(`Operation "${entry.operationId}" has an unrecognized security scheme`);
+}
+function readSecurityScopes(entry, schemeName, scopes) {
+	if (!Array.isArray(scopes)) throw new Error(`Operation "${entry.operationId}" has non-array scopes for security scheme "${schemeName}"`);
+	const roles = [];
+	for (const scope of scopes) {
+		if (typeof scope !== "string") throw new Error(`Operation "${entry.operationId}" has a non-string scope for security scheme "${schemeName}"`);
+		roles.push(scope);
+	}
+	return roles;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function getEffectiveParametersByLocation(entry, location) {
 	return (entry.operation.parameters ?? []).filter((parameter) => getEffectiveParameterLocation(entry.apiPath, parameter) === location);
@@ -604,9 +678,10 @@ function resolveHttpClientConfig(config) {
 	};
 }
 const GENERATED_HEADER = ["// This file is auto-generated by vite-plugin-openapi-codegen.", "// Do not edit manually. Changes will be overwritten on next build."];
-async function generateApiTypes(source, outputDir, useTypeAliases) {
+async function generateApiTypes(input, outputDir, useTypeAliases) {
 	const { default: openapiTS, astToString } = await import("openapi-typescript");
-	const contents = astToString(await openapiTS(source, useTypeAliases ? {
+	const { excludedCount, spec } = excludeInternalOperationsFromSpec(input.spec);
+	const contents = astToString(await openapiTS(excludedCount > 0 ? spec : input.apiTypesSource, useTypeAliases ? {
 		rootTypes: true,
 		rootTypesKeepCasing: true,
 		rootTypesNoSchemaPrefix: true
@@ -662,29 +737,6 @@ function createAccessPolicyEntries(operations, securitySchemes, topLevelSecurity
 		}];
 	});
 }
-function readSecurityRequirement(entry, securitySchemes, topLevelSecurity) {
-	const security = entry.operation.security ?? topLevelSecurity;
-	if (security === void 0) return null;
-	if (!Array.isArray(security)) throw new Error(`Operation "${entry.operationId}" has invalid security`);
-	if (security.length === 0) return { kind: "public" };
-	const requirement = security[0];
-	if (!isRecord(requirement)) throw new Error(`Operation "${entry.operationId}" has an invalid security requirement`);
-	for (const [schemeName, scopes] of Object.entries(requirement)) {
-		const scheme = securitySchemes?.[schemeName];
-		if (scheme?.type === "apiKey" && scheme.in === "header") return { kind: "internal" };
-		if (scheme?.type === "http" || scheme?.type === "apiKey" && scheme.in === "cookie") {
-			const roles = Array.isArray(scopes) ? scopes.filter((scope) => typeof scope === "string") : [];
-			return roles.length === 0 ? { kind: "authenticated" } : {
-				kind: "role",
-				roles
-			};
-		}
-	}
-	throw new Error(`Operation "${entry.operationId}" has an unrecognized security scheme`);
-}
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function resolveChannel(channel, useTypeAliases) {
 	if (!channel.typeRef) return channel;
 	return {
@@ -750,11 +802,13 @@ function parseOpenAPISpec(sourceText, inputLabel) {
 async function generateOpenAPIArtifacts(root, options) {
 	const outputDir = resolve(root, options.output);
 	mkdirSync(outputDir, { recursive: true });
-	const { apiTypesSource, spec } = await loadOpenAPIInput(root, options.input);
-	const operations = collectOperations(spec, options.pathPrefix ?? "/api/", options.stripPrefix ?? true);
-	const artifacts = renderGeneratedArtifacts(spec, options, operations);
+	const input = await loadOpenAPIInput(root, options.input);
+	const pathPrefix = options.pathPrefix ?? "/api/";
+	const stripPrefix = options.stripPrefix ?? true;
+	const operations = collectOperations(input.spec, pathPrefix, stripPrefix);
+	const artifacts = renderGeneratedArtifacts(input.spec, options, operations);
 	warnOnParameterLocationMismatch(operations);
-	await generateApiTypes(apiTypesSource, outputDir, options.typeAliases ?? false);
+	await generateApiTypes(input, outputDir, options.typeAliases ?? false);
 	if (artifacts.apiTypes) writeFileSync(resolve(outputDir, "api-types.d.ts"), artifacts.apiTypes, { flag: "a" });
 	if (artifacts.accessPolicies) writeFileSync(resolve(outputDir, "access-policies.ts"), artifacts.accessPolicies);
 	writeFileSync(resolve(outputDir, "api.ts"), artifacts.api);

package/dist/index.mjs

@@ -266,7 +266,81 @@ function collectOperations(spec, pathPrefix = "/api/", stripPrefix = true) {
 			});
 		}
 	}
-	return entries;
+	const publicEntries = excludeInternalOperations(entries, spec);
+	if (entries.length > 0 && publicEntries.length === 0) throw new Error(`All ${entries.length} operation(s) matching prefix "${pathPrefix}" are internal-only and were excluded`);
+	const excludedCount = entries.length - publicEntries.length;
+	if (excludedCount > 0) console.info(`[openapi-codegen] excluded ${excludedCount} internal-only operation(s) from generated artifacts.`);
+	return publicEntries;
+}
+function excludeInternalOperations(entries, spec) {
+	const securitySchemes = spec.components?.securitySchemes;
+	if (!securitySchemes) return entries;
+	return entries.filter((entry) => readSecurityRequirement(entry, securitySchemes, spec.security)?.kind !== "internal");
+}
+function excludeInternalOperationsFromSpec(spec) {
+	const securitySchemes = spec.components?.securitySchemes;
+	if (!securitySchemes || !spec.paths) return {
+		excludedCount: 0,
+		spec
+	};
+	const clone = structuredClone(spec);
+	let excludedCount = 0;
+	for (const [path, pathItem] of Object.entries(clone.paths ?? {})) {
+		let removedFromPath = 0;
+		for (const method of HTTP_METHODS) {
+			const operation = pathItem[method];
+			if (!operation) continue;
+			if (readSecurityRequirement({
+				operation,
+				operationId: operation.operationId ?? `${method.toUpperCase()} ${path}`
+			}, securitySchemes, clone.security)?.kind !== "internal") continue;
+			delete pathItem[method];
+			removedFromPath += 1;
+		}
+		excludedCount += removedFromPath;
+		if (removedFromPath > 0 && !HTTP_METHODS.some((method) => pathItem[method])) delete clone.paths?.[path];
+	}
+	return {
+		excludedCount,
+		spec: clone
+	};
+}
+function readSecurityRequirement(entry, securitySchemes, topLevelSecurity) {
+	const security = entry.operation.security ?? topLevelSecurity;
+	if (security === void 0) return null;
+	if (!Array.isArray(security)) throw new Error(`Operation "${entry.operationId}" has invalid security`);
+	if (security.length === 0) return { kind: "public" };
+	if (security.length > 1) throw new Error(`Operation "${entry.operationId}" declares ${security.length} security requirements; the backend contract emits at most one`);
+	const requirement = security[0];
+	if (!isRecord(requirement)) throw new Error(`Operation "${entry.operationId}" has an invalid security requirement`);
+	const schemeEntries = Object.entries(requirement);
+	if (schemeEntries.length > 1) throw new Error(`Operation "${entry.operationId}" declares ${schemeEntries.length} schemes in one security requirement; the backend contract emits exactly one`);
+	const schemeEntry = schemeEntries[0];
+	if (schemeEntry) {
+		const [schemeName, scopes] = schemeEntry;
+		const scheme = securitySchemes?.[schemeName];
+		if (scheme?.type === "apiKey" && scheme.in === "header") return { kind: "internal" };
+		if (scheme?.type === "http" || scheme?.type === "apiKey" && scheme.in === "cookie") {
+			const roles = readSecurityScopes(entry, schemeName, scopes);
+			return roles.length === 0 ? { kind: "authenticated" } : {
+				kind: "role",
+				roles
+			};
+		}
+	}
+	throw new Error(`Operation "${entry.operationId}" has an unrecognized security scheme`);
+}
+function readSecurityScopes(entry, schemeName, scopes) {
+	if (!Array.isArray(scopes)) throw new Error(`Operation "${entry.operationId}" has non-array scopes for security scheme "${schemeName}"`);
+	const roles = [];
+	for (const scope of scopes) {
+		if (typeof scope !== "string") throw new Error(`Operation "${entry.operationId}" has a non-string scope for security scheme "${schemeName}"`);
+		roles.push(scope);
+	}
+	return roles;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function getEffectiveParametersByLocation(entry, location) {
 	return (entry.operation.parameters ?? []).filter((parameter) => getEffectiveParameterLocation(entry.apiPath, parameter) === location);
@@ -602,9 +676,10 @@ function resolveHttpClientConfig(config) {
 	};
 }
 const GENERATED_HEADER = ["// This file is auto-generated by vite-plugin-openapi-codegen.", "// Do not edit manually. Changes will be overwritten on next build."];
-async function generateApiTypes(source, outputDir, useTypeAliases) {
+async function generateApiTypes(input, outputDir, useTypeAliases) {
 	const { default: openapiTS, astToString } = await import("openapi-typescript");
-	const contents = astToString(await openapiTS(source, useTypeAliases ? {
+	const { excludedCount, spec } = excludeInternalOperationsFromSpec(input.spec);
+	const contents = astToString(await openapiTS(excludedCount > 0 ? spec : input.apiTypesSource, useTypeAliases ? {
 		rootTypes: true,
 		rootTypesKeepCasing: true,
 		rootTypesNoSchemaPrefix: true
@@ -660,29 +735,6 @@ function createAccessPolicyEntries(operations, securitySchemes, topLevelSecurity
 		}];
 	});
 }
-function readSecurityRequirement(entry, securitySchemes, topLevelSecurity) {
-	const security = entry.operation.security ?? topLevelSecurity;
-	if (security === void 0) return null;
-	if (!Array.isArray(security)) throw new Error(`Operation "${entry.operationId}" has invalid security`);
-	if (security.length === 0) return { kind: "public" };
-	const requirement = security[0];
-	if (!isRecord(requirement)) throw new Error(`Operation "${entry.operationId}" has an invalid security requirement`);
-	for (const [schemeName, scopes] of Object.entries(requirement)) {
-		const scheme = securitySchemes?.[schemeName];
-		if (scheme?.type === "apiKey" && scheme.in === "header") return { kind: "internal" };
-		if (scheme?.type === "http" || scheme?.type === "apiKey" && scheme.in === "cookie") {
-			const roles = Array.isArray(scopes) ? scopes.filter((scope) => typeof scope === "string") : [];
-			return roles.length === 0 ? { kind: "authenticated" } : {
-				kind: "role",
-				roles
-			};
-		}
-	}
-	throw new Error(`Operation "${entry.operationId}" has an unrecognized security scheme`);
-}
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function resolveChannel(channel, useTypeAliases) {
 	if (!channel.typeRef) return channel;
 	return {
@@ -748,11 +800,13 @@ function parseOpenAPISpec(sourceText, inputLabel) {
 async function generateOpenAPIArtifacts(root, options) {
 	const outputDir = resolve(root, options.output);
 	mkdirSync(outputDir, { recursive: true });
-	const { apiTypesSource, spec } = await loadOpenAPIInput(root, options.input);
-	const operations = collectOperations(spec, options.pathPrefix ?? "/api/", options.stripPrefix ?? true);
-	const artifacts = renderGeneratedArtifacts(spec, options, operations);
+	const input = await loadOpenAPIInput(root, options.input);
+	const pathPrefix = options.pathPrefix ?? "/api/";
+	const stripPrefix = options.stripPrefix ?? true;
+	const operations = collectOperations(input.spec, pathPrefix, stripPrefix);
+	const artifacts = renderGeneratedArtifacts(input.spec, options, operations);
 	warnOnParameterLocationMismatch(operations);
-	await generateApiTypes(apiTypesSource, outputDir, options.typeAliases ?? false);
+	await generateApiTypes(input, outputDir, options.typeAliases ?? false);
 	if (artifacts.apiTypes) writeFileSync(resolve(outputDir, "api-types.d.ts"), artifacts.apiTypes, { flag: "a" });
 	if (artifacts.accessPolicies) writeFileSync(resolve(outputDir, "access-policies.ts"), artifacts.accessPolicies);
 	writeFileSync(resolve(outputDir, "api.ts"), artifacts.api);
@@ -771,7 +825,7 @@ function openapiCodegen(options) {
 		},
 		async buildStart() {
 			if (command === "serve" && options.generateOnDev !== false) {
-				runDevelopmentGeneration(root, options);
+				runDevelopmentGeneration(root, options, { onError: resolvePluginErrorRaiser(this) }).catch(() => {});
 				return;
 			}
 		},
@@ -781,9 +835,12 @@ function openapiCodegen(options) {
 			const inputPath = resolve(root, options.input);
 			if (resolve(ctx.file) !== inputPath) return;
 			console.log("[openapi-codegen] openapi.json changed, regenerating...");
-			await runDevelopmentGeneration(root, options, { onSuccess: () => {
-				console.log("[openapi-codegen] regeneration complete.");
-			} });
+			await runDevelopmentGeneration(root, options, {
+				onError: resolvePluginErrorRaiser(this),
+				onSuccess: () => {
+					console.log("[openapi-codegen] regeneration complete.");
+				}
+			});
 		}
 	};
 }
@@ -792,8 +849,15 @@ async function runDevelopmentGeneration(root, options, handlers) {
 		await generateOpenAPIArtifacts(root, options);
 		handlers?.onSuccess?.();
 	} catch (error) {
-		console.error("[openapi-codegen] generation failed during dev mode.", error);
+		const failure = error instanceof Error ? error : new Error(String(error));
+		console.error("[openapi-codegen] generation failed during dev mode.", failure);
+		handlers?.onError?.(failure);
 	}
 }
+function resolvePluginErrorRaiser(context) {
+	if (typeof context !== "object" || context === null || typeof context.error !== "function") return;
+	const pluginContext = context;
+	return (error) => pluginContext.error(error);
+}
 //#endregion
 export { openapiCodegen, renderGeneratedArtifacts };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-openapi-codegen",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Vite plugin that generates typed API clients and route builders from OpenAPI specs",
   "keywords": [
     "api-client",