@qualisero/openapi-endpoint 0.12.3 → 0.14.0

package/dist/types.d.ts

@@ -1,49 +1,57 @@
 import { type AxiosInstance, type AxiosError, type AxiosRequestConfig, type AxiosResponse } from 'axios';
-import { UseMutationOptions, type UseQueryOptions } from '@tanstack/vue-query';
-import type { MaybeRef, MaybeRefOrGetter } from 'vue';
-import type { EndpointQueryReturn } from './openapi-query';
-import type { EndpointMutationReturn } from './openapi-mutation';
+import type { MutationObserverOptions, QueryKey, QueryObserverOptions } from '@tanstack/query-core';
+import type { ComputedRef, Ref } from 'vue';
 /**
  * Extended Axios request configuration that allows custom properties.
- *
- * This type extends the standard AxiosRequestConfig to support custom properties
- * that users might add through module augmentation. It ensures compatibility with
- * both standard axios options and user-defined custom properties.
  */
 export type AxiosRequestConfigExtended = AxiosRequestConfig & Record<string, unknown>;
-/** @internal */
-export type { EndpointQueryReturn, EndpointMutationReturn };
-export type OperationId = string;
+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;
 /**
- * Interface defining the minimal QueryClient methods required by this library.
+ * A value that can be reactive (ref, computed, getter function) or direct.
+ */
+export type ReactiveOr<T> = T | Ref<T> | ComputedRef<T> | (() => T);
+/**
+ * Constrains a getter function `F` so that its return type has no excess
+ * properties beyond the expected type `T`.
+ *
+ * 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.
  *
- * This interface ensures compatibility with different versions of @tanstack/vue-query
- * by only requiring the specific methods that are actually used internally.
- * This prevents version compatibility issues where internal implementation details
- * (like private properties) might differ between versions.
+ * @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 ❌
+ * ```
  *
- * @group Types
+ * @internal Used in generated `api-client.ts` to enforce strict path params on getter fns.
+ */
+export type NoExcessReturn<T extends Record<string, unknown>, F extends () => T> = Exclude<keyof ReturnType<F>, keyof T> extends never ? F : never;
+/**
+ * Reactive value that excludes function getters.
+ * @internal Used for internal type inference.
  */
+export type ReactiveValue<T> = T | Ref<T> | ComputedRef<T>;
 export interface QueryClientLike {
-    /**
-     * Cancel running queries that match the provided filters.
-     * Used to prevent race conditions when mutations affect data.
-     */
     cancelQueries(filters: {
         queryKey: unknown[];
         exact?: boolean;
     }): Promise<void>;
-    /**
-     * Set query data for a specific query key.
-     * Used for optimistic updates after successful mutations.
-     */
     setQueryData(queryKey: unknown[], data: unknown): void;
-    /**
-     * Invalidate queries that match the provided filters.
-     * Used to trigger refetches of related data after mutations.
-     *
-     * @param filters - Filters can include queryKey, exact, and/or a predicate function
-     */
     invalidateQueries(filters: {
         queryKey?: unknown[];
         exact?: boolean;
@@ -52,289 +60,251 @@ export interface QueryClientLike {
         }) => boolean;
     }): Promise<void>;
 }
-export type Operations<Ops> = object & {
-    [K in keyof Ops]: {
-        method: HttpMethod;
-    };
-};
 /**
- * Configuration object for initializing the OpenAPI client.
+ * Runtime configuration for a single endpoint. Passed directly to
+ * `useEndpointQuery` / `useEndpointMutation` by generated code.
  *
- * This interface defines the required configuration to set up a type-safe OpenAPI client
- * with Vue Query integration. It requires both the operations metadata (typically generated
- * from your OpenAPI specification) and an Axios instance for making HTTP requests.
- *
- * @template Ops - The operations type, typically generated from your OpenAPI specification
- * @template AxiosConfig - The axios request configuration type (defaults to AxiosRequestConfig)
- *
- * @example
- * ```typescript
- * import { OpenApiConfig } from '@qualisero/openapi-endpoint'
- * import { openApiOperations, type OpenApiOperations } from './generated/api-operations'
- * import axios from 'axios'
- *
- * // Basic usage with default axios config
- * const config: OpenApiConfig<OpenApiOperations> = {
- *   operations: openApiOperations,
- *   axios: axios.create({
- *     baseURL: 'https://api.example.com',
- *     headers: { 'Authorization': 'Bearer token' }
- *   }),
- *   queryClient: customQueryClient // optional
- * }
- *
- * // With custom axios config type (for module augmentation)
- * const configWithCustomAxios: OpenApiConfig<OpenApiOperations, MyCustomAxiosRequestConfig> = {
- *   operations: openApiOperations,
- *   axios: customAxiosInstance
- * }
- * ```
+ * Created by the generated `createApiClient` factory and embedded per-operation
+ * in the generated `api-client.ts`.
  */
-export interface OpenApiConfig<Ops extends Operations<Ops>> {
-    /**
-     * The operations metadata object, typically generated from your OpenAPI specification.
-     * This contains type information and HTTP method details for each API endpoint.
-     */
-    operations: Ops;
+export interface EndpointConfig {
+    axios: AxiosInstance;
+    queryClient: QueryClientLike;
+    /** The OpenAPI path template, e.g. `/pets/{petId}` */
+    path: string;
+    method: HttpMethod;
     /**
-     * Axios instance for making HTTP requests.
-     * Configure this with your base URL, authentication, and any global request/response interceptors.
+     * 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.
      */
-    axios: AxiosInstance;
+    listPath?: string | null;
     /**
-     * Optional TanStack Query client instance.
-     * If not provided, a default QueryClient with sensible defaults will be used.
-     *
-     * Note: This accepts any QueryClient-like object that implements the required methods,
-     * ensuring compatibility across different versions of @tanstack/vue-query.
+     * Registry of all operations' paths, used to resolve `invalidateOperations`
+     * option at mutation time. Generated and embedded by the CLI.
      */
-    queryClient?: QueryClientLike;
-}
-export declare enum HttpMethod {
-    GET = "GET",
-    POST = "POST",
-    PUT = "PUT",
-    PATCH = "PATCH",
-    DELETE = "DELETE",
-    HEAD = "HEAD",
-    OPTIONS = "OPTIONS",
-    TRACE = "TRACE"
+    operationsRegistry?: Readonly<Record<string, {
+        path: string;
+    }>>;
 }
-/** @internal */
-export interface OperationInfo {
-    path: string;
-    method: HttpMethod;
+/**
+ * Minimal interface satisfied by `QueryReturn`. Used for `refetchEndpoints`
+ * in cache invalidation options.
+ */
+export interface Refetchable {
+    refetch: () => Promise<void>;
 }
-export type GetOperation<Ops extends Operations<Ops>, Op extends keyof Ops> = Ops[Op];
-export type GetResponseData<Ops extends Operations<Ops>, Op extends keyof Ops> = GetOperation<Ops, Op> extends {
-    responses: {
-        200: {
-            content: {
-                'application/json': infer Data;
-            };
-        };
-    };
-} ? RequireReadonly<Data> : unknown;
-type OmitMaybeRef<T, K extends PropertyKey> = T extends MaybeRef<infer U> ? MaybeRef<Omit<U, K> & Partial<Pick<U, K & keyof U>>> : Omit<T, K> & Partial<Pick<T, K & keyof T>>;
-/** @internal */
-export type QQueryOptions<Ops extends Operations<Ops>, Op extends keyof Ops> = OmitMaybeRef<UseQueryOptions<GetResponseData<Ops, Op>, Error, GetResponseData<Ops, Op>, GetResponseData<Ops, Op>>, 'queryKey' | 'queryFn' | 'enabled'> & {
-    enabled?: MaybeRefOrGetter<boolean>;
-    onLoad?: (data: GetResponseData<Ops, Op>) => void;
-    axiosOptions?: AxiosRequestConfigExtended;
-    errorHandler?: (error: AxiosError) => GetResponseData<Ops, Op> | void | Promise<GetResponseData<Ops, Op> | void>;
-    queryParams?: MaybeRefOrGetter<GetQueryParameters<Ops, Op>>;
-};
-type MutationOnSuccessOptions<Ops extends Operations<Ops>> = {
+/**
+ * Options for controlling automatic cache invalidation after mutations.
+ */
+export interface CacheInvalidationOptions {
+    /** Skip automatic cache invalidation. @default false */
     dontInvalidate?: boolean;
+    /** Skip automatic cache update for PUT/PATCH responses. @default false */
     dontUpdateCache?: boolean;
-    invalidateOperations?: (keyof Ops)[] | Partial<{
-        [K in keyof Ops]: GetPathParameters<Ops, K>;
-    }>;
-    refetchEndpoints?: EndpointQueryReturn<Ops, keyof Ops>[];
+    /**
+     * 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[];
+}
+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;
 };
-/** @internal */
-export type QMutationVars<Ops extends Operations<Ops>, Op extends keyof Ops> = MutationOnSuccessOptions<Ops> & {
-    data?: GetRequestBody<Ops, Op>;
-    pathParams?: GetPathParameters<Ops, Op>;
+/**
+ * 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
+ */
+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;
-    queryParams?: GetQueryParameters<Ops, Op>;
+    errorHandler?: (error: AxiosError) => TResponse | void | Promise<TResponse | void>;
+    queryParams?: ReactiveOr<TQueryParams>;
 };
-/** @internal */
-export type QMutationOptions<Ops extends Operations<Ops>, Op extends keyof Ops> = OmitMaybeRef<UseMutationOptions<AxiosResponse<GetResponseData<Ops, Op>>, Error, GetRequestBody<Ops, Op> extends never ? QMutationVars<Ops, Op> | void : QMutationVars<Ops, Op>>, 'mutationFn' | 'mutationKey'> & MutationOnSuccessOptions<Ops> & {
+type MutationVarsBase<TPathParams extends Record<string, unknown>, TQueryParams extends Record<string, unknown>> = CacheInvalidationOptions & {
+    pathParams?: Partial<TPathParams>;
     axiosOptions?: AxiosRequestConfigExtended;
-    queryParams?: MaybeRefOrGetter<GetQueryParameters<Ops, Op>>;
+    queryParams?: TQueryParams;
+};
+/**
+ * Variables passed to `mutation.mutate()` or `mutation.mutateAsync()`.
+ *
+ * When `TRequest` is `never` (operation has no request body), `data` is excluded.
+ *
+ * @template TPathParams  Path parameters type
+ * @template TRequest     Request body type (`never` if none)
+ * @template TQueryParams Query parameters type
+ */
+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;
+};
+/**
+ * Options for `useMutation` composable.
+ *
+ * @template TResponse    Response data type
+ * @template TPathParams  Path parameters type
+ * @template TRequest     Request body type
+ * @template TQueryParams Query parameters type
+ */
+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>;
+};
+/**
+ * Return type of `mutation.mutateAsync()`.
+ */
+export type MutateAsyncReturn<TResponse> = Promise<AxiosResponse<TResponse>>;
+/**
+ * `mutation.mutate()` function signature.
+ */
+export type MutateFn<TPathParams extends Record<string, unknown>, TRequest, TQueryParams extends Record<string, unknown> = Record<string, never>> = (vars?: MutationVars<TPathParams, TRequest, TQueryParams>) => void;
+/**
+ * `mutation.mutateAsync()` function signature.
+ */
+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>;
+/**
+ * Constraint for operation objects. Accepts any object type including
+ * interfaces with known keys (like those generated by openapi-typescript).
+ */
+type AnyOps = object;
+type RequireAll<T> = {
+    [K in keyof T]-?: T[K];
 };
-export type GetPathParameters<Ops extends Operations<Ops>, Op extends keyof Ops> = Ops[Op] extends {
-    parameters: {
-        path: infer PathParams;
-    };
-} ? {
-    [K in keyof PathParams]: PathParams[K] | undefined;
-} : Record<string, never>;
-export type GetQueryParameters<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>;
 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 the response data type (all fields required).
+ * @example `ApiResponse<operations, 'getPet'>` → `{ readonly id: string, name: string, ... }`
+ */
+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 IsReadonly<T, K> extends false ? K : never]: T[K];
+    -readonly [K in keyof T as IfEquals<Pick<T, K>, {
+        -readonly [Q in K]: T[K];
+    }, false, true> extends false ? K : never]: T[K];
 };
-export type GetRequestBody<Ops extends Operations<Ops>, Op extends keyof Ops> = GetOperation<Ops, Op> extends {
+/**
+ * Extract the request body type.
+ * @example `ApiRequest<operations, 'createPet'>` → `{ name: string, species?: string }`
+ */
+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;
         };
     };
 } ? Writable<Body> | FormData : never;
-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];
-};
-export type IsQueryOperation<Ops extends Operations<Ops>, Op extends keyof Ops> = Ops[Op] extends {
-    method: HttpMethod.GET | HttpMethod.HEAD | HttpMethod.OPTIONS;
-} ? true : false;
 /**
- * Type representing an instance of the OpenAPI client returned by useOpenApi.
- *
- * This interface defines all the methods available on the API client instance,
- * providing type-safe access to queries, mutations, and generic endpoints based
- * on your OpenAPI specification.
- *
- * @group Types
- * @template Ops - The operations type from your OpenAPI specification
- * @template AxiosConfig - The axios request configuration type (defaults to AxiosRequestConfig)
- *
- * @example
- * ```typescript
- * import { OpenApiInstance } from '@qualisero/openapi-endpoint'
- * import { type OpenApiOperations } from './generated/api-operations'
- *
- * // Type your API instance for better IntelliSense
- * const api: OpenApiInstance<OpenApiOperations> = useOpenApi(config)
- *
- * // All methods are now fully typed
- * const query = api.useQuery('getPet', { petId: '123' })
- * const mutation = api.useMutation('createPet')
- * const endpoint = api.useEndpoint('listPets')
- * ```
+ * Extract path parameters type (all required).
+ * @example `ApiPathParams<operations, 'getPet'>` → `{ petId: string }`
  */
-export type OpenApiInstance<Ops extends Operations<Ops>> = {
-    /**
-     * Debug utility to inspect operation metadata at runtime.
-     *
-     * This method helps during development to understand how operations are classified
-     * and can be useful for debugging type inference issues.
-     *
-     * @param operationId - The operation ID to inspect
-     * @returns Boolean indicating whether the operation is a query (GET/HEAD/OPTIONS)
-     *
-     * @example
-     * ```typescript
-     * // Check if an operation is a query or mutation
-     * const isQuery = api._debugIsQueryOperation('getPet') // true for GET
-     * const isMutation = api._debugIsQueryOperation('createPet') // false for POST
-     * ```
-     */
-    _debugIsQueryOperation: <Op extends keyof Ops>(operationId: Op) => IsQueryOperation<Ops, Op>;
-    /**
-     * Creates a reactive query for GET/HEAD/OPTIONS operations.
-     *
-     * This method creates a TanStack Query with automatic type inference, caching,
-     * and reactive updates. Only accepts operation IDs that correspond to query operations.
-     *
-     * @template Op - The operation key from your operations type
-     * @param operationId - Operation ID (must be a GET/HEAD/OPTIONS operation)
-     * @param pathParamsOrOptions - Path parameters (for parameterized routes) or query options
-     * @param optionsOrNull - Additional query options when path parameters are provided separately
-     * @returns Reactive query result with data, loading state, error handling, etc.
-     *
-     * @example
-     * ```typescript
-     * // Simple query without parameters
-     * const { data: pets, isLoading } = api.useQuery('listPets')
-     *
-     * // Query with path parameters
-     * const { data: pet } = api.useQuery('getPet', { petId: '123' })
-     *
-     * // Query with options
-     * const { data: pets } = api.useQuery('listPets', {
-     *   enabled: computed(() => shouldLoad.value),
-     *   onLoad: (data) => console.log('Loaded:', data)
-     * })
-     * ```
-     */
-    useQuery: <Op extends keyof Ops>(operationId: IsQueryOperation<Ops, Op> extends true ? Op : never, pathParamsOrOptions?: GetPathParameters<Ops, Op> extends Record<string, never> ? QQueryOptions<Ops, Op> : MaybeRefOrGetter<GetPathParameters<Ops, Op> | null | undefined> | QQueryOptions<Ops, Op>, optionsOrNull?: QQueryOptions<Ops, Op>) => EndpointQueryReturn<Ops, Op>;
-    /**
-     * Creates a reactive mutation for POST/PUT/PATCH/DELETE operations.
-     *
-     * This method creates a TanStack Query mutation with automatic cache invalidation,
-     * optimistic updates, and type-safe request/response handling. Only accepts operation IDs
-     * that correspond to mutation operations.
-     *
-     * @template Op - The operation key from your operations type
-     * @param operationId - Operation ID (must be a POST/PUT/PATCH/DELETE operation)
-     * @param pathParamsOrOptions - Path parameters (for parameterized routes) or mutation options
-     * @param optionsOrNull - Additional mutation options when path parameters are provided separately
-     * @returns Reactive mutation result with mutate, mutateAsync, status, etc.
-     *
-     * @example
-     * ```typescript
-     * // Simple mutation without path parameters
-     * const createPet = api.useMutation('createPet', {
-     *   onSuccess: (data) => console.log('Created:', data),
-     *   onError: (error) => console.error('Failed:', error)
-     * })
-     *
-     * // Mutation with path parameters
-     * const updatePet = api.useMutation('updatePet', { petId: '123' })
-     *
-     * // Execute mutations
-     * await createPet.mutateAsync({ data: { name: 'Fluffy', species: 'cat' } })
-     * await updatePet.mutateAsync({ data: { name: 'Updated Name' } })
-     * ```
-     */
-    useMutation: <Op extends keyof Ops>(operationId: IsQueryOperation<Ops, Op> extends false ? Op : never, pathParamsOrOptions?: GetPathParameters<Ops, Op> extends Record<string, never> ? QMutationOptions<Ops, Op> : MaybeRefOrGetter<GetPathParameters<Ops, Op> | null | undefined> | QMutationOptions<Ops, Op>, optionsOrNull?: QMutationOptions<Ops, Op>) => EndpointMutationReturn<Ops, Op>;
-    /**
-     * Generic endpoint composable that automatically detects operation type.
-     *
-     * This is a universal method that returns either a query or mutation based on the
-     * operation's HTTP method. It provides the same functionality as useQuery/useMutation
-     * but with automatic type detection, making it useful for generic or dynamic scenarios.
-     *
-     * @template Op - The operation key from your operations type
-     * @param operationId - Any valid operation ID from your API specification
-     * @param pathParamsOrOptions - Path parameters (for parameterized routes) or operation-specific options
-     * @param optionsOrNull - Additional options when path parameters are provided separately
-     * @returns Query result for GET/HEAD/OPTIONS operations, mutation result for others
-     *
-     * @example
-     * ```typescript
-     * // Automatically becomes a query for GET operations
-     * const listEndpoint = api.useEndpoint('listPets')
-     * // TypeScript infers this has query properties: .data, .isLoading, .refetch(), etc.
-     *
-     * // Automatically becomes a mutation for POST operations
-     * const createEndpoint = api.useEndpoint('createPet')
-     * // TypeScript infers this has mutation properties: .mutate(), .mutateAsync(), etc.
-     *
-     * // Use based on the detected type
-     * const petData = listEndpoint.data // Query data
-     * await createEndpoint.mutateAsync({ data: { name: 'Fluffy' } }) // Mutation execution
-     * ```
-     */
-    useEndpoint: <Op extends keyof Ops>(operationId: Op, pathParamsOrOptions?: GetPathParameters<Ops, Op> extends Record<string, never> ? IsQueryOperation<Ops, Op> extends true ? QQueryOptions<Ops, Op> : QMutationOptions<Ops, Op> : MaybeRefOrGetter<GetPathParameters<Ops, Op> | null | undefined> | (IsQueryOperation<Ops, Op> extends true ? QQueryOptions<Ops, Op> : QMutationOptions<Ops, Op>), optionsOrNull?: IsQueryOperation<Ops, Op> extends true ? QQueryOptions<Ops, Op> : QMutationOptions<Ops, Op>) => IsQueryOperation<Ops, Op> extends true ? EndpointQueryReturn<Ops, Op> : EndpointMutationReturn<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>;
+/**
+ * Path params input type — same as `ApiPathParams` but all values allow `undefined`
+ * (for reactive resolution where params may not yet be set).
+ */
+export type ApiPathParamsInput<Ops extends AnyOps, Op extends keyof Ops> = {
+    [K in keyof ApiPathParams<Ops, Op>]: ApiPathParams<Ops, Op>[K] | undefined;
 };
+/**
+ * Extract query parameters type (all optional).
+ * @example `ApiQueryParams<operations, 'listPets'>` → `{ limit?: number, status?: string }`
+ */
+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