@0xsequence/marketplace-sdk 0.8.11 → 0.9.0

package/src/react/hooks/__tests__/useRoyalty.test.tsx

@@ -25,27 +25,4 @@ describe('useRoyaltyPercentage', () => {
 			}
 		`);
 	});
-
-	it('should handle invalid args', async () => {
-		const invalidArgs = {
-			collectionAddress: 'invalid-collection-address' as `0x${string}`,
-			chainId: 'invalid-chain-id',
-			collectibleId: '1',
-		};
-
-		// @ts-expect-error - This will fail Zod validation
-		const { result } = renderHook(() => useRoyalty(invalidArgs));
-
-		expect(result.current.isLoading).toBe(true);
-
-		await waitFor(
-			() => {
-				expect(result.current.isLoading).toBe(false);
-			},
-			{ timeout: 1000000 },
-		);
-
-		expect(result.current.data).toBeNull();
-		expect(result.current.error).toBeDefined();
-	});
 });

package/src/react/hooks/index.ts

@@ -1,40 +1,50 @@
 export * from './useAutoSelectFeeOption';
 export * from './useBalanceOfCollectible';
-export * from './useCountOfCollectables';
+export * from './useCancelOrder';
+export * from './useCheckoutOptionsSalesContract';
+export * from './useCheckoutOptionsSalesContract';
 export * from './useCollectible';
 export * from './useCollection';
 export * from './useCollectionBalanceDetails';
+export * from './useCollectionDetails';
+export * from './useCollectionDetailsPolling';
 export * from './useComparePrices';
 export * from './useConfig';
 export * from './useConvertPriceToUSD';
-export * from './useMarketCurrencies';
+export * from './useCountListingsForCollectible';
+export * from './useCountOfCollectables';
+export * from './useCountOffersForCollectible';
+export * from './useCountOfPrimarySaleItems';
 export * from './useCurrency';
-export * from './useFilters';
+export * from './useERC721SaleMintedTokens';
 export * from './useFilterState';
+export * from './useFilters';
 export * from './useFloorOrder';
+export * from './useGenerateCancelTransaction';
+export * from './useGenerateListingTransaction';
+export * from './useGenerateOfferTransaction';
+export * from './useGenerateSellTransaction';
+export * from './useGetTokenRanges';
+export * from './useGetTokenSuppliesMap';
 export * from './useHighestOffer';
 export * from './useInventory';
+export * from './useList721ShopCardData';
+export * from './useList1155ShopCardData';
 export * from './useListBalances';
 export * from './useListCollectibleActivities';
 export * from './useListCollectibles';
 export * from './useListCollectiblesPaginated';
 export * from './useListCollectionActivities';
-export * from './useListOffersForCollectible';
-export * from './useCountOffersForCollectible';
+export * from './useListCollections';
 export * from './useListListingsForCollectible';
-export * from './useCountListingsForCollectible';
+export * from './useListMarketCardData';
+export * from './useListOffersForCollectible';
+export * from './useListPrimarySaleItems';
+export * from './useListShopCardData';
+export * from './useListTokenMetadata';
 export * from './useLowestListing';
+export * from './useMarketCurrencies';
 export * from './useMarketplaceConfig';
 export * from './useRoyalty';
-export * from './useGenerateListingTransaction';
-export * from './useGenerateOfferTransaction';
-export * from './useGenerateSellTransaction';
-export * from './useGenerateCancelTransaction';
+export * from './useShopCollectibleSaleData';
 export * from './useTransferTokens';
-export * from './useCheckoutOptions';
-export * from './useListCollections';
-export * from './useCancelOrder';
-export * from './useCollectionDetails';
-export * from './useCollectionDetailsPolling';
-export * from './useListTokenMetadata';
-export * from './useGetTokenSuppliesMap';

package/src/react/hooks/options/index.ts

@@ -1,2 +1 @@
-export { fetchCollection, collectionOptions } from './collectionOptions';
 export * from '../../queries/marketplaceConfig';

package/src/react/hooks/useAutoSelectFeeOption.tsx

@@ -1,8 +1,8 @@
 'use client';
-import { type Address, zeroAddress } from 'viem';
 
 import { useChain } from '@0xsequence/connect';
 import { useCallback, useEffect } from 'react';
+import { type Address, zeroAddress } from 'viem';
 import { useAccount } from 'wagmi';
 import type { FeeOption } from '../../types/waas-types';
 import { useCollectionBalanceDetails } from './useCollectionBalanceDetails';

package/src/react/hooks/useBalanceOfCollectible.tsx

@@ -1,8 +1,8 @@
 import { useQuery } from '@tanstack/react-query';
 import { ContractType } from '../_internal';
 import {
-	type UseBalanceOfCollectibleArgs,
 	balanceOfCollectibleOptions,
+	type UseBalanceOfCollectibleArgs,
 } from '../queries/balanceOfCollectible';
 import { useConfig } from './useConfig';
 import { useMarketplaceConfig } from './useMarketplaceConfig';
@@ -31,14 +31,18 @@ export function useBalanceOfCollectible(args: UseBalanceOfCollectibleArgs) {
 	const config = useConfig();
 	const { data: marketplaceConfig } = useMarketplaceConfig();
 
-	const isLaos721 =
-		marketplaceConfig?.market.collections.find(
-			(collection) => collection.itemsAddress === args.collectionAddress,
-		)?.contractType === ContractType.LAOSERC721;
-
-	if (isLaos721) {
-		args.isLaos721 = true;
-	}
+	const collection = marketplaceConfig?.market.collections.find(
+		(collection) => collection.itemsAddress === args.collectionAddress,
+	);
+	const isLaos721 = collection?.contractType === ContractType.LAOS_ERC_721;
 
-	return useQuery(balanceOfCollectibleOptions(args, config));
+	return useQuery(
+		balanceOfCollectibleOptions(
+			{
+				...args,
+				isLaos721,
+			},
+			config,
+		),
+	);
 }

package/src/react/hooks/useCancelTransactionSteps.tsx

@@ -4,11 +4,12 @@ import {
 	WalletInstanceNotFoundError,
 } from '../../utils/_internal/error/transaction';
 import {
+	ExecuteType,
+	getMarketplaceClient,
+	getQueryClient,
 	type MarketplaceKind,
 	type Step,
 	StepType,
-	getMarketplaceClient,
-	getQueryClient,
 } from '../_internal';
 import type {
 	SignatureStep,
@@ -46,7 +47,7 @@ export const useCancelTransactionSteps = ({
 	const { wallet, isLoading, isError } = useWallet();
 	const walletIsInitialized = wallet && !isLoading && !isError;
 	const sdkConfig = useConfig();
-	const marketplaceClient = getMarketplaceClient(chainId, sdkConfig);
+	const marketplaceClient = getMarketplaceClient(sdkConfig);
 	const { generateCancelTransactionAsync } = useGenerateCancelTransaction({
 		chainId,
 	});
@@ -95,6 +96,7 @@ export const useCancelTransactionSteps = ({
 			}
 
 			const steps = await generateCancelTransactionAsync({
+				chainId,
 				collectionAddress,
 				maker: address,
 				marketplace,
@@ -230,10 +232,12 @@ export const useCancelTransactionSteps = ({
 		);
 
 		const result = await marketplaceClient.execute({
+			chainId: String(chainId),
 			signature: signature as string,
 			method: signatureStep.post?.method as string,
 			endpoint: signatureStep.post?.endpoint as string,
 			body: signatureStep.post?.body,
+			executeType: ExecuteType.order,
 		});
 
 		return result.orderId;

package/src/react/hooks/useCheckoutOptionsSalesContract.tsx

@@ -0,0 +1,67 @@
+import { queryOptions, skipToken, useQuery } from '@tanstack/react-query';
+import type { Hex } from 'viem';
+import { useAccount } from 'wagmi';
+import type { SdkConfig } from '../../types';
+import {
+	type CheckoutOptionsSalesContractArgs,
+	getMarketplaceClient,
+} from '../_internal';
+import { useConfig } from './useConfig';
+
+type UseCheckoutOptionsSalesContractArgs = Omit<
+	CheckoutOptionsSalesContractArgs,
+	'wallet' | 'chainId'
+> & { chainId: number };
+
+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,
+	});
+};
+
+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,
+						),
+	});
+};
+
+export const useCheckoutOptionsSalesContract = (
+	args: UseCheckoutOptionsSalesContractArgs | typeof skipToken,
+) => {
+	const { address } = useAccount();
+	const config = useConfig();
+	return useQuery(
+		checkoutOptionsSalesContractOptions(
+			skipToken === args ? skipToken : { ...args, wallet: address },
+			config,
+		),
+	);
+};

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,
 	});
 };