vue-api-kit 1.7.0 → 1.8.1

package/README.md

@@ -290,6 +290,133 @@ const api = createApiClient({
 });
 ```
 
+## 🎯 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:**
+
+```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.

package/dist/core/types.d.ts

@@ -42,6 +42,7 @@ export interface ApiQuery<TParams extends ZodType<any> | undefined = ZodType<any
     params?: TParams;
     data?: TData;
     response?: TResponse;
+    onBeforeRequest?: (config: InternalAxiosRequestConfig<any>) => Promise<any> | void | any;
 }
 /**
  * Defines a mutation (POST, PUT, PATCH, DELETE) endpoint configuration
@@ -63,6 +64,7 @@ export interface ApiMutation<TData extends ZodType<any> | undefined = ZodType<an
     data?: TData;
     response?: TResponse;
     isMultipart?: boolean;
+    onBeforeRequest?: (config: InternalAxiosRequestConfig<any>) => Promise<any> | void | any;
 }
 /**
  * Configuration options for creating an API client
@@ -126,6 +128,7 @@ export interface UseQueryOptions<TParams = any, TData = any, TResult = any> {
     onResult?: (result: TResult) => void;
     onError?: (error: AxiosError | ZodError | Error) => void;
     onZodError?: (issues: Omit<$ZodIssue, "input">[]) => void;
+    onBeforeRequest?: (config: InternalAxiosRequestConfig<any>) => Promise<any> | void | any;
 }
 /**
  * Options for configuring a mutation hook
@@ -142,6 +145,7 @@ export interface UseMutationOptions<TResult = any> {
     onError?: (error: AxiosError | ZodError | Error) => void;
     onZodError?: (issues: Omit<$ZodIssue, "input">[]) => void;
     onUploadProgress?: (progress: number) => void;
+    onBeforeRequest?: (config: InternalAxiosRequestConfig<any>) => Promise<any> | void | any;
 }
 /**
  * Return type from a query hook

package/dist/index.js

@@ -1,188 +1,204 @@
 import { ZodError as S } from "zod";
 import * as U from "zod";
 import L, { AxiosError as F } from "axios";
-import { AxiosError as H } from "axios";
-import { nextTick as T, ref as m, onMounted as k, watch as x, onBeforeUnmount as N } from "vue";
-import { debounce as Z } from "lodash-es";
-function z(r) {
-  const h = L.create({
-    baseURL: r.baseURL,
+import { AxiosError as K } from "axios";
+import { nextTick as T, ref as m, onMounted as k, watch as Z, onBeforeUnmount as x } from "vue";
+import { debounce as N } from "lodash-es";
+function V(s) {
+  const R = L.create({
+    baseURL: s.baseURL,
     headers: {
       "Content-Type": "application/json",
       Accept: "application/json",
-      ...r.headers
+      ...s.headers
     },
-    withCredentials: r.withCredentials ?? !1,
-    withXSRFToken: r.withXSRFToken ?? !1
+    withCredentials: s.withCredentials ?? !1,
+    withXSRFToken: s.withXSRFToken ?? !1
   });
-  let b = !1, q = null;
-  r.onBeforeRequest && h.interceptors.request.use(
+  let C = !1, j = null;
+  s.onBeforeRequest && R.interceptors.request.use(
     async (e) => {
       try {
-        return await r.onBeforeRequest(e) || e;
-      } catch (s) {
-        return Promise.reject(s);
+        return await s.onBeforeRequest(e) || e;
+      } catch (r) {
+        return Promise.reject(r);
       }
     },
     (e) => Promise.reject(e)
-  ), r.onStartRequest && h.interceptors.request.use(
+  ), s.onStartRequest && R.interceptors.request.use(
     async (e) => {
       try {
-        return await r.onStartRequest(), e;
-      } catch (s) {
-        return Promise.reject(s);
+        return await s.onStartRequest(), e;
+      } catch (r) {
+        return Promise.reject(r);
       }
     },
     (e) => Promise.reject(e)
-  ), r.onFinishRequest && h.interceptors.response.use(
-    (e) => (r.onFinishRequest(), e),
-    (e) => (r.onFinishRequest(), Promise.reject(e))
-  ), h.interceptors.request.use((e) => {
+  ), s.onFinishRequest && R.interceptors.response.use(
+    (e) => (s.onFinishRequest(), e),
+    (e) => (s.onFinishRequest(), Promise.reject(e))
+  ), R.interceptors.request.use((e) => {
     if (!e.url) return e;
-    const s = (a) => {
+    const r = (a) => {
       if (a)
-        for (const [t, v] of Object.entries(a)) {
-          const l = `{${t}}`;
-          e.url.includes(l) && (e.url = e.url.replace(
-            l,
-            encodeURIComponent(String(v))
+        for (const [t, p] of Object.entries(a)) {
+          const f = `{${t}}`;
+          e.url.includes(f) && (e.url = e.url.replace(
+            f,
+            encodeURIComponent(String(p))
           ), delete a[t]);
         }
     };
-    return e.method !== "get" && e.data?.params && s(e.data.params), s(e.params), e;
-  }), r.csrfRefreshEndpoint && h.interceptors.response.use(
+    return e.method !== "get" && e.data?.params && r(e.data.params), r(e.params), e;
+  }), s.csrfRefreshEndpoint && R.interceptors.response.use(
     (e) => e,
     async (e) => {
-      const s = e.config;
-      if (s?.url === r.csrfRefreshEndpoint)
+      const r = e.config;
+      if (r?.url === s.csrfRefreshEndpoint)
         return Promise.reject(e);
-      if (e.response && (e.response.status === 403 || e.response.status === 419) && !s?._retry) {
-        s._retry = !0;
+      if (e.response && (e.response.status === 403 || e.response.status === 419) && !r?._retry) {
+        r._retry = !0;
         try {
-          return b && q ? await q : (b = !0, q = h.get(r.csrfRefreshEndpoint).then(() => {
-            b = !1, q = null;
-          }), await q), h.request(s);
+          return C && j ? await j : (C = !0, j = R.get(s.csrfRefreshEndpoint).then(() => {
+            C = !1, j = null;
+          }), await j), R.request(r);
         } catch (a) {
-          return b = !1, q = null, Promise.reject(a);
+          return C = !1, j = null, Promise.reject(a);
         }
       }
       return Promise.reject(e);
     }
-  ), h.interceptors.response.use(
+  ), R.interceptors.response.use(
     (e) => e,
     (e) => (T(() => {
       e.code;
     }), Promise.reject(e))
   );
-  const C = r.queries ?? {}, M = {};
-  for (const e in C) {
-    const s = C[e];
-    s && (M[e] = (a) => {
+  const P = s.queries ?? {}, M = {};
+  for (const e in P) {
+    const r = P[e];
+    r && (M[e] = (a) => {
       let t;
-      a && typeof a == "object" && ("loadOnMount" in a || "debounce" in a || "onResult" in a || "onError" in a || "data" in a ? t = a : t = { params: a });
-      const v = m(), l = m(), R = m(), g = m(!1), y = m(!1), P = m(!0);
-      let j = new AbortController();
-      const u = () => {
-        j?.abort(), j = new AbortController();
-      }, c = async () => {
-        g.value && u(), g.value = !0, l.value = void 0;
+      a && typeof a == "object" && ("loadOnMount" in a || "debounce" in a || "onResult" in a || "onError" in a || "onZodError" in a || "onBeforeRequest" in a || "data" in a ? t = a : t = { params: a });
+      const p = m(), f = m(), g = m(), E = m(!1), y = m(!1), A = m(!0);
+      let b = new AbortController();
+      const i = () => {
+        b?.abort(), b = new AbortController();
+      }, l = async () => {
+        E.value && i(), E.value = !0, f.value = void 0;
         try {
-          s.params && t?.params && s.params.parse(t.params);
+          r.params && t?.params && r.params.parse(t.params);
           let o = t?.data;
-          s.data && o && s.data.parse(o);
-          const f = {
-            method: s.method ?? "GET",
-            url: s.path,
+          r.data && o && r.data.parse(o);
+          const u = {
+            method: r.method ?? "GET",
+            url: r.path,
             params: t?.params,
-            signal: j.signal
+            signal: b.signal
           };
-          s.method === "POST" && o && (f.data = o);
-          const n = await h.request(f), i = s.response ? s.response.parse(n.data) : n.data;
-          v.value = i, t?.onResult?.(i);
+          if (r.method === "POST" && o && (u.data = o), r.onBeforeRequest) {
+            const c = await r.onBeforeRequest(u);
+            c !== void 0 && Object.assign(u, c);
+          }
+          if (t?.onBeforeRequest) {
+            const c = await t.onBeforeRequest(u);
+            c !== void 0 && Object.assign(u, c);
+          }
+          const h = await R.request(u), n = r.response ? r.response.parse(h.data) : h.data;
+          p.value = n, t?.onResult?.(n);
         } catch (o) {
           if (o instanceof F) {
             if (o.code !== "ERR_CANCELED") {
-              const f = o.response?.data?.message || o.message || "An error occurred", n = o.response?.status, i = o.code, p = o.response?.data;
-              l.value = f, t?.onError?.(o), r.onErrorRequest?.({ message: f, status: n, code: i, data: p });
+              const u = o.response?.data?.message || o.message || "An error occurred", h = o.response?.status, n = o.code, c = o.response?.data;
+              f.value = u, t?.onError?.(o), s.onErrorRequest?.({ message: u, status: h, code: n, data: c });
             }
           } else if (o instanceof S) {
-            R.value = o.issues || [];
-            const n = `Validation error: ${R.value.map(
-              (i) => `${i.path.join(".")}: ${i.message}`
+            g.value = o.issues || [];
+            const h = `Validation error: ${g.value.map(
+              (n) => `${n.path.join(".")}: ${n.message}`
             ).join(", ")}`;
-            l.value = n, t?.onError?.(o), t?.onZodError?.(R.value), r.onErrorRequest?.({ message: n, code: "VALIDATION_ERROR" }), r.onZodError && r.onZodError(R.value);
+            f.value = h, t?.onError?.(o), t?.onZodError?.(g.value), s.onErrorRequest?.({ message: h, code: "VALIDATION_ERROR" }), s.onZodError && s.onZodError(g.value);
           } else {
-            const f = o.message || "An error occurred";
-            l.value = f, t?.onError?.(f), r.onErrorRequest?.({ message: f });
+            const u = o.message || "An error occurred";
+            f.value = u, t?.onError?.(u), s.onErrorRequest?.({ message: u });
           }
         } finally {
-          g.value = !1, y.value = !0;
+          E.value = !1, y.value = !0;
         }
-      }, E = t?.debounce ? Z(c, t.debounce) : c;
+      }, v = t?.debounce ? N(l, t.debounce) : l;
       let d = null;
       return (t?.params || t?.data) && (k(() => {
-        d && d(), d = x(
+        d && d(), d = Z(
           () => JSON.stringify({ params: t.params, data: t.data }),
           () => {
-            E();
+            v();
           },
           { immediate: !1 }
         );
-      }), N(() => {
-        d && d(), j?.abort();
-      })), (t?.loadOnMount === void 0 || t.loadOnMount) && !y.value && (P.value ? (P.value = !1, c()) : E()), { result: v, errorMessage: l, zodErrors: R, isLoading: g, isDone: y, refetch: c };
+      }), x(() => {
+        d && d(), b?.abort();
+      })), (t?.loadOnMount === void 0 || t.loadOnMount) && !y.value && (A.value ? (A.value = !1, l()) : v()), { result: p, errorMessage: f, zodErrors: g, isLoading: E, isDone: y, refetch: l };
     });
   }
-  const w = r.mutations ?? {}, D = {};
-  for (const e in w) {
-    const s = w[e];
-    s && (D[e] = (a) => {
-      const t = m(), v = m(), l = m(), R = m(!1), g = m(!1), y = m(0);
-      return { result: t, errorMessage: v, zodErrors: l, isLoading: R, isDone: g, uploadProgress: y, mutate: async (j) => {
-        if (!R.value) {
-          R.value = !0, v.value = void 0, y.value = 0;
+  const B = s.mutations ?? {}, D = {};
+  for (const e in B) {
+    const r = B[e];
+    r && (D[e] = (a) => {
+      const t = m(), p = m(), f = m(), g = m(!1), E = m(!1), y = m(0);
+      return { result: t, errorMessage: p, zodErrors: f, isLoading: g, isDone: E, uploadProgress: y, mutate: async (b) => {
+        if (!g.value) {
+          g.value = !0, p.value = void 0, y.value = 0;
           try {
-            const { data: u = {}, params: c } = j ?? {};
-            let E = u ?? {}, d = {};
-            if (s.isMultipart) {
+            const { data: i = {}, params: l } = b ?? {};
+            let v = i ?? {}, d = {};
+            if (r.isMultipart) {
               const n = new FormData();
-              for (const [i, p] of Object.entries(u))
-                p instanceof File || p instanceof Blob ? n.append(i, p) : Array.isArray(p) ? p.forEach((A) => {
-                  A instanceof File || A instanceof Blob ? n.append(i, A) : n.append(i, JSON.stringify(A));
-                }) : typeof p == "object" && p !== null ? n.append(i, JSON.stringify(p)) : n.append(i, String(p));
-              E = n, d["Content-Type"] = "multipart/form-data";
-            } else s.data && s.data.parse(u);
-            s.params && c && s.params.parse(c);
-            const o = await h.request({
-              method: s.method,
-              url: s.path,
-              data: E,
-              params: c,
+              for (const [c, q] of Object.entries(i))
+                q instanceof File || q instanceof Blob ? n.append(c, q) : Array.isArray(q) ? q.forEach((w) => {
+                  w instanceof File || w instanceof Blob ? n.append(c, w) : n.append(c, JSON.stringify(w));
+                }) : typeof q == "object" && q !== null ? n.append(c, JSON.stringify(q)) : n.append(c, String(q));
+              v = n, d["Content-Type"] = "multipart/form-data";
+            } else r.data && r.data.parse(i);
+            r.params && l && r.params.parse(l);
+            const o = {
+              method: r.method,
+              url: r.path,
+              data: v,
+              params: l,
               headers: d,
               onUploadProgress: (n) => {
                 if (n.total) {
-                  const i = Math.round(n.loaded * 100 / n.total);
-                  y.value = i, a?.onUploadProgress?.(i);
+                  const c = Math.round(n.loaded * 100 / n.total);
+                  y.value = c, a?.onUploadProgress?.(c);
                 }
               }
-            }), f = s.response ? s.response.parse(o.data) : o.data;
-            t.value = f, a?.onResult?.(f);
-          } catch (u) {
-            if (u instanceof F) {
-              const c = u.response?.data?.message || u.message || "An error occurred", E = u.response?.status, d = u.code;
-              v.value = c, a?.onError?.(u), r.onErrorRequest?.({ message: c, status: E, code: d });
-            } else if (u instanceof S) {
-              l.value = u.issues || [];
-              const E = `Validation error: ${l.value.map(
+            };
+            if (r.onBeforeRequest) {
+              const n = await r.onBeforeRequest(o);
+              n !== void 0 && Object.assign(o, n);
+            }
+            if (a?.onBeforeRequest) {
+              const n = await a.onBeforeRequest(o);
+              n !== void 0 && Object.assign(o, n);
+            }
+            const u = await R.request(o), h = r.response ? r.response.parse(u.data) : u.data;
+            t.value = h, a?.onResult?.(h);
+          } catch (i) {
+            if (i instanceof F) {
+              const l = i.response?.data?.message || i.message || "An error occurred", v = i.response?.status, d = i.code;
+              p.value = l, a?.onError?.(i), s.onErrorRequest?.({ message: l, status: v, code: d });
+            } else if (i instanceof S) {
+              f.value = i.issues || [];
+              const v = `Validation error: ${f.value.map(
                 (d) => `${d.path.join(".")}: ${d.message}`
               ).join(", ")}`;
-              v.value = E, a?.onError?.(u), a?.onZodError?.(l.value), r.onErrorRequest?.({ message: E, code: "VALIDATION_ERROR" }), r.onZodError && r.onZodError(l.value);
+              p.value = v, a?.onError?.(i), a?.onZodError?.(f.value), s.onErrorRequest?.({ message: v, code: "VALIDATION_ERROR" }), s.onZodError && s.onZodError(f.value);
             } else {
-              const c = u.message || "An error occurred";
-              v.value = c, a?.onError?.(u), r.onErrorRequest?.({ message: c });
+              const l = i.message || "An error occurred";
+              p.value = l, a?.onError?.(i), s.onErrorRequest?.({ message: l });
             }
           } finally {
-            R.value = !1, g.value = !0;
+            g.value = !1, E.value = !0;
           }
         }
       } };
@@ -193,24 +209,24 @@ function z(r) {
     mutation: D
   };
 }
-function V(r) {
-  return r;
+function J(s) {
+  return s;
 }
-function J(r) {
-  return r;
+function Q(s) {
+  return s;
 }
-function Q(...r) {
-  return Object.assign({}, ...r);
+function W(...s) {
+  return Object.assign({}, ...s);
 }
-function W(...r) {
-  return Object.assign({}, ...r);
+function X(...s) {
+  return Object.assign({}, ...s);
 }
 export {
-  H as AxiosError,
-  z as createApiClient,
-  J as defineMutation,
-  V as defineQuery,
-  W as mergeMutations,
-  Q as mergeQueries,
+  K as AxiosError,
+  V as createApiClient,
+  Q as defineMutation,
+  J as defineQuery,
+  X as mergeMutations,
+  W as mergeQueries,
   U as z
 };

package/package.json

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