@0xsequence/marketplace-sdk 0.9.0 → 0.10.0

package/src/react/hooks/useConvertPriceToUSD.tsx

@@ -1,82 +1,96 @@
-import { queryOptions, useQuery } from '@tanstack/react-query';
-import { type Address, formatUnits } from 'viem';
-import type { SdkConfig } from '../../types';
-import { type Currency, currencyKeys, getQueryClient } from '../_internal';
-import { marketCurrenciesQueryOptions } from '../queries/marketCurrencies';
-import { useConfig } from './useConfig';
-
-export interface UseConvertPriceToUSDArgs {
-	chainId: number;
-	currencyAddress: Address;
-	amountRaw: string;
-	query?: {
-		enabled?: boolean;
-	};
-}
-
-export type UseConvertPriceToUSDReturn = {
-	usdAmount: number;
-	usdAmountFormatted: string;
-};
+'use client';
 
-export const convertPriceToUSD = async (
-	args: UseConvertPriceToUSDArgs,
-	config: SdkConfig,
-): Promise<UseConvertPriceToUSDReturn> => {
-	const queryClient = getQueryClient();
-	const currencies = (await queryClient.fetchQuery(
-		marketCurrenciesQueryOptions({
-			chainId: args.chainId,
-			config,
-		}),
-	)) as Currency[];
-	const currencyDetails = currencies.find(
-		(c: Currency) =>
-			c.contractAddress.toLowerCase() === args.currencyAddress.toLowerCase(),
-	);
-
-	if (!currencyDetails) {
-		throw new Error('Currency not found');
-	}
-
-	const amountDecimal = Number(
-		formatUnits(BigInt(args.amountRaw), currencyDetails.decimals),
-	);
-	const usdAmount = amountDecimal * currencyDetails.exchangeRate;
+import { useQuery } from '@tanstack/react-query';
+import type { Address } from 'viem';
+import type { Optional } from '../_internal';
+import {
+	type ConvertPriceToUSDQueryOptions,
+	type ConvertPriceToUSDReturn,
+	convertPriceToUSDQueryOptions,
+	type FetchConvertPriceToUSDParams,
+} from '../queries/convertPriceToUSD';
+import { useConfig } from './useConfig';
 
-	return {
-		usdAmount,
-		usdAmountFormatted: usdAmount.toFixed(2),
-	};
-};
-
-export const convertPriceToUSDOptions = (
-	args: UseConvertPriceToUSDArgs,
-	config: SdkConfig,
-) => {
-	return queryOptions({
-		...args.query,
-		queryKey: [...currencyKeys.conversion, args],
-		queryFn: () => convertPriceToUSD(args, config),
-	});
-};
+export type UseConvertPriceToUSDParams = Optional<
+	ConvertPriceToUSDQueryOptions,
+	'config'
+>;
 
 /**
  * Hook to convert a price amount from a specific currency to USD
- * @returns The price amount in USD and formatted USD amount
+ *
+ * Converts cryptocurrency amounts to their USD equivalent using current exchange rates.
+ * Fetches currency data and calculates the USD value based on the provided amount
+ * and currency address.
+ *
+ * @param params - Configuration parameters
+ * @param params.chainId - The chain ID (must be number, e.g., 1 for Ethereum, 137 for Polygon)
+ * @param params.currencyAddress - The currency contract address to convert from
+ * @param params.amountRaw - The raw amount in smallest units (e.g., wei for ETH)
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing USD amount and formatted USD amount
+ *
  * @example
- * ```ts
- * const { data } = useConvertPriceToUSD({
+ * Basic ETH to USD conversion:
+ * ```typescript
+ * const { data: conversion, isLoading } = useConvertPriceToUSD({
  *   chainId: 1,
- *   currencyAddress: "0x0000000000000000000000000000000000000000",
- *   amountRaw: "1000000000000000000",
- * });
+ *   currencyAddress: '0x0000000000000000000000000000000000000000', // ETH
+ *   amountRaw: '1000000000000000000' // 1 ETH in wei
+ * })
+ *
+ * if (data) {
+ *   console.log(`$${data.usdAmountFormatted}`); // e.g., "$2000.00"
+ *   console.log(data.usdAmount); // e.g., 2000
+ * }
+ * ```
  *
- * console.log(data);
- * // { usdAmount: 1000, usdAmountFormatted: "1000.00" }
+ * @example
+ * ERC-20 token conversion with conditional enabling:
+ * ```typescript
+ * const { data: conversion } = useConvertPriceToUSD({
+ *   chainId: 137,
+ *   currencyAddress: '0x2791bca1f2de4661ed88a30c99a7a9449aa84174', // USDC on Polygon
+ *   amountRaw: '1000000', // 1 USDC (6 decimals)
+ *   query: {
+ *     enabled: Boolean(userHasTokens),
+ *     refetchInterval: 30000 // Update price every 30 seconds
+ *   }
+ * })
  * ```
  */
-export const useConvertPriceToUSD = (args: UseConvertPriceToUSDArgs) => {
-	const config = useConfig();
-	return useQuery(convertPriceToUSDOptions(args, config));
+export function useConvertPriceToUSD(params: UseConvertPriceToUSDParams) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = convertPriceToUSDQueryOptions({
+		config,
+		...rest,
+	});
+
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { convertPriceToUSDQueryOptions };
+
+export type {
+	FetchConvertPriceToUSDParams,
+	ConvertPriceToUSDQueryOptions,
+	ConvertPriceToUSDReturn,
+};
+
+// Legacy exports for backward compatibility
+export type UseConvertPriceToUSDArgs = {
+	chainId: number;
+	currencyAddress: Address;
+	amountRaw: string;
+	query?: {
+		enabled?: boolean;
+	};
 };
+
+export type UseConvertPriceToUSDReturn = ConvertPriceToUSDReturn;

package/src/react/hooks/useCurrencyBalance.tsx

@@ -1,51 +1,137 @@
-import { skipToken, useQuery } from '@tanstack/react-query';
-import { type Address, erc20Abi, formatUnits, zeroAddress } from 'viem';
-import { usePublicClient } from 'wagmi';
-export function useCurrencyBalance({
-	currencyAddress,
-	chainId,
-	userAddress,
-}: {
+'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;
-}) {
-	const publicClient = usePublicClient({ chainId });
-
-	return useQuery({
-		queryKey: ['balance', currencyAddress, chainId, userAddress],
-		queryFn:
-			!!userAddress && !!chainId && !!currencyAddress && !!publicClient
-				? async () => {
-						if (currencyAddress === zeroAddress) {
-							const balance = await publicClient.getBalance({
-								address: userAddress,
-							});
-							return {
-								value: balance,
-								formatted: formatUnits(balance, 18),
-							};
-						}
-
-						const [balance, decimals] = await Promise.all([
-							publicClient.readContract({
-								address: currencyAddress,
-								abi: erc20Abi,
-								functionName: 'balanceOf',
-								args: [userAddress],
-							}),
-							publicClient.readContract({
-								address: currencyAddress,
-								abi: erc20Abi,
-								functionName: 'decimals',
-							}),
-						]);
-
-						return {
-							value: balance,
-							formatted: formatUnits(balance, decimals),
-						};
-					}
-				: skipToken,
+	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/useERC721SaleMintedTokens.tsx

@@ -1,7 +1,7 @@
 import type { Address } from 'viem';
 import { useReadContract } from 'wagmi';
 import { ERC721_SALE_ABI } from '../../../../sdk/src';
-import { useGetTokenSuppliesMap } from './useGetTokenSuppliesMap';
+import { useTokenSupplies } from './useTokenSupplies';
 
 interface UseERC721SaleMintedTokensProps {
 	chainId: number;
@@ -34,9 +34,8 @@ export function useERC721SaleMintedTokens({
 
 	// Get token supplies for all potential tokens in the sale
 	const { data: tokenSupplies, isLoading: tokenSuppliesLoading } =
-		useGetTokenSuppliesMap({
+		useTokenSupplies({
 			chainId,
-			tokenIds,
 			collectionAddress: contractAddress as Address,
 		});
 
@@ -44,8 +43,12 @@ export function useERC721SaleMintedTokens({
 
 	// Count how many tokens have been minted/owned
 	const ownedCount = tokenIds.reduce((count, tokenId) => {
-		const supplies = tokenSupplies?.supplies[contractAddress];
-		const supply = supplies?.find((s) => s.tokenID === tokenId);
+		let supply: { tokenID: string; supply: string } | undefined;
+
+		if (tokenSupplies) {
+			supply = tokenSupplies.tokenIDs.find((s) => s.tokenID === tokenId);
+		}
+
 		// If supply exists and is greater than 0, token exists and is owned
 		const hasOwner = supply ? BigInt(supply.supply) > 0n : false;
 		return count + (hasOwner ? 1 : 0);

package/src/react/hooks/useFilters.tsx

@@ -1,126 +1,152 @@
+'use client';
+
 import type { PropertyFilter } from '@0xsequence/metadata';
-import { queryOptions, useQuery } from '@tanstack/react-query';
-import { FilterCondition, type SdkConfig } from '../../types';
-import { compareAddress } from '../../utils';
+import { useQuery } from '@tanstack/react-query';
+import type { Optional } from '../_internal';
 import {
-	collectableKeys,
-	getMetadataClient,
-	getQueryClient,
-} from '../_internal';
-import { marketplaceConfigOptions } from '../queries/marketplaceConfig';
+	type FetchFiltersParams,
+	type FiltersQueryOptions,
+	filtersQueryOptions,
+} from '../queries/filters';
 import { useConfig } from './useConfig';
 
-export type UseFiltersArgs = {
-	chainId: number;
-	collectionAddress: string;
-	showAllFilters?: boolean;
-	excludePropertyValues?: boolean;
-	query?: {
-		enabled?: boolean;
-	};
-};
-
-export type UseFilterReturn = Awaited<ReturnType<typeof fetchFilters>>;
-
-export const fetchFilters = async (args: UseFiltersArgs, config: SdkConfig) => {
-	const parsedArgs = args;
-	const metadataClient = getMetadataClient(config);
-
-	const filters = await metadataClient
-		.getTokenMetadataPropertyFilters({
-			chainID: parsedArgs.chainId.toString(),
-			contractAddress: parsedArgs.collectionAddress,
-			excludeProperties: [],
-			excludePropertyValues: parsedArgs.excludePropertyValues,
-		})
-		.then((resp) => resp.filters);
-
-	if (args.showAllFilters) return filters;
-
-	const queryClient = getQueryClient();
-	const marketplaceConfig = await queryClient.fetchQuery(
-		marketplaceConfigOptions(config),
-	);
-	const collectionFilters = marketplaceConfig.market.collections.find((c) =>
-		compareAddress(c.itemsAddress, parsedArgs.collectionAddress),
-	)?.filterSettings;
-
-	if (
-		!collectionFilters?.exclusions ||
-		collectionFilters.exclusions.length === 0 ||
-		!collectionFilters.filterOrder ||
-		collectionFilters.filterOrder.length === 0
-	)
-		return filters;
-
-	const { filterOrder, exclusions } = collectionFilters;
-
-	const sortedFilters = filters.toSorted((a, b) => {
-		const aIndex =
-			filterOrder.indexOf(a.name) > -1
-				? filterOrder.indexOf(a.name)
-				: filterOrder.length;
-		const bIndex =
-			filterOrder.indexOf(b.name) > -1
-				? filterOrder.indexOf(b.name)
-				: filterOrder.length;
-		return aIndex - bIndex;
+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,
 	});
 
-	const filteredResults = sortedFilters.reduce<PropertyFilter[]>(
-		(acc, filter) => {
-			const exclusionRule = exclusions.find((rule) => rule.key === filter.name);
-
-			if (!exclusionRule) {
-				acc.push(filter);
-				return acc;
-			}
-
-			if (exclusionRule.condition === FilterCondition.ENTIRE_KEY) {
-				return acc;
-			}
-
-			if (
-				exclusionRule.condition === FilterCondition.SPECIFIC_VALUE &&
-				exclusionRule.value
-			) {
-				const filteredValues =
-					filter.values?.filter((value) => value !== exclusionRule.value) || [];
-				if (filteredValues.length > 0) {
-					acc.push({ ...filter, values: filteredValues });
-				}
-			}
-
-			return acc;
-		},
-		[],
-	);
-
-	return filteredResults;
-};
-
-export const filtersOptions = (args: UseFiltersArgs, config: SdkConfig) => {
-	return queryOptions({
-		...args.query,
-		queryKey: [...collectableKeys.filter, args, config],
-		queryFn: () => fetchFilters(args, config),
+	return useQuery({
+		...queryOptions,
 	});
-};
-
-export const useFilters = (args: UseFiltersArgs) => {
-	const config = useConfig();
-	return useQuery(filtersOptions(args, config));
-};
-
-export const useFiltersProgressive = (args: UseFiltersArgs) => {
-	const config = useConfig();
+}
+
+/**
+ * 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(
-		filtersOptions({ ...args, excludePropertyValues: true }, config),
+		filtersQueryOptions({
+			config,
+			...rest,
+			excludePropertyValues: true,
+		}),
 	);
 
 	const fullQuery = useQuery({
-		...filtersOptions(args, config),
+		...filtersQueryOptions({
+			config,
+			...rest,
+		}),
 		placeholderData: namesQuery.data,
 	});
 
@@ -132,4 +158,21 @@ export const useFiltersProgressive = (args: UseFiltersArgs) => {
 		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[];