@0xsequence/marketplace-sdk 0.8.12 → 0.9.0

package/src/react/hooks/useCollectible.tsx

@@ -1,54 +1,69 @@
-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,
-	getMetadataClient,
-} from '../_internal';
+	type CollectibleQueryOptions,
+	collectibleQueryOptions,
+	type FetchCollectibleParams,
+} from '../queries/collectible';
 import { useConfig } from './useConfig';
 
-const UseCollectibleSchema = z.object({
-	chainId: z.number(),
-	collectionAddress: AddressSchema,
-	collectibleId: z.string().optional(),
-	query: QueryArgSchema,
-});
-
-export type UseCollectibleArgs = z.infer<typeof UseCollectibleSchema>;
-
-export type UseCollectibleReturn = Awaited<ReturnType<typeof fetchCollectible>>;
-
-const fetchCollectible = async (
-	args: UseCollectibleArgs,
-	config: SdkConfig,
-) => {
-	const parsedArgs = UseCollectibleSchema.parse(args);
-	const metadataClient = getMetadataClient(config);
-	const tokenIds = parsedArgs.collectibleId ? [parsedArgs.collectibleId] : [];
-
-	return metadataClient
-		.getTokenMetadata({
-			chainID: parsedArgs.chainId.toString(),
-			contractAddress: parsedArgs.collectionAddress,
-			tokenIDs: tokenIds,
-		})
-		.then((resp) => resp.tokenMetadata[0]);
-};
-
-export const collectibleOptions = (
-	args: UseCollectibleArgs,
-	config: SdkConfig,
-) => {
-	return queryOptions({
-		...args.query,
-		queryKey: [...collectableKeys.details, args, config],
-		queryFn: () => fetchCollectible(args, config),
+export type UseCollectibleParams = Optional<CollectibleQueryOptions, 'config'>;
+
+/**
+ * Hook to fetch metadata for a specific collectible
+ *
+ * This hook retrieves metadata for an individual NFT from a collection,
+ * including properties like name, description, image, attributes, 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.collectibleId - The token ID of the collectible
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing the collectible metadata
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data: collectible, isLoading } = useCollectible({
+ *   chainId: 137,
+ *   collectionAddress: '0x631998e91476da5b870d741192fc5cbc55f5a52e',
+ *   collectibleId: '12345'
+ * })
+ * ```
+ *
+ * @example
+ * With custom query options:
+ * ```typescript
+ * const { data } = useCollectible({
+ *   chainId: 137,
+ *   collectionAddress: '0x631998e91476da5b870d741192fc5cbc55f5a52e',
+ *   collectibleId: '12345',
+ *   query: {
+ *     enabled: Boolean(collectionAddress && tokenId),
+ *     staleTime: 30_000
+ *   }
+ * })
+ * ```
+ */
+export function useCollectible(params: UseCollectibleParams) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = collectibleQueryOptions({
+		config,
+		...rest,
 	});
-};
 
-export const useCollectible = (args: UseCollectibleArgs) => {
-	const config = useConfig();
-	return useQuery(collectibleOptions(args, config));
-};
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { collectibleQueryOptions };
+
+export type { FetchCollectibleParams, CollectibleQueryOptions };

package/src/react/hooks/useCollection.tsx

@@ -1,17 +1,66 @@
+'use client';
+
 import { useQuery } from '@tanstack/react-query';
-import type { z } from 'zod';
+import type { Optional } from '../_internal';
 import {
-	type UseCollectionSchema,
-	collectionOptions,
-	type fetchCollection,
-} from './options/collectionOptions';
+	type CollectionQueryOptions,
+	collectionQueryOptions,
+	type FetchCollectionParams,
+} from '../queries/collection';
 import { useConfig } from './useConfig';
 
-export type UseCollectionArgs = z.input<typeof UseCollectionSchema>;
+export type UseCollectionParams = Optional<CollectionQueryOptions, 'config'>;
+
+/**
+ * Hook to fetch collection information from the metadata API
+ *
+ * Retrieves basic contract information including name, symbol, type,
+ * and extension data for a given collection contract.
+ *
+ * @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 contract information
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data, isLoading } = useCollection({
+ *   chainId: 137,
+ *   collectionAddress: '0x...'
+ * })
+ * ```
+ *
+ * @example
+ * With custom query options:
+ * ```typescript
+ * const { data, isLoading } = useCollection({
+ *   chainId: 1,
+ *   collectionAddress: '0x...',
+ *   query: {
+ *     refetchInterval: 30000,
+ *     enabled: userWantsToFetch
+ *   }
+ * })
+ * ```
+ */
+export function useCollection(params: UseCollectionParams) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = collectionQueryOptions({
+		config,
+		...rest,
+	});
+
+	return useQuery({
+		...queryOptions,
+	});
+}
 
-export type UseCollectionReturn = Awaited<ReturnType<typeof fetchCollection>>;
+export { collectionQueryOptions };
 
-export const useCollection = (args: UseCollectionArgs) => {
-	const config = useConfig();
-	return useQuery(collectionOptions(args, config));
-};
+export type { FetchCollectionParams, CollectionQueryOptions };

package/src/react/hooks/useCollectionBalanceDetails.tsx

@@ -1,31 +1,22 @@
 import type { GetTokenBalancesDetailsReturn } from '@0xsequence/indexer';
 import { queryOptions, useQuery } from '@tanstack/react-query';
-import { z } from 'zod';
+import type { Address } from 'viem';
 import type { SdkConfig } from '../../types';
-import {
-	AddressSchema,
-	QueryArgSchema,
-	balanceQueries,
-	getIndexerClient,
-} from '../_internal';
+import type { QueryArg } from '../_internal';
+import { balanceQueries, getIndexerClient } from '../_internal';
 import { useConfig } from './useConfig';
 
-const filterSchema = z.object({
-	accountAddresses: z.array(AddressSchema),
-	contractWhitelist: z.array(AddressSchema).optional(),
-	omitNativeBalances: z.boolean(),
-});
+export interface CollectionBalanceFilter {
+	accountAddresses: Address[];
+	contractWhitelist?: Address[];
+	omitNativeBalances: 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 interface UseCollectionBalanceDetailsArgs {
+	chainId: number;
+	filter: CollectionBalanceFilter;
+	query?: QueryArg;
+}
 
 const fetchCollectionBalanceDetails = async (
 	args: UseCollectionBalanceDetailsArgs,
@@ -43,7 +34,10 @@ const fetchCollectionBalanceDetails = async (
 
 	const responses = await Promise.all(promises);
 	const mergedResponse = responses.reduce<GetTokenBalancesDetailsReturn>(
-		(acc, curr) => {
+		(
+			acc: GetTokenBalancesDetailsReturn,
+			curr: GetTokenBalancesDetailsReturn | null,
+		) => {
 			if (!curr) return acc;
 			return {
 				page: curr.page,
@@ -68,13 +62,12 @@ export const collectionBalanceDetailsOptions = (
 	args: UseCollectionBalanceDetailsArgs,
 	config: SdkConfig,
 ) => {
-	const parsedArgs = useCollectionBalanceDetailsArgsSchema.parse(args);
-	const indexerClient = getIndexerClient(parsedArgs.chainId, config);
+	const indexerClient = getIndexerClient(args.chainId, config);
 
 	return queryOptions({
 		queryKey: [...balanceQueries.collectionBalanceDetails, args, config],
-		queryFn: () => fetchCollectionBalanceDetails(parsedArgs, indexerClient),
-		...args.query,
+		queryFn: () => fetchCollectionBalanceDetails(args, indexerClient),
+		...(args.query || {}),
 	});
 };
 

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 { collectionDetailsQueryOptions } from '../queries/collectionDetails';
 import { useConfig } from './useConfig';
 
 type UseCollectionDetailsPolling = {
 	collectionAddress: string;
 	chainId: number;
+	query?: {
+		enabled?: boolean;
+	};
 };
 
 const INITIAL_POLLING_INTERVAL = 2000; // 2 seconds
@@ -27,7 +30,11 @@ export const collectionDetailsPollingOptions = (
 	config: SdkConfig,
 ) => {
 	return queryOptions({
-		...collectionDetailsOptions(args, config),
+		...collectionDetailsQueryOptions({
+			collectionAddress: args.collectionAddress,
+			chainId: args.chainId,
+			config,
+		}),
 		refetchInterval: (query) => {
 			const data = query.state.data;
 			if (data && isTerminalState(data.status)) {
@@ -49,6 +56,7 @@ export const collectionDetailsPollingOptions = (
 		},
 		refetchOnWindowFocus: false,
 		retry: false,
+		enabled: args.query?.enabled ?? true,
 	});
 };
 

package/src/react/hooks/useComparePrices.tsx

@@ -1,49 +1,46 @@
 import { queryOptions, useQuery } from '@tanstack/react-query';
-import { z } from 'zod';
+import type { Address } from 'viem';
 import type { SdkConfig } from '../../types';
-import { AddressSchema, QueryArgSchema, currencyKeys } from '../_internal';
+import { currencyKeys, type QueryArg } from '../_internal';
 import { useConfig } from './useConfig';
 import { convertPriceToUSD } from './useConvertPriceToUSD';
 
-const UseComparePricesArgsSchema = z.object({
-	chainId: z.number(),
+export interface UseComparePricesArgs {
+	chainId: number;
 	// First price details
-	priceAmountRaw: z.string(),
-	priceCurrencyAddress: AddressSchema,
+	priceAmountRaw: string;
+	priceCurrencyAddress: Address;
 	// Second price details (to compare against)
-	compareToPriceAmountRaw: z.string(),
-	compareToPriceCurrencyAddress: AddressSchema,
-	query: QueryArgSchema,
-});
+	compareToPriceAmountRaw: string;
+	compareToPriceCurrencyAddress: Address;
+	query: QueryArg;
+}
 
-type UseComparePricesArgs = z.input<typeof UseComparePricesArgsSchema>;
-
-export type UseComparePricesReturn = {
+export interface UseComparePricesReturn {
 	percentageDifference: number;
 	percentageDifferenceFormatted: string;
 	status: 'above' | 'same' | 'below';
-};
+}
 
 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,
+				chainId: args.chainId,
+				currencyAddress: args.priceCurrencyAddress,
+				amountRaw: args.priceAmountRaw,
 				query: {},
 			},
 			config,
 		),
 		convertPriceToUSD(
 			{
-				chainId: parsedArgs.chainId,
-				currencyAddress: parsedArgs.compareToPriceCurrencyAddress,
-				amountRaw: parsedArgs.compareToPriceAmountRaw,
+				chainId: args.chainId,
+				currencyAddress: args.compareToPriceCurrencyAddress,
+				amountRaw: args.compareToPriceAmountRaw,
 				query: {},
 			},
 			config,

package/src/react/hooks/useConvertPriceToUSD.tsx

@@ -1,26 +1,18 @@
 import { queryOptions, useQuery } from '@tanstack/react-query';
-import { formatUnits } from 'viem';
-import { z } from 'zod';
+import { type Address, formatUnits } from 'viem';
 import type { SdkConfig } from '../../types';
-import {
-	AddressSchema,
-	QueryArgSchema,
-	currencyKeys,
-	getQueryClient,
-} from '../_internal';
-import { currenciesOptions } from '../queries/marketCurrencies';
+import { type Currency, currencyKeys, getQueryClient } from '../_internal';
+import { marketCurrenciesQueryOptions } from '../queries/marketCurrencies';
 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 interface UseConvertPriceToUSDArgs {
+	chainId: number;
+	currencyAddress: Address;
+	amountRaw: string;
+	query?: {
+		enabled?: boolean;
+	};
+}
 
 export type UseConvertPriceToUSDReturn = {
 	usdAmount: number;
@@ -31,20 +23,16 @@ 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,
-			},
+	const currencies = (await queryClient.fetchQuery(
+		marketCurrenciesQueryOptions({
+			chainId: args.chainId,
 			config,
-		),
-	);
+		}),
+	)) as Currency[];
 	const currencyDetails = currencies.find(
-		(c) =>
-			c.contractAddress.toLowerCase() ===
-			parsedArgs.currencyAddress.toLowerCase(),
+		(c: Currency) =>
+			c.contractAddress.toLowerCase() === args.currencyAddress.toLowerCase(),
 	);
 
 	if (!currencyDetails) {
@@ -52,7 +40,7 @@ export const convertPriceToUSD = async (
 	}
 
 	const amountDecimal = Number(
-		formatUnits(BigInt(parsedArgs.amountRaw), currencyDetails.decimals),
+		formatUnits(BigInt(args.amountRaw), currencyDetails.decimals),
 	);
 	const usdAmount = amountDecimal * currencyDetails.exchangeRate;
 
@@ -68,12 +56,7 @@ export const convertPriceToUSDOptions = (
 ) => {
 	return queryOptions({
 		...args.query,
-		queryKey: [
-			...currencyKeys.conversion,
-			args.chainId,
-			args.currencyAddress,
-			args.amountRaw,
-		],
+		queryKey: [...currencyKeys.conversion, args],
 		queryFn: () => convertPriceToUSD(args, config),
 	});
 };

package/src/react/hooks/useCountListingsForCollectible.tsx

@@ -1,64 +1,75 @@
-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';
-import { countListingsForCollectibleArgsSchema } from '../_internal/api/zod-schema';
+	type CountListingsForCollectibleQueryOptions,
+	countListingsForCollectibleQueryOptions,
+	type FetchCountListingsForCollectibleParams,
+} from '../queries/countListingsForCollectible';
 import { useConfig } from './useConfig';
 
-const UseCountListingsForCollectibleArgsSchema =
-	countListingsForCollectibleArgsSchema
-		.omit({
-			contractAddress: true,
-			tokenId: true,
-		})
-		.extend({
-			collectionAddress: AddressSchema,
-			collectibleId: z.string(),
-			chainId: z.number(),
-			query: QueryArgSchema,
-		});
-
-export type UseCountListingsForCollectibleArgs = z.infer<
-	typeof UseCountListingsForCollectibleArgsSchema
+export type UseCountListingsForCollectibleParams = Optional<
+	CountListingsForCollectibleQueryOptions,
+	'config'
 >;
 
-export type UseCountListingsForCollectibleReturn = Awaited<
-	ReturnType<typeof fetchCountListingsForCollectible>
->;
+/**
+ * Hook to get the count of listings for a specific collectible
+ *
+ * Counts the number of active listings for a given collectible in the marketplace.
+ * Useful for displaying listing counts in UI components.
+ *
+ * @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.collectibleId - The specific collectible/token ID
+ * @param params.filter - Optional filter criteria for listings
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing the count of listings
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data: listingCount, isLoading } = useCountListingsForCollectible({
+ *   chainId: 137,
+ *   collectionAddress: '0x...',
+ *   collectibleId: '123'
+ * })
+ * ```
+ *
+ * @example
+ * With filter:
+ * ```typescript
+ * const { data: filteredCount } = useCountListingsForCollectible({
+ *   chainId: 137,
+ *   collectionAddress: '0x...',
+ *   collectibleId: '123',
+ *   filter: { priceRange: { min: '1000000000000000000' } }
+ * })
+ * ```
+ */
+export function useCountListingsForCollectible(
+	params: UseCountListingsForCollectibleParams,
+) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
 
-const fetchCountListingsForCollectible = async (
-	args: UseCountListingsForCollectibleArgs,
-	config: SdkConfig,
-) => {
-	const parsedArgs = UseCountListingsForCollectibleArgsSchema.parse(args);
-	const marketplaceClient = getMarketplaceClient(config);
-	const { chainId, collectionAddress, collectibleId } = parsedArgs;
-	return marketplaceClient.getCountOfListingsForCollectible({
-		chainId: String(chainId),
-		contractAddress: collectionAddress,
-		tokenId: collectibleId,
+	const queryOptions = countListingsForCollectibleQueryOptions({
+		config,
+		...rest,
 	});
-};
 
-export const countListingsForCollectibleOptions = (
-	args: UseCountListingsForCollectibleArgs,
-	config: SdkConfig,
-) => {
-	return queryOptions({
-		...args.query,
-		queryKey: [...collectableKeys.listingsCount, args, config],
-		queryFn: () => fetchCountListingsForCollectible(args, config),
+	return useQuery({
+		...queryOptions,
 	});
-};
+}
+
+export { countListingsForCollectibleQueryOptions };
 
-export const useCountListingsForCollectible = (
-	args: UseCountListingsForCollectibleArgs,
-) => {
-	const config = useConfig();
-	return useQuery(countListingsForCollectibleOptions(args, config));
+export type {
+	FetchCountListingsForCollectibleParams,
+	CountListingsForCollectibleQueryOptions,
 };