api-core-lib 3.3.2 → 4.3.3

package/dist/index.d.mts

@@ -61,6 +61,7 @@ interface RequestConfig extends AxiosRequestConfig {
     cancelTokenKey?: string;
     onUploadProgress?: (progressEvent: AxiosProgressEvent) => void;
     onDownloadProgress?: (progressEvent: AxiosProgressEvent) => void;
+    isPublic?: boolean;
 }
 /**
  * يمثل خيارات الاستعلام للترقيم والبحث والفرز.
@@ -75,19 +76,6 @@ interface PaginateQueryOptions {
     }[];
     filter?: Record<string, any>;
 }
-/**
- * واجهة لتهيئة الهوك `useApi`.
- * @template T نوع البيانات التي يتعامل معها الهوك.
- */
-interface UseApiConfig<T> {
-    endpoint: string;
-    initialData?: T | T[];
-    initialQuery?: PaginateQueryOptions;
-    enabled?: boolean;
-    refetchAfterChange?: boolean;
-    onSuccess?: (message: string, data?: T) => void;
-    onError?: (message: string, error?: ApiError) => void;
-}
 /**
  * واجهة لتخصيص عملية تجديد التوكن بشكل كامل.
  */
@@ -174,6 +162,49 @@ interface StandardResponse<T> {
     message?: string;
     validationErrors?: ValidationError[];
 }
+/**
+ * NEW: واجهة استعلام مرنة تسمح بالبارامترات القياسية (للفلترة والترقيم)
+ * بالإضافة إلى أي بارامترات مخصصة أخرى عبر الـ index signature.
+ * @example
+ * { page: 1, limit: 10, search: 'term', status: 'published', authorId: 123 }
+ */
+interface QueryOptions {
+    page?: number;
+    limit?: number;
+    search?: string;
+    sortBy?: {
+        key: string;
+        direction: 'asc' | 'desc';
+    }[];
+    filter?: Record<string, any>;
+    [key: string]: any;
+}
+/**
+ * NEW: واجهة لتمرير خيارات إضافية لدوال الأكشن (create, update, remove).
+ */
+interface ActionOptions {
+    /**
+     * يسمح لك بتجاوز الـ endpoint الافتراضي المحدد في الهوك.
+     * مفيد لإرسال طلبات لنقاط نهاية متخصصة.
+     * @example
+     * // لتحديث عنصر وتغيير حالته عبر مسار مختلف
+     * update('123', { status: 'active' }, { endpoint: '/items/123/activate' })
+     */
+    endpoint?: string;
+}
+/**
+ * واجهة لتهيئة الهوك `useApi`.
+ * @template T نوع البيانات التي يتعامل معها الهوك.
+ */
+interface UseApiConfig<T> {
+    endpoint: string;
+    initialData?: T | T[];
+    initialQuery?: QueryOptions;
+    enabled?: boolean;
+    refetchAfterChange?: boolean;
+    onSuccess?: (message: string, data?: T) => void;
+    onError?: (message: string, error?: ApiError) => void;
+}
 
 /**
  * @file src/core/client.ts
@@ -185,12 +216,13 @@ interface StandardResponse<T> {
 
 declare function createApiClient(config: ApiClientConfig): AxiosInstance;
 
+type CrudRequestConfig = RequestConfig & ActionOptions;
 declare function createApiServices<T>(axiosInstance: AxiosInstance, endpoint: string): {
     get: (id?: string, config?: RequestConfig) => Promise<StandardResponse<T | T[]>>;
     getWithQuery: (query: string, config?: RequestConfig) => Promise<StandardResponse<T[]>>;
-    post: (data: Partial<T>, config?: RequestConfig) => Promise<StandardResponse<T>>;
-    patch: (id: string, data: Partial<T>, config?: RequestConfig) => Promise<StandardResponse<T>>;
-    remove: (id: string, config?: RequestConfig) => Promise<StandardResponse<any>>;
+    post: (data: Partial<T>, config?: CrudRequestConfig) => Promise<StandardResponse<T>>;
+    patch: (id: string, data: Partial<T>, config?: CrudRequestConfig) => Promise<StandardResponse<T>>;
+    remove: (id: string, config?: CrudRequestConfig) => Promise<StandardResponse<any>>;
 };
 
 /**
@@ -201,7 +233,13 @@ declare function createApiServices<T>(axiosInstance: AxiosInstance, endpoint: st
  * بالإضافة إلى دوال التحقق من الأنواع (type guards).
  */
 
-declare function buildPaginateQuery(query: PaginateQueryOptions): string;
+/**
+ * يبني سلسلة استعلام (query string) من كائن خيارات مرن.
+ * يتعامل مع البارامترات القياسية والمخصصة.
+ * @param query - كائن من نوع QueryOptions.
+ * @returns سلسلة استعلام جاهزة للإضافة للرابط.
+ */
+declare function buildPaginateQuery(query: QueryOptions): string;
 
 /**
  * Defines a single custom API action.
@@ -263,14 +301,14 @@ declare function useApi<T extends {
     state: StandardResponse<T | T[]>;
     setState: react.Dispatch<react.SetStateAction<StandardResponse<T | T[]>>>;
     actions: {
-        fetch: () => Promise<void>;
-        create: (newItem: Partial<T>) => Promise<StandardResponse<T>>;
-        update: (id: string, updatedItem: Partial<T>) => Promise<StandardResponse<T>>;
-        remove: (id: string) => Promise<StandardResponse<any>>;
+        fetch: (options?: QueryOptions) => Promise<void>;
+        create: (newItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
+        update: (id: string, updatedItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
+        remove: (id: string, options?: ActionOptions) => Promise<StandardResponse<any>>;
     };
     query: {
-        options: PaginateQueryOptions;
-        setOptions: react.Dispatch<react.SetStateAction<PaginateQueryOptions>>;
+        options: QueryOptions;
+        setOptions: react.Dispatch<react.SetStateAction<QueryOptions>>;
         setPage: (page: number) => void;
         setLimit: (limit: number) => void;
         setSearchTerm: (search: string) => void;
@@ -279,8 +317,9 @@ declare function useApi<T extends {
             direction: "asc" | "desc";
         }[]) => void;
         setFilters: (filter: Record<string, any>) => void;
+        setQueryParam: (key: string, value: any) => void;
         reset: () => void;
     };
 };
 
-export { type ApiClientConfig, type ApiError, type ApiResponse, type PaginateQueryOptions, type PaginationMeta, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiConfig, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi };
+export { type ActionOptions, type ApiClientConfig, type ApiError, type ApiResponse, type PaginateQueryOptions, type PaginationMeta, type QueryOptions, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiConfig, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi };

package/dist/index.d.ts

@@ -61,6 +61,7 @@ interface RequestConfig extends AxiosRequestConfig {
     cancelTokenKey?: string;
     onUploadProgress?: (progressEvent: AxiosProgressEvent) => void;
     onDownloadProgress?: (progressEvent: AxiosProgressEvent) => void;
+    isPublic?: boolean;
 }
 /**
  * يمثل خيارات الاستعلام للترقيم والبحث والفرز.
@@ -75,19 +76,6 @@ interface PaginateQueryOptions {
     }[];
     filter?: Record<string, any>;
 }
-/**
- * واجهة لتهيئة الهوك `useApi`.
- * @template T نوع البيانات التي يتعامل معها الهوك.
- */
-interface UseApiConfig<T> {
-    endpoint: string;
-    initialData?: T | T[];
-    initialQuery?: PaginateQueryOptions;
-    enabled?: boolean;
-    refetchAfterChange?: boolean;
-    onSuccess?: (message: string, data?: T) => void;
-    onError?: (message: string, error?: ApiError) => void;
-}
 /**
  * واجهة لتخصيص عملية تجديد التوكن بشكل كامل.
  */
@@ -174,6 +162,49 @@ interface StandardResponse<T> {
     message?: string;
     validationErrors?: ValidationError[];
 }
+/**
+ * NEW: واجهة استعلام مرنة تسمح بالبارامترات القياسية (للفلترة والترقيم)
+ * بالإضافة إلى أي بارامترات مخصصة أخرى عبر الـ index signature.
+ * @example
+ * { page: 1, limit: 10, search: 'term', status: 'published', authorId: 123 }
+ */
+interface QueryOptions {
+    page?: number;
+    limit?: number;
+    search?: string;
+    sortBy?: {
+        key: string;
+        direction: 'asc' | 'desc';
+    }[];
+    filter?: Record<string, any>;
+    [key: string]: any;
+}
+/**
+ * NEW: واجهة لتمرير خيارات إضافية لدوال الأكشن (create, update, remove).
+ */
+interface ActionOptions {
+    /**
+     * يسمح لك بتجاوز الـ endpoint الافتراضي المحدد في الهوك.
+     * مفيد لإرسال طلبات لنقاط نهاية متخصصة.
+     * @example
+     * // لتحديث عنصر وتغيير حالته عبر مسار مختلف
+     * update('123', { status: 'active' }, { endpoint: '/items/123/activate' })
+     */
+    endpoint?: string;
+}
+/**
+ * واجهة لتهيئة الهوك `useApi`.
+ * @template T نوع البيانات التي يتعامل معها الهوك.
+ */
+interface UseApiConfig<T> {
+    endpoint: string;
+    initialData?: T | T[];
+    initialQuery?: QueryOptions;
+    enabled?: boolean;
+    refetchAfterChange?: boolean;
+    onSuccess?: (message: string, data?: T) => void;
+    onError?: (message: string, error?: ApiError) => void;
+}
 
 /**
  * @file src/core/client.ts
@@ -185,12 +216,13 @@ interface StandardResponse<T> {
 
 declare function createApiClient(config: ApiClientConfig): AxiosInstance;
 
+type CrudRequestConfig = RequestConfig & ActionOptions;
 declare function createApiServices<T>(axiosInstance: AxiosInstance, endpoint: string): {
     get: (id?: string, config?: RequestConfig) => Promise<StandardResponse<T | T[]>>;
     getWithQuery: (query: string, config?: RequestConfig) => Promise<StandardResponse<T[]>>;
-    post: (data: Partial<T>, config?: RequestConfig) => Promise<StandardResponse<T>>;
-    patch: (id: string, data: Partial<T>, config?: RequestConfig) => Promise<StandardResponse<T>>;
-    remove: (id: string, config?: RequestConfig) => Promise<StandardResponse<any>>;
+    post: (data: Partial<T>, config?: CrudRequestConfig) => Promise<StandardResponse<T>>;
+    patch: (id: string, data: Partial<T>, config?: CrudRequestConfig) => Promise<StandardResponse<T>>;
+    remove: (id: string, config?: CrudRequestConfig) => Promise<StandardResponse<any>>;
 };
 
 /**
@@ -201,7 +233,13 @@ declare function createApiServices<T>(axiosInstance: AxiosInstance, endpoint: st
  * بالإضافة إلى دوال التحقق من الأنواع (type guards).
  */
 
-declare function buildPaginateQuery(query: PaginateQueryOptions): string;
+/**
+ * يبني سلسلة استعلام (query string) من كائن خيارات مرن.
+ * يتعامل مع البارامترات القياسية والمخصصة.
+ * @param query - كائن من نوع QueryOptions.
+ * @returns سلسلة استعلام جاهزة للإضافة للرابط.
+ */
+declare function buildPaginateQuery(query: QueryOptions): string;
 
 /**
  * Defines a single custom API action.
@@ -263,14 +301,14 @@ declare function useApi<T extends {
     state: StandardResponse<T | T[]>;
     setState: react.Dispatch<react.SetStateAction<StandardResponse<T | T[]>>>;
     actions: {
-        fetch: () => Promise<void>;
-        create: (newItem: Partial<T>) => Promise<StandardResponse<T>>;
-        update: (id: string, updatedItem: Partial<T>) => Promise<StandardResponse<T>>;
-        remove: (id: string) => Promise<StandardResponse<any>>;
+        fetch: (options?: QueryOptions) => Promise<void>;
+        create: (newItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
+        update: (id: string, updatedItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
+        remove: (id: string, options?: ActionOptions) => Promise<StandardResponse<any>>;
     };
     query: {
-        options: PaginateQueryOptions;
-        setOptions: react.Dispatch<react.SetStateAction<PaginateQueryOptions>>;
+        options: QueryOptions;
+        setOptions: react.Dispatch<react.SetStateAction<QueryOptions>>;
         setPage: (page: number) => void;
         setLimit: (limit: number) => void;
         setSearchTerm: (search: string) => void;
@@ -279,8 +317,9 @@ declare function useApi<T extends {
             direction: "asc" | "desc";
         }[]) => void;
         setFilters: (filter: Record<string, any>) => void;
+        setQueryParam: (key: string, value: any) => void;
         reset: () => void;
     };
 };
 
-export { type ApiClientConfig, type ApiError, type ApiResponse, type PaginateQueryOptions, type PaginationMeta, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiConfig, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi };
+export { type ActionOptions, type ApiClientConfig, type ApiError, type ApiResponse, type PaginateQueryOptions, type PaginationMeta, type QueryOptions, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiConfig, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi };

package/dist/index.js

@@ -106,7 +106,10 @@ function createApiClient(config) {
   let tokenRefreshPromise = null;
   axiosInstance.interceptors.request.use(async (req) => {
     req.headers["X-Request-ID"] = (0, import_uuid.v4)();
-    if (req.url?.includes("/auth/")) return req;
+    if (req.isPublic) {
+      console.log(`[API Core] Skipping token for public request: ${req.url}`);
+      return req;
+    }
     if (tokenRefreshPromise) {
       await tokenRefreshPromise;
     }
@@ -125,6 +128,9 @@ function createApiClient(config) {
     if (tokens.accessToken && !tokenManager.isHttpOnly()) {
       const tokenType = tokens.tokenType || "Bearer";
       req.headers.Authorization = `${tokenType} ${tokens.accessToken}`;
+      console.log(`[API Core] Token attached to request: ${req.url}`);
+    } else {
+      console.warn(`[API Core] No token attached for request: ${req.url}`);
     }
     return req;
   }, (error) => Promise.reject(error));
@@ -164,6 +170,7 @@ var import_axios2 = __toESM(require("axios"));
 function buildPaginateQuery(query) {
   if (!query) return "";
   const params = new URLSearchParams();
+  const standardKeys = /* @__PURE__ */ new Set(["page", "limit", "search", "sortBy", "filter"]);
   if (query.page) params.append("page", query.page.toString());
   if (query.limit) params.append("limit", query.limit.toString());
   if (query.search) params.append("search", query.search);
@@ -175,6 +182,14 @@ function buildPaginateQuery(query) {
       params.append(`filter.${field}`, String(value));
     });
   }
+  for (const key in query) {
+    if (Object.prototype.hasOwnProperty.call(query, key) && !standardKeys.has(key)) {
+      const value = query[key];
+      if (value !== void 0 && value !== null) {
+        params.append(key, String(value));
+      }
+    }
+  }
   const queryString = params.toString();
   return queryString ? `?${queryString}` : "";
 }
@@ -244,24 +259,27 @@ function createApiServices(axiosInstance, endpoint) {
     }
   };
   const post = async (data, config) => {
+    const finalUrl = config?.endpoint || endpoint;
     try {
-      const response = await axiosInstance.post(endpoint, data, config);
+      const response = await axiosInstance.post(finalUrl, data, config);
       return processResponse(response);
     } catch (error) {
       return processResponse(error);
     }
   };
   const patch = async (id, data, config) => {
+    const finalUrl = config?.endpoint || `${endpoint}/${id}`;
     try {
-      const response = await axiosInstance.patch(`${endpoint}/${id}`, data, config);
+      const response = await axiosInstance.patch(finalUrl, data, config);
       return processResponse(response);
     } catch (error) {
       return processResponse(error);
     }
   };
   const remove = async (id, config) => {
+    const finalUrl = config?.endpoint || `${endpoint}/${id}`;
     try {
-      const response = await axiosInstance.delete(`${endpoint}/${id}`, config);
+      const response = await axiosInstance.delete(finalUrl, config);
       return processResponse(response);
     } catch (error) {
       return processResponse(error);
@@ -335,15 +353,15 @@ function useApi(axiosInstance, config) {
   const {
     endpoint,
     initialData,
-    initialQuery = { page: 1, limit: 10 },
+    initialQuery = { limit: 10 },
     enabled = true,
     refetchAfterChange = true,
+    // تم تعديل القيمة الافتراضية لتكون أكثر شيوعًا
     onSuccess,
     onError
   } = config;
   const [state, setState] = (0, import_react.useState)({
     data: initialData || null,
-    // <--- التغيير هنا
     rawResponse: null,
     loading: enabled,
     error: null,
@@ -351,9 +369,10 @@ function useApi(axiosInstance, config) {
   });
   const [queryOptions, setQueryOptions] = (0, import_react.useState)(initialQuery);
   const apiServices = (0, import_react.useRef)(createApiServices(axiosInstance, endpoint)).current;
-  const fetchData = (0, import_react.useCallback)(async () => {
+  const fetchData = (0, import_react.useCallback)(async (options) => {
+    const currentQuery = options || queryOptions;
     setState((prev) => ({ ...prev, data: null, loading: true, error: null }));
-    const queryString = buildPaginateQuery(queryOptions);
+    const queryString = buildPaginateQuery(currentQuery);
     const result = await apiServices.getWithQuery(queryString, { cancelTokenKey: endpoint });
     setState(result);
     if (!result.success && onError) {
@@ -365,9 +384,9 @@ function useApi(axiosInstance, config) {
       fetchData();
     }
   }, [enabled, queryOptions]);
-  const createItem = async (newItem) => {
+  const createItem = async (newItem, options) => {
     setState((prev) => ({ ...prev, loading: true }));
-    const result = await apiServices.post(newItem);
+    const result = await apiServices.post(newItem, options);
     if (result.success) {
       if (refetchAfterChange) await fetchData();
       else setState((prev) => ({ ...prev, loading: false }));
@@ -378,9 +397,9 @@ function useApi(axiosInstance, config) {
     }
     return result;
   };
-  const updateItem = async (id, updatedItem) => {
+  const updateItem = async (id, updatedItem, options) => {
     setState((prev) => ({ ...prev, loading: true }));
-    const result = await apiServices.patch(id, updatedItem);
+    const result = await apiServices.patch(id, updatedItem, options);
     if (result.success) {
       if (refetchAfterChange) await fetchData();
       else setState((prev) => ({ ...prev, loading: false }));
@@ -391,9 +410,9 @@ function useApi(axiosInstance, config) {
     }
     return result;
   };
-  const deleteItem = async (id) => {
+  const deleteItem = async (id, options) => {
     setState((prev) => ({ ...prev, loading: true }));
-    const result = await apiServices.remove(id);
+    const result = await apiServices.remove(id, options);
     if (result.success) {
       if (refetchAfterChange) await fetchData();
       else setState((prev) => ({ ...prev, loading: false }));
@@ -409,11 +428,19 @@ function useApi(axiosInstance, config) {
   const setSearchTerm = (search) => setQueryOptions((prev) => ({ ...prev, search, page: 1 }));
   const setSorting = (sortBy) => setQueryOptions((prev) => ({ ...prev, sortBy }));
   const setFilters = (filter) => setQueryOptions((prev) => ({ ...prev, filter, page: 1 }));
+  const setQueryParam = (key, value) => {
+    setQueryOptions((prev) => {
+      const newQuery = { ...prev, [key]: value };
+      if (key !== "page") {
+        newQuery.page = 1;
+      }
+      return newQuery;
+    });
+  };
   const resetQuery = () => setQueryOptions(initialQuery);
   return {
     state,
     setState,
-    // Exposing setState for direct manipulation or connection to Redux
     actions: {
       fetch: fetchData,
       create: createItem,
@@ -428,6 +455,8 @@ function useApi(axiosInstance, config) {
       setSearchTerm,
       setSorting,
       setFilters,
+      setQueryParam,
+      // <-- NEW
       reset: resetQuery
     }
   };

package/dist/index.mjs

@@ -64,7 +64,10 @@ function createApiClient(config) {
   let tokenRefreshPromise = null;
   axiosInstance.interceptors.request.use(async (req) => {
     req.headers["X-Request-ID"] = uuidv4();
-    if (req.url?.includes("/auth/")) return req;
+    if (req.isPublic) {
+      console.log(`[API Core] Skipping token for public request: ${req.url}`);
+      return req;
+    }
     if (tokenRefreshPromise) {
       await tokenRefreshPromise;
     }
@@ -83,6 +86,9 @@ function createApiClient(config) {
     if (tokens.accessToken && !tokenManager.isHttpOnly()) {
       const tokenType = tokens.tokenType || "Bearer";
       req.headers.Authorization = `${tokenType} ${tokens.accessToken}`;
+      console.log(`[API Core] Token attached to request: ${req.url}`);
+    } else {
+      console.warn(`[API Core] No token attached for request: ${req.url}`);
     }
     return req;
   }, (error) => Promise.reject(error));
@@ -122,6 +128,7 @@ import axios2 from "axios";
 function buildPaginateQuery(query) {
   if (!query) return "";
   const params = new URLSearchParams();
+  const standardKeys = /* @__PURE__ */ new Set(["page", "limit", "search", "sortBy", "filter"]);
   if (query.page) params.append("page", query.page.toString());
   if (query.limit) params.append("limit", query.limit.toString());
   if (query.search) params.append("search", query.search);
@@ -133,6 +140,14 @@ function buildPaginateQuery(query) {
       params.append(`filter.${field}`, String(value));
     });
   }
+  for (const key in query) {
+    if (Object.prototype.hasOwnProperty.call(query, key) && !standardKeys.has(key)) {
+      const value = query[key];
+      if (value !== void 0 && value !== null) {
+        params.append(key, String(value));
+      }
+    }
+  }
   const queryString = params.toString();
   return queryString ? `?${queryString}` : "";
 }
@@ -202,24 +217,27 @@ function createApiServices(axiosInstance, endpoint) {
     }
   };
   const post = async (data, config) => {
+    const finalUrl = config?.endpoint || endpoint;
     try {
-      const response = await axiosInstance.post(endpoint, data, config);
+      const response = await axiosInstance.post(finalUrl, data, config);
       return processResponse(response);
     } catch (error) {
       return processResponse(error);
     }
   };
   const patch = async (id, data, config) => {
+    const finalUrl = config?.endpoint || `${endpoint}/${id}`;
     try {
-      const response = await axiosInstance.patch(`${endpoint}/${id}`, data, config);
+      const response = await axiosInstance.patch(finalUrl, data, config);
       return processResponse(response);
     } catch (error) {
       return processResponse(error);
     }
   };
   const remove = async (id, config) => {
+    const finalUrl = config?.endpoint || `${endpoint}/${id}`;
     try {
-      const response = await axiosInstance.delete(`${endpoint}/${id}`, config);
+      const response = await axiosInstance.delete(finalUrl, config);
       return processResponse(response);
     } catch (error) {
       return processResponse(error);
@@ -293,15 +311,15 @@ function useApi(axiosInstance, config) {
   const {
     endpoint,
     initialData,
-    initialQuery = { page: 1, limit: 10 },
+    initialQuery = { limit: 10 },
     enabled = true,
     refetchAfterChange = true,
+    // تم تعديل القيمة الافتراضية لتكون أكثر شيوعًا
     onSuccess,
     onError
   } = config;
   const [state, setState] = useState({
     data: initialData || null,
-    // <--- التغيير هنا
     rawResponse: null,
     loading: enabled,
     error: null,
@@ -309,9 +327,10 @@ function useApi(axiosInstance, config) {
   });
   const [queryOptions, setQueryOptions] = useState(initialQuery);
   const apiServices = useRef(createApiServices(axiosInstance, endpoint)).current;
-  const fetchData = useCallback(async () => {
+  const fetchData = useCallback(async (options) => {
+    const currentQuery = options || queryOptions;
     setState((prev) => ({ ...prev, data: null, loading: true, error: null }));
-    const queryString = buildPaginateQuery(queryOptions);
+    const queryString = buildPaginateQuery(currentQuery);
     const result = await apiServices.getWithQuery(queryString, { cancelTokenKey: endpoint });
     setState(result);
     if (!result.success && onError) {
@@ -323,9 +342,9 @@ function useApi(axiosInstance, config) {
       fetchData();
     }
   }, [enabled, queryOptions]);
-  const createItem = async (newItem) => {
+  const createItem = async (newItem, options) => {
     setState((prev) => ({ ...prev, loading: true }));
-    const result = await apiServices.post(newItem);
+    const result = await apiServices.post(newItem, options);
     if (result.success) {
       if (refetchAfterChange) await fetchData();
       else setState((prev) => ({ ...prev, loading: false }));
@@ -336,9 +355,9 @@ function useApi(axiosInstance, config) {
     }
     return result;
   };
-  const updateItem = async (id, updatedItem) => {
+  const updateItem = async (id, updatedItem, options) => {
     setState((prev) => ({ ...prev, loading: true }));
-    const result = await apiServices.patch(id, updatedItem);
+    const result = await apiServices.patch(id, updatedItem, options);
     if (result.success) {
       if (refetchAfterChange) await fetchData();
       else setState((prev) => ({ ...prev, loading: false }));
@@ -349,9 +368,9 @@ function useApi(axiosInstance, config) {
     }
     return result;
   };
-  const deleteItem = async (id) => {
+  const deleteItem = async (id, options) => {
     setState((prev) => ({ ...prev, loading: true }));
-    const result = await apiServices.remove(id);
+    const result = await apiServices.remove(id, options);
     if (result.success) {
       if (refetchAfterChange) await fetchData();
       else setState((prev) => ({ ...prev, loading: false }));
@@ -367,11 +386,19 @@ function useApi(axiosInstance, config) {
   const setSearchTerm = (search) => setQueryOptions((prev) => ({ ...prev, search, page: 1 }));
   const setSorting = (sortBy) => setQueryOptions((prev) => ({ ...prev, sortBy }));
   const setFilters = (filter) => setQueryOptions((prev) => ({ ...prev, filter, page: 1 }));
+  const setQueryParam = (key, value) => {
+    setQueryOptions((prev) => {
+      const newQuery = { ...prev, [key]: value };
+      if (key !== "page") {
+        newQuery.page = 1;
+      }
+      return newQuery;
+    });
+  };
   const resetQuery = () => setQueryOptions(initialQuery);
   return {
     state,
     setState,
-    // Exposing setState for direct manipulation or connection to Redux
     actions: {
       fetch: fetchData,
       create: createItem,
@@ -386,6 +413,8 @@ function useApi(axiosInstance, config) {
       setSearchTerm,
       setSorting,
       setFilters,
+      setQueryParam,
+      // <-- NEW
       reset: resetQuery
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api-core-lib",
-  "version": "3.3.2",
+  "version": "4.3.3",
   "description": "A flexible and powerful API client library for modern web applications.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",