api-core-lib 3.2.2 → 3.3.2

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[];
-}
 /**
  * يمثل مجموعة التوكنات التي يتم إدارتها.
  */
@@ -162,6 +141,39 @@ 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[];
+}
 
 /**
  * @file src/core/client.ts
@@ -191,6 +203,39 @@ declare function createApiServices<T>(axiosInstance: AxiosInstance, endpoint: st
 
 declare function buildPaginateQuery(query: PaginateQueryOptions): 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;
     private defaultDuration;
@@ -202,12 +247,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;
@@ -235,4 +283,4 @@ declare function useApi<T extends {
     };
 };
 
-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 ApiClientConfig, type ApiError, type ApiResponse, type PaginateQueryOptions, type PaginationMeta, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiConfig, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi };

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[];
-}
 /**
  * يمثل مجموعة التوكنات التي يتم إدارتها.
  */
@@ -162,6 +141,39 @@ 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[];
+}
 
 /**
  * @file src/core/client.ts
@@ -191,6 +203,39 @@ declare function createApiServices<T>(axiosInstance: AxiosInstance, endpoint: st
 
 declare function buildPaginateQuery(query: PaginateQueryOptions): 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;
     private defaultDuration;
@@ -202,12 +247,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;
@@ -235,4 +283,4 @@ declare function useApi<T extends {
     };
 };
 
-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 ApiClientConfig, type ApiError, type ApiResponse, type PaginateQueryOptions, type PaginationMeta, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiConfig, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi };

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,
@@ -188,37 +189,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
   };
 };
 
@@ -268,6 +270,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();
@@ -312,7 +342,9 @@ function useApi(axiosInstance, config) {
     onError
   } = config;
   const [state, setState] = (0, import_react.useState)({
-    response: initialData || void 0,
+    data: initialData || null,
+    // <--- التغيير هنا
+    rawResponse: null,
     loading: enabled,
     error: null,
     success: false
@@ -320,7 +352,7 @@ function useApi(axiosInstance, config) {
   const [queryOptions, setQueryOptions] = (0, import_react.useState)(initialQuery);
   const apiServices = (0, import_react.useRef)(createApiServices(axiosInstance, endpoint)).current;
   const fetchData = (0, import_react.useCallback)(async () => {
-    setState((prev) => ({ ...prev, loading: true, error: null }));
+    setState((prev) => ({ ...prev, data: null, loading: true, error: null }));
     const queryString = buildPaginateQuery(queryOptions);
     const result = await apiServices.getWithQuery(queryString, { cancelTokenKey: endpoint });
     setState(result);
@@ -339,7 +371,7 @@ function useApi(axiosInstance, config) {
     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);
@@ -352,7 +384,7 @@ function useApi(axiosInstance, config) {
     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);
@@ -404,6 +436,7 @@ function useApi(axiosInstance, config) {
 0 && (module.exports = {
   buildPaginateQuery,
   cacheManager,
+  createApiActions,
   createApiClient,
   createApiServices,
   processResponse,

package/dist/index.mjs

@@ -147,37 +147,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
   };
 };
 
@@ -227,6 +228,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();
@@ -271,7 +300,9 @@ function useApi(axiosInstance, config) {
     onError
   } = config;
   const [state, setState] = useState({
-    response: initialData || void 0,
+    data: initialData || null,
+    // <--- التغيير هنا
+    rawResponse: null,
     loading: enabled,
     error: null,
     success: false
@@ -279,7 +310,7 @@ function useApi(axiosInstance, config) {
   const [queryOptions, setQueryOptions] = useState(initialQuery);
   const apiServices = useRef(createApiServices(axiosInstance, endpoint)).current;
   const fetchData = useCallback(async () => {
-    setState((prev) => ({ ...prev, loading: true, error: null }));
+    setState((prev) => ({ ...prev, data: null, loading: true, error: null }));
     const queryString = buildPaginateQuery(queryOptions);
     const result = await apiServices.getWithQuery(queryString, { cancelTokenKey: endpoint });
     setState(result);
@@ -298,7 +329,7 @@ function useApi(axiosInstance, config) {
     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);
@@ -311,7 +342,7 @@ function useApi(axiosInstance, config) {
     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);
@@ -362,6 +393,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.2",
   "description": "A flexible and powerful API client library for modern web applications.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",