@qualisero/openapi-endpoint 0.13.2 → 0.14.0

package/dist/cli.js

@@ -203,7 +203,7 @@ function addMissingOperationIds(openApiSpec, prefixToStrip = '/api') {
         });
     });
 }
-function parseOperationsFromSpec(openapiContent, excludePrefix = '_deprecated') {
+function _parseOperationsFromSpec(openapiContent, excludePrefix = '_deprecated') {
     const openApiSpec = JSON.parse(openapiContent);
     if (!openApiSpec.paths) {
         throw new Error('Invalid OpenAPI spec: missing paths');
@@ -570,18 +570,18 @@ function generateApiEnumsContent(enums) {
     // Generate the generic enum helper utility
     const helperUtility = `/**
  * Generic utility for working with enums
- * 
+ *
  * @example
  * import { EnumHelper, RequestedValuationType } from './api-enums'
- * 
+ *
  * // Get all values
  * const allTypes = EnumHelper.values(RequestedValuationType)
- * 
+ *
  * // Validate a value
  * if (EnumHelper.isValid(RequestedValuationType, userInput)) {
  *   // TypeScript knows userInput is RequestedValuationType
  * }
- * 
+ *
  * // Reverse lookup
  * const key = EnumHelper.getKey(RequestedValuationType, 'cat') // 'Cat'
  */
@@ -698,10 +698,10 @@ import type { components } from './openapi-types.js'
 /**
  * Type aliases for schema objects from the API spec.
  * These are references to components['schemas'] for convenient importing.
- * 
+ *
  * @example
  * import type { Nuts, Address, BorrowerInfo } from './api-schemas'
- * 
+ *
  * const nutsData: Nuts = { NUTS_ID: 'BE241', ... }
  */
 `;
@@ -731,235 +731,451 @@ async function generateApiSchemas(openapiContent, outputDir, _excludePrefix = '_
     console.log(`✅ Generated api-schemas file: ${outputPath}`);
     console.log(`📊 Found ${schemaCount} schemas`);
 }
-function generateApiOperationsContent(operationIds, operationInfoMap) {
-    // Generate operationsBase dictionary
-    const operationsBaseContent = operationIds
-        .map((id) => {
-        const info = operationInfoMap[id];
-        return `  ${id}: {\n    path: '${info.path}',\n    method: HttpMethod.${info.method},\n  },`;
-    })
-        .join('\n');
-    const queryOperationIds = operationIds.filter((id) => {
-        const method = operationInfoMap[id]?.method;
-        return method === HttpMethod.GET || method === HttpMethod.HEAD || method === HttpMethod.OPTIONS;
-    });
-    const mutationOperationIds = operationIds.filter((id) => {
-        const method = operationInfoMap[id]?.method;
-        return (method === HttpMethod.POST ||
-            method === HttpMethod.PUT ||
-            method === HttpMethod.PATCH ||
-            method === HttpMethod.DELETE);
-    });
-    // Generate filtered OperationId enums (source of truth)
-    const queryOperationIdContent = queryOperationIds.map((id) => `  ${id}: '${id}' as const,`).join('\n');
-    const mutationOperationIdContent = mutationOperationIds.map((id) => `  ${id}: '${id}' as const,`).join('\n');
-    // Generate OpType namespace from BOTH lists
-    const opTypeContent = [
-        ...queryOperationIds.map((id) => `  export type ${id} = typeof QueryOperationId.${id}`),
-        ...mutationOperationIds.map((id) => `  export type ${id} = typeof MutationOperationId.${id}`),
-    ].join('\n');
-    // Generate pre-computed type alias content for Phase 3B
-    const queryParamsContent = queryOperationIds.map((id) => `  ${id}: ApiQueryParams<OpType.${id}>`).join('\n');
-    const mutationParamsContent = mutationOperationIds.map((id) => `  ${id}: ApiPathParams<OpType.${id}>`).join('\n');
-    const mutationBodyContent = mutationOperationIds.map((id) => `  ${id}: ApiRequest<OpType.${id}>`).join('\n');
-    return `// Auto-generated from OpenAPI specification
-// Do not edit this file manually
+// ============================================================================
+// List path computation (ported from openapi-helpers.ts for code-gen time use)
+// ============================================================================
+const PLURAL_ES_SUFFIXES_CLI = ['s', 'x', 'z', 'ch', 'sh', 'o'];
+function pluralizeResourceCli(name) {
+    if (name.endsWith('y'))
+        return name.slice(0, -1) + 'ies';
+    if (PLURAL_ES_SUFFIXES_CLI.some((s) => name.endsWith(s)))
+        return name + 'es';
+    return name + 's';
+}
+/**
+ * Computes the list path for a mutation operation (used for cache invalidation).
+ * Returns null if no matching list operation is found.
+ */
+function computeListPath(operationId, opInfo, operationMap) {
+    const method = opInfo.method;
+    if (!['POST', 'PUT', 'PATCH', 'DELETE'].includes(method))
+        return null;
+    const prefixes = {
+        [HttpMethod.POST]: 'create',
+        [HttpMethod.PUT]: 'update',
+        [HttpMethod.PATCH]: 'update',
+        [HttpMethod.DELETE]: 'delete',
+    };
+    const prefix = prefixes[method];
+    if (!prefix)
+        return null;
+    let resourceName = null;
+    if (operationId.startsWith(prefix)) {
+        const remaining = operationId.slice(prefix.length);
+        if (remaining.length > 0 && /^[A-Z]/.test(remaining))
+            resourceName = remaining;
+    }
+    if (resourceName) {
+        const tryList = (name) => {
+            const listId = `list${name}`;
+            if (listId in operationMap && operationMap[listId].method === HttpMethod.GET)
+                return operationMap[listId].path;
+            return null;
+        };
+        const found = tryList(resourceName) || tryList(pluralizeResourceCli(resourceName));
+        if (found)
+            return found;
+    }
+    // Fallback: strip last path param segment
+    const segments = opInfo.path.split('/').filter((s) => s.length > 0);
+    if (segments.length >= 2 && /^\{[^}]+\}$/.test(segments[segments.length - 1])) {
+        return '/' + segments.slice(0, -1).join('/') + '/';
+    }
+    return null;
+}
+// ============================================================================
+// New generator: api-client.ts
+// ============================================================================
+/**
+ * Generate JSDoc comment for an operation function.
+ */
+function _generateOperationJSDoc(operationId, method, apiPath) {
+    const methodUpper = method.toUpperCase();
+    const isQuery = ['GET', 'HEAD', 'OPTIONS'].includes(methodUpper);
+    const lines = ['/**', ` * ${operationId}`, ' * ', ` * ${methodUpper} ${apiPath}`];
+    if (isQuery) {
+        lines.push(' * ');
+        lines.push(' * @param pathParams - Path parameters (reactive)');
+        lines.push(' * @param options - Query options (enabled, staleTime, onLoad, etc.)');
+        lines.push(' * @returns Query result with data, isLoading, refetch(), etc.');
+    }
+    else {
+        lines.push(' * ');
+        lines.push(' * @param pathParams - Path parameters (reactive)');
+        lines.push(' * @param options - Mutation options (onSuccess, onError, invalidateOperations, etc.)');
+        lines.push(' * @returns Mutation helper with mutate() and mutateAsync() methods');
+    }
+    lines.push(' */');
+    return lines.join('\n');
+}
+function generateApiClientContent(operationMap) {
+    const ids = Object.keys(operationMap).sort();
+    const QUERY_HTTP = new Set(['GET', 'HEAD', 'OPTIONS']);
+    const isQuery = (id) => QUERY_HTTP.has(operationMap[id].method);
+    const hasPathParams = (id) => operationMap[id].path.includes('{');
+    // Registry for invalidateOperations support
+    const registryEntries = ids.map((id) => `  ${id}: { path: '${operationMap[id].path}' },`).join('\n');
+    // Generic factory helpers (4 patterns)
+    const helpers = `/**
+ * Generic query helper for operations without path parameters.
+ * @internal
+ */
+function _queryNoParams<Op extends AllOps>(
+  base: _Config,
+  cfg: { path: string; method: HttpMethod; listPath: string | null },
+  enums: Record<string, unknown>,
+) {
+  type Response = ApiResponse<Op>
+  type QueryParams = ApiQueryParams<Op>
 
-import type { operations } from './openapi-types.js'
-import type {
-  ApiResponse as ApiResponseBase,
-  ApiResponseSafe as ApiResponseSafeBase,
-  ApiRequest as ApiRequestBase,
-  ApiPathParams as ApiPathParamsBase,
-  ApiQueryParams as ApiQueryParamsBase,
-} from '@qualisero/openapi-endpoint'
+  const useQuery = (
+    options?: QueryOptions<Response, QueryParams>,
+  ): QueryReturn<Response, Record<string, never>> =>
+    useEndpointQuery<Response, Record<string, never>, QueryParams>(
+      { ...base, ...cfg },
+      undefined,
+      options,
+    )
 
-export enum HttpMethod {
-  GET = 'GET',
-  POST = 'POST',
-  PUT = 'PUT',
-  PATCH = 'PATCH',
-  DELETE = 'DELETE',
-  HEAD = 'HEAD',
-  OPTIONS = 'OPTIONS',
-  TRACE = 'TRACE',
+  return {
+    /**
+     * Query hook for this operation.
+     *
+     * Returns an object with:
+     * - \`data\`: The response data
+     * - \`isLoading\`: Whether the query is loading
+     * - \`error\`: Error object if the query failed
+     * - \`refetch\`: Function to manually trigger a refetch
+     * - \`isPending\`: Alias for isLoading
+     * - \`status\`: 'pending' | 'error' | 'success'
+     *
+     * @param options - Query options (enabled, refetchInterval, etc.)
+     * @returns Query result object
+     */
+    useQuery,
+    enums,
+  } as const
 }
 
-// Create the typed structure that combines operations with operation metadata
-// This ensures the debug method returns correct values and all operations are properly typed
-const operationsBase = {
-${operationsBaseContent}
-} as const
+/**
+ * Generic query helper for operations with path parameters.
+ * @internal
+ */
+function _queryWithParams<Op extends AllOps>(
+  base: _Config,
+  cfg: { path: string; method: HttpMethod; listPath: string | null },
+  enums: Record<string, unknown>,
+) {
+  type PathParams = ApiPathParams<Op>
+  type PathParamsInput = ApiPathParamsInput<Op>
+  type Response = ApiResponse<Op>
+  type QueryParams = ApiQueryParams<Op>
 
-// Merge with operations type to maintain OpenAPI type information
-export const openApiOperations = operationsBase as typeof operationsBase & Pick<operations, keyof typeof operationsBase>
+  // Two-overload interface: non-function (exact via object-literal checking) +
+  // getter function (exact via NoExcessReturn constraint).
+  type _UseQuery = {
+    (
+      pathParams: PathParamsInput | Ref<PathParamsInput> | ComputedRef<PathParamsInput>,
+      options?: QueryOptions<Response, QueryParams>,
+    ): QueryReturn<Response, PathParams>
+    <F extends () => PathParamsInput>(
+      pathParams: NoExcessReturn<PathParamsInput, F>,
+      options?: QueryOptions<Response, QueryParams>,
+    ): QueryReturn<Response, PathParams>
+  }
 
-export type OpenApiOperations = typeof openApiOperations
+  const _impl = (
+    pathParams: ReactiveOr<PathParamsInput>,
+    options?: QueryOptions<Response, QueryParams>,
+  ): QueryReturn<Response, PathParams> =>
+    useEndpointQuery<Response, PathParams, QueryParams>(
+      { ...base, ...cfg },
+      pathParams as _PathParamsCast,
+      options,
+    )
 
-// Query operations only - use with useQuery() for better autocomplete
-export const QueryOperationId = {
-${queryOperationIdContent}
-} satisfies Partial<Record<keyof typeof operationsBase, keyof typeof operationsBase>>
+  return {
+    /**
+     * Query hook for this operation.
+     *
+     * Returns an object with:
+     * - \`data\`: The response data
+     * - \`isLoading\`: Whether the query is loading
+     * - \`error\`: Error object if the query failed
+     * - \`refetch\`: Function to manually trigger a refetch
+     * - \`isPending\`: Alias for isLoading
+     * - \`status\`: 'pending' | 'error' | 'success'
+     *
+     * @param pathParams - Path parameters (object, ref, computed, or getter function)
+     * @param options - Query options (enabled, refetchInterval, etc.)
+     * @returns Query result object
+     */
+    useQuery: _impl as _UseQuery,
+    enums,
+  } as const
+}
 
-export type QueryOperationId = keyof typeof QueryOperationId
+/**
+ * Generic mutation helper for operations without path parameters.
+ * @internal
+ */
+function _mutationNoParams<Op extends AllOps>(
+  base: _Config,
+  cfg: { path: string; method: HttpMethod; listPath: string | null },
+  enums: Record<string, unknown>,
+) {
+  type RequestBody = ApiRequest<Op>
+  type Response = ApiResponse<Op>
+  type QueryParams = ApiQueryParams<Op>
 
-// Mutation operations only - use with useMutation() for better autocomplete
-export const MutationOperationId = {
-${mutationOperationIdContent}
-} satisfies Partial<Record<keyof typeof operationsBase, keyof typeof operationsBase>>
+  const useMutation = (
+    options?: MutationOptions<Response, Record<string, never>, RequestBody, QueryParams>,
+  ): MutationReturn<Response, Record<string, never>, RequestBody, QueryParams> =>
+    useEndpointMutation<Response, Record<string, never>, RequestBody, QueryParams>(
+      { ...base, ...cfg },
+      undefined,
+      options,
+    )
 
-export type MutationOperationId = keyof typeof MutationOperationId
+  return {
+    /**
+     * Mutation hook for this operation.
+     *
+     * Returns an object with:
+     * - \`mutate\`: Synchronous mutation function (returns void)
+     * - \`mutateAsync\`: Async mutation function (returns Promise)
+     * - \`data\`: The response data
+     * - \`isLoading\`: Whether the mutation is in progress
+     * - \`error\`: Error object if the mutation failed
+     * - \`isPending\`: Alias for isLoading
+     * - \`status\`: 'idle' | 'pending' | 'error' | 'success'
+     *
+     * @param options - Mutation options (onSuccess, onError, etc.)
+     * @returns Mutation result object
+     */
+    useMutation,
+    enums,
+  } as const
+}
 
 /**
- * Union type of all operation IDs (queries and mutations).
- * Used for generic type constraints in helper types.
+ * Generic mutation helper for operations with path parameters.
  * @internal
  */
-export type AllOperationIds = QueryOperationId | MutationOperationId
+function _mutationWithParams<Op extends AllOps>(
+  base: _Config,
+  cfg: { path: string; method: HttpMethod; listPath: string | null },
+  enums: Record<string, unknown>,
+) {
+  type PathParams = ApiPathParams<Op>
+  type PathParamsInput = ApiPathParamsInput<Op>
+  type RequestBody = ApiRequest<Op>
+  type Response = ApiResponse<Op>
+  type QueryParams = ApiQueryParams<Op>
 
-// ============================================================================
-// Type-safe API Helpers - Use OpType.XXX for type-safe access with intellisense
-// ============================================================================
+  // Two-overload interface: non-function (exact via object-literal checking) +
+  // getter function (exact via NoExcessReturn constraint).
+  type _UseMutation = {
+    (
+      pathParams: PathParamsInput | Ref<PathParamsInput> | ComputedRef<PathParamsInput>,
+      options?: MutationOptions<Response, PathParams, RequestBody, QueryParams>,
+    ): MutationReturn<Response, PathParams, RequestBody, QueryParams>
+    <F extends () => PathParamsInput>(
+      pathParams: NoExcessReturn<PathParamsInput, F>,
+      options?: MutationOptions<Response, PathParams, RequestBody, QueryParams>,
+    ): MutationReturn<Response, PathParams, RequestBody, QueryParams>
+  }
 
-/**
- * Response data type for an API operation.
- * All fields are REQUIRED - no null checks needed.
- * @example
- *   type Response = ApiResponse<OpType.getPet>
- */
-export type ApiResponse<K extends AllOperationIds> = ApiResponseBase<OpenApiOperations, K>
+  const _impl = (
+    pathParams: ReactiveOr<PathParamsInput>,
+    options?: MutationOptions<Response, PathParams, RequestBody, QueryParams>,
+  ): MutationReturn<Response, PathParams, RequestBody, QueryParams> =>
+    useEndpointMutation<Response, PathParams, RequestBody, QueryParams>(
+      { ...base, ...cfg },
+      pathParams as _PathParamsCast,
+      options,
+    )
 
-/**
- * Response data type with safe typing for unreliable backends.
- * Only readonly properties are required; others may be undefined.
- * @example
- *   type Response = ApiResponseSafe<OpType.getPet>
- */
-export type ApiResponseSafe<K extends AllOperationIds> = ApiResponseSafeBase<OpenApiOperations, K>
+  return {
+    /**
+     * Mutation hook for this operation.
+     *
+     * Returns an object with:
+     * - \`mutate\`: Synchronous mutation function (returns void)
+     * - \`mutateAsync\`: Async mutation function (returns Promise)
+     * - \`data\`: The response data
+     * - \`isLoading\`: Whether the mutation is in progress
+     * - \`error\`: Error object if the mutation failed
+     * - \`isPending\`: Alias for isLoading
+     * - \`status\`: 'idle' | 'pending' | 'error' | 'success'
+     *
+     * @param pathParams - Path parameters (object, ref, computed, or getter function)
+     * @param options - Mutation options (onSuccess, onError, etc.)
+     * @returns Mutation result object
+     */
+    useMutation: _impl as _UseMutation,
+    enums,
+  } as const
+}`;
+    // createApiClient factory with operation calls
+    const factoryCalls = ids
+        .map((id) => {
+        const op = operationMap[id];
+        const { path: apiPath, method } = op;
+        const listPath = computeListPath(id, op, operationMap);
+        const listPathStr = listPath ? `'${listPath}'` : 'null';
+        const query = isQuery(id);
+        const withParams = hasPathParams(id);
+        const cfg = `{ path: '${apiPath}', method: HttpMethod.${method}, listPath: ${listPathStr} }`;
+        const helper = query
+            ? withParams
+                ? '_queryWithParams'
+                : '_queryNoParams'
+            : withParams
+                ? '_mutationWithParams'
+                : '_mutationNoParams';
+        // Build JSDoc comment
+        const docLines = [];
+        // Summary/description
+        if (op.summary) {
+            docLines.push(op.summary);
+        }
+        if (op.description && op.description !== op.summary) {
+            docLines.push(op.description);
+        }
+        // Path parameters
+        if (op.pathParams && op.pathParams.length > 0) {
+            const paramList = op.pathParams.map((p) => `${p.name}: ${p.type}`).join(', ');
+            docLines.push(`@param pathParams - { ${paramList} }`);
+        }
+        // Request body
+        if (op.requestBodySchema) {
+            docLines.push(`@param body - Request body type: ${op.requestBodySchema}`);
+        }
+        // Response
+        if (op.responseSchema) {
+            docLines.push(`@returns Response type: ${op.responseSchema}`);
+        }
+        const jsDoc = docLines.length > 0 ? `\n    /**\n     * ${docLines.join('\n     * ')}\n     */` : '';
+        return `${jsDoc}\n    ${id}: ${helper}<'${id}'>(base, ${cfg}, ${id}_enums),`;
+    })
+        .join('');
+    // Enum imports
+    const enumImports = ids.map((id) => `  ${id}_enums,`).join('\n');
+    // Type alias for AllOps
+    const allOpsType = `type AllOps = keyof operations`;
+    return `// Auto-generated from OpenAPI specification - do not edit manually
+// Use \`createApiClient\` to instantiate a fully-typed API client.
 
-/**
- * Request body type for a mutation operation.
- * @example
- *   type Request = ApiRequest<OpType.createPet>
- */
-export type ApiRequest<K extends AllOperationIds> = ApiRequestBase<OpenApiOperations, K>
+import type { AxiosInstance } from 'axios'
+import type { Ref, ComputedRef } from 'vue'
+import {
+  useEndpointQuery,
+  useEndpointMutation,
+  defaultQueryClient,
+  HttpMethod,
+  type QueryOptions,
+  type MutationOptions,
+  type QueryReturn,
+  type MutationReturn,
+  type ReactiveOr,
+  type NoExcessReturn,
+  type QueryClientLike,
+  type MaybeRefOrGetter,
+} from '@qualisero/openapi-endpoint'
 
-/**
- * Path parameters type for an operation.
- * @example
- *   type Params = ApiPathParams<OpType.getPet>
- */
-export type ApiPathParams<K extends AllOperationIds> = ApiPathParamsBase<OpenApiOperations, K>
+import type {
+  ApiResponse,
+  ApiRequest,
+  ApiPathParams,
+  ApiPathParamsInput,
+  ApiQueryParams,
+  operations,
+} from './api-operations.js'
 
-/**
- * Query parameters type for an operation.
- * @example
- *   type Params = ApiQueryParams<OpType.listPets>
- */
-export type ApiQueryParams<K extends AllOperationIds> = ApiQueryParamsBase<OpenApiOperations, K>
+import {
+${enumImports}
+} from './api-operations.js'
 
 // ============================================================================
-// OpType namespace - enables dot notation: ApiResponse<OpType.getPet>
+// Operations registry (for invalidateOperations support)
 // ============================================================================
 
-/**
- * Namespace that mirrors operation IDs as types.
- * Enables dot notation syntax: ApiResponse<OpType.getPet>
- *
- * This is the idiomatic TypeScript pattern for enabling dot notation
- * on type-level properties. The namespace is preferred over type aliases
- * because it allows \`OpType.getPet\` instead of \`OpType['getPet']\`.
- *
- * @example
- *   type Response = ApiResponse<OpType.getPet>
- *   type Request = ApiRequest<OpType.createPet>
- */
-// eslint-disable-next-line @typescript-eslint/no-namespace
-export namespace OpType {
-${opTypeContent}
-}
+const _registry = {
+${registryEntries}
+} as const
 
 // ============================================================================
-// Pre-Computed Type Aliases - For easier DX and clearer intent
+// Internal config type
 // ============================================================================
 
-/**
- * Query parameters for each query operation.
- * 
- * Use this to get autocomplete on query parameter names and types.
- * 
- * @example
- * \`\`\`typescript
- * const params: QueryParams['listPets'] = { limit: 10, status: 'available' }
- * const query = api.useQuery(QueryOperationId.listPets, { queryParams: params })
- * \`\`\`
- */
-export type QueryParams = {
-${queryParamsContent}
+type _Config = {
+  axios: AxiosInstance
+  queryClient: QueryClientLike
+  operationsRegistry: typeof _registry
 }
 
-/**
- * Path parameters for each mutation operation.
- * 
- * Use this to get autocomplete on path parameter names and types.
- * 
- * @example
- * \`\`\`typescript
- * const params: MutationParams['updatePet'] = { petId: '123' }
- * const mutation = api.useMutation(MutationOperationId.updatePet, params)
- * \`\`\`
- */
-export type MutationParams = {
-${mutationParamsContent}
-}
+// ============================================================================
+// Type alias for path params cast (avoids repetition)
+// ============================================================================
 
-/**
- * Request body for each mutation operation.
- * 
- * Use this to get autocomplete on request body properties and types.
- * 
- * @example
- * \`\`\`typescript
- * const body: MutationBody['createPet'] = { name: 'Fluffy', species: 'cat' }
- * await createPet.mutateAsync({ data: body })
- * \`\`\`
- */
-export type MutationBody = {
-${mutationBodyContent}
-}
+type _PathParamsCast = MaybeRefOrGetter<Record<string, string | number | undefined> | null | undefined>
 
 // ============================================================================
-// LEGACY: OperationId (auto-derived from union for backward compatibility)
+// Type alias for all operations
 // ============================================================================
-// Use QueryOperationId or MutationOperationId directly for better type safety
 
-/**
- * @deprecated Use QueryOperationId or MutationOperationId instead.
- * Auto-derived from their union for backward compatibility.
- */
-export type OperationId = AllOperationIds
+${allOpsType}
+
+// ============================================================================
+// Shared generic factory helpers (4 patterns)
+// ============================================================================
+
+${helpers}
+
+// ============================================================================
+// Public API client factory
+// ============================================================================
 
 /**
- * @deprecated Use QueryOperationId or MutationOperationId instead.
- * Auto-derived from their union for backward compatibility.
+ * Create a fully-typed API client.
+ *
+ * Each operation in the spec is a property of the returned object:
+ * - GET/HEAD/OPTIONS → \`api.opName.useQuery(...)\`
+ * - POST/PUT/PATCH/DELETE → \`api.opName.useMutation(...)\`
+ * - All operations → \`api.opName.enums.fieldName.Value\`
+ *
+ * @example
+ * \`\`\`ts
+ * import { createApiClient } from './generated/api-client'
+ * import axios from 'axios'
+ *
+ * const api = createApiClient(axios.create({ baseURL: '/api' }))
+ *
+ * // In a Vue component:
+ * const { data: pets } = api.listPets.useQuery()
+ * const create = api.createPet.useMutation()
+ * create.mutate({ data: { name: 'Fluffy' } })
+ * \`\`\`
  */
-export const OperationId = {
-  ...QueryOperationId,
-  ...MutationOperationId,
-} satisfies Record<AllOperationIds, AllOperationIds>
+export function createApiClient(axios: AxiosInstance, queryClient: QueryClientLike = defaultQueryClient) {
+  const base: _Config = { axios, queryClient, operationsRegistry: _registry }
+  return {
+${factoryCalls}
+  } as const
+}
+
+/** The fully-typed API client instance type. */
+export type ApiClient = ReturnType<typeof createApiClient>
 `;
 }
-async function generateApiOperations(openapiContent, outputDir, excludePrefix = '_deprecated') {
-    console.log('🔨 Generating openapi-typed-operations.ts file...');
-    const { operationIds, operationInfoMap } = parseOperationsFromSpec(openapiContent, excludePrefix);
-    // Generate TypeScript content
-    const tsContent = generateApiOperationsContent(operationIds, operationInfoMap);
-    // Write to output file
-    const outputPath = path.join(outputDir, 'openapi-typed-operations.ts');
-    fs.writeFileSync(outputPath, tsContent);
-    console.log(`✅ Generated openapi-typed-operations file: ${outputPath}`);
-    console.log(`📊 Found ${operationIds.length} operations`);
+async function generateApiClientFile(openApiSpec, outputDir, excludePrefix) {
+    const operationMap = buildOperationMap(openApiSpec, excludePrefix);
+    const content = generateApiClientContent(operationMap);
+    fs.writeFileSync(path.join(outputDir, 'api-client.ts'), content);
+    console.log(`✅ Generated api-client.ts (${Object.keys(operationMap).length} operations)`);
 }
+// ============================================================================
 function printUsage() {
     console.log(`
 Usage: npx @qualisero/openapi-endpoint <openapi-input> <output-directory> [options]
@@ -981,12 +1197,337 @@ Examples:
   npx @qualisero/openapi-endpoint ./api.json ./src/gen --no-exclude
 
 This command will generate:
-  - openapi-types.ts              (TypeScript types from OpenAPI spec)
-  - openapi-typed-operations.ts   (Operation IDs and info for use with this library)
-  - api-enums.ts                  (Type-safe enum objects from OpenAPI spec)
-  - api-schemas.ts                (Type aliases for schema objects from OpenAPI spec)
+  - openapi-types.ts   (TypeScript types from OpenAPI spec)
+  - api-client.ts      (Fully-typed createApiClient factory — main file to use)
+  - api-operations.ts  (Operations map + type aliases)
+  - api-types.ts       (Types namespace for type-only access)
+  - api-enums.ts       (Type-safe enum objects from OpenAPI spec)
+  - api-schemas.ts     (Type aliases for schema objects from OpenAPI spec)
 `);
 }
+// ============================================================================
+// New helper functions for operation-named API
+// ============================================================================
+/**
+ * Parses an already-loaded OpenAPISpec into a map of operationId → OperationInfo.
+ * @param openApiSpec The parsed OpenAPI spec object
+ * @param excludePrefix Operations with this prefix are excluded
+ * @returns Map of operation ID to { path, method }
+ */
+function buildOperationMap(openApiSpec, excludePrefix) {
+    const map = {};
+    for (const [pathUrl, pathItem] of Object.entries(openApiSpec.paths)) {
+        for (const [method, rawOp] of Object.entries(pathItem)) {
+            if (!HTTP_METHODS.includes(method))
+                continue;
+            const op = rawOp;
+            if (!op.operationId)
+                continue;
+            if (excludePrefix && op.operationId.startsWith(excludePrefix))
+                continue;
+            // Extract path and query parameters
+            const pathParams = [];
+            const queryParams = [];
+            if (op.parameters) {
+                for (const param of op.parameters) {
+                    const type = param.schema?.type || 'string';
+                    if (param.in === 'path') {
+                        pathParams.push({ name: param.name, type });
+                    }
+                    else if (param.in === 'query') {
+                        queryParams.push({ name: param.name, type });
+                    }
+                }
+            }
+            // Extract request body schema
+            let requestBodySchema;
+            const reqBodyRef = op.requestBody?.content?.['application/json']?.schema?.$ref;
+            if (reqBodyRef) {
+                requestBodySchema = reqBodyRef.split('/').pop();
+            }
+            // Extract response schema (from 200/201 responses)
+            let responseSchema;
+            if (op.responses) {
+                for (const statusCode of ['200', '201']) {
+                    const resRef = op.responses[statusCode]?.content?.['application/json']?.schema?.$ref;
+                    if (resRef) {
+                        responseSchema = resRef.split('/').pop();
+                        break;
+                    }
+                }
+            }
+            map[op.operationId] = {
+                path: pathUrl,
+                method: method.toUpperCase(),
+                summary: op.summary,
+                description: op.description,
+                pathParams: pathParams.length > 0 ? pathParams : undefined,
+                queryParams: queryParams.length > 0 ? queryParams : undefined,
+                requestBodySchema,
+                responseSchema,
+            };
+        }
+    }
+    return map;
+}
+/**
+ * Converts an OpenAPI enum array to `{ MemberName: 'value' }`.
+ * @param values Enum values (may include null)
+ * @returns Object with PascalCase keys and string literal values
+ */
+function enumArrayToObject(values) {
+    const obj = {};
+    for (const v of values) {
+        if (v === null)
+            continue;
+        obj[toEnumMemberName(v)] = String(v);
+    }
+    return obj;
+}
+/**
+ * For each operation, extract enum fields from:
+ *  1. Request body object properties (direct `enum` or `$ref` to an enum schema)
+ *  2. Query and path parameters with `enum`
+ * @param openApiSpec The parsed OpenAPI spec
+ * @param operationMap Map from buildOperationMap
+ * @returns operationId → { fieldName → { MemberName: 'value' } }
+ */
+function buildOperationEnums(openApiSpec, operationMap) {
+    // Schema-level enum lookup: schemaName → { MemberName: value }
+    const schemaEnumLookup = {};
+    if (openApiSpec.components?.schemas) {
+        for (const [schemaName, schema] of Object.entries(openApiSpec.components.schemas)) {
+            if (schema.enum) {
+                schemaEnumLookup[schemaName] = enumArrayToObject(schema.enum);
+            }
+        }
+    }
+    function resolveEnums(schema) {
+        if (schema.enum)
+            return enumArrayToObject(schema.enum);
+        if (typeof schema.$ref === 'string') {
+            const name = schema.$ref.split('/').pop();
+            return schemaEnumLookup[name] ?? null;
+        }
+        return null;
+    }
+    const result = {};
+    for (const [_pathUrl, pathItem] of Object.entries(openApiSpec.paths)) {
+        for (const [method, rawOp] of Object.entries(pathItem)) {
+            if (!HTTP_METHODS.includes(method))
+                continue;
+            const op = rawOp;
+            if (!op.operationId || !(op.operationId in operationMap))
+                continue;
+            const fields = {};
+            // Request body properties
+            const bodyProps = op.requestBody?.content?.['application/json']?.schema?.properties;
+            if (bodyProps) {
+                for (const [fieldName, fieldSchema] of Object.entries(bodyProps)) {
+                    const resolved = resolveEnums(fieldSchema);
+                    if (resolved)
+                        fields[fieldName] = resolved;
+                }
+            }
+            // Query + path parameters
+            for (const param of op.parameters ?? []) {
+                if (param.schema) {
+                    const resolved = resolveEnums(param.schema);
+                    if (resolved)
+                        fields[param.name] = resolved;
+                }
+            }
+            result[op.operationId] = fields;
+        }
+    }
+    return result;
+}
+// ============================================================================
+// New generators: api-operations.ts
+// ============================================================================
+/**
+ * Generates the content for `api-operations.ts` file.
+ * @param operationMap The operation info map
+ * @param opEnums Per-operation enum fields
+ * @param schemaEnumNames Names from api-enums.ts to re-export
+ * @returns Generated TypeScript file content
+ */
+function generateApiOperationsContent(operationMap, opEnums, schemaEnumNames) {
+    const ids = Object.keys(operationMap).sort();
+    const _queryIds = ids.filter((id) => ['GET', 'HEAD', 'OPTIONS'].includes(operationMap[id].method));
+    const _mutationIds = ids.filter((id) => ['POST', 'PUT', 'PATCH', 'DELETE'].includes(operationMap[id].method));
+    // Per-operation enum consts
+    const enumConsts = ids
+        .map((id) => {
+        const fields = opEnums[id] ?? {};
+        const body = Object.entries(fields)
+            .map(([field, vals]) => {
+            const members = Object.entries(vals)
+                .map(([k, v]) => `    ${k}: ${JSON.stringify(v)} as const,`)
+                .join('\n');
+            return `  ${field}: {\n${members}\n  } as const,`;
+        })
+            .join('\n');
+        return `export const ${id}_enums = {\n${body}\n} as const`;
+    })
+        .join('\n\n');
+    // Operations map
+    const opEntries = ids
+        .map((id) => `  ${id}: { path: '${operationMap[id].path}', method: HttpMethod.${operationMap[id].method} },`)
+        .join('\n');
+    // Type helpers — now use openapi-typescript `operations` directly (not OpenApiOperations)
+    const typeHelpers = `
+type AllOps = keyof operations
+
+/** Response data type for an operation (all fields required). */
+export type ApiResponse<K extends AllOps> = _ApiResponse<operations, K>
+/** Response data type - only \`readonly\` fields required. */
+export type ApiResponseSafe<K extends AllOps> = _ApiResponseSafe<operations, K>
+/** Request body type. */
+export type ApiRequest<K extends AllOps> = _ApiRequest<operations, K>
+/** Path parameters type. */
+export type ApiPathParams<K extends AllOps> = _ApiPathParams<operations, K>
+/** Path parameters input type (allows undefined values for reactive resolution). */
+export type ApiPathParamsInput<K extends AllOps> = _ApiPathParamsInput<operations, K>
+/** Query parameters type. */
+export type ApiQueryParams<K extends AllOps> = _ApiQueryParams<operations, K>`;
+    // Re-exports
+    // Use type-only wildcard export to avoid duplicate identifier errors
+    const reExports = schemaEnumNames.length > 0
+        ? schemaEnumNames.map((n) => `export { ${n} } from './api-enums'`).join('\n') +
+            "\nexport type * from './api-enums'"
+        : '// No schema-level enums to re-export';
+    return `// Auto-generated from OpenAPI specification - do not edit manually
+
+import type { operations } from './openapi-types.js'
+import { HttpMethod } from '@qualisero/openapi-endpoint'
+import type {
+  ApiResponse as _ApiResponse,
+  ApiResponseSafe as _ApiResponseSafe,
+  ApiRequest as _ApiRequest,
+  ApiPathParams as _ApiPathParams,
+  ApiPathParamsInput as _ApiPathParamsInput,
+  ApiQueryParams as _ApiQueryParams,
+} from '@qualisero/openapi-endpoint'
+
+export type { operations }
+
+${reExports}
+
+// ============================================================================
+// Per-operation enum values
+// ============================================================================
+
+${enumConsts}
+
+// ============================================================================
+// Operations map (kept for inspection / backward compatibility)
+// ============================================================================
+
+const operationsBase = {
+${opEntries}
+} as const
+
+export const openApiOperations = operationsBase as typeof operationsBase & Pick<operations, keyof typeof operationsBase>
+export type OpenApiOperations = typeof openApiOperations
+
+// ============================================================================
+// Convenience type aliases
+// ============================================================================
+${typeHelpers}
+`;
+}
+/**
+ * Async wrapper for generateApiOperationsContent.
+ */
+async function generateApiOperationsFile(openApiSpec, outputDir, excludePrefix, schemaEnumNames) {
+    console.log('🔨 Generating api-operations.ts...');
+    const operationMap = buildOperationMap(openApiSpec, excludePrefix);
+    const opEnums = buildOperationEnums(openApiSpec, operationMap);
+    const content = generateApiOperationsContent(operationMap, opEnums, schemaEnumNames);
+    fs.writeFileSync(path.join(outputDir, 'api-operations.ts'), content);
+    console.log(`✅ Generated api-operations.ts (${Object.keys(operationMap).length} operations)`);
+}
+// ============================================================================
+// New generators: api-types.ts
+// ============================================================================
+/**
+ * Generates the content for `api-types.ts` file.
+ * @param operationMap The operation info map
+ * @param opEnums Per-operation enum fields
+ * @returns Generated TypeScript file content
+ */
+function generateApiTypesContent(operationMap, opEnums) {
+    const ids = Object.keys(operationMap).sort();
+    const isQuery = (id) => ['GET', 'HEAD', 'OPTIONS'].includes(operationMap[id].method);
+    const namespaces = ids
+        .map((id) => {
+        const query = isQuery(id);
+        const fields = opEnums[id] ?? {};
+        const enumTypes = Object.entries(fields)
+            .map(([fieldName, vals]) => {
+            const typeName = fieldName.charAt(0).toUpperCase() + fieldName.slice(1);
+            const union = Object.values(vals)
+                .map((v) => `'${v}'`)
+                .join(' | ');
+            return `      /** \`${union}\` */\n      export type ${typeName} = ${union}`;
+        })
+            .join('\n');
+        const commonLines = [
+            `    /** Full response type - all fields required. */`,
+            `    export type Response     = _ApiResponse<OpenApiOperations, '${id}'>`,
+            `    /** Response type - only \`readonly\` fields required. */`,
+            `    export type SafeResponse = _ApiResponseSafe<OpenApiOperations, '${id}'>`,
+        ];
+        if (!query) {
+            commonLines.push(`    /** Request body type. */`, `    export type Request      = _ApiRequest<OpenApiOperations, '${id}'>`);
+        }
+        commonLines.push(`    /** Path parameters. */`, `    export type PathParams   = _ApiPathParams<OpenApiOperations, '${id}'>`, `    /** Query parameters. */`, `    export type QueryParams  = _ApiQueryParams<OpenApiOperations, '${id}'>`);
+        const enumNs = enumTypes ? `    export namespace Enums {\n${enumTypes}\n    }` : `    export namespace Enums {}`;
+        return `  export namespace ${id} {\n${commonLines.join('\n')}\n${enumNs}\n  }`;
+    })
+        .join('\n\n');
+    return `/* eslint-disable */
+// Auto-generated from OpenAPI specification — do not edit manually
+
+import type {
+  ApiResponse as _ApiResponse,
+  ApiResponseSafe as _ApiResponseSafe,
+  ApiRequest as _ApiRequest,
+  ApiPathParams as _ApiPathParams,
+  ApiQueryParams as _ApiQueryParams,
+} from '@qualisero/openapi-endpoint'
+import type { operations as OpenApiOperations } from './openapi-types.js'
+
+/**
+ * Type-only namespace for all API operations.
+ *
+ * @example
+ * \`\`\`ts
+ * import type { Types } from './generated/api-types'
+ *
+ * type Pet       = Types.getPet.Response
+ * type NewPet    = Types.createPet.Request
+ * type PetStatus = Types.createPet.Enums.Status   // 'available' | 'pending' | 'adopted'
+ * type Params    = Types.getPet.PathParams         // { petId: string }
+ * \`\`\`
+ */
+export namespace Types {
+${namespaces}
+}
+`;
+}
+/**
+ * Async wrapper for generateApiTypesContent.
+ */
+async function generateApiTypesFile(openApiSpec, outputDir, excludePrefix) {
+    console.log('🔨 Generating api-types.ts...');
+    const operationMap = buildOperationMap(openApiSpec, excludePrefix);
+    const opEnums = buildOperationEnums(openApiSpec, operationMap);
+    const content = generateApiTypesContent(operationMap, opEnums);
+    fs.writeFileSync(path.join(outputDir, 'api-types.ts'), content);
+    console.log(`✅ Generated api-types.ts`);
+}
 async function main() {
     const args = process.argv.slice(2);
     if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
@@ -1030,18 +1571,22 @@ async function main() {
         else {
             console.log(`✅ Including all operations (no exclusion filter)`);
         }
-        // Fetch OpenAPI spec content
+        // Fetch and parse OpenAPI spec once
         let openapiContent = await fetchOpenAPISpec(openapiInput);
-        // Parse spec and add missing operationIds
         const openApiSpec = JSON.parse(openapiContent);
+        // Add missing operationIds
         addMissingOperationIds(openApiSpec);
         openapiContent = JSON.stringify(openApiSpec, null, 2);
+        // Collect schema enum names for re-export
+        const schemaEnumNames = extractEnumsFromSpec(openApiSpec).map((e) => e.name);
         // Generate all files
         await Promise.all([
             generateTypes(openapiContent, outputDir),
-            generateApiOperations(openapiContent, outputDir, excludePrefix),
             generateApiEnums(openapiContent, outputDir, excludePrefix),
             generateApiSchemas(openapiContent, outputDir, excludePrefix),
+            generateApiOperationsFile(openApiSpec, outputDir, excludePrefix, schemaEnumNames),
+            generateApiTypesFile(openApiSpec, outputDir, excludePrefix),
+            generateApiClientFile(openApiSpec, outputDir, excludePrefix),
         ]);
         console.log('🎉 Code generation completed successfully!');
     }