api-core-lib 4.4.3 → 5.5.4

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { ResponseType, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method, AxiosResponse } from 'axios';
+import { InternalAxiosRequestConfig, AxiosResponse, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method } from 'axios';
 import * as react from 'react';
 
 /**
@@ -35,28 +35,49 @@ interface ApiError {
     errors?: ValidationError[];
     requestId?: string;
 }
-/**
- * يمثل مجموعة التوكنات التي يتم إدارتها.
- */
 interface Tokens {
     accessToken: string | null;
     refreshToken: string | null;
     expiresAt?: number;
     tokenType?: string;
 }
-/**
- * واجهة لمدير التوكنات، تسمح بفصل منطق تخزين التوكن.
- * يمكن للمستخدم توفير تطبيق لهذه الواجهة (e.g., LocalStorage, Cookies).
- */
 interface TokenManager {
     getTokens(): Promise<Tokens>;
     setTokens(tokens: Tokens): Promise<void>;
     clearTokens(): Promise<void>;
+    /**
+     * دالة لتحديد سياق التشغيل.
+     * true إذا كانت التوكنات في كوكيز httpOnly (الوضع الآمن).
+     * false إذا كانت في مكان يمكن للعميل الوصول إليه (للتطبيقات غير Next.js).
+     */
     isHttpOnly(): boolean;
 }
 /**
- * يوسع إعدادات طلب Axios القياسية بخيارات خاصة بالمكتبة.
+ * واجهة لـ Logger مخصص. متوافقة مع `console`.
+ */
+interface Logger {
+    log(message?: any, ...optionalParams: any[]): void;
+    info(message?: any, ...optionalParams: any[]): void;
+    warn(message?: any, ...optionalParams: any[]): void;
+    error(message?: any, ...optionalParams: any[]): void;
+}
+/**
+ * سياق البرمجيات الوسيطة الذي يتم تمريره لكل دالة.
  */
+interface MiddlewareContext {
+    req: InternalAxiosRequestConfig;
+    res?: AxiosResponse;
+    error?: any;
+    logger: Logger;
+    custom?: Record<string, any>;
+}
+/**
+ * دالة برمجية وسيطة (Middleware Function).
+ */
+type Middleware = (context: MiddlewareContext, next: () => Promise<void>) => Promise<void>;
+interface RequestConfig extends AxiosRequestConfig {
+    isPublic?: boolean;
+}
 interface RequestConfig extends AxiosRequestConfig {
     cancelTokenKey?: string;
     onUploadProgress?: (progressEvent: AxiosProgressEvent) => void;
@@ -113,7 +134,7 @@ interface RefreshTokenConfig {
     };
 }
 /**
- * الواجهة الرئيسية لتهيئة عميل الـ API.
+ * الواجهة الرئيسية لتهيئة عميل الـ API (محدثة بالكامل).
  */
 interface ApiClientConfig {
     baseURL?: string;
@@ -121,13 +142,16 @@ interface ApiClientConfig {
     timeout?: number;
     headers?: Record<string, string>;
     withCredentials?: boolean;
-    responseType?: ResponseType;
-    /**
-     * إعدادات مخصصة لعملية تجديد التوكن.
-     * إذا لم يتم توفيرها، ستتوقف محاولات التجديد التلقائي.
-     */
     refreshTokenConfig?: RefreshTokenConfig;
     onRefreshError?: (error: any) => void;
+    /**
+     * ✨ NEW: Logger مخصص. الافتراضي هو `console`.
+     */
+    logger?: Logger;
+    /**
+     * ✨ NEW: مصفوفة من البرمجيات الوسيطة (Middleware) لتشغيلها مع كل طلب.
+     */
+    middleware?: Middleware[];
 }
 /**
  * يمثل بنية الاستجابة القياسية من الـ API.
@@ -191,6 +215,7 @@ interface ActionOptions {
      * update('123', { status: 'active' }, { endpoint: '/items/123/activate' })
      */
     endpoint?: string;
+    refetch?: boolean;
 }
 /**
  * واجهة لتهيئة الهوك `useApi`.
@@ -213,21 +238,41 @@ interface UseApiConfig<T> {
 
 /**
  * @file src/core/client.ts
- * @description
- * هذا هو القلب النابض للمكتبة. دالة `createApiClient` تنشئ وتهيئ نسخة Axios
- * مع معترضات (interceptors) ذكية لإدارة التوكنات، بما في ذلك التجديد التلقائي
- * والاستباقي للتوكن، ومعالجة الأخطاء بشكل مركزي.
+ * @description This is the heart of the API client library.
+ * The `createApiClient` function constructs and configures a sophisticated Axios instance.
+ * It features intelligent, security-first token management, a flexible middleware system,
+ * and customizable logging, all designed to work seamlessly in modern web frameworks like Next.js.
  */
 
+/**
+ * Creates and configures a new Axios instance with advanced features.
+ *
+ * This factory function is the central entry point of the library. It sets up
+ * request and response interceptors to handle:
+ * - Secure token management (supporting httpOnly and client-side storage).
+ * - A flexible middleware pipeline for custom logic.
+ * - Centralized logging for observability.
+ * - Automatic token refresh for client-side scenarios.
+ *
+ * @param {ApiClientConfig} config - The configuration object for the API client.
+ * @returns {AxiosInstance} A fully configured Axios instance ready for use.
+ */
 declare function createApiClient(config: ApiClientConfig): AxiosInstance;
 
 type CrudRequestConfig = RequestConfig & ActionOptions;
+/**
+ * دالة مصنع (Factory Function) لإنشاء مجموعة خدمات API قابلة لإعادة الاستخدام لنقطة نهاية (endpoint) محددة.
+ * توفر عمليات CRUD كاملة بالإضافة إلى ميزات متقدمة مثل الحذف الجماعي ورفع الملفات.
+ */
 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?: CrudRequestConfig) => Promise<StandardResponse<T>>;
+    put: (id: string, data: 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>>;
+    bulkDelete: (ids: string[], config?: CrudRequestConfig) => Promise<StandardResponse<any>>;
+    upload: (file: File, additionalData?: Record<string, any>, config?: CrudRequestConfig) => Promise<StandardResponse<any>>;
 };
 
 /**
@@ -275,6 +320,7 @@ declare function createApiActions<TActions extends Record<string, {
     endpoint: string;
     requestType: any;
     responseType: any;
+    log?: boolean;
 }>>(axiosInstance: AxiosInstance, actionsConfig: TActions): {
     [K in keyof TActions]: ApiAction<TActions[K]['requestType'], TActions[K]['responseType']>;
 };
@@ -298,7 +344,7 @@ declare const cacheManager: CacheManager;
  * @param responseOrError The raw Axios response or a pre-processed ApiError.
  * @returns A standardized `StandardResponse` object with direct access to `.data`.
  */
-declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError) => StandardResponse<T>;
+declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError, log?: boolean) => StandardResponse<T>;
 
 declare function useApi<T extends {
     id?: string | number;
@@ -308,8 +354,11 @@ declare function useApi<T extends {
     actions: {
         fetch: (options?: QueryOptions) => Promise<void>;
         create: (newItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
+        put: (id: string, item: 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>>;
+        bulkRemove: (ids: string[], options?: ActionOptions) => Promise<StandardResponse<any>>;
+        upload: (file: File, additionalData?: Record<string, any>, options?: ActionOptions) => Promise<StandardResponse<any>>;
     };
     query: {
         options: QueryOptions;
@@ -327,4 +376,4 @@ declare function useApi<T extends {
     };
 };
 
-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 };
+export { type ActionOptions, type ApiClientConfig, type ApiError, type ApiResponse, type Logger, type Middleware, type MiddlewareContext, 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

@@ -1,4 +1,4 @@
-import { ResponseType, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method, AxiosResponse } from 'axios';
+import { InternalAxiosRequestConfig, AxiosResponse, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method } from 'axios';
 import * as react from 'react';
 
 /**
@@ -35,28 +35,49 @@ interface ApiError {
     errors?: ValidationError[];
     requestId?: string;
 }
-/**
- * يمثل مجموعة التوكنات التي يتم إدارتها.
- */
 interface Tokens {
     accessToken: string | null;
     refreshToken: string | null;
     expiresAt?: number;
     tokenType?: string;
 }
-/**
- * واجهة لمدير التوكنات، تسمح بفصل منطق تخزين التوكن.
- * يمكن للمستخدم توفير تطبيق لهذه الواجهة (e.g., LocalStorage, Cookies).
- */
 interface TokenManager {
     getTokens(): Promise<Tokens>;
     setTokens(tokens: Tokens): Promise<void>;
     clearTokens(): Promise<void>;
+    /**
+     * دالة لتحديد سياق التشغيل.
+     * true إذا كانت التوكنات في كوكيز httpOnly (الوضع الآمن).
+     * false إذا كانت في مكان يمكن للعميل الوصول إليه (للتطبيقات غير Next.js).
+     */
     isHttpOnly(): boolean;
 }
 /**
- * يوسع إعدادات طلب Axios القياسية بخيارات خاصة بالمكتبة.
+ * واجهة لـ Logger مخصص. متوافقة مع `console`.
+ */
+interface Logger {
+    log(message?: any, ...optionalParams: any[]): void;
+    info(message?: any, ...optionalParams: any[]): void;
+    warn(message?: any, ...optionalParams: any[]): void;
+    error(message?: any, ...optionalParams: any[]): void;
+}
+/**
+ * سياق البرمجيات الوسيطة الذي يتم تمريره لكل دالة.
  */
+interface MiddlewareContext {
+    req: InternalAxiosRequestConfig;
+    res?: AxiosResponse;
+    error?: any;
+    logger: Logger;
+    custom?: Record<string, any>;
+}
+/**
+ * دالة برمجية وسيطة (Middleware Function).
+ */
+type Middleware = (context: MiddlewareContext, next: () => Promise<void>) => Promise<void>;
+interface RequestConfig extends AxiosRequestConfig {
+    isPublic?: boolean;
+}
 interface RequestConfig extends AxiosRequestConfig {
     cancelTokenKey?: string;
     onUploadProgress?: (progressEvent: AxiosProgressEvent) => void;
@@ -113,7 +134,7 @@ interface RefreshTokenConfig {
     };
 }
 /**
- * الواجهة الرئيسية لتهيئة عميل الـ API.
+ * الواجهة الرئيسية لتهيئة عميل الـ API (محدثة بالكامل).
  */
 interface ApiClientConfig {
     baseURL?: string;
@@ -121,13 +142,16 @@ interface ApiClientConfig {
     timeout?: number;
     headers?: Record<string, string>;
     withCredentials?: boolean;
-    responseType?: ResponseType;
-    /**
-     * إعدادات مخصصة لعملية تجديد التوكن.
-     * إذا لم يتم توفيرها، ستتوقف محاولات التجديد التلقائي.
-     */
     refreshTokenConfig?: RefreshTokenConfig;
     onRefreshError?: (error: any) => void;
+    /**
+     * ✨ NEW: Logger مخصص. الافتراضي هو `console`.
+     */
+    logger?: Logger;
+    /**
+     * ✨ NEW: مصفوفة من البرمجيات الوسيطة (Middleware) لتشغيلها مع كل طلب.
+     */
+    middleware?: Middleware[];
 }
 /**
  * يمثل بنية الاستجابة القياسية من الـ API.
@@ -191,6 +215,7 @@ interface ActionOptions {
      * update('123', { status: 'active' }, { endpoint: '/items/123/activate' })
      */
     endpoint?: string;
+    refetch?: boolean;
 }
 /**
  * واجهة لتهيئة الهوك `useApi`.
@@ -213,21 +238,41 @@ interface UseApiConfig<T> {
 
 /**
  * @file src/core/client.ts
- * @description
- * هذا هو القلب النابض للمكتبة. دالة `createApiClient` تنشئ وتهيئ نسخة Axios
- * مع معترضات (interceptors) ذكية لإدارة التوكنات، بما في ذلك التجديد التلقائي
- * والاستباقي للتوكن، ومعالجة الأخطاء بشكل مركزي.
+ * @description This is the heart of the API client library.
+ * The `createApiClient` function constructs and configures a sophisticated Axios instance.
+ * It features intelligent, security-first token management, a flexible middleware system,
+ * and customizable logging, all designed to work seamlessly in modern web frameworks like Next.js.
  */
 
+/**
+ * Creates and configures a new Axios instance with advanced features.
+ *
+ * This factory function is the central entry point of the library. It sets up
+ * request and response interceptors to handle:
+ * - Secure token management (supporting httpOnly and client-side storage).
+ * - A flexible middleware pipeline for custom logic.
+ * - Centralized logging for observability.
+ * - Automatic token refresh for client-side scenarios.
+ *
+ * @param {ApiClientConfig} config - The configuration object for the API client.
+ * @returns {AxiosInstance} A fully configured Axios instance ready for use.
+ */
 declare function createApiClient(config: ApiClientConfig): AxiosInstance;
 
 type CrudRequestConfig = RequestConfig & ActionOptions;
+/**
+ * دالة مصنع (Factory Function) لإنشاء مجموعة خدمات API قابلة لإعادة الاستخدام لنقطة نهاية (endpoint) محددة.
+ * توفر عمليات CRUD كاملة بالإضافة إلى ميزات متقدمة مثل الحذف الجماعي ورفع الملفات.
+ */
 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?: CrudRequestConfig) => Promise<StandardResponse<T>>;
+    put: (id: string, data: 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>>;
+    bulkDelete: (ids: string[], config?: CrudRequestConfig) => Promise<StandardResponse<any>>;
+    upload: (file: File, additionalData?: Record<string, any>, config?: CrudRequestConfig) => Promise<StandardResponse<any>>;
 };
 
 /**
@@ -275,6 +320,7 @@ declare function createApiActions<TActions extends Record<string, {
     endpoint: string;
     requestType: any;
     responseType: any;
+    log?: boolean;
 }>>(axiosInstance: AxiosInstance, actionsConfig: TActions): {
     [K in keyof TActions]: ApiAction<TActions[K]['requestType'], TActions[K]['responseType']>;
 };
@@ -298,7 +344,7 @@ declare const cacheManager: CacheManager;
  * @param responseOrError The raw Axios response or a pre-processed ApiError.
  * @returns A standardized `StandardResponse` object with direct access to `.data`.
  */
-declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError) => StandardResponse<T>;
+declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError, log?: boolean) => StandardResponse<T>;
 
 declare function useApi<T extends {
     id?: string | number;
@@ -308,8 +354,11 @@ declare function useApi<T extends {
     actions: {
         fetch: (options?: QueryOptions) => Promise<void>;
         create: (newItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
+        put: (id: string, item: 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>>;
+        bulkRemove: (ids: string[], options?: ActionOptions) => Promise<StandardResponse<any>>;
+        upload: (file: File, additionalData?: Record<string, any>, options?: ActionOptions) => Promise<StandardResponse<any>>;
     };
     query: {
         options: QueryOptions;
@@ -327,4 +376,4 @@ declare function useApi<T extends {
     };
 };
 
-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 };
+export { type ActionOptions, type ApiClientConfig, type ApiError, type ApiResponse, type Logger, type Middleware, type MiddlewareContext, 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

@@ -43,10 +43,20 @@ module.exports = __toCommonJS(index_exports);
 // src/core/client.ts
 var import_axios = __toESM(require("axios"));
 var import_uuid = require("uuid");
-async function refreshToken(config, tokenManager) {
+async function runMiddleware(context, middlewares = []) {
+  const run = async (index) => {
+    if (index >= middlewares.length) {
+      return;
+    }
+    const middleware = middlewares[index];
+    await middleware(context, () => run(index + 1));
+  };
+  await run(0);
+}
+async function refreshToken(config, tokenManager, logger) {
   const { refreshTokenConfig } = config;
   if (!refreshTokenConfig) {
-    console.warn("[API Core] Refresh token process is disabled (refreshTokenConfig is not provided).");
+    logger.warn("[API Core] Token refresh is disabled: `refreshTokenConfig` is not provided.");
     await tokenManager.clearTokens();
     return null;
   }
@@ -58,6 +68,7 @@ async function refreshToken(config, tokenManager) {
     const { path, buildRequestBody, buildRequestHeaders, extractTokens } = refreshTokenConfig;
     const requestBody = buildRequestBody ? buildRequestBody(currentTokens.refreshToken) : { refresh_token: currentTokens.refreshToken };
     const requestHeaders = buildRequestHeaders ? buildRequestHeaders(currentTokens) : {};
+    logger.info(`[API Core] Attempting to refresh token at path: ${path}`);
     const response = await import_axios.default.post(
       `${config.baseURL}${path}`,
       requestBody,
@@ -73,15 +84,14 @@ async function refreshToken(config, tokenManager) {
     const newTokens = {
       accessToken: extracted.accessToken,
       refreshToken: extracted.refreshToken || currentTokens.refreshToken,
-      // احتفظ بالقديم إذا لم يأتِ جديد
       expiresAt: Date.now() + extracted.expiresIn * 1e3,
       tokenType: extracted.tokenType || "Bearer"
     };
     await tokenManager.setTokens(newTokens);
-    console.log("[API Core] Tokens refreshed successfully.");
+    logger.info("[API Core] Tokens refreshed successfully.");
     return newTokens;
   } catch (err) {
-    console.error("[API Core] Failed to refresh token.", err.response?.data || err.message);
+    logger.error("[API Core] Failed to refresh token.", err.response?.data || err.message);
     if (config.onRefreshError) {
       config.onRefreshError(err);
     }
@@ -95,10 +105,9 @@ function createApiClient(config) {
     tokenManager,
     timeout = 15e3,
     headers = {},
-    withCredentials = false
-    // onRefreshError = () => {},
-    // responseType = 'json',
-    // refreshTokenConfig,
+    withCredentials = false,
+    middleware = [],
+    logger = console
   } = config;
   const axiosInstance = import_axios.default.create({
     baseURL,
@@ -106,63 +115,88 @@ function createApiClient(config) {
     headers: { "Content-Type": "application/json", ...headers },
     withCredentials
   });
-  let tokenRefreshPromise = null;
+  let isRefreshing = false;
+  let failedQueue = [];
+  const processQueue = (error, token = null) => {
+    failedQueue.forEach((prom) => error ? prom.reject(error) : prom.resolve(token));
+    failedQueue = [];
+  };
   axiosInstance.interceptors.request.use(async (req) => {
     req.headers["X-Request-ID"] = (0, import_uuid.v4)();
+    logger.info(`[Request] > ${req.method?.toUpperCase()} ${req.url}`, { id: req.headers["X-Request-ID"] });
+    const context = { req, logger, custom: {} };
+    await runMiddleware(context, middleware);
     if (req.isPublic) {
-      console.log(`[API Core] Skipping token for public request: ${req.url}`);
       return req;
     }
-    if (tokenRefreshPromise) {
-      await tokenRefreshPromise;
+    if (tokenManager.isHttpOnly()) {
+      return req;
     }
     let tokens = await tokenManager.getTokens();
     const now = Date.now();
     const tokenBuffer = 60 * 1e3;
-    if (tokens.accessToken && tokens.expiresAt && tokens.expiresAt - now < tokenBuffer) {
-      if (!tokenRefreshPromise && config.refreshTokenConfig) {
-        console.log("[API Core] Proactive token refresh initiated.");
-        tokenRefreshPromise = refreshToken(config, tokenManager);
+    if (tokens.accessToken && tokens.expiresAt && tokens.expiresAt - now < tokenBuffer && !isRefreshing) {
+      if (config.refreshTokenConfig) {
+        logger.info("[API Core] Proactive token refresh initiated.");
+        isRefreshing = true;
+        try {
+          const newTokens = await refreshToken(config, tokenManager, logger);
+          if (newTokens) tokens = newTokens;
+        } finally {
+          isRefreshing = false;
+        }
       }
-      const newTokens = await tokenRefreshPromise;
-      tokenRefreshPromise = null;
-      if (newTokens) tokens = newTokens;
     }
-    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}`);
+    if (tokens.accessToken) {
+      req.headers.Authorization = `${tokens.tokenType || "Bearer"} ${tokens.accessToken}`;
     }
     return req;
-  }, (error) => Promise.reject(error));
+  });
   axiosInstance.interceptors.response.use(
-    (response) => response,
+    async (res) => {
+      logger.info(`[Response] < ${res.config.method?.toUpperCase()} ${res.config.url}`, { id: res.config.headers["X-Request-ID"], status: res.status });
+      const context = { req: res.config, res, logger, custom: {} };
+      await runMiddleware(context, middleware);
+      return res;
+    },
     async (error) => {
       const originalRequest = error.config;
-      if (error.response?.status === 401 && !originalRequest._retry) {
-        originalRequest._retry = true;
-        if (!tokenRefreshPromise && config.refreshTokenConfig) {
-          console.log("[API Core] Reactive token refresh initiated due to 401.");
-          tokenRefreshPromise = refreshToken(config, tokenManager);
+      logger.error(`[Response Error] < ${originalRequest.method?.toUpperCase()} ${originalRequest.url}`, { id: originalRequest.headers?.["X-Request-ID"], status: error.response?.status, error: error.message });
+      const context = { req: originalRequest, error, logger, custom: {} };
+      await runMiddleware(context, middleware);
+      const isHttpOnlyMode = tokenManager.isHttpOnly();
+      const canAttemptRefresh = error.response?.status === 401 && !originalRequest._retry && config.refreshTokenConfig;
+      if (isHttpOnlyMode && canAttemptRefresh) {
+        logger.error("[API Core] Fatal: Received 401 in httpOnly mode. Token refresh must be handled by the server-side proxy. The request will not be retried from the client.");
+        return Promise.reject(error);
+      }
+      if (!isHttpOnlyMode && canAttemptRefresh) {
+        if (isRefreshing) {
+          return new Promise((resolve, reject) => {
+            failedQueue.push({ resolve, reject });
+          }).then((token) => {
+            originalRequest.headers["Authorization"] = `Bearer ${token}`;
+            return axiosInstance(originalRequest);
+          });
         }
-        const newTokens = await tokenRefreshPromise;
-        tokenRefreshPromise = null;
-        if (newTokens) {
-          if (newTokens.accessToken && !tokenManager.isHttpOnly()) {
-            originalRequest.headers.Authorization = `${newTokens.tokenType || "Bearer"} ${newTokens.accessToken}`;
+        originalRequest._retry = true;
+        isRefreshing = true;
+        try {
+          const newTokens = await refreshToken(config, tokenManager, logger);
+          if (!newTokens || !newTokens.accessToken) {
+            throw new Error("Token refresh failed to produce a new access token.");
           }
+          processQueue(null, newTokens.accessToken);
+          originalRequest.headers["Authorization"] = `${newTokens.tokenType || "Bearer"} ${newTokens.accessToken}`;
           return axiosInstance(originalRequest);
+        } catch (refreshError) {
+          processQueue(refreshError, null);
+          return Promise.reject(refreshError);
+        } finally {
+          isRefreshing = false;
         }
       }
-      const enhancedError = {
-        message: error.response?.data?.message || error.message,
-        status: error.response?.status || 500,
-        errors: error.response?.data?.errors,
-        requestId: originalRequest.headers?.["X-Request-ID"]
-      };
-      return Promise.reject(enhancedError);
+      return Promise.reject(error);
     }
   );
   return axiosInstance;
@@ -204,8 +238,10 @@ function isAxiosResponse(obj) {
 }
 
 // src/core/processor.ts
-var processResponse = (responseOrError) => {
+var processResponse = (responseOrError, log) => {
   if (isApiError(responseOrError)) {
+    log && console.log(`****[ API ERROR PROCESS RESPONSE ]: ***
+ ${responseOrError} ***  `);
     return {
       data: null,
       rawResponse: void 0,
@@ -217,15 +253,17 @@ var processResponse = (responseOrError) => {
     };
   }
   if (isAxiosResponse(responseOrError)) {
+    log && console.log(`****[ API IS SCSS PROCESS RESPONSE ]: ***
+ ${responseOrError} ***  `);
     const rawData = responseOrError.data;
     const isWrappedResponse = rawData && typeof rawData.success === "boolean" && rawData.data !== void 0;
+    log && console.log(`12345[ API IS WRAPPED DATA PROCESS RESPONSE ]: ***
+ ${isWrappedResponse} ***  `);
     const finalData = isWrappedResponse ? rawData.data : rawData;
     const message = isWrappedResponse ? rawData.message : "Request successful.";
     return {
       data: finalData,
-      // <-- وصول مباشر للبيانات النهائية!
       rawResponse: rawData,
-      // احتفظ بالاستجابة الكاملة إذا احتجت إليها
       loading: false,
       success: true,
       error: null,
@@ -233,6 +271,7 @@ var processResponse = (responseOrError) => {
       validationErrors: []
     };
   }
+  log && console.log(`****[ API STATUS 500 ]: *** ${responseOrError} ***  `);
   return {
     data: null,
     rawResponse: void 0,
@@ -270,6 +309,15 @@ function createApiServices(axiosInstance, endpoint) {
       return processResponse(error);
     }
   };
+  const put = async (id, data, config) => {
+    const finalUrl = config?.endpoint || `${endpoint}/${id}`;
+    try {
+      const response = await axiosInstance.put(finalUrl, data, config);
+      return processResponse(response);
+    } catch (error) {
+      return processResponse(error);
+    }
+  };
   const patch = async (id, data, config) => {
     const finalUrl = config?.endpoint || `${endpoint}/${id}`;
     try {
@@ -288,23 +336,57 @@ function createApiServices(axiosInstance, endpoint) {
       return processResponse(error);
     }
   };
-  return { get, getWithQuery, post, patch, remove };
+  const bulkDelete = async (ids, config) => {
+    const finalUrl = config?.endpoint || `${endpoint}`;
+    try {
+      const response = await axiosInstance.delete(finalUrl, { data: { ids }, ...config });
+      return processResponse(response);
+    } catch (error) {
+      return processResponse(error);
+    }
+  };
+  const upload = async (file, additionalData, config) => {
+    const finalUrl = config?.endpoint || `${endpoint}`;
+    const formData = new FormData();
+    formData.append("file", file);
+    if (additionalData) {
+      Object.keys(additionalData).forEach((key) => {
+        formData.append(key, additionalData[key]);
+      });
+    }
+    try {
+      const response = await axiosInstance.post(finalUrl, formData, {
+        ...config,
+        headers: {
+          ...config?.headers,
+          "Content-Type": "multipart/form-data"
+        }
+      });
+      return processResponse(response);
+    } catch (error) {
+      return processResponse(error);
+    }
+  };
+  return { get, getWithQuery, post, put, patch, remove, bulkDelete, upload };
 }
 
 // src/services/actions.ts
-function createAction(axiosInstance, method, endpoint) {
+function createAction(axiosInstance, method, endpoint, log) {
   return async (payload, config) => {
+    log && console.log(`*[ ${method.toUpperCase()} ACTION API TO ENDPOINT ]: ${endpoint} **** [${payload}]**  `);
     try {
+      log && console.log(`**[ ${method.toUpperCase()} ACTION API TO ENDPOINT ]:${endpoint} **** [action try req]**  `);
       const response = await axiosInstance.request({
-        // <--- غيرنا النوع إلى any
         url: endpoint,
         method,
         ...method.toUpperCase() === "GET" ? { params: payload } : { data: payload },
         ...config
       });
-      return processResponse(response);
+      log && console.log(`***[ ${method.toUpperCase()} ACTION API TO ENDPOINT ]: ${endpoint} ***
+ ${response}***  `);
+      return processResponse(response, log);
     } catch (error) {
-      return processResponse(error);
+      return processResponse(error, log);
     }
   };
 }
@@ -312,8 +394,8 @@ function createApiActions(axiosInstance, actionsConfig) {
   const actions = {};
   for (const actionName in actionsConfig) {
     if (Object.prototype.hasOwnProperty.call(actionsConfig, actionName)) {
-      const { method, endpoint } = actionsConfig[actionName];
-      actions[actionName] = createAction(axiosInstance, method, endpoint);
+      const { method, endpoint, log } = actionsConfig[actionName];
+      actions[actionName] = createAction(axiosInstance, method, endpoint, log);
     }
   }
   return actions;
@@ -379,7 +461,6 @@ function useApi(axiosInstance, config) {
     const result = await apiServices.getWithQuery(queryString, {
       cancelTokenKey: endpoint,
       ...requestConfig
-      // <-- هنا نمرر الإعدادات الافتراضية
     });
     setState(result);
     if (!result.success && onError) {
@@ -404,6 +485,19 @@ function useApi(axiosInstance, config) {
     }
     return result;
   };
+  const putItem = async (id, item, options) => {
+    setState((prev) => ({ ...prev, loading: true }));
+    const result = await apiServices.put(id, item, options);
+    if (result.success) {
+      if (refetchAfterChange) await fetchData();
+      else setState((prev) => ({ ...prev, loading: false }));
+      if (onSuccess) onSuccess(result.message || "Item replaced successfully!", result.data);
+    } else {
+      setState((prev) => ({ ...prev, loading: false, error: result.error }));
+      if (onError) onError(result.message || "Replace failed", result.error || void 0);
+    }
+    return result;
+  };
   const updateItem = async (id, updatedItem, options) => {
     setState((prev) => ({ ...prev, loading: true }));
     const result = await apiServices.patch(id, updatedItem, options);
@@ -430,19 +524,39 @@ function useApi(axiosInstance, config) {
     }
     return result;
   };
+  const bulkDeleteItem = async (ids, options) => {
+    setState((prev) => ({ ...prev, loading: true }));
+    const result = await apiServices.bulkDelete(ids, options);
+    if (result.success) {
+      if (refetchAfterChange) await fetchData();
+      else setState((prev) => ({ ...prev, loading: false }));
+      if (onSuccess) onSuccess(result.message || "Items deleted successfully!");
+    } else {
+      setState((prev) => ({ ...prev, loading: false, error: result.error }));
+      if (onError) onError(result.message || "Bulk delete failed", result.error || void 0);
+    }
+    return result;
+  };
+  const uploadFile = async (file, additionalData, options) => {
+    setState((prev) => ({ ...prev, loading: true }));
+    const result = await apiServices.upload(file, additionalData, options);
+    if (result.success) {
+      if (refetchAfterChange && options?.refetch !== false) await fetchData();
+      else setState((prev) => ({ ...prev, loading: false }));
+      if (onSuccess) onSuccess(result.message || "File uploaded successfully!", result.data);
+    } else {
+      setState((prev) => ({ ...prev, loading: false, error: result.error }));
+      if (onError) onError(result.message || "Upload failed", result.error || void 0);
+    }
+    return result;
+  };
   const setPage = (page) => setQueryOptions((prev) => ({ ...prev, page }));
   const setLimit = (limit) => setQueryOptions((prev) => ({ ...prev, limit, page: 1 }));
   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;
-    });
+    setQueryOptions((prev) => ({ ...prev, [key]: value, page: key !== "page" ? 1 : prev.page }));
   };
   const resetQuery = () => setQueryOptions(initialQuery);
   return {
@@ -451,8 +565,14 @@ function useApi(axiosInstance, config) {
     actions: {
       fetch: fetchData,
       create: createItem,
+      put: putItem,
+      // <-- NEW
       update: updateItem,
-      remove: deleteItem
+      remove: deleteItem,
+      bulkRemove: bulkDeleteItem,
+      // <-- NEW
+      upload: uploadFile
+      // <-- NEW
     },
     query: {
       options: queryOptions,
@@ -463,7 +583,6 @@ function useApi(axiosInstance, config) {
       setSorting,
       setFilters,
       setQueryParam,
-      // <-- NEW
       reset: resetQuery
     }
   };

package/dist/index.mjs

@@ -1,10 +1,20 @@
 // src/core/client.ts
 import axios from "axios";
 import { v4 as uuidv4 } from "uuid";
-async function refreshToken(config, tokenManager) {
+async function runMiddleware(context, middlewares = []) {
+  const run = async (index) => {
+    if (index >= middlewares.length) {
+      return;
+    }
+    const middleware = middlewares[index];
+    await middleware(context, () => run(index + 1));
+  };
+  await run(0);
+}
+async function refreshToken(config, tokenManager, logger) {
   const { refreshTokenConfig } = config;
   if (!refreshTokenConfig) {
-    console.warn("[API Core] Refresh token process is disabled (refreshTokenConfig is not provided).");
+    logger.warn("[API Core] Token refresh is disabled: `refreshTokenConfig` is not provided.");
     await tokenManager.clearTokens();
     return null;
   }
@@ -16,6 +26,7 @@ async function refreshToken(config, tokenManager) {
     const { path, buildRequestBody, buildRequestHeaders, extractTokens } = refreshTokenConfig;
     const requestBody = buildRequestBody ? buildRequestBody(currentTokens.refreshToken) : { refresh_token: currentTokens.refreshToken };
     const requestHeaders = buildRequestHeaders ? buildRequestHeaders(currentTokens) : {};
+    logger.info(`[API Core] Attempting to refresh token at path: ${path}`);
     const response = await axios.post(
       `${config.baseURL}${path}`,
       requestBody,
@@ -31,15 +42,14 @@ async function refreshToken(config, tokenManager) {
     const newTokens = {
       accessToken: extracted.accessToken,
       refreshToken: extracted.refreshToken || currentTokens.refreshToken,
-      // احتفظ بالقديم إذا لم يأتِ جديد
       expiresAt: Date.now() + extracted.expiresIn * 1e3,
       tokenType: extracted.tokenType || "Bearer"
     };
     await tokenManager.setTokens(newTokens);
-    console.log("[API Core] Tokens refreshed successfully.");
+    logger.info("[API Core] Tokens refreshed successfully.");
     return newTokens;
   } catch (err) {
-    console.error("[API Core] Failed to refresh token.", err.response?.data || err.message);
+    logger.error("[API Core] Failed to refresh token.", err.response?.data || err.message);
     if (config.onRefreshError) {
       config.onRefreshError(err);
     }
@@ -53,10 +63,9 @@ function createApiClient(config) {
     tokenManager,
     timeout = 15e3,
     headers = {},
-    withCredentials = false
-    // onRefreshError = () => {},
-    // responseType = 'json',
-    // refreshTokenConfig,
+    withCredentials = false,
+    middleware = [],
+    logger = console
   } = config;
   const axiosInstance = axios.create({
     baseURL,
@@ -64,63 +73,88 @@ function createApiClient(config) {
     headers: { "Content-Type": "application/json", ...headers },
     withCredentials
   });
-  let tokenRefreshPromise = null;
+  let isRefreshing = false;
+  let failedQueue = [];
+  const processQueue = (error, token = null) => {
+    failedQueue.forEach((prom) => error ? prom.reject(error) : prom.resolve(token));
+    failedQueue = [];
+  };
   axiosInstance.interceptors.request.use(async (req) => {
     req.headers["X-Request-ID"] = uuidv4();
+    logger.info(`[Request] > ${req.method?.toUpperCase()} ${req.url}`, { id: req.headers["X-Request-ID"] });
+    const context = { req, logger, custom: {} };
+    await runMiddleware(context, middleware);
     if (req.isPublic) {
-      console.log(`[API Core] Skipping token for public request: ${req.url}`);
       return req;
     }
-    if (tokenRefreshPromise) {
-      await tokenRefreshPromise;
+    if (tokenManager.isHttpOnly()) {
+      return req;
     }
     let tokens = await tokenManager.getTokens();
     const now = Date.now();
     const tokenBuffer = 60 * 1e3;
-    if (tokens.accessToken && tokens.expiresAt && tokens.expiresAt - now < tokenBuffer) {
-      if (!tokenRefreshPromise && config.refreshTokenConfig) {
-        console.log("[API Core] Proactive token refresh initiated.");
-        tokenRefreshPromise = refreshToken(config, tokenManager);
+    if (tokens.accessToken && tokens.expiresAt && tokens.expiresAt - now < tokenBuffer && !isRefreshing) {
+      if (config.refreshTokenConfig) {
+        logger.info("[API Core] Proactive token refresh initiated.");
+        isRefreshing = true;
+        try {
+          const newTokens = await refreshToken(config, tokenManager, logger);
+          if (newTokens) tokens = newTokens;
+        } finally {
+          isRefreshing = false;
+        }
       }
-      const newTokens = await tokenRefreshPromise;
-      tokenRefreshPromise = null;
-      if (newTokens) tokens = newTokens;
     }
-    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}`);
+    if (tokens.accessToken) {
+      req.headers.Authorization = `${tokens.tokenType || "Bearer"} ${tokens.accessToken}`;
     }
     return req;
-  }, (error) => Promise.reject(error));
+  });
   axiosInstance.interceptors.response.use(
-    (response) => response,
+    async (res) => {
+      logger.info(`[Response] < ${res.config.method?.toUpperCase()} ${res.config.url}`, { id: res.config.headers["X-Request-ID"], status: res.status });
+      const context = { req: res.config, res, logger, custom: {} };
+      await runMiddleware(context, middleware);
+      return res;
+    },
     async (error) => {
       const originalRequest = error.config;
-      if (error.response?.status === 401 && !originalRequest._retry) {
-        originalRequest._retry = true;
-        if (!tokenRefreshPromise && config.refreshTokenConfig) {
-          console.log("[API Core] Reactive token refresh initiated due to 401.");
-          tokenRefreshPromise = refreshToken(config, tokenManager);
+      logger.error(`[Response Error] < ${originalRequest.method?.toUpperCase()} ${originalRequest.url}`, { id: originalRequest.headers?.["X-Request-ID"], status: error.response?.status, error: error.message });
+      const context = { req: originalRequest, error, logger, custom: {} };
+      await runMiddleware(context, middleware);
+      const isHttpOnlyMode = tokenManager.isHttpOnly();
+      const canAttemptRefresh = error.response?.status === 401 && !originalRequest._retry && config.refreshTokenConfig;
+      if (isHttpOnlyMode && canAttemptRefresh) {
+        logger.error("[API Core] Fatal: Received 401 in httpOnly mode. Token refresh must be handled by the server-side proxy. The request will not be retried from the client.");
+        return Promise.reject(error);
+      }
+      if (!isHttpOnlyMode && canAttemptRefresh) {
+        if (isRefreshing) {
+          return new Promise((resolve, reject) => {
+            failedQueue.push({ resolve, reject });
+          }).then((token) => {
+            originalRequest.headers["Authorization"] = `Bearer ${token}`;
+            return axiosInstance(originalRequest);
+          });
         }
-        const newTokens = await tokenRefreshPromise;
-        tokenRefreshPromise = null;
-        if (newTokens) {
-          if (newTokens.accessToken && !tokenManager.isHttpOnly()) {
-            originalRequest.headers.Authorization = `${newTokens.tokenType || "Bearer"} ${newTokens.accessToken}`;
+        originalRequest._retry = true;
+        isRefreshing = true;
+        try {
+          const newTokens = await refreshToken(config, tokenManager, logger);
+          if (!newTokens || !newTokens.accessToken) {
+            throw new Error("Token refresh failed to produce a new access token.");
           }
+          processQueue(null, newTokens.accessToken);
+          originalRequest.headers["Authorization"] = `${newTokens.tokenType || "Bearer"} ${newTokens.accessToken}`;
           return axiosInstance(originalRequest);
+        } catch (refreshError) {
+          processQueue(refreshError, null);
+          return Promise.reject(refreshError);
+        } finally {
+          isRefreshing = false;
         }
       }
-      const enhancedError = {
-        message: error.response?.data?.message || error.message,
-        status: error.response?.status || 500,
-        errors: error.response?.data?.errors,
-        requestId: originalRequest.headers?.["X-Request-ID"]
-      };
-      return Promise.reject(enhancedError);
+      return Promise.reject(error);
     }
   );
   return axiosInstance;
@@ -162,8 +196,10 @@ function isAxiosResponse(obj) {
 }
 
 // src/core/processor.ts
-var processResponse = (responseOrError) => {
+var processResponse = (responseOrError, log) => {
   if (isApiError(responseOrError)) {
+    log && console.log(`****[ API ERROR PROCESS RESPONSE ]: ***
+ ${responseOrError} ***  `);
     return {
       data: null,
       rawResponse: void 0,
@@ -175,15 +211,17 @@ var processResponse = (responseOrError) => {
     };
   }
   if (isAxiosResponse(responseOrError)) {
+    log && console.log(`****[ API IS SCSS PROCESS RESPONSE ]: ***
+ ${responseOrError} ***  `);
     const rawData = responseOrError.data;
     const isWrappedResponse = rawData && typeof rawData.success === "boolean" && rawData.data !== void 0;
+    log && console.log(`12345[ API IS WRAPPED DATA PROCESS RESPONSE ]: ***
+ ${isWrappedResponse} ***  `);
     const finalData = isWrappedResponse ? rawData.data : rawData;
     const message = isWrappedResponse ? rawData.message : "Request successful.";
     return {
       data: finalData,
-      // <-- وصول مباشر للبيانات النهائية!
       rawResponse: rawData,
-      // احتفظ بالاستجابة الكاملة إذا احتجت إليها
       loading: false,
       success: true,
       error: null,
@@ -191,6 +229,7 @@ var processResponse = (responseOrError) => {
       validationErrors: []
     };
   }
+  log && console.log(`****[ API STATUS 500 ]: *** ${responseOrError} ***  `);
   return {
     data: null,
     rawResponse: void 0,
@@ -228,6 +267,15 @@ function createApiServices(axiosInstance, endpoint) {
       return processResponse(error);
     }
   };
+  const put = async (id, data, config) => {
+    const finalUrl = config?.endpoint || `${endpoint}/${id}`;
+    try {
+      const response = await axiosInstance.put(finalUrl, data, config);
+      return processResponse(response);
+    } catch (error) {
+      return processResponse(error);
+    }
+  };
   const patch = async (id, data, config) => {
     const finalUrl = config?.endpoint || `${endpoint}/${id}`;
     try {
@@ -246,23 +294,57 @@ function createApiServices(axiosInstance, endpoint) {
       return processResponse(error);
     }
   };
-  return { get, getWithQuery, post, patch, remove };
+  const bulkDelete = async (ids, config) => {
+    const finalUrl = config?.endpoint || `${endpoint}`;
+    try {
+      const response = await axiosInstance.delete(finalUrl, { data: { ids }, ...config });
+      return processResponse(response);
+    } catch (error) {
+      return processResponse(error);
+    }
+  };
+  const upload = async (file, additionalData, config) => {
+    const finalUrl = config?.endpoint || `${endpoint}`;
+    const formData = new FormData();
+    formData.append("file", file);
+    if (additionalData) {
+      Object.keys(additionalData).forEach((key) => {
+        formData.append(key, additionalData[key]);
+      });
+    }
+    try {
+      const response = await axiosInstance.post(finalUrl, formData, {
+        ...config,
+        headers: {
+          ...config?.headers,
+          "Content-Type": "multipart/form-data"
+        }
+      });
+      return processResponse(response);
+    } catch (error) {
+      return processResponse(error);
+    }
+  };
+  return { get, getWithQuery, post, put, patch, remove, bulkDelete, upload };
 }
 
 // src/services/actions.ts
-function createAction(axiosInstance, method, endpoint) {
+function createAction(axiosInstance, method, endpoint, log) {
   return async (payload, config) => {
+    log && console.log(`*[ ${method.toUpperCase()} ACTION API TO ENDPOINT ]: ${endpoint} **** [${payload}]**  `);
     try {
+      log && console.log(`**[ ${method.toUpperCase()} ACTION API TO ENDPOINT ]:${endpoint} **** [action try req]**  `);
       const response = await axiosInstance.request({
-        // <--- غيرنا النوع إلى any
         url: endpoint,
         method,
         ...method.toUpperCase() === "GET" ? { params: payload } : { data: payload },
         ...config
       });
-      return processResponse(response);
+      log && console.log(`***[ ${method.toUpperCase()} ACTION API TO ENDPOINT ]: ${endpoint} ***
+ ${response}***  `);
+      return processResponse(response, log);
     } catch (error) {
-      return processResponse(error);
+      return processResponse(error, log);
     }
   };
 }
@@ -270,8 +352,8 @@ function createApiActions(axiosInstance, actionsConfig) {
   const actions = {};
   for (const actionName in actionsConfig) {
     if (Object.prototype.hasOwnProperty.call(actionsConfig, actionName)) {
-      const { method, endpoint } = actionsConfig[actionName];
-      actions[actionName] = createAction(axiosInstance, method, endpoint);
+      const { method, endpoint, log } = actionsConfig[actionName];
+      actions[actionName] = createAction(axiosInstance, method, endpoint, log);
     }
   }
   return actions;
@@ -337,7 +419,6 @@ function useApi(axiosInstance, config) {
     const result = await apiServices.getWithQuery(queryString, {
       cancelTokenKey: endpoint,
       ...requestConfig
-      // <-- هنا نمرر الإعدادات الافتراضية
     });
     setState(result);
     if (!result.success && onError) {
@@ -362,6 +443,19 @@ function useApi(axiosInstance, config) {
     }
     return result;
   };
+  const putItem = async (id, item, options) => {
+    setState((prev) => ({ ...prev, loading: true }));
+    const result = await apiServices.put(id, item, options);
+    if (result.success) {
+      if (refetchAfterChange) await fetchData();
+      else setState((prev) => ({ ...prev, loading: false }));
+      if (onSuccess) onSuccess(result.message || "Item replaced successfully!", result.data);
+    } else {
+      setState((prev) => ({ ...prev, loading: false, error: result.error }));
+      if (onError) onError(result.message || "Replace failed", result.error || void 0);
+    }
+    return result;
+  };
   const updateItem = async (id, updatedItem, options) => {
     setState((prev) => ({ ...prev, loading: true }));
     const result = await apiServices.patch(id, updatedItem, options);
@@ -388,19 +482,39 @@ function useApi(axiosInstance, config) {
     }
     return result;
   };
+  const bulkDeleteItem = async (ids, options) => {
+    setState((prev) => ({ ...prev, loading: true }));
+    const result = await apiServices.bulkDelete(ids, options);
+    if (result.success) {
+      if (refetchAfterChange) await fetchData();
+      else setState((prev) => ({ ...prev, loading: false }));
+      if (onSuccess) onSuccess(result.message || "Items deleted successfully!");
+    } else {
+      setState((prev) => ({ ...prev, loading: false, error: result.error }));
+      if (onError) onError(result.message || "Bulk delete failed", result.error || void 0);
+    }
+    return result;
+  };
+  const uploadFile = async (file, additionalData, options) => {
+    setState((prev) => ({ ...prev, loading: true }));
+    const result = await apiServices.upload(file, additionalData, options);
+    if (result.success) {
+      if (refetchAfterChange && options?.refetch !== false) await fetchData();
+      else setState((prev) => ({ ...prev, loading: false }));
+      if (onSuccess) onSuccess(result.message || "File uploaded successfully!", result.data);
+    } else {
+      setState((prev) => ({ ...prev, loading: false, error: result.error }));
+      if (onError) onError(result.message || "Upload failed", result.error || void 0);
+    }
+    return result;
+  };
   const setPage = (page) => setQueryOptions((prev) => ({ ...prev, page }));
   const setLimit = (limit) => setQueryOptions((prev) => ({ ...prev, limit, page: 1 }));
   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;
-    });
+    setQueryOptions((prev) => ({ ...prev, [key]: value, page: key !== "page" ? 1 : prev.page }));
   };
   const resetQuery = () => setQueryOptions(initialQuery);
   return {
@@ -409,8 +523,14 @@ function useApi(axiosInstance, config) {
     actions: {
       fetch: fetchData,
       create: createItem,
+      put: putItem,
+      // <-- NEW
       update: updateItem,
-      remove: deleteItem
+      remove: deleteItem,
+      bulkRemove: bulkDeleteItem,
+      // <-- NEW
+      upload: uploadFile
+      // <-- NEW
     },
     query: {
       options: queryOptions,
@@ -421,7 +541,6 @@ function useApi(axiosInstance, config) {
       setSorting,
       setFilters,
       setQueryParam,
-      // <-- NEW
       reset: resetQuery
     }
   };

package/package.json

@@ -1,40 +1,40 @@
-{
-  "name": "api-core-lib",
-  "version": "4.4.3",
-  "description": "A flexible and powerful API client library for modern web applications.",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
-    "dev": "tsup src/index.ts --format esm,cjs --dts --watch"
-  },
-  "keywords": [
-    "axios",
-    "api",
-    "react",
-    "nextjs",
-    "typescript",
-    "state-management"
-  ],
-  "author": "Your Name",
-  "license": "MIT",
-  "peerDependencies": {
-    "react": ">=17.0.0"
-  },
-  "dependencies": {
-    "axios": "^1.6.8",
-    "axios-retry": "^4.1.0",
-    "uuid": "^9.0.1"
-  },
-  "devDependencies": {
-    "@types/react": "^18.3.2",
-    "@types/uuid": "^9.0.8",
-    "react": "^18.3.1",
-    "tsup": "^8.0.2",
-    "typescript": "^5.4.5"
-  },
-  "files": [
-    "dist"
-  ]
+{
+  "name": "api-core-lib",
+  "version": "5.5.4",
+  "description": "A flexible and powerful API client library for modern web applications.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch"
+  },
+  "keywords": [
+    "axios",
+    "api",
+    "react",
+    "nextjs",
+    "typescript",
+    "state-management"
+  ],
+  "author": "Your Name",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=17.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.6.8",
+    "axios-retry": "^4.1.0",
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.2",
+    "@types/uuid": "^9.0.8",
+    "react": "^18.3.1",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5"
+  },
+  "files": [
+    "dist"
+  ]
 }