api-core-lib 3.2.2 → 3.3.3

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { ResponseType, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, AxiosResponse } from 'axios';
+import { ResponseType, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method, AxiosResponse } from 'axios';
 import * as react from 'react';
 
 /**
@@ -18,15 +18,6 @@ interface PaginationMeta {
     currentPage: number;
     totalPages: number;
 }
-/**
- * يمثل بنية الاستجابة القياسية من الـ API.
- * @template T نوع البيانات الأساسية في الاستجابة.
- */
-interface ApiResponse<T = any> {
-    data: T;
-    message?: string;
-    meta?: PaginationMeta;
-}
 /**
  * يمثل خطأ التحقق من صحة حقل معين.
  */
@@ -44,18 +35,6 @@ interface ApiError {
     errors?: ValidationError[];
     requestId?: string;
 }
-/**
- * يمثل كائن الاستجابة الموحد الذي يرجعه كل طلب.
- * @template T نوع البيانات المتوقعة في حالة النجاح.
- */
-interface StandardResponse<T> {
-    response?: ApiResponse<T> | T;
-    error: ApiError | null;
-    loading: boolean;
-    success: boolean;
-    message?: string;
-    validationErrors?: ValidationError[];
-}
 /**
  * يمثل مجموعة التوكنات التي يتم إدارتها.
  */
@@ -96,19 +75,6 @@ interface PaginateQueryOptions {
     }[];
     filter?: Record<string, any>;
 }
-/**
- * واجهة لتهيئة الهوك `useApi`.
- * @template T نوع البيانات التي يتعامل معها الهوك.
- */
-interface UseApiConfig<T> {
-    endpoint: string;
-    initialData?: T | T[];
-    initialQuery?: PaginateQueryOptions;
-    enabled?: boolean;
-    refetchAfterChange?: boolean;
-    onSuccess?: (message: string, data?: T) => void;
-    onError?: (message: string, error?: ApiError) => void;
-}
 /**
  * واجهة لتخصيص عملية تجديد التوكن بشكل كامل.
  */
@@ -162,6 +128,82 @@ interface ApiClientConfig {
     refreshTokenConfig?: RefreshTokenConfig;
     onRefreshError?: (error: any) => void;
 }
+/**
+ * يمثل بنية الاستجابة القياسية من الـ API.
+ * @template T نوع البيانات الأساسية في الاستجابة.
+ */
+interface ApiResponse<T = any> {
+    data: T;
+    message?: string;
+    meta?: PaginationMeta;
+}
+/**
+ * يمثل بنية الاستجابة القياسية المغلفة التي قد تأتي من بعض نقاط الـ API.
+ * @template T نوع البيانات الأساسية في الاستجابة.
+ */
+interface ApiResponse<T = any> {
+    data: T;
+    message?: string;
+    meta?: PaginationMeta;
+    success?: boolean;
+}
+/**
+ * يمثل كائن الاستجابة الموحد والنهائي الذي يرجعه كل طلب.
+ * هذا هو النوع الذي ستتعامل معه دائمًا.
+ * @template T نوع البيانات النهائية التي تريد الوصول إليها.
+ */
+interface StandardResponse<T> {
+    data: T | null;
+    rawResponse: any;
+    error: ApiError | null;
+    loading: boolean;
+    success: boolean;
+    message?: string;
+    validationErrors?: ValidationError[];
+}
+/**
+ * NEW: واجهة استعلام مرنة تسمح بالبارامترات القياسية (للفلترة والترقيم)
+ * بالإضافة إلى أي بارامترات مخصصة أخرى عبر الـ index signature.
+ * @example
+ * { page: 1, limit: 10, search: 'term', status: 'published', authorId: 123 }
+ */
+interface QueryOptions {
+    page?: number;
+    limit?: number;
+    search?: string;
+    sortBy?: {
+        key: string;
+        direction: 'asc' | 'desc';
+    }[];
+    filter?: Record<string, any>;
+    [key: string]: any;
+}
+/**
+ * NEW: واجهة لتمرير خيارات إضافية لدوال الأكشن (create, update, remove).
+ */
+interface ActionOptions {
+    /**
+     * يسمح لك بتجاوز الـ endpoint الافتراضي المحدد في الهوك.
+     * مفيد لإرسال طلبات لنقاط نهاية متخصصة.
+     * @example
+     * // لتحديث عنصر وتغيير حالته عبر مسار مختلف
+     * update('123', { status: 'active' }, { endpoint: '/items/123/activate' })
+     */
+    endpoint?: string;
+}
+/**
+ * واجهة لتهيئة الهوك `useApi`.
+ * @template T نوع البيانات التي يتعامل معها الهوك.
+ */
+interface UseApiConfig<T> {
+    endpoint: string;
+    initialData?: T | T[];
+    initialQuery?: QueryOptions;
+    enabled?: boolean;
+    refetchAfterChange?: boolean;
+    onSuccess?: (message: string, data?: T) => void;
+    onError?: (message: string, error?: ApiError) => void;
+}
 
 /**
  * @file src/core/client.ts
@@ -173,12 +215,13 @@ interface ApiClientConfig {
 
 declare function createApiClient(config: ApiClientConfig): AxiosInstance;
 
+type CrudRequestConfig = RequestConfig & ActionOptions;
 declare function createApiServices<T>(axiosInstance: AxiosInstance, endpoint: string): {
     get: (id?: string, config?: RequestConfig) => Promise<StandardResponse<T | T[]>>;
     getWithQuery: (query: string, config?: RequestConfig) => Promise<StandardResponse<T[]>>;
-    post: (data: Partial<T>, config?: RequestConfig) => Promise<StandardResponse<T>>;
-    patch: (id: string, data: Partial<T>, config?: RequestConfig) => Promise<StandardResponse<T>>;
-    remove: (id: string, config?: RequestConfig) => Promise<StandardResponse<any>>;
+    post: (data: Partial<T>, config?: CrudRequestConfig) => Promise<StandardResponse<T>>;
+    patch: (id: string, data: Partial<T>, config?: CrudRequestConfig) => Promise<StandardResponse<T>>;
+    remove: (id: string, config?: CrudRequestConfig) => Promise<StandardResponse<any>>;
 };
 
 /**
@@ -189,7 +232,46 @@ declare function createApiServices<T>(axiosInstance: AxiosInstance, endpoint: st
  * بالإضافة إلى دوال التحقق من الأنواع (type guards).
  */
 
-declare function buildPaginateQuery(query: PaginateQueryOptions): string;
+/**
+ * يبني سلسلة استعلام (query string) من كائن خيارات مرن.
+ * يتعامل مع البارامترات القياسية والمخصصة.
+ * @param query - كائن من نوع QueryOptions.
+ * @returns سلسلة استعلام جاهزة للإضافة للرابط.
+ */
+declare function buildPaginateQuery(query: QueryOptions): string;
+
+/**
+ * Defines a single custom API action.
+ * @template TRequest - The type of the data sent in the request body/params.
+ * @template TResponse - The type of the data expected in the successful API response.
+ */
+type ApiAction<TRequest, TResponse> = (payload: TRequest, config?: RequestConfig) => Promise<StandardResponse<TResponse>>;
+/**
+ * A factory function to create a collection of typed, custom API actions.
+ *
+ * @template TActions - An object type where keys are action names and values are objects
+ *                      defining the endpoint, method, and types for that action.
+ * @param axiosInstance - The configured Axios instance from `createApiClient`.
+ * @param actionsConfig - An object defining the configuration for each custom action.
+ * @returns A fully-typed object of executable API action functions.
+ *
+ * @example
+ * const authActions = createApiActions(apiClient, {
+ *   login: { method: 'POST', endpoint: '/auth/login', requestType: {} as LoginCredentials, responseType: {} as AuthResponse },
+ *   getProfile: { method: 'GET', endpoint: '/user/profile', requestType: {} as void, responseType: {} as UserProfile }
+ * });
+ *
+ * // Usage:
+ * const result = await authActions.login({ email: '..', password: '..' });
+ */
+declare function createApiActions<TActions extends Record<string, {
+    method: Method;
+    endpoint: string;
+    requestType: any;
+    responseType: any;
+}>>(axiosInstance: AxiosInstance, actionsConfig: TActions): {
+    [K in keyof TActions]: ApiAction<TActions[K]['requestType'], TActions[K]['responseType']>;
+};
 
 declare class CacheManager {
     private cache;
@@ -202,12 +284,15 @@ declare class CacheManager {
 declare const cacheManager: CacheManager;
 
 /**
- * @file src/core/processor.ts
- * @description
- * ...
+ * A smart response processor that normalizes API responses.
+ * It intelligently unwraps nested data from standard API envelopes
+ * (like { success: true, data: {...} }) and provides direct access
+ * to the core data, while still handling errors consistently.
+ *
+ * @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<ApiResponse<T>> | ApiError) => StandardResponse<T>;
+declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError) => StandardResponse<T>;
 
 declare function useApi<T extends {
     id?: string | number;
@@ -215,14 +300,14 @@ declare function useApi<T extends {
     state: StandardResponse<T | T[]>;
     setState: react.Dispatch<react.SetStateAction<StandardResponse<T | T[]>>>;
     actions: {
-        fetch: () => Promise<void>;
-        create: (newItem: Partial<T>) => Promise<StandardResponse<T>>;
-        update: (id: string, updatedItem: Partial<T>) => Promise<StandardResponse<T>>;
-        remove: (id: string) => Promise<StandardResponse<any>>;
+        fetch: (options?: QueryOptions) => Promise<void>;
+        create: (newItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
+        update: (id: string, updatedItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
+        remove: (id: string, options?: ActionOptions) => Promise<StandardResponse<any>>;
     };
     query: {
-        options: PaginateQueryOptions;
-        setOptions: react.Dispatch<react.SetStateAction<PaginateQueryOptions>>;
+        options: QueryOptions;
+        setOptions: react.Dispatch<react.SetStateAction<QueryOptions>>;
         setPage: (page: number) => void;
         setLimit: (limit: number) => void;
         setSearchTerm: (search: string) => void;
@@ -231,8 +316,9 @@ declare function useApi<T extends {
             direction: "asc" | "desc";
         }[]) => void;
         setFilters: (filter: Record<string, any>) => void;
+        setQueryParam: (key: string, value: any) => void;
         reset: () => void;
     };
 };
 
-export { type ApiClientConfig, type ApiError, type ApiResponse, type PaginateQueryOptions, type PaginationMeta, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiConfig, type ValidationError, buildPaginateQuery, cacheManager, createApiClient, createApiServices, processResponse, useApi };
+export { type ActionOptions, type ApiClientConfig, type ApiError, type ApiResponse, type PaginateQueryOptions, type PaginationMeta, type QueryOptions, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiConfig, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ResponseType, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, AxiosResponse } from 'axios';
+import { ResponseType, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method, AxiosResponse } from 'axios';
 import * as react from 'react';
 
 /**
@@ -18,15 +18,6 @@ interface PaginationMeta {
     currentPage: number;
     totalPages: number;
 }
-/**
- * يمثل بنية الاستجابة القياسية من الـ API.
- * @template T نوع البيانات الأساسية في الاستجابة.
- */
-interface ApiResponse<T = any> {
-    data: T;
-    message?: string;
-    meta?: PaginationMeta;
-}
 /**
  * يمثل خطأ التحقق من صحة حقل معين.
  */
@@ -44,18 +35,6 @@ interface ApiError {
     errors?: ValidationError[];
     requestId?: string;
 }
-/**
- * يمثل كائن الاستجابة الموحد الذي يرجعه كل طلب.
- * @template T نوع البيانات المتوقعة في حالة النجاح.
- */
-interface StandardResponse<T> {
-    response?: ApiResponse<T> | T;
-    error: ApiError | null;
-    loading: boolean;
-    success: boolean;
-    message?: string;
-    validationErrors?: ValidationError[];
-}
 /**
  * يمثل مجموعة التوكنات التي يتم إدارتها.
  */
@@ -96,19 +75,6 @@ interface PaginateQueryOptions {
     }[];
     filter?: Record<string, any>;
 }
-/**
- * واجهة لتهيئة الهوك `useApi`.
- * @template T نوع البيانات التي يتعامل معها الهوك.
- */
-interface UseApiConfig<T> {
-    endpoint: string;
-    initialData?: T | T[];
-    initialQuery?: PaginateQueryOptions;
-    enabled?: boolean;
-    refetchAfterChange?: boolean;
-    onSuccess?: (message: string, data?: T) => void;
-    onError?: (message: string, error?: ApiError) => void;
-}
 /**
  * واجهة لتخصيص عملية تجديد التوكن بشكل كامل.
  */
@@ -162,6 +128,82 @@ interface ApiClientConfig {
     refreshTokenConfig?: RefreshTokenConfig;
     onRefreshError?: (error: any) => void;
 }
+/**
+ * يمثل بنية الاستجابة القياسية من الـ API.
+ * @template T نوع البيانات الأساسية في الاستجابة.
+ */
+interface ApiResponse<T = any> {
+    data: T;
+    message?: string;
+    meta?: PaginationMeta;
+}
+/**
+ * يمثل بنية الاستجابة القياسية المغلفة التي قد تأتي من بعض نقاط الـ API.
+ * @template T نوع البيانات الأساسية في الاستجابة.
+ */
+interface ApiResponse<T = any> {
+    data: T;
+    message?: string;
+    meta?: PaginationMeta;
+    success?: boolean;
+}
+/**
+ * يمثل كائن الاستجابة الموحد والنهائي الذي يرجعه كل طلب.
+ * هذا هو النوع الذي ستتعامل معه دائمًا.
+ * @template T نوع البيانات النهائية التي تريد الوصول إليها.
+ */
+interface StandardResponse<T> {
+    data: T | null;
+    rawResponse: any;
+    error: ApiError | null;
+    loading: boolean;
+    success: boolean;
+    message?: string;
+    validationErrors?: ValidationError[];
+}
+/**
+ * NEW: واجهة استعلام مرنة تسمح بالبارامترات القياسية (للفلترة والترقيم)
+ * بالإضافة إلى أي بارامترات مخصصة أخرى عبر الـ index signature.
+ * @example
+ * { page: 1, limit: 10, search: 'term', status: 'published', authorId: 123 }
+ */
+interface QueryOptions {
+    page?: number;
+    limit?: number;
+    search?: string;
+    sortBy?: {
+        key: string;
+        direction: 'asc' | 'desc';
+    }[];
+    filter?: Record<string, any>;
+    [key: string]: any;
+}
+/**
+ * NEW: واجهة لتمرير خيارات إضافية لدوال الأكشن (create, update, remove).
+ */
+interface ActionOptions {
+    /**
+     * يسمح لك بتجاوز الـ endpoint الافتراضي المحدد في الهوك.
+     * مفيد لإرسال طلبات لنقاط نهاية متخصصة.
+     * @example
+     * // لتحديث عنصر وتغيير حالته عبر مسار مختلف
+     * update('123', { status: 'active' }, { endpoint: '/items/123/activate' })
+     */
+    endpoint?: string;
+}
+/**
+ * واجهة لتهيئة الهوك `useApi`.
+ * @template T نوع البيانات التي يتعامل معها الهوك.
+ */
+interface UseApiConfig<T> {
+    endpoint: string;
+    initialData?: T | T[];
+    initialQuery?: QueryOptions;
+    enabled?: boolean;
+    refetchAfterChange?: boolean;
+    onSuccess?: (message: string, data?: T) => void;
+    onError?: (message: string, error?: ApiError) => void;
+}
 
 /**
  * @file src/core/client.ts
@@ -173,12 +215,13 @@ interface ApiClientConfig {
 
 declare function createApiClient(config: ApiClientConfig): AxiosInstance;
 
+type CrudRequestConfig = RequestConfig & ActionOptions;
 declare function createApiServices<T>(axiosInstance: AxiosInstance, endpoint: string): {
     get: (id?: string, config?: RequestConfig) => Promise<StandardResponse<T | T[]>>;
     getWithQuery: (query: string, config?: RequestConfig) => Promise<StandardResponse<T[]>>;
-    post: (data: Partial<T>, config?: RequestConfig) => Promise<StandardResponse<T>>;
-    patch: (id: string, data: Partial<T>, config?: RequestConfig) => Promise<StandardResponse<T>>;
-    remove: (id: string, config?: RequestConfig) => Promise<StandardResponse<any>>;
+    post: (data: Partial<T>, config?: CrudRequestConfig) => Promise<StandardResponse<T>>;
+    patch: (id: string, data: Partial<T>, config?: CrudRequestConfig) => Promise<StandardResponse<T>>;
+    remove: (id: string, config?: CrudRequestConfig) => Promise<StandardResponse<any>>;
 };
 
 /**
@@ -189,7 +232,46 @@ declare function createApiServices<T>(axiosInstance: AxiosInstance, endpoint: st
  * بالإضافة إلى دوال التحقق من الأنواع (type guards).
  */
 
-declare function buildPaginateQuery(query: PaginateQueryOptions): string;
+/**
+ * يبني سلسلة استعلام (query string) من كائن خيارات مرن.
+ * يتعامل مع البارامترات القياسية والمخصصة.
+ * @param query - كائن من نوع QueryOptions.
+ * @returns سلسلة استعلام جاهزة للإضافة للرابط.
+ */
+declare function buildPaginateQuery(query: QueryOptions): string;
+
+/**
+ * Defines a single custom API action.
+ * @template TRequest - The type of the data sent in the request body/params.
+ * @template TResponse - The type of the data expected in the successful API response.
+ */
+type ApiAction<TRequest, TResponse> = (payload: TRequest, config?: RequestConfig) => Promise<StandardResponse<TResponse>>;
+/**
+ * A factory function to create a collection of typed, custom API actions.
+ *
+ * @template TActions - An object type where keys are action names and values are objects
+ *                      defining the endpoint, method, and types for that action.
+ * @param axiosInstance - The configured Axios instance from `createApiClient`.
+ * @param actionsConfig - An object defining the configuration for each custom action.
+ * @returns A fully-typed object of executable API action functions.
+ *
+ * @example
+ * const authActions = createApiActions(apiClient, {
+ *   login: { method: 'POST', endpoint: '/auth/login', requestType: {} as LoginCredentials, responseType: {} as AuthResponse },
+ *   getProfile: { method: 'GET', endpoint: '/user/profile', requestType: {} as void, responseType: {} as UserProfile }
+ * });
+ *
+ * // Usage:
+ * const result = await authActions.login({ email: '..', password: '..' });
+ */
+declare function createApiActions<TActions extends Record<string, {
+    method: Method;
+    endpoint: string;
+    requestType: any;
+    responseType: any;
+}>>(axiosInstance: AxiosInstance, actionsConfig: TActions): {
+    [K in keyof TActions]: ApiAction<TActions[K]['requestType'], TActions[K]['responseType']>;
+};
 
 declare class CacheManager {
     private cache;
@@ -202,12 +284,15 @@ declare class CacheManager {
 declare const cacheManager: CacheManager;
 
 /**
- * @file src/core/processor.ts
- * @description
- * ...
+ * A smart response processor that normalizes API responses.
+ * It intelligently unwraps nested data from standard API envelopes
+ * (like { success: true, data: {...} }) and provides direct access
+ * to the core data, while still handling errors consistently.
+ *
+ * @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<ApiResponse<T>> | ApiError) => StandardResponse<T>;
+declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError) => StandardResponse<T>;
 
 declare function useApi<T extends {
     id?: string | number;
@@ -215,14 +300,14 @@ declare function useApi<T extends {
     state: StandardResponse<T | T[]>;
     setState: react.Dispatch<react.SetStateAction<StandardResponse<T | T[]>>>;
     actions: {
-        fetch: () => Promise<void>;
-        create: (newItem: Partial<T>) => Promise<StandardResponse<T>>;
-        update: (id: string, updatedItem: Partial<T>) => Promise<StandardResponse<T>>;
-        remove: (id: string) => Promise<StandardResponse<any>>;
+        fetch: (options?: QueryOptions) => Promise<void>;
+        create: (newItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
+        update: (id: string, updatedItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
+        remove: (id: string, options?: ActionOptions) => Promise<StandardResponse<any>>;
     };
     query: {
-        options: PaginateQueryOptions;
-        setOptions: react.Dispatch<react.SetStateAction<PaginateQueryOptions>>;
+        options: QueryOptions;
+        setOptions: react.Dispatch<react.SetStateAction<QueryOptions>>;
         setPage: (page: number) => void;
         setLimit: (limit: number) => void;
         setSearchTerm: (search: string) => void;
@@ -231,8 +316,9 @@ declare function useApi<T extends {
             direction: "asc" | "desc";
         }[]) => void;
         setFilters: (filter: Record<string, any>) => void;
+        setQueryParam: (key: string, value: any) => void;
         reset: () => void;
     };
 };
 
-export { type ApiClientConfig, type ApiError, type ApiResponse, type PaginateQueryOptions, type PaginationMeta, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiConfig, type ValidationError, buildPaginateQuery, cacheManager, createApiClient, createApiServices, processResponse, useApi };
+export { type ActionOptions, type ApiClientConfig, type ApiError, type ApiResponse, type PaginateQueryOptions, type PaginationMeta, type QueryOptions, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiConfig, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi };

package/dist/index.js

@@ -32,6 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   buildPaginateQuery: () => buildPaginateQuery,
   cacheManager: () => cacheManager,
+  createApiActions: () => createApiActions,
   createApiClient: () => createApiClient,
   createApiServices: () => createApiServices,
   processResponse: () => processResponse,
@@ -163,6 +164,7 @@ var import_axios2 = __toESM(require("axios"));
 function buildPaginateQuery(query) {
   if (!query) return "";
   const params = new URLSearchParams();
+  const standardKeys = /* @__PURE__ */ new Set(["page", "limit", "search", "sortBy", "filter"]);
   if (query.page) params.append("page", query.page.toString());
   if (query.limit) params.append("limit", query.limit.toString());
   if (query.search) params.append("search", query.search);
@@ -174,6 +176,14 @@ function buildPaginateQuery(query) {
       params.append(`filter.${field}`, String(value));
     });
   }
+  for (const key in query) {
+    if (Object.prototype.hasOwnProperty.call(query, key) && !standardKeys.has(key)) {
+      const value = query[key];
+      if (value !== void 0 && value !== null) {
+        params.append(key, String(value));
+      }
+    }
+  }
   const queryString = params.toString();
   return queryString ? `?${queryString}` : "";
 }
@@ -188,37 +198,38 @@ function isAxiosResponse(obj) {
 var processResponse = (responseOrError) => {
   if (isApiError(responseOrError)) {
     return {
-      response: void 0,
+      data: null,
+      rawResponse: void 0,
       error: responseOrError,
       validationErrors: responseOrError.errors || [],
-      // الخطأ الآن صحيح
       success: false,
       loading: false,
       message: responseOrError.message
     };
   }
   if (isAxiosResponse(responseOrError)) {
-    const response = responseOrError;
+    const rawData = responseOrError.data;
+    const isWrappedResponse = rawData && typeof rawData.success === "boolean" && rawData.data !== void 0;
+    const finalData = isWrappedResponse ? rawData.data : rawData;
+    const message = isWrappedResponse ? rawData.message : "Request successful.";
     return {
-      response: response.data,
+      data: finalData,
+      // <-- وصول مباشر للبيانات النهائية!
+      rawResponse: rawData,
+      // احتفظ بالاستجابة الكاملة إذا احتجت إليها
       loading: false,
       success: true,
       error: null,
-      message: response.data.message || "Request successful.",
+      message,
       validationErrors: []
-      // <-- أضف قيمة افتراضية هنا للاتساق
     };
   }
   return {
-    response: void 0,
-    error: {
-      message: "An unknown error occurred during response processing.",
-      status: 500
-    },
+    data: null,
+    rawResponse: void 0,
+    error: { message: "An unknown error occurred during response processing.", status: 500 },
     success: false,
-    loading: false,
-    validationErrors: []
-    // <-- أضف قيمة افتراضية هنا أيضًا
+    loading: false
   };
 };
 
@@ -242,24 +253,27 @@ function createApiServices(axiosInstance, endpoint) {
     }
   };
   const post = async (data, config) => {
+    const finalUrl = config?.endpoint || endpoint;
     try {
-      const response = await axiosInstance.post(endpoint, data, config);
+      const response = await axiosInstance.post(finalUrl, data, config);
       return processResponse(response);
     } catch (error) {
       return processResponse(error);
     }
   };
   const patch = async (id, data, config) => {
+    const finalUrl = config?.endpoint || `${endpoint}/${id}`;
     try {
-      const response = await axiosInstance.patch(`${endpoint}/${id}`, data, config);
+      const response = await axiosInstance.patch(finalUrl, data, config);
       return processResponse(response);
     } catch (error) {
       return processResponse(error);
     }
   };
   const remove = async (id, config) => {
+    const finalUrl = config?.endpoint || `${endpoint}/${id}`;
     try {
-      const response = await axiosInstance.delete(`${endpoint}/${id}`, config);
+      const response = await axiosInstance.delete(finalUrl, config);
       return processResponse(response);
     } catch (error) {
       return processResponse(error);
@@ -268,6 +282,34 @@ function createApiServices(axiosInstance, endpoint) {
   return { get, getWithQuery, post, patch, remove };
 }
 
+// src/services/actions.ts
+function createAction(axiosInstance, method, endpoint) {
+  return async (payload, config) => {
+    try {
+      const response = await axiosInstance.request({
+        // <--- غيرنا النوع إلى any
+        url: endpoint,
+        method,
+        ...method.toUpperCase() === "GET" ? { params: payload } : { data: payload },
+        ...config
+      });
+      return processResponse(response);
+    } catch (error) {
+      return processResponse(error);
+    }
+  };
+}
+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);
+    }
+  }
+  return actions;
+}
+
 // src/core/cache.ts
 var CacheManager = class {
   cache = /* @__PURE__ */ new Map();
@@ -305,23 +347,26 @@ function useApi(axiosInstance, config) {
   const {
     endpoint,
     initialData,
-    initialQuery = { page: 1, limit: 10 },
+    initialQuery = { limit: 10 },
     enabled = true,
     refetchAfterChange = true,
+    // تم تعديل القيمة الافتراضية لتكون أكثر شيوعًا
     onSuccess,
     onError
   } = config;
   const [state, setState] = (0, import_react.useState)({
-    response: initialData || void 0,
+    data: initialData || null,
+    rawResponse: null,
     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 fetchData = (0, import_react.useCallback)(async (options) => {
+    const currentQuery = options || queryOptions;
+    setState((prev) => ({ ...prev, data: null, loading: true, error: null }));
+    const queryString = buildPaginateQuery(currentQuery);
     const result = await apiServices.getWithQuery(queryString, { cancelTokenKey: endpoint });
     setState(result);
     if (!result.success && onError) {
@@ -333,35 +378,35 @@ function useApi(axiosInstance, config) {
       fetchData();
     }
   }, [enabled, queryOptions]);
-  const createItem = async (newItem) => {
+  const createItem = async (newItem, options) => {
     setState((prev) => ({ ...prev, loading: true }));
-    const result = await apiServices.post(newItem);
+    const result = await apiServices.post(newItem, options);
     if (result.success) {
       if (refetchAfterChange) await fetchData();
       else setState((prev) => ({ ...prev, loading: false }));
-      if (onSuccess) onSuccess(result.message || "Item created successfully!", result.response);
+      if (onSuccess) onSuccess(result.message || "Item created successfully!", result.data);
     } 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) => {
+  const updateItem = async (id, updatedItem, options) => {
     setState((prev) => ({ ...prev, loading: true }));
-    const result = await apiServices.patch(id, updatedItem);
+    const result = await apiServices.patch(id, updatedItem, options);
     if (result.success) {
       if (refetchAfterChange) await fetchData();
       else setState((prev) => ({ ...prev, loading: false }));
-      if (onSuccess) onSuccess(result.message || "Item updated successfully!", result.response);
+      if (onSuccess) onSuccess(result.message || "Item updated successfully!", result.data);
     } 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) => {
+  const deleteItem = async (id, options) => {
     setState((prev) => ({ ...prev, loading: true }));
-    const result = await apiServices.remove(id);
+    const result = await apiServices.remove(id, options);
     if (result.success) {
       if (refetchAfterChange) await fetchData();
       else setState((prev) => ({ ...prev, loading: false }));
@@ -377,11 +422,19 @@ function useApi(axiosInstance, config) {
   const setSearchTerm = (search) => setQueryOptions((prev) => ({ ...prev, search, page: 1 }));
   const setSorting = (sortBy) => setQueryOptions((prev) => ({ ...prev, sortBy }));
   const setFilters = (filter) => setQueryOptions((prev) => ({ ...prev, filter, page: 1 }));
+  const setQueryParam = (key, value) => {
+    setQueryOptions((prev) => {
+      const newQuery = { ...prev, [key]: value };
+      if (key !== "page") {
+        newQuery.page = 1;
+      }
+      return newQuery;
+    });
+  };
   const resetQuery = () => setQueryOptions(initialQuery);
   return {
     state,
     setState,
-    // Exposing setState for direct manipulation or connection to Redux
     actions: {
       fetch: fetchData,
       create: createItem,
@@ -396,6 +449,8 @@ function useApi(axiosInstance, config) {
       setSearchTerm,
       setSorting,
       setFilters,
+      setQueryParam,
+      // <-- NEW
       reset: resetQuery
     }
   };
@@ -404,6 +459,7 @@ function useApi(axiosInstance, config) {
 0 && (module.exports = {
   buildPaginateQuery,
   cacheManager,
+  createApiActions,
   createApiClient,
   createApiServices,
   processResponse,

package/dist/index.mjs

@@ -122,6 +122,7 @@ import axios2 from "axios";
 function buildPaginateQuery(query) {
   if (!query) return "";
   const params = new URLSearchParams();
+  const standardKeys = /* @__PURE__ */ new Set(["page", "limit", "search", "sortBy", "filter"]);
   if (query.page) params.append("page", query.page.toString());
   if (query.limit) params.append("limit", query.limit.toString());
   if (query.search) params.append("search", query.search);
@@ -133,6 +134,14 @@ function buildPaginateQuery(query) {
       params.append(`filter.${field}`, String(value));
     });
   }
+  for (const key in query) {
+    if (Object.prototype.hasOwnProperty.call(query, key) && !standardKeys.has(key)) {
+      const value = query[key];
+      if (value !== void 0 && value !== null) {
+        params.append(key, String(value));
+      }
+    }
+  }
   const queryString = params.toString();
   return queryString ? `?${queryString}` : "";
 }
@@ -147,37 +156,38 @@ function isAxiosResponse(obj) {
 var processResponse = (responseOrError) => {
   if (isApiError(responseOrError)) {
     return {
-      response: void 0,
+      data: null,
+      rawResponse: void 0,
       error: responseOrError,
       validationErrors: responseOrError.errors || [],
-      // الخطأ الآن صحيح
       success: false,
       loading: false,
       message: responseOrError.message
     };
   }
   if (isAxiosResponse(responseOrError)) {
-    const response = responseOrError;
+    const rawData = responseOrError.data;
+    const isWrappedResponse = rawData && typeof rawData.success === "boolean" && rawData.data !== void 0;
+    const finalData = isWrappedResponse ? rawData.data : rawData;
+    const message = isWrappedResponse ? rawData.message : "Request successful.";
     return {
-      response: response.data,
+      data: finalData,
+      // <-- وصول مباشر للبيانات النهائية!
+      rawResponse: rawData,
+      // احتفظ بالاستجابة الكاملة إذا احتجت إليها
       loading: false,
       success: true,
       error: null,
-      message: response.data.message || "Request successful.",
+      message,
       validationErrors: []
-      // <-- أضف قيمة افتراضية هنا للاتساق
     };
   }
   return {
-    response: void 0,
-    error: {
-      message: "An unknown error occurred during response processing.",
-      status: 500
-    },
+    data: null,
+    rawResponse: void 0,
+    error: { message: "An unknown error occurred during response processing.", status: 500 },
     success: false,
-    loading: false,
-    validationErrors: []
-    // <-- أضف قيمة افتراضية هنا أيضًا
+    loading: false
   };
 };
 
@@ -201,24 +211,27 @@ function createApiServices(axiosInstance, endpoint) {
     }
   };
   const post = async (data, config) => {
+    const finalUrl = config?.endpoint || endpoint;
     try {
-      const response = await axiosInstance.post(endpoint, data, config);
+      const response = await axiosInstance.post(finalUrl, data, config);
       return processResponse(response);
     } catch (error) {
       return processResponse(error);
     }
   };
   const patch = async (id, data, config) => {
+    const finalUrl = config?.endpoint || `${endpoint}/${id}`;
     try {
-      const response = await axiosInstance.patch(`${endpoint}/${id}`, data, config);
+      const response = await axiosInstance.patch(finalUrl, data, config);
       return processResponse(response);
     } catch (error) {
       return processResponse(error);
     }
   };
   const remove = async (id, config) => {
+    const finalUrl = config?.endpoint || `${endpoint}/${id}`;
     try {
-      const response = await axiosInstance.delete(`${endpoint}/${id}`, config);
+      const response = await axiosInstance.delete(finalUrl, config);
       return processResponse(response);
     } catch (error) {
       return processResponse(error);
@@ -227,6 +240,34 @@ function createApiServices(axiosInstance, endpoint) {
   return { get, getWithQuery, post, patch, remove };
 }
 
+// src/services/actions.ts
+function createAction(axiosInstance, method, endpoint) {
+  return async (payload, config) => {
+    try {
+      const response = await axiosInstance.request({
+        // <--- غيرنا النوع إلى any
+        url: endpoint,
+        method,
+        ...method.toUpperCase() === "GET" ? { params: payload } : { data: payload },
+        ...config
+      });
+      return processResponse(response);
+    } catch (error) {
+      return processResponse(error);
+    }
+  };
+}
+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);
+    }
+  }
+  return actions;
+}
+
 // src/core/cache.ts
 var CacheManager = class {
   cache = /* @__PURE__ */ new Map();
@@ -264,23 +305,26 @@ function useApi(axiosInstance, config) {
   const {
     endpoint,
     initialData,
-    initialQuery = { page: 1, limit: 10 },
+    initialQuery = { limit: 10 },
     enabled = true,
     refetchAfterChange = true,
+    // تم تعديل القيمة الافتراضية لتكون أكثر شيوعًا
     onSuccess,
     onError
   } = config;
   const [state, setState] = useState({
-    response: initialData || void 0,
+    data: initialData || null,
+    rawResponse: null,
     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 fetchData = useCallback(async (options) => {
+    const currentQuery = options || queryOptions;
+    setState((prev) => ({ ...prev, data: null, loading: true, error: null }));
+    const queryString = buildPaginateQuery(currentQuery);
     const result = await apiServices.getWithQuery(queryString, { cancelTokenKey: endpoint });
     setState(result);
     if (!result.success && onError) {
@@ -292,35 +336,35 @@ function useApi(axiosInstance, config) {
       fetchData();
     }
   }, [enabled, queryOptions]);
-  const createItem = async (newItem) => {
+  const createItem = async (newItem, options) => {
     setState((prev) => ({ ...prev, loading: true }));
-    const result = await apiServices.post(newItem);
+    const result = await apiServices.post(newItem, options);
     if (result.success) {
       if (refetchAfterChange) await fetchData();
       else setState((prev) => ({ ...prev, loading: false }));
-      if (onSuccess) onSuccess(result.message || "Item created successfully!", result.response);
+      if (onSuccess) onSuccess(result.message || "Item created successfully!", result.data);
     } 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) => {
+  const updateItem = async (id, updatedItem, options) => {
     setState((prev) => ({ ...prev, loading: true }));
-    const result = await apiServices.patch(id, updatedItem);
+    const result = await apiServices.patch(id, updatedItem, options);
     if (result.success) {
       if (refetchAfterChange) await fetchData();
       else setState((prev) => ({ ...prev, loading: false }));
-      if (onSuccess) onSuccess(result.message || "Item updated successfully!", result.response);
+      if (onSuccess) onSuccess(result.message || "Item updated successfully!", result.data);
     } 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) => {
+  const deleteItem = async (id, options) => {
     setState((prev) => ({ ...prev, loading: true }));
-    const result = await apiServices.remove(id);
+    const result = await apiServices.remove(id, options);
     if (result.success) {
       if (refetchAfterChange) await fetchData();
       else setState((prev) => ({ ...prev, loading: false }));
@@ -336,11 +380,19 @@ function useApi(axiosInstance, config) {
   const setSearchTerm = (search) => setQueryOptions((prev) => ({ ...prev, search, page: 1 }));
   const setSorting = (sortBy) => setQueryOptions((prev) => ({ ...prev, sortBy }));
   const setFilters = (filter) => setQueryOptions((prev) => ({ ...prev, filter, page: 1 }));
+  const setQueryParam = (key, value) => {
+    setQueryOptions((prev) => {
+      const newQuery = { ...prev, [key]: value };
+      if (key !== "page") {
+        newQuery.page = 1;
+      }
+      return newQuery;
+    });
+  };
   const resetQuery = () => setQueryOptions(initialQuery);
   return {
     state,
     setState,
-    // Exposing setState for direct manipulation or connection to Redux
     actions: {
       fetch: fetchData,
       create: createItem,
@@ -355,6 +407,8 @@ function useApi(axiosInstance, config) {
       setSearchTerm,
       setSorting,
       setFilters,
+      setQueryParam,
+      // <-- NEW
       reset: resetQuery
     }
   };
@@ -362,6 +416,7 @@ function useApi(axiosInstance, config) {
 export {
   buildPaginateQuery,
   cacheManager,
+  createApiActions,
   createApiClient,
   createApiServices,
   processResponse,

package/package.json

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