@qualisero/openapi-endpoint 0.13.2 → 0.14.0

package/dist/types.d.ts

@@ -1,52 +1,51 @@
 import { type AxiosInstance, type AxiosError, type AxiosRequestConfig, type AxiosResponse } from 'axios';
 import type { MutationObserverOptions, QueryKey, QueryObserverOptions } from '@tanstack/query-core';
 import type { ComputedRef, Ref } from 'vue';
-import type { EndpointQueryReturn } from './openapi-query';
-import type { EndpointMutationReturn } from './openapi-mutation';
 /**
  * Extended Axios request configuration that allows custom properties.
  */
 export type AxiosRequestConfigExtended = AxiosRequestConfig & Record<string, unknown>;
+export declare enum HttpMethod {
+    GET = "GET",
+    POST = "POST",
+    PUT = "PUT",
+    PATCH = "PATCH",
+    DELETE = "DELETE",
+    HEAD = "HEAD",
+    OPTIONS = "OPTIONS",
+    TRACE = "TRACE"
+}
+export declare const QUERY_METHODS: readonly [HttpMethod.GET, HttpMethod.HEAD, HttpMethod.OPTIONS];
+export declare const MUTATION_METHODS: readonly [HttpMethod.POST, HttpMethod.PUT, HttpMethod.PATCH, HttpMethod.DELETE];
+export declare function isQueryMethod(method: HttpMethod): boolean;
+export declare function isMutationMethod(method: HttpMethod): boolean;
 /**
- * Error type shown when an operation requires path parameters but they weren't provided.
- *
- * @internal
+ * A value that can be reactive (ref, computed, getter function) or direct.
  */
-export type RequiresPathParameters<Op extends string> = {
-    readonly __error: `Operation '${Op}' requires path parameters as the second argument`;
-    readonly __fix: 'Provide path parameters as the second argument';
-    readonly __see: 'Check the operation path definition (e.g., /pets/{petId}) or JSDoc';
-};
+export type ReactiveOr<T> = T | Ref<T> | ComputedRef<T> | (() => T);
 /**
- * Validates that path parameters have no excess properties.
+ * Constrains a getter function `F` so that its return type has no excess
+ * properties beyond the expected type `T`.
  *
- * @internal
- */
-export type HasExcessPathParams<Provided extends Record<string, unknown>, Expected extends Record<string, unknown>> = Exclude<keyof Provided, keyof Expected> extends never ? true : false;
-/**
- * Type representing an operation that does NOT require path parameters.
- * Used in function signatures to restrict which operations can be called without path params.
+ * Evaluates to `F` when the return type is valid, or `never` when the
+ * function returns unexpected extra properties — causing a type error at the
+ * call site.
  *
- * @internal
- */
-export type NoPathParams<Ops extends Operations<Ops>, Op extends keyof Ops> = Op & (ApiPathParams<Ops, Op> extends Record<string, never> ? Op : RequiresPathParameters<Op & string>);
-/**
- * Type representing an operation that DOES require path parameters.
- * Used in function signatures to restrict which operations must be called with path params.
+ * @example
+ * ```ts
+ * type PP = { petId: string | undefined }
+ * type F1 = () => { petId: string }         // NoExcessReturn<PP, F1> → F1   ✅
+ * type F2 = () => { petId: string; bad: 'x' } // NoExcessReturn<PP, F2> → never ❌
+ * ```
  *
- * @internal
+ * @internal Used in generated `api-client.ts` to enforce strict path params on getter fns.
  */
-export type WithPathParams<Ops extends Operations<Ops>, Op extends keyof Ops> = Op & (ApiPathParams<Ops, Op> extends Record<string, never> ? RequiresPathParameters<Op & string> : Op);
-/** @internal */
-export type { EndpointQueryReturn, EndpointMutationReturn };
+export type NoExcessReturn<T extends Record<string, unknown>, F extends () => T> = Exclude<keyof ReturnType<F>, keyof T> extends never ? F : never;
 /**
- * Interface defining the minimal QueryClient methods required by this library.
- *
- * This interface ensures compatibility with different versions of @tanstack/vue-query
- * by only requiring the specific methods that are actually used internally.
- *
- * @group Types
+ * Reactive value that excludes function getters.
+ * @internal Used for internal type inference.
  */
+export type ReactiveValue<T> = T | Ref<T> | ComputedRef<T>;
 export interface QueryClientLike {
     cancelQueries(filters: {
         queryKey: unknown[];
@@ -61,197 +60,219 @@ export interface QueryClientLike {
         }) => boolean;
     }): Promise<void>;
 }
-/** @internal */
-export type Operations<Ops> = object & {
-    [K in keyof Ops]: OperationInfo;
-};
 /**
- * Configuration object for initializing the OpenAPI client.
- *
- * @template Ops - The operations type, typically generated from your OpenAPI specification
- *
- * @example
- * ```typescript
- * import { useOpenApi } from '@qualisero/openapi-endpoint'
- * import { openApiOperations, type OpenApiOperations } from './generated/api-operations'
- * import axios from 'axios'
+ * Runtime configuration for a single endpoint. Passed directly to
+ * `useEndpointQuery` / `useEndpointMutation` by generated code.
  *
- * const config: OpenApiConfig<OpenApiOperations> = {
- *   operations: openApiOperations,
- *   axios: axios.create({ baseURL: 'https://api.example.com' }),
- *   queryClient: customQueryClient // optional
- * }
- * ```
+ * Created by the generated `createApiClient` factory and embedded per-operation
+ * in the generated `api-client.ts`.
  */
-export interface OpenApiConfig<Ops extends Operations<Ops>> {
-    operations: Ops;
+export interface EndpointConfig {
     axios: AxiosInstance;
-    queryClient?: QueryClientLike;
-}
-/** @internal */
-export declare enum HttpMethod {
-    GET = "GET",
-    POST = "POST",
-    PUT = "PUT",
-    PATCH = "PATCH",
-    DELETE = "DELETE",
-    HEAD = "HEAD",
-    OPTIONS = "OPTIONS",
-    TRACE = "TRACE"
+    queryClient: QueryClientLike;
+    /** The OpenAPI path template, e.g. `/pets/{petId}` */
+    path: string;
+    method: HttpMethod;
+    /**
+     * Pre-computed list path for cache invalidation after mutations.
+     * e.g. for `updatePet` at `/pets/{petId}`, this would be `/pets`.
+     * `null` means no list invalidation.
+     * Generated at code-gen time by the CLI.
+     */
+    listPath?: string | null;
+    /**
+     * Registry of all operations' paths, used to resolve `invalidateOperations`
+     * option at mutation time. Generated and embedded by the CLI.
+     */
+    operationsRegistry?: Readonly<Record<string, {
+        path: string;
+    }>>;
 }
 /**
- * HTTP methods that are considered read-only query operations.
- * These can be used with useQuery() and support caching.
+ * Minimal interface satisfied by `QueryReturn`. Used for `refetchEndpoints`
+ * in cache invalidation options.
  */
-export declare const QUERY_METHODS: readonly [HttpMethod.GET, HttpMethod.HEAD, HttpMethod.OPTIONS];
+export interface Refetchable {
+    refetch: () => Promise<void>;
+}
 /**
- * HTTP methods that modify data and should use mutations.
+ * Options for controlling automatic cache invalidation after mutations.
  */
-export declare const MUTATION_METHODS: readonly [HttpMethod.POST, HttpMethod.PUT, HttpMethod.PATCH, HttpMethod.DELETE];
-/** @internal */
-export declare function isQueryMethod(method: HttpMethod): boolean;
-/** @internal */
-export declare function isMutationMethod(method: HttpMethod): boolean;
-/** @internal */
-export interface OperationInfo {
-    path: string;
-    method: HttpMethod;
+export interface CacheInvalidationOptions {
+    /** Skip automatic cache invalidation. @default false */
+    dontInvalidate?: boolean;
+    /** Skip automatic cache update for PUT/PATCH responses. @default false */
+    dontUpdateCache?: boolean;
+    /**
+     * Additional operation IDs to invalidate after mutation succeeds.
+     * Array of operation name strings, or map of operation name → path params.
+     * @example ['listPets']
+     * @example { getPet: { petId: '123' } }
+     */
+    invalidateOperations?: string[] | Record<string, Record<string, string | undefined>>;
+    /** Specific query endpoints to refetch after mutation succeeds. */
+    refetchEndpoints?: Refetchable[];
 }
-/** @internal */
-export type GetOperation<Ops extends Operations<Ops>, Op extends keyof Ops> = Ops[Op];
-type RequireAll<T> = {
-    [K in keyof T]-?: T[K];
-};
-type RequireReadonly<T> = {
-    [K in keyof T as IsReadonly<T, K> extends true ? K : never]-?: T[K];
-} & {
-    [K in keyof T as IsReadonly<T, K> extends false ? K : never]: T[K];
+type MaybeRefLeaf<T> = T | Ref<T> | ComputedRef<T>;
+type MaybeRefDeep<T> = T extends (...args: never[]) => unknown ? T : T extends object ? {
+    [K in keyof T]: MaybeRefDeep<T[K]>;
+} : MaybeRefLeaf<T>;
+type BaseQueryOptions<TResponse, _TQueryParams extends Record<string, unknown>> = MaybeRefDeep<QueryObserverOptions<TResponse, Error, TResponse, TResponse, QueryKey>> & {
+    shallow?: boolean;
 };
-type IfEquals<X, Y, A = X, B = never> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? A : B;
-type IsReadonly<T, K extends keyof T> = IfEquals<Pick<T, K>, {
-    -readonly [Q in K]: T[K];
-}, false, true>;
 /**
- * Extract the raw response data type from an operation without modifications.
- * @internal
+ * Options for `useQuery` composable. Accepts all TanStack Query options plus:
+ * - `enabled`: reactive boolean
+ * - `queryParams`: reactive query string parameters
+ * - `onLoad`: callback when data loads for the first time
+ * - `errorHandler`: custom error handler
+ * - `axiosOptions`: additional axios config
+ *
+ * @template TResponse    The response data type for this operation
+ * @template TQueryParams The query parameters type for this operation
  */
-type ExtractResponseData<Ops extends Operations<Ops>, Op extends keyof Ops> = GetOperation<Ops, Op> extends {
-    responses: {
-        200: {
-            content: {
-                'application/json': infer Data;
-            };
-        };
-    };
-} ? Data : unknown;
+export type QueryOptions<TResponse, TQueryParams extends Record<string, unknown> = Record<string, never>> = Omit<BaseQueryOptions<TResponse, TQueryParams>, 'queryKey' | 'queryFn' | 'enabled'> & {
+    enabled?: ReactiveOr<boolean>;
+    onLoad?: (data: TResponse) => void;
+    axiosOptions?: AxiosRequestConfigExtended;
+    errorHandler?: (error: AxiosError) => TResponse | void | Promise<TResponse | void>;
+    queryParams?: ReactiveOr<TQueryParams>;
+};
+type MutationVarsBase<TPathParams extends Record<string, unknown>, TQueryParams extends Record<string, unknown>> = CacheInvalidationOptions & {
+    pathParams?: Partial<TPathParams>;
+    axiosOptions?: AxiosRequestConfigExtended;
+    queryParams?: TQueryParams;
+};
 /**
- * Extract response data type from an operation (all fields required).
+ * Variables passed to `mutation.mutate()` or `mutation.mutateAsync()`.
  *
- * All fields are REQUIRED regardless of their `required` status in the OpenAPI schema.
- * This assumes the server always returns complete objects.
+ * When `TRequest` is `never` (operation has no request body), `data` is excluded.
  *
- * @example
- * ```typescript
- * type PetResponse = ApiResponse<OpenApiOperations, 'getPet'>
- * // { readonly id: string, name: string, ... } - all required
- * ```
+ * @template TPathParams  Path parameters type
+ * @template TRequest     Request body type (`never` if none)
+ * @template TQueryParams Query parameters type
  */
-export type ApiResponse<Ops extends Operations<Ops>, Op extends keyof Ops> = RequireAll<ExtractResponseData<Ops, Op>>;
+export type MutationVars<TPathParams extends Record<string, unknown>, TRequest, TQueryParams extends Record<string, unknown> = Record<string, never>> = [TRequest] extends [never] ? MutationVarsBase<TPathParams, TQueryParams> : MutationVarsBase<TPathParams, TQueryParams> & {
+    data?: TRequest;
+};
+type BaseMutationOptions<TResponse, TPathParams extends Record<string, unknown>, TRequest, TQueryParams extends Record<string, unknown>> = MaybeRefDeep<MutationObserverOptions<AxiosResponse<TResponse>, Error, MutationVars<TPathParams, TRequest, TQueryParams>, unknown>> & {
+    shallow?: boolean;
+};
 /**
- * Extract response data type with safe typing for unreliable backends.
- *
- * Only readonly properties are REQUIRED. Other properties preserve their optional status.
+ * Options for `useMutation` composable.
  *
- * @example
- * ```typescript
- * type PetResponse = ApiResponseSafe<OpenApiOperations, 'getPet'>
- * // { readonly id: string, name?: string, ... } - only readonly required
- * ```
+ * @template TResponse    Response data type
+ * @template TPathParams  Path parameters type
+ * @template TRequest     Request body type
+ * @template TQueryParams Query parameters type
  */
-export type ApiResponseSafe<Ops extends Operations<Ops>, Op extends keyof Ops> = RequireReadonly<ExtractResponseData<Ops, Op>>;
+export type MutationOptions<TResponse, TPathParams extends Record<string, unknown>, TRequest, TQueryParams extends Record<string, unknown> = Record<string, never>> = Omit<BaseMutationOptions<TResponse, TPathParams, TRequest, TQueryParams>, 'mutationFn' | 'mutationKey'> & CacheInvalidationOptions & {
+    axiosOptions?: AxiosRequestConfigExtended;
+    queryParams?: ReactiveOr<TQueryParams>;
+};
 /**
- * A value that can be reactive (ref, computed) or direct.
- * Standardized pattern for all reactive values across the library.
- *
- * @internal
+ * Return type of `mutation.mutateAsync()`.
  */
-export type ReactiveOr<T> = T | Ref<T> | ComputedRef<T> | (() => T);
+export type MutateAsyncReturn<TResponse> = Promise<AxiosResponse<TResponse>>;
 /**
- * Reactive value that excludes function getters.
- * Useful for path params where function overloads have stricter checks.
- *
- * @internal
+ * `mutation.mutate()` function signature.
  */
-export type ReactiveValue<T> = T | Ref<T> | ComputedRef<T>;
-/** @internal */
-type MaybeRefLeaf<T> = T | Ref<T> | ComputedRef<T>;
-type MaybeRefDeep<T> = T extends (...args: never[]) => unknown ? T : T extends object ? {
-    [K in keyof T]: MaybeRefDeep<T[K]>;
-} : MaybeRefLeaf<T>;
-/** @internal */
-type ShallowOption = {
-    shallow?: boolean;
-};
+export type MutateFn<TPathParams extends Record<string, unknown>, TRequest, TQueryParams extends Record<string, unknown> = Record<string, never>> = (vars?: MutationVars<TPathParams, TRequest, TQueryParams>) => void;
 /**
- * Extract path parameters type from an operation (truly required).
- *
- * All path parameters from the OpenAPI schema are required - they cannot be undefined.
- * This matches the runtime behavior where missing path params cause errors.
- *
- * @example
- * ```typescript
- * type Params = ApiPathParams<OpenApiOperations, 'getPet'>
- * // { petId: string } - all params required
- * ```
+ * `mutation.mutateAsync()` function signature.
  */
-export type ApiPathParams<Ops extends Operations<Ops>, Op extends keyof Ops> = Ops[Op] extends {
-    parameters: {
-        path: infer PathParams;
-    };
-} ? PathParams extends Record<string, unknown> ? PathParams : Record<string, never> : Record<string, never>;
+export type MutateAsyncFn<TResponse, TPathParams extends Record<string, unknown>, TRequest, TQueryParams extends Record<string, unknown> = Record<string, never>> = (vars?: MutationVars<TPathParams, TRequest, TQueryParams>) => MutateAsyncReturn<TResponse>;
 /**
- * Path params input type that allows undefined values for reactive resolution.
- *
- * @internal
+ * Constraint for operation objects. Accepts any object type including
+ * interfaces with known keys (like those generated by openapi-typescript).
  */
-export type ApiPathParamsInput<Ops extends Operations<Ops>, Op extends keyof Ops> = {
-    [K in keyof ApiPathParams<Ops, Op>]: ApiPathParams<Ops, Op>[K] | undefined;
+type AnyOps = object;
+type RequireAll<T> = {
+    [K in keyof T]-?: T[K];
+};
+type IfEquals<X, Y, A = X, B = never> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? A : B;
+type IsReadonly<T, K extends keyof T> = IfEquals<Pick<T, K>, {
+    -readonly [Q in K]: T[K];
+}, false, true>;
+type RequireReadonly<T> = {
+    [K in keyof T as IsReadonly<T, K> extends true ? K : never]-?: T[K];
+} & {
+    [K in keyof T as IsReadonly<T, K> extends false ? K : never]: T[K];
 };
+type ExtractResponseData<Ops extends AnyOps, Op extends keyof Ops> = Ops[Op] extends {
+    responses: {
+        200: {
+            content: {
+                'application/json': infer Data;
+            };
+        };
+    };
+} ? Data : Ops[Op] extends {
+    responses: {
+        201: {
+            content: {
+                'application/json': infer Data;
+            };
+        };
+    };
+} ? Data : Ops[Op] extends {
+    responses: {
+        202: {
+            content: {
+                'application/json': infer Data;
+            };
+        };
+    };
+} ? Data : Ops[Op] extends {
+    responses: {
+        203: {
+            content: {
+                'application/json': infer Data;
+            };
+        };
+    };
+} ? Data : Ops[Op] extends {
+    responses: {
+        204: {
+            content: {
+                'application/json': infer Data;
+            };
+        };
+    };
+} ? Data : Ops[Op] extends {
+    responses: {
+        206: {
+            content: {
+                'application/json': infer Data;
+            };
+        };
+    };
+} ? Data : unknown;
 /**
- * Extract query parameters type from an operation.
- * @example
- * ```typescript
- * type Params = ApiQueryParams<OpenApiOperations, 'listPets'>
- * // { limit?: number, status?: string }
- * ```
+ * Extract the response data type (all fields required).
+ * @example `ApiResponse<operations, 'getPet'>` → `{ readonly id: string, name: string, ... }`
  */
-export type ApiQueryParams<Ops extends Operations<Ops>, Op extends keyof Ops> = Ops[Op] extends {
-    parameters: {
-        query?: infer QueryParams;
-    };
-} ? QueryParams extends Record<string, unknown> ? {
-    [K in keyof QueryParams]?: QueryParams[K];
-} : Record<string, never> : Record<string, never>;
+export type ApiResponse<Ops extends AnyOps, Op extends keyof Ops> = RequireAll<ExtractResponseData<Ops, Op>>;
+/**
+ * Extract the response data type (only readonly fields required).
+ */
+export type ApiResponseSafe<Ops extends AnyOps, Op extends keyof Ops> = RequireReadonly<ExtractResponseData<Ops, Op>>;
 type Writable<T> = {
     -readonly [K in keyof T as IfEquals<Pick<T, K>, {
         -readonly [Q in K]: T[K];
     }, false, true> extends false ? K : never]: T[K];
 };
 /**
- * Extract request body type from an operation.
- * @example
- * ```typescript
- * type Body = ApiRequest<OpenApiOperations, 'createPet'>
- * // { name: string, species?: string }
- * ```
+ * Extract the request body type.
+ * @example `ApiRequest<operations, 'createPet'>` → `{ name: string, species?: string }`
  */
-export type ApiRequest<Ops extends Operations<Ops>, Op extends keyof Ops> = GetOperation<Ops, Op> extends {
+export type ApiRequest<Ops extends AnyOps, Op extends keyof Ops> = Ops[Op] extends {
     requestBody: {
         content: {
             'application/json': infer Body;
         };
     };
-} ? Writable<Body> : GetOperation<Ops, Op> extends {
+} ? Writable<Body> : Ops[Op] extends {
     requestBody: {
         content: {
             'multipart/form-data': infer Body;
@@ -259,296 +280,31 @@ export type ApiRequest<Ops extends Operations<Ops>, Op extends keyof Ops> = GetO
     };
 } ? Writable<Body> | FormData : never;
 /**
- * Options for controlling automatic cache invalidation and updates after mutations.
- *
- * By default, mutations automatically:
- * - Update cache for PUT/PATCH responses with the returned data
- * - Invalidate matching GET queries to trigger refetches
- *
- * @group Types
+ * Extract path parameters type (all required).
+ * @example `ApiPathParams<operations, 'getPet'>` → `{ petId: string }`
  */
-export interface CacheInvalidationOptions<Ops extends Operations<Ops>> {
-    /**
-     * Skip automatic cache invalidation after mutation completes.
-     *
-     * @default false
-     */
-    dontInvalidate?: boolean;
-    /**
-     * Skip automatic cache update for PUT/PATCH responses.
-     *
-     * @default false
-     */
-    dontUpdateCache?: boolean;
-    /**
-     * Additional operations to invalidate after mutation succeeds.
-     *
-     * Can be either:
-     * - Array of operation IDs: `['listPets', 'getPetStats']`
-     * - Map of operation ID to path params: `{ getPet: { petId: '123' } }`
-     *
-     * @example
-     * ```typescript
-     * // Invalidate list when creating
-     * { invalidateOperations: ['listPets'] }
-     *
-     * // Invalidate specific item
-     * { invalidateOperations: { getPet: { petId: '123' } } }
-     * ```
-     */
-    invalidateOperations?: (keyof Ops)[] | Partial<{
-        [K in keyof Ops]: ApiPathParams<Ops, K>;
-    }>;
-    /**
-     * Specific query endpoints to refetch after mutation succeeds.
-     *
-     * Use when you have specific query results that need to be refetched.
-     *
-     * @example
-     * ```typescript
-     * const listQuery = api.useQuery('listPets')
-     * { refetchEndpoints: [listQuery] }
-     * ```
-     */
-    refetchEndpoints?: EndpointQueryReturn<Ops, keyof Ops>[];
-}
-/**
- * Query options for `useQuery` with custom extensions.
- *
- * Supports all TanStack Query options plus:
- * - `enabled`: Reactive boolean to control when query runs
- * - `queryParams`: Reactive query string parameters
- * - `onLoad`: Callback when data loads successfully
- * - `errorHandler`: Custom error handler with fallback support
- * - `axiosOptions`: Additional axios configuration
- *
- * @template Ops - The operations type from your OpenAPI specification
- * @template Op - The operation key
- *
- * @example
- * ```typescript
- * const { data } = api.useQuery('listPets', {
- *   queryParams: { limit: 10 },
- *   enabled: computed(() => isLoggedIn.value),
- *   staleTime: 5000,
- *   onLoad: (data) => console.log('Loaded:', data.length)
- * })
- * ```
- *
- * @group Types
- */
-type BaseQueryOptions<Ops extends Operations<Ops>, Op extends keyof Ops> = MaybeRefDeep<QueryObserverOptions<ApiResponse<Ops, Op>, Error, ApiResponse<Ops, Op>, ApiResponse<Ops, Op>, QueryKey>> & ShallowOption;
-export type QQueryOptions<Ops extends Operations<Ops>, Op extends keyof Ops> = Omit<BaseQueryOptions<Ops, Op>, 'queryKey' | 'queryFn' | 'enabled'> & {
-    /** Whether the query should execute. Can be reactive (ref/computed/function). */
-    enabled?: ReactiveOr<boolean>;
-    /** Callback when data is successfully loaded for the first time. */
-    onLoad?: (data: ApiResponse<Ops, Op>) => void;
-    /** Additional axios configuration for this request. */
-    axiosOptions?: AxiosRequestConfigExtended;
-    /** Custom error handler. Return data to use as fallback, or void to use default error. */
-    errorHandler?: (error: AxiosError) => ApiResponse<Ops, Op> | void | Promise<ApiResponse<Ops, Op> | void>;
-    /** Query parameters for the request. Can be reactive (ref/computed/function). */
-    queryParams?: ReactiveOr<ApiQueryParams<Ops, Op>>;
-};
-/**
- * Variables passed to mutation.mutate() or mutation.mutateAsync().
- *
- * Combines cache invalidation options with mutation-specific data:
- * - `data`: Request body (when operation accepts one)
- * - `pathParams`: Path parameters (can override those from useMutation call)
- * - `queryParams`: Query string parameters
- * - `axiosOptions`: Additional axios configuration
- *
- * Plus all cache invalidation options (dontInvalidate, invalidateOperations, etc.)
- *
- * @template Ops - The operations type
- * @template Op - The operation key
- *
- * @example
- * ```typescript
- * const mutation = api.useMutation('createPet')
- * mutation.mutate({
- *   data: { name: 'Fluffy' },
- *   invalidateOperations: ['listPets']
- * })
- * ```
- *
- * @group Types
- */
-export type QMutationVars<Ops extends Operations<Ops>, Op extends keyof Ops> = CacheInvalidationOptions<Ops> & {
-    data?: ApiRequest<Ops, Op>;
-    pathParams?: ApiPathParamsInput<Ops, Op>;
-    axiosOptions?: AxiosRequestConfigExtended;
-    queryParams?: ApiQueryParams<Ops, Op>;
-};
-/**
- * Resolved return type for mutateAsync to avoid showing full operations union in tooltips.
- * @internal
- */
-export type MutateAsyncReturn<Ops extends Operations<Ops>, Op extends keyof Ops> = Promise<AxiosResponse<ApiResponse<Ops, Op>>>;
-/**
- * Function signature for mutation.mutate() - non-blocking mutation execution.
- *
- * Inlined types allow TypeScript to resolve specific operation types in tooltips
- * instead of showing the entire operations union.
- *
- * @group Types
- * @internal
- */
-export type MutateFn<Ops extends Operations<Ops>, Op extends keyof Ops> = (vars?: {
-    data?: ApiRequest<Ops, Op>;
-    pathParams?: ApiPathParamsInput<Ops, Op>;
-    axiosOptions?: AxiosRequestConfigExtended;
-    queryParams?: ApiQueryParams<Ops, Op>;
-    dontInvalidate?: boolean;
-    dontUpdateCache?: boolean;
-    invalidateOperations?: (keyof Ops)[];
-    refetchEndpoints?: EndpointQueryReturn<Ops, keyof Ops>[];
-}) => void;
-/**
- * Function signature for mutation.mutateAsync() - async mutation execution.
- *
- * Inlined types allow TypeScript to resolve specific operation types in tooltips
- * instead of showing the entire operations union.
- *
- * @group Types
- * @internal
- */
-export type MutateAsyncFn<Ops extends Operations<Ops>, Op extends keyof Ops> = (vars?: {
-    data?: ApiRequest<Ops, Op>;
-    pathParams?: ApiPathParamsInput<Ops, Op>;
-    axiosOptions?: AxiosRequestConfigExtended;
-    queryParams?: ApiQueryParams<Ops, Op>;
-    dontInvalidate?: boolean;
-    dontUpdateCache?: boolean;
-    invalidateOperations?: (keyof Ops)[];
-    refetchEndpoints?: EndpointQueryReturn<Ops, keyof Ops>[];
-}) => MutateAsyncReturn<Ops, Op>;
+export type ApiPathParams<Ops extends AnyOps, Op extends keyof Ops> = Ops[Op] extends {
+    parameters: {
+        path: infer PathParams;
+    };
+} ? PathParams extends Record<string, unknown> ? PathParams : Record<string, never> : Record<string, never>;
 /**
- * Mutation options for `useMutation` with custom extensions.
- *
- * Supports all TanStack Query mutation options plus:
- * - Cache invalidation options (dontInvalidate, invalidateOperations, etc.)
- * - `queryParams`: Reactive query string parameters
- * - `axiosOptions`: Additional axios configuration
- *
- * @template Ops - The operations type
- * @template Op - The operation key
- *
- * @example
- * ```typescript
- * const mutation = api.useMutation('createPet', {
- *   onSuccess: () => console.log('Created!'),
- *   invalidateOperations: ['listPets']
- * })
- * ```
- *
- * @group Types
+ * Path params input type — same as `ApiPathParams` but all values allow `undefined`
+ * (for reactive resolution where params may not yet be set).
  */
-type MutationVarsInput<Ops extends Operations<Ops>, Op extends keyof Ops> = ApiRequest<Ops, Op> extends never ? QMutationVars<Ops, Op> | void : QMutationVars<Ops, Op>;
-type BaseMutationOptions<Ops extends Operations<Ops>, Op extends keyof Ops> = MaybeRefDeep<MutationObserverOptions<AxiosResponse<ApiResponse<Ops, Op>>, Error, MutationVarsInput<Ops, Op>, unknown>> & ShallowOption;
-export type QMutationOptions<Ops extends Operations<Ops>, Op extends keyof Ops> = Omit<BaseMutationOptions<Ops, Op>, 'mutationFn' | 'mutationKey'> & CacheInvalidationOptions<Ops> & {
-    axiosOptions?: AxiosRequestConfigExtended;
-    queryParams?: ReactiveOr<ApiQueryParams<Ops, Op>>;
+export type ApiPathParamsInput<Ops extends AnyOps, Op extends keyof Ops> = {
+    [K in keyof ApiPathParams<Ops, Op>]: ApiPathParams<Ops, Op>[K] | undefined;
 };
 /**
- * Runtime type validator for mutation parameters.
- *
- * This helper is a pass-through function that helps TypeScript narrow parameter types.
- *
- * @example
- * ```typescript
- * const mutation = api.useMutation(MutationOperationId.createPet)
- * await mutation.mutateAsync(
- *   validateMutationParams(MutationOperationId.createPet, {
- *     data: { name: 'Fluffy' }
- *   })
- * )
- * ```
+ * Extract query parameters type (all optional).
+ * @example `ApiQueryParams<operations, 'listPets'>` → `{ limit?: number, status?: string }`
  */
-export declare function validateMutationParams<Ops extends Operations<Ops>, Op extends keyof Ops>(_operationId: Op, params: QMutationVars<Ops, Op>): QMutationVars<Ops, Op>;
-/** @internal */
-export type QueryOpsNoPathParams<Ops extends Operations<Ops>> = {
-    [Op in keyof Ops]: Ops[Op]['method'] extends HttpMethod.GET | HttpMethod.HEAD | HttpMethod.OPTIONS ? ApiPathParams<Ops, Op> extends Record<string, never> ? Op : never : never;
-}[keyof Ops];
-/** @internal */
-export type QueryOpsWithPathParams<Ops extends Operations<Ops>> = {
-    [Op in keyof Ops]: Ops[Op]['method'] extends HttpMethod.GET | HttpMethod.HEAD | HttpMethod.OPTIONS ? ApiPathParams<Ops, Op> extends Record<string, never> ? never : Op : never;
-}[keyof Ops];
-/** @internal */
-export type MutationOpsNoPathParams<Ops extends Operations<Ops>> = {
-    [Op in keyof Ops]: Ops[Op]['method'] extends HttpMethod.POST | HttpMethod.PUT | HttpMethod.PATCH | HttpMethod.DELETE ? ApiPathParams<Ops, Op> extends Record<string, never> ? Op : never : never;
-}[keyof Ops];
-/** @internal */
-export type MutationOpsWithPathParams<Ops extends Operations<Ops>> = {
-    [Op in keyof Ops]: Ops[Op]['method'] extends HttpMethod.POST | HttpMethod.PUT | HttpMethod.PATCH | HttpMethod.DELETE ? ApiPathParams<Ops, Op> extends Record<string, never> ? never : Op : never;
-}[keyof Ops];
-/**
- * Type representing an instance of the OpenAPI client returned by useOpenApi.
- *
- * This interface defines all the methods available on the API client instance.
- *
- * @group Types
- * @template Ops - The operations type from your OpenAPI specification
- *
- * @example
- * ```typescript
- * import { useOpenApi } from '@qualisero/openapi-endpoint'
- * import { type OpenApiOperations } from './generated/api-operations'
- *
- * const api: OpenApiInstance<OpenApiOperations> = useOpenApi(config)
- * const query = api.useQuery('getPet', { petId: '123' })
- * const mutation = api.useMutation('createPet')
- * ```
- */
-export type OpenApiInstance<Ops extends Operations<Ops>> = {
-    /**
-     * Execute a type-safe query (GET/HEAD/OPTIONS) with automatic caching.
-     *
-     * @template Op - The operation key
-     * @param operationId - Query operation ID
-     * @param pathParams - Path params for operations that require them
-     * @param options - Query options
-     * @returns Reactive query result
-     *
-     * @example
-     * ```typescript
-     * // No path params
-     * const listQuery = api.useQuery('listPets', { queryParams: { limit: 10 } })
-     *
-     * // With path params (direct object)
-     * const petQuery = api.useQuery('getPet', { petId: '123' })
-     *
-     * // With path params (reactive function)
-     * const id = ref('')
-     * const detailsQuery = api.useQuery('getPet', () => ({ petId: id.value }))
-     * ```
-     */
-    useQuery: (<Op extends QueryOpsNoPathParams<Ops>>(operationId: Op, options?: QQueryOptions<Ops, Op>) => EndpointQueryReturn<Ops, Op>) & (<Op extends QueryOpsWithPathParams<Ops>>(operationId: Op, pathParams: ReactiveValue<ApiPathParamsInput<Ops, Op>>, options?: QQueryOptions<Ops, Op>) => EndpointQueryReturn<Ops, Op>) & (<Op extends QueryOpsWithPathParams<Ops>, PathParams extends ApiPathParamsInput<Ops, Op>>(operationId: Op, pathParams: () => PathParams & (HasExcessPathParams<PathParams, ApiPathParams<Ops, Op>> extends true ? PathParams : never), options?: QQueryOptions<Ops, Op>) => EndpointQueryReturn<Ops, Op>);
-    /**
-     * Execute a type-safe mutation (POST/PUT/PATCH/DELETE) with automatic cache updates.
-     *
-     * @template Op - The operation key
-     * @param operationId - Mutation operation ID
-     * @param pathParams - Path params for operations that require them
-     * @param options - Mutation options
-     * @returns Reactive mutation result
-     *
-     * @example
-     * ```typescript
-     * // No path params
-     * const createPet = api.useMutation('createPet')
-     * createPet.mutate({ data: { name: 'Fluffy' } })
-     *
-     * // With path params (direct object)
-     * const updatePet = api.useMutation('updatePet', { petId: '123' })
-     * updatePet.mutate({ data: { name: 'Updated' } })
-     *
-     * // With path params (reactive function)
-     * const id = ref('')
-     * const deletePet = api.useMutation('deletePet', () => ({ petId: id.value }))
-     * ```
-     */
-    useMutation: (<Op extends MutationOpsNoPathParams<Ops>>(operationId: Op, options?: QMutationOptions<Ops, Op>) => EndpointMutationReturn<Ops, Op>) & (<Op extends MutationOpsWithPathParams<Ops>>(operationId: Op, pathParams: ReactiveValue<ApiPathParamsInput<Ops, Op>>, options?: QMutationOptions<Ops, Op>) => EndpointMutationReturn<Ops, Op>) & (<Op extends MutationOpsWithPathParams<Ops>, PathParams extends ApiPathParamsInput<Ops, Op>>(operationId: Op, pathParams: () => PathParams & (HasExcessPathParams<PathParams, ApiPathParams<Ops, Op>> extends true ? PathParams : never), options?: QMutationOptions<Ops, Op>) => EndpointMutationReturn<Ops, Op>);
-};
+export type ApiQueryParams<Ops extends AnyOps, Op extends keyof Ops> = Ops[Op] extends {
+    parameters: {
+        query?: infer QueryParams;
+    };
+} ? QueryParams extends Record<string, unknown> ? {
+    [K in keyof QueryParams]?: QueryParams[K];
+} : Record<string, never> : Record<string, never>;
+export {};
 //# sourceMappingURL=types.d.ts.map