api-core-lib 16.2.0 → 16.12.134

package/README.md

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

package/bin/cli-launcher.cjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+// bin/cli-launcher.js
+// هذا الملف هو مجرد مشغّل بسيط بصيغة CommonJS.
+// وظيفته الوحيدة هي تحميل وتشغيل منطق الـ CLI الفعلي من مجلد dist.
+
+try {
+  // استدعاء المنطق الرئيسي للـ CLI الذي تم بناؤه بواسطة tsup
+  require('../dist/cli.cjs');
+} catch (error) {
+  console.error('Failed to start the API Core generator.');
+  console.error(error);
+  process.exit(1);
+}

package/dist/apiModule.types-DEskFzOY.d.cts

@@ -0,0 +1,278 @@
+import { AxiosRequestConfig, AxiosProgressEvent, InternalAxiosRequestConfig, AxiosResponse } 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;
+    upload?: 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;
+    upload?: 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;
+    /** Re-fetches the query using the last used query options. */
+    refetch: () => 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;
+}
+interface t {
+    type: string;
+    payload?: any;
+}
+
+interface ActionState<TOutput> extends ActionStateModule<TOutput> {
+    isStale?: boolean;
+}
+interface ActionConfigModule<TInput extends Record<string, any> | undefined = undefined, TOutput = unknown> {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    description?: string;
+    hasQuery?: boolean;
+    autoFetch?: boolean;
+    cacheResponse?: boolean;
+    upload?: boolean;
+    invalidates?: string[];
+    requiresAuth?: boolean;
+    pathParams?: string[];
+    _input?: TInput;
+    _output?: TOutput;
+}
+interface ApiModuleConfig<TActions extends Record<string, ActionConfigModule<any, any>>> {
+    baseEndpoint: string;
+    actions: TActions;
+}
+interface UrlSyncOptions<TModule extends ApiModuleConfig<any>> {
+    searchParams: string;
+    updateUrl: (newSearchParams: string) => void;
+    actionsToSync: (keyof TModule['actions'])[];
+    defaultSyncAction?: keyof TModule['actions'];
+}
+interface UseApiModuleOptions<TModule extends ApiModuleConfig<any>, TExtra = {}> {
+    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;
+    extraContextData?: TExtra;
+    urlSync?: UrlSyncOptions<TModule>;
+    defaultQueryOptions?: Partial<Record<keyof TModule['actions'], QueryOptions>>;
+    initialActionsToExecute?: (keyof TModule['actions'])[];
+}
+type InputOf<TActionConfig> = TActionConfig extends ActionConfigModule<infer TInput, any> ? TInput : never;
+type OutputOf<TActionConfig> = TActionConfig extends ActionConfigModule<any, infer TOutput> ? TOutput : never;
+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;
+    onSettled?: (data?: TOutput, error?: ApiError, context?: TContext) => void;
+}
+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;
+    };
+};
+type ModuleStates<TActions extends Record<string, ActionConfigModule<any, any>>> = {
+    [K in keyof TActions]: ActionState<OutputOf<TActions[K]>>;
+};
+type ActionsWithQuery<TActions extends Record<string, ActionConfigModule<any, any>>> = {
+    [K in keyof TActions]: TActions[K] extends ActionConfigModule<QueryOptions, any> ? K : never;
+}[keyof TActions];
+type ModuleQueries<TActions extends Record<string, ActionConfigModule<any, any>>> = {
+    [K in ActionsWithQuery<TActions>]: UseApiQuery;
+};
+type UseApiModuleReturn<TActions extends Record<string, ActionConfigModule<any, any>>, TExtra extends object = {}> = {
+    states: ModuleStates<TActions>;
+    actions: ModuleActions<TActions>;
+    queries: ModuleQueries<TActions>;
+    dehydrate: () => string;
+} & TExtra;
+type ActionMethods<TAction extends ActionConfigModule<any, any>> = {
+    execute: <TContext = unknown>(input?: InputOf<TAction>, options?: ExecuteOptions<InputOf<TAction>, OutputOf<TAction>, TContext>) => Promise<StandardResponse<OutputOf<TAction>>>;
+    reset: (input?: InputOf<TAction>, options?: {
+        pathParams?: Record<string, any>;
+    }) => void;
+};
+
+export type { ApiModuleConfig as A, ExecutableAction as E, InputOf as I, LogLevel as L, ModuleStates 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, UseApiModuleOptions as a, UseApiModuleReturn as b, ModuleActions as c, ModuleQueries as d, ApiClientConfig as e, ActionConfigModule as f, ActionOptions as g, ActionStateModule as h, UseApiQuery as i, ApiError as j, TokenManager as k, MiddlewareContext as l, Middleware as m, RefreshTokenConfig as n, ActionConfig as o, UseApiState as p, ActionState as q, UrlSyncOptions as r, ExecuteOptions as s, t, ActionsWithQuery as u, ActionMethods as v };

package/dist/apiModule.types-DEskFzOY.d.ts

@@ -0,0 +1,278 @@
+import { AxiosRequestConfig, AxiosProgressEvent, InternalAxiosRequestConfig, AxiosResponse } 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;
+    upload?: 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;
+    upload?: 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;
+    /** Re-fetches the query using the last used query options. */
+    refetch: () => 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;
+}
+interface t {
+    type: string;
+    payload?: any;
+}
+
+interface ActionState<TOutput> extends ActionStateModule<TOutput> {
+    isStale?: boolean;
+}
+interface ActionConfigModule<TInput extends Record<string, any> | undefined = undefined, TOutput = unknown> {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    description?: string;
+    hasQuery?: boolean;
+    autoFetch?: boolean;
+    cacheResponse?: boolean;
+    upload?: boolean;
+    invalidates?: string[];
+    requiresAuth?: boolean;
+    pathParams?: string[];
+    _input?: TInput;
+    _output?: TOutput;
+}
+interface ApiModuleConfig<TActions extends Record<string, ActionConfigModule<any, any>>> {
+    baseEndpoint: string;
+    actions: TActions;
+}
+interface UrlSyncOptions<TModule extends ApiModuleConfig<any>> {
+    searchParams: string;
+    updateUrl: (newSearchParams: string) => void;
+    actionsToSync: (keyof TModule['actions'])[];
+    defaultSyncAction?: keyof TModule['actions'];
+}
+interface UseApiModuleOptions<TModule extends ApiModuleConfig<any>, TExtra = {}> {
+    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;
+    extraContextData?: TExtra;
+    urlSync?: UrlSyncOptions<TModule>;
+    defaultQueryOptions?: Partial<Record<keyof TModule['actions'], QueryOptions>>;
+    initialActionsToExecute?: (keyof TModule['actions'])[];
+}
+type InputOf<TActionConfig> = TActionConfig extends ActionConfigModule<infer TInput, any> ? TInput : never;
+type OutputOf<TActionConfig> = TActionConfig extends ActionConfigModule<any, infer TOutput> ? TOutput : never;
+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;
+    onSettled?: (data?: TOutput, error?: ApiError, context?: TContext) => void;
+}
+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;
+    };
+};
+type ModuleStates<TActions extends Record<string, ActionConfigModule<any, any>>> = {
+    [K in keyof TActions]: ActionState<OutputOf<TActions[K]>>;
+};
+type ActionsWithQuery<TActions extends Record<string, ActionConfigModule<any, any>>> = {
+    [K in keyof TActions]: TActions[K] extends ActionConfigModule<QueryOptions, any> ? K : never;
+}[keyof TActions];
+type ModuleQueries<TActions extends Record<string, ActionConfigModule<any, any>>> = {
+    [K in ActionsWithQuery<TActions>]: UseApiQuery;
+};
+type UseApiModuleReturn<TActions extends Record<string, ActionConfigModule<any, any>>, TExtra extends object = {}> = {
+    states: ModuleStates<TActions>;
+    actions: ModuleActions<TActions>;
+    queries: ModuleQueries<TActions>;
+    dehydrate: () => string;
+} & TExtra;
+type ActionMethods<TAction extends ActionConfigModule<any, any>> = {
+    execute: <TContext = unknown>(input?: InputOf<TAction>, options?: ExecuteOptions<InputOf<TAction>, OutputOf<TAction>, TContext>) => Promise<StandardResponse<OutputOf<TAction>>>;
+    reset: (input?: InputOf<TAction>, options?: {
+        pathParams?: Record<string, any>;
+    }) => void;
+};
+
+export type { ApiModuleConfig as A, ExecutableAction as E, InputOf as I, LogLevel as L, ModuleStates 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, UseApiModuleOptions as a, UseApiModuleReturn as b, ModuleActions as c, ModuleQueries as d, ApiClientConfig as e, ActionConfigModule as f, ActionOptions as g, ActionStateModule as h, UseApiQuery as i, ApiError as j, TokenManager as k, MiddlewareContext as l, Middleware as m, RefreshTokenConfig as n, ActionConfig as o, UseApiState as p, ActionState as q, UrlSyncOptions as r, ExecuteOptions as s, t, ActionsWithQuery as u, ActionMethods as v };