@0xsequence/marketplace-sdk 0.9.0 → 1.0.0

package/src/react/hooks/data/primary-sales/useList721ShopCardData.tsx

@@ -0,0 +1,183 @@
+import type { TokenMetadata } from '@0xsequence/metadata';
+import { useInfiniteQuery } from '@tanstack/react-query';
+import { useEffect, useState } from 'react';
+import type { Address } from 'viem';
+import { useReadContract } from 'wagmi';
+import { useFilterState } from '../../..';
+import { ContractType } from '../../../_internal';
+import type { CollectiblePrimarySaleItem } from '../../../_internal/api/marketplace.gen';
+import type { ShopCollectibleCardProps } from '../../../ui';
+import { useConfig } from '../../config';
+import { useSalesContractABI } from '../../contracts/useSalesContractABI';
+import { tokenSuppliesQueryOptions } from '../tokens';
+
+interface UseList721ShopCardDataProps {
+	primarySaleItemsWithMetadata: CollectiblePrimarySaleItem[];
+	chainId: number;
+	contractAddress: Address;
+	salesContractAddress: Address;
+	enabled?: boolean;
+}
+
+export function useList721ShopCardData({
+	primarySaleItemsWithMetadata,
+	chainId,
+	contractAddress,
+	salesContractAddress,
+	enabled = true,
+}: UseList721ShopCardDataProps) {
+	const [allTokenSuppliesFetched, setAllTokenSuppliesFetched] = useState(false);
+	const { showListedOnly: showAvailableSales } = useFilterState();
+
+	const { abi, isLoading: versionLoading } = useSalesContractABI({
+		contractAddress: salesContractAddress,
+		contractType: ContractType.ERC721,
+		chainId,
+		enabled,
+	});
+	const config = useConfig();
+
+	const tokenSuppliesQuery = useInfiniteQuery({
+		...tokenSuppliesQueryOptions({
+			chainId,
+			collectionAddress: contractAddress,
+			includeMetadata: true,
+			config,
+		}),
+	});
+
+	const {
+		data: tokenSuppliesData,
+		fetchNextPage: fetchNextTokenSuppliesPage,
+		hasNextPage: hasNextSuppliesPage,
+		isFetchingNextPage: isFetchingNextSuppliesPage,
+		isLoading: tokenSuppliesLoading,
+	} = tokenSuppliesQuery;
+
+	useEffect(() => {
+		async function fetchAllPages() {
+			if (!hasNextSuppliesPage && tokenSuppliesData) {
+				setAllTokenSuppliesFetched(true);
+				return;
+			}
+
+			if (isFetchingNextSuppliesPage || tokenSuppliesLoading) return;
+
+			await fetchNextTokenSuppliesPage();
+		}
+
+		fetchAllPages();
+	}, [
+		hasNextSuppliesPage,
+		isFetchingNextSuppliesPage,
+		tokenSuppliesLoading,
+		fetchNextTokenSuppliesPage,
+	]);
+
+	const allTokenSupplies = tokenSuppliesData?.pages.flatMap(
+		(page) => page.tokenIDs,
+	);
+	const matchingTokenSupplies = allTokenSupplies?.filter((item) =>
+		primarySaleItemsWithMetadata.some(
+			(primarySaleItem) => primarySaleItem.metadata.tokenId === item.tokenID,
+		),
+	);
+
+	// For ERC721, we'll fetch the sale details directly from the contract
+	const {
+		data: saleDetails,
+		isLoading: saleDetailsLoading,
+		error: saleDetailsError,
+	} = useReadContract({
+		chainId,
+		address: salesContractAddress,
+		abi: abi || [],
+		functionName: 'saleDetails',
+		query: {
+			enabled: enabled && !versionLoading && !!abi,
+		},
+	});
+
+	// Filter out primary sale items that have already been minted
+	const unmintedPrimarySaleItems = primarySaleItemsWithMetadata.filter(
+		(item) =>
+			!matchingTokenSupplies?.some(
+				(supply) => supply.tokenID === item.metadata.tokenId,
+			),
+	);
+
+	const primarySaleItemsCollectibleCards = unmintedPrimarySaleItems.map(
+		(item) => {
+			const { metadata, primarySaleItem } = item;
+
+			const salePrice = {
+				amount: primarySaleItem.priceAmount?.toString(),
+				currencyAddress: primarySaleItem.currencyAddress as Address,
+			};
+
+			const quantityInitial = primarySaleItem.supply?.toString();
+
+			const quantityRemaining = '1';
+
+			const saleStartsAt = primarySaleItem.startDate.toString();
+
+			const saleEndsAt = primarySaleItem.endDate.toString();
+
+			return {
+				collectibleId: metadata.tokenId,
+				chainId,
+				collectionAddress: contractAddress,
+				collectionType: ContractType.ERC721,
+				tokenMetadata: metadata,
+				cardLoading: saleDetailsLoading,
+				salesContractAddress: salesContractAddress,
+				salePrice,
+				quantityInitial,
+				quantityRemaining,
+				quantityDecimals: 0,
+				saleStartsAt,
+				saleEndsAt,
+				marketplaceType: 'shop',
+			} satisfies ShopCollectibleCardProps;
+		},
+	);
+
+	const mintedTokensCollectibleCards = allTokenSupplies?.map((item) => {
+		return {
+			collectibleId: item.tokenID,
+			chainId,
+			collectionAddress: contractAddress,
+			collectionType: ContractType.ERC721,
+			tokenMetadata: item.tokenMetadata as TokenMetadata,
+			cardLoading: saleDetailsLoading,
+			salesContractAddress: salesContractAddress,
+			salePrice: {
+				amount: '0',
+				currencyAddress: '0x0000000000000000000000000000000000000000',
+			},
+			quantityInitial: undefined,
+			quantityRemaining: undefined,
+			quantityDecimals: 0,
+			saleStartsAt: undefined,
+			saleEndsAt: undefined,
+			marketplaceType: 'shop',
+		} satisfies ShopCollectibleCardProps;
+	});
+
+	const collectibleCards = showAvailableSales
+		? primarySaleItemsCollectibleCards
+		: [
+				...(mintedTokensCollectibleCards ?? []),
+				...primarySaleItemsCollectibleCards,
+			];
+
+	return {
+		salePrice: collectibleCards[0]?.salePrice,
+		collectibleCards,
+		saleDetailsError,
+		saleDetails,
+		isLoading:
+			saleDetailsLoading || tokenSuppliesLoading || !allTokenSuppliesFetched,
+		tokenSuppliesData,
+	};
+}

package/src/react/hooks/data/primary-sales/useListPrimarySaleItems.tsx

@@ -0,0 +1,66 @@
+'use client';
+
+import { useInfiniteQuery } from '@tanstack/react-query';
+import type { Optional } from '../../../_internal';
+import {
+	type ListPrimarySaleItemsQueryOptions,
+	listPrimarySaleItemsQueryOptions,
+} from '../../../queries/primarySaleItems';
+import { useConfig } from '../../config/useConfig';
+
+export type UseListPrimarySaleItemsParams = Optional<
+	ListPrimarySaleItemsQueryOptions,
+	'config'
+>;
+
+/**
+ * Hook to fetch primary sale items with pagination support
+ *
+ * Retrieves a paginated list of primary sale items for a specific contract address
+ * from the marketplace.
+ *
+ * @param params - Configuration parameters
+ * @param params.chainId - The chain ID (must be number, e.g., 1 for Ethereum, 137 for Polygon)
+ * @param params.primarySaleContractAddress - The primary sale contract address
+ * @param params.filter - Optional filter parameters for the query
+ * @param params.page - Optional pagination parameters
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Infinite query result containing the primary sale items data
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data, isLoading } = useListPrimarySaleItems({
+ *   chainId: 137,
+ *   primarySaleContractAddress: '0x...',
+ * })
+ * ```
+ *
+ * @example
+ * With filters and pagination:
+ * ```typescript
+ * const { data, isLoading } = useListPrimarySaleItems({
+ *   chainId: 1,
+ *   primarySaleContractAddress: '0x...',
+ *   filter: { status: 'active' },
+ *   page: { page: 1, pageSize: 20 },
+ *   query: {
+ *     enabled: isReady
+ *   }
+ * })
+ * ```
+ */
+export function useListPrimarySaleItems(params: UseListPrimarySaleItemsParams) {
+	const defaultConfig = useConfig();
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = listPrimarySaleItemsQueryOptions({
+		config,
+		...rest,
+	});
+
+	return useInfiniteQuery(queryOptions);
+}
+
+export type { ListPrimarySaleItemsQueryOptions };

package/src/react/hooks/data/tokens/index.ts

@@ -0,0 +1,5 @@
+export * from './useGetTokenRanges';
+export * from './useListBalances';
+export * from './useListTokenMetadata';
+export * from './useSearchTokenMetadata';
+export * from './useTokenSupplies';

package/src/react/hooks/{__tests__ → data/tokens}/useCurrencyBalance.test.tsx

@@ -1,8 +1,8 @@
 import { renderHook, waitFor } from '@test';
 import { zeroAddress } from 'viem';
 import { describe, expect, it } from 'vitest';
-import { USDC_ADDRESS, USDC_HOLDER } from '../../../../test/const';
-import { useCurrencyBalance } from '../useCurrencyBalance';
+import { USDC_ADDRESS, USDC_HOLDER } from '../../../../../test/const';
+import { useCurrencyBalance } from './useCurrencyBalance';
 
 describe('useCurrencyBalance', () => {
 	const defaultArgs = {
@@ -63,11 +63,15 @@ describe('useCurrencyBalance', () => {
 		`);
 	});
 
-	it('should return skipToken when required parameters are missing', () => {
+	it('should handle disabled query when enabled is false', () => {
 		const { result } = renderHook(() =>
-			// @ts-expect-error - missing params
 			useCurrencyBalance({
-				chainId: undefined,
+				chainId: 1,
+				currencyAddress: zeroAddress,
+				userAddress: USDC_HOLDER,
+				query: {
+					enabled: false,
+				},
 			}),
 		);
 

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

@@ -0,0 +1,137 @@
+'use client';
+
+import type { Address } from 'viem';
+import { erc20Abi, formatUnits, zeroAddress } from 'viem';
+import { useBalance, useReadContracts } from 'wagmi';
+
+export type UseCurrencyBalanceArgs = {
+	currencyAddress: Address | undefined;
+	chainId: number | undefined;
+	userAddress: Address | undefined;
+	query?: {
+		enabled?: boolean;
+	};
+};
+
+/**
+ * Hook to fetch cryptocurrency balance for a user
+ *
+ * Retrieves the balance of a specific currency (native token or ERC-20)
+ * for a given user address using wagmi. Handles both native tokens (ETH, MATIC, etc.)
+ * and ERC-20 tokens with automatic decimal formatting through direct blockchain calls.
+ *
+ * @param args - Configuration parameters
+ * @param args.currencyAddress - The currency contract address (use zero address for native tokens)
+ * @param args.chainId - The chain ID to query on
+ * @param args.userAddress - The user address to check balance for
+ * @param args.query - Optional wagmi query configuration
+ *
+ * @returns Wagmi query result containing raw and formatted balance values
+ *
+ * @example
+ * Native token balance (ETH):
+ * ```typescript
+ * const { data: ethBalance, isLoading } = useCurrencyBalance({
+ *   currencyAddress: '0x0000000000000000000000000000000000000000', // Zero address for ETH
+ *   chainId: 1,
+ *   userAddress: '0x1234...'
+ * })
+ *
+ * if (data) {
+ *   console.log(`ETH Balance: ${data.formatted} ETH`); // e.g., "1.5 ETH"
+ *   console.log(`Raw balance: ${data.value.toString()}`); // e.g., "1500000000000000000"
+ * }
+ * ```
+ *
+ * @example
+ * ERC-20 token balance (USDC):
+ * ```typescript
+ * const { data: usdcBalance } = useCurrencyBalance({
+ *   currencyAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
+ *   chainId: 1,
+ *   userAddress: userAddress,
+ *   query: {
+ *     enabled: Boolean(userAddress), // Only fetch when user is connected
+ *     refetchInterval: 30000 // Update every 30 seconds
+ *   }
+ * })
+ *
+ * if (data) {
+ *   console.log(`USDC Balance: $${data.formatted}`); // e.g., "$1000.50"
+ * }
+ * ```
+ */
+export function useCurrencyBalance(args: UseCurrencyBalanceArgs) {
+	const { currencyAddress, chainId, userAddress, query } = args;
+
+	// Check if all required parameters are present
+	const hasAllParams = Boolean(currencyAddress && chainId && userAddress);
+	const isNativeToken = currencyAddress === zeroAddress;
+
+	// For native token (zero address), use useBalance
+	const nativeBalance = useBalance({
+		address: userAddress,
+		chainId,
+		query: {
+			...query,
+			enabled: hasAllParams && isNativeToken && (query?.enabled ?? true),
+		},
+	});
+
+	// For ERC-20 tokens, use useReadContracts to get both balance and decimals
+	const erc20Balance = useReadContracts({
+		contracts:
+			hasAllParams && !isNativeToken && currencyAddress && userAddress
+				? [
+						{
+							address: currencyAddress,
+							abi: erc20Abi,
+							functionName: 'balanceOf',
+							args: [userAddress],
+							chainId,
+						},
+						{
+							address: currencyAddress,
+							abi: erc20Abi,
+							functionName: 'decimals',
+							chainId,
+						},
+					]
+				: [],
+		query: {
+			...query,
+			enabled: hasAllParams && !isNativeToken && (query?.enabled ?? true),
+		},
+	});
+
+	// Return native balance result if zero address
+	if (isNativeToken) {
+		return {
+			...nativeBalance,
+			data: nativeBalance.data
+				? {
+						value: nativeBalance.data.value,
+						formatted: nativeBalance.data.formatted,
+					}
+				: undefined,
+		};
+	}
+
+	// Return ERC-20 balance result with formatted data
+	const [balanceResult, decimalsResult] = erc20Balance.data || [];
+	const balance = balanceResult?.result;
+	const decimals = decimalsResult?.result;
+
+	const formattedData =
+		balance !== undefined && decimals !== undefined
+			? {
+					value: balance,
+					formatted: formatUnits(balance, decimals),
+				}
+			: undefined;
+
+	return {
+		...erc20Balance,
+		data: formattedData,
+	};
+}

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

@@ -0,0 +1,111 @@
+import { renderHook, server, waitFor } from '@test';
+import { HttpResponse, http } from 'msw';
+import { zeroAddress } from 'viem';
+import { describe, expect, it } from 'vitest';
+import { mockIndexerEndpoint } from '../../../_internal/api/__mocks__/indexer.msw';
+import type { UseGetTokenRangesParams } from './useGetTokenRanges';
+import { useGetTokenRanges } from './useGetTokenRanges';
+
+describe('useGetTokenRanges', () => {
+	const defaultArgs: UseGetTokenRangesParams = {
+		chainId: 1,
+		collectionAddress: zeroAddress,
+	};
+
+	it('should fetch token ranges successfully', async () => {
+		const { result } = renderHook(() => useGetTokenRanges(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);
+		});
+
+		expect(result.current.data).toBeDefined();
+		expect(result.current.data?.tokenIDRanges).toBeDefined();
+		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(mockIndexerEndpoint('GetTokenIDRanges'), () => {
+				return HttpResponse.json(
+					{ error: { message: 'Failed to fetch token ranges' } },
+					{ status: 500 },
+				);
+			}),
+		);
+
+		const { result } = renderHook(() => useGetTokenRanges(defaultArgs));
+
+		// Wait for the error state
+		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(() =>
+			useGetTokenRanges(defaultArgs),
+		);
+
+		// Wait for initial data
+		await waitFor(() => {
+			expect(result.current.isLoading).toBe(false);
+		});
+
+		// Change args and rerender
+		const newArgs = {
+			...defaultArgs,
+			collectionAddress:
+				'0x1234567890123456789012345678901234567890' as `0x${string}`,
+		};
+
+		rerender(() => useGetTokenRanges(newArgs));
+
+		// Wait for new data
+		await waitFor(() => {
+			expect(result.current.data).toBeDefined();
+		});
+
+		expect(result.current.isSuccess).toBe(true);
+	});
+
+	it('should handle disabled query when required params are missing', async () => {
+		const { result } = renderHook(() =>
+			useGetTokenRanges({
+				chainId: 0, // Invalid chainId should disable the query
+				collectionAddress: zeroAddress,
+			}),
+		);
+
+		// Query should be disabled when chainId is invalid
+		expect(result.current.isLoading).toBe(false);
+		expect(result.current.data).toBeUndefined();
+		expect(result.current.error).toBeNull();
+	});
+
+	it('should handle enabled/disabled state from query options', async () => {
+		const { result } = renderHook(() =>
+			useGetTokenRanges({
+				...defaultArgs,
+				query: {
+					enabled: false, // Explicitly disable the query
+				},
+			}),
+		);
+
+		// Query should be disabled
+		expect(result.current.isLoading).toBe(false);
+		expect(result.current.data).toBeUndefined();
+		expect(result.current.error).toBeNull();
+		expect(result.current.fetchStatus).toBe('idle');
+	});
+});

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

@@ -0,0 +1,94 @@
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import type { Address } from 'viem';
+import type { Optional } from '../../../_internal';
+import {
+	type FetchGetTokenRangesParams,
+	type GetTokenRangesQueryOptions,
+	getTokenRangesQueryOptions,
+} from '../../../queries/getTokenRanges';
+import { useConfig } from '../../config/useConfig';
+
+export type UseGetTokenRangesParams = Optional<
+	GetTokenRangesQueryOptions,
+	'config'
+>;
+
+/**
+ * Hook to fetch token ID ranges for a collection
+ *
+ * Retrieves the available token ID ranges for a specific collection,
+ * which is useful for understanding the token distribution and
+ * available tokens within a collection.
+ *
+ * @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 ranges for
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing token ID ranges for the collection
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data: tokenRanges, isLoading } = useGetTokenRanges({
+ *   chainId: 137,
+ *   collectionAddress: '0x1234...'
+ * })
+ *
+ * if (data) {
+ *   console.log(`Token ranges: ${JSON.stringify(data.tokenIDRanges)}`);
+ *   data.tokenIDRanges?.forEach(range => {
+ *     console.log(`Range: ${range.start} - ${range.end}`);
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * With conditional enabling:
+ * ```typescript
+ * const { data: tokenRanges } = useGetTokenRanges({
+ *   chainId: 1,
+ *   collectionAddress: selectedCollection?.address,
+ *   query: {
+ *     enabled: Boolean(selectedCollection?.address),
+ *     staleTime: 300000, // Cache for 5 minutes
+ *     refetchInterval: 60000 // Refresh every minute
+ *   }
+ * })
+ * ```
+ */
+export function useGetTokenRanges(params: UseGetTokenRangesParams) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = getTokenRangesQueryOptions({
+		config,
+		...rest,
+	});
+
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { getTokenRangesQueryOptions };
+
+export type { FetchGetTokenRangesParams, GetTokenRangesQueryOptions };
+
+// Legacy exports for backward compatibility
+export type UseGetTokenRangesProps = {
+	chainId: number;
+	collectionAddress: Address;
+	query?: {
+		enabled?: boolean;
+	};
+};
+
+export type UseGetTokenRangesReturn = Awaited<
+	ReturnType<
+		typeof import('../../../queries/getTokenRanges').fetchGetTokenRanges
+	>
+>;

package/src/react/hooks/{__tests__ → data/tokens}/useListBalances.test.tsx

@@ -2,8 +2,8 @@ import { renderHook } from '@test';
 import { waitFor } from '@testing-library/react';
 import { zeroAddress } from 'viem';
 import { describe, expect, it } from 'vitest';
-import { mockTokenBalance } from '../../_internal/api/__mocks__/indexer.msw';
-import { useListBalances } from '../useListBalances';
+import { mockTokenBalance } from '../../../_internal/api/__mocks__/indexer.msw';
+import { useListBalances } from './useListBalances';
 
 describe('useListBalances', () => {
 	it('should fetch token balances successfully', async () => {

package/src/react/hooks/{useListBalances.tsx → data/tokens/useListBalances.tsx}

@@ -1,9 +1,9 @@
 import { useInfiniteQuery } from '@tanstack/react-query';
-import { ContractType } from '../_internal';
-import type { UseListBalancesArgs } from '../queries/listBalances';
-import { listBalancesOptions } from '../queries/listBalances';
-import { useConfig } from './useConfig';
-import { useMarketplaceConfig } from './useMarketplaceConfig';
+import { ContractType } from '../../../_internal';
+import type { UseListBalancesArgs } from '../../../queries/listBalances';
+import { listBalancesOptions } from '../../../queries/listBalances';
+import { useConfig } from '../../config/useConfig';
+import { useMarketplaceConfig } from '../../config/useMarketplaceConfig';
 
 /**
  * Hook to fetch a list of token balances with pagination support