@0xsequence/marketplace-sdk 0.8.12 → 0.10.0

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/useFilterState.tsx

@@ -1,5 +1,3 @@
-import { useMemo } from 'react';
-
 import {
 	createSerializer,
 	parseAsBoolean,
@@ -7,6 +5,7 @@ import {
 	parseAsString,
 	useQueryState,
 } from 'nuqs';
+import { useMemo } from 'react';
 import { type PropertyFilter, PropertyType } from '../_internal';
 
 interface StringFilterValues {

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[];

package/src/react/hooks/useFloorOrder.tsx

@@ -1,45 +1,70 @@
-import { queryOptions, useQuery } from '@tanstack/react-query';
-import { z } from 'zod';
-import type { SdkConfig } from '../../types';
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import type { Optional } from '../_internal';
 import {
-	AddressSchema,
-	QueryArgSchema,
-	collectableKeys,
-	getMarketplaceClient,
-} from '../_internal';
+	type FetchFloorOrderParams,
+	type FloorOrderQueryOptions,
+	floorOrderQueryOptions,
+} from '../queries/floorOrder';
 import { useConfig } from './useConfig';
 
-const UseFloorOrderSchema = z.object({
-	chainId: z.number(),
-	collectionAddress: AddressSchema,
-	query: QueryArgSchema,
-});
-
-export type UseFloorOrderArgs = z.infer<typeof UseFloorOrderSchema>;
-
-export type UseFloorOrderReturn = Awaited<ReturnType<typeof fetchFloorOrder>>;
-
-const fetchFloorOrder = async (args: UseFloorOrderArgs, config: SdkConfig) => {
-	const marketplaceClient = getMarketplaceClient(config);
-	return marketplaceClient
-		.getFloorOrder({
-			chainId: String(args.chainId),
-			contractAddress: args.collectionAddress,
-		})
-		.then((data) => data.collectible);
-};
-
-export const floorOrderOptions = (
-	args: UseFloorOrderArgs,
-	config: SdkConfig,
-) => {
-	return queryOptions({
-		queryKey: [...collectableKeys.floorOrders, args, config],
-		queryFn: () => fetchFloorOrder(args, config),
+export type UseFloorOrderParams = Optional<FloorOrderQueryOptions, 'config'>;
+
+/**
+ * Hook to fetch the floor order for a collection
+ *
+ * Retrieves the lowest priced order (listing) currently available for any token
+ * in the specified collection 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.collectionAddress - The collection contract address
+ * @param params.filter - Optional filter criteria for collectibles
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing the floor order data for the collection
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data, isLoading } = useFloorOrder({
+ *   chainId: 137,
+ *   collectionAddress: '0x...'
+ * })
+ * ```
+ *
+ * @example
+ * With filters and custom query options:
+ * ```typescript
+ * const { data, isLoading } = useFloorOrder({
+ *   chainId: 1,
+ *   collectionAddress: '0x...',
+ *   filter: {
+ *     minPrice: '1000000000000000000' // 1 ETH in wei
+ *   },
+ *   query: {
+ *     refetchInterval: 30000,
+ *     enabled: hasCollectionAddress
+ *   }
+ * })
+ * ```
+ */
+export function useFloorOrder(params: UseFloorOrderParams) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = floorOrderQueryOptions({
+		config,
+		...rest,
 	});
-};
 
-export const useFloorOrder = (args: UseFloorOrderArgs) => {
-	const config = useConfig();
-	return useQuery(floorOrderOptions(args, config));
-};
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { floorOrderQueryOptions };
+
+export type { FetchFloorOrderParams, FloorOrderQueryOptions };

package/src/react/hooks/useGenerateCancelTransaction.tsx

@@ -1,11 +1,10 @@
 import { useMutation } from '@tanstack/react-query';
-import { z } from 'zod';
 import type { SdkConfig } from '../../types';
 import {
 	type GenerateCancelTransactionArgs,
 	getMarketplaceClient,
 } from '../_internal';
-import { stepSchema } from '../_internal/api/zod-schema';
+import type { Step } from '../_internal/api/marketplace.gen';
 import { useConfig } from './useConfig';
 
 // Create a type that uses number for chainId
@@ -16,14 +15,10 @@ type GenerateCancelTransactionArgsWithNumberChainId = Omit<
 	chainId: number;
 };
 
-const UserGenerateCancelTransactionArgsSchema = z.object({
-	chainId: z.number(),
-	onSuccess: z.function().args(stepSchema.array().optional()).optional(),
-});
-
-type UseGenerateCancelTransactionArgs = z.infer<
-	typeof UserGenerateCancelTransactionArgsSchema
->;
+interface UseGenerateCancelTransactionArgs {
+	chainId: number;
+	onSuccess?: (steps?: Step[]) => void;
+}
 
 export const generateCancelTransaction = async (
 	args: GenerateCancelTransactionArgsWithNumberChainId,

package/src/react/hooks/useGenerateListingTransaction.tsx

@@ -11,8 +11,8 @@ import { dateToUnixTime } from '../../utils/date';
 import {
 	type CreateReq,
 	type GenerateListingTransactionArgs,
-	type Step,
 	getMarketplaceClient,
+	type Step,
 } from '../_internal';
 
 export type CreateReqWithDateExpiry = Omit<CreateReq, 'expiry'> & {