@0xsequence/marketplace-sdk 0.8.12 → 0.10.0

package/src/react/hooks/useCollectionBalanceDetails.tsx

@@ -1,86 +1,106 @@
-import type { GetTokenBalancesDetailsReturn } from '@0xsequence/indexer';
-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,
-	balanceQueries,
-	getIndexerClient,
-} from '../_internal';
+	type CollectionBalanceDetailsQueryOptions,
+	type CollectionBalanceFilter,
+	collectionBalanceDetailsQueryOptions,
+	type FetchCollectionBalanceDetailsParams,
+	type fetchCollectionBalanceDetails,
+} from '../queries/collectionBalanceDetails';
 import { useConfig } from './useConfig';
 
-const filterSchema = z.object({
-	accountAddresses: z.array(AddressSchema),
-	contractWhitelist: z.array(AddressSchema).optional(),
-	omitNativeBalances: z.boolean(),
-});
-
-const useCollectionBalanceDetailsArgsSchema = z.object({
-	chainId: z.number(),
-	filter: filterSchema,
-	query: QueryArgSchema.optional(),
-});
-
-export type CollectionBalanceFilter = z.infer<typeof filterSchema>;
-export type UseCollectionBalanceDetailsArgs = z.input<
-	typeof useCollectionBalanceDetailsArgsSchema
+export type UseCollectionBalanceDetailsParams = Optional<
+	CollectionBalanceDetailsQueryOptions,
+	'config'
 >;
 
-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, curr) => {
-			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 parsedArgs = useCollectionBalanceDetailsArgsSchema.parse(args);
-	const indexerClient = getIndexerClient(parsedArgs.chainId, config);
+export { collectionBalanceDetailsQueryOptions };
 
-	return queryOptions({
-		queryKey: [...balanceQueries.collectionBalanceDetails, args, config],
-		queryFn: () => fetchCollectionBalanceDetails(parsedArgs, 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/useCollectionDetails.ts

@@ -0,0 +1,69 @@
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import type { Optional } from '../_internal';
+import {
+	type CollectionDetailsQueryOptions,
+	collectionDetailsQueryOptions,
+	type FetchCollectionDetailsParams,
+} from '../queries/collectionDetails';
+import { useConfig } from './useConfig';
+
+export type UseCollectionDetailsParams = Optional<
+	CollectionDetailsQueryOptions,
+	'config'
+>;
+
+/**
+ * Hook to fetch detailed information about a collection
+ *
+ * This hook retrieves comprehensive metadata and details for an NFT collection,
+ * including collection name, description, banner, avatar, social links, stats, etc.
+ *
+ * @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.query - Optional React Query configuration
+ *
+ * @returns Query result containing the collection details
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data: collection, isLoading } = useCollectionDetails({
+ *   chainId: 137,
+ *   collectionAddress: '0x631998e91476da5b870d741192fc5cbc55f5a52e'
+ * })
+ * ```
+ *
+ * @example
+ * With custom query options:
+ * ```typescript
+ * const { data } = useCollectionDetails({
+ *   chainId: 137,
+ *   collectionAddress: '0x631998e91476da5b870d741192fc5cbc55f5a52e',
+ *   query: {
+ *     enabled: Boolean(collectionAddress),
+ *     staleTime: 60_000
+ *   }
+ * })
+ * ```
+ */
+export function useCollectionDetails(params: UseCollectionDetailsParams) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = collectionDetailsQueryOptions({
+		config,
+		...rest,
+	});
+
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { collectionDetailsQueryOptions };
+
+export type { FetchCollectionDetailsParams, CollectionDetailsQueryOptions };

package/src/react/hooks/useCollectionDetailsPolling.tsx

@@ -1,12 +1,15 @@
 import { queryOptions, useQuery } from '@tanstack/react-query';
 import type { SdkConfig } from '../../types';
-import { CollectionStatus } from '../_internal/api/marketplace.gen';
-import { collectionDetailsOptions } from './useCollectionDetails';
+import { CollectionStatus } from '../_internal';
+import { collectionDetailsQueryOptions } from './useCollectionDetails';
 import { useConfig } from './useConfig';
 
 type UseCollectionDetailsPolling = {
 	collectionAddress: string;
 	chainId: number;
+	query?: {
+		enabled?: boolean;
+	};
 };
 
 const INITIAL_POLLING_INTERVAL = 2000; // 2 seconds
@@ -27,7 +30,7 @@ export const collectionDetailsPollingOptions = (
 	config: SdkConfig,
 ) => {
 	return queryOptions({
-		...collectionDetailsOptions(args, config),
+		...collectionDetailsQueryOptions({ ...args, config }),
 		refetchInterval: (query) => {
 			const data = query.state.data;
 			if (data && isTerminalState(data.status)) {
@@ -49,6 +52,7 @@ export const collectionDetailsPollingOptions = (
 		},
 		refetchOnWindowFocus: false,
 		retry: false,
+		enabled: args.query?.enabled ?? true,
 	});
 };
 

package/src/react/hooks/useComparePrices.tsx

@@ -1,99 +1,104 @@
-import { queryOptions, useQuery } from '@tanstack/react-query';
-import { z } from 'zod';
-import type { SdkConfig } from '../../types';
-import { AddressSchema, QueryArgSchema, currencyKeys } from '../_internal';
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import type { Address } from 'viem';
+import type { Optional } from '../_internal';
+import {
+	type ComparePricesQueryOptions,
+	comparePricesQueryOptions,
+	type FetchComparePricesParams,
+} from '../queries/comparePrices';
 import { useConfig } from './useConfig';
-import { convertPriceToUSD } from './useConvertPriceToUSD';
 
-const UseComparePricesArgsSchema = z.object({
-	chainId: z.number(),
-	// First price details
-	priceAmountRaw: z.string(),
-	priceCurrencyAddress: AddressSchema,
-	// Second price details (to compare against)
-	compareToPriceAmountRaw: z.string(),
-	compareToPriceCurrencyAddress: AddressSchema,
-	query: QueryArgSchema,
-});
+export type UseComparePricesParams = Optional<
+	ComparePricesQueryOptions,
+	'config'
+>;
 
-type UseComparePricesArgs = z.input<typeof UseComparePricesArgsSchema>;
+/**
+ * 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();
 
-export type UseComparePricesReturn = {
-	percentageDifference: number;
-	percentageDifferenceFormatted: string;
-	status: 'above' | 'same' | 'below';
-};
+	const { config = defaultConfig, ...rest } = params;
 
-const comparePrices = async (
-	args: UseComparePricesArgs,
-	config: SdkConfig,
-): Promise<UseComparePricesReturn> => {
-	const parsedArgs = UseComparePricesArgsSchema.parse(args);
-	const [priceUSD, compareToPriceUSD] = await Promise.all([
-		convertPriceToUSD(
-			{
-				chainId: parsedArgs.chainId,
-				currencyAddress: parsedArgs.priceCurrencyAddress,
-				amountRaw: parsedArgs.priceAmountRaw,
-				query: {},
-			},
-			config,
-		),
-		convertPriceToUSD(
-			{
-				chainId: parsedArgs.chainId,
-				currencyAddress: parsedArgs.compareToPriceCurrencyAddress,
-				amountRaw: parsedArgs.compareToPriceAmountRaw,
-				query: {},
-			},
-			config,
-		),
-	]);
-	const difference = priceUSD.usdAmount - compareToPriceUSD.usdAmount;
+	const queryOptions = comparePricesQueryOptions({
+		config,
+		...rest,
+	});
+
+	return useQuery({
+		...queryOptions,
+	});
+}
 
-	if (compareToPriceUSD.usdAmount === 0) {
-		throw new Error('Cannot compare to zero price');
-	}
+export { comparePricesQueryOptions };
 
-	const percentageDifference = (difference / compareToPriceUSD.usdAmount) * 100;
-	const isAbove = percentageDifference > 0;
-	const isSame = percentageDifference === 0;
+export type { FetchComparePricesParams, ComparePricesQueryOptions };
 
-	return {
-		percentageDifference,
-		percentageDifferenceFormatted: Math.abs(percentageDifference).toFixed(2),
-		status: isAbove ? 'above' : isSame ? 'same' : 'below',
+// Legacy exports for backward compatibility
+export type UseComparePricesArgs = {
+	chainId: number;
+	priceAmountRaw: string;
+	priceCurrencyAddress: Address;
+	compareToPriceAmountRaw: string;
+	compareToPriceCurrencyAddress: Address;
+	query?: {
+		enabled?: boolean;
 	};
 };
 
-export const comparePricesOptions = (
-	args: UseComparePricesArgs,
-	config: SdkConfig,
-) => {
-	return queryOptions({
-		...args.query,
-		queryKey: [...currencyKeys.conversion, 'compare', args],
-		queryFn: () => comparePrices(args, config),
-	});
+export type UseComparePricesReturn = {
+	percentageDifference: number;
+	percentageDifferenceFormatted: string;
+	status: 'above' | 'same' | 'below';
 };
 
-/**
- * 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;

package/src/react/hooks/useConvertPriceToUSD.tsx

@@ -1,99 +1,96 @@
-import { queryOptions, useQuery } from '@tanstack/react-query';
-import { formatUnits } from 'viem';
-import { z } from 'zod';
-import type { SdkConfig } from '../../types';
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import type { Address } from 'viem';
+import type { Optional } from '../_internal';
 import {
-	AddressSchema,
-	QueryArgSchema,
-	currencyKeys,
-	getQueryClient,
-} from '../_internal';
-import { currenciesOptions } from '../queries/marketCurrencies';
+	type ConvertPriceToUSDQueryOptions,
+	type ConvertPriceToUSDReturn,
+	convertPriceToUSDQueryOptions,
+	type FetchConvertPriceToUSDParams,
+} from '../queries/convertPriceToUSD';
 import { useConfig } from './useConfig';
 
-const UseConvertPriceToUSDArgsSchema = z.object({
-	chainId: z.number(),
-	currencyAddress: AddressSchema,
-	amountRaw: z.string(),
-	query: QueryArgSchema,
-});
-
-export type UseConvertPriceToUSDArgs = z.input<
-	typeof UseConvertPriceToUSDArgsSchema
+export type UseConvertPriceToUSDParams = Optional<
+	ConvertPriceToUSDQueryOptions,
+	'config'
 >;
 
-export type UseConvertPriceToUSDReturn = {
-	usdAmount: number;
-	usdAmountFormatted: string;
-};
-
-export const convertPriceToUSD = async (
-	args: UseConvertPriceToUSDArgs,
-	config: SdkConfig,
-): Promise<UseConvertPriceToUSDReturn> => {
-	const parsedArgs = UseConvertPriceToUSDArgsSchema.parse(args);
-	const queryClient = getQueryClient();
-	const currencies = await queryClient.fetchQuery(
-		currenciesOptions(
-			{
-				chainId: parsedArgs.chainId,
-			},
-			config,
-		),
-	);
-	const currencyDetails = currencies.find(
-		(c) =>
-			c.contractAddress.toLowerCase() ===
-			parsedArgs.currencyAddress.toLowerCase(),
-	);
-
-	if (!currencyDetails) {
-		throw new Error('Currency not found');
-	}
-
-	const amountDecimal = Number(
-		formatUnits(BigInt(parsedArgs.amountRaw), currencyDetails.decimals),
-	);
-	const usdAmount = amountDecimal * currencyDetails.exchangeRate;
-
-	return {
-		usdAmount,
-		usdAmountFormatted: usdAmount.toFixed(2),
-	};
-};
-
-export const convertPriceToUSDOptions = (
-	args: UseConvertPriceToUSDArgs,
-	config: SdkConfig,
-) => {
-	return queryOptions({
-		...args.query,
-		queryKey: [
-			...currencyKeys.conversion,
-			args.chainId,
-			args.currencyAddress,
-			args.amountRaw,
-		],
-		queryFn: () => convertPriceToUSD(args, 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;