@pagamio/frontend-commons-lib 0.8.213 → 0.8.215

package/lib/api/TanstackQueryProvider.d.ts

@@ -0,0 +1,146 @@
+/**
+ * @fileoverview TanStack Query Provider for the API client
+ * Provides a configured QueryClient with sensible defaults
+ */
+import { QueryClient } from '@tanstack/react-query';
+import type { ReactNode } from 'react';
+/**
+ * Default configuration for the QueryClient
+ * Matches the conservative caching strategy used in the SWR integration
+ */
+export declare const DEFAULT_QUERY_CLIENT_OPTIONS: {
+    queries: {
+        /** Data is considered fresh for 5 minutes */
+        staleTime: number;
+        /** Garbage collection time - 10 minutes */
+        gcTime: number;
+        /** Don't refetch on window focus (matches SWR config) */
+        refetchOnWindowFocus: boolean;
+        /** Don't refetch on reconnect (matches SWR config) */
+        refetchOnReconnect: boolean;
+        /** Retry failed requests once */
+        retry: number;
+        /** Retry delay */
+        retryDelay: (attemptIndex: number) => number;
+        /** Don't refetch on mount if data exists */
+        refetchOnMount: boolean;
+    };
+    mutations: {
+        /** Retry failed mutations once */
+        retry: number;
+    };
+};
+/**
+ * Configuration options for the ApiQueryProvider
+ */
+export interface ApiQueryProviderConfig {
+    /** Custom QueryClient options to merge with defaults */
+    queryClientOptions?: {
+        queries?: Partial<typeof DEFAULT_QUERY_CLIENT_OPTIONS.queries>;
+        mutations?: Partial<typeof DEFAULT_QUERY_CLIENT_OPTIONS.mutations>;
+    };
+    /** Show React Query Devtools (default: false in production) */
+    showDevtools?: boolean;
+    /** Devtools position */
+    devtoolsPosition?: 'left' | 'right' | 'top' | 'bottom';
+    /** Initial devtools open state */
+    devtoolsInitialIsOpen?: boolean;
+}
+/**
+ * Props for the ApiQueryProvider component
+ */
+export interface ApiQueryProviderProps extends ApiQueryProviderConfig {
+    /** React children */
+    children: ReactNode;
+    /** Optional existing QueryClient instance */
+    queryClient?: QueryClient;
+}
+/**
+ * Creates a configured QueryClient instance
+ *
+ * @example
+ * ```tsx
+ * // Create a custom query client
+ * const queryClient = createQueryClient({
+ *   queries: {
+ *     staleTime: 10 * 60 * 1000, // 10 minutes
+ *   },
+ * });
+ * ```
+ */
+export declare function createQueryClient(options?: ApiQueryProviderConfig['queryClientOptions']): QueryClient;
+/**
+ * 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 declare function ApiQueryProvider({ children, queryClient: existingQueryClient, queryClientOptions, showDevtools, devtoolsPosition, devtoolsInitialIsOpen, }: ApiQueryProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * 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/TanstackQueryProvider.js

@@ -0,0 +1,140 @@
+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/index.d.ts

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

package/lib/api/index.js

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

package/lib/api/tanstackQuery.d.ts

@@ -0,0 +1,249 @@
+/**
+ * @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>;
+};