api-core-lib 12.0.0 → 12.0.5

package/dist/apiModule.types-2yhaJWN3.d.cts

@@ -0,0 +1,257 @@
+import { InternalAxiosRequestConfig, AxiosResponse, AxiosRequestConfig, AxiosProgressEvent } from 'axios';
+import React__default from 'react';
+
+/**
+ * يمثل معلومات الترقيم (Pagination) التي قد تعود من ה-API.
+ */
+interface PaginationMeta {
+    itemsPerPage: number;
+    totalItems: number;
+    currentPage: number;
+    totalPages: number;
+    [key: string]: any;
+}
+/**
+ * يمثل خطأ تحقق واحد لحقل معين.
+ */
+interface ValidationError {
+    field: string;
+    message: string;
+}
+/**
+ * يمثل كائن الخطأ الموحد الذي تنتجه المكتبة.
+ */
+interface ApiError {
+    message: string;
+    status: number;
+    code?: string;
+    errors?: ValidationError[];
+    requestId?: string;
+}
+/**
+ * الكائن القياسي والموحد الذي تعيده جميع دوال المكتبة.
+ * هذا هو النوع الأساسي الذي سيتعامل معه المطورون.
+ * @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;
+    success: boolean;
+    message?: string;
+    validationErrors?: ValidationError[];
+}
+interface Tokens {
+    accessToken: string | null;
+    refreshToken: string | null;
+    expiresAt?: number;
+    tokenType?: string;
+}
+interface TokenManager {
+    getTokens(): Promise<Tokens>;
+    setTokens(tokens: Tokens): Promise<void>;
+    clearTokens(): Promise<void>;
+    isHttpOnly(): boolean;
+}
+interface MiddlewareContext {
+    req: InternalAxiosRequestConfig;
+    res?: AxiosResponse;
+    error?: any;
+    custom?: Record<string, any>;
+}
+type Middleware = (context: MiddlewareContext, next: () => Promise<void>) => Promise<void>;
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+interface RefreshTokenConfig {
+    path: string;
+    buildRequestBody?: (refreshToken: string) => Record<string, any>;
+    buildRequestHeaders?: (currentTokens: Tokens) => Record<string, string>;
+    extractTokens: (responseData: any) => {
+        accessToken: string;
+        refreshToken?: string;
+        expiresIn: number;
+        tokenType?: string;
+    };
+}
+interface ApiClientConfig {
+    baseURL?: string;
+    tokenManager: TokenManager;
+    timeout?: number;
+    headers?: Record<string, string>;
+    withCredentials?: boolean;
+    refreshTokenConfig?: RefreshTokenConfig;
+    onRefreshError?: (error: any) => void;
+    middleware?: Middleware[];
+    logLevel?: LogLevel;
+    defaultIsPublic?: boolean;
+    maxTokenRefreshRetries?: number;
+    maxQueueSize?: number;
+}
+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;
+}
+/**
+ * يمثل إعدادات إجراء واحد داخل الموديول.
+ */
+interface ActionConfig<TInput = any, TOutput = any> {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    description?: string;
+    isList?: boolean;
+    invalidates?: string[];
+}
+/**
+ * [مُحدَّث] يمثل الحالة التفاعلية الكاملة لإجراء واحد.
+ * هذا هو النوع الذي يتم إرجاعه في `states` من الهوك.
+ */
+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;
+}
+/**
+ * الكائن الموحد الذي يتم إرجاعه لكل إجراء، ويحتوي على حالته ومنفذه وأدوات التحكم.
+ */
+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__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. */
+    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;
+}
+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;
+}
+
+/** @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;
+    hasQuery?: boolean;
+    autoFetch?: boolean;
+    invalidates?: string[];
+    _input?: TInput;
+    _output?: TOutput;
+}
+/** @description Defines the complete structure of an API module. */
+interface ApiModuleConfig<TActions extends Record<string, ActionConfigModule<any, any>>> {
+    baseEndpoint: string;
+    actions: TActions;
+}
+/** @description Configuration options passed directly to the `useApiModule` hook. */
+interface UseApiModuleOptions {
+    onSuccess?: (actionName: string, message: string, data: unknown) => void;
+    onError?: (actionName: string, message: string, error?: ApiError | null) => void;
+    refetchOnWindowFocus?: boolean;
+    pathParams?: Record<string, any>;
+    enabled?: boolean;
+    hydratedState?: string;
+}
+/** 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;
+}
+/** @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;
+}
+
+export type { ApiClientConfig as A, ExecutableAction as E, InputOf as I, LogLevel as L, MiddlewareContext as M, OutputOf as O, PaginationMeta as P, QueryOptions as Q, RequestConfig as R, StandardResponse as S, Tokens as T, UseApiConfig as U, ValidationError as V, ActionConfigModule as a, ActionOptions as b, ActionStateModule as c, ApiError as d, ApiModuleConfig as e, UseApiModuleOptions as f, UseApiModuleReturn as g, UseApiQuery as h, TokenManager as i, Middleware as j, RefreshTokenConfig as k, ActionConfig as l, UseApiState as m, ActionState as n, ExecuteOptions as o, ModuleActions as p, ModuleStates as q };

package/dist/apiModule.types-2yhaJWN3.d.ts

@@ -0,0 +1,257 @@
+import { InternalAxiosRequestConfig, AxiosResponse, AxiosRequestConfig, AxiosProgressEvent } from 'axios';
+import React__default from 'react';
+
+/**
+ * يمثل معلومات الترقيم (Pagination) التي قد تعود من ה-API.
+ */
+interface PaginationMeta {
+    itemsPerPage: number;
+    totalItems: number;
+    currentPage: number;
+    totalPages: number;
+    [key: string]: any;
+}
+/**
+ * يمثل خطأ تحقق واحد لحقل معين.
+ */
+interface ValidationError {
+    field: string;
+    message: string;
+}
+/**
+ * يمثل كائن الخطأ الموحد الذي تنتجه المكتبة.
+ */
+interface ApiError {
+    message: string;
+    status: number;
+    code?: string;
+    errors?: ValidationError[];
+    requestId?: string;
+}
+/**
+ * الكائن القياسي والموحد الذي تعيده جميع دوال المكتبة.
+ * هذا هو النوع الأساسي الذي سيتعامل معه المطورون.
+ * @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;
+    success: boolean;
+    message?: string;
+    validationErrors?: ValidationError[];
+}
+interface Tokens {
+    accessToken: string | null;
+    refreshToken: string | null;
+    expiresAt?: number;
+    tokenType?: string;
+}
+interface TokenManager {
+    getTokens(): Promise<Tokens>;
+    setTokens(tokens: Tokens): Promise<void>;
+    clearTokens(): Promise<void>;
+    isHttpOnly(): boolean;
+}
+interface MiddlewareContext {
+    req: InternalAxiosRequestConfig;
+    res?: AxiosResponse;
+    error?: any;
+    custom?: Record<string, any>;
+}
+type Middleware = (context: MiddlewareContext, next: () => Promise<void>) => Promise<void>;
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+interface RefreshTokenConfig {
+    path: string;
+    buildRequestBody?: (refreshToken: string) => Record<string, any>;
+    buildRequestHeaders?: (currentTokens: Tokens) => Record<string, string>;
+    extractTokens: (responseData: any) => {
+        accessToken: string;
+        refreshToken?: string;
+        expiresIn: number;
+        tokenType?: string;
+    };
+}
+interface ApiClientConfig {
+    baseURL?: string;
+    tokenManager: TokenManager;
+    timeout?: number;
+    headers?: Record<string, string>;
+    withCredentials?: boolean;
+    refreshTokenConfig?: RefreshTokenConfig;
+    onRefreshError?: (error: any) => void;
+    middleware?: Middleware[];
+    logLevel?: LogLevel;
+    defaultIsPublic?: boolean;
+    maxTokenRefreshRetries?: number;
+    maxQueueSize?: number;
+}
+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;
+}
+/**
+ * يمثل إعدادات إجراء واحد داخل الموديول.
+ */
+interface ActionConfig<TInput = any, TOutput = any> {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    description?: string;
+    isList?: boolean;
+    invalidates?: string[];
+}
+/**
+ * [مُحدَّث] يمثل الحالة التفاعلية الكاملة لإجراء واحد.
+ * هذا هو النوع الذي يتم إرجاعه في `states` من الهوك.
+ */
+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;
+}
+/**
+ * الكائن الموحد الذي يتم إرجاعه لكل إجراء، ويحتوي على حالته ومنفذه وأدوات التحكم.
+ */
+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__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. */
+    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;
+}
+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;
+}
+
+/** @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;
+    hasQuery?: boolean;
+    autoFetch?: boolean;
+    invalidates?: string[];
+    _input?: TInput;
+    _output?: TOutput;
+}
+/** @description Defines the complete structure of an API module. */
+interface ApiModuleConfig<TActions extends Record<string, ActionConfigModule<any, any>>> {
+    baseEndpoint: string;
+    actions: TActions;
+}
+/** @description Configuration options passed directly to the `useApiModule` hook. */
+interface UseApiModuleOptions {
+    onSuccess?: (actionName: string, message: string, data: unknown) => void;
+    onError?: (actionName: string, message: string, error?: ApiError | null) => void;
+    refetchOnWindowFocus?: boolean;
+    pathParams?: Record<string, any>;
+    enabled?: boolean;
+    hydratedState?: string;
+}
+/** 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;
+}
+/** @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;
+}
+
+export type { ApiClientConfig as A, ExecutableAction as E, InputOf as I, LogLevel as L, MiddlewareContext as M, OutputOf as O, PaginationMeta as P, QueryOptions as Q, RequestConfig as R, StandardResponse as S, Tokens as T, UseApiConfig as U, ValidationError as V, ActionConfigModule as a, ActionOptions as b, ActionStateModule as c, ApiError as d, ApiModuleConfig as e, UseApiModuleOptions as f, UseApiModuleReturn as g, UseApiQuery as h, TokenManager as i, Middleware as j, RefreshTokenConfig as k, ActionConfig as l, UseApiState as m, ActionState as n, ExecuteOptions as o, ModuleActions as p, ModuleStates as q };