@kubb/plugin-fetch 5.3.0-canary.20260907T104724 → 5.3.0

package/dist/index.d.ts

@@ -22,6 +22,14 @@ type ValidatorOptions = false | 'zod' | {
  * - `'flat'`: one class with every operation as a direct method.
  */
 type Mode = 'tag' | 'flat';
+/**
+ * Shape of the value a generated operation function resolves to.
+ * - `'full'`: the complete `{ status, data, error, contentType, request, response }` result.
+ * - `'data'`: the bare success body once `throwOnError` (on by default) narrows away the error
+ *   branch, falling back to the full result when a call sets `throwOnError: false` and still
+ *   needs `error` to discriminate a failed response.
+ */
+type ReturnTypeOption = 'full' | 'data';
 /**
  * The resolver shared by the client plugins. Inherits the built-in camelCase `name` and `file`;
  * classes and tag groups use PascalCase (with a `Client` suffix for groups).
@@ -76,6 +84,20 @@ type Options = OutputOptions & {
    * @default false
    */
   validator?: ValidatorOptions;
+  /**
+   * Shape of the value a generated operation function resolves to. Applies to the standalone
+   * functions and the class-based SDK; not to the query-hook plugins (`@kubb/plugin-react-query`,
+   * `@kubb/plugin-vue-query`, `@kubb/plugin-swr`), which keep calling the client directly and
+   * expect the full result.
+   *
+   * @default 'full'
+   * @example
+   * ```ts
+   * pluginAxios({ returnType: 'data' })
+   * // const pet = await getPetById({ path: { petId: 1 } }) // Pet, not { status, data, ... }
+   * ```
+   */
+  returnType?: ReturnTypeOption;
   /**
    * Generates a class-based SDK instead of the standalone functions. Each tag client is an instance
    * class whose constructor takes a client config and builds its own client, so every environment is
@@ -142,6 +164,7 @@ type ResolvedOptions = {
   group: Group | null;
   baseURL: Options['baseURL'];
   validator: NonNullable<Options['validator']>;
+  returnType: ReturnTypeOption;
   sdk: {
     mode: Mode;
     name: string | undefined;

package/dist/index.js

@@ -450,23 +450,49 @@ function createGroupConfig(group) {
 function buildRequestResultGenerics({ node, types }) {
 	return `${types.response.responses(node)}, ThrowOnError`;
 }
+/**
+* Builds the full return type an operation's function signature uses: `Unwrappable<RequestResult>`
+* for the default `returnType: 'full'`, already a promise so no further wrapping is needed, or a
+* `Promise` of the runtime's `UnwrappedResult` when `returnType: 'data'` narrows a resolved call
+* down to the bare success body.
+*
+* @example
+* `buildResultType({ node, types, returnType: 'data' }) // 'Promise<UnwrappedResult<AddPetResponses, ThrowOnError>>'`
+*/
+function buildResultType({ node, types, returnType }) {
+	const generics = buildRequestResultGenerics({
+		node,
+		types
+	});
+	return returnType === "data" ? `Promise<UnwrappedResult<${generics}>>` : `Unwrappable<RequestResult<${generics}>>`;
+}
 //#endregion
 //#region ../../internals/client/src/builders/returnStatement.ts
 /**
-* Builds the return statement of a generated operation function. The runtime call already resolves
-* to `{ data, error, request, response }`. The generated code casts that result to the operation's
-* `RequestResult`, then wraps it with `withUnwrap`, so the caller can `await` it directly or call
-* `.unwrap()` for the bare success body.
+* Builds the return statement of a generated operation function. With the default
+* `returnType: 'full'` the runtime call already resolves to `{ data, error, request, response }`.
+* The generated code casts that result to the operation's `RequestResult`, then wraps it with
+* `withUnwrap`, so the caller can `await` it directly or call `.unwrap()` for the bare success
+* body. With `returnType: 'data'` it instead routes the call through the runtime's `unwrapResult`,
+* which narrows the resolved value down to the bare success body the same way `RequestResult`
+* already does, keeping the `throwOnError` default in one place instead of restating it per call.
 *
-* Cast first, wrap second. That order keeps `withUnwrap`'s generic inferred as `RequestResult`
-* instead of the runtime's own internal result type. Casting an `Unwrappable<A>` straight to
-* `Unwrappable<B>` does not work: the `.then` overload stays pinned to `A`, and `as` rejects that
-* two-generic swap even where `A` and `B` on their own would satisfy it.
+* Cast first, wrap second, for the `'full'` path. That order keeps `withUnwrap`'s generic inferred
+* as `RequestResult` instead of the runtime's own internal result type. Casting an `Unwrappable<A>`
+* straight to `Unwrappable<B>` does not work: the `.then` overload stays pinned to `A`, and `as`
+* rejects that two-generic swap even where `A` and `B` on their own would satisfy it.
 *
 * @example
 * `return withUnwrap(request({ method: 'POST', url: '/pet', ...config }) as Promise<RequestResult<AddPetResponses, ThrowOnError>>)`
+* @example
+* `return unwrapResult(request({ method: 'POST', url: '/pet', ...config }), config.throwOnError) as Promise<UnwrappedResult<AddPetResponses, ThrowOnError>>`
 */
-function buildReturnStatement({ node, types, callConfig }) {
+function buildReturnStatement({ node, types, callConfig, returnType }) {
+	if (returnType === "data") return `return unwrapResult(request(${callConfig}), config.throwOnError) as ${buildResultType({
+		node,
+		types,
+		returnType
+	})}`;
 	return `return withUnwrap(request(${callConfig}) as Promise<RequestResult<${buildRequestResultGenerics({
 		node,
 		types
@@ -552,7 +578,7 @@ const declarationPrinter = functionPrinter({ mode: "declaration" });
 * per-operation input type has to be emitted. Both names come from `types`, which is `plugin-ts` or
 * `plugin-zod`'s inferred types (see `resolveOperationTypes`).
 */
-function buildGroupedOptionsSignature({ node, types }) {
+function buildGroupedOptionsSignature({ node, types, returnType }) {
 	const optionsName = types.response.options(node);
 	const { isOptional } = getRequestGroupOptionality(node);
 	return {
@@ -561,10 +587,11 @@ function buildGroupedOptionsSignature({ node, types }) {
 			type: `Options<${optionsName}, ThrowOnError>`,
 			...isOptional ? { default: "{}" } : {}
 		})] })) ?? "",
-		returnType: `Unwrappable<RequestResult<${buildRequestResultGenerics({
+		returnType: buildResultType({
 			node,
-			types
-		})}>>`,
+			types,
+			returnType
+		}),
 		generics: ["ThrowOnError extends boolean = true"]
 	};
 }
@@ -685,11 +712,12 @@ function buildCallConfig({ node, validator, zodResolver, security }) {
 * instance client, so one operation can be routed to a different environment without a new
 * instance.
 */
-function buildSdkMethod({ node, name, types, zodResolver, validator, security }) {
+function buildSdkMethod({ node, name, types, zodResolver, validator, security, returnType }) {
 	if (!ast.isHttpOperationNode(node)) return "";
 	const signature = buildGroupedOptionsSignature({
 		node,
-		types
+		types,
+		returnType
 	});
 	const returnStatement = buildReturnStatement({
 		node,
@@ -699,7 +727,8 @@ function buildSdkMethod({ node, name, types, zodResolver, validator, security })
 			validator,
 			zodResolver,
 			security
-		})
+		}),
+		returnType
 	});
 	const generics = signature.generics.length ? `<${signature.generics.join(", ")}>` : "";
 	const jsdoc = buildJSDoc(buildOperationComments(node, {
@@ -775,11 +804,12 @@ function buildStyles({ node }) {
 * type, signature, and call config are built with the AST factory, and only the jsx-renderer emits
 * the source.
 */
-function Operation({ name, node, types, zodResolver, validator, security, isExportable = true, isIndexable = true }) {
+function Operation({ name, node, types, zodResolver, validator, returnType, security, isExportable = true, isIndexable = true }) {
 	if (!ast.isHttpOperationNode(node)) return null;
 	const signature = buildGroupedOptionsSignature({
 		node,
-		types
+		types,
+		returnType
 	});
 	const validators = buildValidatorHooks({
 		node,
@@ -812,11 +842,12 @@ function Operation({ name, node, types, zodResolver, validator, security, isExpo
 		"...config"
 	].filter(Boolean).join(", ")} }`;
 	const eventType = `SuccessOf<${types.response.responses(node)}>`;
-	const returnType = eventStream ? `Promise<EventStreamResult<${eventType}>>` : signature.returnType;
+	const functionReturnType = eventStream ? `Promise<EventStreamResult<${eventType}>>` : signature.returnType;
 	const returnStatement = eventStream ? `return toEventStream<${eventType}>(request(${callConfig}))` : buildReturnStatement({
 		node,
 		types,
-		callConfig
+		callConfig,
+		returnType
 	});
 	return /* @__PURE__ */ jsx(File.Source, {
 		name,
@@ -827,7 +858,7 @@ function Operation({ name, node, types, zodResolver, validator, security, isExpo
 			export: isExportable,
 			generics: signature.generics,
 			params: signature.paramsSignature,
-			returnType,
+			returnType: functionReturnType,
 			JSDoc: { comments: buildOperationComments(node, {
 				link: "urlPath",
 				linkPosition: "beforeDeprecated",
@@ -849,14 +880,15 @@ function Operation({ name, node, types, zodResolver, validator, security, isExpo
 * instance: `const api = new PetClient({ baseURL }); api.getPetById(...)`. A per-call `client` option
 * still overrides the instance client for a one-off call.
 */
-function SdkClient({ name, isExportable = true, isIndexable = true, operations, validator, children }) {
+function SdkClient({ name, isExportable = true, isIndexable = true, operations, validator, returnType, children }) {
 	const methods = operations.map(({ node, name: methodName, types, zodResolver, security }) => buildSdkMethod({
 		node,
 		name: methodName,
 		types,
 		zodResolver,
 		validator,
-		security
+		security,
+		returnType
 	}));
 	const classCode = `export class ${name} {\n${[
 		"  private readonly client: ClientInstance",
@@ -936,7 +968,7 @@ function createClientGenerator(name) {
 		operation(node, ctx) {
 			if (!ast.isHttpOperationNode(node)) return null;
 			const { config, driver, resolver, root } = ctx;
-			const { output, validator, group } = ctx.options;
+			const { output, validator, returnType, group } = ctx.options;
 			const types = resolveOperationTypes(driver);
 			if (!types) {
 				ctx.warn(MISSING_OPERATION_TYPES_WARNING);
@@ -1003,7 +1035,7 @@ function createClientGenerator(name) {
 				}),
 				children: [
 					/* @__PURE__ */ jsx(File.Import, {
-						name: eventStream ? ["client", "toEventStream"] : ["client", "withUnwrap"],
+						name: eventStream ? ["client", "toEventStream"] : ["client", returnType === "data" ? "unwrapResult" : "withUnwrap"],
 						root: meta.file.path,
 						path: clientPath
 					}),
@@ -1012,7 +1044,7 @@ function createClientGenerator(name) {
 							"Options",
 							"EventStreamResult",
 							"SuccessOf"
-						] : [
+						] : returnType === "data" ? ["Options", "UnwrappedResult"] : [
 							"Options",
 							"Unwrappable",
 							"RequestResult"
@@ -1038,6 +1070,7 @@ function createClientGenerator(name) {
 						types,
 						zodResolver,
 						validator,
+						returnType,
 						security
 					})
 				]
@@ -1178,7 +1211,7 @@ function createSdkGenerator() {
 		renderer: jsxRenderer,
 		operations(nodes, ctx) {
 			const { config, resolver, root } = ctx;
-			const { output, group, validator, sdk } = ctx.options;
+			const { output, group, validator, returnType, sdk } = ctx.options;
 			if (!sdk) return null;
 			const types = resolveOperationTypes(ctx.driver);
 			if (!types) {
@@ -1223,12 +1256,17 @@ function createSdkGenerator() {
 					footer: footer(file),
 					children: [
 						/* @__PURE__ */ jsx(File.Import, {
-							name: ["createClient", "withUnwrap"],
+							name: ["createClient", returnType === "data" ? "unwrapResult" : "withUnwrap"],
 							root: file.path,
 							path: clientPath
 						}),
 						/* @__PURE__ */ jsx(File.Import, {
-							name: [
+							name: returnType === "data" ? [
+								"ClientConfig",
+								"ClientInstance",
+								"Options",
+								"UnwrappedResult"
+							] : [
 								"ClientConfig",
 								"ClientInstance",
 								"Options",
@@ -1258,7 +1296,8 @@ function createSdkGenerator() {
 						/* @__PURE__ */ jsx(SdkClient, {
 							name: className,
 							operations: ops,
-							validator
+							validator,
+							returnType
 						})
 					]
 				}, file.path);
@@ -1395,7 +1434,7 @@ const pluginFetch = definePlugin((options) => {
 	const { output = {
 		path: "clients",
 		barrel: { type: "named" }
-	}, exclude = [], include, override = [], baseURL, validator = false, group, sdk, resolver: userResolver } = options;
+	}, exclude = [], include, override = [], baseURL, validator = false, returnType = "full", group, sdk, resolver: userResolver } = options;
 	const resolved = {
 		output,
 		exclude,
@@ -1404,6 +1443,7 @@ const pluginFetch = definePlugin((options) => {
 		group: createGroupConfig(group),
 		baseURL,
 		validator,
+		returnType,
 		sdk: sdk ? {
 			mode: sdk.mode ?? "tag",
 			name: sdk.name