@0xsequence/marketplace-sdk 0.8.12 → 0.9.0

package/src/react/hooks/useListListingsForCollectible.tsx

@@ -1,61 +1,101 @@
-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 {
-	type ListListingsForCollectibleArgs,
-	collectableKeys,
-	getMarketplaceClient,
-} from '../_internal';
-import { listListingsForCollectibleArgsSchema } from '../_internal/api/zod-schema';
+	type FetchListListingsForCollectibleParams,
+	type fetchListListingsForCollectible,
+	type ListListingsForCollectibleQueryOptions,
+	listListingsForCollectibleQueryOptions,
+} from '../queries/listListingsForCollectible';
 import { useConfig } from './useConfig';
 
-const UseListListingsForCollectibleArgsSchema =
-	listListingsForCollectibleArgsSchema
-		.extend({
-			chainId: z.number(),
-			collectionAddress: z.string(),
-			collectibleId: z.string(),
-		})
-		.omit({ contractAddress: true, tokenId: true });
-
-type UseListListingsForCollectibleArgs = z.infer<
-	typeof UseListListingsForCollectibleArgsSchema
+export type UseListListingsForCollectibleParams = Optional<
+	ListListingsForCollectibleQueryOptions,
+	'config'
 >;
 
-export type UseListListingsForCollectibleReturn = Awaited<
-	ReturnType<typeof fetchListListingsForCollectible>
->;
+/**
+ * Hook to fetch listings for a specific collectible
+ *
+ * Fetches active listings (sales) for a specific token from the marketplace
+ * with support for filtering and pagination.
+ *
+ * @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 token ID to fetch listings for
+ * @param params.filter - Optional filtering parameters (marketplace, currencies, etc.)
+ * @param params.page - Optional pagination parameters
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing listings data for the collectible
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data, isLoading } = useListListingsForCollectible({
+ *   chainId: 137,
+ *   collectionAddress: '0x...',
+ *   collectibleId: '123'
+ * })
+ * ```
+ *
+ * @example
+ * With pagination:
+ * ```typescript
+ * const { data } = useListListingsForCollectible({
+ *   chainId: 1,
+ *   collectionAddress: '0x...',
+ *   collectibleId: '456',
+ *   page: {
+ *     page: 2,
+ *     pageSize: 20
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * With filtering:
+ * ```typescript
+ * const { data } = useListListingsForCollectible({
+ *   chainId: 137,
+ *   collectionAddress: '0x...',
+ *   collectibleId: '789',
+ *   filter: {
+ *     marketplace: [MarketplaceKind.sequence_marketplace_v2],
+ *     currencies: ['0x...'] // Specific currency addresses
+ *   }
+ * })
+ * ```
+ */
+export function useListListingsForCollectible(
+	params: UseListListingsForCollectibleParams,
+) {
+	const defaultConfig = useConfig();
 
-const fetchListListingsForCollectible = async (
-	config: SdkConfig,
-	args: UseListListingsForCollectibleArgs,
-) => {
-	const arg = {
-		chainId: String(args.chainId),
-		contractAddress: args.collectionAddress,
-		tokenId: args.collectibleId,
-		filter: args.filter,
-		page: args.page,
-	} satisfies ListListingsForCollectibleArgs;
-
-	const marketplaceClient = getMarketplaceClient(config);
-	return marketplaceClient.listCollectibleListings(arg);
-};
+	const { config = defaultConfig, ...rest } = params;
 
-export const listListingsForCollectibleOptions = (
-	args: UseListListingsForCollectibleArgs,
-	config: SdkConfig,
-) => {
-	return queryOptions({
-		queryKey: [...collectableKeys.listings, args, config],
-		queryFn: () => fetchListListingsForCollectible(config, args),
+	const queryOptions = listListingsForCollectibleQueryOptions({
+		config,
+		...rest,
 	});
-};
 
-export const useListListingsForCollectible = (
-	args: UseListListingsForCollectibleArgs,
-) => {
-	const config = useConfig();
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { listListingsForCollectibleQueryOptions };
 
-	return useQuery(listListingsForCollectibleOptions(args, config));
+export type {
+	FetchListListingsForCollectibleParams,
+	ListListingsForCollectibleQueryOptions,
 };
+
+// Legacy exports for backward compatibility during migration
+export type UseListListingsForCollectibleArgs =
+	UseListListingsForCollectibleParams;
+export type UseListListingsForCollectibleReturn = Awaited<
+	ReturnType<typeof fetchListListingsForCollectible>
+>;

package/src/react/hooks/useListMarketCardData.tsx

@@ -2,7 +2,6 @@ import { useMemo } from 'react';
 
 import type { Address } from 'viem';
 import { useAccount } from 'wagmi';
-import { OrderSide } from '../../types';
 import type {
 	CollectibleCardAction,
 	CollectibleOrder,
@@ -11,6 +10,7 @@ import type {
 	OrderbookKind,
 	PropertyFilter,
 } from '../../types';
+import { OrderSide } from '../../types';
 import type { MarketCollectibleCardProps } from '../ui/components/marketplace-collectible-card/types';
 import { useSellModal } from '../ui/modals/SellModal';
 import { useCollectionBalanceDetails } from './useCollectionBalanceDetails';

package/src/react/hooks/useListOffersForCollectible.tsx

@@ -1,25 +1,20 @@
 import { queryOptions, useQuery } from '@tanstack/react-query';
-import { z } from 'zod';
 import type { SdkConfig } from '../../types';
 import {
-	type ListOffersForCollectibleArgs,
 	collectableKeys,
 	getMarketplaceClient,
+	type ListOffersForCollectibleArgs,
 } from '../_internal';
-import { listOffersForCollectibleArgsSchema } from '../_internal/api/zod-schema';
+import type { OrderFilter, Page } from '../_internal/api/marketplace.gen';
 import { useConfig } from './useConfig';
 
-const UseListOffersForCollectibleArgsSchema = listOffersForCollectibleArgsSchema
-	.extend({
-		chainId: z.number(),
-		collectionAddress: z.string(),
-		collectibleId: z.string(),
-	})
-	.omit({ contractAddress: true, tokenId: true });
-
-type UseListOffersForCollectibleArgs = z.infer<
-	typeof UseListOffersForCollectibleArgsSchema
->;
+interface UseListOffersForCollectibleArgs {
+	chainId: number;
+	collectionAddress: string;
+	collectibleId: string;
+	filter?: OrderFilter;
+	page?: Page;
+}
 
 export type UseListOffersForCollectibleReturn = Awaited<
 	ReturnType<typeof fetchListOffersForCollectible>

package/src/react/hooks/useListPrimarySaleItems.ts

@@ -1,19 +1,29 @@
-import { queryOptions, useQuery } from '@tanstack/react-query';
+import { useInfiniteQuery, useQuery } from '@tanstack/react-query';
+import type { Address } from 'viem';
 import type { SdkConfig } from '../../types';
 import {
-	type ListPrimarySaleItemsArgs,
 	getMarketplaceClient,
+	type ListPrimarySaleItemsArgs,
+	type ListPrimarySaleItemsReturn,
+	type Page,
+	type PrimarySaleItemsFilter,
 } from '../_internal';
 import { useConfig } from './useConfig';
 
-type UseListPrimarySaleItemsArgs = Omit<ListPrimarySaleItemsArgs, 'chainId'> & {
+interface UseListPrimarySaleItemsArgs {
 	chainId: number;
-};
+	primarySaleContractAddress: Address | undefined;
+	filter?: PrimarySaleItemsFilter;
+	page?: Page;
+	query?: {
+		enabled?: boolean;
+	};
+}
 
 const fetchListPrimarySaleItems = async (
+	args: ListPrimarySaleItemsArgs,
 	config: SdkConfig,
-	args: UseListPrimarySaleItemsArgs,
-) => {
+): Promise<ListPrimarySaleItemsReturn> => {
 	const arg = {
 		chainId: String(args.chainId),
 		primarySaleContractAddress: args.primarySaleContractAddress,
@@ -25,18 +35,68 @@ const fetchListPrimarySaleItems = async (
 	return marketplaceClient.listPrimarySaleItems(arg);
 };
 
-export const listPrimarySaleItemsOptions = (
+const listPrimarySaleItemsOptions = (
 	args: UseListPrimarySaleItemsArgs,
 	config: SdkConfig,
 ) => {
-	return queryOptions({
-		queryKey: ['primarySaleItems', args, config],
-		queryFn: () => fetchListPrimarySaleItems(config, args),
-	});
+	const primarySaleContractAddress = args.primarySaleContractAddress as Address;
+	return {
+		queryKey: ['listPrimarySaleItems', args],
+		queryFn: async ({ pageParam }: { pageParam: Page }) => {
+			return fetchListPrimarySaleItems(
+				{
+					chainId: String(args.chainId),
+					primarySaleContractAddress,
+					filter: args.filter,
+					page: pageParam,
+				},
+				config,
+			);
+		},
+		initialPageParam: { page: 1, pageSize: 30 } as Page,
+		getNextPageParam: (lastPage: ListPrimarySaleItemsReturn) =>
+			lastPage.page?.more
+				? {
+						page: lastPage.page?.page || 1,
+						pageSize: lastPage.page?.pageSize || 30,
+					}
+				: undefined,
+		...args.query,
+		enabled: !!primarySaleContractAddress && args.query?.enabled !== false,
+	};
 };
 
 export const useListPrimarySaleItems = (args: UseListPrimarySaleItemsArgs) => {
 	const config = useConfig();
+	return useInfiniteQuery(listPrimarySaleItemsOptions(args, config));
+};
+
+interface UseGetCountOfPrimarySaleItemsArgs {
+	chainId: number;
+	primarySaleContractAddress: Address | undefined;
+	filter?: PrimarySaleItemsFilter;
+	query?: {
+		enabled?: boolean;
+	};
+}
+
+export const useGetCountOfPrimarySaleItems = (
+	args: UseGetCountOfPrimarySaleItemsArgs,
+) => {
+	const config = useConfig();
+
+	return useQuery({
+		queryKey: ['getCountOfPrimarySaleItems', args],
+		queryFn: async () => {
+			const marketplaceClient = getMarketplaceClient(config);
 
-	return useQuery(listPrimarySaleItemsOptions(args, config));
+			return marketplaceClient.getCountOfPrimarySaleItems({
+				chainId: String(args.chainId),
+				primarySaleContractAddress: args.primarySaleContractAddress || '',
+				filter: args.filter,
+			});
+		},
+		...args.query,
+		enabled: !!args.primarySaleContractAddress && args.query?.enabled !== false,
+	});
 };

package/src/react/hooks/useListShopCardData.tsx

@@ -0,0 +1,70 @@
+import type { Address } from 'viem';
+import { ContractType } from '../_internal';
+import { useList721ShopCardData } from './useList721ShopCardData';
+import { useList1155ShopCardData } from './useList1155ShopCardData';
+
+interface UseListShopCardDataProps {
+	tokenIds: string[];
+	chainId: number;
+	contractAddress: Address;
+	salesContractAddress: Address;
+	contractType: ContractType | undefined;
+	enabled?: boolean;
+}
+
+export function useListShopCardData({
+	tokenIds,
+	chainId,
+	contractAddress,
+	salesContractAddress,
+	contractType,
+	enabled = true,
+}: UseListShopCardDataProps) {
+	const shouldUse721 = contractType === ContractType.ERC721;
+	const shouldUse1155 = contractType === ContractType.ERC1155;
+
+	const erc721Data = useList721ShopCardData({
+		tokenIds,
+		chainId,
+		contractAddress,
+		salesContractAddress,
+		enabled: enabled && shouldUse721,
+	});
+
+	const erc1155Data = useList1155ShopCardData({
+		tokenIds,
+		chainId,
+		contractAddress,
+		salesContractAddress,
+		enabled: enabled && shouldUse1155,
+	});
+
+	if (shouldUse721) {
+		return erc721Data;
+	}
+
+	if (shouldUse1155) {
+		// Map ERC1155 data to match ERC721 structure
+		return {
+			collectibleCards: erc1155Data.collectibleCards,
+			isLoading: erc1155Data.isLoading,
+			saleDetailsError: erc1155Data.tokenSaleDetailsError,
+			primarySaleItemsError: erc1155Data.tokenMetadataError,
+			saleDetails: undefined,
+			primarySaleItems: undefined,
+			salePrice: erc1155Data.collectibleCards[0]?.salePrice,
+		};
+	}
+
+	// Return a default state when contract type is not determined yet
+	return {
+		collectibleCards: [],
+		isLoading: !contractType,
+		collectionDetailsError: null,
+		saleDetailsError: null,
+		primarySaleItemsError: null,
+		saleDetails: undefined,
+		primarySaleItems: undefined,
+		salePrice: undefined,
+	};
+}

package/src/react/hooks/useListTokenMetadata.tsx

@@ -0,0 +1,73 @@
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import type { Optional } from '../_internal';
+import {
+	type FetchListTokenMetadataParams,
+	type ListTokenMetadataQueryOptions,
+	listTokenMetadataQueryOptions,
+} from '../queries/listTokenMetadata';
+import { useConfig } from './useConfig';
+
+export type UseListTokenMetadataParams = Optional<
+	ListTokenMetadataQueryOptions,
+	'config'
+>;
+
+/**
+ * Hook to fetch metadata for multiple tokens
+ *
+ * Retrieves metadata for a batch of tokens from a specific contract using the metadata API.
+ * This hook is optimized for fetching multiple token metadata in a single request.
+ *
+ * @param params - Configuration parameters
+ * @param params.chainId - The chain ID (must be number, e.g., 1 for Ethereum, 137 for Polygon)
+ * @param params.contractAddress - The contract address containing the tokens
+ * @param params.tokenIds - Array of token IDs to fetch metadata for
+ * @param params.config - Optional SDK configuration (defaults from context)
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing an array of token metadata
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data: metadata, isLoading } = useListTokenMetadata({
+ *   chainId: 137,
+ *   contractAddress: '0x...',
+ *   tokenIds: ['1', '2', '3']
+ * })
+ * ```
+ *
+ * @example
+ * With query options:
+ * ```typescript
+ * const { data: metadata } = useListTokenMetadata({
+ *   chainId: 1,
+ *   contractAddress: '0x...',
+ *   tokenIds: selectedTokenIds,
+ *   query: {
+ *     enabled: selectedTokenIds.length > 0,
+ *     staleTime: 10 * 60 * 1000 // 10 minutes
+ *   }
+ * })
+ * ```
+ */
+export function useListTokenMetadata(params: UseListTokenMetadataParams) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = listTokenMetadataQueryOptions({
+		config,
+		...rest,
+	});
+
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { listTokenMetadataQueryOptions };
+
+export type { FetchListTokenMetadataParams, ListTokenMetadataQueryOptions };

package/src/react/hooks/useLowestListing.tsx

@@ -1,8 +1,72 @@
+'use client';
+
 import { useQuery } from '@tanstack/react-query';
-import { type UseLowestListingArgs, lowestListingOptions } from '../queries';
+import type { Optional } from '../_internal';
+import {
+	type FetchLowestListingParams,
+	type LowestListingQueryOptions,
+	lowestListingQueryOptions,
+} from '../queries/lowestListing';
 import { useConfig } from './useConfig';
 
-export function useLowestListing(args: UseLowestListingArgs) {
-	const config = useConfig();
-	return useQuery(lowestListingOptions(args, config));
+export type UseLowestListingParams = Optional<
+	LowestListingQueryOptions,
+	'config'
+>;
+
+/**
+ * Hook to fetch the lowest listing for a collectible
+ *
+ * Retrieves the lowest priced listing currently available for a specific token
+ * in a 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.tokenId - The token ID within the collection
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing the lowest listing data or null if no listings exist
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data, isLoading } = useLowestListing({
+ *   chainId: 137,
+ *   collectionAddress: '0x...',
+ *   tokenId: '1'
+ * })
+ * ```
+ *
+ * @example
+ * With custom query options:
+ * ```typescript
+ * const { data, isLoading } = useLowestListing({
+ *   chainId: 1,
+ *   collectionAddress: '0x...',
+ *   tokenId: '42',
+ *   query: {
+ *     refetchInterval: 15000,
+ *     enabled: hasTokenId
+ *   }
+ * })
+ * ```
+ */
+export function useLowestListing(params: UseLowestListingParams) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = lowestListingQueryOptions({
+		config,
+		...rest,
+	});
+
+	return useQuery({
+		...queryOptions,
+	});
 }
+
+export { lowestListingQueryOptions };
+
+export type { FetchLowestListingParams, LowestListingQueryOptions };

package/src/react/hooks/useMarketCurrencies.tsx

@@ -1,8 +1,65 @@
+'use client';
+
 import { useQuery } from '@tanstack/react-query';
-import { type UseMarketCurrenciesArgs, currenciesOptions } from '../queries';
+import type { Optional } from '../_internal';
+import {
+	type FetchMarketCurrenciesParams,
+	type MarketCurrenciesQueryOptions,
+	marketCurrenciesQueryOptions,
+} from '../queries/marketCurrencies';
 import { useConfig } from './useConfig';
 
-export const useMarketCurrencies = (args: UseMarketCurrenciesArgs) => {
-	const config = useConfig();
-	return useQuery(currenciesOptions(args, config));
-};
+export type UseMarketCurrenciesParams = Optional<
+	MarketCurrenciesQueryOptions,
+	'config'
+>;
+
+/**
+ * Hook to fetch supported currencies for a marketplace
+ *
+ * Retrieves the list of currencies supported by the marketplace for a specific chain.
+ * Can optionally filter to exclude native currency or filter by collection.
+ *
+ * @param params - Configuration parameters
+ * @param params.chainId - The chain ID (must be number, e.g., 1 for Ethereum, 137 for Polygon)
+ * @param params.includeNativeCurrency - Whether to include native currency (default: true)
+ * @param params.collectionAddress - Optional collection address to filter currencies
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing supported currencies
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data, isLoading } = useMarketCurrencies({
+ *   chainId: 137
+ * })
+ * ```
+ *
+ * @example
+ * Exclude native currency:
+ * ```typescript
+ * const { data, isLoading } = useMarketCurrencies({
+ *   chainId: 1,
+ *   includeNativeCurrency: false
+ * })
+ * ```
+ */
+export function useMarketCurrencies(params: UseMarketCurrenciesParams) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = marketCurrenciesQueryOptions({
+		config,
+		...rest,
+	});
+
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { marketCurrenciesQueryOptions };
+
+export type { FetchMarketCurrenciesParams, MarketCurrenciesQueryOptions };

package/src/react/hooks/useRoyalty.tsx

@@ -1,18 +1,62 @@
+'use client';
+
+import type { Address } from 'viem';
 import { useReadContract } from 'wagmi';
-import { z } from 'zod';
 import { EIP2981_ABI } from '../../utils';
-import { AddressSchema, QueryArgSchema, collectableKeys } from '../_internal';
-
-const UseRoyaltySchema = z.object({
-	chainId: z.number(),
-	collectionAddress: AddressSchema,
-	collectibleId: z.string(),
-	query: QueryArgSchema.optional(),
-});
+import type { QueryArg } from '../_internal';
+import { collectableKeys } from '../_internal';
 
-type UseRoyaltyArgs = z.infer<typeof UseRoyaltySchema>;
+export interface UseRoyaltyArgs {
+	chainId: number;
+	collectionAddress: Address;
+	collectibleId: string;
+	query?: QueryArg;
+}
 
-export const useRoyalty = (args: UseRoyaltyArgs) => {
+/**
+ * Hook to fetch royalty information for a collectible
+ *
+ * Reads royalty information from the blockchain using the EIP-2981 standard.
+ * This hook queries the contract directly to get royalty percentage and recipient
+ * address for a specific token.
+ *
+ * @param args - Configuration parameters
+ * @param args.chainId - The chain ID (must be number, e.g., 1 for Ethereum, 137 for Polygon)
+ * @param args.collectionAddress - The collection contract address
+ * @param args.collectibleId - The token ID within the collection
+ * @param args.query - Optional React Query configuration
+ *
+ * @returns Query result containing royalty information (percentage and recipient) or null
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data, isLoading } = useRoyalty({
+ *   chainId: 137,
+ *   collectionAddress: '0x...',
+ *   collectibleId: '1'
+ * })
+ *
+ * if (data) {
+ *   console.log('Royalty:', data.percentage, 'Recipient:', data.recipient)
+ * }
+ * ```
+ *
+ * @example
+ * With custom query options:
+ * ```typescript
+ * const { data, isLoading } = useRoyalty({
+ *   chainId: 1,
+ *   collectionAddress: '0x...',
+ *   collectibleId: '42',
+ *   query: {
+ *     refetchInterval: 60000,
+ *     enabled: hasTokenId
+ *   }
+ * })
+ * ```
+ */
+export function useRoyalty(args: UseRoyaltyArgs) {
 	const { chainId, collectionAddress, collectibleId, query } = args;
 	const scopeKey = `${collectableKeys.royaltyPercentage.join('.')}-${chainId}-${collectionAddress}-${collectibleId}`;
 
@@ -31,7 +75,7 @@ export const useRoyalty = (args: UseRoyaltyArgs) => {
 		recipient && percentage
 			? {
 					percentage,
-					recipient,
+					recipient: recipient as Address,
 				}
 			: null;
 
@@ -39,4 +83,4 @@ export const useRoyalty = (args: UseRoyaltyArgs) => {
 		...contractResult,
 		data: formattedData,
 	};
-};
+}