api-core-lib 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,145 @@
+import { AxiosRequestConfig, AxiosInstance } from 'axios';
+import * as react from 'react';
+
+interface PaginationMeta {
+    itemsPerPage: number;
+    totalItems: number;
+    currentPage: number;
+    totalPages: number;
+    sortBy?: [string, 'asc' | 'desc'][];
+}
+interface ApiLinks {
+    current: string;
+    first?: string;
+    last?: string;
+    next?: string;
+    prev?: string;
+}
+interface ApiResponse<T = any> {
+    data: T;
+    meta?: PaginationMeta;
+    links?: ApiLinks;
+    message?: string;
+    timestamp?: string;
+}
+interface ValidationError {
+    field: string;
+    message: string;
+    code: string;
+}
+interface ApiError {
+    message: string;
+    status: number;
+    code?: string;
+    errors?: ValidationError[];
+    timestamp?: string;
+    path?: string;
+    requestId?: string;
+}
+interface StandardResponse<T> {
+    response?: ApiResponse<T> | T;
+    error: ApiError | null;
+    loading: boolean;
+    success: boolean;
+    message?: string;
+    cached?: boolean;
+    validationErrors?: ValidationError[];
+}
+interface CacheConfig {
+    enabled: boolean;
+    duration?: number;
+}
+interface RequestConfig extends AxiosRequestConfig {
+    retry?: boolean;
+    retryCount?: number;
+    cache?: boolean | CacheConfig;
+    cancelTokenKey?: string;
+}
+interface ApiClientConfig {
+    baseURL: string;
+    timeout?: number;
+    headers?: Record<string, string>;
+    getAccessToken?: () => string | null | Promise<string | null>;
+    getRefreshToken?: () => string | null | Promise<string | null>;
+    handleTokenRefresh?: (refreshToken: string) => Promise<{
+        newAccessToken: string;
+        newRefreshToken: string;
+    }>;
+    onTokenRefreshSuccess?: (newAccessToken: string, newRefreshToken: string) => void;
+    onTokenRefreshError?: (error: any) => void;
+}
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+interface PaginateQueryOptions {
+    page?: number;
+    limit?: number;
+    search?: string;
+    sortBy?: {
+        key: string;
+        direction: 'asc' | 'desc';
+    }[];
+    filter?: Record<string, any>;
+    [key: string]: any;
+}
+interface UseApiConfig<T> {
+    endpoint: string;
+    reduxKey?: string;
+    initialData?: T | T[];
+    initialQuery?: PaginateQueryOptions;
+    enabled?: boolean;
+    refetchAfterChange?: boolean;
+    isToastAfterActions?: boolean;
+    onSuccess?: (message: string, data?: T) => void;
+    onError?: (message: string, error?: ApiError) => void;
+}
+
+declare function createApiClient(config: ApiClientConfig): AxiosInstance;
+
+declare class CacheManager {
+    private cache;
+    private defaultDuration;
+    set<T>(key: string, data: T, duration?: number): void;
+    get<T>(key: string): T | null;
+    delete(key: string): void;
+    clear(): void;
+}
+declare const cacheManager: CacheManager;
+
+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>>;
+};
+
+declare const cancelRequest: (key: string) => void;
+declare const cancelAllRequests: () => void;
+declare function buildPaginateQuery(query: PaginateQueryOptions): string;
+
+declare function useApi<T extends {
+    id?: string | number;
+}>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): {
+    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>>;
+    };
+    query: {
+        options: PaginateQueryOptions;
+        setOptions: react.Dispatch<react.SetStateAction<PaginateQueryOptions>>;
+        setPage: (page: number) => void;
+        setLimit: (limit: number) => void;
+        setSearchTerm: (search: string) => void;
+        setSorting: (sortBy: {
+            key: string;
+            direction: "asc" | "desc";
+        }[]) => void;
+        setFilters: (filter: Record<string, any>) => void;
+        reset: () => void;
+    };
+};
+
+export { type ApiClientConfig, type ApiError, type ApiLinks, type ApiResponse, type CacheConfig, type HttpMethod, type PaginateQueryOptions, type PaginationMeta, type RequestConfig, type StandardResponse, type UseApiConfig, type ValidationError, buildPaginateQuery, cacheManager, cancelAllRequests, cancelRequest, createApiClient, createApiServices, useApi };

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+import { AxiosRequestConfig, AxiosInstance } from 'axios';
+import * as react from 'react';
+
+interface PaginationMeta {
+    itemsPerPage: number;
+    totalItems: number;
+    currentPage: number;
+    totalPages: number;
+    sortBy?: [string, 'asc' | 'desc'][];
+}
+interface ApiLinks {
+    current: string;
+    first?: string;
+    last?: string;
+    next?: string;
+    prev?: string;
+}
+interface ApiResponse<T = any> {
+    data: T;
+    meta?: PaginationMeta;
+    links?: ApiLinks;
+    message?: string;
+    timestamp?: string;
+}
+interface ValidationError {
+    field: string;
+    message: string;
+    code: string;
+}
+interface ApiError {
+    message: string;
+    status: number;
+    code?: string;
+    errors?: ValidationError[];
+    timestamp?: string;
+    path?: string;
+    requestId?: string;
+}
+interface StandardResponse<T> {
+    response?: ApiResponse<T> | T;
+    error: ApiError | null;
+    loading: boolean;
+    success: boolean;
+    message?: string;
+    cached?: boolean;
+    validationErrors?: ValidationError[];
+}
+interface CacheConfig {
+    enabled: boolean;
+    duration?: number;
+}
+interface RequestConfig extends AxiosRequestConfig {
+    retry?: boolean;
+    retryCount?: number;
+    cache?: boolean | CacheConfig;
+    cancelTokenKey?: string;
+}
+interface ApiClientConfig {
+    baseURL: string;
+    timeout?: number;
+    headers?: Record<string, string>;
+    getAccessToken?: () => string | null | Promise<string | null>;
+    getRefreshToken?: () => string | null | Promise<string | null>;
+    handleTokenRefresh?: (refreshToken: string) => Promise<{
+        newAccessToken: string;
+        newRefreshToken: string;
+    }>;
+    onTokenRefreshSuccess?: (newAccessToken: string, newRefreshToken: string) => void;
+    onTokenRefreshError?: (error: any) => void;
+}
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+interface PaginateQueryOptions {
+    page?: number;
+    limit?: number;
+    search?: string;
+    sortBy?: {
+        key: string;
+        direction: 'asc' | 'desc';
+    }[];
+    filter?: Record<string, any>;
+    [key: string]: any;
+}
+interface UseApiConfig<T> {
+    endpoint: string;
+    reduxKey?: string;
+    initialData?: T | T[];
+    initialQuery?: PaginateQueryOptions;
+    enabled?: boolean;
+    refetchAfterChange?: boolean;
+    isToastAfterActions?: boolean;
+    onSuccess?: (message: string, data?: T) => void;
+    onError?: (message: string, error?: ApiError) => void;
+}
+
+declare function createApiClient(config: ApiClientConfig): AxiosInstance;
+
+declare class CacheManager {
+    private cache;
+    private defaultDuration;
+    set<T>(key: string, data: T, duration?: number): void;
+    get<T>(key: string): T | null;
+    delete(key: string): void;
+    clear(): void;
+}
+declare const cacheManager: CacheManager;
+
+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>>;
+};
+
+declare const cancelRequest: (key: string) => void;
+declare const cancelAllRequests: () => void;
+declare function buildPaginateQuery(query: PaginateQueryOptions): string;
+
+declare function useApi<T extends {
+    id?: string | number;
+}>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): {
+    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>>;
+    };
+    query: {
+        options: PaginateQueryOptions;
+        setOptions: react.Dispatch<react.SetStateAction<PaginateQueryOptions>>;
+        setPage: (page: number) => void;
+        setLimit: (limit: number) => void;
+        setSearchTerm: (search: string) => void;
+        setSorting: (sortBy: {
+            key: string;
+            direction: "asc" | "desc";
+        }[]) => void;
+        setFilters: (filter: Record<string, any>) => void;
+        reset: () => void;
+    };
+};
+
+export { type ApiClientConfig, type ApiError, type ApiLinks, type ApiResponse, type CacheConfig, type HttpMethod, type PaginateQueryOptions, type PaginationMeta, type RequestConfig, type StandardResponse, type UseApiConfig, type ValidationError, buildPaginateQuery, cacheManager, cancelAllRequests, cancelRequest, createApiClient, createApiServices, useApi };

package/dist/index.js

@@ -0,0 +1,440 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  buildPaginateQuery: () => buildPaginateQuery,
+  cacheManager: () => cacheManager,
+  cancelAllRequests: () => cancelAllRequests,
+  cancelRequest: () => cancelRequest,
+  createApiClient: () => createApiClient,
+  createApiServices: () => createApiServices,
+  useApi: () => useApi
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/client.ts
+var import_axios2 = __toESM(require("axios"));
+var import_axios_retry = __toESM(require("axios-retry"));
+var import_uuid = require("uuid");
+
+// src/core/cache.ts
+var CacheManager = class {
+  cache = /* @__PURE__ */ new Map();
+  defaultDuration = 15 * 60 * 1e3;
+  // 15 minutes
+  set(key, data, duration) {
+    this.cache.set(key, {
+      data,
+      timestamp: Date.now(),
+      duration: duration || this.defaultDuration
+    });
+  }
+  get(key) {
+    const item = this.cache.get(key);
+    if (!item) return null;
+    const isExpired = Date.now() - item.timestamp > item.duration;
+    if (isExpired) {
+      this.cache.delete(key);
+      return null;
+    }
+    return item.data;
+  }
+  delete(key) {
+    this.cache.delete(key);
+  }
+  clear() {
+    this.cache.clear();
+  }
+};
+var cacheManager = new CacheManager();
+
+// src/core/utils.ts
+var import_axios = __toESM(require("axios"));
+var cancelTokens = /* @__PURE__ */ new Map();
+var createCancelToken = (key) => {
+  const existingToken = cancelTokens.get(key);
+  if (existingToken) {
+    existingToken.cancel("Operation canceled due to new request.");
+    cancelTokens.delete(key);
+  }
+  const source = import_axios.default.CancelToken.source();
+  cancelTokens.set(key, source);
+  return source;
+};
+var cancelRequest = (key) => {
+  const source = cancelTokens.get(key);
+  if (source) {
+    source.cancel("Operation canceled by user.");
+    cancelTokens.delete(key);
+  }
+};
+var cancelAllRequests = () => {
+  cancelTokens.forEach((source) => source.cancel("All operations canceled."));
+  cancelTokens.clear();
+};
+function buildPaginateQuery(query) {
+  const params = new URLSearchParams();
+  if (!query) return "";
+  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);
+  if (query.sortBy) {
+    query.sortBy.forEach((sort) => params.append("sortBy", `${sort.key}:${sort.direction}`));
+  }
+  if (query.filter) {
+    Object.entries(query.filter).forEach(([field, value]) => {
+      params.append(`filter.${field}`, value);
+    });
+  }
+  const queryString = params.toString();
+  return queryString ? `?${queryString}` : "";
+}
+function isApiError(obj) {
+  return obj && typeof obj.status === "number" && typeof obj.message === "string" && obj.config === void 0;
+}
+function isAxiosResponse(obj) {
+  return obj && obj.data !== void 0 && obj.status !== void 0 && obj.config !== void 0;
+}
+
+// src/core/client.ts
+function createApiClient(config) {
+  const {
+    baseURL,
+    timeout = 1e4,
+    headers = {},
+    getAccessToken,
+    getRefreshToken,
+    handleTokenRefresh,
+    onTokenRefreshSuccess,
+    onTokenRefreshError
+  } = config;
+  const axiosInstance = import_axios2.default.create({
+    baseURL,
+    timeout,
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      ...headers
+    },
+    withCredentials: true
+  });
+  (0, import_axios_retry.default)(axiosInstance, {
+    retries: 3,
+    retryDelay: import_axios_retry.default.exponentialDelay,
+    retryCondition: (error) => import_axios_retry.default.isNetworkOrIdempotentRequestError(error) || error.response?.status === 429
+  });
+  let isRefreshing = false;
+  let requestQueue = [];
+  axiosInstance.interceptors.request.use(async (req) => {
+    req.headers["X-Request-ID"] = (0, import_uuid.v4)();
+    if (getAccessToken) {
+      const token = await getAccessToken();
+      if (token) {
+        req.headers.Authorization = `Bearer ${token}`;
+      }
+    }
+    if (req.cancelTokenKey) {
+      req.cancelToken = createCancelToken(req.cancelTokenKey).token;
+    }
+    if (req.method?.toLowerCase() === "get" && req.cache) {
+      const cacheKey = req.url || "default-cache-key";
+      const cachedData = cacheManager.get(cacheKey);
+      if (cachedData) {
+        console.log(`[Cache] HIT for ${cacheKey}`);
+        req.adapter = () => Promise.resolve({
+          data: cachedData,
+          status: 200,
+          statusText: "OK (from cache)",
+          headers: req.headers,
+          config: req
+        });
+        req.cached = true;
+      }
+    }
+    return req;
+  }, (error) => Promise.reject(error));
+  axiosInstance.interceptors.response.use(
+    (response) => {
+      const config2 = response.config;
+      if (response.config.method?.toLowerCase() === "get" && config2.cache) {
+        const cacheKey = response.config.url || "default-cache-key";
+        const cacheConfig = typeof config2.cache === "object" ? config2.cache : { enabled: true };
+        if (cacheConfig.enabled) {
+          console.log(`[Cache] SET for ${cacheKey}`);
+          cacheManager.set(cacheKey, response.data, cacheConfig.duration);
+        }
+      }
+      return response;
+    },
+    async (error) => {
+      const originalRequest = error.config;
+      if (error.response?.status === 401 && !originalRequest._retry && getRefreshToken && handleTokenRefresh) {
+        originalRequest._retry = true;
+        if (isRefreshing) {
+          return new Promise((resolve) => {
+            requestQueue.push((token) => {
+              originalRequest.headers.Authorization = `Bearer ${token}`;
+              resolve(axiosInstance(originalRequest));
+            });
+          });
+        }
+        isRefreshing = true;
+        try {
+          const currentRefreshToken = await getRefreshToken();
+          if (!currentRefreshToken) throw new Error("No refresh token available.");
+          const { newAccessToken, newRefreshToken } = await handleTokenRefresh(currentRefreshToken);
+          if (onTokenRefreshSuccess) {
+            onTokenRefreshSuccess(newAccessToken, newRefreshToken);
+          }
+          axiosInstance.defaults.headers.common["Authorization"] = `Bearer ${newAccessToken}`;
+          originalRequest.headers.Authorization = `Bearer ${newAccessToken}`;
+          requestQueue.forEach((cb) => cb(newAccessToken));
+          requestQueue = [];
+          return axiosInstance(originalRequest);
+        } catch (refreshError) {
+          if (onTokenRefreshError) {
+            onTokenRefreshError(refreshError);
+          }
+          requestQueue = [];
+          return Promise.reject(refreshError);
+        } finally {
+          isRefreshing = false;
+        }
+      }
+      const enhancedError = {
+        message: error.response?.data?.message || error.message || "An unexpected error occurred",
+        status: error.response?.status || 500,
+        code: error.code,
+        errors: error.response?.data?.errors,
+        path: originalRequest.url,
+        requestId: originalRequest.headers?.["X-Request-ID"]
+      };
+      return Promise.reject(enhancedError);
+    }
+  );
+  return axiosInstance;
+}
+
+// src/core/processor.ts
+var processResponse = (responseOrError) => {
+  if (isApiError(responseOrError)) {
+    return {
+      response: void 0,
+      error: responseOrError,
+      validationErrors: responseOrError.errors || [],
+      success: false,
+      loading: false,
+      message: responseOrError.message
+    };
+  }
+  if (isAxiosResponse(responseOrError)) {
+    const response = responseOrError;
+    const isSuccess = response.status >= 200 && response.status < 300;
+    if (isSuccess) {
+      return {
+        response: response.data,
+        loading: false,
+        success: true,
+        cached: response.config.cached,
+        error: null,
+        validationErrors: [],
+        message: response.data.message || "Request successful."
+      };
+    }
+  }
+  return {
+    response: void 0,
+    error: {
+      message: "An unknown error occurred during response processing.",
+      status: 500
+    },
+    success: false,
+    loading: false
+  };
+};
+
+// src/services/crud.ts
+function createApiServices(axiosInstance, endpoint) {
+  const get = async (id, config) => {
+    const url = id ? `${endpoint}/${id}` : endpoint;
+    try {
+      const response = await axiosInstance.get(url, config);
+      return processResponse(response);
+    } catch (error) {
+      return processResponse(error);
+    }
+  };
+  const getWithQuery = async (query, config) => {
+    try {
+      const response = await axiosInstance.get(`${endpoint}${query}`, config);
+      return processResponse(response);
+    } catch (error) {
+      return processResponse(error);
+    }
+  };
+  const post = async (data, config) => {
+    try {
+      const response = await axiosInstance.post(endpoint, data, config);
+      return processResponse(response);
+    } catch (error) {
+      return processResponse(error);
+    }
+  };
+  const patch = async (id, data, config) => {
+    try {
+      const response = await axiosInstance.patch(`${endpoint}/${id}`, data, config);
+      return processResponse(response);
+    } catch (error) {
+      return processResponse(error);
+    }
+  };
+  const remove = async (id, config) => {
+    try {
+      const response = await axiosInstance.delete(`${endpoint}/${id}`, config);
+      return processResponse(response);
+    } catch (error) {
+      return processResponse(error);
+    }
+  };
+  return { get, getWithQuery, post, patch, remove };
+}
+
+// src/hooks/useApi.ts
+var import_react = require("react");
+function useApi(axiosInstance, config) {
+  const {
+    endpoint,
+    initialData,
+    initialQuery = { page: 1, limit: 10 },
+    enabled = true,
+    refetchAfterChange = true,
+    onSuccess,
+    onError
+  } = config;
+  const [state, setState] = (0, import_react.useState)({
+    response: initialData || void 0,
+    loading: enabled,
+    error: null,
+    success: false
+  });
+  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 () => {
+    setState((prev) => ({ ...prev, loading: true, error: null }));
+    const queryString = buildPaginateQuery(queryOptions);
+    const result = await apiServices.getWithQuery(queryString, { cancelTokenKey: endpoint });
+    setState(result);
+    if (!result.success && onError) {
+      onError(result.message || "Fetch failed", result.error || void 0);
+    }
+  }, [apiServices, queryOptions, endpoint, onError]);
+  (0, import_react.useEffect)(() => {
+    if (enabled) {
+      fetchData();
+    }
+  }, [enabled, queryOptions]);
+  const createItem = async (newItem) => {
+    setState((prev) => ({ ...prev, loading: true }));
+    const result = await apiServices.post(newItem);
+    if (result.success) {
+      if (refetchAfterChange) await fetchData();
+      else setState((prev) => ({ ...prev, loading: false }));
+      if (onSuccess) onSuccess(result.message || "Item created successfully!", result.response);
+    } else {
+      setState((prev) => ({ ...prev, loading: false, error: result.error }));
+      if (onError) onError(result.message || "Create failed", result.error || void 0);
+    }
+    return result;
+  };
+  const updateItem = async (id, updatedItem) => {
+    setState((prev) => ({ ...prev, loading: true }));
+    const result = await apiServices.patch(id, updatedItem);
+    if (result.success) {
+      if (refetchAfterChange) await fetchData();
+      else setState((prev) => ({ ...prev, loading: false }));
+      if (onSuccess) onSuccess(result.message || "Item updated successfully!", result.response);
+    } else {
+      setState((prev) => ({ ...prev, loading: false, error: result.error }));
+      if (onError) onError(result.message || "Update failed", result.error || void 0);
+    }
+    return result;
+  };
+  const deleteItem = async (id) => {
+    setState((prev) => ({ ...prev, loading: true }));
+    const result = await apiServices.remove(id);
+    if (result.success) {
+      if (refetchAfterChange) await fetchData();
+      else setState((prev) => ({ ...prev, loading: false }));
+      if (onSuccess) onSuccess(result.message || "Item deleted successfully!");
+    } else {
+      setState((prev) => ({ ...prev, loading: false, error: result.error }));
+      if (onError) onError(result.message || "Delete 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 resetQuery = () => setQueryOptions(initialQuery);
+  return {
+    state,
+    setState,
+    // Exposing setState for direct manipulation or connection to Redux
+    actions: {
+      fetch: fetchData,
+      create: createItem,
+      update: updateItem,
+      remove: deleteItem
+    },
+    query: {
+      options: queryOptions,
+      setOptions: setQueryOptions,
+      setPage,
+      setLimit,
+      setSearchTerm,
+      setSorting,
+      setFilters,
+      reset: resetQuery
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildPaginateQuery,
+  cacheManager,
+  cancelAllRequests,
+  cancelRequest,
+  createApiClient,
+  createApiServices,
+  useApi
+});

package/dist/index.mjs

@@ -0,0 +1,397 @@
+// src/core/client.ts
+import axios2 from "axios";
+import axiosRetry from "axios-retry";
+import { v4 as uuidv4 } from "uuid";
+
+// src/core/cache.ts
+var CacheManager = class {
+  cache = /* @__PURE__ */ new Map();
+  defaultDuration = 15 * 60 * 1e3;
+  // 15 minutes
+  set(key, data, duration) {
+    this.cache.set(key, {
+      data,
+      timestamp: Date.now(),
+      duration: duration || this.defaultDuration
+    });
+  }
+  get(key) {
+    const item = this.cache.get(key);
+    if (!item) return null;
+    const isExpired = Date.now() - item.timestamp > item.duration;
+    if (isExpired) {
+      this.cache.delete(key);
+      return null;
+    }
+    return item.data;
+  }
+  delete(key) {
+    this.cache.delete(key);
+  }
+  clear() {
+    this.cache.clear();
+  }
+};
+var cacheManager = new CacheManager();
+
+// src/core/utils.ts
+import axios from "axios";
+var cancelTokens = /* @__PURE__ */ new Map();
+var createCancelToken = (key) => {
+  const existingToken = cancelTokens.get(key);
+  if (existingToken) {
+    existingToken.cancel("Operation canceled due to new request.");
+    cancelTokens.delete(key);
+  }
+  const source = axios.CancelToken.source();
+  cancelTokens.set(key, source);
+  return source;
+};
+var cancelRequest = (key) => {
+  const source = cancelTokens.get(key);
+  if (source) {
+    source.cancel("Operation canceled by user.");
+    cancelTokens.delete(key);
+  }
+};
+var cancelAllRequests = () => {
+  cancelTokens.forEach((source) => source.cancel("All operations canceled."));
+  cancelTokens.clear();
+};
+function buildPaginateQuery(query) {
+  const params = new URLSearchParams();
+  if (!query) return "";
+  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);
+  if (query.sortBy) {
+    query.sortBy.forEach((sort) => params.append("sortBy", `${sort.key}:${sort.direction}`));
+  }
+  if (query.filter) {
+    Object.entries(query.filter).forEach(([field, value]) => {
+      params.append(`filter.${field}`, value);
+    });
+  }
+  const queryString = params.toString();
+  return queryString ? `?${queryString}` : "";
+}
+function isApiError(obj) {
+  return obj && typeof obj.status === "number" && typeof obj.message === "string" && obj.config === void 0;
+}
+function isAxiosResponse(obj) {
+  return obj && obj.data !== void 0 && obj.status !== void 0 && obj.config !== void 0;
+}
+
+// src/core/client.ts
+function createApiClient(config) {
+  const {
+    baseURL,
+    timeout = 1e4,
+    headers = {},
+    getAccessToken,
+    getRefreshToken,
+    handleTokenRefresh,
+    onTokenRefreshSuccess,
+    onTokenRefreshError
+  } = config;
+  const axiosInstance = axios2.create({
+    baseURL,
+    timeout,
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      ...headers
+    },
+    withCredentials: true
+  });
+  axiosRetry(axiosInstance, {
+    retries: 3,
+    retryDelay: axiosRetry.exponentialDelay,
+    retryCondition: (error) => axiosRetry.isNetworkOrIdempotentRequestError(error) || error.response?.status === 429
+  });
+  let isRefreshing = false;
+  let requestQueue = [];
+  axiosInstance.interceptors.request.use(async (req) => {
+    req.headers["X-Request-ID"] = uuidv4();
+    if (getAccessToken) {
+      const token = await getAccessToken();
+      if (token) {
+        req.headers.Authorization = `Bearer ${token}`;
+      }
+    }
+    if (req.cancelTokenKey) {
+      req.cancelToken = createCancelToken(req.cancelTokenKey).token;
+    }
+    if (req.method?.toLowerCase() === "get" && req.cache) {
+      const cacheKey = req.url || "default-cache-key";
+      const cachedData = cacheManager.get(cacheKey);
+      if (cachedData) {
+        console.log(`[Cache] HIT for ${cacheKey}`);
+        req.adapter = () => Promise.resolve({
+          data: cachedData,
+          status: 200,
+          statusText: "OK (from cache)",
+          headers: req.headers,
+          config: req
+        });
+        req.cached = true;
+      }
+    }
+    return req;
+  }, (error) => Promise.reject(error));
+  axiosInstance.interceptors.response.use(
+    (response) => {
+      const config2 = response.config;
+      if (response.config.method?.toLowerCase() === "get" && config2.cache) {
+        const cacheKey = response.config.url || "default-cache-key";
+        const cacheConfig = typeof config2.cache === "object" ? config2.cache : { enabled: true };
+        if (cacheConfig.enabled) {
+          console.log(`[Cache] SET for ${cacheKey}`);
+          cacheManager.set(cacheKey, response.data, cacheConfig.duration);
+        }
+      }
+      return response;
+    },
+    async (error) => {
+      const originalRequest = error.config;
+      if (error.response?.status === 401 && !originalRequest._retry && getRefreshToken && handleTokenRefresh) {
+        originalRequest._retry = true;
+        if (isRefreshing) {
+          return new Promise((resolve) => {
+            requestQueue.push((token) => {
+              originalRequest.headers.Authorization = `Bearer ${token}`;
+              resolve(axiosInstance(originalRequest));
+            });
+          });
+        }
+        isRefreshing = true;
+        try {
+          const currentRefreshToken = await getRefreshToken();
+          if (!currentRefreshToken) throw new Error("No refresh token available.");
+          const { newAccessToken, newRefreshToken } = await handleTokenRefresh(currentRefreshToken);
+          if (onTokenRefreshSuccess) {
+            onTokenRefreshSuccess(newAccessToken, newRefreshToken);
+          }
+          axiosInstance.defaults.headers.common["Authorization"] = `Bearer ${newAccessToken}`;
+          originalRequest.headers.Authorization = `Bearer ${newAccessToken}`;
+          requestQueue.forEach((cb) => cb(newAccessToken));
+          requestQueue = [];
+          return axiosInstance(originalRequest);
+        } catch (refreshError) {
+          if (onTokenRefreshError) {
+            onTokenRefreshError(refreshError);
+          }
+          requestQueue = [];
+          return Promise.reject(refreshError);
+        } finally {
+          isRefreshing = false;
+        }
+      }
+      const enhancedError = {
+        message: error.response?.data?.message || error.message || "An unexpected error occurred",
+        status: error.response?.status || 500,
+        code: error.code,
+        errors: error.response?.data?.errors,
+        path: originalRequest.url,
+        requestId: originalRequest.headers?.["X-Request-ID"]
+      };
+      return Promise.reject(enhancedError);
+    }
+  );
+  return axiosInstance;
+}
+
+// src/core/processor.ts
+var processResponse = (responseOrError) => {
+  if (isApiError(responseOrError)) {
+    return {
+      response: void 0,
+      error: responseOrError,
+      validationErrors: responseOrError.errors || [],
+      success: false,
+      loading: false,
+      message: responseOrError.message
+    };
+  }
+  if (isAxiosResponse(responseOrError)) {
+    const response = responseOrError;
+    const isSuccess = response.status >= 200 && response.status < 300;
+    if (isSuccess) {
+      return {
+        response: response.data,
+        loading: false,
+        success: true,
+        cached: response.config.cached,
+        error: null,
+        validationErrors: [],
+        message: response.data.message || "Request successful."
+      };
+    }
+  }
+  return {
+    response: void 0,
+    error: {
+      message: "An unknown error occurred during response processing.",
+      status: 500
+    },
+    success: false,
+    loading: false
+  };
+};
+
+// src/services/crud.ts
+function createApiServices(axiosInstance, endpoint) {
+  const get = async (id, config) => {
+    const url = id ? `${endpoint}/${id}` : endpoint;
+    try {
+      const response = await axiosInstance.get(url, config);
+      return processResponse(response);
+    } catch (error) {
+      return processResponse(error);
+    }
+  };
+  const getWithQuery = async (query, config) => {
+    try {
+      const response = await axiosInstance.get(`${endpoint}${query}`, config);
+      return processResponse(response);
+    } catch (error) {
+      return processResponse(error);
+    }
+  };
+  const post = async (data, config) => {
+    try {
+      const response = await axiosInstance.post(endpoint, data, config);
+      return processResponse(response);
+    } catch (error) {
+      return processResponse(error);
+    }
+  };
+  const patch = async (id, data, config) => {
+    try {
+      const response = await axiosInstance.patch(`${endpoint}/${id}`, data, config);
+      return processResponse(response);
+    } catch (error) {
+      return processResponse(error);
+    }
+  };
+  const remove = async (id, config) => {
+    try {
+      const response = await axiosInstance.delete(`${endpoint}/${id}`, config);
+      return processResponse(response);
+    } catch (error) {
+      return processResponse(error);
+    }
+  };
+  return { get, getWithQuery, post, patch, remove };
+}
+
+// src/hooks/useApi.ts
+import { useState, useEffect, useCallback, useRef } from "react";
+function useApi(axiosInstance, config) {
+  const {
+    endpoint,
+    initialData,
+    initialQuery = { page: 1, limit: 10 },
+    enabled = true,
+    refetchAfterChange = true,
+    onSuccess,
+    onError
+  } = config;
+  const [state, setState] = useState({
+    response: initialData || void 0,
+    loading: enabled,
+    error: null,
+    success: false
+  });
+  const [queryOptions, setQueryOptions] = useState(initialQuery);
+  const apiServices = useRef(createApiServices(axiosInstance, endpoint)).current;
+  const fetchData = useCallback(async () => {
+    setState((prev) => ({ ...prev, loading: true, error: null }));
+    const queryString = buildPaginateQuery(queryOptions);
+    const result = await apiServices.getWithQuery(queryString, { cancelTokenKey: endpoint });
+    setState(result);
+    if (!result.success && onError) {
+      onError(result.message || "Fetch failed", result.error || void 0);
+    }
+  }, [apiServices, queryOptions, endpoint, onError]);
+  useEffect(() => {
+    if (enabled) {
+      fetchData();
+    }
+  }, [enabled, queryOptions]);
+  const createItem = async (newItem) => {
+    setState((prev) => ({ ...prev, loading: true }));
+    const result = await apiServices.post(newItem);
+    if (result.success) {
+      if (refetchAfterChange) await fetchData();
+      else setState((prev) => ({ ...prev, loading: false }));
+      if (onSuccess) onSuccess(result.message || "Item created successfully!", result.response);
+    } else {
+      setState((prev) => ({ ...prev, loading: false, error: result.error }));
+      if (onError) onError(result.message || "Create failed", result.error || void 0);
+    }
+    return result;
+  };
+  const updateItem = async (id, updatedItem) => {
+    setState((prev) => ({ ...prev, loading: true }));
+    const result = await apiServices.patch(id, updatedItem);
+    if (result.success) {
+      if (refetchAfterChange) await fetchData();
+      else setState((prev) => ({ ...prev, loading: false }));
+      if (onSuccess) onSuccess(result.message || "Item updated successfully!", result.response);
+    } else {
+      setState((prev) => ({ ...prev, loading: false, error: result.error }));
+      if (onError) onError(result.message || "Update failed", result.error || void 0);
+    }
+    return result;
+  };
+  const deleteItem = async (id) => {
+    setState((prev) => ({ ...prev, loading: true }));
+    const result = await apiServices.remove(id);
+    if (result.success) {
+      if (refetchAfterChange) await fetchData();
+      else setState((prev) => ({ ...prev, loading: false }));
+      if (onSuccess) onSuccess(result.message || "Item deleted successfully!");
+    } else {
+      setState((prev) => ({ ...prev, loading: false, error: result.error }));
+      if (onError) onError(result.message || "Delete 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 resetQuery = () => setQueryOptions(initialQuery);
+  return {
+    state,
+    setState,
+    // Exposing setState for direct manipulation or connection to Redux
+    actions: {
+      fetch: fetchData,
+      create: createItem,
+      update: updateItem,
+      remove: deleteItem
+    },
+    query: {
+      options: queryOptions,
+      setOptions: setQueryOptions,
+      setPage,
+      setLimit,
+      setSearchTerm,
+      setSorting,
+      setFilters,
+      reset: resetQuery
+    }
+  };
+}
+export {
+  buildPaginateQuery,
+  cacheManager,
+  cancelAllRequests,
+  cancelRequest,
+  createApiClient,
+  createApiServices,
+  useApi
+};

package/package.json

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