api-core-lib 5.5.4 → 6.5.5

package/dist/index.d.mts

@@ -1,16 +1,14 @@
 import { InternalAxiosRequestConfig, AxiosResponse, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method } from 'axios';
-import * as react from 'react';
 
 /**
  * @file src/types.ts
- * @description
- * هذا الملف هو المصدر المركزي لجميع أنواع البيانات (Types) والواجهات (Interfaces)
- * المستخدمة في المكتبة. تعريف الأنواع هنا يضمن التناسق وسلامة الأنواع
- * في جميع أنحاء المشروع ويوفر واجهة واضحة للمستخدم النهائي.
+ * @description This file serves as the central source for all data types and interfaces
+ * used throughout the library. Defining types here ensures consistency, type safety,
+ * and provides a clear API contract for the end-user.
  */
 
 /**
- * يمثل بيانات الترقيم (Pagination) التي تأتي من الـ API.
+ * Defines the structure for pagination metadata returned by the API.
  */
 interface PaginationMeta {
     itemsPerPage: number;
@@ -19,14 +17,24 @@ interface PaginationMeta {
     totalPages: number;
 }
 /**
- * يمثل خطأ التحقق من صحة حقل معين.
+ * Represents the standard wrapper that an API might use for its responses.
+ * @template T The type of the core data payload.
+ */
+interface ApiResponse<T = any> {
+    success?: boolean;
+    data: T;
+    message?: string;
+    meta?: PaginationMeta;
+}
+/**
+ * Defines the structure for a single field validation error.
  */
 interface ValidationError {
     field: string;
     message: string;
 }
 /**
- * يمثل كائن الخطأ الموحد الذي تنتجه المكتبة.
+ * Represents the unified error object produced by the library for any failed request.
  */
 interface ApiError {
     message: string;
@@ -35,34 +43,46 @@ interface ApiError {
     errors?: ValidationError[];
     requestId?: string;
 }
+/**
+ * The standardized, final response object that every library function returns.
+ * This is the primary type developers will interact with.
+ * @template T The type of the final, unwrapped data.
+ */
+interface StandardResponse<T> {
+    data: T | null;
+    rawResponse: any;
+    error: ApiError | null;
+    loading: boolean;
+    success: boolean;
+    message?: string;
+    validationErrors?: ValidationError[];
+}
+/**
+ * Represents the set of authentication tokens managed by the library.
+ */
 interface Tokens {
     accessToken: string | null;
     refreshToken: string | null;
     expiresAt?: number;
     tokenType?: string;
 }
+/**
+ * An interface for a token manager, allowing the logic for token storage to be decoupled.
+ * Consumers of the library can provide their own implementation (e.g., LocalStorage, Cookies).
+ */
 interface TokenManager {
     getTokens(): Promise<Tokens>;
     setTokens(tokens: Tokens): Promise<void>;
     clearTokens(): Promise<void>;
     /**
-     * دالة لتحديد سياق التشغيل.
-     * true إذا كانت التوكنات في كوكيز httpOnly (الوضع الآمن).
-     * false إذا كانت في مكان يمكن للعميل الوصول إليه (للتطبيقات غير Next.js).
+     * Determines the operating context.
+     * @returns `true` if tokens are in secure httpOnly cookies (server-side context).
+     * @returns `false` if tokens are accessible from the client (e.g., localStorage).
      */
     isHttpOnly(): boolean;
 }
 /**
- * واجهة لـ Logger مخصص. متوافقة مع `console`.
- */
-interface Logger {
-    log(message?: any, ...optionalParams: any[]): void;
-    info(message?: any, ...optionalParams: any[]): void;
-    warn(message?: any, ...optionalParams: any[]): void;
-    error(message?: any, ...optionalParams: any[]): void;
-}
-/**
- * سياق البرمجيات الوسيطة الذي يتم تمريره لكل دالة.
+ * The context object passed to each middleware function in the pipeline.
  */
 interface MiddlewareContext {
     req: InternalAxiosRequestConfig;
@@ -72,22 +92,28 @@ interface MiddlewareContext {
     custom?: Record<string, any>;
 }
 /**
- * دالة برمجية وسيطة (Middleware Function).
+ * Defines the signature for a middleware function.
  */
 type Middleware = (context: MiddlewareContext, next: () => Promise<void>) => Promise<void>;
+/**
+ * Extends the default Axios request configuration with custom properties for the library.
+ */
 interface RequestConfig extends AxiosRequestConfig {
+    /** If true, the request will bypass the token injection logic. */
     isPublic?: boolean;
-}
-interface RequestConfig extends AxiosRequestConfig {
+    /** A key for managing request cancellation. */
     cancelTokenKey?: string;
+    /** Callback for upload progress events. */
     onUploadProgress?: (progressEvent: AxiosProgressEvent) => void;
+    /** Callback for download progress events. */
     onDownloadProgress?: (progressEvent: AxiosProgressEvent) => void;
-    isPublic?: boolean;
 }
 /**
- * يمثل خيارات الاستعلام للترقيم والبحث والفرز.
+ * Defines a flexible query options interface for pagination, sorting, filtering, and searching.
+ * Supports standard keys as well as any custom top-level query parameters.
+ * @example { page: 1, limit: 10, search: 'term', status: 'published' }
  */
-interface PaginateQueryOptions {
+interface QueryOptions {
     page?: number;
     limit?: number;
     search?: string;
@@ -96,35 +122,58 @@ interface PaginateQueryOptions {
         direction: 'asc' | 'desc';
     }[];
     filter?: Record<string, any>;
+    [key: string]: any;
 }
 /**
- * واجهة لتخصيص عملية تجديد التوكن بشكل كامل.
+ * Defines additional options for action methods like create, update, or delete.
  */
-interface RefreshTokenConfig {
+interface ActionOptions {
     /**
-     * المسار الذي يتم استخدامه لتجديد التوكن (e.g., '/auth/refresh').
-     * @default '/auth/refresh'
+     * Overrides the default endpoint for a specific action. Useful for specialized routes.
+     * @example update('123', { status: 'active' }, { endpoint: '/items/123/activate' })
      */
-    path: string;
+    endpoint?: string;
     /**
-     * دالة لتحديد كيفية بناء جسم (body) طلب التجديد.
-     * @param refreshToken - التوكن المستخدم للتجديد.
-     * @returns كائن يمثل جسم الطلب.
-     * @default (refreshToken) => ({ refresh_token: refreshToken })
+     * Overrides the `refetchAfterChange` setting for a single action.
      */
+    refetch?: boolean;
+}
+/**
+ * The main configuration object for the `useApi` hook.
+ * @template T The data type the hook will manage.
+ */
+interface UseApiConfig<T> {
+    /** The base API endpoint for the resource (e.g., '/users'). */
+    endpoint: string;
+    /** Initial data to populate the state before the first fetch. */
+    initialData?: T | T[];
+    /** Default query options to use for the initial fetch. */
+    initialQuery?: QueryOptions;
+    /** If false, the hook will not fetch data automatically on mount. */
+    enabled?: boolean;
+    /** If true, data will be refetched automatically after a successful create, update, or delete action. */
+    refetchAfterChange?: boolean;
+    /** A default `RequestConfig` to apply to all GET requests made by the hook. */
+    requestConfig?: RequestConfig;
+    /** Callback function executed on a successful action. */
+    onSuccess?: (message: string, data?: T) => void;
+    /** Callback function executed on a failed action. */
+    onError?: (message: string, error?: ApiError) => void;
+}
+/**
+ * Defines the configuration for the automatic token refresh mechanism.
+ */
+interface RefreshTokenConfig {
+    /** The API path for the token refresh endpoint (e.g., '/auth/refresh'). */
+    path: string;
+    /** A function to build the request body for the refresh call. */
     buildRequestBody?: (refreshToken: string) => Record<string, any>;
-    /**
-     * دالة لتحديد كيفية بناء الهيدرز (headers) الخاصة بطلب التجديد.
-     * @param currentTokens - التوكنات الحالية.
-     * @returns كائن يمثل الهيدرز الإضافية.
-     * @default () => ({})
-     */
+    /** A function to build any custom headers for the refresh call. */
     buildRequestHeaders?: (currentTokens: Tokens) => Record<string, string>;
     /**
-     * دالة مخصصة لاستخلاص التوكنات الجديدة من استجابة الـ API.
-     * @param responseData - البيانات التي تم إرجاعها من الـ API.
-     * @returns كائن من نوع Tokens.
-     * @default (data) => ({ accessToken: data.access_token, ... })
+     * A function to extract the new tokens from the refresh API's response data.
+     * @param responseData The raw data from the refresh API response.
+     * @returns An object containing the new token details.
      */
     extractTokens: (responseData: any) => {
         accessToken: string;
@@ -134,106 +183,59 @@ interface RefreshTokenConfig {
     };
 }
 /**
- * الواجهة الرئيسية لتهيئة عميل الـ API (محدثة بالكامل).
+ * Defines the available levels for logging.
+ * 'debug': Logs everything.
+ * 'info': Logs standard requests and responses.
+ * 'warn': Logs warnings and errors.
+ * 'error': Logs only critical errors.
+ * 'silent': Disables all logging.
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * An interface for a custom logger, compatible with the standard `console` object.
+ * It now includes a `debug` method for more granular logging.
+ */
+interface Logger {
+    /** Logs a standard message. In our wrapper, this is often an alias for `info` or `debug`. */
+    log(message?: any, ...optionalParams: any[]): void;
+    /** Logs an informational message. */
+    info(message?: any, ...optionalParams: any[]): void;
+    /** Logs a warning message. */
+    warn(message?: any, ...optionalParams: any[]): void;
+    /** Logs an error message. */
+    error(message?: any, ...optionalParams: any[]): void;
+    /**
+     * Logs a debug message, typically for verbose, development-only output.
+     */
+    debug(message?: any, ...optionalParams: any[]): void;
+}
+/**
+ * The main configuration object for the `createApiClient` factory function.
  */
 interface ApiClientConfig {
+    /** The base URL for all API requests. */
     baseURL?: string;
+    /** The token manager instance responsible for handling token storage. */
     tokenManager: TokenManager;
+    /** The request timeout in milliseconds. */
     timeout?: number;
+    /** Default headers to be sent with every request. */
     headers?: Record<string, string>;
+    /** If true, cookies will be sent with cross-origin requests. */
     withCredentials?: boolean;
+    /** Configuration for the automatic token refresh mechanism. */
     refreshTokenConfig?: RefreshTokenConfig;
+    /** A callback function executed if the token refresh process fails. */
     onRefreshError?: (error: any) => void;
-    /**
-     * ✨ NEW: Logger مخصص. الافتراضي هو `console`.
-     */
+    /** A custom logger instance. Defaults to the browser `console`. */
     logger?: Logger;
-    /**
-     * ✨ NEW: مصفوفة من البرمجيات الوسيطة (Middleware) لتشغيلها مع كل طلب.
-     */
+    /** An array of middleware functions to be executed with every request. */
     middleware?: Middleware[];
-}
-/**
- * يمثل بنية الاستجابة القياسية من الـ 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;
-    refetch?: boolean;
-}
-/**
- * واجهة لتهيئة الهوك `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;
     /**
-     * إعدادات Axios/Request افتراضية يتم تطبيقها على جميع طلبات الجلب (GET).
-     * مفيدة لتمرير إعدادات مثل isPublic.
+     * Sets the verbosity of the internal logger.
+     * @default 'info'
      */
-    requestConfig?: RequestConfig;
+    logLevel?: LogLevel;
 }
 
 /**
@@ -246,16 +248,6 @@ interface UseApiConfig<T> {
 
 /**
  * Creates and configures a new Axios instance with advanced features.
- *
- * This factory function is the central entry point of the library. It sets up
- * request and response interceptors to handle:
- * - Secure token management (supporting httpOnly and client-side storage).
- * - A flexible middleware pipeline for custom logic.
- * - Centralized logging for observability.
- * - Automatic token refresh for client-side scenarios.
- *
- * @param {ApiClientConfig} config - The configuration object for the API client.
- * @returns {AxiosInstance} A fully configured Axios instance ready for use.
  */
 declare function createApiClient(config: ApiClientConfig): AxiosInstance;
 
@@ -346,34 +338,84 @@ declare const cacheManager: CacheManager;
  */
 declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError, log?: boolean) => StandardResponse<T>;
 
+/**
+ * @file src/hooks/useApi.types.ts
+ * @description This file defines the professional, publicly-facing types
+ * returned by the `useApi` hook, providing a clean and stable contract for consumers.
+ */
+
+/**
+ * The primary state object managed by the `useApi` hook.
+ * It contains the fetched data, loading status, and any potential errors.
+ * @template T The type of the data entity being managed.
+ */
+type UseApiState<T> = StandardResponse<T | T[]>;
+/**
+ * A collection of callable functions for performing CRUD and other operations.
+ * These actions automatically handle state updates like loading and refetching.
+ * @template T The type of the data entity being managed.
+ */
+interface UseApiActions<T> {
+    /** Fetches or refetches the list of data. */
+    fetch: (options?: QueryOptions) => Promise<void>;
+    /** Creates a new item. */
+    create: (newItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
+    /** Replaces an entire item. */
+    put: (id: string | number, item: T, options?: ActionOptions) => Promise<StandardResponse<T>>;
+    /** Partially updates an item. */
+    update: (id: string | number, updatedItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
+    /** Deletes an item. */
+    remove: (id: string | number, options?: ActionOptions) => Promise<StandardResponse<any>>;
+    /** Deletes multiple items in a single request. */
+    bulkRemove: (ids: Array<string | number>, options?: ActionOptions) => Promise<StandardResponse<any>>;
+    /** Uploads a file, optionally with additional data. */
+    upload: (file: File, additionalData?: Record<string, any>, options?: ActionOptions) => Promise<StandardResponse<any>>;
+}
+/**
+ * A collection of functions and properties for controlling the query parameters
+ * used for fetching data, such as pagination, sorting, and filtering.
+ */
+interface UseApiQuery {
+    /** The current query options state. */
+    options: QueryOptions;
+    /** A function to set the entire query options object at once. */
+    setOptions: React.Dispatch<React.SetStateAction<QueryOptions>>;
+    /** Sets the current page number and resets to the first page. */
+    setPage: (page: number) => void;
+    /** Sets the number of items per page and resets to the first page. */
+    setLimit: (limit: number) => void;
+    /** Sets the search term and resets to the first page. */
+    setSearchTerm: (search: string) => void;
+    /** Sets the sorting configuration. */
+    setSorting: (sortBy: {
+        key: string;
+        direction: 'asc' | 'desc';
+    }[]) => void;
+    /** Sets the filter object and resets to the first page. */
+    setFilters: (filter: Record<string, any>) => void;
+    /** Sets a single, custom query parameter and resets to the first page. */
+    setQueryParam: (key: string, value: any) => void;
+    /** Resets the query options to their initial state. */
+    reset: () => void;
+}
+/**
+ * The complete return type of the `useApi` hook.
+ * It encapsulates the state, actions, and query controls for a given API resource.
+ * @template T The type of the data entity being managed.
+ */
+interface UseApiReturn<T> {
+    /** The current state of the API request (data, loading, error). */
+    state: UseApiState<T>;
+    /** A function to manually set the state. Use with caution. */
+    setState: React.Dispatch<React.SetStateAction<UseApiState<T>>>;
+    /** An object containing all available data manipulation actions (create, update, delete, etc.). */
+    actions: UseApiActions<T>;
+    /** An object for controlling the query parameters for data fetching. */
+    query: UseApiQuery;
+}
+
 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: (options?: QueryOptions) => Promise<void>;
-        create: (newItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
-        put: (id: string, item: T, options?: ActionOptions) => Promise<StandardResponse<T>>;
-        update: (id: string, updatedItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
-        remove: (id: string, options?: ActionOptions) => Promise<StandardResponse<any>>;
-        bulkRemove: (ids: string[], options?: ActionOptions) => Promise<StandardResponse<any>>;
-        upload: (file: File, additionalData?: Record<string, any>, options?: ActionOptions) => Promise<StandardResponse<any>>;
-    };
-    query: {
-        options: QueryOptions;
-        setOptions: react.Dispatch<react.SetStateAction<QueryOptions>>;
-        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;
-        setQueryParam: (key: string, value: any) => void;
-        reset: () => void;
-    };
-};
+}>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): UseApiReturn<T>;
 
-export { type ActionOptions, type ApiClientConfig, type ApiError, type ApiResponse, type Logger, type Middleware, type MiddlewareContext, type PaginateQueryOptions, type PaginationMeta, type QueryOptions, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiConfig, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi };
+export { type ActionOptions, type ApiClientConfig, type ApiError, type ApiResponse, type LogLevel, type Logger, type Middleware, type MiddlewareContext, 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 };