@kubb/plugin-client 5.0.0-beta.22 → 5.0.0-beta.27

package/dist/index.cjs

@@ -191,6 +191,26 @@ function isValidVarName(name) {
 	if (!name || reservedWords.has(name)) return false;
 	return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name);
 }
+/**
+* Returns `name` when it's a syntactically valid JavaScript variable name,
+* otherwise prefixes it with `_` so the result is a valid identifier.
+*
+* Useful for sanitizing OpenAPI schema names or operation IDs that start with
+* a digit (e.g. `409`, `504AccountCancel`) before using them as exported
+* variable, type, or function names.
+*
+* @example
+* ```ts
+* ensureValidVarName('409')             // '_409'
+* ensureValidVarName('504AccountCancel') // '_504AccountCancel'
+* ensureValidVarName('Pet')              // 'Pet'
+* ensureValidVarName('class')            // '_class'
+* ```
+*/
+function ensureValidVarName(name) {
+	if (!name || isValidVarName(name)) return name;
+	return `_${name}`;
+}
 //#endregion
 //#region ../../internals/utils/src/urlPath.ts
 /**
@@ -257,12 +277,12 @@ var URLPath = class {
 	get object() {
 		return this.toObject();
 	}
-	/** Returns a map of path parameter names, or `undefined` when the path has no parameters.
+	/** Returns a map of path parameter names, or `null` when the path has no parameters.
 	*
 	* @example
 	* ```ts
 	* new URLPath('/pet/{petId}').params // { petId: 'petId' }
-	* new URLPath('/pet').params         // undefined
+	* new URLPath('/pet').params         // null
 	* ```
 	*/
 	get params() {
@@ -325,7 +345,7 @@ var URLPath = class {
 			const key = replacer ? replacer(param) : param;
 			params[key] = key;
 		});
-		return Object.keys(params).length > 0 ? params : void 0;
+		return Object.keys(params).length > 0 ? params : null;
 	}
 	/** Converts the OpenAPI path to Express-style colon syntax.
 	*
@@ -341,9 +361,9 @@ var URLPath = class {
 //#endregion
 //#region ../../internals/shared/src/operation.ts
 function getOperationLink(node, link) {
-	if (!link) return;
-	if (typeof link === "function") return link(node);
-	if (link === "urlPath") return node.path ? `{@link ${new URLPath(node.path).URL}}` : void 0;
+	if (!link) return null;
+	if (typeof link === "function") return link(node) ?? null;
+	if (link === "urlPath") return node.path ? `{@link ${new URLPath(node.path).URL}}` : null;
 	return `{@link ${node.path.replaceAll("{", ":").replaceAll("}", "")}}`;
 }
 function getContentTypeInfo(node) {
@@ -358,9 +378,9 @@ function getContentTypeInfo(node) {
 	};
 }
 function buildRequestConfigType(node, resolver) {
-	const requestName = node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : void 0;
+	const requestName = node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : null;
 	const { isMultipleContentTypes, contentTypeUnion } = getContentTypeInfo(node);
-	return `${requestName ? `Partial<RequestConfig<${requestName}>>` : "Partial<RequestConfig>"} & { ${["client?: Client", isMultipleContentTypes ? `contentType?: ${contentTypeUnion}` : void 0].filter(Boolean).join("; ")} }`;
+	return `${requestName ? `Partial<RequestConfig<${requestName}>>` : "Partial<RequestConfig>"} & { ${["client?: Client", isMultipleContentTypes ? `contentType?: ${contentTypeUnion}` : null].filter(Boolean).join("; ")} }`;
 }
 function buildOperationComments(node, options = {}) {
 	const { link = "pathTemplate", linkPosition = "afterDeprecated", splitLines = false } = options;
@@ -390,15 +410,22 @@ function getOperationParameters(node, options = {}) {
 }
 function getStatusCodeNumber(statusCode) {
 	const code = Number(statusCode);
-	return Number.isNaN(code) ? void 0 : code;
+	return Number.isNaN(code) ? null : code;
+}
+function isSuccessStatusCode(statusCode) {
+	const code = getStatusCodeNumber(statusCode);
+	return code !== null && code >= 200 && code < 300;
 }
 function isErrorStatusCode(statusCode) {
 	const code = getStatusCodeNumber(statusCode);
-	return code !== void 0 && code >= 400;
+	return code !== null && code >= 400;
 }
 function resolveErrorNames(node, resolver) {
 	return node.responses.filter((response) => isErrorStatusCode(response.statusCode)).map((response) => resolver.resolveResponseStatusName(node, response.statusCode));
 }
+function resolveSuccessNames(node, resolver) {
+	return node.responses.filter((response) => isSuccessStatusCode(response.statusCode)).map((response) => resolver.resolveResponseStatusName(node, response.statusCode));
+}
 function resolveStatusCodeNames(node, resolver) {
 	return node.responses.map((response) => resolver.resolveResponseStatusName(node, response.statusCode));
 }
@@ -421,7 +448,7 @@ function resolveOperationTypeNames(node, resolver, options = {}) {
 		...query.map((param) => resolver.resolveQueryParamsName(node, param)),
 		...header.map((param) => resolver.resolveHeaderParamsName(node, param))
 	];
-	const bodyAndResponseNames = [node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : void 0, resolver.resolveResponseName(node)];
+	const bodyAndResponseNames = [node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : null, resolver.resolveResponseName(node)];
 	const result = (options.order === "body-response-first" ? [
 		...bodyAndResponseNames,
 		...paramNames,
@@ -444,7 +471,7 @@ function buildParamsMapping(originalParams, mappedParams) {
 		mapping[param.name] = mappedName;
 		if (param.name !== mappedName) hasChanged = true;
 	});
-	return hasChanged ? mapping : void 0;
+	return hasChanged ? mapping : null;
 }
 //#endregion
 //#region src/functionParams.ts
@@ -457,18 +484,18 @@ function createType(type) {
 	return type ? _kubb_core.ast.createParamsType({
 		variant: "reference",
 		name: type
-	}) : void 0;
+	}) : null;
 }
 function createDeclarationLeaf(name, spec) {
 	if (spec.default !== void 0) return _kubb_core.ast.createFunctionParameter({
 		name,
-		type: createType(spec.type),
+		type: createType(spec.type) ?? void 0,
 		default: spec.default,
 		rest: spec.mode === "inlineSpread"
 	});
 	return _kubb_core.ast.createFunctionParameter({
 		name,
-		type: createType(spec.type),
+		type: createType(spec.type) ?? void 0,
 		optional: !!spec.optional,
 		rest: spec.mode === "inlineSpread"
 	});
@@ -477,14 +504,14 @@ function createDeclarationParam(name, spec) {
 	if (isGroup(spec)) return _kubb_core.ast.createParameterGroup({
 		inline: spec.mode === "inlineSpread",
 		default: spec.default,
-		properties: Object.entries(spec.children).filter(([, child]) => child !== void 0).map(([childName, child]) => createDeclarationLeaf(childName, child))
+		properties: Object.entries(spec.children).filter(([, child]) => child != null).map(([childName, child]) => createDeclarationLeaf(childName, child))
 	});
 	return createDeclarationLeaf(name, spec);
 }
 function createCallParam(name, spec) {
 	if (isGroup(spec)) return _kubb_core.ast.createParameterGroup({
 		inline: spec.mode === "inlineSpread",
-		properties: Object.entries(spec.children).filter(([, child]) => child !== void 0).map(([childName, child]) => _kubb_core.ast.createFunctionParameter({
+		properties: Object.entries(spec.children).filter(([, child]) => child != null).map(([childName, child]) => _kubb_core.ast.createFunctionParameter({
 			name: child?.mode === "inlineSpread" ? spec.mode === "inlineSpread" ? child.value ?? childName : `...${child.value ?? childName}` : child?.value ? `${childName}: ${child.value}` : childName,
 			rest: spec.mode === "inlineSpread" && child?.mode === "inlineSpread"
 		}))
@@ -499,7 +526,7 @@ function createCallParam(name, spec) {
 * Returns utilities to output constructor signatures (`toConstructor()`) or call expressions (`toCall()`).
 */
 function createFunctionParams(params) {
-	const entries = Object.entries(params).filter(([, spec]) => spec !== void 0);
+	const entries = Object.entries(params).filter(([, spec]) => spec != null);
 	return {
 		toConstructor() {
 			return declarationPrinter$4.print(_kubb_core.ast.createFunctionParameters({ params: entries.map(([name, spec]) => createDeclarationParam(name, spec)) })) ?? "";
@@ -537,7 +564,7 @@ function Url({ name, isExportable = true, isIndexable = true, baseURL, paramsTyp
 	const paramsSignature = declarationPrinter$3.print(paramsNode) ?? "";
 	const { path: originalPathParams } = getOperationParameters(node);
 	const { path: casedPathParams } = getOperationParameters(node, { paramsCasing });
-	const pathParamsMapping = paramsCasing ? buildParamsMapping(originalPathParams, casedPathParams) : void 0;
+	const pathParamsMapping = paramsCasing ? buildParamsMapping(originalPathParams, casedPathParams) : null;
 	return /* @__PURE__ */ (0, _kubb_renderer_jsx_jsx_runtime.jsx)(_kubb_renderer_jsx.File.Source, {
 		name,
 		isExportable,
@@ -584,19 +611,20 @@ function Client({ name, isExportable = true, isIndexable = true, returnType, bas
 	const isFormData = !isMultipleContentTypes && contentType === "multipart/form-data";
 	const { path: originalPathParams, query: originalQueryParams, header: originalHeaderParams } = getOperationParameters(node);
 	const { path: casedPathParams, query: casedQueryParams, header: casedHeaderParams } = getOperationParameters(node, { paramsCasing });
-	const pathParamsMapping = paramsCasing && !urlName ? buildParamsMapping(originalPathParams, casedPathParams) : void 0;
-	const queryParamsMapping = paramsCasing ? buildParamsMapping(originalQueryParams, casedQueryParams) : void 0;
-	const headerParamsMapping = paramsCasing ? buildParamsMapping(originalHeaderParams, casedHeaderParams) : void 0;
-	const requestName = node.requestBody?.content?.[0]?.schema ? tsResolver.resolveDataName(node) : void 0;
-	const responseName = tsResolver.resolveResponseName(node);
-	const queryParamsName = originalQueryParams.length > 0 ? tsResolver.resolveQueryParamsName(node, originalQueryParams[0]) : void 0;
-	const headerParamsName = originalHeaderParams.length > 0 ? tsResolver.resolveHeaderParamsName(node, originalHeaderParams[0]) : void 0;
-	const zodResponseName = zodResolver && parser === "zod" ? zodResolver.resolveResponseName?.(node) : void 0;
-	const zodRequestName = zodResolver && parser === "zod" && node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : void 0;
+	const pathParamsMapping = paramsCasing && !urlName ? buildParamsMapping(originalPathParams, casedPathParams) : null;
+	const queryParamsMapping = paramsCasing ? buildParamsMapping(originalQueryParams, casedQueryParams) : null;
+	const headerParamsMapping = paramsCasing ? buildParamsMapping(originalHeaderParams, casedHeaderParams) : null;
+	const requestName = node.requestBody?.content?.[0]?.schema ? tsResolver.resolveDataName(node) : null;
+	const successNames = resolveSuccessNames(node, tsResolver);
+	const responseName = successNames.length > 0 ? successNames.join(" | ") : tsResolver.resolveResponseName(node);
+	const queryParamsName = originalQueryParams.length > 0 ? tsResolver.resolveQueryParamsName(node, originalQueryParams[0]) : null;
+	const headerParamsName = originalHeaderParams.length > 0 ? tsResolver.resolveHeaderParamsName(node, originalHeaderParams[0]) : null;
+	const zodResponseName = zodResolver && parser === "zod" ? zodResolver.resolveResponseName?.(node) : null;
+	const zodRequestName = zodResolver && parser === "zod" && node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : null;
 	const errorNames = node.responses.filter((r) => {
 		return Number.parseInt(r.statusCode, 10) >= 400;
 	}).map((r) => tsResolver.resolveResponseStatusName(node, r.statusCode));
-	const headers = [!isMultipleContentTypes && contentType !== "application/json" && contentType !== "multipart/form-data" ? `'Content-Type': '${contentType}'` : void 0, headerParamsName ? headerParamsMapping ? "...mappedHeaders" : "...headers" : void 0].filter(Boolean);
+	const headers = [!isMultipleContentTypes && contentType !== "application/json" && contentType !== "multipart/form-data" ? `'Content-Type': '${contentType}'` : null, headerParamsName ? headerParamsMapping ? "...mappedHeaders" : "...headers" : null].filter(Boolean);
 	const generics = [
 		responseName,
 		`ResponseErrorConfig<${errorNames.length > 0 ? errorNames.join(" | ") : "Error"}>`,
@@ -624,12 +652,12 @@ function Client({ name, isExportable = true, isIndexable = true, returnType, bas
 		children: {
 			method: { value: JSON.stringify(node.method.toUpperCase()) },
 			url: { value: urlName ? `${urlName}(${urlParamsCall}).url.toString()` : path.template },
-			baseURL: baseURL && !urlName ? { value: `\`${baseURL}\`` } : void 0,
-			params: queryParamsName ? queryParamsMapping ? { value: "mappedParams" } : {} : void 0,
-			data: requestName ? { value: isMultipleContentTypes && hasFormData ? "contentType === 'multipart/form-data' ? formData as FormData : requestData" : isFormData ? "formData as FormData" : "requestData" } : void 0,
-			contentType: isConfigurable && isMultipleContentTypes ? {} : void 0,
-			requestConfig: isConfigurable ? { mode: "inlineSpread" } : void 0,
-			headers: headers.length ? { value: isConfigurable ? `{ ${headers.join(", ")}, ...requestConfig.headers }` : `{ ${headers.join(", ")} }` } : void 0
+			baseURL: baseURL && !urlName ? { value: `\`${baseURL}\`` } : null,
+			params: queryParamsName ? queryParamsMapping ? { value: "mappedParams" } : {} : null,
+			data: requestName ? { value: isMultipleContentTypes && hasFormData ? "contentType === 'multipart/form-data' ? formData as FormData : requestData" : isFormData ? "formData as FormData" : "requestData" } : null,
+			contentType: isConfigurable && isMultipleContentTypes ? {} : null,
+			requestConfig: isConfigurable ? { mode: "inlineSpread" } : null,
+			headers: headers.length ? { value: isConfigurable ? `{ ${headers.join(", ")}, ...requestConfig.headers }` : `{ ${headers.join(", ")} }` } : null
 		}
 	} });
 	const childrenElement = children ? children : /* @__PURE__ */ (0, _kubb_renderer_jsx_jsx_runtime.jsxs)(_kubb_renderer_jsx_jsx_runtime.Fragment, { children: [
@@ -687,15 +715,16 @@ function Client({ name, isExportable = true, isIndexable = true, returnType, bas
 * Includes Content-Type (if not default) and spreads header parameters if present.
 */
 function buildHeaders(contentType, hasHeaderParams) {
-	return [contentType !== "application/json" && contentType !== "multipart/form-data" ? `'Content-Type': '${contentType}'` : void 0, hasHeaderParams ? "...headers" : void 0].filter(Boolean);
+	return [contentType !== "application/json" && contentType !== "multipart/form-data" ? `'Content-Type': '${contentType}'` : null, hasHeaderParams ? "...headers" : null].filter(Boolean);
 }
 /**
 * Builds TypeScript generic parameters for a client method.
 * Includes response type, error type, and optional request type.
 */
 function buildGenerics(node, tsResolver) {
-	const responseName = tsResolver.resolveResponseName(node);
-	const requestName = node.requestBody?.content?.[0]?.schema ? tsResolver.resolveDataName(node) : void 0;
+	const successNames = resolveSuccessNames(node, tsResolver);
+	const responseName = successNames.length > 0 ? successNames.join(" | ") : tsResolver.resolveResponseName(node);
+	const requestName = node.requestBody?.content?.[0]?.schema ? tsResolver.resolveDataName(node) : null;
 	const errorNames = node.responses.filter((r) => Number.parseInt(r.statusCode, 10) >= 400).map((r) => tsResolver.resolveResponseStatusName(node, r.statusCode));
 	return [
 		responseName,
@@ -709,19 +738,19 @@ function buildGenerics(node, tsResolver) {
 */
 function buildClassClientParams({ node, path, baseURL, tsResolver, isFormData, isMultipleContentTypes, hasFormData, headers }) {
 	const { query: queryParams } = getOperationParameters(node);
-	const queryParamsName = queryParams.length > 0 ? tsResolver.resolveQueryParamsName(node, queryParams[0]) : void 0;
-	const requestName = node.requestBody?.content?.[0]?.schema ? tsResolver.resolveDataName(node) : void 0;
+	const queryParamsName = queryParams.length > 0 ? tsResolver.resolveQueryParamsName(node, queryParams[0]) : null;
+	const requestName = node.requestBody?.content?.[0]?.schema ? tsResolver.resolveDataName(node) : null;
 	return createFunctionParams({ config: {
 		mode: "object",
 		children: {
 			requestConfig: { mode: "inlineSpread" },
 			method: { value: JSON.stringify(node.method.toUpperCase()) },
 			url: { value: path.template },
-			baseURL: baseURL ? { value: JSON.stringify(baseURL) } : void 0,
-			params: queryParamsName ? {} : void 0,
-			data: requestName ? { value: isMultipleContentTypes && hasFormData ? "contentType === 'multipart/form-data' ? formData as FormData : requestData" : isFormData ? "formData as FormData" : "requestData" } : void 0,
-			contentType: isMultipleContentTypes ? {} : void 0,
-			headers: headers.length ? { value: `{ ${headers.join(", ")}, ...requestConfig.headers }` } : void 0
+			baseURL: baseURL ? { value: JSON.stringify(baseURL) } : null,
+			params: queryParamsName ? {} : null,
+			data: requestName ? { value: isMultipleContentTypes && hasFormData ? "contentType === 'multipart/form-data' ? formData as FormData : requestData" : isFormData ? "formData as FormData" : "requestData" } : null,
+			contentType: isMultipleContentTypes ? {} : null,
+			headers: headers.length ? { value: `{ ${headers.join(", ")}, ...requestConfig.headers }` } : null
 		}
 	} });
 }
@@ -730,7 +759,7 @@ function buildClassClientParams({ node, path, baseURL, tsResolver, isFormData, i
 * Applies Zod validation if configured, otherwise uses data directly.
 */
 function buildRequestDataLine({ parser, node, zodResolver }) {
-	const zodRequestName = zodResolver && parser === "zod" && node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : void 0;
+	const zodRequestName = zodResolver && parser === "zod" && node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : null;
 	if (parser === "zod" && zodRequestName) return `const requestData = ${zodRequestName}.parse(data)`;
 	if (node.requestBody?.content?.[0]?.schema) return "const requestData = data";
 	return "";
@@ -747,7 +776,7 @@ function buildFormDataLine(isFormData, hasRequest) {
 * Applies Zod validation to response data if configured, otherwise returns raw response.
 */
 function buildReturnStatement({ dataReturnType, parser, node, zodResolver }) {
-	const zodResponseName = zodResolver && parser === "zod" ? zodResolver.resolveResponseName?.(node) : void 0;
+	const zodResponseName = zodResolver && parser === "zod" ? zodResolver.resolveResponseName?.(node) : null;
 	if (dataReturnType === "full" && parser === "zod" && zodResponseName) return `return {...res, data: ${zodResponseName}.parse(res.data)}`;
 	if (dataReturnType === "data" && parser === "zod" && zodResponseName) return `return ${zodResponseName}.parse(res.data)`;
 	if (dataReturnType === "full" && parser === "client") return "return res";
@@ -761,7 +790,7 @@ function generateMethod$1({ node, name, tsResolver, zodResolver, baseURL, dataRe
 	const { defaultContentType: contentType, isMultipleContentTypes, hasFormData } = getContentTypeInfo(node);
 	const isFormData = !isMultipleContentTypes && contentType === "multipart/form-data";
 	const { header: headerParams } = getOperationParameters(node);
-	const headerParamsName = headerParams.length > 0 ? tsResolver.resolveHeaderParamsName(node, headerParams[0]) : void 0;
+	const headerParamsName = headerParams.length > 0 ? tsResolver.resolveHeaderParamsName(node, headerParams[0]) : null;
 	const headers = isMultipleContentTypes ? headerParamsName ? ["...headers"] : [] : buildHeaders(contentType, !!headerParamsName);
 	const generics = buildGenerics(node, tsResolver);
 	const paramsNode = buildClientParamsNode({
@@ -862,9 +891,14 @@ function resolveTypeImportNames$1(node, tsResolver) {
 }
 require_chunk.__name(resolveTypeImportNames$1, "resolveTypeImportNames");
 function resolveZodImportNames$1(node, zodResolver) {
-	return [zodResolver.resolveResponseName?.(node), node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : void 0].filter((n) => Boolean(n));
+	return [zodResolver.resolveResponseName?.(node), node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : null].filter((n) => Boolean(n));
 }
 require_chunk.__name(resolveZodImportNames$1, "resolveZodImportNames");
+/**
+* Built-in `operations` generator for `@kubb/plugin-client` when
+* `clientType: 'class'`. Emits one class per tag, with one instance method
+* per operation and a shared constructor for request configuration.
+*/
 const classClientGenerator = (0, _kubb_core.defineGenerator)({
 	name: "classClient",
 	renderer: _kubb_renderer_jsx.jsxRendererSync,
@@ -876,8 +910,8 @@ const classClientGenerator = (0, _kubb_core.defineGenerator)({
 		if (!pluginTs) return null;
 		const tsResolver = driver.getResolver(_kubb_plugin_ts.pluginTsName);
 		const tsPluginOptions = pluginTs.options;
-		const pluginZod = parser === "zod" ? driver.getPlugin(_kubb_plugin_zod.pluginZodName) : void 0;
-		const zodResolver = pluginZod ? driver.getResolver(_kubb_plugin_zod.pluginZodName) : void 0;
+		const pluginZod = parser === "zod" ? driver.getPlugin(_kubb_plugin_zod.pluginZodName) : null;
+		const zodResolver = pluginZod ? driver.getResolver(_kubb_plugin_zod.pluginZodName) : null;
 		function buildOperationData(node) {
 			const typeFile = tsResolver.resolveFile({
 				name: node.operationId,
@@ -897,8 +931,8 @@ const classClientGenerator = (0, _kubb_core.defineGenerator)({
 			}, {
 				root,
 				output: pluginZod.options?.output ?? output,
-				group: pluginZod.options?.group
-			}) : void 0;
+				group: pluginZod.options?.group ?? void 0
+			}) : null;
 			return {
 				node,
 				name: resolver.resolveName(node.operationId),
@@ -919,7 +953,7 @@ const classClientGenerator = (0, _kubb_core.defineGenerator)({
 				}, {
 					root,
 					output,
-					group
+					group: group ?? void 0
 				});
 				const operationData = buildOperationData(operationNode);
 				const previous = acc.find((item) => item.file.path === file.path);
@@ -941,7 +975,7 @@ const classClientGenerator = (0, _kubb_core.defineGenerator)({
 				}, {
 					root,
 					output,
-					group
+					group: group ?? void 0
 				});
 				const operationData = buildOperationData(operationNode);
 				const previous = acc.find((item) => item.file.path === file.path);
@@ -1098,7 +1132,7 @@ const classClientGenerator = (0, _kubb_core.defineGenerator)({
 			}, {
 				root,
 				output,
-				group
+				group: group ?? void 0
 			});
 			files.push(/* @__PURE__ */ (0, _kubb_renderer_jsx_jsx_runtime.jsxs)(_kubb_renderer_jsx.File, {
 				baseName: sdkFile.baseName,
@@ -1143,6 +1177,11 @@ const classClientGenerator = (0, _kubb_core.defineGenerator)({
 });
 //#endregion
 //#region src/generators/clientGenerator.tsx
+/**
+* Built-in operation generator for `@kubb/plugin-client`. Emits one async
+* function per OpenAPI operation, plus the matching URL helper. Used when
+* `clientType: 'function'` (the default).
+*/
 const clientGenerator = (0, _kubb_core.defineGenerator)({
 	name: "client",
 	renderer: _kubb_renderer_jsx.jsxRendererSync,
@@ -1153,10 +1192,10 @@ const clientGenerator = (0, _kubb_core.defineGenerator)({
 		const pluginTs = driver.getPlugin(_kubb_plugin_ts.pluginTsName);
 		if (!pluginTs) return null;
 		const tsResolver = driver.getResolver(_kubb_plugin_ts.pluginTsName);
-		const pluginZod = parser === "zod" ? driver.getPlugin(_kubb_plugin_zod.pluginZodName) : void 0;
-		const zodResolver = pluginZod ? driver.getResolver(_kubb_plugin_zod.pluginZodName) : void 0;
+		const pluginZod = parser === "zod" ? driver.getPlugin(_kubb_plugin_zod.pluginZodName) : null;
+		const zodResolver = pluginZod ? driver.getResolver(_kubb_plugin_zod.pluginZodName) : null;
 		const importedTypeNames = resolveOperationTypeNames(node, tsResolver, { paramsCasing });
-		const importedZodNames = zodResolver && parser === "zod" ? [zodResolver.resolveResponseName?.(node), node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : void 0].filter((name) => Boolean(name)) : [];
+		const importedZodNames = zodResolver && parser === "zod" ? [zodResolver.resolveResponseName?.(node), node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : null].filter((name) => Boolean(name)) : [];
 		const meta = {
 			name: resolver.resolveName(node.operationId),
 			urlName: resolver.resolveUrlName(node),
@@ -1168,7 +1207,7 @@ const clientGenerator = (0, _kubb_core.defineGenerator)({
 			}, {
 				root,
 				output,
-				group
+				group: group ?? void 0
 			}),
 			fileTs: tsResolver.resolveFile({
 				name: node.operationId,
@@ -1178,7 +1217,7 @@ const clientGenerator = (0, _kubb_core.defineGenerator)({
 			}, {
 				root,
 				output: pluginTs.options?.output ?? output,
-				group: pluginTs.options?.group
+				group: pluginTs.options?.group ?? void 0
 			}),
 			fileZod: zodResolver && pluginZod?.options ? zodResolver.resolveFile({
 				name: node.operationId,
@@ -1188,8 +1227,8 @@ const clientGenerator = (0, _kubb_core.defineGenerator)({
 			}, {
 				root,
 				output: pluginZod.options.output ?? output,
-				group: pluginZod.options?.group
-			}) : void 0
+				group: pluginZod.options?.group ?? void 0
+			}) : null
 		};
 		const hasFormData = node.requestBody?.content?.some((e) => e.contentType === "multipart/form-data") ?? false;
 		return /* @__PURE__ */ (0, _kubb_renderer_jsx_jsx_runtime.jsxs)(_kubb_renderer_jsx.File, {
@@ -1276,6 +1315,12 @@ const clientGenerator = (0, _kubb_core.defineGenerator)({
 });
 //#endregion
 //#region src/generators/groupedClientGenerator.tsx
+/**
+* Emits one aggregate file per tag/group when `group` is configured. Each
+* file re-exports every client function for that group, so callers can
+* `import { petController } from './gen/clients'` instead of importing
+* each operation individually.
+*/
 const groupedClientGenerator = (0, _kubb_core.defineGenerator)({
 	name: "groupedClient",
 	renderer: _kubb_renderer_jsx.jsxRendererSync,
@@ -1285,7 +1330,7 @@ const groupedClientGenerator = (0, _kubb_core.defineGenerator)({
 		return /* @__PURE__ */ (0, _kubb_renderer_jsx_jsx_runtime.jsx)(_kubb_renderer_jsx_jsx_runtime.Fragment, { children: nodes.reduce((acc, operationNode) => {
 			if (group?.type === "tag") {
 				const tag = operationNode.tags[0];
-				const name = tag ? group?.name?.({ group: camelCase(tag) }) : void 0;
+				const name = tag ? group?.name?.({ group: camelCase(tag) }) : null;
 				if (!tag || !name) return acc;
 				const file = resolver.resolveFile({
 					name,
@@ -1294,7 +1339,7 @@ const groupedClientGenerator = (0, _kubb_core.defineGenerator)({
 				}, {
 					root,
 					output,
-					group
+					group: group ?? void 0
 				});
 				const clientFile = resolver.resolveFile({
 					name: operationNode.operationId,
@@ -1304,7 +1349,7 @@ const groupedClientGenerator = (0, _kubb_core.defineGenerator)({
 				}, {
 					root,
 					output,
-					group
+					group: group ?? void 0
 				});
 				const client = {
 					name: resolver.resolveName(operationNode.operationId),
@@ -1373,6 +1418,12 @@ function Operations({ name, nodes }) {
 }
 //#endregion
 //#region src/generators/operationsGenerator.tsx
+/**
+* Generates an `operations.ts` file that re-exports every operation grouped
+* by HTTP method. Enabled when `pluginClient({ operations: true })`. Useful
+* for building meta-tooling on top of the generated client (route
+* registries, API explorers).
+*/
 const operationsGenerator = (0, _kubb_core.defineGenerator)({
 	name: "client",
 	renderer: _kubb_renderer_jsx.jsxRendererSync,
@@ -1386,7 +1437,7 @@ const operationsGenerator = (0, _kubb_core.defineGenerator)({
 		}, {
 			root,
 			output,
-			group
+			group: group ?? void 0
 		});
 		return /* @__PURE__ */ (0, _kubb_renderer_jsx_jsx_runtime.jsx)(_kubb_renderer_jsx.File, {
 			baseName: file.baseName,
@@ -1415,7 +1466,7 @@ function generateMethod({ node, name, tsResolver, zodResolver, baseURL, dataRetu
 	const { defaultContentType: contentType, isMultipleContentTypes, hasFormData } = getContentTypeInfo(node);
 	const isFormData = !isMultipleContentTypes && contentType === "multipart/form-data";
 	const { header: headerParams } = getOperationParameters(node);
-	const headerParamsName = headerParams.length > 0 ? tsResolver.resolveHeaderParamsName(node, headerParams[0]) : void 0;
+	const headerParamsName = headerParams.length > 0 ? tsResolver.resolveHeaderParamsName(node, headerParams[0]) : null;
 	const headers = isMultipleContentTypes ? headerParamsName ? ["...headers"] : [] : buildHeaders(contentType, !!headerParamsName);
 	const generics = buildGenerics(node, tsResolver);
 	const paramsNode = buildClientParamsNode({
@@ -1489,8 +1540,14 @@ function resolveTypeImportNames(node, tsResolver) {
 	return resolveOperationTypeNames(node, tsResolver, { order: "body-response-first" });
 }
 function resolveZodImportNames(node, zodResolver) {
-	return [zodResolver.resolveResponseName?.(node), node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : void 0].filter((n) => Boolean(n));
+	return [zodResolver.resolveResponseName?.(node), node.requestBody?.content?.[0]?.schema ? zodResolver.resolveDataName?.(node) : null].filter((n) => Boolean(n));
 }
+/**
+* Built-in `operations` generator for `@kubb/plugin-client` when
+* `clientType: 'staticClass'`. Emits one class per tag, with a static method
+* per operation so callers can use `Pet.getPetById(...)` without
+* instantiating the class.
+*/
 const staticClassClientGenerator = (0, _kubb_core.defineGenerator)({
 	name: "staticClassClient",
 	renderer: _kubb_renderer_jsx.jsxRendererSync,
@@ -1502,8 +1559,8 @@ const staticClassClientGenerator = (0, _kubb_core.defineGenerator)({
 		if (!pluginTs) return null;
 		const tsResolver = driver.getResolver(_kubb_plugin_ts.pluginTsName);
 		const tsPluginOptions = pluginTs.options;
-		const pluginZod = parser === "zod" ? driver.getPlugin(_kubb_plugin_zod.pluginZodName) : void 0;
-		const zodResolver = pluginZod ? driver.getResolver(_kubb_plugin_zod.pluginZodName) : void 0;
+		const pluginZod = parser === "zod" ? driver.getPlugin(_kubb_plugin_zod.pluginZodName) : null;
+		const zodResolver = pluginZod ? driver.getResolver(_kubb_plugin_zod.pluginZodName) : null;
 		function buildOperationData(node) {
 			const typeFile = tsResolver.resolveFile({
 				name: node.operationId,
@@ -1523,8 +1580,8 @@ const staticClassClientGenerator = (0, _kubb_core.defineGenerator)({
 			}, {
 				root,
 				output: pluginZod.options?.output ?? output,
-				group: pluginZod.options?.group
-			}) : void 0;
+				group: pluginZod.options?.group ?? void 0
+			}) : null;
 			return {
 				node,
 				name: resolver.resolveName(node.operationId),
@@ -1545,7 +1602,7 @@ const staticClassClientGenerator = (0, _kubb_core.defineGenerator)({
 				}, {
 					root,
 					output,
-					group
+					group: group ?? void 0
 				});
 				const operationData = buildOperationData(operationNode);
 				const previous = acc.find((item) => item.file.path === file.path);
@@ -1566,7 +1623,7 @@ const staticClassClientGenerator = (0, _kubb_core.defineGenerator)({
 				}, {
 					root,
 					output,
-					group
+					group: group ?? void 0
 				});
 				const operationData = buildOperationData(operationNode);
 				const previous = acc.find((item) => item.file.path === file.path);
@@ -1720,18 +1777,25 @@ const staticClassClientGenerator = (0, _kubb_core.defineGenerator)({
 //#endregion
 //#region src/resolvers/resolverClient.ts
 /**
-* Naming convention resolver for client plugin.
+* Default resolver used by `@kubb/plugin-client`. Decides the names and file
+* paths for every generated client function or class. Functions and files use
+* camelCase; classes and tag groups use PascalCase.
 *
-* Provides default naming helpers using camelCase for functions and file paths.
+* @example Resolve client function and class names
+* ```ts
+* import { resolverClient } from '@kubb/plugin-client'
 *
-* @example
-* `resolverClient.default('list pets', 'function')  // → 'listPets'`
+* resolverClient.default('list pets', 'function') // 'listPets'
+* resolverClient.resolveClassName('pet')          // 'Pet'
+* resolverClient.resolveUrlName(operationNode)    // 'getShowPetByIdUrl'
+* ```
 */
 const resolverClient = (0, _kubb_core.defineResolver)(() => ({
 	name: "default",
 	pluginName: "plugin-client",
 	default(name, type) {
-		return camelCase(name, { isFile: type === "file" });
+		const resolved = camelCase(name, { isFile: type === "file" });
+		return type === "file" ? resolved : ensureValidVarName(resolved);
 	},
 	resolveName(name) {
 		return this.default(name, "function");
@@ -1740,13 +1804,13 @@ const resolverClient = (0, _kubb_core.defineResolver)(() => ({
 		return this.default(name, type);
 	},
 	resolveClassName(name) {
-		return pascalCase(name);
+		return ensureValidVarName(pascalCase(name));
 	},
 	resolveGroupName(name) {
-		return pascalCase(name);
+		return ensureValidVarName(pascalCase(name));
 	},
 	resolveClientPropertyName(name) {
-		return camelCase(name);
+		return ensureValidVarName(camelCase(name));
 	},
 	resolveUrlName(node) {
 		const name = this.resolveName(node.operationId);
@@ -1756,19 +1820,32 @@ const resolverClient = (0, _kubb_core.defineResolver)(() => ({
 //#endregion
 //#region src/plugin.ts
 /**
-* Canonical plugin name for `@kubb/plugin-client`, used in driver lookups and warnings.
+* Canonical plugin name for `@kubb/plugin-client`. Used for driver lookups and
+* cross-plugin dependency references.
 */
 const pluginClientName = "plugin-client";
 /**
-* Generates type-safe HTTP client functions or classes from an OpenAPI specification.
-* Creates client APIs by walking operations and delegating to generators.
-* Writes barrel files based on the configured `barrelType`.
+* Generates one HTTP client function per OpenAPI operation. Each function has
+* typed path params, query params, body, and response, so callers use the API
+* like any other typed function. Ships with `axios` and `fetch` runtimes; bring
+* your own by setting `importPath`.
 *
-* @example Client generator
+* @example
 * ```ts
-* import pluginClient from '@kubb/plugin-client'
+* import { defineConfig } from 'kubb'
+* import { pluginTs } from '@kubb/plugin-ts'
+* import { pluginClient } from '@kubb/plugin-client'
+*
 * export default defineConfig({
-*   plugins: [pluginClient({ output: { path: 'clients' } })]
+*   input: { path: './petStore.yaml' },
+*   output: { path: './src/gen' },
+*   plugins: [
+*     pluginTs(),
+*     pluginClient({
+*       output: { path: './clients' },
+*       client: 'fetch',
+*     }),
+*   ],
 * })
 * ```
 */
@@ -1780,8 +1857,8 @@ const pluginClient = (0, _kubb_core.definePlugin)((options) => {
 	const resolvedImportPath = importPath ?? (!bundle ? `@kubb/plugin-client/clients/${client}` : void 0);
 	const selectedGenerators = options.generators ?? [
 		clientType === "staticClass" ? staticClassClientGenerator : clientType === "class" ? classClientGenerator : clientGenerator,
-		group && clientType === "function" ? groupedClientGenerator : void 0,
-		operations ? operationsGenerator : void 0
+		group && clientType === "function" ? groupedClientGenerator : null,
+		operations ? operationsGenerator : null
 	].filter((x) => Boolean(x));
 	const groupConfig = group ? {
 		...group,
@@ -1789,11 +1866,11 @@ const pluginClient = (0, _kubb_core.definePlugin)((options) => {
 			if (group.type === "path") return `${ctx.group.split("/")[1]}`;
 			return `${camelCase(ctx.group)}Controller`;
 		}
-	} : void 0;
+	} : null;
 	return {
 		name: pluginClientName,
 		options,
-		dependencies: [_kubb_plugin_ts.pluginTsName, parser === "zod" ? _kubb_plugin_zod.pluginZodName : void 0].filter((dependency) => Boolean(dependency)),
+		dependencies: [_kubb_plugin_ts.pluginTsName, parser === "zod" ? _kubb_plugin_zod.pluginZodName : null].filter((dependency) => Boolean(dependency)),
 		hooks: { "kubb:plugin:setup"(ctx) {
 			const resolver = userResolver ? {
 				...resolverClient,