@navios/react-query 0.4.0 → 0.5.0

package/src/{types/client-instance.mts → client/types.mts}

@@ -1,5 +1,7 @@
 import type {
   BaseEndpointConfig,
+  EndpointFunctionArgs,
+  HttpMethod,
   UrlHasParams,
   UrlParams,
   Util_FlatObject,
@@ -14,14 +16,55 @@ import type {
 } from '@tanstack/react-query'
 import type { z, ZodObject, ZodType } from 'zod/v4'
 
-import type { ProcessResponseFunction, Split } from '../types.mjs'
-import type { ClientEndpointHelper } from './client-endpoint-helper.mjs'
-import type { ClientMutationArgs } from './mutation-args.mjs'
-import type { MutationHelpers } from './mutation-helpers.mjs'
-import type { ClientQueryArgs } from './query-args.mjs'
-import type { QueryHelpers } from './query-helpers.mjs'
+import type { ProcessResponseFunction, Split } from '../common/types.mjs'
+import type { MutationArgs, MutationHelpers } from '../mutation/types.mjs'
+import type { QueryArgs, QueryHelpers } from '../query/types.mjs'
 
+/**
+ * Helper type that attaches the endpoint to query/mutation results.
+ */
+export type EndpointHelper<
+  Method extends HttpMethod = HttpMethod,
+  Url extends string = string,
+  RequestSchema = unknown,
+  ResponseSchema extends z.ZodType = z.ZodType,
+  QuerySchema = unknown,
+> = {
+  endpoint: ((
+    params: Util_FlatObject<
+      EndpointFunctionArgs<Url, QuerySchema, RequestSchema>
+    >,
+  ) => Promise<z.output<ResponseSchema>>) & {
+    config: BaseEndpointConfig<
+      Method,
+      Url,
+      QuerySchema,
+      ResponseSchema,
+      RequestSchema
+    >
+  }
+}
+
+// Legacy export for backwards compatibility
+/** @deprecated Use EndpointHelper instead */
+export type ClientEndpointHelper<
+  Method extends HttpMethod = HttpMethod,
+  Url extends string = string,
+  RequestSchema = unknown,
+  ResponseSchema extends z.ZodType = z.ZodType,
+  QuerySchema = unknown,
+> = EndpointHelper<Method, Url, RequestSchema, ResponseSchema, QuerySchema>
+
+/**
+ * The main client instance interface.
+ * Provides methods for creating queries, infinite queries, and mutations.
+ */
 export interface ClientInstance {
+  // ============================================================================
+  // QUERY METHODS
+  // ============================================================================
+
+  // Standard query methods (GET, HEAD, OPTIONS) without query schema
   query<
     Method extends 'GET' | 'HEAD' | 'OPTIONS' = 'GET',
     Url extends string = string,
@@ -33,7 +76,7 @@ export interface ClientInstance {
     responseSchema: Response
     processResponse?: (data: z.output<Response>) => Result
   }): ((
-    params: Util_FlatObject<ClientQueryArgs<Url, undefined>>,
+    params: Util_FlatObject<QueryArgs<Url, undefined>>,
   ) => UseSuspenseQueryOptions<
     Result,
     Error,
@@ -41,8 +84,9 @@ export interface ClientInstance {
     DataTag<Split<Url, '/'>, Result, Error>
   >) &
     QueryHelpers<Url, undefined, Result> &
-    ClientEndpointHelper<Method, Url, undefined, Response>
+    EndpointHelper<Method, Url, undefined, Response>
 
+  // Standard query methods (GET, HEAD, OPTIONS) with query schema
   query<
     Method extends 'GET' | 'HEAD' | 'OPTIONS' = 'GET',
     Url extends string = string,
@@ -56,7 +100,7 @@ export interface ClientInstance {
     responseSchema: Response
     processResponse?: (data: z.output<Response>) => Result
   }): ((
-    params: Util_FlatObject<ClientQueryArgs<Url, QuerySchema>>,
+    params: Util_FlatObject<QueryArgs<Url, QuerySchema>>,
   ) => UseSuspenseQueryOptions<
     Result,
     Error,
@@ -64,8 +108,63 @@ export interface ClientInstance {
     DataTag<Split<Url, '/'>, Result, Error>
   >) &
     QueryHelpers<Url, QuerySchema, Result> &
-    ClientEndpointHelper<Method, Url, undefined, Response, QuerySchema>
+    EndpointHelper<Method, Url, undefined, Response, QuerySchema>
 
+  // POST query methods (for search endpoints) without query schema
+  query<
+    Method extends 'POST' = 'POST',
+    Url extends string = string,
+    RequestSchema extends ZodType = ZodType,
+    Response extends ZodType = ZodType,
+    Result = z.output<Response>,
+  >(config: {
+    method: Method
+    url: Url
+    requestSchema: RequestSchema
+    responseSchema: Response
+    processResponse?: (data: z.output<Response>) => Result
+  }): ((
+    params: Util_FlatObject<QueryArgs<Url, undefined, RequestSchema>>,
+  ) => UseSuspenseQueryOptions<
+    Result,
+    Error,
+    Result,
+    DataTag<Split<Url, '/'>, Result, Error>
+  >) &
+    QueryHelpers<Url, undefined, Result, false, RequestSchema> &
+    EndpointHelper<Method, Url, RequestSchema, Response>
+
+  // POST query methods (for search endpoints) with query schema
+  query<
+    Method extends 'POST' = 'POST',
+    Url extends string = string,
+    QuerySchema extends ZodObject = ZodObject,
+    RequestSchema extends ZodType = ZodType,
+    Response extends ZodType = ZodType,
+    Result = z.output<Response>,
+  >(config: {
+    method: Method
+    url: Url
+    querySchema: QuerySchema
+    requestSchema: RequestSchema
+    responseSchema: Response
+    processResponse?: (data: z.output<Response>) => Result
+  }): ((
+    params: Util_FlatObject<QueryArgs<Url, QuerySchema, RequestSchema>>,
+  ) => UseSuspenseQueryOptions<
+    Result,
+    Error,
+    Result,
+    DataTag<Split<Url, '/'>, Result, Error>
+  >) &
+    QueryHelpers<Url, QuerySchema, Result, false, RequestSchema> &
+    EndpointHelper<Method, Url, RequestSchema, Response, QuerySchema>
+
+  // ============================================================================
+  // INFINITE QUERY METHODS
+  // ============================================================================
+
+  // Standard infiniteQuery methods (GET, HEAD, OPTIONS)
   infiniteQuery<
     Method extends 'GET' | 'HEAD' | 'OPTIONS' = 'GET',
     Url extends string = string,
@@ -92,7 +191,7 @@ export interface ClientInstance {
       allPageParams: z.infer<QuerySchema>[] | undefined,
     ) => z.input<QuerySchema>
   }): ((
-    params: Util_FlatObject<ClientQueryArgs<Url, QuerySchema>>,
+    params: Util_FlatObject<QueryArgs<Url, QuerySchema>>,
   ) => UseSuspenseInfiniteQueryOptions<
     PageResult,
     Error,
@@ -101,8 +200,53 @@ export interface ClientInstance {
     z.output<QuerySchema>
   >) &
     QueryHelpers<Url, QuerySchema, PageResult, true> &
-    ClientEndpointHelper<Method, Url, undefined, Response, QuerySchema>
+    EndpointHelper<Method, Url, undefined, Response, QuerySchema>
 
+  // POST infiniteQuery methods (for search endpoints)
+  infiniteQuery<
+    Method extends 'POST' = 'POST',
+    Url extends string = string,
+    QuerySchema extends ZodObject = ZodObject,
+    RequestSchema extends ZodType = ZodType,
+    Response extends ZodType = ZodType,
+    PageResult = z.output<Response>,
+    Result = InfiniteData<PageResult>,
+  >(config: {
+    method: Method
+    url: Url
+    querySchema: QuerySchema
+    requestSchema: RequestSchema
+    responseSchema: Response
+    processResponse?: (data: z.output<Response>) => PageResult
+    getNextPageParam: (
+      lastPage: PageResult,
+      allPages: PageResult[],
+      lastPageParam: z.infer<QuerySchema> | undefined,
+      allPageParams: z.infer<QuerySchema>[] | undefined,
+    ) => z.input<QuerySchema> | undefined
+    getPreviousPageParam?: (
+      firstPage: PageResult,
+      allPages: PageResult[],
+      lastPageParam: z.infer<QuerySchema> | undefined,
+      allPageParams: z.infer<QuerySchema>[] | undefined,
+    ) => z.input<QuerySchema>
+  }): ((
+    params: Util_FlatObject<QueryArgs<Url, QuerySchema, RequestSchema>>,
+  ) => UseSuspenseInfiniteQueryOptions<
+    PageResult,
+    Error,
+    Result,
+    DataTag<Split<Url, '/'>, PageResult, Error>,
+    z.output<QuerySchema>
+  >) &
+    QueryHelpers<Url, QuerySchema, PageResult, true, RequestSchema> &
+    EndpointHelper<Method, Url, RequestSchema, Response, QuerySchema>
+
+  // ============================================================================
+  // MUTATION METHODS (POST, PUT, PATCH)
+  // ============================================================================
+
+  // With useKey, requestSchema, and querySchema
   mutation<
     Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
     Url extends string = string,
@@ -125,17 +269,13 @@ export interface ClientInstance {
     onSuccess?: (
       queryClient: QueryClient,
       data: NoInfer<Result>,
-      variables: Util_FlatObject<
-        ClientMutationArgs<Url, RequestSchema, QuerySchema>
-      >,
+      variables: Util_FlatObject<MutationArgs<Url, RequestSchema, QuerySchema>>,
       context: Context,
     ) => void | Promise<void>
     onError?: (
       queryClient: QueryClient,
       error: Error,
-      variables: Util_FlatObject<
-        ClientMutationArgs<Url, RequestSchema, QuerySchema>
-      >,
+      variables: Util_FlatObject<MutationArgs<Url, RequestSchema, QuerySchema>>,
       context: Context,
     ) => void | Promise<void>
   }): ((
@@ -143,11 +283,12 @@ export interface ClientInstance {
   ) => UseMutationResult<
     Result,
     Error,
-    ClientMutationArgs<Url, RequestSchema, QuerySchema>
+    MutationArgs<Url, RequestSchema, QuerySchema>
   >) &
     MutationHelpers<Url, Result> &
-    ClientEndpointHelper<Method, Url, RequestSchema, Response, QuerySchema>
+    EndpointHelper<Method, Url, RequestSchema, Response, QuerySchema>
 
+  // Without useKey, with requestSchema and querySchema
   mutation<
     Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
     Url extends string = string,
@@ -168,26 +309,24 @@ export interface ClientInstance {
     onSuccess?: (
       queryClient: QueryClient,
       data: NoInfer<Result>,
-      variables: Util_FlatObject<
-        ClientMutationArgs<Url, RequestSchema, QuerySchema>
-      >,
+      variables: Util_FlatObject<MutationArgs<Url, RequestSchema, QuerySchema>>,
       context: Context,
     ) => void | Promise<void>
     onError?: (
       queryClient: QueryClient,
       error: Error,
-      variables: Util_FlatObject<
-        ClientMutationArgs<Url, RequestSchema, QuerySchema>
-      >,
+      variables: Util_FlatObject<MutationArgs<Url, RequestSchema, QuerySchema>>,
       context: Context,
     ) => void | Promise<void>
   }): (() => UseMutationResult<
     Result,
     Error,
-    ClientMutationArgs<Url, RequestSchema, QuerySchema>
+    MutationArgs<Url, RequestSchema, QuerySchema>
   >) &
-    ClientEndpointHelper<Method, Url, RequestSchema, Response, QuerySchema>
+    MutationHelpers<Url, Result> &
+    EndpointHelper<Method, Url, RequestSchema, Response, QuerySchema>
 
+  // Without useKey, with requestSchema only
   mutation<
     Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
     Url extends string = string,
@@ -206,27 +345,24 @@ export interface ClientInstance {
     onSuccess?: (
       queryClient: QueryClient,
       data: NoInfer<Result>,
-      variables: Util_FlatObject<
-        ClientMutationArgs<Url, RequestSchema, undefined>
-      >,
+      variables: Util_FlatObject<MutationArgs<Url, RequestSchema, undefined>>,
       context: Context,
     ) => void | Promise<void>
     onError?: (
       queryClient: QueryClient,
       error: Error,
-      variables: Util_FlatObject<
-        ClientMutationArgs<Url, RequestSchema, undefined>
-      >,
+      variables: Util_FlatObject<MutationArgs<Url, RequestSchema, undefined>>,
       context: Context,
     ) => void | Promise<void>
   }): (() => UseMutationResult<
     Result,
     Error,
-    ClientMutationArgs<Url, RequestSchema, undefined>
+    MutationArgs<Url, RequestSchema, undefined>
   >) &
     MutationHelpers<Url, Result> &
-    ClientEndpointHelper<Method, Url, RequestSchema, Response>
+    EndpointHelper<Method, Url, RequestSchema, Response>
 
+  // With useKey and requestSchema only
   mutation<
     Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
     Url extends string = string,
@@ -247,17 +383,13 @@ export interface ClientInstance {
     onSuccess?: (
       queryClient: QueryClient,
       data: NoInfer<Result>,
-      variables: Util_FlatObject<
-        ClientMutationArgs<Url, RequestSchema, undefined>
-      >,
+      variables: Util_FlatObject<MutationArgs<Url, RequestSchema, undefined>>,
       context: Context,
     ) => void | Promise<void>
     onError?: (
       queryClient: QueryClient,
       error: Error,
-      variables: Util_FlatObject<
-        ClientMutationArgs<Url, RequestSchema, undefined>
-      >,
+      variables: Util_FlatObject<MutationArgs<Url, RequestSchema, undefined>>,
       context: Context,
     ) => void | Promise<void>
   }): ((
@@ -265,11 +397,16 @@ export interface ClientInstance {
   ) => UseMutationResult<
     Result,
     Error,
-    ClientMutationArgs<Url, RequestSchema, undefined>
+    MutationArgs<Url, RequestSchema, undefined>
   >) &
     MutationHelpers<Url, Result> &
-    ClientEndpointHelper<Method, Url, RequestSchema, Response>
+    EndpointHelper<Method, Url, RequestSchema, Response>
+
+  // ============================================================================
+  // DELETE MUTATION METHODS
+  // ============================================================================
 
+  // DELETE with useKey and querySchema
   mutation<
     Method extends 'DELETE' = 'DELETE',
     Url extends string = string,
@@ -290,17 +427,13 @@ export interface ClientInstance {
     onSuccess?: (
       queryClient: QueryClient,
       data: NoInfer<Result>,
-      variables: Util_FlatObject<
-        ClientMutationArgs<Url, undefined, QuerySchema>
-      >,
+      variables: Util_FlatObject<MutationArgs<Url, undefined, QuerySchema>>,
       context: Context,
     ) => void | Promise<void>
     onError?: (
       queryClient: QueryClient,
       error: Error,
-      variables: Util_FlatObject<
-        ClientMutationArgs<Url, undefined, QuerySchema>
-      >,
+      variables: Util_FlatObject<MutationArgs<Url, undefined, QuerySchema>>,
       context: Context,
     ) => void | Promise<void>
   }): ((
@@ -308,11 +441,12 @@ export interface ClientInstance {
   ) => UseMutationResult<
     Result,
     Error,
-    ClientMutationArgs<Url, undefined, QuerySchema>
+    MutationArgs<Url, undefined, QuerySchema>
   >) &
     MutationHelpers<Url, Result> &
-    ClientEndpointHelper<Method, Url, undefined, Response, QuerySchema>
+    EndpointHelper<Method, Url, undefined, Response, QuerySchema>
 
+  // DELETE without useKey, with querySchema
   mutation<
     Method extends 'DELETE' = 'DELETE',
     Url extends string = string,
@@ -331,26 +465,24 @@ export interface ClientInstance {
     onSuccess?: (
       queryClient: QueryClient,
       data: NoInfer<Result>,
-      variables: Util_FlatObject<
-        ClientMutationArgs<Url, undefined, QuerySchema>
-      >,
+      variables: Util_FlatObject<MutationArgs<Url, undefined, QuerySchema>>,
       context: Context,
     ) => void | Promise<void>
     onError?: (
       queryClient: QueryClient,
       error: Error,
-      variables: Util_FlatObject<
-        ClientMutationArgs<Url, undefined, QuerySchema>
-      >,
+      variables: Util_FlatObject<MutationArgs<Url, undefined, QuerySchema>>,
       context: Context,
     ) => void | Promise<void>
   }): (() => UseMutationResult<
     Result,
     Error,
-    ClientMutationArgs<Url, undefined, QuerySchema>
+    MutationArgs<Url, undefined, QuerySchema>
   >) &
-    ClientEndpointHelper<Method, Url, undefined, Response, QuerySchema>
+    MutationHelpers<Url, Result> &
+    EndpointHelper<Method, Url, undefined, Response, QuerySchema>
 
+  // DELETE with useKey only (no schemas)
   mutation<
     Method extends 'DELETE' = 'DELETE',
     Url extends string = string,
@@ -369,13 +501,13 @@ export interface ClientInstance {
     onSuccess?: (
       queryClient: QueryClient,
       data: NoInfer<Result>,
-      variables: Util_FlatObject<ClientMutationArgs<Url, undefined, undefined>>,
+      variables: Util_FlatObject<MutationArgs<Url, undefined, undefined>>,
       context: Context,
     ) => void | Promise<void>
     onError?: (
       queryClient: QueryClient,
       error: Error,
-      variables: Util_FlatObject<ClientMutationArgs<Url, undefined, undefined>>,
+      variables: Util_FlatObject<MutationArgs<Url, undefined, undefined>>,
       context: Context,
     ) => void | Promise<void>
   }): ((
@@ -383,11 +515,12 @@ export interface ClientInstance {
   ) => UseMutationResult<
     Result,
     Error,
-    ClientMutationArgs<Url, undefined, undefined>
+    MutationArgs<Url, undefined, undefined>
   >) &
     MutationHelpers<Url, Result> &
-    ClientEndpointHelper<Method, Url, undefined, Response>
+    EndpointHelper<Method, Url, undefined, Response>
 
+  // DELETE without useKey (no schemas)
   mutation<
     Method extends 'DELETE' = 'DELETE',
     Url extends string = string,
@@ -404,21 +537,26 @@ export interface ClientInstance {
     onSuccess?: (
       queryClient: QueryClient,
       data: NoInfer<Result>,
-      variables: Util_FlatObject<ClientMutationArgs<Url, undefined, undefined>>,
+      variables: Util_FlatObject<MutationArgs<Url, undefined, undefined>>,
       context: Context,
     ) => void | Promise<void>
     onError?: (
       queryClient: QueryClient,
       error: Error,
-      variables: Util_FlatObject<ClientMutationArgs<Url, undefined, undefined>>,
+      variables: Util_FlatObject<MutationArgs<Url, undefined, undefined>>,
       context: Context,
     ) => void | Promise<void>
   }): (() => UseMutationResult<
     Result,
     Error,
-    ClientMutationArgs<Url, undefined, undefined>
+    MutationArgs<Url, undefined, undefined>
   >) &
-    ClientEndpointHelper<Method, Url, undefined, Response>
+    MutationHelpers<Url, Result> &
+    EndpointHelper<Method, Url, undefined, Response>
+
+  // ============================================================================
+  // FROM ENDPOINT METHODS
+  // ============================================================================
 
   queryFromEndpoint<
     Method extends 'GET' | 'HEAD' | 'OPTIONS' = 'GET',
@@ -427,14 +565,14 @@ export interface ClientInstance {
     Response extends ZodType = ZodType,
     Result = z.output<Response>,
   >(
-    endpoint: any & {
+    endpoint: {
       config: BaseEndpointConfig<Method, Url, QuerySchema, Response>
     },
     options?: {
       processResponse?: (data: z.output<Response>) => Result
     },
   ): (
-    params: UrlHasParams<Url> extends true ? { urlParams: UrlParams<Url> } : {},
+    params: Util_FlatObject<QueryArgs<Url, QuerySchema>>,
   ) => UseSuspenseQueryOptions<
     Result,
     Error,
@@ -449,14 +587,14 @@ export interface ClientInstance {
     Response extends ZodType = ZodType,
     Result = z.output<Response>,
   >(
-    endpoint: any & {
+    endpoint: {
       config: BaseEndpointConfig<Method, Url, undefined, Response>
     },
     options?: {
       processResponse?: (data: z.output<Response>) => Result
     },
   ): ((
-    params: UrlHasParams<Url> extends true ? { urlParams: UrlParams<Url> } : {},
+    params: Util_FlatObject<QueryArgs<Url, undefined>>,
   ) => UseSuspenseQueryOptions<
     Result,
     Error,
@@ -473,7 +611,7 @@ export interface ClientInstance {
     PageResult = z.output<Response>,
     Result = InfiniteData<PageResult>,
   >(
-    endpoint: any & {
+    endpoint: {
       config: BaseEndpointConfig<Method, Url, QuerySchema, Response>
     },
     options: {
@@ -492,7 +630,7 @@ export interface ClientInstance {
       ) => z.input<QuerySchema>
     },
   ): ((
-    params: UrlHasParams<Url> extends true ? { urlParams: UrlParams<Url> } : {},
+    params: Util_FlatObject<QueryArgs<Url, QuerySchema>>,
   ) => UseSuspenseInfiniteQueryOptions<
     PageResult,
     Error,
@@ -502,6 +640,10 @@ export interface ClientInstance {
   >) &
     QueryHelpers<Url, QuerySchema, PageResult, true>
 
+  // ============================================================================
+  // MUTATION FROM ENDPOINT METHODS (POST, PUT, PATCH)
+  // ============================================================================
+
   mutationFromEndpoint<
     Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
     Url extends string = string,
@@ -513,7 +655,7 @@ export interface ClientInstance {
     Context = unknown,
     UseKey extends true = true,
   >(
-    endpoint: any & {
+    endpoint: {
       config: BaseEndpointConfig<
         Method,
         Url,
@@ -530,7 +672,7 @@ export interface ClientInstance {
         queryClient: QueryClient,
         data: NoInfer<Result>,
         variables: Util_FlatObject<
-          ClientMutationArgs<Url, RequestSchema, QuerySchema>
+          MutationArgs<Url, RequestSchema, QuerySchema>
         >,
         context: Context,
       ) => void | Promise<void>
@@ -538,20 +680,20 @@ export interface ClientInstance {
         queryClient: QueryClient,
         error: Error,
         variables: Util_FlatObject<
-          ClientMutationArgs<Url, RequestSchema, QuerySchema>
+          MutationArgs<Url, RequestSchema, QuerySchema>
         >,
         context: Context,
       ) => void | Promise<void>
     },
   ): ((
-    params: UrlHasParams<Url> extends true ? UrlParams<Url> : {},
+    params: Util_FlatObject<MutationArgs<Url, RequestSchema, QuerySchema>>,
   ) => UseMutationResult<
     Result,
     Error,
-    ClientMutationArgs<Url, RequestSchema, QuerySchema>
+    MutationArgs<Url, RequestSchema, QuerySchema>
   >) &
     MutationHelpers<Url, Result> &
-    ClientEndpointHelper<Method, Url, RequestSchema, Response, QuerySchema>
+    EndpointHelper<Method, Url, RequestSchema, Response, QuerySchema>
 
   mutationFromEndpoint<
     Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
@@ -563,7 +705,7 @@ export interface ClientInstance {
     Context = unknown,
     UseKey extends true = true,
   >(
-    endpoint: any & {
+    endpoint: {
       config: BaseEndpointConfig<
         Method,
         Url,
@@ -579,29 +721,25 @@ export interface ClientInstance {
       onSuccess?: (
         queryClient: QueryClient,
         data: NoInfer<Result>,
-        variables: Util_FlatObject<
-          ClientMutationArgs<Url, RequestSchema, undefined>
-        >,
+        variables: Util_FlatObject<MutationArgs<Url, RequestSchema, undefined>>,
         context: Context,
       ) => void | Promise<void>
       onError?: (
         queryClient: QueryClient,
         error: Error,
-        variables: Util_FlatObject<
-          ClientMutationArgs<Url, RequestSchema, undefined>
-        >,
+        variables: Util_FlatObject<MutationArgs<Url, RequestSchema, undefined>>,
         context: Context,
       ) => void | Promise<void>
     },
   ): ((
-    params: UrlHasParams<Url> extends true ? UrlParams<Url> : {},
+    params: Util_FlatObject<MutationArgs<Url, RequestSchema, undefined>>,
   ) => UseMutationResult<
     Result,
     Error,
-    ClientMutationArgs<Url, RequestSchema, undefined>
+    MutationArgs<Url, RequestSchema, undefined>
   >) &
     MutationHelpers<Url, Result> &
-    ClientEndpointHelper<Method, Url, RequestSchema, Response, undefined>
+    EndpointHelper<Method, Url, RequestSchema, Response, undefined>
 
   mutationFromEndpoint<
     Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
@@ -613,7 +751,7 @@ export interface ClientInstance {
     Result = unknown,
     Context = unknown,
   >(
-    endpoint: any & {
+    endpoint: {
       config: BaseEndpointConfig<
         Method,
         Url,
@@ -629,7 +767,7 @@ export interface ClientInstance {
         queryClient: QueryClient,
         data: NoInfer<Result>,
         variables: Util_FlatObject<
-          ClientMutationArgs<Url, RequestSchema, QuerySchema>
+          MutationArgs<Url, RequestSchema, QuerySchema>
         >,
         context: Context,
       ) => void | Promise<void>
@@ -637,17 +775,19 @@ export interface ClientInstance {
         queryClient: QueryClient,
         error: Error,
         variables: Util_FlatObject<
-          ClientMutationArgs<Url, RequestSchema, QuerySchema>
+          MutationArgs<Url, RequestSchema, QuerySchema>
         >,
         context: Context,
       ) => void | Promise<void>
     },
-  ): (() => UseMutationResult<
+  ): ((
+    params: Util_FlatObject<MutationArgs<Url, RequestSchema, QuerySchema>>,
+  ) => UseMutationResult<
     Result,
     Error,
-    ClientMutationArgs<Url, RequestSchema, QuerySchema>
+    MutationArgs<Url, RequestSchema, QuerySchema>
   >) &
-    ClientEndpointHelper<Method, Url, RequestSchema, Response, QuerySchema>
+    EndpointHelper<Method, Url, RequestSchema, Response, QuerySchema>
 
   mutationFromEndpoint<
     Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
@@ -658,7 +798,7 @@ export interface ClientInstance {
     Result = unknown,
     Context = unknown,
   >(
-    endpoint: any & {
+    endpoint: {
       config: BaseEndpointConfig<
         Method,
         Url,
@@ -673,26 +813,28 @@ export interface ClientInstance {
       onSuccess?: (
         queryClient: QueryClient,
         data: NoInfer<Result>,
-        variables: Util_FlatObject<
-          ClientMutationArgs<Url, RequestSchema, undefined>
-        >,
+        variables: Util_FlatObject<MutationArgs<Url, RequestSchema, undefined>>,
         context: Context,
       ) => void | Promise<void>
       onError?: (
         queryClient: QueryClient,
         error: Error,
-        variables: Util_FlatObject<
-          ClientMutationArgs<Url, RequestSchema, undefined>
-        >,
+        variables: Util_FlatObject<MutationArgs<Url, RequestSchema, undefined>>,
         context: Context,
       ) => void | Promise<void>
     },
-  ): (() => UseMutationResult<
+  ): ((
+    params: Util_FlatObject<MutationArgs<Url, RequestSchema, undefined>>,
+  ) => UseMutationResult<
     Result,
     Error,
-    ClientMutationArgs<Url, RequestSchema, undefined>
+    MutationArgs<Url, RequestSchema, undefined>
   >) &
-    ClientEndpointHelper<Method, Url, RequestSchema, Response, undefined>
+    EndpointHelper<Method, Url, RequestSchema, Response, undefined>
+
+  // ============================================================================
+  // DELETE MUTATION FROM ENDPOINT METHODS
+  // ============================================================================
 
   mutationFromEndpoint<
     Method extends 'DELETE' = 'DELETE',
@@ -704,7 +846,7 @@ export interface ClientInstance {
     Context = unknown,
     UseKey extends true = true,
   >(
-    endpoint: any & {
+    endpoint: {
       config: BaseEndpointConfig<Method, Url, QuerySchema, Response>
     },
     mutationOptions: {
@@ -714,29 +856,25 @@ export interface ClientInstance {
       onSuccess?: (
         queryClient: QueryClient,
         data: NoInfer<Result>,
-        variables: Util_FlatObject<
-          ClientMutationArgs<Url, undefined, QuerySchema>
-        >,
+        variables: Util_FlatObject<MutationArgs<Url, undefined, QuerySchema>>,
         context: Context,
       ) => void | Promise<void>
       onError?: (
         queryClient: QueryClient,
         error: Error,
-        variables: Util_FlatObject<
-          ClientMutationArgs<Url, undefined, QuerySchema>
-        >,
+        variables: Util_FlatObject<MutationArgs<Url, undefined, QuerySchema>>,
         context: Context,
       ) => void | Promise<void>
     },
   ): ((
-    params: UrlHasParams<Url> extends true ? UrlParams<Url> : {},
+    params: Util_FlatObject<MutationArgs<Url, undefined, QuerySchema>>,
   ) => UseMutationResult<
     Result,
     Error,
-    ClientMutationArgs<Url, undefined, QuerySchema>
+    MutationArgs<Url, undefined, QuerySchema>
   >) &
     MutationHelpers<Url, Result> &
-    ClientEndpointHelper<Method, Url, undefined, Response, QuerySchema>
+    EndpointHelper<Method, Url, undefined, Response, QuerySchema>
 
   mutationFromEndpoint<
     Method extends 'DELETE' = 'DELETE',
@@ -747,7 +885,7 @@ export interface ClientInstance {
     Context = unknown,
     UseKey extends true = true,
   >(
-    endpoint: any & {
+    endpoint: {
       config: BaseEndpointConfig<Method, Url, undefined, Response>
     },
     mutationOptions: {
@@ -757,29 +895,25 @@ export interface ClientInstance {
       onSuccess?: (
         queryClient: QueryClient,
         data: NoInfer<Result>,
-        variables: Util_FlatObject<
-          ClientMutationArgs<Url, undefined, undefined>
-        >,
+        variables: Util_FlatObject<MutationArgs<Url, undefined, undefined>>,
         context: Context,
       ) => void | Promise<void>
       onError?: (
         queryClient: QueryClient,
         error: Error,
-        variables: Util_FlatObject<
-          ClientMutationArgs<Url, undefined, undefined>
-        >,
+        variables: Util_FlatObject<MutationArgs<Url, undefined, undefined>>,
         context: Context,
       ) => void | Promise<void>
     },
   ): ((
-    params: UrlHasParams<Url> extends true ? UrlParams<Url> : {},
+    params: Util_FlatObject<MutationArgs<Url, undefined, undefined>>,
   ) => UseMutationResult<
     Result,
     Error,
-    ClientMutationArgs<Url, undefined, undefined>
+    MutationArgs<Url, undefined, undefined>
   >) &
     MutationHelpers<Url, Result> &
-    ClientEndpointHelper<Method, Url, undefined, Response, undefined>
+    EndpointHelper<Method, Url, undefined, Response, undefined>
 
   mutationFromEndpoint<
     Method extends 'DELETE' = 'DELETE',
@@ -790,7 +924,7 @@ export interface ClientInstance {
     Result = unknown,
     Context = unknown,
   >(
-    endpoint: any & {
+    endpoint: {
       config: BaseEndpointConfig<Method, Url, QuerySchema, Response>
     },
     mutationOptions: {
@@ -799,26 +933,24 @@ export interface ClientInstance {
       onSuccess?: (
         queryClient: QueryClient,
         data: NoInfer<Result>,
-        variables: Util_FlatObject<
-          ClientMutationArgs<Url, undefined, QuerySchema>
-        >,
+        variables: Util_FlatObject<MutationArgs<Url, undefined, QuerySchema>>,
         context: Context,
       ) => void | Promise<void>
       onError?: (
         queryClient: QueryClient,
         error: Error,
-        variables: Util_FlatObject<
-          ClientMutationArgs<Url, undefined, QuerySchema>
-        >,
+        variables: Util_FlatObject<MutationArgs<Url, undefined, QuerySchema>>,
         context: Context,
       ) => void | Promise<void>
     },
-  ): (() => UseMutationResult<
+  ): ((
+    params: Util_FlatObject<MutationArgs<Url, undefined, QuerySchema>>,
+  ) => UseMutationResult<
     Result,
     Error,
-    ClientMutationArgs<Url, undefined, QuerySchema>
+    MutationArgs<Url, undefined, QuerySchema>
   >) &
-    ClientEndpointHelper<Method, Url, undefined, Response, QuerySchema>
+    EndpointHelper<Method, Url, undefined, Response, QuerySchema>
 
   mutationFromEndpoint<
     Method extends 'DELETE' = 'DELETE',
@@ -828,7 +960,7 @@ export interface ClientInstance {
     Result = unknown,
     Context = unknown,
   >(
-    endpoint: any & {
+    endpoint: {
       config: BaseEndpointConfig<Method, Url, undefined, Response>
     },
     mutationOptions: {
@@ -837,26 +969,178 @@ export interface ClientInstance {
       onSuccess?: (
         queryClient: QueryClient,
         data: NoInfer<Result>,
-        variables: Util_FlatObject<
-          ClientMutationArgs<Url, undefined, undefined>
-        >,
+        variables: Util_FlatObject<MutationArgs<Url, undefined, undefined>>,
         context: Context,
       ) => void | Promise<void>
       onError?: (
         queryClient: QueryClient,
         error: Error,
-        variables: Util_FlatObject<
-          ClientMutationArgs<Url, undefined, undefined>
-        >,
+        variables: Util_FlatObject<MutationArgs<Url, undefined, undefined>>,
         context: Context,
       ) => void | Promise<void>
     },
   ): ((
+    params: Util_FlatObject<MutationArgs<Url, undefined, undefined>>,
+  ) => UseMutationResult<
+    Result,
+    Error,
+    MutationArgs<Url, undefined, undefined>
+  >) &
+    EndpointHelper<Method, Url, undefined, Response, undefined>
+
+  // ============================================================================
+  // MULTIPART MUTATION METHODS
+  // ============================================================================
+
+  multipartMutation<
+    Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
+    Url extends string = string,
+    RequestSchema extends ZodType = ZodType,
+    QuerySchema extends ZodObject = ZodObject,
+    Response extends ZodType = ZodType,
+    ReqResult = z.output<Response>,
+    Result = unknown,
+    Context = unknown,
+    UseKey extends true = true,
+  >(config: {
+    method: Method
+    url: Url
+    useKey: UseKey
+    requestSchema: RequestSchema
+    querySchema: QuerySchema
+    responseSchema: Response
+    processResponse: ProcessResponseFunction<Result, ReqResult>
+    useContext?: () => Context
+    onSuccess?: (
+      queryClient: QueryClient,
+      data: NoInfer<Result>,
+      variables: Util_FlatObject<MutationArgs<Url, RequestSchema, QuerySchema>>,
+      context: Context,
+    ) => void | Promise<void>
+    onError?: (
+      queryClient: QueryClient,
+      error: Error,
+      variables: Util_FlatObject<MutationArgs<Url, RequestSchema, QuerySchema>>,
+      context: Context,
+    ) => void | Promise<void>
+  }): ((
+    params: UrlHasParams<Url> extends true ? { urlParams: UrlParams<Url> } : {},
+  ) => UseMutationResult<
+    Result,
+    Error,
+    MutationArgs<Url, RequestSchema, QuerySchema>
+  >) &
+    MutationHelpers<Url, Result> &
+    EndpointHelper<Method, Url, RequestSchema, Response, QuerySchema>
+
+  multipartMutation<
+    Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
+    Url extends string = string,
+    RequestSchema extends ZodType = ZodType,
+    QuerySchema extends ZodObject = ZodObject,
+    Response extends ZodType = ZodType,
+    ReqResult = z.output<Response>,
+    Result = unknown,
+    Context = unknown,
+  >(config: {
+    method: Method
+    url: Url
+    requestSchema: RequestSchema
+    querySchema: QuerySchema
+    responseSchema: Response
+    processResponse: ProcessResponseFunction<Result, ReqResult>
+    useContext?: () => Context
+    onSuccess?: (
+      queryClient: QueryClient,
+      data: NoInfer<Result>,
+      variables: Util_FlatObject<MutationArgs<Url, RequestSchema, QuerySchema>>,
+      context: Context,
+    ) => void | Promise<void>
+    onError?: (
+      queryClient: QueryClient,
+      error: Error,
+      variables: Util_FlatObject<MutationArgs<Url, RequestSchema, QuerySchema>>,
+      context: Context,
+    ) => void | Promise<void>
+  }): (() => UseMutationResult<
+    Result,
+    Error,
+    MutationArgs<Url, RequestSchema, QuerySchema>
+  >) &
+    MutationHelpers<Url, Result> &
+    EndpointHelper<Method, Url, RequestSchema, Response, QuerySchema>
+
+  multipartMutation<
+    Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
+    Url extends string = string,
+    RequestSchema extends ZodType = ZodType,
+    Response extends ZodType = ZodType,
+    ReqResult = z.output<Response>,
+    Result = unknown,
+    Context = unknown,
+  >(config: {
+    method: Method
+    url: Url
+    requestSchema: RequestSchema
+    responseSchema: Response
+    processResponse: ProcessResponseFunction<Result, ReqResult>
+    useContext?: () => Context
+    onSuccess?: (
+      queryClient: QueryClient,
+      data: NoInfer<Result>,
+      variables: Util_FlatObject<MutationArgs<Url, RequestSchema, undefined>>,
+      context: Context,
+    ) => void | Promise<void>
+    onError?: (
+      queryClient: QueryClient,
+      error: Error,
+      variables: Util_FlatObject<MutationArgs<Url, RequestSchema, undefined>>,
+      context: Context,
+    ) => void | Promise<void>
+  }): (() => UseMutationResult<
+    Result,
+    Error,
+    MutationArgs<Url, RequestSchema, undefined>
+  >) &
+    MutationHelpers<Url, Result> &
+    EndpointHelper<Method, Url, RequestSchema, Response>
+
+  multipartMutation<
+    Method extends 'POST' | 'PUT' | 'PATCH' = 'POST' | 'PUT' | 'PATCH',
+    Url extends string = string,
+    RequestSchema extends ZodType = ZodType,
+    Response extends ZodType = ZodType,
+    ReqResult = z.output<Response>,
+    Result = unknown,
+    Context = unknown,
+    UseKey extends true = true,
+  >(config: {
+    method: Method
+    url: Url
+    useKey: UseKey
+    requestSchema: RequestSchema
+    responseSchema: Response
+    processResponse: ProcessResponseFunction<Result, ReqResult>
+    useContext?: () => Context
+    onSuccess?: (
+      queryClient: QueryClient,
+      data: NoInfer<Result>,
+      variables: Util_FlatObject<MutationArgs<Url, RequestSchema, undefined>>,
+      context: Context,
+    ) => void | Promise<void>
+    onError?: (
+      queryClient: QueryClient,
+      error: Error,
+      variables: Util_FlatObject<MutationArgs<Url, RequestSchema, undefined>>,
+      context: Context,
+    ) => void | Promise<void>
+  }): ((
     params: UrlHasParams<Url> extends true ? UrlParams<Url> : {},
   ) => UseMutationResult<
     Result,
     Error,
-    ClientMutationArgs<Url, undefined, undefined>
+    MutationArgs<Url, RequestSchema, undefined>
   >) &
-    ClientEndpointHelper<Method, Url, undefined, Response, undefined>
+    MutationHelpers<Url, Result> &
+    EndpointHelper<Method, Url, RequestSchema, Response>
 }