@0xsequence/marketplace-sdk 0.10.0 → 1.0.0

package/src/react/hooks/data/tokens/useSearchTokenMetadata.test.tsx

@@ -0,0 +1,284 @@
+import { PropertyType } from '@0xsequence/metadata';
+import { renderHook, server, waitFor } from '@test';
+import { HttpResponse, http } from 'msw';
+import { zeroAddress } from 'viem';
+import { describe, expect, it } from 'vitest';
+import {
+	mockIndexerEndpoint,
+	mockTokenSupply,
+} from '../../../_internal/api/__mocks__/indexer.msw';
+import {
+	mockMetadataEndpoint,
+	mockTokenMetadata,
+} from '../../../_internal/api/__mocks__/metadata.msw';
+import type { UseSearchTokenMetadataParams } from './useSearchTokenMetadata';
+import { useSearchTokenMetadata } from './useSearchTokenMetadata';
+
+describe('useSearchTokenMetadata', () => {
+	const defaultArgs: UseSearchTokenMetadataParams = {
+		chainId: 1,
+		collectionAddress: zeroAddress,
+		filter: {
+			text: 'test',
+		},
+	};
+
+	const defaultArgsWithProperties: UseSearchTokenMetadataParams = {
+		chainId: 1,
+		collectionAddress: zeroAddress,
+		filter: {
+			properties: [
+				{
+					name: 'Rarity',
+					type: PropertyType.STRING,
+					values: ['Legendary'],
+				},
+				{
+					name: 'Level',
+					type: PropertyType.INT,
+					min: 50,
+					max: 100,
+				},
+			],
+		},
+	};
+
+	it('should fetch metadata with text search successfully', async () => {
+		const { result } = renderHook(() => useSearchTokenMetadata(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).toBeDefined();
+		expect(result.current.data?.tokenMetadata).toEqual([mockTokenMetadata]);
+		expect(result.current.error).toBeNull();
+	});
+
+	it('should fetch metadata with property filters successfully', async () => {
+		const { result } = renderHook(() =>
+			useSearchTokenMetadata(defaultArgsWithProperties),
+		);
+
+		// 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).toBeDefined();
+		expect(result.current.data?.tokenMetadata).toEqual([mockTokenMetadata]);
+		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(mockMetadataEndpoint('SearchTokenMetadata'), () => {
+				return HttpResponse.json(
+					{ error: { message: 'Failed to search token metadata' } },
+					{ status: 500 },
+				);
+			}),
+		);
+
+		const { result } = renderHook(() => useSearchTokenMetadata(defaultArgs));
+
+		await waitFor(() => {
+			expect(result.current.isError).toBe(true);
+		});
+
+		expect(result.current.error).toBeDefined();
+		expect(result.current.data).toBeUndefined();
+	});
+
+	it('should respect enabled option in query config', () => {
+		const { result } = renderHook(() =>
+			useSearchTokenMetadata({
+				...defaultArgs,
+				query: {
+					enabled: false,
+				},
+			}),
+		);
+
+		expect(result.current.isLoading).toBe(false);
+		expect(result.current.data).toBeUndefined();
+	});
+
+	describe('onlyMinted filter', () => {
+		it('should return all tokens when onlyMinted is false', async () => {
+			const { result } = renderHook(() =>
+				useSearchTokenMetadata({
+					...defaultArgs,
+					onlyMinted: false,
+				}),
+			);
+
+			await waitFor(() => {
+				expect(result.current.isLoading).toBe(false);
+			});
+
+			expect(result.current.data).toBeDefined();
+			expect(result.current.data?.tokenMetadata).toEqual([mockTokenMetadata]);
+		});
+
+		it('should filter out unminted tokens when onlyMinted is true', async () => {
+			const unmintedTokenSupply = {
+				...mockTokenSupply,
+				supply: '0',
+			};
+
+			server.use(
+				http.post(mockIndexerEndpoint('GetTokenSupplies'), () => {
+					return HttpResponse.json({
+						page: { page: 1, pageSize: 10, more: false },
+						contractType: 'ERC721',
+						tokenIDs: [unmintedTokenSupply],
+					});
+				}),
+			);
+
+			const { result } = renderHook(() =>
+				useSearchTokenMetadata({
+					...defaultArgs,
+					onlyMinted: true,
+				}),
+			);
+
+			await waitFor(() => {
+				expect(result.current.isLoading).toBe(false);
+			});
+
+			expect(result.current.data).toBeDefined();
+			expect(result.current.data?.tokenMetadata).toEqual([]);
+		});
+
+		it('should return only minted tokens when onlyMinted is true', async () => {
+			const mintedTokenSupply = {
+				...mockTokenSupply,
+				supply: '1',
+				tokenID: mockTokenMetadata.tokenId,
+			};
+
+			server.use(
+				http.post(mockIndexerEndpoint('GetTokenSupplies'), () => {
+					return HttpResponse.json({
+						page: { page: 1, pageSize: 10, more: false },
+						contractType: 'ERC721',
+						tokenIDs: [mintedTokenSupply],
+					});
+				}),
+			);
+
+			const { result } = renderHook(() =>
+				useSearchTokenMetadata({
+					...defaultArgs,
+					onlyMinted: true,
+				}),
+			);
+
+			await waitFor(() => {
+				expect(result.current.isLoading).toBe(false);
+			});
+
+			expect(result.current.data).toBeDefined();
+			expect(result.current.data?.tokenMetadata).toEqual([mockTokenMetadata]);
+		});
+
+		it('should handle errors from token supplies endpoint when onlyMinted is true', async () => {
+			server.use(
+				http.post(mockIndexerEndpoint('GetTokenSupplies'), () => {
+					return HttpResponse.json(
+						{ error: { message: 'Failed to fetch token supplies' } },
+						{ status: 500 },
+					);
+				}),
+			);
+
+			const { result } = renderHook(() =>
+				useSearchTokenMetadata({
+					...defaultArgs,
+					onlyMinted: true,
+				}),
+			);
+
+			await waitFor(() => {
+				expect(result.current.isError).toBe(true);
+			});
+
+			expect(result.current.error).toBeDefined();
+			expect(result.current.data).toBeUndefined();
+		});
+
+		it('should handle pagination correctly with onlyMinted filter', async () => {
+			const mintedTokenSupply1 = {
+				...mockTokenSupply,
+				supply: '1',
+				tokenID: '1',
+			};
+			const mintedTokenSupply2 = {
+				...mockTokenSupply,
+				supply: '1',
+				tokenID: '2',
+			};
+
+			let page = 1;
+
+			server.use(
+				http.post(mockIndexerEndpoint('GetTokenSupplies'), () => {
+					const response = {
+						page: { page, pageSize: 1, more: page === 1 },
+						contractType: 'ERC721',
+						tokenIDs: [page === 1 ? mintedTokenSupply1 : mintedTokenSupply2],
+					};
+					page++;
+					return HttpResponse.json(response);
+				}),
+
+				http.post(mockMetadataEndpoint('SearchTokenMetadata'), () => {
+					return HttpResponse.json({
+						tokenMetadata: [
+							{ ...mockTokenMetadata, tokenId: '1' },
+							{ ...mockTokenMetadata, tokenId: '2' },
+						],
+						page: { page: 1, pageSize: 10, more: false },
+					});
+				}),
+			);
+
+			const { result } = renderHook(() =>
+				useSearchTokenMetadata({
+					...defaultArgs,
+					onlyMinted: true,
+				}),
+			);
+
+			await waitFor(() => {
+				expect(result.current.isLoading).toBe(false);
+			});
+
+			expect(result.current.hasNextPage).toBe(true);
+			expect(result.current.data?.tokenMetadata).toHaveLength(1);
+
+			await result.current.fetchNextPage();
+
+			await waitFor(() => {
+				expect(result.current.isFetching).toBe(false);
+			});
+
+			expect(result.current.data?.tokenMetadata).toHaveLength(2);
+			expect(result.current.hasNextPage).toBe(false);
+		});
+	});
+});

package/src/react/hooks/data/tokens/useSearchTokenMetadata.tsx

@@ -0,0 +1,186 @@
+'use client';
+
+import { useInfiniteQuery } from '@tanstack/react-query';
+import type { Optional } from '../../../_internal';
+import {
+	type SearchTokenMetadataQueryOptions,
+	searchTokenMetadataQueryOptions,
+} from '../../../queries/searchTokenMetadata';
+import { useConfig } from '../../config/useConfig';
+import { useTokenSupplies } from './useTokenSupplies';
+
+export type UseSearchTokenMetadataParams = Optional<
+	SearchTokenMetadataQueryOptions,
+	'config'
+> & {
+	/**
+	 * If true, only return minted tokens (tokens with supply > 0)
+	 */
+	onlyMinted?: boolean;
+};
+
+/**
+ * Hook to search token metadata using filters with infinite pagination support
+ *
+ * Searches for tokens in a collection based on text and property filters.
+ * Supports filtering by attributes, ranges, and text search.
+ * Can optionally filter to only show minted tokens (tokens with supply > 0).
+ *
+ * @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
+ * @param params.filter - Filter criteria for the search
+ * @param params.filter.text - Optional text search query
+ * @param params.filter.properties - Optional array of property filters
+ * @param params.page - Optional pagination parameters
+ * @param params.query - Optional React Query configuration
+ * @param params.onlyMinted - If true, only return minted tokens (tokens with supply > 0)
+ *
+ * @returns Infinite query result containing matching token metadata with pagination support
+ *
+ * @example
+ * Basic text search with pagination:
+ * ```typescript
+ * const { data, isLoading, fetchNextPage, hasNextPage } = useSearchTokenMetadata({
+ *   chainId: 137,
+ *   collectionAddress: '0x...',
+ *   filter: {
+ *     text: 'dragon'
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * Property filters:
+ * ```typescript
+ * const { data, fetchNextPage } = useSearchTokenMetadata({
+ *   chainId: 1,
+ *   collectionAddress: '0x...',
+ *   filter: {
+ *     properties: [
+ *       {
+ *         name: 'Rarity',
+ *         type: PropertyType.STRING,
+ *         values: ['Legendary', 'Epic']
+ *       },
+ *       {
+ *         name: 'Level',
+ *         type: PropertyType.INT,
+ *         min: 50,
+ *         max: 100
+ *       }
+ *     ]
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * Search only minted tokens:
+ * ```typescript
+ * const { data, fetchNextPage } = useSearchTokenMetadata({
+ *   chainId: 1,
+ *   collectionAddress: '0x...',
+ *   onlyMinted: true,
+ *   filter: {
+ *     text: 'dragon'
+ *   }
+ * })
+ * ```
+ */
+export function useSearchTokenMetadata(params: UseSearchTokenMetadataParams) {
+	const defaultConfig = useConfig();
+	const { config = defaultConfig, onlyMinted, ...rest } = params;
+
+	// Get token supplies to check which tokens are minted if onlyMinted is true
+	const {
+		data: suppliesData,
+		hasNextPage: hasNextSuppliesPage,
+		isFetching: isSuppliesFetching,
+		isLoading: isSuppliesLoading,
+		error: suppliesError,
+		fetchNextPage: fetchNextSuppliesPage,
+	} = useTokenSupplies({
+		chainId: params.chainId,
+		collectionAddress: params.collectionAddress,
+		includeMetadata: true,
+		query: {
+			enabled: onlyMinted && (params.query?.enabled ?? true),
+		},
+	});
+
+	const queryOptions = searchTokenMetadataQueryOptions({
+		config,
+		...rest,
+	});
+
+	const result = useInfiniteQuery({
+		...queryOptions,
+		// If onlyMinted is true, only enable the metadata query when token supplies query succeeds
+		enabled: onlyMinted
+			? !isSuppliesLoading && !suppliesError && queryOptions.enabled
+			: queryOptions.enabled,
+	});
+
+	// If onlyMinted is true and we have a supplies error, return that error state
+	if (onlyMinted && suppliesError) {
+		return {
+			...result,
+			isError: true,
+			error: suppliesError,
+			data: undefined,
+		};
+	}
+
+	if (!onlyMinted) {
+		return {
+			...result,
+			data: result.data
+				? {
+						tokenMetadata: result.data.pages.flatMap(
+							(page) => page.tokenMetadata,
+						),
+						page: result.data.pages[result.data.pages.length - 1]?.page,
+					}
+				: undefined,
+		};
+	}
+
+	const mintedTokenIds = new Set(
+		suppliesData?.pages
+			.flatMap((page) => page.tokenIDs)
+			?.filter((token) => BigInt(token.supply) > 0n)
+			.map((token) => token.tokenID) ?? [],
+	);
+
+	// Filter minted tokens from all metadata pages
+	const filteredTokenMetadata = result.data?.pages
+		.flatMap((page) => page.tokenMetadata)
+		.filter((metadata) => mintedTokenIds.has(metadata.tokenId));
+
+	const lastPage = result.data?.pages[result.data.pages.length - 1]?.page;
+
+	const shouldFetchNextMetadataPage =
+		result.hasNextPage &&
+		(filteredTokenMetadata?.length ?? 0) < (mintedTokenIds?.size ?? 0);
+
+	const fetchNextPage = async () => {
+		if (hasNextSuppliesPage && !isSuppliesFetching) {
+			await fetchNextSuppliesPage();
+		}
+	};
+
+	return {
+		...result,
+		hasNextPage: shouldFetchNextMetadataPage || hasNextSuppliesPage,
+		data: result.data
+			? {
+					tokenMetadata: filteredTokenMetadata ?? [],
+					page: lastPage,
+				}
+			: undefined,
+		isLoading: result.isLoading || isSuppliesLoading,
+		isFetching: result.isFetching || isSuppliesFetching,
+		error: result.error || suppliesError,
+		fetchNextPage,
+	};
+}

package/src/react/hooks/{useTokenSupplies.ts → data/tokens/useTokenSupplies.ts}

@@ -1,13 +1,13 @@
 'use client';
 
-import { useQuery } from '@tanstack/react-query';
-import type { Optional } from '../_internal';
+import { useInfiniteQuery } from '@tanstack/react-query';
+import type { Optional } from '../../../_internal';
 import {
 	type FetchTokenSuppliesParams,
 	type TokenSuppliesQueryOptions,
 	tokenSuppliesQueryOptions,
-} from '../queries/tokenSupplies';
-import { useConfig } from './useConfig';
+} from '../../../queries/tokenSupplies';
+import { useConfig } from '../../config/useConfig';
 
 export type UseTokenSuppliesParams = Optional<
 	TokenSuppliesQueryOptions,
@@ -71,7 +71,7 @@ export function useTokenSupplies(params: UseTokenSuppliesParams) {
 		...rest,
 	});
 
-	return useQuery({
+	return useInfiniteQuery({
 		...queryOptions,
 	});
 }

package/src/react/hooks/index.ts

@@ -1,52 +1,18 @@
-export * from './useAutoSelectFeeOption';
-export * from './useBalanceOfCollectible';
-export * from './useCancelOrder';
-export * from './useCheckoutOptionsSalesContract';
-export * from './useCheckoutOptionsSalesContract';
-export * from './useCollectible';
-export * from './useCollection';
-export * from './useCollectionBalanceDetails';
-export * from './useCollectionDetails';
-export * from './useCollectionDetailsPolling';
-export * from './useComparePrices';
-export * from './useConfig';
-export * from './useConvertPriceToUSD';
-export * from './useCountListingsForCollectible';
-export * from './useCountOfCollectables';
-export * from './useCountOffersForCollectible';
-export * from './useCountOfPrimarySaleItems';
-export * from './useCurrency';
-export * from './useERC721SaleMintedTokens';
-export * from './useFilterState';
-export * from './useFilters';
-export * from './useFloorOrder';
-export * from './useGenerateCancelTransaction';
-export * from './useGenerateListingTransaction';
-export * from './useGenerateOfferTransaction';
-export * from './useGenerateSellTransaction';
-export * from './useGetCountOfPrimarySaleItems';
-export * from './useGetTokenRanges';
-export * from './useHighestOffer';
-export * from './useInventory';
-export * from './useList721ShopCardData';
-export * from './useList1155ShopCardData';
-export * from './useListBalances';
-export * from './useListCollectibleActivities';
-export * from './useListCollectibles';
-export * from './useListCollectiblesPaginated';
-export * from './useListCollectionActivities';
-export * from './useListCollections';
-export * from './useListListingsForCollectible';
-export * from './useListMarketCardData';
-export * from './useListOffersForCollectible';
-export * from './useListPrimarySaleItems';
-export * from './useListShopCardData';
-export * from './useListTokenMetadata';
-export * from './useLowestListing';
-export * from './useMarketCurrencies';
-export * from './useMarketplaceConfig';
-export * from './useOpenConnectModal';
-export * from './useRoyalty';
-export * from './useShopCollectibleSaleData';
-export * from './useTokenSupplies';
-export * from './useTransferTokens';
+// Re-export all hooks from their new organized locations
+// This maintains backwards compatibility while providing better organization
+
+// Configuration & context hooks
+export * from './config';
+// Contract hooks
+export * from './contracts';
+// Data fetching hooks
+export * from './data';
+// Inventory hooks
+export * from './data/inventory';
+// Transaction hooks
+export * from './transactions';
+
+// UI state hooks
+export * from './ui';
+// Utility hooks
+export * from './utils';

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

@@ -0,0 +1,9 @@
+export * from './useCancelOrder';
+export * from './useCancelTransactionSteps';
+export * from './useGenerateCancelTransaction';
+export * from './useGenerateListingTransaction';
+export * from './useGenerateOfferTransaction';
+export * from './useGenerateSellTransaction';
+export * from './useOrderSteps';
+export * from './useProcessStep';
+export * from './useTransferTokens';