@pagamio/frontend-commons-lib 0.8.175 → 0.8.183

package/lib/api/client.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @fileoverview Generic API client for making HTTP requests with authentication support
+ */
+import { type CustomAuthConfig } from '../auth';
+import { type ApiClientConfig, type MockConfigArray, type RequestConfig } from './types';
+export declare class ApiClient<T extends CustomAuthConfig> {
+    private readonly config;
+    private readonly activeControllers;
+    private mockConfig?;
+    constructor(config: ApiClientConfig<T>);
+    /**
+     * Sets the mock configurations for the API client.
+     * @param mockConfig - Array of mock configurations.
+     */
+    setMockConfig(mockConfig: MockConfigArray): void;
+    /**
+     * Makes a GET request.
+     */
+    get<ResponseType>(endpoint: string, config?: RequestConfig): Promise<ResponseType>;
+    /**
+     * Makes a POST request.
+     */
+    post<ResponseType>(endpoint: string, data?: unknown, config?: RequestConfig): Promise<ResponseType>;
+    /**
+     * Makes a PUT request.
+     */
+    put<ResponseType>(endpoint: string, data?: unknown, config?: RequestConfig): Promise<ResponseType>;
+    /**
+     * Makes a PATCH request.
+     */
+    patch<ResponseType>(endpoint: string, data?: unknown, config?: RequestConfig): Promise<ResponseType>;
+    /**
+     * Makes a DELETE request.
+     */
+    delete<ResponseType>(endpoint: string, config?: RequestConfig): Promise<ResponseType>;
+    /**
+     * Aborts all ongoing requests.
+     */
+    /**
+     * Aborts all ongoing requests started without a custom signal.
+     */
+    abort(): void;
+    /**
+     * Sets a default header for all requests.
+     */
+    setDefaultHeader(key: string, value: string): void;
+    /**
+     * Finds a mock response that matches the request path, method, and params.
+     * @param path - The API endpoint path.
+     * @param method - The HTTP method.
+     * @param params - The query parameters or payload.
+     * @returns The mock response if a match is found, otherwise undefined.
+     */
+    private findMockResponse;
+    /**
+     * Normalizes request parameters or body into a plain object.
+     * @param params - The query parameters or body.
+     * @returns A plain object representation of the parameters or body.
+     */
+    private normalizeParams;
+    /**
+     * Creates a URL with query parameters.
+     */
+    private createUrl;
+    /**
+     * Handles a request by checking for a matching mock response.
+     * If no mock is found, proceeds with the real API request.
+     */
+    private handleRequest;
+    /**
+     * Makes the actual HTTP request.
+     */
+    private makeRequest;
+    private buildRequestConfig;
+    private injectAuthHeader;
+    private applyOnRequestHook;
+    private fetchWithTimeout;
+    private shouldHandle401;
+    private handle401AndRetry;
+    /**
+     * Handles the API response.
+     */
+    private handleResponse;
+    /**
+     * Handles API errors.
+     */
+    private handleError;
+}

package/lib/api/client.js

@@ -0,0 +1,339 @@
+import { ApiError, } from './types';
+export class ApiClient {
+    config;
+    activeControllers = new Set();
+    mockConfig;
+    constructor(config) {
+        this.config = {
+            timeout: 30000,
+            retries: 1,
+            retryDelay: 1000,
+            defaultHeaders: {
+                'Content-Type': 'application/json',
+            },
+            ...config,
+        };
+    }
+    /**
+     * Sets the mock configurations for the API client.
+     * @param mockConfig - Array of mock configurations.
+     */
+    setMockConfig(mockConfig) {
+        this.mockConfig = mockConfig;
+    }
+    /**
+     * Makes a GET request.
+     */
+    async get(endpoint, config) {
+        return this.handleRequest(endpoint, 'GET', config);
+    }
+    /**
+     * Makes a POST request.
+     */
+    async post(endpoint, data, config) {
+        if (data instanceof FormData) {
+            const headers = {};
+            // Copy existing headers except Content-Type
+            if (config?.headers) {
+                Object.entries(config.headers).forEach(([key, value]) => {
+                    if (key !== 'Content-Type' && typeof value === 'string') {
+                        headers[key] = value;
+                    }
+                });
+            }
+            const defaultHeaders = {};
+            // Copy existing default headers except Content-Type
+            if (this.config.defaultHeaders) {
+                Object.entries(this.config.defaultHeaders).forEach(([key, value]) => {
+                    if (key !== 'Content-Type' && typeof value === 'string') {
+                        defaultHeaders[key] = value;
+                    }
+                });
+            }
+            const requestConfig = {
+                ...config,
+                body: data,
+                headers,
+            };
+            return this.handleRequest(endpoint, 'POST', requestConfig, defaultHeaders);
+        }
+        const body = data ? JSON.stringify(data) : undefined;
+        return this.handleRequest(endpoint, 'POST', { ...config, body });
+    }
+    /**
+     * Makes a PUT request.
+     */
+    async put(endpoint, data, config) {
+        const body = data ? JSON.stringify(data) : undefined;
+        return this.handleRequest(endpoint, 'PUT', { ...config, body });
+    }
+    /**
+     * Makes a PATCH request.
+     */
+    async patch(endpoint, data, config) {
+        const body = data ? JSON.stringify(data) : undefined;
+        return this.handleRequest(endpoint, 'PATCH', { ...config, body });
+    }
+    /**
+     * Makes a DELETE request.
+     */
+    async delete(endpoint, config) {
+        return this.handleRequest(endpoint, 'DELETE', config);
+    }
+    /**
+     * Aborts all ongoing requests.
+     */
+    /**
+     * Aborts all ongoing requests started without a custom signal.
+     */
+    abort() {
+        this.activeControllers.forEach((controller) => controller.abort());
+        this.activeControllers.clear();
+    }
+    /**
+     * Sets a default header for all requests.
+     */
+    setDefaultHeader(key, value) {
+        if (this.config.defaultHeaders) {
+            this.config.defaultHeaders = {
+                ...this.config.defaultHeaders,
+                [key]: value,
+            };
+        }
+        else {
+            this.config.defaultHeaders = { [key]: value };
+        }
+    }
+    /**
+     * Finds a mock response that matches the request path, method, and params.
+     * @param path - The API endpoint path.
+     * @param method - The HTTP method.
+     * @param params - The query parameters or payload.
+     * @returns The mock response if a match is found, otherwise undefined.
+     */
+    findMockResponse(path, method, params) {
+        if (!this.mockConfig)
+            return undefined;
+        // Convert BodyInit (e.g., FormData, URLSearchParams) to a plain object
+        const normalizedParams = this.normalizeParams(params);
+        return this.mockConfig.find((mock) => mock.path === path &&
+            mock.method === method &&
+            (!mock.params || JSON.stringify(mock.params) === JSON.stringify(normalizedParams)))?.response;
+    }
+    /**
+     * Normalizes request parameters or body into a plain object.
+     * @param params - The query parameters or body.
+     * @returns A plain object representation of the parameters or body.
+     */
+    normalizeParams(params) {
+        if (!params)
+            return undefined;
+        // Handle FormData
+        if (params instanceof FormData) {
+            const result = {};
+            params.forEach((value, key) => {
+                result[key] = value;
+            });
+            return result;
+        }
+        // Handle URLSearchParams
+        if (params instanceof URLSearchParams) {
+            const result = {};
+            params.forEach((value, key) => {
+                result[key] = value;
+            });
+            return result;
+        }
+        // Handle Blob, ArrayBuffer, etc. (wrap in an object)
+        if (params instanceof Blob || params instanceof ArrayBuffer) {
+            return { body: params }; // Wrap in an object to make it compatible
+        }
+        if (typeof params === 'string') {
+            return JSON.parse(params);
+        }
+        // Handle plain objects or arrays
+        return params;
+    }
+    /**
+     * Creates a URL with query parameters.
+     */
+    createUrl(endpoint, params) {
+        const url = new URL(endpoint.startsWith('http') ? endpoint : `${this.config.baseURL}${endpoint}`);
+        if (params) {
+            Object.entries(params).forEach(([key, value]) => {
+                url.searchParams.append(key, value);
+            });
+        }
+        return url.toString();
+    }
+    /**
+     * Handles a request by checking for a matching mock response.
+     * If no mock is found, proceeds with the real API request.
+     */
+    async handleRequest(endpoint, method, config = {}, overrideDefaultHeaders) {
+        // Check for a mock response
+        const mockResponse = this.findMockResponse(endpoint, method, config.params || config.body);
+        if (mockResponse !== undefined) {
+            // Simulate network delay
+            await new Promise((resolve) => setTimeout(resolve, 500));
+            return mockResponse;
+        }
+        // Proceed with the real API request
+        const { params, timeout = this.config.timeout, retries = this.config.retries, skipAuth = false, skipRetry = false, skipRefresh = false, signal, ...requestConfig } = config;
+        let attempt = 0;
+        const maxAttempts = skipRetry ? 1 : (retries ?? 0) + 1;
+        while (attempt < maxAttempts) {
+            try {
+                const response = await this.makeRequest(endpoint, method, {
+                    params,
+                    timeout,
+                    skipAuth,
+                    skipRefresh,
+                    signal,
+                    requestConfig,
+                    overrideDefaultHeaders,
+                });
+                const data = await this.handleResponse(response);
+                if (!response.ok) {
+                    throw new ApiError(data?.message ?? 'Request failed', response.status, data);
+                }
+                return data;
+            }
+            catch (error) {
+                attempt++;
+                if (attempt >= maxAttempts) {
+                    await this.handleError(error);
+                    throw error;
+                }
+                await new Promise((resolve) => setTimeout(resolve, this.config.retryDelay));
+            }
+        }
+        throw new ApiError('Request failed after all retries', 0);
+    }
+    /**
+     * Makes the actual HTTP request.
+     */
+    async makeRequest(endpoint, method, config) {
+        const { params, timeout, skipAuth, skipRefresh, requestConfig, overrideDefaultHeaders, signal } = config;
+        const url = this.createUrl(endpoint, params);
+        // Use provided signal, or create a new AbortController for this request
+        let requestSignal;
+        let controller;
+        if (signal) {
+            requestSignal = signal;
+        }
+        else {
+            controller = new AbortController();
+            this.activeControllers.add(controller);
+            requestSignal = controller.signal;
+        }
+        let finalConfig = this.buildRequestConfig(requestConfig, method, overrideDefaultHeaders, requestSignal);
+        finalConfig = await this.injectAuthHeader(finalConfig, skipAuth);
+        finalConfig = await this.applyOnRequestHook(finalConfig);
+        let response;
+        try {
+            response = await this.fetchWithTimeout(url, finalConfig, timeout, controller);
+        }
+        finally {
+            if (controller)
+                this.activeControllers.delete(controller);
+        }
+        if (await this.shouldHandle401(response, skipAuth, skipRefresh)) {
+            return this.handle401AndRetry(endpoint, method, config);
+        }
+        return response;
+    }
+    buildRequestConfig(requestConfig, method, overrideDefaultHeaders, signal) {
+        return {
+            ...requestConfig,
+            method,
+            headers: {
+                ...(overrideDefaultHeaders ?? this.config.defaultHeaders),
+                ...requestConfig.headers,
+            },
+            signal,
+        };
+    }
+    async injectAuthHeader(finalConfig, skipAuth) {
+        if (!skipAuth && this.config.tokenManager) {
+            const { token } = this.config.tokenManager.getAccessToken();
+            if (token) {
+                return {
+                    ...finalConfig,
+                    headers: {
+                        ...finalConfig.headers,
+                        Authorization: `Bearer ${token}`,
+                    },
+                };
+            }
+        }
+        return finalConfig;
+    }
+    async applyOnRequestHook(finalConfig) {
+        if (this.config.onRequest) {
+            return this.config.onRequest(finalConfig);
+        }
+        return finalConfig;
+    }
+    async fetchWithTimeout(url, finalConfig, timeout, controller) {
+        let timeoutId = null;
+        try {
+            if (timeout && controller) {
+                timeoutId = setTimeout(() => {
+                    controller.abort();
+                }, timeout);
+            }
+            return await fetch(url, finalConfig);
+        }
+        finally {
+            if (timeoutId)
+                clearTimeout(timeoutId);
+        }
+    }
+    async shouldHandle401(response, skipAuth, skipRefresh) {
+        return response.status === 401 && !skipAuth && !skipRefresh && !!this.config.tokenManager;
+    }
+    async handle401AndRetry(endpoint, method, config) {
+        const refreshed = await this.config.tokenManager.refreshTokens();
+        if (refreshed) {
+            const newToken = this.config.tokenManager.getAccessToken().token;
+            if (newToken) {
+                return this.makeRequest(endpoint, method, {
+                    ...config,
+                    skipRefresh: true, // Prevent infinite refresh loop
+                });
+            }
+        }
+        this.config.onUnauthorized?.();
+        throw new ApiError('Unauthorized', 401);
+    }
+    /**
+     * Handles the API response.
+     */
+    async handleResponse(response) {
+        let data;
+        const contentType = response.headers.get('content-type');
+        if (contentType?.includes('application/json')) {
+            data = await response.json();
+        }
+        else {
+            data = response;
+        }
+        if (this.config.onResponse) {
+            data = await this.config.onResponse(response, data);
+        }
+        return data;
+    }
+    /**
+     * Handles API errors.
+     */
+    async handleError(error) {
+        if (error instanceof ApiError) {
+            await this.config.onError?.(error);
+        }
+        else if (error instanceof Error) {
+            const apiError = new ApiError(error.message, 0, { originalError: error });
+            await this.config.onError?.(apiError);
+        }
+    }
+}

package/lib/api/context.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @fileoverview API Context and utilities for managing a shared API client instance
+ * Provides context, provider component, and hooks for consistent API access across the application
+ */
+import { type ReactNode } from 'react';
+import type { CustomAuthConfig, TokenManager } from '../auth';
+import { ApiClient } from './client';
+import type { MockConfigArray } from './types';
+/**
+ * Props for the ApiProvider component
+ *
+ * @template T - Type extending CustomAuthConfig that defines the shape of authentication data
+ *
+ * @example
+ * ```tsx
+ * const apiClient = createApiClient<MyAuthConfig>({...});
+ *
+ * return (
+ *   <ApiProvider apiClient={apiClient}>
+ *     <App />
+ *   </ApiProvider>
+ * );
+ * ```
+ */
+interface ApiProviderProps<T extends CustomAuthConfig> {
+    /** React children nodes */
+    children: ReactNode;
+    /** Configured API client instance */
+    apiClient: ApiClient<T>;
+    /** Whether to use mock API */
+    mocked?: boolean;
+    /** Mock configurations for API requests */
+    mockConfig?: MockConfigArray;
+}
+/**
+ * Provider component for the API context
+ * Makes the API client instance available to all child components
+ *
+ * @template T - Type extending CustomAuthConfig
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <ApiProvider apiClient={apiClient}>
+ *       <MyComponents />
+ *     </ApiProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function ApiProvider<T extends CustomAuthConfig>({ children, apiClient, mocked, mockConfig, }: Readonly<ApiProviderProps<T>>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook for accessing the API client instance
+ * Must be used within an ApiProvider component
+ *
+ * @template T - Type extending CustomAuthConfig for type-safe API operations
+ * @returns The shared API client instance
+ * @throws Error if used outside of ApiProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const api = useApi<MyAuthConfig>();
+ *
+ *   const fetchData = async () => {
+ *     try {
+ *       const data = await api.get('/endpoint');
+ *       // Handle response
+ *     } catch (error) {
+ *       // Handle error
+ *     }
+ *   };
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+export declare function useApi<T extends CustomAuthConfig>(): ApiClient<T>;
+/**
+ * Factory function to create a configured ApiClient instance
+ *
+ * @template T - Type extending CustomAuthConfig that defines the shape of authentication data
+ * @param config - Configuration options for the API client
+ * @param config.baseURL - Base URL for all API requests
+ * @param config.tokenManager - Token manager instance for handling authentication
+ * @param config.defaultHeaders - Default headers to include in all requests
+ * @param config.timeout - Request timeout in milliseconds (default: 30000)
+ * @param config.retries - Number of retry attempts for failed requests (default: 1)
+ * @returns Configured ApiClient instance
+ *
+ * @example
+ * ```typescript
+ * const apiClient = createApiClient<MyAuthConfig>({
+ *   baseURL: 'https://api.example.com',
+ *   tokenManager: tokenManager,
+ *   defaultHeaders: {
+ *     'Content-Type': 'application/json',
+ *   },
+ *   timeout: 5000,
+ *   retries: 2,
+ * });
+ * ```
+ */
+export declare function createApiClient<T extends CustomAuthConfig>({ baseURL, tokenManager, defaultHeaders, timeout, retries, }: {
+    baseURL: string;
+    tokenManager: TokenManager<T>;
+    defaultHeaders?: HeadersInit;
+    timeout?: number;
+    retries?: number;
+}): ApiClient<T>;
+export {};

package/lib/api/context.js

@@ -0,0 +1,105 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * @fileoverview API Context and utilities for managing a shared API client instance
+ * Provides context, provider component, and hooks for consistent API access across the application
+ */
+import { createContext, useContext, useMemo } from 'react';
+import { ApiClient } from './client';
+/**
+ * React context for sharing the API client instance
+ * Initialized as undefined to ensure proper provider wrapping
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const ApiContext = createContext(undefined);
+/**
+ * Provider component for the API context
+ * Makes the API client instance available to all child components
+ *
+ * @template T - Type extending CustomAuthConfig
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <ApiProvider apiClient={apiClient}>
+ *       <MyComponents />
+ *     </ApiProvider>
+ *   );
+ * }
+ * ```
+ */
+export function ApiProvider({ children, apiClient, mocked = false, mockConfig = [], }) {
+    // Set mock config on the API client if mocking is enabled
+    if (mocked) {
+        apiClient.setMockConfig(mockConfig);
+    }
+    const value = useMemo(() => ({ apiClient }), [apiClient]);
+    return _jsx(ApiContext.Provider, { value: value, children: children });
+}
+/**
+ * Hook for accessing the API client instance
+ * Must be used within an ApiProvider component
+ *
+ * @template T - Type extending CustomAuthConfig for type-safe API operations
+ * @returns The shared API client instance
+ * @throws Error if used outside of ApiProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const api = useApi<MyAuthConfig>();
+ *
+ *   const fetchData = async () => {
+ *     try {
+ *       const data = await api.get('/endpoint');
+ *       // Handle response
+ *     } catch (error) {
+ *       // Handle error
+ *     }
+ *   };
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+export function useApi() {
+    const context = useContext(ApiContext);
+    if (!context) {
+        throw new Error('useApi must be used within an ApiProvider');
+    }
+    return context.apiClient;
+}
+/**
+ * Factory function to create a configured ApiClient instance
+ *
+ * @template T - Type extending CustomAuthConfig that defines the shape of authentication data
+ * @param config - Configuration options for the API client
+ * @param config.baseURL - Base URL for all API requests
+ * @param config.tokenManager - Token manager instance for handling authentication
+ * @param config.defaultHeaders - Default headers to include in all requests
+ * @param config.timeout - Request timeout in milliseconds (default: 30000)
+ * @param config.retries - Number of retry attempts for failed requests (default: 1)
+ * @returns Configured ApiClient instance
+ *
+ * @example
+ * ```typescript
+ * const apiClient = createApiClient<MyAuthConfig>({
+ *   baseURL: 'https://api.example.com',
+ *   tokenManager: tokenManager,
+ *   defaultHeaders: {
+ *     'Content-Type': 'application/json',
+ *   },
+ *   timeout: 5000,
+ *   retries: 2,
+ * });
+ * ```
+ */
+export function createApiClient({ baseURL, tokenManager, defaultHeaders = {}, timeout = 30000, retries = 1, }) {
+    return new ApiClient({
+        baseURL,
+        tokenManager,
+        defaultHeaders,
+        timeout,
+        retries,
+    });
+}

package/lib/api/index.d.ts

@@ -0,0 +1,4 @@
+export * from './client';
+export * from './swr';
+export * from './context';
+export * from './types';

package/lib/api/index.js

@@ -0,0 +1,4 @@
+export * from './client';
+export * from './swr';
+export * from './context';
+export * from './types';

package/lib/api/swr.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview SWR integration for the API client
+ */
+import { type Key, type SWRConfiguration, type SWRResponse } from 'swr';
+import type { ApiErrorResponse, RequestConfig, SpringBootResponse } from './types';
+/**
+ * Main SWR hook that automatically inherits auth config
+ * @template ResponseData - Type of the expected response data
+ * @template ErrorData - Type of the error response (defaults to ApiErrorResponse)
+ */
+export declare function useApiSWR<ResponseData, ErrorData = ApiErrorResponse>(endpoint: Key, config?: RequestConfig & SWRConfiguration<ResponseData, ErrorData>): SWRResponse<ResponseData, ErrorData>;
+/**
+ * Paginated SWR hook that inherits auth config
+ * @template ItemType - Type of items in the paginated response
+ * @template ResponseType - Type of the full response (defaults to SpringBootResponse)
+ */
+export declare function usePaginatedApiSWR<ItemType, ResponseType extends {
+    content: ItemType[];
+} = SpringBootResponse<ItemType>>(endpoint: Key, config?: RequestConfig & SWRConfiguration<ResponseType>): SWRResponse<ResponseType>;
+/**
+ * Mutation hook that inherits auth config
+ * @template ResponseData - Type of the expected response data
+ */
+export declare function useApiMutation<ResponseData>(): {
+    post: (endpoint: string, data?: unknown, config?: RequestConfig) => Promise<ResponseData>;
+    put: (endpoint: string, data?: unknown, config?: RequestConfig) => Promise<ResponseData>;
+    patch: (endpoint: string, data?: unknown, config?: RequestConfig) => Promise<ResponseData>;
+    delete: (endpoint: string, config?: RequestConfig) => Promise<ResponseData>;
+};
+/**
+ * Combined SWR and mutation hook
+ * @template ResponseData - Type of the expected response data
+ */
+export declare function useApiSWRWithMutation<ResponseData>(endpoint: Key, config?: RequestConfig & SWRConfiguration<ResponseData>): {
+    mutate: {
+        post: (endpoint: string, data?: unknown, config?: RequestConfig) => Promise<ResponseData>;
+        put: (endpoint: string, data?: unknown, config?: RequestConfig) => Promise<ResponseData>;
+        patch: (endpoint: string, data?: unknown, config?: RequestConfig) => Promise<ResponseData>;
+        delete: (endpoint: string, config?: RequestConfig) => Promise<ResponseData>;
+    };
+    refresh: () => Promise<any>;
+    data: ResponseData | undefined;
+    error: ApiErrorResponse | undefined;
+    isValidating: boolean;
+    isLoading: boolean;
+};