api-core-lib 11.10.10 → 12.0.0

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import { InternalAxiosRequestConfig, AxiosResponse, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method } from 'axios';
+import { Dispatch, SetStateAction } from 'react';
 
 /**
  * @file src/types.ts
@@ -88,7 +89,6 @@ interface MiddlewareContext {
     req: InternalAxiosRequestConfig;
     res?: AxiosResponse;
     error?: any;
-    logger: Logger;
     custom?: Record<string, any>;
 }
 /**
@@ -197,20 +197,6 @@ 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.
  */
@@ -230,7 +216,6 @@ interface ApiClientConfig {
     /** A callback function executed if the token refresh process fails. */
     onRefreshError?: (error: any) => void;
     /** A custom logger instance. Defaults to the browser `console`. */
-    logger?: Logger;
     /** An array of middleware functions to be executed with every request. */
     middleware?: Middleware[];
     /**
@@ -244,19 +229,10 @@ interface ApiClientConfig {
      * @default false
      */
     defaultIsPublic?: boolean;
+    maxTokenRefreshRetries?: number;
+    maxQueueSize?: number;
 }
 
-/**
- * @file src/core/client.ts
- * @description This is the heart of the API client library.
- * The `createApiClient` function constructs and configures a sophisticated Axios instance.
- * It features intelligent, security-first token management, a flexible middleware system,
- * and customizable logging, all designed to work seamlessly in modern web frameworks like Next.js.
- */
-
-/**
- * Creates and configures a new Axios instance with advanced features.
- */
 declare function createApiClient(config: ApiClientConfig): AxiosInstance;
 
 /**
@@ -327,122 +303,52 @@ interface UseApiReturn<T> {
     query: UseApiQuery;
 }
 
-/**
- * يصف إجراءً واحدًا داخل وحدة API، مع أنواع دقيقة للإدخال والإخراج.
- * @template TInput نوع بيانات الإدخال (الجسم أو معاملات الاستعلام).
- * @template TOutput نوع البيانات التي يتم إرجاعها في `data` عند النجاح.
- */
 interface ActionConfig<TInput = any, TOutput = any> {
-    /** نوع طلب HTTP. */
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-    /**
-     * المسار النسبي للإجراء. يمكن أن يحتوي على متغيرات مثل `{id}` أو `{tenantId}`.
-     * مثال: '/{id}/activate'
-     */
     path: string;
-    /**
-     * وصف للإجراء، مفيد للتوثيق وتلميحات محرر الكود.
-     */
     description?: string;
-    /**
-     * إذا كان `true`، فهذا يعني أن الإجراء يجلب قائمة بيانات ويدعم معاملات الاستعلام (pagination, sorting).
-     * سيتم تزويد هذا الإجراء بأدوات التحكم `query` تلقائيًا.
-     */
     isList?: boolean;
-    /**
-     * قائمة بأسماء الإجراءات (من نفس الموديول) التي يجب إبطال بياناتها في الـ Cache بعد نجاح هذا الإجراء.
-     * أساسي لمزامنة البيانات تلقائيًا بعد عمليات التعديل (Mutations).
-     * مثال: إجراء `update` يجب أن يبطل `getOne` و `list`.
-     */
     invalidates?: string[];
 }
-/**
- * يمثل الإعداد الكامل لوحدة API. هذا هو "مصدر الحقيقة" لمجموعة من نقاط النهاية.
- */
 interface ApiModuleConfig {
-    /** نقطة النهاية الأساسية للموديول (مثل '/api/v1/products'). */
     baseEndpoint: string;
-    /** قاموس يحتوي على جميع الإجراءات المتاحة في هذا الموديول. المفتاح هو اسم الإجراء. */
     actions: Record<string, ActionConfig<any, any>>;
 }
-/**
- * إعدادات اختيارية لتخصيص سلوك الهوك `useApiModule`.
- */
 interface UseApiModuleOptions {
-    /**
-     * دالة callback تُنفذ عند نجاح أي إجراء.
-     * @param actionName اسم الإجراء الذي نجح.
-     * @param message رسالة النجاح من الـ API.
-     * @param data البيانات المُرجعة.
-     */
     onSuccess?: (actionName: string, message: string, data: any) => void;
-    /**
-     * دالة callback تُنفذ عند فشل أي إجراء.
-     * @param actionName اسم الإجراء الذي فشل.
-     * @param message رسالة الخطأ من الـ API.
-     * @param error كائن الخطأ الموحد.
-     */
     onError?: (actionName: string, message: string, error?: ApiError | null) => void;
-    /**
-     * المدة التي تعتبر فيها البيانات "حية" (fresh) بالمللي ثانية.
-     * خلال هذه المدة، لن يتم إرسال طلب شبكة جديد لنفس البيانات.
-     * الافتراضي: `0` (مما يعني أنها تعتبر "قديمة" stale فورًا).
-     */
     staleTime?: number;
-    /**
-     * مدة بقاء البيانات في الـ Cache (بالمللي ثانية) قبل أن يتم حذفها تلقائيًا.
-     * يمرر إلى `cacheManager.set`. إذا لم يتم تحديده، يستخدم `CacheManager` قيمته الافتراضية.
-     */
     cacheTime?: number;
-    /**
-     * إذا كان `true`، سيتم إعادة جلب جميع الإجراءات التي تم استدعاؤها عند عودة المستخدم إلى نافذة التطبيق.
-     * الافتراضي: `true`.
-     */
     refetchOnWindowFocus?: boolean;
 }
-/**
- * الحالة التي يديرها كل إجراء على حدة.
- * @template TOutput نوع بيانات الإخراج.
- */
 interface ActionState<TOutput> {
-    /** البيانات التي تم جلبها بنجاح. تكون `null` في البداية أو عند حدوث خطأ. */
     data: TOutput | null;
-    /** كائن الخطأ في حال فشل الطلب. */
     error: ApiError | null;
-    /** `true` أثناء تنفيذ طلب الشبكة. */
     loading: boolean;
-    /** `true` إذا كان آخر طلب قد نجح. */
     success: boolean;
-    /** `true` إذا تم استدعاء الإجراء مرة واحدة على الأقل. مفيد للتمييز بين الحالة الأولية وحالة "لم يتم العثور على بيانات". */
     called: boolean;
 }
 /**
- * الكائن التنفيذي للإجراء، يجمع بين دالة التنفيذ وحالته الخاصة.
- * @template TInput نوع بيانات الإدخال.
- * @template TOutput نوع بيانات الإخراج.
+ * 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> {
-    /**
-     * الدالة الرئيسية لتنفيذ الإجراء.
-     * @param input بيانات الإدخال (الجسم أو معاملات الاستعلام).
-     * @param options خيارات إضافية للطلب مثل `pathParams` و `config` Axios.
-     * @returns `Promise` يحتوي على الاستجابة الموحدة `StandardResponse`.
-     */
+    /** 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>>;
-    /** الحالة الحالية لهذا الإجراء المحدد. */
-    state: ActionState<TOutput>;
-    /** دالة لإعادة حالة هذا الإجراء إلى وضعها الأولي. */
+    /** A stable function to reset the action's state to its initial value. */
     reset: () => void;
-    /** أدوات التحكم بالاستعلام (pagination, sorting) متاحة فقط للإجراءات المعرفة بـ `isList: true`. */
+    /** Query controls (pagination, sorting, etc.) available only if `isList: true`. */
     query?: UseApiQuery;
 }
 /**
- * النوع النهائي الذي يتم إرجاعه من الهوك `useApiModule`.
- * وهو عبارة عن قاموس من الإجراءات القابلة للتنفيذ، مع أنواع مستنتجة بالكامل.
+ * 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;
@@ -539,23 +445,103 @@ declare class CacheManager {
 }
 declare const cacheManager: CacheManager;
 
+declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError) => StandardResponse<T>;
+
+declare function useApi<T>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): UseApiReturn<T>;
+
 /**
- * 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`.
+ * هوك متقدم يقوم ببناء مجموعة من الإجراءات القابلة للتنفيذ من إعدادات موديول API،
+ * مع فصل تام بين الدوال المستقرة والحالات المتغيرة لمنع الحلقات اللانهائية.
  */
-declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError, log?: boolean) => StandardResponse<T>;
+declare function useApiModule<TModule extends ApiModuleConfig>(axiosInstance: AxiosInstance, moduleConfig: TModule, options?: UseApiModuleOptions): any;
 
-declare function useApi<T>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): UseApiReturn<T>;
+/**
+ * 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 for the resource (e.g., '/users'). */
+    endpoint: string;
+    /** 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>>>;
+}
 
 /**
- * هوك متقدم يقوم ببناء مجموعة من الإجراءات القابلة للتنفيذ من إعدادات موديول API.
+ * 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.
  */
-declare function useApiModule<TModule extends ApiModuleConfig>(axiosInstance: AxiosInstance, moduleConfig: TModule, options?: UseApiModuleOptions): ModuleActions<TModule>;
+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;
 
 type ApiResourceStatus = 'idle' | 'loading' | 'success' | 'error';
 interface UseApiResourceState<T> {
@@ -603,4 +589,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 Logger, 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 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 UseApiRecordActions, type UseApiRecordConfig, type UseApiRecordReturn, type UseApiRecordState, type UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, type UseApiState, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi, useApiModule, useApiRecord, useDeepCompareEffect };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { InternalAxiosRequestConfig, AxiosResponse, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method } from 'axios';
+import { Dispatch, SetStateAction } from 'react';
 
 /**
  * @file src/types.ts
@@ -88,7 +89,6 @@ interface MiddlewareContext {
     req: InternalAxiosRequestConfig;
     res?: AxiosResponse;
     error?: any;
-    logger: Logger;
     custom?: Record<string, any>;
 }
 /**
@@ -197,20 +197,6 @@ 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.
  */
@@ -230,7 +216,6 @@ interface ApiClientConfig {
     /** A callback function executed if the token refresh process fails. */
     onRefreshError?: (error: any) => void;
     /** A custom logger instance. Defaults to the browser `console`. */
-    logger?: Logger;
     /** An array of middleware functions to be executed with every request. */
     middleware?: Middleware[];
     /**
@@ -244,19 +229,10 @@ interface ApiClientConfig {
      * @default false
      */
     defaultIsPublic?: boolean;
+    maxTokenRefreshRetries?: number;
+    maxQueueSize?: number;
 }
 
-/**
- * @file src/core/client.ts
- * @description This is the heart of the API client library.
- * The `createApiClient` function constructs and configures a sophisticated Axios instance.
- * It features intelligent, security-first token management, a flexible middleware system,
- * and customizable logging, all designed to work seamlessly in modern web frameworks like Next.js.
- */
-
-/**
- * Creates and configures a new Axios instance with advanced features.
- */
 declare function createApiClient(config: ApiClientConfig): AxiosInstance;
 
 /**
@@ -327,122 +303,52 @@ interface UseApiReturn<T> {
     query: UseApiQuery;
 }
 
-/**
- * يصف إجراءً واحدًا داخل وحدة API، مع أنواع دقيقة للإدخال والإخراج.
- * @template TInput نوع بيانات الإدخال (الجسم أو معاملات الاستعلام).
- * @template TOutput نوع البيانات التي يتم إرجاعها في `data` عند النجاح.
- */
 interface ActionConfig<TInput = any, TOutput = any> {
-    /** نوع طلب HTTP. */
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-    /**
-     * المسار النسبي للإجراء. يمكن أن يحتوي على متغيرات مثل `{id}` أو `{tenantId}`.
-     * مثال: '/{id}/activate'
-     */
     path: string;
-    /**
-     * وصف للإجراء، مفيد للتوثيق وتلميحات محرر الكود.
-     */
     description?: string;
-    /**
-     * إذا كان `true`، فهذا يعني أن الإجراء يجلب قائمة بيانات ويدعم معاملات الاستعلام (pagination, sorting).
-     * سيتم تزويد هذا الإجراء بأدوات التحكم `query` تلقائيًا.
-     */
     isList?: boolean;
-    /**
-     * قائمة بأسماء الإجراءات (من نفس الموديول) التي يجب إبطال بياناتها في الـ Cache بعد نجاح هذا الإجراء.
-     * أساسي لمزامنة البيانات تلقائيًا بعد عمليات التعديل (Mutations).
-     * مثال: إجراء `update` يجب أن يبطل `getOne` و `list`.
-     */
     invalidates?: string[];
 }
-/**
- * يمثل الإعداد الكامل لوحدة API. هذا هو "مصدر الحقيقة" لمجموعة من نقاط النهاية.
- */
 interface ApiModuleConfig {
-    /** نقطة النهاية الأساسية للموديول (مثل '/api/v1/products'). */
     baseEndpoint: string;
-    /** قاموس يحتوي على جميع الإجراءات المتاحة في هذا الموديول. المفتاح هو اسم الإجراء. */
     actions: Record<string, ActionConfig<any, any>>;
 }
-/**
- * إعدادات اختيارية لتخصيص سلوك الهوك `useApiModule`.
- */
 interface UseApiModuleOptions {
-    /**
-     * دالة callback تُنفذ عند نجاح أي إجراء.
-     * @param actionName اسم الإجراء الذي نجح.
-     * @param message رسالة النجاح من الـ API.
-     * @param data البيانات المُرجعة.
-     */
     onSuccess?: (actionName: string, message: string, data: any) => void;
-    /**
-     * دالة callback تُنفذ عند فشل أي إجراء.
-     * @param actionName اسم الإجراء الذي فشل.
-     * @param message رسالة الخطأ من الـ API.
-     * @param error كائن الخطأ الموحد.
-     */
     onError?: (actionName: string, message: string, error?: ApiError | null) => void;
-    /**
-     * المدة التي تعتبر فيها البيانات "حية" (fresh) بالمللي ثانية.
-     * خلال هذه المدة، لن يتم إرسال طلب شبكة جديد لنفس البيانات.
-     * الافتراضي: `0` (مما يعني أنها تعتبر "قديمة" stale فورًا).
-     */
     staleTime?: number;
-    /**
-     * مدة بقاء البيانات في الـ Cache (بالمللي ثانية) قبل أن يتم حذفها تلقائيًا.
-     * يمرر إلى `cacheManager.set`. إذا لم يتم تحديده، يستخدم `CacheManager` قيمته الافتراضية.
-     */
     cacheTime?: number;
-    /**
-     * إذا كان `true`، سيتم إعادة جلب جميع الإجراءات التي تم استدعاؤها عند عودة المستخدم إلى نافذة التطبيق.
-     * الافتراضي: `true`.
-     */
     refetchOnWindowFocus?: boolean;
 }
-/**
- * الحالة التي يديرها كل إجراء على حدة.
- * @template TOutput نوع بيانات الإخراج.
- */
 interface ActionState<TOutput> {
-    /** البيانات التي تم جلبها بنجاح. تكون `null` في البداية أو عند حدوث خطأ. */
     data: TOutput | null;
-    /** كائن الخطأ في حال فشل الطلب. */
     error: ApiError | null;
-    /** `true` أثناء تنفيذ طلب الشبكة. */
     loading: boolean;
-    /** `true` إذا كان آخر طلب قد نجح. */
     success: boolean;
-    /** `true` إذا تم استدعاء الإجراء مرة واحدة على الأقل. مفيد للتمييز بين الحالة الأولية وحالة "لم يتم العثور على بيانات". */
     called: boolean;
 }
 /**
- * الكائن التنفيذي للإجراء، يجمع بين دالة التنفيذ وحالته الخاصة.
- * @template TInput نوع بيانات الإدخال.
- * @template TOutput نوع بيانات الإخراج.
+ * 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> {
-    /**
-     * الدالة الرئيسية لتنفيذ الإجراء.
-     * @param input بيانات الإدخال (الجسم أو معاملات الاستعلام).
-     * @param options خيارات إضافية للطلب مثل `pathParams` و `config` Axios.
-     * @returns `Promise` يحتوي على الاستجابة الموحدة `StandardResponse`.
-     */
+    /** 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>>;
-    /** الحالة الحالية لهذا الإجراء المحدد. */
-    state: ActionState<TOutput>;
-    /** دالة لإعادة حالة هذا الإجراء إلى وضعها الأولي. */
+    /** A stable function to reset the action's state to its initial value. */
     reset: () => void;
-    /** أدوات التحكم بالاستعلام (pagination, sorting) متاحة فقط للإجراءات المعرفة بـ `isList: true`. */
+    /** Query controls (pagination, sorting, etc.) available only if `isList: true`. */
     query?: UseApiQuery;
 }
 /**
- * النوع النهائي الذي يتم إرجاعه من الهوك `useApiModule`.
- * وهو عبارة عن قاموس من الإجراءات القابلة للتنفيذ، مع أنواع مستنتجة بالكامل.
+ * 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;
@@ -539,23 +445,103 @@ declare class CacheManager {
 }
 declare const cacheManager: CacheManager;
 
+declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError) => StandardResponse<T>;
+
+declare function useApi<T>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): UseApiReturn<T>;
+
 /**
- * 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`.
+ * هوك متقدم يقوم ببناء مجموعة من الإجراءات القابلة للتنفيذ من إعدادات موديول API،
+ * مع فصل تام بين الدوال المستقرة والحالات المتغيرة لمنع الحلقات اللانهائية.
  */
-declare const processResponse: <T>(responseOrError: AxiosResponse<any> | ApiError, log?: boolean) => StandardResponse<T>;
+declare function useApiModule<TModule extends ApiModuleConfig>(axiosInstance: AxiosInstance, moduleConfig: TModule, options?: UseApiModuleOptions): any;
 
-declare function useApi<T>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): UseApiReturn<T>;
+/**
+ * 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 for the resource (e.g., '/users'). */
+    endpoint: string;
+    /** 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>>>;
+}
 
 /**
- * هوك متقدم يقوم ببناء مجموعة من الإجراءات القابلة للتنفيذ من إعدادات موديول API.
+ * 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.
  */
-declare function useApiModule<TModule extends ApiModuleConfig>(axiosInstance: AxiosInstance, moduleConfig: TModule, options?: UseApiModuleOptions): ModuleActions<TModule>;
+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;
 
 type ApiResourceStatus = 'idle' | 'loading' | 'success' | 'error';
 interface UseApiResourceState<T> {
@@ -603,4 +589,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 Logger, 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 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 UseApiRecordActions, type UseApiRecordConfig, type UseApiRecordReturn, type UseApiRecordState, type UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, type UseApiState, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi, useApiModule, useApiRecord, useDeepCompareEffect };