@0xsequence/marketplace-sdk 0.9.0 → 1.0.0

package/src/react/hooks/ui/useFilters.tsx

@@ -0,0 +1,178 @@
+'use client';
+
+import type { PropertyFilter } from '@0xsequence/metadata';
+import { useQuery } from '@tanstack/react-query';
+import type { Optional } from '../../_internal';
+import {
+	type FetchFiltersParams,
+	type FiltersQueryOptions,
+	filtersQueryOptions,
+} from '../../queries/filters';
+import { useConfig } from '../config/useConfig';
+
+export type UseFiltersParams = Optional<FiltersQueryOptions, 'config'>;
+
+/**
+ * Hook to fetch metadata filters for a collection
+ *
+ * Retrieves property filters for a collection from the metadata service,
+ * with support for marketplace-specific filter configuration including
+ * exclusion rules and custom ordering.
+ *
+ * @param params - Configuration parameters
+ * @param params.chainId - The chain ID (must be number, e.g., 1 for Ethereum, 137 for Polygon)
+ * @param params.collectionAddress - The collection contract address to fetch filters for
+ * @param params.showAllFilters - Whether to show all filters or apply marketplace filtering
+ * @param params.excludePropertyValues - Whether to exclude property values from the response
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing property filters for the collection
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data: filters, isLoading } = useFilters({
+ *   chainId: 137,
+ *   collectionAddress: '0x1234...'
+ * })
+ *
+ * if (data) {
+ *   console.log(`Found ${data.length} filters`);
+ *   data.forEach(filter => {
+ *     console.log(`${filter.name}: ${filter.values?.join(', ')}`);
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * With marketplace filtering disabled:
+ * ```typescript
+ * const { data: allFilters } = useFilters({
+ *   chainId: 1,
+ *   collectionAddress: '0x5678...',
+ *   showAllFilters: true, // Bypass marketplace filter rules
+ *   query: {
+ *     enabled: Boolean(selectedCollection),
+ *     staleTime: 300000 // Cache for 5 minutes
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * Exclude property values for faster loading:
+ * ```typescript
+ * const { data: filterNames } = useFilters({
+ *   chainId: 137,
+ *   collectionAddress: collectionAddress,
+ *   excludePropertyValues: true, // Only get filter names, not values
+ *   query: {
+ *     enabled: Boolean(collectionAddress)
+ *   }
+ * })
+ * ```
+ */
+export function useFilters(params: UseFiltersParams) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = filtersQueryOptions({
+		config,
+		...rest,
+	});
+
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+/**
+ * Hook to progressively load collection filters
+ *
+ * First loads filter names only for fast initial display, then loads full filter
+ * data with values. Uses placeholder data to provide immediate feedback while
+ * full data loads in the background.
+ *
+ * @param params - Configuration parameters (same as useFilters)
+ *
+ * @returns Query result with additional loading states
+ * @returns result.isLoadingNames - Whether filter names are still loading
+ * @returns result.isFetchingValues - Whether filter values are being fetched
+ *
+ * @example
+ * Progressive filter loading:
+ * ```typescript
+ * const {
+ *   data: filters,
+ *   isLoadingNames,
+ *   isFetchingValues,
+ *   isLoading
+ * } = useFiltersProgressive({
+ *   chainId: 137,
+ *   collectionAddress: '0x1234...'
+ * })
+ *
+ * if (isLoadingNames) {
+ *   return <div>Loading filters...</div>;
+ * }
+ *
+ * return (
+ *   <div>
+ *     {filters?.map(filter => (
+ *       <FilterComponent
+ *         key={filter.name}
+ *         filter={filter}
+ *         isLoadingValues={isFetchingValues}
+ *       />
+ *     ))}
+ *   </div>
+ * );
+ * ```
+ */
+export function useFiltersProgressive(params: UseFiltersParams) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const namesQuery = useQuery(
+		filtersQueryOptions({
+			config,
+			...rest,
+			excludePropertyValues: true,
+		}),
+	);
+
+	const fullQuery = useQuery({
+		...filtersQueryOptions({
+			config,
+			...rest,
+		}),
+		placeholderData: namesQuery.data,
+	});
+
+	const isLoadingNames = namesQuery.isLoading;
+	const isFetchingValues = fullQuery.isPlaceholderData && fullQuery.isFetching;
+
+	return {
+		...fullQuery,
+		isFetchingValues,
+		isLoadingNames,
+	};
+}
+
+export { filtersQueryOptions };
+
+export type { FetchFiltersParams, FiltersQueryOptions };
+
+// Legacy exports for backward compatibility
+export type UseFiltersArgs = {
+	chainId: number;
+	collectionAddress: string;
+	showAllFilters?: boolean;
+	excludePropertyValues?: boolean;
+	query?: {
+		enabled?: boolean;
+	};
+};
+
+export type UseFilterReturn = PropertyFilter[];

package/src/react/hooks/ui/useOpenConnectModal.tsx

@@ -0,0 +1,9 @@
+import { useConfig } from '../config/useConfig';
+
+export const useOpenConnectModal = () => {
+	const context = useConfig();
+
+	return {
+		openConnectModal: context.openConnectModal,
+	};
+};

package/src/react/hooks/util/optimisticCancelUpdates.ts

@@ -43,6 +43,7 @@ export const updateQueriesOnCancel = ({
 		queryClient.invalidateQueries({
 			queryKey: collectableKeys.highestOffers,
 			exact: false,
+			predicate: (query) => !query.meta?.persistent,
 		});
 	}, 2 * SECOND);
 

package/src/react/hooks/utils/index.ts

@@ -0,0 +1,9 @@
+export * from './useAutoSelectFeeOption';
+export * from './useCheckoutOptions';
+export * from './useCheckoutOptionsSalesContract';
+export * from './useComparePrices';
+export * from './useConvertPriceToUSD';
+export * from './useEnsureCorrectChain';
+export * from './useGetReceiptFromHash';
+export * from './useRoyalty';
+export * from './useSwitchChainWithModal';

package/src/react/hooks/{__tests__ → utils}/useAutoSelectFeeOption.test.tsx

@@ -9,7 +9,7 @@ import {
 	mockIndexerHandler,
 	mockTokenBalance,
 } from '../../_internal/api/__mocks__/indexer.msw';
-import { useAutoSelectFeeOption } from '../useAutoSelectFeeOption';
+import { useAutoSelectFeeOption } from './useAutoSelectFeeOption';
 
 describe('useAutoSelectFeeOption', () => {
 	const mockChainId = 1;
@@ -238,10 +238,14 @@ describe('useAutoSelectFeeOption', () => {
 	});
 
 	it('should return UserNotConnected error when wallet is not connected', async () => {
-		const { result: disconnect } = renderHook(() => useDisconnect());
+		const { result: disconnect } = renderHook(() => useDisconnect(), {
+			autoConnect: false,
+		});
 		await disconnect.current.disconnectAsync();
 
-		const { result } = renderHook(() => useAutoSelectFeeOption(defaultArgs));
+		const { result } = renderHook(() => useAutoSelectFeeOption(defaultArgs), {
+			autoConnect: false,
+		});
 
 		// Wait for the hook to complete
 		await waitFor(async () => {

package/src/react/hooks/{useAutoSelectFeeOption.tsx → utils/useAutoSelectFeeOption.tsx}

@@ -4,8 +4,8 @@ import { useChain } from '@0xsequence/connect';
 import { useCallback, useEffect } from 'react';
 import { type Address, zeroAddress } from 'viem';
 import { useAccount } from 'wagmi';
-import type { FeeOption } from '../../types/waas-types';
-import { useCollectionBalanceDetails } from './useCollectionBalanceDetails';
+import type { FeeOption } from '../../../types/waas-types';
+import { useCollectionBalanceDetails } from '../data/collections/useCollectionBalanceDetails';
 
 enum AutoSelectFeeOptionError {
 	UserNotConnected = 'User not connected',

package/src/react/hooks/utils/useCheckoutOptions.test.tsx

@@ -0,0 +1,162 @@
+import { renderHook, server, waitFor } from '@test';
+import { HttpResponse, http } from 'msw';
+import { zeroAddress } from 'viem';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { useAccount } from 'wagmi';
+import { MarketplaceKind } from '../../_internal';
+import {
+	mockCheckoutOptions,
+	mockMarketplaceEndpoint,
+} from '../../_internal/api/__mocks__/marketplace.msw';
+import type { UseCheckoutOptionsParams } from './useCheckoutOptions';
+import { useCheckoutOptions } from './useCheckoutOptions';
+
+// Mock wagmi useAccount hook
+vi.mock('wagmi', async () => {
+	const actual = await vi.importActual('wagmi');
+	return {
+		...actual,
+		useAccount: vi.fn(),
+	};
+});
+
+const mockUseAccount = vi.mocked(useAccount);
+
+describe('useCheckoutOptions', () => {
+	const defaultArgs: UseCheckoutOptionsParams = {
+		chainId: 1,
+		orders: [
+			{
+				collectionAddress: zeroAddress,
+				orderId: '123',
+				marketplace: MarketplaceKind.sequence_marketplace_v2,
+			},
+		],
+		additionalFee: 0,
+		query: {},
+	};
+
+	beforeEach(() => {
+		mockUseAccount.mockReturnValue({
+			address: zeroAddress,
+		} as unknown as ReturnType<typeof useAccount>);
+	});
+
+	it('should fetch checkout options successfully', async () => {
+		const { result } = renderHook(() => useCheckoutOptions(defaultArgs));
+
+		// Initially loading
+		expect(result.current.isLoading).toBe(true);
+		expect(result.current.data).toBeUndefined();
+
+		// Wait for data to be loaded
+		await waitFor(() => {
+			expect(result.current.isLoading).toBe(false);
+		});
+
+		// Verify the data matches our mock
+		expect(result.current.data).toEqual(mockCheckoutOptions);
+		expect(result.current.error).toBeNull();
+	});
+
+	it('should handle error states', async () => {
+		// Override the handler for this test to return an error
+		server.use(
+			http.post(mockMarketplaceEndpoint('CheckoutOptionsMarketplace'), () => {
+				return HttpResponse.json(
+					{ error: { message: 'Failed to fetch checkout options' } },
+					{ status: 500 },
+				);
+			}),
+		);
+
+		const { result } = renderHook(() => useCheckoutOptions(defaultArgs));
+
+		await waitFor(() => {
+			expect(result.current.isError).toBe(true);
+		});
+
+		expect(result.current.error).toBeDefined();
+		expect(result.current.data).toBeUndefined();
+	});
+
+	it('should refetch when args change', async () => {
+		const { result, rerender } = renderHook(() =>
+			useCheckoutOptions(defaultArgs),
+		);
+
+		// Wait for initial data
+		await waitFor(() => {
+			expect(result.current.isLoading).toBe(false);
+		});
+
+		// Change args and rerender
+		const firstOrder = defaultArgs.orders?.[0];
+		if (!firstOrder) throw new Error('Expected defaultArgs.orders to exist');
+
+		const newArgs = {
+			...defaultArgs,
+			orders: [
+				{
+					...firstOrder,
+					orderId: '456',
+				},
+			],
+		};
+
+		rerender(() => useCheckoutOptions(newArgs));
+
+		// Wait for new data
+		await waitFor(() => {
+			expect(result.current.data).toBeDefined();
+		});
+
+		// Verify that the query was refetched with new args
+		expect(result.current.data).toBeDefined();
+		expect(result.current.isSuccess).toBe(true);
+	});
+
+	it('should handle disabled query when wallet not connected', async () => {
+		// Mock wallet not connected
+		mockUseAccount.mockReturnValue({
+			address: undefined,
+		} as unknown as ReturnType<typeof useAccount>);
+
+		const { result } = renderHook(() => useCheckoutOptions(defaultArgs));
+
+		// Should not make request when wallet not connected
+		expect(result.current.isLoading).toBe(false);
+		expect(result.current.data).toBeUndefined();
+		expect(result.current.error).toBeNull();
+	});
+
+	it('should handle multiple orders', async () => {
+		const multiOrderArgs: UseCheckoutOptionsParams = {
+			chainId: 137,
+			orders: [
+				{
+					collectionAddress: zeroAddress,
+					orderId: '123',
+					marketplace: MarketplaceKind.sequence_marketplace_v2,
+				},
+				{
+					collectionAddress:
+						'0x1234567890123456789012345678901234567890' as `0x${string}`,
+					orderId: '456',
+					marketplace: MarketplaceKind.opensea,
+				},
+			],
+			additionalFee: 100,
+			query: {},
+		};
+
+		const { result } = renderHook(() => useCheckoutOptions(multiOrderArgs));
+
+		await waitFor(() => {
+			expect(result.current.isLoading).toBe(false);
+		});
+
+		expect(result.current.data).toBeDefined();
+		expect(result.current.error).toBeNull();
+	});
+});

package/src/react/hooks/utils/useCheckoutOptions.tsx

@@ -0,0 +1,98 @@
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import type { Address } from 'viem';
+import { useAccount } from 'wagmi';
+import type { MarketplaceKind, Optional } from '../../_internal';
+import {
+	type CheckoutOptionsQueryOptions,
+	checkoutOptionsQueryOptions,
+	type FetchCheckoutOptionsParams,
+} from '../../queries/checkoutOptions';
+import { useConfig } from '../config/useConfig';
+
+export type UseCheckoutOptionsParams = Optional<
+	CheckoutOptionsQueryOptions,
+	'config' | 'walletAddress'
+>;
+
+/**
+ * Hook to fetch checkout options for marketplace orders
+ *
+ * Retrieves checkout options including available payment methods, fees, and transaction details
+ * for a set of marketplace orders. Requires a connected wallet to calculate wallet-specific options.
+ *
+ * @param params - Configuration parameters
+ * @param params.chainId - The chain ID (must be number, e.g., 1 for Ethereum, 137 for Polygon)
+ * @param params.orders - Array of orders to checkout containing collection address, order ID, and marketplace
+ * @param params.additionalFee - Additional fee to include in checkout (defaults to 0)
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing checkout options with payment methods and fees
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data: checkoutOptions, isLoading } = useCheckoutOptions({
+ *   chainId: 137,
+ *   orders: [{
+ *     collectionAddress: '0x1234...',
+ *     orderId: '123',
+ *     marketplace: MarketplaceKind.sequence_marketplace_v2
+ *   }],
+ *   additionalFee: 0
+ * })
+ * ```
+ *
+ * @example
+ * With custom query options:
+ * ```typescript
+ * const { data: checkoutOptions } = useCheckoutOptions({
+ *   chainId: 1,
+ *   orders: orders,
+ *   query: {
+ *     enabled: orders.length > 0,
+ *     staleTime: 30000
+ *   }
+ * })
+ * ```
+ */
+export function useCheckoutOptions(params: UseCheckoutOptionsParams) {
+	const { address } = useAccount();
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = checkoutOptionsQueryOptions({
+		config,
+		walletAddress: address as Address,
+		...rest,
+	});
+
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { checkoutOptionsQueryOptions };
+
+export type { FetchCheckoutOptionsParams, CheckoutOptionsQueryOptions };
+
+// Legacy export for backward compatibility
+export type UseCheckoutOptionsArgs = {
+	chainId: number;
+	orders: Array<{
+		collectionAddress: string;
+		orderId: string;
+		marketplace: MarketplaceKind;
+	}>;
+	query?: {
+		enabled?: boolean;
+	};
+};
+
+export type UseCheckoutOptionsReturn = Awaited<
+	ReturnType<
+		typeof import('../../queries/checkoutOptions').fetchCheckoutOptions
+	>
+>;

package/src/react/hooks/{__tests__ → utils}/useCheckoutOptionsSalesContract.test.tsx

@@ -1,18 +1,27 @@
 import { skipToken } from '@tanstack/react-query';
-import { renderHook, waitFor } from '@test';
+import { renderHook, server, waitFor } from '@test';
+import { HttpResponse, http } from 'msw';
 import type { Address } from 'viem';
+import { zeroAddress } from 'viem';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { useCheckoutOptionsSalesContract } from '../useCheckoutOptionsSalesContract';
-
-// Mock wagmi's useAccount hook
+import { useAccount } from 'wagmi';
+import {
+	mockCheckoutOptions,
+	mockMarketplaceEndpoint,
+} from '../../_internal/api/__mocks__/marketplace.msw';
+import { useCheckoutOptionsSalesContract } from './useCheckoutOptionsSalesContract';
+
+// Mock wagmi useAccount hook
 vi.mock('wagmi', async () => {
 	const actual = await vi.importActual('wagmi');
 	return {
 		...actual,
-		useAccount: vi.fn(() => ({ address: '0xTestWallet' as Address })),
+		useAccount: vi.fn(),
 	};
 });
 
+const mockUseAccount = vi.mocked(useAccount);
+
 const mockContractAddress =
 	'0x1234567890123456789012345678901234567890' as Address;
 const mockCollectionAddress =
@@ -21,6 +30,9 @@ const mockCollectionAddress =
 describe('useCheckoutOptionsSalesContract', () => {
 	beforeEach(() => {
 		vi.clearAllMocks();
+		mockUseAccount.mockReturnValue({
+			address: zeroAddress,
+		} as unknown as ReturnType<typeof useAccount>);
 	});
 
 	afterEach(() => {
@@ -51,15 +63,8 @@ describe('useCheckoutOptionsSalesContract', () => {
 			expect(result.current.isSuccess).toBe(true);
 		});
 
-		// Check the response
-		expect(result.current.data).toEqual({
-			options: {
-				crypto: 'all',
-				swap: [],
-				nftCheckout: [],
-				onRamp: [],
-			},
-		});
+		// Check the response matches our mock
+		expect(result.current.data).toEqual(mockCheckoutOptions);
 	});
 
 	it('should handle skipToken', () => {
@@ -96,8 +101,7 @@ describe('useCheckoutOptionsSalesContract', () => {
 			expect(result.current.isSuccess).toBe(true);
 		});
 
-		expect(result.current.data).toBeDefined();
-		expect(result.current.data?.options).toBeDefined();
+		expect(result.current.data).toEqual(mockCheckoutOptions);
 	});
 
 	it('should refetch when args change', async () => {
@@ -135,23 +139,16 @@ describe('useCheckoutOptionsSalesContract', () => {
 		expect(result.current.data).toEqual(firstData);
 	});
 
-	it('should use wallet address from useAccount', async () => {
-		const { useAccount } = await import('wagmi');
-		const mockUseAccount = vi.mocked(useAccount);
-
-		// Set a specific address
-		mockUseAccount.mockReturnValue({
-			address: '0xSpecificWallet' as Address,
-			isConnected: true,
-			isConnecting: false,
-			isDisconnected: false,
-			isReconnecting: false,
-			connector: null,
-			addresses: undefined,
-			chain: undefined,
-			chainId: undefined,
-			status: 'connected',
-		} as unknown as ReturnType<typeof useAccount>);
+	it('should handle error states', async () => {
+		// Override the handler for this test to return an error
+		server.use(
+			http.post(mockMarketplaceEndpoint('CheckoutOptionsSalesContract'), () => {
+				return HttpResponse.json(
+					{ error: { message: 'Failed to fetch checkout options' } },
+					{ status: 500 },
+				);
+			}),
+		);
 
 		const { result } = renderHook(() =>
 			useCheckoutOptionsSalesContract({
@@ -163,28 +160,17 @@ describe('useCheckoutOptionsSalesContract', () => {
 		);
 
 		await waitFor(() => {
-			expect(result.current.isSuccess).toBe(true);
+			expect(result.current.isError).toBe(true);
 		});
 
-		expect(result.current.data).toBeDefined();
+		expect(result.current.error).toBeDefined();
+		expect(result.current.data).toBeUndefined();
 	});
 
 	it('should handle when wallet is not connected', async () => {
-		const { useAccount } = await import('wagmi');
-		const mockUseAccount = vi.mocked(useAccount);
-
-		// No wallet connected
+		// Mock wallet not connected for this test
 		mockUseAccount.mockReturnValue({
 			address: undefined,
-			isConnected: false,
-			isConnecting: false,
-			isDisconnected: true,
-			isReconnecting: false,
-			connector: null,
-			addresses: undefined,
-			chain: undefined,
-			chainId: undefined,
-			status: 'disconnected',
 		} as unknown as ReturnType<typeof useAccount>);
 
 		const { result } = renderHook(() =>
@@ -196,14 +182,10 @@ describe('useCheckoutOptionsSalesContract', () => {
 			}),
 		);
 
-		// The hook will still try to fetch even without a wallet (using undefined)
-		// Wait for it to complete
-		await waitFor(() => {
-			expect(result.current.isSuccess).toBe(true);
-		});
-
-		// The API should still return data even without wallet
-		expect(result.current.data).toBeDefined();
+		// Should not make request when wallet not connected
+		expect(result.current.isLoading).toBe(false);
+		expect(result.current.data).toBeUndefined();
+		expect(result.current.error).toBeNull();
 	});
 
 	it('should handle empty items array', async () => {
@@ -216,10 +198,9 @@ describe('useCheckoutOptionsSalesContract', () => {
 			}),
 		);
 
-		await waitFor(() => {
-			expect(result.current.isSuccess).toBe(true);
-		});
-
-		expect(result.current.data).toBeDefined();
+		// Should not make request when items array is empty
+		expect(result.current.isLoading).toBe(false);
+		expect(result.current.data).toBeUndefined();
+		expect(result.current.error).toBeNull();
 	});
 });