@0xsequence/marketplace-sdk 0.9.0 → 0.10.0

package/src/react/hooks/useCheckoutOptionsSalesContract.tsx

@@ -1,67 +1,108 @@
-import { queryOptions, skipToken, useQuery } from '@tanstack/react-query';
-import type { Hex } from 'viem';
+'use client';
+
+import { skipToken, useQuery } from '@tanstack/react-query';
+import type { Address } from 'viem';
 import { useAccount } from 'wagmi';
-import type { SdkConfig } from '../../types';
+import type { CheckoutOptionsItem, Optional } from '../_internal';
 import {
-	type CheckoutOptionsSalesContractArgs,
-	getMarketplaceClient,
-} from '../_internal';
+	type CheckoutOptionsSalesContractQueryOptions,
+	checkoutOptionsSalesContractQueryOptions,
+	type FetchCheckoutOptionsSalesContractParams,
+	type fetchCheckoutOptionsSalesContract,
+} from '../queries/checkoutOptionsSalesContract';
 import { useConfig } from './useConfig';
 
-type UseCheckoutOptionsSalesContractArgs = Omit<
-	CheckoutOptionsSalesContractArgs,
-	'wallet' | 'chainId'
-> & { chainId: number };
+export type UseCheckoutOptionsSalesContractParams = Optional<
+	CheckoutOptionsSalesContractQueryOptions,
+	'config' | 'walletAddress'
+>;
 
-const fetchCheckoutOptionsSalesContract = async (
-	args: CheckoutOptionsSalesContractArgs,
-	config: SdkConfig,
-) => {
-	const marketplaceClient = getMarketplaceClient(config);
-	return marketplaceClient.checkoutOptionsSalesContract({
-		chainId: args.chainId,
-		wallet: args.wallet,
-		contractAddress: args.contractAddress,
-		collectionAddress: args.collectionAddress,
-		items: args.items,
-	});
-};
+/**
+ * Hook to fetch checkout options for sales contract items
+ *
+ * Retrieves checkout options including available payment methods, fees, and transaction details
+ * for items from a sales contract. Requires a connected wallet to calculate wallet-specific options.
+ *
+ * @param params - Configuration parameters or skipToken to skip the query
+ * @param params.chainId - The chain ID (must be number, e.g., 1 for Ethereum, 137 for Polygon)
+ * @param params.contractAddress - The sales contract address
+ * @param params.collectionAddress - The collection contract address
+ * @param params.items - Array of items to purchase with tokenId and quantity
+ * @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 } = useCheckoutOptionsSalesContract({
+ *   chainId: 137,
+ *   contractAddress: '0x1234...',
+ *   collectionAddress: '0x5678...',
+ *   items: [{
+ *     tokenId: '1',
+ *     quantity: '1'
+ *   }]
+ * })
+ * ```
+ *
+ * @example
+ * With skipToken to conditionally skip:
+ * ```typescript
+ * const { data: checkoutOptions } = useCheckoutOptionsSalesContract(
+ *   items.length > 0 ? {
+ *     chainId: 1,
+ *     contractAddress: contractAddress,
+ *     collectionAddress: collectionAddress,
+ *     items: items
+ *   } : skipToken
+ * )
+ * ```
+ */
+export function useCheckoutOptionsSalesContract(
+	params: UseCheckoutOptionsSalesContractParams | typeof skipToken,
+) {
+	const { address } = useAccount();
+	const defaultConfig = useConfig();
+
+	const queryOptions = checkoutOptionsSalesContractQueryOptions(
+		params === skipToken
+			? {
+					config: defaultConfig,
+					walletAddress: address as Address,
+					chainId: 0,
+					contractAddress: '',
+					collectionAddress: '',
+					items: [],
+					query: { enabled: false },
+				}
+			: {
+					config: defaultConfig,
+					walletAddress: address as Address,
+					...params,
+				},
+	);
 
-export const checkoutOptionsSalesContractOptions = (
-	args:
-		| (UseCheckoutOptionsSalesContractArgs & { wallet?: Hex })
-		| typeof skipToken,
-	config: SdkConfig,
-) => {
-	return queryOptions({
-		queryKey: ['checkoutOptionsSalesContract', args],
-		queryFn:
-			skipToken === args
-				? skipToken
-				: () =>
-						fetchCheckoutOptionsSalesContract(
-							{
-								chainId: String(args.chainId),
-								// biome-ignore lint/style/noNonNullAssertion: wallet is guaranteed to exist when not skipToken
-								wallet: args.wallet!,
-								contractAddress: args.contractAddress,
-								collectionAddress: args.collectionAddress,
-								items: args.items,
-							},
-							config,
-						),
+	return useQuery({
+		...queryOptions,
 	});
+}
+
+export { checkoutOptionsSalesContractQueryOptions };
+
+export type {
+	FetchCheckoutOptionsSalesContractParams,
+	CheckoutOptionsSalesContractQueryOptions,
 };
 
-export const useCheckoutOptionsSalesContract = (
-	args: UseCheckoutOptionsSalesContractArgs | typeof skipToken,
-) => {
-	const { address } = useAccount();
-	const config = useConfig();
-	return useQuery(
-		checkoutOptionsSalesContractOptions(
-			skipToken === args ? skipToken : { ...args, wallet: address },
-			config,
-		),
-	);
+// Legacy exports for backward compatibility
+export type UseCheckoutOptionsSalesContractArgs = {
+	chainId: number;
+	contractAddress: string;
+	collectionAddress: string;
+	items: Array<CheckoutOptionsItem>;
 };
+
+export type UseCheckoutOptionsSalesContractReturn = Awaited<
+	ReturnType<typeof fetchCheckoutOptionsSalesContract>
+>;

package/src/react/hooks/useCollectionBalanceDetails.tsx

@@ -1,79 +1,106 @@
-import type { GetTokenBalancesDetailsReturn } from '@0xsequence/indexer';
-import { queryOptions, useQuery } from '@tanstack/react-query';
-import type { Address } from 'viem';
-import type { SdkConfig } from '../../types';
-import type { QueryArg } from '../_internal';
-import { balanceQueries, getIndexerClient } from '../_internal';
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import type { Optional } from '../_internal';
+import {
+	type CollectionBalanceDetailsQueryOptions,
+	type CollectionBalanceFilter,
+	collectionBalanceDetailsQueryOptions,
+	type FetchCollectionBalanceDetailsParams,
+	type fetchCollectionBalanceDetails,
+} from '../queries/collectionBalanceDetails';
 import { useConfig } from './useConfig';
 
-export interface CollectionBalanceFilter {
-	accountAddresses: Address[];
-	contractWhitelist?: Address[];
-	omitNativeBalances: boolean;
-}
+export type UseCollectionBalanceDetailsParams = Optional<
+	CollectionBalanceDetailsQueryOptions,
+	'config'
+>;
 
-export interface UseCollectionBalanceDetailsArgs {
-	chainId: number;
-	filter: CollectionBalanceFilter;
-	query?: QueryArg;
-}
-
-const fetchCollectionBalanceDetails = async (
-	args: UseCollectionBalanceDetailsArgs,
-	indexerClient: Awaited<ReturnType<typeof getIndexerClient>>,
-) => {
-	const promises = args.filter.accountAddresses.map((accountAddress) =>
-		indexerClient.getTokenBalancesDetails({
-			filter: {
-				accountAddresses: [accountAddress],
-				contractWhitelist: args.filter.contractWhitelist,
-				omitNativeBalances: args.filter.omitNativeBalances,
-			},
-		}),
-	);
+/**
+ * Hook to fetch detailed balance information for multiple accounts
+ *
+ * Retrieves token balances and native balances for multiple account addresses,
+ * with support for contract whitelisting and optional native balance exclusion.
+ * Aggregates results from multiple account addresses into a single response.
+ *
+ * @param params - Configuration parameters
+ * @param params.chainId - The chain ID (must be number, e.g., 1 for Ethereum, 137 for Polygon)
+ * @param params.filter - Filter configuration for balance queries
+ * @param params.filter.accountAddresses - Array of account addresses to query balances for
+ * @param params.filter.contractWhitelist - Optional array of contract addresses to filter by
+ * @param params.filter.omitNativeBalances - Whether to exclude native token balances
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing aggregated balance details for all accounts
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data: balanceDetails, isLoading } = useCollectionBalanceDetails({
+ *   chainId: 137,
+ *   filter: {
+ *     accountAddresses: ['0x1234...', '0x5678...'],
+ *     omitNativeBalances: false
+ *   }
+ * })
+ *
+ * if (data) {
+ *   console.log(`Found ${data.balances.length} token balances`);
+ *   console.log(`Found ${data.nativeBalances.length} native balances`);
+ * }
+ * ```
+ *
+ * @example
+ * With contract whitelist:
+ * ```typescript
+ * const { data: balanceDetails } = useCollectionBalanceDetails({
+ *   chainId: 1,
+ *   filter: {
+ *     accountAddresses: [userAddress],
+ *     contractWhitelist: ['0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'], // USDC only
+ *     omitNativeBalances: true
+ *   },
+ *   query: {
+ *     enabled: Boolean(userAddress),
+ *     refetchInterval: 60000 // Refresh every minute
+ *   }
+ * })
+ * ```
+ */
+export function useCollectionBalanceDetails(
+	params: UseCollectionBalanceDetailsParams,
+) {
+	const defaultConfig = useConfig();
 
-	const responses = await Promise.all(promises);
-	const mergedResponse = responses.reduce<GetTokenBalancesDetailsReturn>(
-		(
-			acc: GetTokenBalancesDetailsReturn,
-			curr: GetTokenBalancesDetailsReturn | null,
-		) => {
-			if (!curr) return acc;
-			return {
-				page: curr.page,
-				nativeBalances: [
-					...(acc.nativeBalances || []),
-					...(curr.nativeBalances || []),
-				],
-				balances: [...(acc.balances || []), ...(curr.balances || [])],
-			};
-		},
-		{ page: {}, nativeBalances: [], balances: [] },
-	);
+	const { config = defaultConfig, ...rest } = params;
 
-	if (!mergedResponse) {
-		throw new Error('Failed to fetch collection balance details');
-	}
+	const queryOptions = collectionBalanceDetailsQueryOptions({
+		config,
+		...rest,
+	});
 
-	return mergedResponse;
-};
+	return useQuery({
+		...queryOptions,
+	});
+}
 
-export const collectionBalanceDetailsOptions = (
-	args: UseCollectionBalanceDetailsArgs,
-	config: SdkConfig,
-) => {
-	const indexerClient = getIndexerClient(args.chainId, config);
+export { collectionBalanceDetailsQueryOptions };
 
-	return queryOptions({
-		queryKey: [...balanceQueries.collectionBalanceDetails, args, config],
-		queryFn: () => fetchCollectionBalanceDetails(args, indexerClient),
-		...(args.query || {}),
-	});
+export type {
+	FetchCollectionBalanceDetailsParams,
+	CollectionBalanceDetailsQueryOptions,
+	CollectionBalanceFilter,
 };
 
-export const useCollectionBalanceDetails = (
-	args: UseCollectionBalanceDetailsArgs,
-) => {
-	const config = useConfig();
-	return useQuery(collectionBalanceDetailsOptions(args, config));
+// Legacy exports for backward compatibility
+export type UseCollectionBalanceDetailsArgs = {
+	chainId: number;
+	filter: CollectionBalanceFilter;
+	query?: {
+		enabled?: boolean;
+	};
 };
+
+export type UseCollectionBalanceDetailsReturn = Awaited<
+	ReturnType<typeof fetchCollectionBalanceDetails>
+>;

package/src/react/hooks/useCollectionDetailsPolling.tsx

@@ -1,7 +1,7 @@
 import { queryOptions, useQuery } from '@tanstack/react-query';
 import type { SdkConfig } from '../../types';
-import { CollectionStatus } from '../_internal/api/marketplace.gen';
-import { collectionDetailsQueryOptions } from '../queries/collectionDetails';
+import { CollectionStatus } from '../_internal';
+import { collectionDetailsQueryOptions } from './useCollectionDetails';
 import { useConfig } from './useConfig';
 
 type UseCollectionDetailsPolling = {
@@ -30,11 +30,7 @@ export const collectionDetailsPollingOptions = (
 	config: SdkConfig,
 ) => {
 	return queryOptions({
-		...collectionDetailsQueryOptions({
-			collectionAddress: args.collectionAddress,
-			chainId: args.chainId,
-			config,
-		}),
+		...collectionDetailsQueryOptions({ ...args, config }),
 		refetchInterval: (query) => {
 			const data = query.state.data;
 			if (data && isTerminalState(data.status)) {

package/src/react/hooks/useComparePrices.tsx

@@ -1,96 +1,104 @@
-import { queryOptions, useQuery } from '@tanstack/react-query';
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
 import type { Address } from 'viem';
-import type { SdkConfig } from '../../types';
-import { currencyKeys, type QueryArg } from '../_internal';
+import type { Optional } from '../_internal';
+import {
+	type ComparePricesQueryOptions,
+	comparePricesQueryOptions,
+	type FetchComparePricesParams,
+} from '../queries/comparePrices';
 import { useConfig } from './useConfig';
-import { convertPriceToUSD } from './useConvertPriceToUSD';
 
-export interface UseComparePricesArgs {
+export type UseComparePricesParams = Optional<
+	ComparePricesQueryOptions,
+	'config'
+>;
+
+/**
+ * Hook to compare prices between different currencies by converting both to USD
+ *
+ * Compares two prices by converting both to USD using real-time exchange rates
+ * and returns the percentage difference with comparison status.
+ *
+ * @param params - Configuration parameters
+ * @param params.chainId - The chain ID (must be number, e.g., 1 for Ethereum, 137 for Polygon)
+ * @param params.priceAmountRaw - The raw amount of the first price (wei format)
+ * @param params.priceCurrencyAddress - The currency address of the first price
+ * @param params.compareToPriceAmountRaw - The raw amount of the second price to compare against (wei format)
+ * @param params.compareToPriceCurrencyAddress - The currency address of the second price
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing percentage difference and comparison status
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data: comparison, isLoading } = useComparePrices({
+ *   chainId: 1,
+ *   priceAmountRaw: '1000000000000000000', // 1 ETH in wei
+ *   priceCurrencyAddress: '0x0000000000000000000000000000000000000000', // ETH
+ *   compareToPriceAmountRaw: '2000000000', // 2000 USDC in wei (6 decimals)
+ *   compareToPriceCurrencyAddress: '0xA0b86a33E6B8DbF5E71Eaa9bfD3F6fD8e8Be3F69' // USDC
+ * })
+ *
+ * if (data) {
+ *   console.log(`${data.percentageDifferenceFormatted}% ${data.status}`);
+ *   // e.g., "25.50% above" or "10.25% below"
+ * }
+ * ```
+ *
+ * @example
+ * With custom query options:
+ * ```typescript
+ * const { data: comparison } = useComparePrices({
+ *   chainId: 137,
+ *   priceAmountRaw: price1,
+ *   priceCurrencyAddress: currency1Address,
+ *   compareToPriceAmountRaw: price2,
+ *   compareToPriceCurrencyAddress: currency2Address,
+ *   query: {
+ *     enabled: Boolean(price1 && price2),
+ *     refetchInterval: 30000 // Refresh every 30 seconds
+ *   }
+ * })
+ * ```
+ */
+export function useComparePrices(params: UseComparePricesParams) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = comparePricesQueryOptions({
+		config,
+		...rest,
+	});
+
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { comparePricesQueryOptions };
+
+export type { FetchComparePricesParams, ComparePricesQueryOptions };
+
+// Legacy exports for backward compatibility
+export type UseComparePricesArgs = {
 	chainId: number;
-	// First price details
 	priceAmountRaw: string;
 	priceCurrencyAddress: Address;
-	// Second price details (to compare against)
 	compareToPriceAmountRaw: string;
 	compareToPriceCurrencyAddress: Address;
-	query: QueryArg;
-}
+	query?: {
+		enabled?: boolean;
+	};
+};
 
-export interface UseComparePricesReturn {
+export type UseComparePricesReturn = {
 	percentageDifference: number;
 	percentageDifferenceFormatted: string;
 	status: 'above' | 'same' | 'below';
-}
-
-const comparePrices = async (
-	args: UseComparePricesArgs,
-	config: SdkConfig,
-): Promise<UseComparePricesReturn> => {
-	const [priceUSD, compareToPriceUSD] = await Promise.all([
-		convertPriceToUSD(
-			{
-				chainId: args.chainId,
-				currencyAddress: args.priceCurrencyAddress,
-				amountRaw: args.priceAmountRaw,
-				query: {},
-			},
-			config,
-		),
-		convertPriceToUSD(
-			{
-				chainId: args.chainId,
-				currencyAddress: args.compareToPriceCurrencyAddress,
-				amountRaw: args.compareToPriceAmountRaw,
-				query: {},
-			},
-			config,
-		),
-	]);
-	const difference = priceUSD.usdAmount - compareToPriceUSD.usdAmount;
-
-	if (compareToPriceUSD.usdAmount === 0) {
-		throw new Error('Cannot compare to zero price');
-	}
-
-	const percentageDifference = (difference / compareToPriceUSD.usdAmount) * 100;
-	const isAbove = percentageDifference > 0;
-	const isSame = percentageDifference === 0;
-
-	return {
-		percentageDifference,
-		percentageDifferenceFormatted: Math.abs(percentageDifference).toFixed(2),
-		status: isAbove ? 'above' : isSame ? 'same' : 'below',
-	};
 };
 
-export const comparePricesOptions = (
-	args: UseComparePricesArgs,
-	config: SdkConfig,
-) => {
-	return queryOptions({
-		...args.query,
-		queryKey: [...currencyKeys.conversion, 'compare', args],
-		queryFn: () => comparePrices(args, config),
-	});
-};
-
-/**
- * Hook to compare prices between different currencies by converting both to USD
- * @param args - The arguments for the hook
- * @returns The percentage difference between the two prices
- * @example
- * ```ts
- * const { data } = useComparePrices({
- *   chainId: 1,
- *   priceAmountRaw: "1000000000000000000",
- *   priceCurrencyAddress: "0x0000000000000000000000000000000000000000",
- * });
- *
- * console.log(data);
- * // { percentageDifference: 10, percentageDifferenceFormatted: "10.00", isAbove: true, isSame: false, isBelow: false }
- * ```
- */
-export const useComparePrices = (args: UseComparePricesArgs) => {
-	const config = useConfig();
-	return useQuery(comparePricesOptions(args, config));
-};
+export type ComparePricesReturn = UseComparePricesReturn;