api-core-lib 12.12.111 → 16.2.0

package/README.md

@@ -1 +0,0 @@
-    "build": "tsup && node scripts/obfuscate.js",

package/dist/index.d.mts

@@ -0,0 +1,517 @@
+import { InternalAxiosRequestConfig, AxiosResponse, AxiosRequestConfig, AxiosProgressEvent, AxiosInstance, Method } from 'axios';
+
+/**
+ * @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.
+ */
+interface PaginationMeta {
+    itemsPerPage: number;
+    totalItems: number;
+    currentPage: number;
+    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;
+    status: number;
+    code?: string;
+    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>;
+    /**
+     * 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.
+ */
+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;
+        expiresIn: number;
+        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.
+ */
+/**
+ * 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>;
+/**
+ * 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: () => 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>>;
+}
+/**
+ * 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. */
+    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. */
+    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> {
+    state: UseApiState<T>;
+    setState: React.Dispatch<React.SetStateAction<UseApiState<T>>>;
+    actions: UseApiActions<T>;
+    query: UseApiQuery;
+}
+
+interface ActionConfig<TInput = any, TOutput = any> {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    description?: string;
+    isList?: boolean;
+    invalidates?: string[];
+    autoFetch?: boolean;
+    upload?: boolean;
+    _input?: QueryOptions;
+}
+interface ApiModuleConfig {
+    baseEndpoint: string;
+    actions: Record<string, ActionConfig<any, any>>;
+}
+interface UrlSyncOptions<TModule extends ApiModuleConfig> {
+    searchParams: string;
+    updateUrl: (newSearchParams: string) => void;
+    actionsToSync: (keyof TModule['actions'])[];
+    defaultSyncAction?: keyof TModule['actions'];
+}
+interface UseApiModuleOptions<TModule extends ApiModuleConfig> {
+    onSuccess?: (actionName: string, message: string, data: any) => void;
+    onError?: (actionName: string, message: string, error?: ApiError | null) => void;
+    staleTime?: number;
+    cacheTime?: number;
+    refetchOnWindowFocus?: boolean;
+    dehydratedState?: Record<string, Partial<ActionState<any>>>;
+    urlSync?: UrlSyncOptions<TModule>;
+    initialActionsToExecute?: (keyof TModule['actions'])[];
+    defaultQueryOptions?: Partial<Record<keyof TModule['actions'], QueryOptions>>;
+    pathParams?: Record<string, any>;
+}
+interface ActionState<TOutput> {
+    data: TOutput | null;
+    error: ApiError | null;
+    loading: boolean;
+    success: boolean;
+    called: boolean;
+}
+interface ExecutableAction<TInput, TOutput> {
+    state: ActionState<TOutput>;
+    execute: (input?: TInput, options?: {
+        pathParams?: Record<string, any>;
+        config?: AxiosRequestConfig;
+        query?: QueryOptions;
+        onSuccess?: (message: string, data?: TOutput) => void;
+        onError?: (message: string, error?: ApiError | null) => void;
+    }) => Promise<StandardResponse<TOutput>>;
+    reset: () => void;
+    query?: UseApiQuery;
+}
+type ModuleActions<TModule extends ApiModuleConfig> = {
+    [K in keyof TModule['actions']]: TModule['actions'][K] extends ActionConfig<infer TInput, infer TOutput> ? ExecutableAction<TInput, TOutput> : never;
+};
+type ModuleStates<TModule extends ApiModuleConfig> = {
+    [K in keyof TModule['actions']]: TModule['actions'][K] extends ActionConfig<any, infer TOutput> ? ActionState<TOutput> : never;
+};
+type ModuleQueries<TModule extends ApiModuleConfig> = {
+    [K in keyof TModule['actions']]: TModule['actions'][K]['isList'] extends true ? UseApiQuery : undefined;
+};
+interface UseApiModuleReturn<TModule extends ApiModuleConfig> {
+    actions: {
+        [K in keyof TModule['actions']]: ModuleActions<TModule>[K]['execute'];
+    };
+    states: ModuleStates<TModule>;
+    queries: ModuleQueries<TModule>;
+    refetch: (actionName: keyof TModule['actions']) => Promise<StandardResponse<any> | undefined>;
+}
+
+/**
+ * A factory function to create a reusable set of API services for a specific endpoint.
+ * It provides full CRUD operations plus advanced features like bulk deletion and file uploads,
+ * with intelligent, dynamic URL building.
+ */
+declare function createApiServices<T>(axiosInstance: AxiosInstance, baseEndpoint: string): {
+    get: (id?: string | number, config?: ActionOptions) => Promise<StandardResponse<T>>;
+    getWithQuery: (query: string, config?: RequestConfig) => Promise<StandardResponse<T>>;
+    post: (data: Partial<T>, config?: ActionOptions) => Promise<StandardResponse<T>>;
+    put: (id: string | number, data: T, config?: ActionOptions) => Promise<StandardResponse<T>>;
+    patch: (id: string | number, data: Partial<T>, config?: ActionOptions) => Promise<StandardResponse<T>>;
+    remove: (id: string | number, config?: ActionOptions) => Promise<StandardResponse<any>>;
+    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).
+ */
+
+/**
+ * يبني سلسلة استعلام (query string) من كائن خيارات مرن.
+ * يتعامل مع البارامترات القياسية والمخصصة.
+ * @param query - كائن من نوع QueryOptions.
+ * @returns سلسلة استعلام جاهزة للإضافة للرابط.
+ */
+declare function buildPaginateQuery(query: QueryOptions): string;
+
+/**
+ * Defines a single custom API action.
+ * @template TRequest - The type of the data sent in the request body/params.
+ * @template TResponse - The type of the data expected in the successful API response.
+ */
+type ApiAction<TRequest, TResponse> = (payload: TRequest, config?: RequestConfig) => Promise<StandardResponse<TResponse>>;
+/**
+ * A factory function to create a collection of typed, custom API actions.
+ *
+ * @template TActions - An object type where keys are action names and values are objects
+ *                      defining the endpoint, method, and types for that action.
+ * @param axiosInstance - The configured Axios instance from `createApiClient`.
+ * @param actionsConfig - An object defining the configuration for each custom action.
+ * @returns A fully-typed object of executable API action functions.
+ *
+ * @example
+ * const authActions = createApiActions(apiClient, {
+ *   login: { method: 'POST', endpoint: '/auth/login', requestType: {} as LoginCredentials, responseType: {} as AuthResponse },
+ *   getProfile: { method: 'GET', endpoint: '/user/profile', requestType: {} as void, responseType: {} as UserProfile }
+ * });
+ *
+ * // Usage:
+ * const result = await authActions.login({ email: '..', password: '..' });
+ */
+declare function createApiActions<TActions extends Record<string, {
+    method: Method;
+    endpoint: string;
+    requestType: any;
+    responseType: any;
+    log?: boolean;
+}>>(axiosInstance: AxiosInstance, actionsConfig: TActions): {
+    [K in keyof TActions]: ApiAction<TActions[K]['requestType'], TActions[K]['responseType']>;
+};
+
+interface CacheItem<T> {
+    data: T;
+    timestamp: number;
+    duration: number;
+}
+declare class CacheManager {
+    private cache;
+    private defaultDuration;
+    set<T>(key: string, data: T, duration?: number): void;
+    get<T>(key: string): T | null;
+    /**
+     * [دالة جديدة] تعيد عنصر الـ Cache بالكامل (البيانات + معلومات إضافية)
+     * دون حذفه عند انتهاء الصلاحية. هذا يسمح لنا بتطبيق منطق stale-while-revalidate.
+     */
+    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>;
+
+declare function useApi<T>(axiosInstance: AxiosInstance, config: UseApiConfig<T>): UseApiReturn<T>;
+
+declare function useApiModule<TModule extends ApiModuleConfig>(axiosInstance: AxiosInstance, moduleConfig: TModule, options?: UseApiModuleOptions<TModule>): UseApiModuleReturn<TModule>;
+
+type ApiResourceStatus = 'idle' | 'loading' | 'success' | 'error';
+interface UseApiResourceState<T> {
+    data: T | T[] | null;
+    error: ApiError | null;
+    status: ApiResourceStatus;
+    isFetching: boolean;
+    isMutating: boolean;
+    isSuccess: boolean;
+    lastResponse?: StandardResponse<any>;
+}
+interface UseApiResourceActions<T, TCreate, TUpdate, TPathParams> {
+    fetch: (pathParams?: TPathParams, queryOptions?: QueryOptions) => Promise<StandardResponse<T[]>>;
+    fetchOne: (pathParams: TPathParams & {
+        id: string | number;
+    }, queryOptions?: QueryOptions) => Promise<StandardResponse<T>>;
+    create: (newItem: TCreate, pathParams?: TPathParams, options?: ActionOptions) => Promise<StandardResponse<T>>;
+    update: (id: string | number, updatedItem: TUpdate, pathParams?: TPathParams, options?: ActionOptions) => Promise<StandardResponse<T>>;
+    remove: (id: string | number, pathParams?: TPathParams, options?: ActionOptions) => Promise<StandardResponse<any>>;
+    reset: () => void;
+}
+interface UseApiResourceConfig<TPathParams> {
+    /**
+     * The API endpoint template. Can be a static string or a function
+     * that builds the URL from parameters.
+     * @example '/users'
+     * @example (params) => `/modules/${params.moduleName}/records`
+     */
+    endpoint: string | ((params: TPathParams) => string);
+    /** Initial data to populate the state. */
+    initialData?: any;
+    /** Controls the verbosity of console logs for debugging. */
+    logLevel?: LogLevel;
+    /** Unique identifier for this hook instance, used in logging. */
+    logKey?: string;
+    /** Callback for success */
+    onSuccess?: (message: string, data?: any) => void;
+    /** Callback for error */
+    onError?: (message: string, error?: ApiError) => void;
+}
+interface UseApiResourceReturn<T, TCreate, TUpdate, TPathParams> {
+    state: UseApiResourceState<T>;
+    actions: UseApiResourceActions<T, TCreate, TUpdate, TPathParams>;
+    query: UseApiQuery;
+    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 ModuleQueries, type ModuleStates, type PaginationMeta, type QueryOptions, type RefreshTokenConfig, type RequestConfig, type StandardResponse, type TokenManager, type Tokens, type UrlSyncOptions, type UseApiActions, type UseApiConfig, type UseApiModuleOptions, type UseApiModuleReturn, type UseApiQuery, type UseApiResourceActions, type UseApiResourceConfig, type UseApiResourceReturn, type UseApiResourceState, type UseApiReturn, type UseApiState, type ValidationError, buildPaginateQuery, cacheManager, createApiActions, createApiClient, createApiServices, processResponse, useApi, useApiModule };