api-core-lib 4.4.4 → 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.
@@ -214,12 +238,25 @@ 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;
@@ -283,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']>;
 };
@@ -306,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;
@@ -338,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.
@@ -214,12 +238,25 @@ 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;
@@ -283,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']>;
 };
@@ -306,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;
@@ -338,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,7 +105,9 @@ function createApiClient(config) {
     tokenManager,
     timeout = 15e3,
     headers = {},
-    withCredentials = false
+    withCredentials = false,
+    middleware = [],
+    logger = console
   } = config;
   const axiosInstance = import_axios.default.create({
     baseURL,
@@ -106,66 +118,76 @@ function createApiClient(config) {
   let isRefreshing = false;
   let failedQueue = [];
   const processQueue = (error, token = null) => {
-    failedQueue.forEach((prom) => {
-      if (error) {
-        prom.reject(error);
-      } else {
-        prom.resolve(token);
-      }
-    });
+    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) {
       return req;
     }
+    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 && !isRefreshing) {
       if (config.refreshTokenConfig) {
-        console.log("[API Core] Proactive token refresh initiated.");
+        logger.info("[API Core] Proactive token refresh initiated.");
         isRefreshing = true;
         try {
-          const newTokens = await refreshToken(config, tokenManager);
+          const newTokens = await refreshToken(config, tokenManager, logger);
           if (newTokens) tokens = newTokens;
         } finally {
           isRefreshing = false;
         }
       }
     }
-    if (tokens.accessToken && !tokenManager.isHttpOnly()) {
+    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 && config.refreshTokenConfig) {
+      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) => {
-            if (token && !tokenManager.isHttpOnly()) {
-              originalRequest.headers["Authorization"] = `Bearer ${token}`;
-            }
+            originalRequest.headers["Authorization"] = `Bearer ${token}`;
             return axiosInstance(originalRequest);
           });
         }
         originalRequest._retry = true;
         isRefreshing = true;
         try {
-          const newTokens = await refreshToken(config, tokenManager);
+          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);
-          if (!tokenManager.isHttpOnly()) {
-            originalRequest.headers["Authorization"] = `${newTokens.tokenType || "Bearer"} ${newTokens.accessToken}`;
-          }
+          originalRequest.headers["Authorization"] = `${newTokens.tokenType || "Bearer"} ${newTokens.accessToken}`;
           return axiosInstance(originalRequest);
         } catch (refreshError) {
           processQueue(refreshError, null);
@@ -174,13 +196,7 @@ function createApiClient(config) {
           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;
@@ -222,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,
@@ -235,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,
@@ -251,6 +271,7 @@ var processResponse = (responseOrError) => {
       validationErrors: []
     };
   }
+  log && console.log(`****[ API STATUS 500 ]: *** ${responseOrError} ***  `);
   return {
     data: null,
     rawResponse: void 0,
@@ -350,19 +371,22 @@ function createApiServices(axiosInstance, endpoint) {
 }
 
 // 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);
     }
   };
 }
@@ -370,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;

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,7 +63,9 @@ function createApiClient(config) {
     tokenManager,
     timeout = 15e3,
     headers = {},
-    withCredentials = false
+    withCredentials = false,
+    middleware = [],
+    logger = console
   } = config;
   const axiosInstance = axios.create({
     baseURL,
@@ -64,66 +76,76 @@ function createApiClient(config) {
   let isRefreshing = false;
   let failedQueue = [];
   const processQueue = (error, token = null) => {
-    failedQueue.forEach((prom) => {
-      if (error) {
-        prom.reject(error);
-      } else {
-        prom.resolve(token);
-      }
-    });
+    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) {
       return req;
     }
+    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 && !isRefreshing) {
       if (config.refreshTokenConfig) {
-        console.log("[API Core] Proactive token refresh initiated.");
+        logger.info("[API Core] Proactive token refresh initiated.");
         isRefreshing = true;
         try {
-          const newTokens = await refreshToken(config, tokenManager);
+          const newTokens = await refreshToken(config, tokenManager, logger);
           if (newTokens) tokens = newTokens;
         } finally {
           isRefreshing = false;
         }
       }
     }
-    if (tokens.accessToken && !tokenManager.isHttpOnly()) {
+    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 && config.refreshTokenConfig) {
+      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) => {
-            if (token && !tokenManager.isHttpOnly()) {
-              originalRequest.headers["Authorization"] = `Bearer ${token}`;
-            }
+            originalRequest.headers["Authorization"] = `Bearer ${token}`;
             return axiosInstance(originalRequest);
           });
         }
         originalRequest._retry = true;
         isRefreshing = true;
         try {
-          const newTokens = await refreshToken(config, tokenManager);
+          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);
-          if (!tokenManager.isHttpOnly()) {
-            originalRequest.headers["Authorization"] = `${newTokens.tokenType || "Bearer"} ${newTokens.accessToken}`;
-          }
+          originalRequest.headers["Authorization"] = `${newTokens.tokenType || "Bearer"} ${newTokens.accessToken}`;
           return axiosInstance(originalRequest);
         } catch (refreshError) {
           processQueue(refreshError, null);
@@ -132,13 +154,7 @@ function createApiClient(config) {
           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;
@@ -180,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,
@@ -193,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,
@@ -209,6 +229,7 @@ var processResponse = (responseOrError) => {
       validationErrors: []
     };
   }
+  log && console.log(`****[ API STATUS 500 ]: *** ${responseOrError} ***  `);
   return {
     data: null,
     rawResponse: void 0,
@@ -308,19 +329,22 @@ function createApiServices(axiosInstance, endpoint) {
 }
 
 // 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);
     }
   };
 }
@@ -328,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;

package/package.json

@@ -1,40 +1,40 @@
-{
-  "name": "api-core-lib",
-  "version": "4.4.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"
-  ]
+{
+  "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"
+  ]
 }