vue-api-kit 1.10.8 → 1.10.9

package/README.md

@@ -1,5 +1,4 @@
 
-
 # 🚀 vue-api-kit
 
 [![NPM Version](https://img.shields.io/npm/v/vue-api-kit.svg?style=flat-square)](https://www.npmjs.com/package/vue-api-kit)
@@ -11,6 +10,24 @@
 
 A powerful and type-safe API client for Vue 3 applications with built-in validation using Zod.
 
+## 📋 Table of Contents
+
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Core Features](#-core-features)
+- [Basic Usage](#-basic-usage)
+  - [Queries (GET)](#queries-get)
+  - [Queries (POST)](#queries-post)
+  - [Mutations (POST/PUT/DELETE)](#mutations-postputdelete)
+- [Configuration](#-configuration)
+- [Advanced Features](#-advanced-features)
+  - [Nested Structure](#nested-structure)
+  - [Modular API Definitions](#modular-api-definitions)
+  - [Request Interceptors](#request-interceptors)
+  - [File Upload](#file-upload)
+  - [CSRF Protection](#csrf-protection)
+- [License](#-license)
+
 ## 📦 Installation
 
 ```bash
@@ -25,7 +42,7 @@ import { z } from 'zod';
 
 // Define your API client
 const api = createApiClient({
-  baseURL: 'https://jsonplaceholder.typicode.com',
+  baseURL: 'https://api.example.com',
   queries: {
     getUsers: {
       path: '/users',
@@ -43,23 +60,6 @@ const api = createApiClient({
         name: z.string(),
         email: z.string()
       })
-    },
-    // POST query for complex searches
-    searchUsers: {
-      method: 'POST',
-      path: '/users/search',
-      data: z.object({
-        query: z.string(),
-        filters: z.object({
-          active: z.boolean().optional(),
-          role: z.string().optional()
-        }).optional()
-      }),
-      response: z.array(z.object({
-        id: z.number(),
-        name: z.string(),
-        email: z.string()
-      }))
     }
   },
   mutations: {
@@ -75,141 +75,149 @@ const api = createApiClient({
         name: z.string(),
         email: z.string()
       })
-    },
-    updateUser: {
-      method: 'PUT',
-      path: '/users/{id}',
-      params: z.object({ id: z.number() }),
-      data: z.object({
-        name: z.string(),
-        email: z.string().email()
-      })
-    },
-    deleteUser: {
-      method: 'DELETE',
-      path: '/users/{id}',
-      params: z.object({ id: z.number() })
     }
   }
 });
 ```
 
-## 📖 Usage in Vue Components
+Use in your Vue components:
+
+```vue
+<script setup lang="ts">
+import { api } from './api';
+
+// Query - auto-loads on mount
+const { result, isLoading, errorMessage } = api.query.getUsers();
+
+// Mutation
+const { mutate, isLoading: creating } = api.mutation.createUser();
+
+async function handleCreate() {
+  await mutate({ name: 'John', email: 'john@example.com' });
+}
+</script>
+
+<template>
+  <div v-if="isLoading">Loading...</div>
+  <div v-else-if="errorMessage">Error: {{ errorMessage }}</div>
+  <ul v-else>
+    <li v-for="user in result" :key="user.id">{{ user.name }}</li>
+  </ul>
+</template>
+```
+
+## 🎯 Core Features
+
+- ✅ **Type-Safe** - Full TypeScript support with automatic type inference
+- ✅ **Zod Validation** - Built-in request/response validation
+- ✅ **Vue 3 Composition API** - Reactive state management
+- ✅ **Lightweight** - ~7kB minified (2.2kB gzipped)
+- ✅ **Auto Loading States** - Built-in loading, error, and success states
+- ✅ **Path Parameters** - Automatic path parameter replacement (`/users/{id}`)
+- ✅ **Debouncing** - Built-in request debouncing
+- ✅ **POST Queries** - Support both GET and POST for data fetching
+- ✅ **File Upload** - Multipart/form-data with nested objects
+- ✅ **CSRF Protection** - Automatic token refresh (Laravel Sanctum compatible)
+- ✅ **Modular** - Split API definitions across files
+- ✅ **Nested Structure** - Organize endpoints hierarchically
+- ✅ **Tree-Shakeable** - Only bundles what you use
 
-### Queries (GET and POST requests)
+## 📖 Basic Usage
 
-Queries support both GET and POST methods, allowing you to fetch data with complex search criteria.
+### Queries (GET)
 
-#### GET Queries
+Use queries to fetch data. They automatically load on component mount:
 
 ```vue
 <script setup lang="ts">
 import { api } from './api';
+import { ref } from 'vue';
 
-// Simple query - loads automatically on mount
+// Simple query - automatically loads data on mount
 const { result, isLoading, errorMessage } = api.query.getUsers();
 
-// Query with parameters
+// Query with parameters - reactive to parameter changes
 const userId = ref(1);
-const { result: user, isLoading: loading, refetch } = api.query.getUser({
+const { result: user, refetch } = api.query.getUser({
   params: { id: userId }
 });
 
-// Query with options
+// Query with options - customize behavior
 const { result: data } = api.query.getUsers({
   loadOnMount: true,
   debounce: 300,
-  onResult: (data) => {
-    console.log('Data loaded:', data);
-  },
-  onError: (error) => {
-    console.error('Error:', error);
-  }
+  onResult: (data) => console.log('Loaded:', data),
+  onError: (error) => console.error('Error:', error)
 });
 </script>
 
 <template>
-  <div>
-    <div v-if="isLoading">Loading...</div>
-    <div v-else-if="errorMessage">Error: {{ errorMessage }}</div>
-    <ul v-else>
-      <li v-for="user in result" :key="user.id">
-        {{ user.name }}
-      </li>
-    </ul>
-  </div>
+  <div v-if="isLoading">Loading...</div>
+  <div v-else-if="errorMessage">Error: {{ errorMessage }}</div>
+  <ul v-else>
+    <li v-for="user in result" :key="user.id">{{ user.name }}</li>
+  </ul>
 </template>
 ```
 
-#### POST Queries
+### Queries (POST)
+
+POST queries are perfect for complex searches with filters:
 
-POST queries are perfect for complex searches, filtering, or any operation that requires sending data in the request body.
+```typescript
+// API definition
+queries: {
+  searchUsers: {
+    method: 'POST',
+    path: '/users/search',
+    data: z.object({
+      query: z.string(),
+      filters: z.object({
+        active: z.boolean().optional(),
+        role: z.string().optional()
+      }).optional()
+    }),
+    response: z.array(z.object({ id: z.number(), name: z.string() }))
+  }
+}
+```
 
 ```vue
 <script setup lang="ts">
-import { api } from './api';
-import { ref } from 'vue';
-
 const searchTerm = ref('');
-
 const { result, isLoading, refetch } = api.query.searchUsers({
   data: {
     query: searchTerm.value,
-    filters: {
-      active: true,
-      role: 'admin'
-    }
+    filters: { active: true }
   },
-  loadOnMount: false,
-  onResult: (data) => {
-    console.log('Search results:', data);
-  }
+  loadOnMount: false
 });
-
-const handleSearch = () => {
-  refetch();
-};
 </script>
 
 <template>
-  <div>
-    <input v-model="searchTerm" @keyup.enter="handleSearch" />
-    <button @click="handleSearch" :disabled="isLoading">Search</button>
-
-    <div v-if="isLoading">Searching...</div>
-    <div v-else-if="result">
-      <div v-for="user in result" :key="user.id">
-        {{ user.name }}
-      </div>
-    </div>
+  <input v-model="searchTerm" @keyup.enter="refetch" />
+  <button @click="refetch" :disabled="isLoading">Search</button>
+  <div v-if="isLoading">Searching...</div>
+  <div v-else-if="result">
+    <div v-for="user in result" :key="user.id">{{ user.name }}</div>
   </div>
 </template>
 ```
 
-### Mutations (POST, PUT, DELETE)
+### Mutations (POST/PUT/DELETE)
 
 ```vue
 <script setup lang="ts">
-import { api } from './api';
-import { ref } from 'vue';
-
 const { mutate, isLoading, result, errorMessage } = api.mutation.createUser({
-  onResult: (data) => {
-    console.log('User created:', data);
-  },
-  onError: (error) => {
-    console.error('Error:', error);
-  }
+  onResult: (data) => console.log('Created:', data),
+  onError: (error) => console.error('Error:', error)
 });
 
 const name = ref('');
 const email = ref('');
 
 async function handleSubmit() {
-  await mutate({
-    name: name.value,
-    email: email.value
-  });
+  await mutate({ name: name.value, email: email.value });
 }
 </script>
 
@@ -225,30 +233,48 @@ async function handleSubmit() {
 </template>
 ```
 
-## 🎯 Features
+## ⚙️ Configuration
 
-- ✅ **Type-Safe**: Full TypeScript support with automatic type inference
-- ✅ **Zod Validation**: Built-in request/response validation
-- ✅ **Vue 3 Composition API**: Reactive state management
-- ✅ **Lightweight**: ~7kB minified (2.2kB gzipped) - optimized for production
-- ✅ **Auto Loading States**: Built-in loading, error, and success states
-- ✅ **POST Queries**: Support for both GET and POST methods in queries for complex data retrieval
-- ✅ **Modular APIs**: Merge queries and mutations from separate files with full type safety
-- ✅ **Multi-Level Nesting**: Organize queries and mutations in nested structures with full type safety
-- ✅ **File Upload**: Support for multipart/form-data with nested objects in mutations
-- ✅ **Path Parameters**: Automatic path parameter replacement
-- ✅ **Debouncing**: Built-in request debouncing
-- ✅ **CSRF Protection**: Automatic CSRF token refresh on 403/419 errors
-- ✅ **Global Error Handling**: Centralized error management
-- ✅ **Request Interceptors**: Modify requests before sending
-- ✅ **Fully Typed**: Complete type inference for params, data, and response
-- ✅ **Tree-Shakeable**: Only bundles what you use
+```typescript
+const api = createApiClient({
+  baseURL: 'https://api.example.com',
+  headers: {
+    'Authorization': 'Bearer token'
+  },
+  withCredentials: true,  // Enable cookies
+  withXSRFToken: true,    // Enable XSRF token handling
 
-## 🏗️ Multi-Level Nested Structure
+  // CSRF token refresh endpoint
+  csrfRefreshEndpoint: '/sanctum/csrf-cookie',
 
-Organize your API endpoints in a hierarchical structure for better code organization and maintainability.
+  // Global handlers
+  onBeforeRequest: async (config) => {
+    // Modify requests globally
+    const token = localStorage.getItem('token');
+    config.headers.Authorization = `Bearer ${token}`;
+    return config;
+  },
+
+  onError: (error) => {
+    // Global error handler
+    console.error('API Error:', error.message);
+  },
+
+  onZodError: (issues) => {
+    // Handle validation errors
+    console.error('Validation errors:', issues);
+  },
+
+  queries: { /* ... */ },
+  mutations: { /* ... */ }
+});
+```
+
+## 🔧 Advanced Features
+
+### Nested Structure
 
-### Basic Nested Structure
+Organize endpoints hierarchically for better code organization:
 
 ```typescript
 import { createApiClient, defineQuery, defineMutation } from 'vue-api-kit';
@@ -256,24 +282,16 @@ import { z } from 'zod';
 
 const api = createApiClient({
   baseURL: 'https://api.example.com',
-
   queries: {
-    // Organize queries by resource
     users: {
       getAll: defineQuery({
         path: '/users',
-        response: z.array(z.object({
-          id: z.number(),
-          name: z.string()
-        }))
+        response: z.array(z.object({ id: z.number(), name: z.string() }))
       }),
       getById: defineQuery({
         path: '/users/{id}',
         params: z.object({ id: z.number() }),
-        response: z.object({
-          id: z.number(),
-          name: z.string()
-        })
+        response: z.object({ id: z.number(), name: z.string() })
       }),
       search: defineQuery({
         method: 'POST',
@@ -294,13 +312,12 @@ const api = createApiClient({
       })
     }
   },
-
   mutations: {
     users: {
       create: defineMutation({
         method: 'POST',
         path: '/users',
-        data: z.object({ name: z.string(), email: z.string().email() }),
+        data: z.object({ name: z.string(), email: z.string() }),
         response: z.object({ id: z.number(), name: z.string() })
       }),
       update: defineMutation({
@@ -319,292 +336,31 @@ const api = createApiClient({
   }
 });
 
-// Usage in components:
-const { result, isLoading } = api.query.users.getAll();
-const { mutate } = api.mutation.users.create();
+// Usage
+api.query.users.getAll()
+api.mutation.users.create()
 ```
 
-### Deep Nesting
+**Benefits:** Better organization, namespace separation, improved readability, scalability.
 
-You can nest as deeply as needed for complex API structures:
+### Modular API Definitions
 
-```typescript
-const api = createApiClient({
-  baseURL: 'https://api.example.com',
-
-  queries: {
-    api: {
-      v1: {
-        admin: {
-          users: {
-            list: defineQuery({ path: '/api/v1/admin/users' }),
-            search: defineQuery({
-              method: 'POST',
-              path: '/api/v1/admin/users/search'
-            })
-          },
-          reports: {
-            daily: defineQuery({ path: '/api/v1/admin/reports/daily' }),
-            monthly: defineQuery({ path: '/api/v1/admin/reports/monthly' })
-          }
-        },
-        public: {
-          posts: {
-            list: defineQuery({ path: '/api/v1/public/posts' })
-          }
-        }
-      }
-    }
-  }
-});
-
-// Access deeply nested endpoints:
-api.query.api.v1.admin.users.list()
-api.query.api.v1.admin.reports.daily()
-api.query.api.v1.public.posts.list()
-```
-
-### Mixed Flat and Nested Structure
-
-You can combine flat and nested structures as needed:
-
-```typescript
-const api = createApiClient({
-  baseURL: 'https://api.example.com',
-
-  queries: {
-    // Flat queries
-    getStatus: defineQuery({ path: '/status' }),
-    getHealth: defineQuery({ path: '/health' }),
-
-    // Nested queries
-    users: {
-      getAll: defineQuery({ path: '/users' }),
-      getById: defineQuery({ path: '/users/{id}' })
-    },
-    posts: {
-      getAll: defineQuery({ path: '/posts' })
-    }
-  }
-});
-
-// Both flat and nested work together:
-api.query.getStatus()       // Flat
-api.query.users.getAll()    // Nested
-```
-
-### Benefits
-
-- **Better Organization**: Group related endpoints together
-- **Improved Readability**: Clear hierarchical structure reflects your API design
-- **Namespace Separation**: Prevent naming conflicts (e.g., `users.create` vs `posts.create`)
-- **Scalability**: Easy to add new endpoints without cluttering the root level
-- **Type Safety**: Full TypeScript inference throughout the nested structure
-- **Backward Compatible**: Works alongside existing flat structure
-
-## 🔧 Advanced Configuration
-
-```typescript
-const api = createApiClient({
-  baseURL: 'https://api.example.com',
-  headers: {
-    'Authorization': 'Bearer token'
-  },
-  withCredentials: true, // Enable cookies
-  withXSRFToken: true,   // Enable automatic XSRF token handling
-
-  // CSRF Token Protection
-  csrfRefreshEndpoint: '/sanctum/csrf-cookie', // Auto-refresh CSRF token on 403/419 errors
-
-  // Global handlers
-  onBeforeRequest: async (config) => {
-    // Modify request before sending
-    const token = localStorage.getItem('token');
-    config.headers.Authorization = `Bearer ${token}`;
-    return config;
-  },
-
-  onStartRequest: async () => {
-    // Called when request starts
-    console.log('Request started');
-  },
-
-  onFinishRequest: async () => {
-    // Called when request finishes (success or error)
-    console.log('Request finished');
-  },
-
-  onError: (error) => {
-    // Global error handler
-    console.error('API Error:', error.message);
-  },
-
-  onZodError: (issues) => {
-    // Handle validation errors
-    console.error('Validation errors:', issues);
-  },
-
-  queries: { /* ... */ },
-  mutations: { /* ... */ }
-});
-```
-
-## 🎯 Per-Query and Per-Mutation Request Interceptors
-
-In addition to global request interceptors, you can define `onBeforeRequest` hooks for individual queries and mutations. This is useful when you need to append specific headers or modify the request configuration for certain endpoints only.
-
-### Query-Level onBeforeRequest
-
-You can define `onBeforeRequest` in two ways for queries:
-
-**1. In the query definition:**
+Split your API definitions across multiple files:
 
+**user-api.ts**
 ```typescript
-const api = createApiClient({
-  baseURL: 'https://api.example.com',
-  queries: {
-    getUser: {
-      path: '/users/{id}',
-      params: z.object({ id: z.number() }),
-      response: z.object({ id: z.number(), name: z.string() }),
-      // Query-level interceptor
-      onBeforeRequest: async (config) => {
-        config.headers['X-Custom-Query-Header'] = 'special-value';
-        return config;
-      }
-    }
-  }
-});
-```
-
-**2. In the query options when calling it:**
-
-```typescript
-const { result, isLoading } = api.query.getUser({
-  params: { id: 1 },
-  // Runtime interceptor
-  onBeforeRequest: async (config) => {
-    const token = await getAuthToken();
-    config.headers.Authorization = `Bearer ${token}`;
-    return config;
-  }
-});
-```
-
-### Mutation-Level onBeforeRequest
-
-Similarly, you can define `onBeforeRequest` for mutations:
-
-**1. In the mutation definition:**
-
-```typescript
-const api = createApiClient({
-  baseURL: 'https://api.example.com',
-  mutations: {
-    createUser: {
-      method: 'POST',
-      path: '/users',
-      data: z.object({ name: z.string(), email: z.string() }),
-      response: z.object({ id: z.number(), name: z.string() }),
-      // Mutation-level interceptor
-      onBeforeRequest: async (config) => {
-        config.headers['X-Action'] = 'create-user';
-        return config;
-      }
-    }
-  }
-});
-```
-
-**2. In the mutation options when calling it:**
-
-```typescript
-const { mutate } = api.mutation.createUser({
-  // Runtime interceptor
-  onBeforeRequest: async (config) => {
-    const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content;
-    if (csrfToken) {
-      config.headers['X-CSRF-Token'] = csrfToken;
-    }
-    return config;
-  }
-});
-
-await mutate({ data: { name: 'John', email: 'john@example.com' } });
-```
-
-### Execution Order
-
-When multiple `onBeforeRequest` hooks are defined, they execute in the following order:
-
-1. **Global interceptor** (defined in `createApiClient` options) - Applied via axios interceptor
-2. **Query/Mutation definition interceptor** (defined in query/mutation object)
-3. **Options interceptor** (defined when calling the query/mutation)
-
-Each hook can modify the config, and later hooks can see and override changes made by earlier hooks.
-
-### Use Cases
-
-- **Authentication**: Add tokens for specific endpoints that require authentication
-- **Custom Headers**: Append API keys, correlation IDs, or feature flags for specific requests
-- **Request Transformation**: Modify request data or parameters before sending
-- **Conditional Logic**: Apply different configurations based on runtime conditions
-- **Debugging**: Add request IDs or trace headers for specific endpoints
-
-### Example: Dynamic Authorization
-
-```typescript
-const api = createApiClient({
-  baseURL: 'https://api.example.com',
-  queries: {
-    getProtectedData: {
-      path: '/protected/data',
-      response: z.object({ data: z.string() }),
-      onBeforeRequest: async (config) => {
-        // This query always needs fresh token
-        const token = await refreshAndGetToken();
-        config.headers.Authorization = `Bearer ${token}`;
-        return config;
-      }
-    },
-    getPublicData: {
-      path: '/public/data',
-      response: z.object({ data: z.string() })
-      // No onBeforeRequest needed for public endpoint
-    }
-  }
-});
-```
-
-## 🧩 Modular API Definitions
-
-For large applications, you can organize your API definitions into separate files and merge them together with full type safety.
-
-### Step 1: Define API modules in separate files
-
-**user-api.ts** - User-related queries and mutations
-```typescript
-import { z, defineQuery, defineMutation } from 'vue-api-kit';
+import { defineQuery, defineMutation } from 'vue-api-kit';
+import { z } from 'zod';
 
 export const userQueries = {
   getUsers: defineQuery({
-    method: 'GET',
     path: '/users',
-    response: z.array(z.object({
-      id: z.number(),
-      name: z.string(),
-      email: z.string().email()
-    }))
+    response: z.array(z.object({ id: z.number(), name: z.string() }))
   }),
   getUser: defineQuery({
-    method: 'GET',
     path: '/users/{id}',
     params: z.object({ id: z.number() }),
-    response: z.object({
-      id: z.number(),
-      name: z.string(),
-      email: z.string().email()
-    })
+    response: z.object({ id: z.number(), name: z.string() })
   })
 };
 
@@ -612,386 +368,130 @@ export const userMutations = {
   createUser: defineMutation({
     method: 'POST',
     path: '/users',
-    data: z.object({
-      name: z.string(),
-      email: z.string().email()
-    }),
-    response: z.object({
-      id: z.number(),
-      name: z.string(),
-      email: z.string().email()
-    })
-  }),
-  updateUser: defineMutation({
-    method: 'PUT',
-    path: '/users/{id}',
-    params: z.object({ id: z.number() }),
-    data: z.object({
-      name: z.string().optional(),
-      email: z.string().email().optional()
-    }),
-    response: z.object({
-      id: z.number(),
-      name: z.string(),
-      email: z.string().email()
-    })
-  })
-};
-```
-
-**post-api.ts** - Post-related queries and mutations
-```typescript
-import { z, defineQuery, defineMutation } from 'vue-api-kit';
-
-export const postQueries = {
-  getPosts: defineQuery({
-    method: 'GET',
-    path: '/posts',
-    response: z.array(z.object({
-      id: z.number(),
-      title: z.string(),
-      body: z.string()
-    }))
-  })
-};
-
-export const postMutations = {
-  createPost: defineMutation({
-    method: 'POST',
-    path: '/posts',
-    data: z.object({
-      title: z.string(),
-      body: z.string()
-    }),
-    response: z.object({
-      id: z.number(),
-      title: z.string(),
-      body: z.string()
-    })
+    data: z.object({ name: z.string(), email: z.string() }),
+    response: z.object({ id: z.number(), name: z.string() })
   })
 };
 ```
 
-### Step 2: Merge API definitions
-
-**api.ts** - Main API client with merged definitions
+**api.ts**
 ```typescript
 import { createApiClient, mergeQueries, mergeMutations } from 'vue-api-kit';
 import { userQueries, userMutations } from './user-api';
 import { postQueries, postMutations } from './post-api';
 
-// Approach 1: Merge queries and mutations separately
 export const api = createApiClient({
   baseURL: 'https://api.example.com',
-
-  // Merge all queries from different modules
   queries: mergeQueries(userQueries, postQueries),
-
-  // Merge all mutations from different modules
   mutations: mergeMutations(userMutations, postMutations)
 });
-
-// Now you can use all queries and mutations with full type safety!
-// api.query.getUsers()    ✓ Fully typed
-// api.query.getPosts()    ✓ Fully typed
-// api.mutation.createUser ✓ Fully typed
-// api.mutation.createPost ✓ Fully typed
 ```
 
-### Nested Structure with Modular APIs
+**Benefits:** Separation of concerns, reusability, team collaboration, full type safety.
 
-You can also use nested structures with modular API definitions:
+### Request Interceptors
 
-**user-api.ts** - User module with nested structure
-```typescript
-import { z, defineQuery, defineMutation } from 'vue-api-kit';
-
-export const userApi = {
-  queries: {
-    users: {
-      getAll: defineQuery({
-        path: '/users',
-        response: z.array(z.object({ id: z.number(), name: z.string() }))
-      }),
-      getById: defineQuery({
-        path: '/users/{id}',
-        params: z.object({ id: z.number() }),
-        response: z.object({ id: z.number(), name: z.string() })
-      })
-    }
-  },
-  mutations: {
-    users: {
-      create: defineMutation({
-        method: 'POST',
-        path: '/users',
-        data: z.object({ name: z.string() })
-      }),
-      update: defineMutation({
-        method: 'PUT',
-        path: '/users/{id}',
-        params: z.object({ id: z.number() }),
-        data: z.object({ name: z.string() })
-      })
-    }
-  }
-};
-```
-
-**post-api.ts** - Post module with nested structure
-```typescript
-import { z, defineQuery, defineMutation } from 'vue-api-kit';
-
-export const postApi = {
-  queries: {
-    posts: {
-      getAll: defineQuery({
-        path: '/posts',
-        response: z.array(z.object({ id: z.number(), title: z.string() }))
-      }),
-      getById: defineQuery({
-        path: '/posts/{id}',
-        params: z.object({ id: z.number() }),
-        response: z.object({ id: z.number(), title: z.string() })
-      })
-    }
-  },
-  mutations: {
-    posts: {
-      create: defineMutation({
-        method: 'POST',
-        path: '/posts',
-        data: z.object({ title: z.string(), content: z.string() })
-      })
-    }
-  }
-};
-```
+Add interceptors at global, definition, or runtime level:
 
-**api.ts** - Merge nested structures
 ```typescript
-import { createApiClient, mergeQueries, mergeMutations } from 'vue-api-kit';
-import { userApi } from './user-api';
-import { postApi } from './post-api';
-
-export const api = createApiClient({
+// 1. Global interceptor
+const api = createApiClient({
   baseURL: 'https://api.example.com',
-
-  // Merge nested queries from modules
-  queries: mergeQueries(userApi.queries, postApi.queries),
-
-  // Merge nested mutations from modules
-  mutations: mergeMutations(userApi.mutations, postApi.mutations)
+  onBeforeRequest: async (config) => {
+    config.headers.Authorization = `Bearer ${getToken()}`;
+    return config;
+  }
 });
 
-// Usage with nested structure:
-api.query.users.getAll()     // ✓ Fully typed
-api.query.posts.getById()    // ✓ Fully typed
-api.mutation.users.create()  // ✓ Fully typed
-api.mutation.posts.create()  // ✓ Fully typed
-```
-
-### Benefits of Modular Approach
-
-- **Separation of Concerns**: Keep related API endpoints together in dedicated files
-- **Reusability**: Import and reuse API definitions across multiple clients
-- **Team Collaboration**: Different team members can work on different API modules independently
-- **Full Type Safety**: TypeScript infers all types correctly, no loss of type information when merging
-- **No Manual Type Assertions**: Use `defineQuery()` and `defineMutation()` helpers instead of `as const`
-- **Easy Testing**: Test individual API modules in isolation
-- **Better Organization**: Manage large APIs without cluttering a single file
-
-## 📤 File Upload Example
-
-File uploads are supported in mutations using the `isMultipart` flag.
-
-```typescript
-const api = createApiClient({
-  baseURL: 'https://api.example.com',
-  mutations: {
-    uploadImage: {
-      method: 'POST',
-      path: '/upload',
-      isMultipart: true, // Enable multipart/form-data
-      response: z.object({
-        url: z.string()
-      })
+// 2. Definition-level interceptor
+queries: {
+  getUser: {
+    path: '/users/{id}',
+    onBeforeRequest: async (config) => {
+      config.headers['X-Custom-Header'] = 'value';
+      return config;
     }
   }
-});
+}
 
-// In component
-const { mutate, uploadProgress } = api.mutation.uploadImage({
-  onUploadProgress: (progress) => {
-    console.log(`Upload progress: ${progress}%`);
+// 3. Runtime interceptor
+const { result } = api.query.getUser({
+  params: { id: 1 },
+  onBeforeRequest: async (config) => {
+    config.headers.Authorization = `Bearer ${await refreshToken()}`;
+    return config;
   }
 });
-
-async function handleUpload(file: File) {
-  await mutate({ data: { file } });
-}
 ```
 
-### Nested Objects in Multipart
+**Execution order:** Global → Definition → Runtime
+
+### File Upload
 
-The multipart feature supports nested objects with automatic bracket notation flattening:
+Upload files with multipart/form-data support:
 
 ```typescript
-const api = createApiClient({
-  baseURL: 'https://api.example.com',
-  mutations: {
-    createProduct: {
-      method: 'POST',
-      path: '/products',
-      isMultipart: true,
-      response: z.object({
-        id: z.number(),
-        success: z.boolean()
-      })
-    }
+mutations: {
+  uploadImage: {
+    method: 'POST',
+    path: '/upload',
+    isMultipart: true,
+    response: z.object({ url: z.string() })
   }
-});
-
-// In component
-const { mutate } = api.mutation.createProduct();
-
-async function handleSubmit(file: File) {
-  await mutate({
-    data: {
-      code: 'PROD001',
-      name: 'Product Name',
-      description: 'Product description',
-      // Nested objects are automatically flattened with bracket notation
-      image: {
-        file_url: 'https://example.com/existing.jpg',
-        file: file
-      }
-    }
-  });
 }
 
-// The FormData will be sent as:
-// code=PROD001
-// name=Product Name
-// description=Product description
-// image[file_url]=https://example.com/existing.jpg
-// image[file]=<File>
-```
+// Usage
+const { mutate, uploadProgress } = api.mutation.uploadImage({
+  onUploadProgress: (progress) => console.log(`${progress}%`)
+});
 
-You can also use flat bracket notation directly:
+await mutate({ data: { file, name: 'avatar.jpg' } });
+```
 
+**Nested objects in multipart:**
 ```typescript
 await mutate({
   data: {
-    'image[file]': file,
-    'image[file_url]': 'https://example.com/existing.jpg',
-    code: 'PROD001'
+    name: 'Product',
+    image: {
+      file: file,              // Sent as: image[file]
+      file_url: 'url'          // Sent as: image[file_url]
+    }
   }
 });
 ```
 
-Both approaches work seamlessly together, giving you flexibility in how you structure your data.
-
-## 🔒 CSRF Token Protection
-
-The client includes built-in CSRF token protection, perfect for Laravel Sanctum or similar CSRF-based authentication systems.
+### CSRF Protection
 
-### How it works
-
-**Automatic XSRF Token Handling:**
-1. Set `withCredentials: true` to enable cookie-based authentication
-2. Set `withXSRFToken: true` to enable automatic XSRF token handling
-3. Axios automatically reads `XSRF-TOKEN` cookie and sends it as `X-XSRF-TOKEN` header
-4. This satisfies Laravel Sanctum's CSRF protection requirements
-
-**Automatic CSRF Refresh:**
-1. Detects CSRF errors (403 or 419 status codes)
-2. Calls the CSRF refresh endpoint to get a new token
-3. Retries the original request automatically with the fresh token
-4. Prevents infinite loops and race conditions
-
-### Configuration
+Built-in CSRF token protection (Laravel Sanctum compatible):
 
 ```typescript
 const api = createApiClient({
   baseURL: 'https://api.example.com',
-  withCredentials: true,   // Enable cookies for authentication
-  withXSRFToken: true,     // Enable automatic XSRF token handling
-  csrfRefreshEndpoint: '/sanctum/csrf-cookie', // Laravel Sanctum endpoint
-  queries: { /* ... */ },
+  withCredentials: true,              // Enable cookies
+  withXSRFToken: true,                // Enable XSRF token handling
+  csrfRefreshEndpoint: '/sanctum/csrf-cookie',  // Refresh endpoint
   mutations: { /* ... */ }
 });
 ```
 
-### Use Case: Laravel Sanctum
-
-```typescript
-// api.ts
-import { createApiClient } from 'vue-api-kit';
-import { z } from 'zod';
-
-export const api = createApiClient({
-  baseURL: 'https://api.example.com',
-  withCredentials: true,   // Enables cookies
-  withXSRFToken: true,     // Enables automatic XSRF-TOKEN header
-  csrfRefreshEndpoint: '/sanctum/csrf-cookie', // Laravel's CSRF endpoint  mutations: {
-    login: {
-      method: 'POST',
-      path: '/login',
-      data: z.object({
-        email: z.string().email(),
-        password: z.string()
-      }),
-      response: z.object({
-        user: z.object({
-          id: z.number(),
-          name: z.string(),
-          email: z.string()
-        })
-      })
-    },
-    createPost: {
-      method: 'POST',
-      path: '/posts',
-      data: z.object({
-        title: z.string(),
-        content: z.string()
-      })
-    }
-  }
-});
+**How it works:**
+1. Axios automatically reads `XSRF-TOKEN` cookie
+2. Sends it as `X-XSRF-TOKEN` header
+3. On 403/419 errors, refreshes CSRF token automatically
+4. Retries the original request
+
+**Laravel CORS config:**
+```php
+// config/cors.php
+'supports_credentials' => true,
+'allowed_origins' => ['http://localhost:5173'],
 ```
 
-### Benefits
-
-- ✅ **Separate Options**: `withCredentials` and `withXSRFToken` can be configured independently
-- ✅ **Built-in XSRF Support**: Axios `withXSRFToken` handles token automatically
-- ✅ **Automatic Recovery**: No manual token refresh needed
-- ✅ **Seamless UX**: Users don't experience authentication errors
-- ✅ **Race Condition Safe**: Multiple simultaneous requests share the same refresh
-- ✅ **Infinite Loop Prevention**: Won't retry the CSRF endpoint itself
-- ✅ **Laravel Sanctum Compatible**: Works perfectly with Laravel's SPA authentication
-
-### Important Notes
-
-1. **Two separate options**:
-   - `withCredentials: true` - Enables sending cookies with requests
-   - `withXSRFToken: true` - Enables automatic XSRF token header handling
-2. **Cookie Domain**: Ensure your API sets cookies with the correct domain (e.g., `.localhost` for local development)
-3. **CORS Configuration**: Your Laravel backend must allow credentials:
-   ```php
-   // config/cors.php
-   'supports_credentials' => true,
-   'allowed_origins' => ['http://localhost:5173'],
-   ```
-
-
-
 ## 📝 License
 
 MIT
 
 ## 👤 Author
 
-MelvishNiz - [GitHub](https://github.com/MelvishNiz)
-
+**MelvishNiz** - [GitHub](https://github.com/MelvishNiz)

package/dist/index.js

@@ -12,19 +12,20 @@ function X(e) {
   return e && typeof e == "object" && e !== null && typeof e.path == "string" && typeof e.method == "string";
 }
 function F(e, a, h = "") {
-  if (a instanceof File || a instanceof Blob)
-    e.append(h, a);
-  else if (Array.isArray(a))
-    a.forEach((l) => {
-      l instanceof File || l instanceof Blob ? e.append(h, l) : typeof l == "object" && l !== null ? F(e, l, h) : e.append(h, String(l));
-    });
-  else if (typeof a == "object" && a !== null)
-    for (const [l, B] of Object.entries(a)) {
-      const k = h ? `${h}[${l}]` : l;
-      F(e, B, k);
-    }
-  else
-    e.append(h, String(a));
+  if (a !== void 0)
+    if (a instanceof File || a instanceof Blob)
+      e.append(h, a);
+    else if (Array.isArray(a))
+      a.forEach((l) => {
+        l instanceof File || l instanceof Blob ? e.append(h, l) : typeof l == "object" && l !== null ? F(e, l, h) : l !== void 0 && e.append(h, String(l));
+      });
+    else if (typeof a == "object" && a !== null)
+      for (const [l, B] of Object.entries(a)) {
+        const k = h ? `${h}[${l}]` : l;
+        F(e, B, k);
+      }
+    else
+      e.append(h, String(a));
 }
 function K(e) {
   const a = U.create({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vue-api-kit",
   "type": "module",
-  "version": "1.10.8",
+  "version": "1.10.9",
   "description": "A powerful and flexible API client for Vue 3 applications, built with TypeScript and Zod for type-safe API interactions.",
   "keywords": [
     "vue3",