api-core-lib 11.11.10 → 12.0.4

package/dist/index.d.mts

@@ -1,40 +1,26 @@
-import { InternalAxiosRequestConfig, AxiosResponse, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method } from 'axios';
+import { InternalAxiosRequestConfig, AxiosResponse, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method, AxiosError } from 'axios';
+import * as React$1 from 'react';
+import React__default, { Dispatch, SetStateAction } from 'react';
 
 /**
- * @file src/types.ts
- * @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.
- */
-
-/**
- * Defines the structure for pagination metadata returned by the API.
+ * يمثل معلومات الترقيم (Pagination) التي قد تعود من ה-API.
  */
 interface PaginationMeta {
     itemsPerPage: number;
     totalItems: number;
     currentPage: number;
     totalPages: number;
+    [key: string]: any;
 }
 /**
- * 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;
@@ -44,12 +30,14 @@ interface ApiError {
     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.
+ * الكائن القياسي والموحد الذي تعيده جميع دوال المكتبة.
+ * هذا هو النوع الأساسي الذي سيتعامل معه المطورون.
+ * @template T نوع البيانات الأساسية.
  */
 interface StandardResponse<T> {
     data: T | null;
+    links?: Record<string, string | null>;
+    meta?: PaginationMeta | Record<string, any>;
     rawResponse: any;
     error: ApiError | null;
     loading: boolean;
@@ -57,125 +45,30 @@ interface StandardResponse<T> {
     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>;
-    /**
-     * 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;
 }
-/**
- * The context object passed to each middleware function in the pipeline.
- */
 interface MiddlewareContext {
     req: InternalAxiosRequestConfig;
     res?: AxiosResponse;
     error?: any;
     custom?: Record<string, any>;
 }
-/**
- * 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;
-    /** 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;
-}
-/**
- * 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 QueryOptions {
-    page?: number;
-    limit?: number;
-    search?: string;
-    sortBy?: {
-        key: string;
-        direction: 'asc' | 'desc';
-    }[];
-    filter?: Record<string, any>;
-    [key: string]: any;
-}
-/**
- * Defines additional options for action methods like create, update, or delete.
- */
-interface ActionOptions extends RequestConfig {
-    /**
-     * Overrides the default endpoint for a specific action. Useful for specialized routes.
-     * @example update('123', { status: 'active' }, { endpoint: '/items/123/activate' })
-     */
-    endpoint?: string;
-    /**
-     * 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 | null;
-    /** 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;
-    encodeQuery?: boolean;
-    pathParams?: Record<string, string | number>;
-    /** 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.
- */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
 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>;
-    /** A function to build any custom headers for the refresh call. */
     buildRequestHeaders?: (currentTokens: Tokens) => Record<string, string>;
-    /**
-     * 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;
         refreshToken?: string;
@@ -183,95 +76,88 @@ interface RefreshTokenConfig {
         tokenType?: string;
     };
 }
-/**
- * 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.
- */
-/**
- * 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;
-    /** A custom logger instance. Defaults to the browser `console`. */
-    /** An array of middleware functions to be executed with every request. */
     middleware?: Middleware[];
-    /**
-     * Sets the verbosity of the internal logger.
-     * @default 'info'
-     */
     logLevel?: LogLevel;
-    /**
-     * If true, all requests will be treated as public by default.
-     * A request can override this by explicitly setting `isPublic: false`.
-     * @default false
-     */
     defaultIsPublic?: boolean;
     maxTokenRefreshRetries?: number;
     maxQueueSize?: number;
 }
-
-declare function createApiClient(config: ApiClientConfig): AxiosInstance;
-
-/**
- * @file src/hooks/useApi.types.ts
- * @description This file defines the professional, publicly-facing types for the `useApi` hook,
- * providing a clean and stable contract for consumers.
- */
-
-/**
- * Configuration object for the `useApi` hook.
- * @template T The type of the data entity.
- */
+interface RequestConfig extends AxiosRequestConfig {
+    isPublic?: boolean;
+    cancelTokenKey?: string;
+    onUploadProgress?: (progressEvent: AxiosProgressEvent) => void;
+    onDownloadProgress?: (progressEvent: AxiosProgressEvent) => void;
+}
+interface QueryOptions {
+    page?: number;
+    limit?: number;
+    search?: string;
+    sortBy?: {
+        key: string;
+        direction: 'asc' | 'desc';
+    }[];
+    filter?: Record<string, any>;
+    [key: string]: any;
+}
+interface ActionOptions extends RequestConfig {
+    endpoint?: string;
+    refetch?: boolean;
+}
 /**
- * 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>;
+interface ActionConfig<TInput = any, TOutput = any> {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    description?: string;
+    isList?: boolean;
+    invalidates?: string[];
+}
 /**
- * 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.
+ * [مُحدَّث] يمثل الحالة التفاعلية الكاملة لإجراء واحد.
+ * هذا هو النوع الذي يتم إرجاعه في `states` من الهوك.
  */
-interface UseApiActions<T, TListItem = T extends (infer U)[] ? U : T> {
-    fetch: () => Promise<void>;
-    create: (newItem: Partial<TListItem>, options?: ActionOptions) => Promise<StandardResponse<TListItem>>;
-    put: (id: string | number, item: TListItem, options?: ActionOptions) => Promise<StandardResponse<TListItem>>;
-    update: (id: string | number, updatedItem: Partial<TListItem>, options?: ActionOptions) => Promise<StandardResponse<TListItem>>;
-    remove: (id: string | number, options?: ActionOptions) => Promise<StandardResponse<any>>;
-    bulkRemove: (ids: Array<string | number>, options?: ActionOptions) => Promise<StandardResponse<any>>;
+interface ActionStateModule<TOutput> {
+    data: TOutput | null;
+    links?: Record<string, string | null>;
+    meta?: PaginationMeta | Record<string, any>;
+    error: ApiError | null;
+    loading: boolean;
+    success: boolean;
+    called: boolean;
+    message?: string;
+    validationErrors?: ValidationError[];
+    rawResponse: any | null;
+    isStale?: boolean;
+    lastSuccessAt?: number;
 }
 /**
- * A collection of functions and properties for controlling the query parameters
- * used for fetching data, such as pagination, sorting, and filtering.
+ * الكائن الموحد الذي يتم إرجاعه لكل إجراء، ويحتوي على حالته ومنفذه وأدوات التحكم.
  */
+interface ExecutableAction<TInput, TOutput> {
+    state: ActionStateModule<TOutput>;
+    execute: (input?: TInput, options?: {
+        pathParams?: Record<string, any>;
+        config?: AxiosRequestConfig;
+        query?: QueryOptions;
+    }) => Promise<StandardResponse<TOutput>>;
+    reset: () => void;
+    query?: UseApiQuery;
+}
+type UseApiState<T> = StandardResponse<T>;
 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>>;
+    setOptions: React__default.Dispatch<React__default.SetStateAction<QueryOptions>>;
     /** Sets the current page number. */
     setPage: (page: number) => void;
     /** Sets the number of items per page and resets to the first page. */
@@ -290,68 +176,86 @@ interface UseApiQuery {
     /** 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> {
-    state: UseApiState<T>;
-    setState: React.Dispatch<React.SetStateAction<UseApiState<T>>>;
-    actions: UseApiActions<T>;
-    query: UseApiQuery;
+interface UseApiConfig<T> {
+    endpoint: string;
+    initialData?: T | null;
+    initialQuery?: QueryOptions;
+    enabled?: boolean;
+    refetchAfterChange?: boolean;
+    requestConfig?: RequestConfig;
+    pathParams?: Record<string, string | number>;
+    encodeQuery?: boolean;
+    onSuccess?: (message: string, data?: T) => void;
+    onError?: (message: string, error?: ApiError) => void;
 }
 
-interface ActionConfig<TInput = any, TOutput = any> {
+declare function createApiClient(config: ApiClientConfig): AxiosInstance;
+
+/** @description Extends the base ActionState with an `isStale` flag for automatic refetching. */
+interface ActionState<TOutput> extends ActionStateModule<TOutput> {
+    isStale?: boolean;
+}
+/** @description Defines the configuration for a single API action within a module. */
+interface ActionConfigModule<TInput = unknown, TOutput = unknown> {
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     path: string;
     description?: string;
-    isList?: boolean;
+    hasQuery?: boolean;
+    autoFetch?: boolean;
     invalidates?: string[];
+    _input?: TInput;
+    _output?: TOutput;
 }
-interface ApiModuleConfig {
+/** @description Defines the complete structure of an API module. */
+interface ApiModuleConfig<TActions extends Record<string, ActionConfigModule<any, any>>> {
     baseEndpoint: string;
-    actions: Record<string, ActionConfig<any, any>>;
+    actions: TActions;
 }
+/** @description Configuration options passed directly to the `useApiModule` hook. */
 interface UseApiModuleOptions {
-    onSuccess?: (actionName: string, message: string, data: any) => void;
+    onSuccess?: (actionName: string, message: string, data: unknown) => void;
     onError?: (actionName: string, message: string, error?: ApiError | null) => void;
-    staleTime?: number;
-    cacheTime?: number;
     refetchOnWindowFocus?: boolean;
+    pathParams?: Record<string, any>;
+    enabled?: boolean;
+    hydratedState?: string;
 }
-interface ActionState<TOutput> {
-    data: TOutput | null;
-    error: ApiError | null;
-    loading: boolean;
-    success: boolean;
-    called: boolean;
-}
-/**
- * The unified object for a single action, containing its state, executor, and controls.
- * This is the new, more ergonomic return structure.
- */
-interface ExecutableAction<TInput, TOutput> {
-    /** The reactive state for this specific action. */
-    state: ActionState<TOutput>;
-    /** The stable function to execute the API call. */
-    execute: (input?: TInput, options?: {
-        pathParams?: Record<string, any>;
-        config?: AxiosRequestConfig;
-        query?: QueryOptions;
-    }) => Promise<StandardResponse<TOutput>>;
-    /** A stable function to reset the action's state to its initial value. */
-    reset: () => void;
-    /** Query controls (pagination, sorting, etc.) available only if `isList: true`. */
-    query?: UseApiQuery;
+/** A utility type to infer the Input type (`TInput`) from an ActionConfigModule. */
+type InputOf<TActionConfig> = TActionConfig extends ActionConfigModule<infer TInput, any> ? TInput : never;
+/** A utility type to infer the Output type (`TOutput`) from an ActionConfigModule. */
+type OutputOf<TActionConfig> = TActionConfig extends ActionConfigModule<any, infer TOutput> ? TOutput : never;
+/** @description Defines the options for the `execute` function, enabling optimistic updates. */
+interface ExecuteOptions<TInput, TOutput, TContext = unknown> {
+    pathParams?: Record<string, any>;
+    config?: AxiosRequestConfig;
+    onMutate?: (variables: TInput) => TContext | Promise<TContext>;
+    onSuccess?: (data: TOutput, context?: TContext) => void;
+    onError?: (error: ApiError, context?: TContext) => void;
 }
-/**
- * The final, fully-typed object returned by the useApiModule hook.
- * It's a dictionary of executable actions.
- */
-type ModuleActions<TModule extends ApiModuleConfig> = {
-    [K in keyof TModule['actions']]: TModule['actions'][K] extends ActionConfig<infer TInput, infer TOutput> ? ExecutableAction<TInput, TOutput> : never;
+/** @description A fully-typed object representing the callable actions for a module. */
+type ModuleActions<TActions extends Record<string, ActionConfigModule<any, any>>> = {
+    [K in keyof TActions]: {
+        execute: <TContext = unknown>(input?: InputOf<TActions[K]>, options?: ExecuteOptions<InputOf<TActions[K]>, OutputOf<TActions[K]>, TContext>) => Promise<StandardResponse<OutputOf<TActions[K]>>>;
+        reset: (input?: InputOf<TActions[K]>, options?: {
+            pathParams?: Record<string, any>;
+        }) => void;
+    };
+};
+/** @description A fully-typed object representing the reactive states for each action in a module. */
+type ModuleStates<TActions extends Record<string, ActionConfigModule<any, any>>> = {
+    [K in keyof TActions]: ActionState<OutputOf<TActions[K]>>;
 };
+/** @description The complete, fully-typed return object of the `useApiModule` hook. */
+interface UseApiModuleReturn<TActions extends Record<string, ActionConfigModule<any, any>>> {
+    states: ModuleStates<TActions>;
+    actions: ModuleActions<TActions>;
+    queries: {
+        [K in keyof TActions]?: TActions[K] extends {
+            hasQuery: true;
+        } ? UseApiQuery : never;
+    };
+    dehydrate: () => string;
+}
 
 /**
  * A factory function to create a reusable set of API services for a specific endpoint.
@@ -368,22 +272,30 @@ declare function createApiServices<T>(axiosInstance: AxiosInstance, baseEndpoint
     bulkDelete: (ids: Array<string | number>, config?: ActionOptions) => Promise<StandardResponse<any>>;
     upload: (file: File, additionalData?: Record<string, any>, config?: ActionOptions) => Promise<StandardResponse<any>>;
 };
-
 /**
- * @file src/core/utils.ts
- * @description
- * يحتوي هذا الملف على مجموعة من الدوال المساعدة المستخدمة في جميع أنحاء المكتبة،
- * مثل بناء سلاسل الاستعلام (query strings) وإدارة إلغاء الطلبات،
- * بالإضافة إلى دوال التحقق من الأنواع (type guards).
+ * [نسخة محدثة ومحسّنة]
+ * دالة عامة وصريحة لتنفيذ أي طلب API.
+ * تستقبل وسائط منظمة بدلاً من محاولة تخمينها.
+ *
+ * @param axiosInstance - نسخة Axios.
+ * @param baseEndpoint - نقطة النهاية الأساسية للموديول.
+ * @param actionConfig - إعدادات الإجراء المحدد.
+ * @param params - كائن يحتوي على جميع البارامترات اللازمة للطلب.
+ * @returns Promise<StandardResponse<any>>
  */
+declare function callDynamicApi(axiosInstance: AxiosInstance, baseEndpoint: string, actionConfig: ActionConfigModule<any, any>, params: {
+    pathParams?: Record<string, string | number>;
+    body?: any;
+    config?: AxiosRequestConfig;
+}): Promise<StandardResponse<any>>;
 
 /**
- * يبني سلسلة استعلام (query string) من كائن خيارات مرن.
- * يتعامل مع البارامترات القياسية والمخصصة.
- * @param query - كائن من نوع QueryOptions.
+ * [نسخة مطورة] يبني سلسلة استعلام (query string) من كائن الخيارات.
+ * يدعم الآن الفلاتر المتداخلة (filter[key]=value) والترتيب المتعدد.
+ * @param options - كائن خيارات الاستعلام (فلترة, ترتيب, ...).
  * @returns سلسلة استعلام جاهزة للإضافة للرابط.
  */
-declare function buildPaginateQuery(query: QueryOptions): string;
+declare function buildPaginateQuery(options: QueryOptions): string;
 
 /**
  * Defines a single custom API action.
@@ -430,30 +342,204 @@ declare class CacheManager {
     set<T>(key: string, data: T, duration?: number): void;
     get<T>(key: string): T | null;
     /**
-     * [دالة جديدة] تعيد عنصر الـ Cache بالكامل (البيانات + معلومات إضافية)
-     * دون حذفه عند انتهاء الصلاحية. هذا يسمح لنا بتطبيق منطق stale-while-revalidate.
+     * [FIX] تم تحويلها إلى دالة عامة (generic) لتعيد النوع الصحيح.
+     * الآن بدلًا من إرجاع CacheItem<unknown>، ستُرجع CacheItem<T>.
      */
     getWithMeta<T>(key: string): CacheItem<T> | null;
     delete(key: string): void;
     clear(): void;
-    /**
-     * [دالة جديدة] تقوم بإبطال (حذف) جميع عناصر الـ Cache التي تبدأ ببادئة معينة.
-     * أساسية لعملية invalidation التلقائية.
-     */
     invalidateByPrefix(prefix: string): void;
 }
 declare const cacheManager: CacheManager;
 
-declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError) => StandardResponse<T>;
+/**
+ * [النسخة النهائية والمضمونة]
+ * تستخدم دوال حماية النوع المخصصة للقضاء على أخطاء 'never' بشكل نهائي.
+ */
+declare const processResponse: <T>(responseOrError: AxiosResponse<any> | AxiosError) => StandardResponse<T>;
+
+declare function useApi<T>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): any;
+
+/**
+ * Represents the internal state of the `useApiRecord` hook.
+ * It mirrors the `StandardResponse` structure, which is the unified response format
+ * used across the library.
+ * @template T The data type of the record.
+ */
+type UseApiRecordState<T> = StandardResponse<T>;
+/**
+ * Defines the action methods provided by the `useApiRecord` hook to interact with
+ * a single API resource.
+ * @template T The data type of the record.
+ */
+interface UseApiRecordActions<T> {
+    /**
+     * Manually fetches or refetches the record from the API.
+     */
+    fetch: () => Promise<void>;
+    /**
+     * Partially updates the record using an HTTP PATCH request.
+     * @param updatedItem An object containing the fields to update.
+     * @param options Additional request options, allowing overrides for this specific action.
+     * @returns A promise that resolves to the standard response object for the updated record.
+     */
+    update: (updatedItem: Partial<T>, options?: ActionOptions) => Promise<StandardResponse<T>>;
+    /**
+     * Replaces the entire record with a new one using an HTTP PUT request.
+     * @param item The complete new record object.
+     * @param options Additional request options.
+     * @returns A promise that resolves to the standard response object for the replaced record.
+     */
+    put: (item: T, options?: ActionOptions) => Promise<StandardResponse<T>>;
+    /**
+     * Deletes the record using an HTTP DELETE request.
+     * @param options Additional request options.
+     * @returns A promise that resolves to a standard response object with a null data payload.
+     */
+    remove: (options?: ActionOptions) => Promise<StandardResponse<null>>;
+    /**
+     * Resets the hook's state to its initial value.
+     */
+    resetState: () => void;
+}
+/**
+ * Defines the configuration options for the `useApiRecord` hook.
+ * @template T The data type of the record.
+ */
+interface UseApiRecordConfig<T> {
+    /**
+     * The base API endpoint template for the resource.
+     * Can contain placeholders like `{endpointName}`.
+     * @example 'v1/dynamic/{endpointName}'
+     */
+    endpoint: string;
+    /**
+     * An object containing key-value pairs to replace placeholders in the endpoint template.
+     * @example { endpointName: 'products' }
+     */
+    pathParams?: Record<string, string | number>;
+    /** The unique identifier of the record to fetch or modify. */
+    recordId?: string | number | null;
+    /** Optional initial data to populate the state before the first fetch is complete. */
+    initialData?: T | null;
+    /** If `false`, the hook will not automatically fetch data on mount. Defaults to `true`. */
+    enabled?: boolean;
+    /** If `true`, the record will be refetched after a successful `update`, `put`, or `remove` action. Defaults to `true`. */
+    refetchAfterChange?: boolean;
+    /** Default `RequestConfig` to apply to the initial GET request made by the hook. */
+    requestConfig?: RequestConfig;
+    /** A callback function executed on a successful API action. */
+    onSuccess?: (message: string, data?: any) => void;
+    /** A callback function executed on a failed API action. */
+    onError?: (message: string, error?: ApiError) => void;
+}
+/**
+ * The return value of the `useApiRecord` hook.
+ * @template T The data type of the record.
+ */
+interface UseApiRecordReturn<T> {
+    /** The current state of the API request, including data, loading, and error status. */
+    state: UseApiRecordState<T>;
+    /** Action methods to manipulate the record. */
+    actions: UseApiRecordActions<T>;
+    /** A React dispatch function to manually set the hook's state. Use with caution. */
+    setState: Dispatch<SetStateAction<UseApiRecordState<T>>>;
+}
+
+/**
+ * A React hook for managing the lifecycle of a single API resource (a record).
+ * It handles fetching, updating, replacing, and deleting a record, while managing
+ * loading, error, and data states. It supports dynamic path parameters for flexible API routing.
+ *
+ * @template T The data type of the record being managed.
+ * @param {AxiosInstance} axiosInstance - The configured Axios instance for making API calls.
+ * @param {UseApiRecordConfig<T>} config - Configuration options for the hook.
+ * @returns {UseApiRecordReturn<T>} An object containing the state, actions, and setState function.
+ */
+declare function useApiRecord<T>(axiosInstance: AxiosInstance, config: UseApiRecordConfig<T>): UseApiRecordReturn<T>;
+
+type EffectCallback = () => (void | (() => void));
+type DependencyList = readonly any[];
+declare function useDeepCompareEffect(callback: EffectCallback, dependencies: DependencyList): void;
+
+declare const ApiModuleProvider: React$1.Provider<UseApiModuleReturn<any> | null>;
+declare function useModuleContext<TModule extends ApiModuleConfig<any>>(): UseApiModuleReturn<TModule['actions']>;
+declare function useApiModule<TActions extends Record<string, ActionConfigModule<any, any>>>(axiosInstance: AxiosInstance, moduleConfig: ApiModuleConfig<TActions>, options?: UseApiModuleOptions): UseApiModuleReturn<TActions>;
+
+declare class GlobalStateManager {
+    private store;
+    /**
+     * يحصل على لقطة (snapshot) للحالة الحالية لمفتاح معين.
+     */
+    getSnapshot<T>(key: string): ActionStateModule<T>;
+    /**
+     * يسجل دالة callback للاستماع إلى التغييرات على مفتاح معين.
+     * @returns دالة لإلغاء الاشتراك.
+     */
+    subscribe(key: string, callback: () => void): () => void;
+    /**
+     * يحدّث الحالة لمفتاح معين ويقوم بإعلام جميع المشتركين.
+     */
+    setState<T>(key: string, updater: (prevState: ActionStateModule<T>) => ActionStateModule<T>): void;
+    /**
+     * يجعل البيانات المرتبطة بمفتاح معين "قديمة" (stale).
+     */
+    invalidate(key: string): void;
+    /**
+   * [نسخة محدثة وأكثر قوة]
+   * يجعل كل البيانات التي تبدأ بمفتاح معين "قديمة" (stale).
+   * @example invalidateByPrefix('myModule/list::') سيبطل كل صفحات القائمة.
+   */
+    invalidateByPrefix(prefix: string): void;
+    /**
+   * Serializes the current state of the query store into a JSON string.
+   * This is used on the server to pass the initial state to the client.
+   * @returns A JSON string representing the dehydrated state.
+   */
+    dehydrate(): string;
+    /**
+     * Merges a dehydrated state object into the current store.
+     * This is used on the client to hydrate the state received from the server.
+     * @param hydratedState - A JSON string from the `dehydrate` method.
+     */
+    rehydrate(hydratedState: string): void;
+}
+declare const globalStateManager: GlobalStateManager;
 
-declare function useApi<T>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): UseApiReturn<T>;
+/**
+ * @file src/hooks/useApi.types.ts
+ * @description This file defines the professional, publicly-facing types for the `useApi` hook,
+ * providing a clean and stable contract for consumers.
+ */
 
 /**
- * A production-ready custom hook that dynamically builds a set of executable and fully-typed API actions.
- * It provides a unified, ergonomic API for each action, collocating state and execution logic,
- * while guaranteeing stable function references to prevent re-renders.
+ * Configuration object for the `useApi` hook.
+ * @template T The type of the data entity.
+ */
+/**
+ * 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, TListItem = T extends (infer U)[] ? U : T> {
+    fetch: (querryOptions?: QueryOptions) => Promise<void>;
+    create: (newItem: Partial<TListItem>, options?: ActionOptions) => Promise<StandardResponse<TListItem>>;
+    put: (id: string | number, item: TListItem, options?: ActionOptions) => Promise<StandardResponse<TListItem>>;
+    update: (id: string | number, updatedItem: Partial<TListItem>, options?: ActionOptions) => Promise<StandardResponse<TListItem>>;
+    remove: (id: string | number, options?: ActionOptions) => Promise<StandardResponse<any>>;
+    bulkRemove: (ids: Array<string | number>, options?: ActionOptions) => Promise<StandardResponse<any>>;
+}
+/**
+ * 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.
  */
-declare function useApiModule<TModule extends ApiModuleConfig>(axiosInstance: AxiosInstance, moduleConfig: TModule, options?: UseApiModuleOptions): ModuleActions<TModule>;
+interface UseApiReturn<T> {
+    state: StandardResponse<T>;
+    setState: React.Dispatch<React.SetStateAction<StandardResponse<T>>>;
+    actions: UseApiActions<T>;
+    query: UseApiQuery;
+}
 
 type ApiResourceStatus = 'idle' | 'loading' | 'success' | 'error';
 interface UseApiResourceState<T> {
@@ -501,4 +587,4 @@ interface UseApiResourceReturn<T, TCreate, TUpdate, TPathParams> {
     setQuery: React.Dispatch<React.SetStateAction<QueryOptions>>;
 }
 
-export { type ActionConfig, type ActionOptions, type ActionState, type ApiClientConfig, type ApiError, type ApiModuleConfig, type ApiResourceStatus, type ApiResponse, type ExecutableAction, type LogLevel, type Middleware, type MiddlewareContext, type ModuleActions, type PaginationMeta, type QueryOptions, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiActions, type UseApiConfig, type UseApiModuleOptions, type UseApiQuery, type UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, type UseApiState, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi, useApiModule };
+export { type ActionConfig, type ActionConfigModule, type ActionOptions, type ActionState, type ActionStateModule, type ApiClientConfig, type ApiError, type ApiModuleConfig, ApiModuleProvider, type ApiResourceStatus, type ExecutableAction, type ExecuteOptions, type InputOf, type LogLevel, type Middleware, type MiddlewareContext, type ModuleActions, type ModuleStates, type OutputOf, type PaginationMeta, type QueryOptions, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UseApiActions, type UseApiConfig, type UseApiModuleOptions, type UseApiModuleReturn, type UseApiQuery, type UseApiRecordActions, type UseApiRecordConfig, type UseApiRecordReturn, type UseApiRecordState, type UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, type UseApiState, type ValidationError, buildPaginateQuery, cacheManager, callDynamicApi, createApiActions, createApiClient, createApiServices, globalStateManager, processResponse, useApi, useApiModule, useApiRecord, useDeepCompareEffect, useModuleContext };