@pagamio/frontend-commons-lib 0.8.217 → 0.8.218

package/lib/api/TanstackQueryProvider.js

@@ -1,140 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/**
- * @fileoverview TanStack Query Provider for the API client
- * Provides a configured QueryClient with sensible defaults
- */
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
-import { useMemo } from 'react';
-/**
- * Default configuration for the QueryClient
- * Matches the conservative caching strategy used in the SWR integration
- */
-export const DEFAULT_QUERY_CLIENT_OPTIONS = {
-    queries: {
-        /** Data is considered fresh for 5 minutes */
-        staleTime: 5 * 60 * 1000,
-        /** Garbage collection time - 10 minutes */
-        gcTime: 10 * 60 * 1000,
-        /** Don't refetch on window focus (matches SWR config) */
-        refetchOnWindowFocus: false,
-        /** Don't refetch on reconnect (matches SWR config) */
-        refetchOnReconnect: false,
-        /** Retry failed requests once */
-        retry: 1,
-        /** Retry delay */
-        retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
-        /** Don't refetch on mount if data exists */
-        refetchOnMount: false,
-    },
-    mutations: {
-        /** Retry failed mutations once */
-        retry: 1,
-    },
-};
-/**
- * Creates a configured QueryClient instance
- *
- * @example
- * ```tsx
- * // Create a custom query client
- * const queryClient = createQueryClient({
- *   queries: {
- *     staleTime: 10 * 60 * 1000, // 10 minutes
- *   },
- * });
- * ```
- */
-export function createQueryClient(options) {
-    return new QueryClient({
-        defaultOptions: {
-            queries: {
-                ...DEFAULT_QUERY_CLIENT_OPTIONS.queries,
-                ...options?.queries,
-            },
-            mutations: {
-                ...DEFAULT_QUERY_CLIENT_OPTIONS.mutations,
-                ...options?.mutations,
-            },
-        },
-    });
-}
-/**
- * Provider component for TanStack Query
- * Wraps your application with a configured QueryClient
- *
- * @example
- * ```tsx
- * // Basic usage
- * function App() {
- *   return (
- *     <ApiQueryProvider>
- *       <ApiProvider apiClient={apiClient}>
- *         <YourApp />
- *       </ApiProvider>
- *     </ApiQueryProvider>
- *   );
- * }
- *
- * // With custom configuration
- * function App() {
- *   return (
- *     <ApiQueryProvider
- *       queryClientOptions={{
- *         queries: {
- *           staleTime: 10 * 60 * 1000, // 10 minutes
- *           refetchOnWindowFocus: true,
- *         },
- *       }}
- *       showDevtools={process.env.NODE_ENV === 'development'}
- *       devtoolsPosition="bottom-right"
- *     >
- *       <ApiProvider apiClient={apiClient}>
- *         <YourApp />
- *       </ApiProvider>
- *     </ApiQueryProvider>
- *   );
- * }
- *
- * // With existing QueryClient
- * const queryClient = createQueryClient();
- *
- * function App() {
- *   return (
- *     <ApiQueryProvider queryClient={queryClient}>
- *       <ApiProvider apiClient={apiClient}>
- *         <YourApp />
- *       </ApiProvider>
- *     </ApiQueryProvider>
- *   );
- * }
- * ```
- */
-export function ApiQueryProvider({ children, queryClient: existingQueryClient, queryClientOptions, showDevtools = process.env.NODE_ENV === 'development', devtoolsPosition = 'bottom', devtoolsInitialIsOpen = false, }) {
-    // Create or use existing query client
-    const queryClient = useMemo(() => existingQueryClient ?? createQueryClient(queryClientOptions), [existingQueryClient, queryClientOptions]);
-    return (_jsxs(QueryClientProvider, { client: queryClient, children: [children, showDevtools && _jsx(ReactQueryDevtools, { initialIsOpen: devtoolsInitialIsOpen, position: devtoolsPosition })] }));
-}
-/**
- * Combined provider that includes both ApiQueryProvider and can be used
- * as a drop-in replacement when you want TanStack Query with your API client
- *
- * @example
- * ```tsx
- * import { CombinedApiQueryProvider, createApiClient } from '@pagamio/frontend-commons-lib';
- *
- * const apiClient = createApiClient({ ... });
- *
- * function App() {
- *   return (
- *     <CombinedApiQueryProvider
- *       apiClient={apiClient}
- *       showDevtools={true}
- *     >
- *       <YourApp />
- *     </CombinedApiQueryProvider>
- *   );
- * }
- * ```
- */
-export { ApiQueryProvider as TanStackQueryProvider };

package/lib/api/tanstackQuery.d.ts

@@ -1,249 +0,0 @@
-/**
- * @fileoverview TanStack Query integration for the API client
- * Provides hooks for data fetching, mutations, and cache management
- */
-import { type InfiniteData, type QueryKey, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseQueryResult } from '@tanstack/react-query';
-import type { ApiErrorResponse, RequestConfig, SpringBootResponse } from './types';
-/**
- * Extended request config for TanStack Query hooks
- */
-export interface TanStackRequestConfig extends RequestConfig {
-    /** HTTP method for the request */
-    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-}
-/**
- * Main TanStack Query hook that automatically inherits auth config
- * @template TData - Type of the expected response data
- * @template TError - Type of the error response (defaults to ApiErrorResponse)
- *
- * @example
- * ```tsx
- * function UsersList() {
- *   const { data, isLoading, error } = useApiQuery<User[]>({
- *     queryKey: ['users'],
- *     endpoint: '/users',
- *   });
- *
- *   if (isLoading) return <div>Loading...</div>;
- *   if (error) return <div>Error: {error.message}</div>;
- *
- *   return (
- *     <ul>
- *       {data?.map(user => <li key={user.id}>{user.name}</li>)}
- *     </ul>
- *   );
- * }
- * ```
- */
-export declare function useApiQuery<TData = unknown, TError = ApiErrorResponse>(options: {
-    /** Unique query key for caching */
-    queryKey: QueryKey;
-    /** API endpoint to fetch */
-    endpoint: string;
-    /** Request configuration */
-    requestConfig?: TanStackRequestConfig;
-} & Omit<UseQueryOptions<TData, TError, TData, QueryKey>, 'queryKey' | 'queryFn'>): UseQueryResult<TData, TError>;
-/**
- * Paginated TanStack Query hook for Spring Boot style responses
- * @template TItem - Type of items in the paginated response
- * @template TError - Type of the error response
- *
- * @example
- * ```tsx
- * function PaginatedUsers() {
- *   const { data, isLoading } = usePaginatedApiQuery<User>({
- *     queryKey: ['users', { page: 0, size: 10 }],
- *     endpoint: '/users?page=0&size=10',
- *   });
- *
- *   return (
- *     <div>
- *       {data?.content.map(user => <div key={user.id}>{user.name}</div>)}
- *       <p>Total: {data?.totalElements}</p>
- *     </div>
- *   );
- * }
- * ```
- */
-export declare function usePaginatedApiQuery<TItem, TError = ApiErrorResponse>(options: {
-    queryKey: QueryKey;
-    endpoint: string;
-    requestConfig?: TanStackRequestConfig;
-} & Omit<UseQueryOptions<SpringBootResponse<TItem>, TError, SpringBootResponse<TItem>, QueryKey>, 'queryKey' | 'queryFn'>): UseQueryResult<SpringBootResponse<TItem>, TError>;
-/**
- * Infinite query hook for infinite scrolling with Spring Boot pagination
- * @template TItem - Type of items in the paginated response
- * @template TError - Type of the error response
- *
- * @example
- * ```tsx
- * function InfiniteUsersList() {
- *   const {
- *     data,
- *     fetchNextPage,
- *     hasNextPage,
- *     isFetchingNextPage,
- *   } = useInfiniteApiQuery<User>({
- *     queryKey: ['users', 'infinite'],
- *     endpoint: '/users',
- *     pageSize: 20,
- *   });
- *
- *   return (
- *     <div>
- *       {data?.pages.flatMap(page => page.content).map(user => (
- *         <div key={user.id}>{user.name}</div>
- *       ))}
- *       {hasNextPage && (
- *         <button onClick={() => fetchNextPage()} disabled={isFetchingNextPage}>
- *           {isFetchingNextPage ? 'Loading...' : 'Load More'}
- *         </button>
- *       )}
- *     </div>
- *   );
- * }
- * ```
- */
-export declare function useInfiniteApiQuery<TItem, TError = ApiErrorResponse>(options: {
-    queryKey: QueryKey;
-    /** Base endpoint (page params will be appended) */
-    endpoint: string;
-    /** Number of items per page */
-    pageSize?: number;
-    /** Parameter name for page number (default: 'page') */
-    pageParam?: string;
-    /** Parameter name for page size (default: 'size') */
-    sizeParam?: string;
-    requestConfig?: TanStackRequestConfig;
-} & Omit<UseInfiniteQueryOptions<SpringBootResponse<TItem>, TError, InfiniteData<SpringBootResponse<TItem>>, QueryKey>, 'queryKey' | 'queryFn' | 'getNextPageParam' | 'getPreviousPageParam' | 'initialPageParam'>): UseInfiniteQueryResult<InfiniteData<SpringBootResponse<TItem>>, TError>;
-/**
- * Mutation types for the useApiQueryMutation hook
- */
-export type MutationType = 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-/**
- * Variables passed to mutation function
- */
-export interface MutationVariables<TData = unknown> {
-    /** API endpoint */
-    endpoint: string;
-    /** Request body data (not needed for DELETE) */
-    data?: TData;
-    /** Additional request config */
-    config?: TanStackRequestConfig;
-}
-/**
- * Mutation hook for POST, PUT, PATCH, DELETE operations
- * @template TData - Type of the response data
- * @template TVariables - Type of the mutation variables
- * @template TError - Type of the error response
- *
- * @example
- * ```tsx
- * function CreateUserForm() {
- *   const queryClient = useQueryClient();
- *   const { mutate, isPending } = useApiQueryMutation<User, CreateUserDto>({
- *     method: 'POST',
- *     onSuccess: () => {
- *       queryClient.invalidateQueries({ queryKey: ['users'] });
- *     },
- *   });
- *
- *   const handleSubmit = (data: CreateUserDto) => {
- *     mutate({ endpoint: '/users', data });
- *   };
- *
- *   return (
- *     <form onSubmit={handleSubmit}>
- *       // ...form fields
- *       <button type="submit" disabled={isPending}>
- *         {isPending ? 'Creating...' : 'Create User'}
- *       </button>
- *     </form>
- *   );
- * }
- * ```
- */
-export declare function useApiQueryMutation<TData = unknown, TVariables = unknown, TError = ApiErrorResponse>(options: {
-    /** HTTP method for the mutation */
-    method: MutationType;
-    /** Query keys to invalidate on success */
-    invalidateKeys?: QueryKey[];
-} & Omit<UseMutationOptions<TData, TError, MutationVariables<TVariables>>, 'mutationFn'>): UseMutationResult<TData, TError, MutationVariables<TVariables>>;
-/**
- * Convenience hook for POST mutations
- */
-export declare function useApiPostMutation<TData = unknown, TVariables = unknown, TError = ApiErrorResponse>(options?: Omit<Parameters<typeof useApiQueryMutation<TData, TVariables, TError>>[0], 'method'>): UseMutationResult<TData, TError, MutationVariables<TVariables>>;
-/**
- * Convenience hook for PUT mutations
- */
-export declare function useApiPutMutation<TData = unknown, TVariables = unknown, TError = ApiErrorResponse>(options?: Omit<Parameters<typeof useApiQueryMutation<TData, TVariables, TError>>[0], 'method'>): UseMutationResult<TData, TError, MutationVariables<TVariables>>;
-/**
- * Convenience hook for PATCH mutations
- */
-export declare function useApiPatchMutation<TData = unknown, TVariables = unknown, TError = ApiErrorResponse>(options?: Omit<Parameters<typeof useApiQueryMutation<TData, TVariables, TError>>[0], 'method'>): UseMutationResult<TData, TError, MutationVariables<TVariables>>;
-/**
- * Convenience hook for DELETE mutations
- */
-export declare function useApiDeleteMutation<TData = unknown, TError = ApiErrorResponse>(options?: Omit<Parameters<typeof useApiQueryMutation<TData, never, TError>>[0], 'method'>): UseMutationResult<TData, TError, MutationVariables<never>>;
-/**
- * Hook for prefetching data
- *
- * @example
- * ```tsx
- * function UserLink({ userId }: { userId: string }) {
- *   const prefetch = useApiPrefetch();
- *
- *   return (
- *     <Link
- *       to={`/users/${userId}`}
- *       onMouseEnter={() => prefetch({
- *         queryKey: ['user', userId],
- *         endpoint: `/users/${userId}`,
- *       })}
- *     >
- *       View User
- *     </Link>
- *   );
- * }
- * ```
- */
-export declare function useApiPrefetch(): <TData = unknown>(options: {
-    queryKey: QueryKey;
-    endpoint: string;
-    requestConfig?: TanStackRequestConfig;
-    staleTime?: number;
-}) => Promise<void>;
-/**
- * Hook for accessing the query client with typed helpers
- *
- * @example
- * ```tsx
- * function RefreshButton() {
- *   const { invalidate, setData, removeQueries } = useApiQueryClient();
- *
- *   return (
- *     <button onClick={() => invalidate(['users'])}>
- *       Refresh Users
- *     </button>
- *   );
- * }
- * ```
- */
-export declare function useApiQueryClient(): {
-    /** The underlying query client */
-    queryClient: import("@tanstack/react-query").QueryClient;
-    /** Invalidate queries by key */
-    invalidate: (queryKey: QueryKey) => Promise<void>;
-    /** Set query data directly */
-    setData: <TData>(queryKey: QueryKey, data: TData) => unknown;
-    /** Get cached query data */
-    getData: <TData>(queryKey: QueryKey) => TData | undefined;
-    /** Remove queries from cache */
-    removeQueries: (queryKey: QueryKey) => void;
-    /** Cancel ongoing queries */
-    cancelQueries: (queryKey: QueryKey) => Promise<void>;
-    /** Refetch queries */
-    refetch: (queryKey: QueryKey) => Promise<void>;
-    /** Reset queries to initial state */
-    resetQueries: (queryKey: QueryKey) => Promise<void>;
-};

package/lib/api/tanstackQuery.js

@@ -1,299 +0,0 @@
-/**
- * @fileoverview TanStack Query integration for the API client
- * Provides hooks for data fetching, mutations, and cache management
- */
-import { useInfiniteQuery, useMutation, useQuery, useQueryClient, } from '@tanstack/react-query';
-import { useApi } from './context';
-/**
- * Creates a fetcher function using the existing ApiClient
- * @template ResponseData - Expected response type
- */
-function useApiFetcher() {
-    const api = useApi();
-    return async (endpoint, config) => {
-        switch (config?.method) {
-            case 'POST':
-                return api.post(endpoint, config.body ? JSON.parse(config.body.toString()) : undefined, config);
-            case 'PUT':
-                return api.put(endpoint, config.body ? JSON.parse(config.body.toString()) : undefined, config);
-            case 'PATCH':
-                return api.patch(endpoint, config.body ? JSON.parse(config.body.toString()) : undefined, config);
-            case 'DELETE':
-                return api.delete(endpoint, config);
-            default:
-                return api.get(endpoint, config);
-        }
-    };
-}
-/**
- * Main TanStack Query hook that automatically inherits auth config
- * @template TData - Type of the expected response data
- * @template TError - Type of the error response (defaults to ApiErrorResponse)
- *
- * @example
- * ```tsx
- * function UsersList() {
- *   const { data, isLoading, error } = useApiQuery<User[]>({
- *     queryKey: ['users'],
- *     endpoint: '/users',
- *   });
- *
- *   if (isLoading) return <div>Loading...</div>;
- *   if (error) return <div>Error: {error.message}</div>;
- *
- *   return (
- *     <ul>
- *       {data?.map(user => <li key={user.id}>{user.name}</li>)}
- *     </ul>
- *   );
- * }
- * ```
- */
-export function useApiQuery(options) {
-    const fetcher = useApiFetcher();
-    const { queryKey, endpoint, requestConfig, ...queryOptions } = options;
-    return useQuery({
-        queryKey,
-        queryFn: () => fetcher(endpoint, requestConfig),
-        ...queryOptions,
-    });
-}
-/**
- * Paginated TanStack Query hook for Spring Boot style responses
- * @template TItem - Type of items in the paginated response
- * @template TError - Type of the error response
- *
- * @example
- * ```tsx
- * function PaginatedUsers() {
- *   const { data, isLoading } = usePaginatedApiQuery<User>({
- *     queryKey: ['users', { page: 0, size: 10 }],
- *     endpoint: '/users?page=0&size=10',
- *   });
- *
- *   return (
- *     <div>
- *       {data?.content.map(user => <div key={user.id}>{user.name}</div>)}
- *       <p>Total: {data?.totalElements}</p>
- *     </div>
- *   );
- * }
- * ```
- */
-export function usePaginatedApiQuery(options) {
-    return useApiQuery(options);
-}
-/**
- * Infinite query hook for infinite scrolling with Spring Boot pagination
- * @template TItem - Type of items in the paginated response
- * @template TError - Type of the error response
- *
- * @example
- * ```tsx
- * function InfiniteUsersList() {
- *   const {
- *     data,
- *     fetchNextPage,
- *     hasNextPage,
- *     isFetchingNextPage,
- *   } = useInfiniteApiQuery<User>({
- *     queryKey: ['users', 'infinite'],
- *     endpoint: '/users',
- *     pageSize: 20,
- *   });
- *
- *   return (
- *     <div>
- *       {data?.pages.flatMap(page => page.content).map(user => (
- *         <div key={user.id}>{user.name}</div>
- *       ))}
- *       {hasNextPage && (
- *         <button onClick={() => fetchNextPage()} disabled={isFetchingNextPage}>
- *           {isFetchingNextPage ? 'Loading...' : 'Load More'}
- *         </button>
- *       )}
- *     </div>
- *   );
- * }
- * ```
- */
-export function useInfiniteApiQuery(options) {
-    const fetcher = useApiFetcher();
-    const { queryKey, endpoint, pageSize = 20, pageParam = 'page', sizeParam = 'size', requestConfig, ...queryOptions } = options;
-    // Build endpoint with pagination params
-    const buildEndpoint = (page) => {
-        const separator = endpoint.includes('?') ? '&' : '?';
-        return `${endpoint}${separator}${pageParam}=${page}&${sizeParam}=${pageSize}`;
-    };
-    return useInfiniteQuery({
-        queryKey,
-        queryFn: ({ pageParam: page }) => fetcher(buildEndpoint(page), requestConfig),
-        initialPageParam: 0,
-        getNextPageParam: (lastPage) => {
-            if (lastPage.last)
-                return undefined;
-            return lastPage.number + 1;
-        },
-        getPreviousPageParam: (firstPage) => {
-            if (firstPage.first)
-                return undefined;
-            return firstPage.number - 1;
-        },
-        ...queryOptions,
-    });
-}
-/**
- * Mutation hook for POST, PUT, PATCH, DELETE operations
- * @template TData - Type of the response data
- * @template TVariables - Type of the mutation variables
- * @template TError - Type of the error response
- *
- * @example
- * ```tsx
- * function CreateUserForm() {
- *   const queryClient = useQueryClient();
- *   const { mutate, isPending } = useApiQueryMutation<User, CreateUserDto>({
- *     method: 'POST',
- *     onSuccess: () => {
- *       queryClient.invalidateQueries({ queryKey: ['users'] });
- *     },
- *   });
- *
- *   const handleSubmit = (data: CreateUserDto) => {
- *     mutate({ endpoint: '/users', data });
- *   };
- *
- *   return (
- *     <form onSubmit={handleSubmit}>
- *       // ...form fields
- *       <button type="submit" disabled={isPending}>
- *         {isPending ? 'Creating...' : 'Create User'}
- *       </button>
- *     </form>
- *   );
- * }
- * ```
- */
-export function useApiQueryMutation(options) {
-    const api = useApi();
-    const queryClient = useQueryClient();
-    const { method, invalidateKeys, ...mutationOptions } = options;
-    return useMutation({
-        mutationFn: async ({ endpoint, data, config }) => {
-            switch (method) {
-                case 'POST':
-                    return api.post(endpoint, data, config);
-                case 'PUT':
-                    return api.put(endpoint, data, config);
-                case 'PATCH':
-                    return api.patch(endpoint, data, config);
-                case 'DELETE':
-                    return api.delete(endpoint, config);
-                default:
-                    throw new Error(`Unsupported mutation method: ${method}`);
-            }
-        },
-        onSuccess: async () => {
-            // Invalidate specified query keys
-            if (invalidateKeys?.length) {
-                await Promise.all(invalidateKeys.map((key) => queryClient.invalidateQueries({ queryKey: key })));
-            }
-        },
-        ...mutationOptions,
-    });
-}
-/**
- * Convenience hook for POST mutations
- */
-export function useApiPostMutation(options) {
-    return useApiQueryMutation({ method: 'POST', ...options });
-}
-/**
- * Convenience hook for PUT mutations
- */
-export function useApiPutMutation(options) {
-    return useApiQueryMutation({ method: 'PUT', ...options });
-}
-/**
- * Convenience hook for PATCH mutations
- */
-export function useApiPatchMutation(options) {
-    return useApiQueryMutation({ method: 'PATCH', ...options });
-}
-/**
- * Convenience hook for DELETE mutations
- */
-export function useApiDeleteMutation(options) {
-    return useApiQueryMutation({ method: 'DELETE', ...options });
-}
-/**
- * Hook for prefetching data
- *
- * @example
- * ```tsx
- * function UserLink({ userId }: { userId: string }) {
- *   const prefetch = useApiPrefetch();
- *
- *   return (
- *     <Link
- *       to={`/users/${userId}`}
- *       onMouseEnter={() => prefetch({
- *         queryKey: ['user', userId],
- *         endpoint: `/users/${userId}`,
- *       })}
- *     >
- *       View User
- *     </Link>
- *   );
- * }
- * ```
- */
-export function useApiPrefetch() {
-    const queryClient = useQueryClient();
-    const fetcher = useApiFetcher();
-    return (options) => {
-        const { queryKey, endpoint, requestConfig, staleTime } = options;
-        return queryClient.prefetchQuery({
-            queryKey,
-            queryFn: () => fetcher(endpoint, requestConfig),
-            staleTime,
-        });
-    };
-}
-/**
- * Hook for accessing the query client with typed helpers
- *
- * @example
- * ```tsx
- * function RefreshButton() {
- *   const { invalidate, setData, removeQueries } = useApiQueryClient();
- *
- *   return (
- *     <button onClick={() => invalidate(['users'])}>
- *       Refresh Users
- *     </button>
- *   );
- * }
- * ```
- */
-export function useApiQueryClient() {
-    const queryClient = useQueryClient();
-    return {
-        /** The underlying query client */
-        queryClient,
-        /** Invalidate queries by key */
-        invalidate: (queryKey) => queryClient.invalidateQueries({ queryKey }),
-        /** Set query data directly */
-        setData: (queryKey, data) => queryClient.setQueryData(queryKey, data),
-        /** Get cached query data */
-        getData: (queryKey) => queryClient.getQueryData(queryKey),
-        /** Remove queries from cache */
-        removeQueries: (queryKey) => queryClient.removeQueries({ queryKey }),
-        /** Cancel ongoing queries */
-        cancelQueries: (queryKey) => queryClient.cancelQueries({ queryKey }),
-        /** Refetch queries */
-        refetch: (queryKey) => queryClient.refetchQueries({ queryKey }),
-        /** Reset queries to initial state */
-        resetQueries: (queryKey) => queryClient.resetQueries({ queryKey }),
-    };
-}