@0xsequence/marketplace-sdk 0.8.12 → 0.10.0

package/src/react/hooks/useListCollectionActivities.tsx

@@ -1,59 +1,93 @@
-import { queryOptions, useQuery } from '@tanstack/react-query';
-import type { z } from 'zod';
-import type { SdkConfig } from '../../types';
-import { getMarketplaceClient } from '../_internal';
-import { collectionKeys } from '../_internal/api';
-import type {
-	getListCollectionActivitiesArgsSchema,
-	getListCollectionActivitiesReturnSchema,
-} from '../_internal/api/zod-schema';
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import type { Optional } from '../_internal';
+import {
+	type FetchListCollectionActivitiesParams,
+	type fetchListCollectionActivities,
+	type ListCollectionActivitiesQueryOptions,
+	listCollectionActivitiesQueryOptions,
+} from '../queries/listCollectionActivities';
 import { useConfig } from './useConfig';
 
-export type UseListCollectionActivitiesArgs = z.infer<
-	typeof getListCollectionActivitiesArgsSchema
+export type UseListCollectionActivitiesParams = Optional<
+	ListCollectionActivitiesQueryOptions,
+	'config'
 >;
 
-export type UseListCollectionActivitiesReturn = z.infer<
-	typeof getListCollectionActivitiesReturnSchema
->;
+/**
+ * Hook to fetch a list of activities for an entire collection
+ *
+ * Fetches activities (transfers, sales, offers, etc.) for all tokens
+ * in a collection from the marketplace with support for pagination and sorting.
+ *
+ * @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.page - Page number to fetch (default: 1)
+ * @param params.pageSize - Number of activities per page (default: 10)
+ * @param params.sort - Sort order for activities
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing activities data for the collection
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data, isLoading } = useListCollectionActivities({
+ *   chainId: 137,
+ *   collectionAddress: '0x...'
+ * })
+ * ```
+ *
+ * @example
+ * With pagination:
+ * ```typescript
+ * const { data } = useListCollectionActivities({
+ *   chainId: 1,
+ *   collectionAddress: '0x...',
+ *   page: 2,
+ *   pageSize: 20
+ * })
+ * ```
+ *
+ * @example
+ * With sorting:
+ * ```typescript
+ * const { data } = useListCollectionActivities({
+ *   chainId: 137,
+ *   collectionAddress: '0x...',
+ *   sort: [{ column: 'createdAt', order: SortOrder.DESC }],
+ *   pageSize: 50
+ * })
+ * ```
+ */
+export function useListCollectionActivities(
+	params: UseListCollectionActivitiesParams,
+) {
+	const defaultConfig = useConfig();
 
-const fetchListCollectionActivities = async (
-	args: UseListCollectionActivitiesArgs,
-	config: SdkConfig,
-) => {
-	const marketplaceClient = getMarketplaceClient(config);
-	return marketplaceClient
-		.listCollectionActivities({
-			chainId: String(args.chainId),
-			contractAddress: args.collectionAddress,
-			page: args.query?.enabled
-				? {
-						page: args.query.page ?? 1,
-						pageSize: args.query.pageSize ?? 10,
-						sort: args.query.sort,
-					}
-				: undefined,
-		})
-		.then((data) => ({
-			activities: data.activities,
-			page: data.page,
-		}));
-};
+	const { config = defaultConfig, ...rest } = params;
 
-export const listCollectionActivitiesOptions = (
-	args: UseListCollectionActivitiesArgs,
-	config: SdkConfig,
-) => {
-	return queryOptions({
-		queryKey: [...collectionKeys.collectionActivities, args, config],
-		queryFn: () => fetchListCollectionActivities(args, config),
-		enabled: args.query?.enabled ?? true,
+	const queryOptions = listCollectionActivitiesQueryOptions({
+		config,
+		...rest,
 	});
-};
 
-export const useListCollectionActivities = (
-	args: UseListCollectionActivitiesArgs,
-) => {
-	const config = useConfig();
-	return useQuery(listCollectionActivitiesOptions(args, config));
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { listCollectionActivitiesQueryOptions };
+
+export type {
+	FetchListCollectionActivitiesParams,
+	ListCollectionActivitiesQueryOptions,
 };
+
+// Legacy exports for backward compatibility during migration
+export type UseListCollectionActivitiesArgs = UseListCollectionActivitiesParams;
+export type UseListCollectionActivitiesReturn = Awaited<
+	ReturnType<typeof fetchListCollectionActivities>
+>;

package/src/react/hooks/useListCollections.tsx

@@ -1,26 +1,80 @@
+'use client';
+
 import { useQuery } from '@tanstack/react-query';
-import type { MarketplaceType } from '../../types/types';
-import { listCollectionsOptions } from '../queries/listCollections';
+import type { Optional } from '../_internal';
+import {
+	type FetchListCollectionsParams,
+	type ListCollectionsQueryOptions,
+	listCollectionsQueryOptions,
+} from '../queries/listCollections';
 import { useConfig } from './useConfig';
 import { useMarketplaceConfig } from './useMarketplaceConfig';
 
-type UseListCollectionsArgs = {
-	marketplaceType?: MarketplaceType;
-	query?: {
-		enabled?: boolean;
-	};
-};
+export type UseListCollectionsParams = Optional<
+	ListCollectionsQueryOptions,
+	'config' | 'marketplaceConfig'
+>;
 
-export const useListCollections = (args: UseListCollectionsArgs = {}) => {
-	const config = useConfig();
+/**
+ * Hook to fetch collections from marketplace configuration
+ *
+ * Retrieves all collections configured in the marketplace, with optional filtering
+ * by marketplace type. Combines metadata from the metadata API with marketplace
+ * configuration to provide complete collection information.
+ *
+ * @param params - Configuration parameters
+ * @param params.marketplaceType - Optional filter by marketplace type
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing array of collections with metadata
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data: collections, isLoading } = useListCollections();
+ *
+ * if (isLoading) return <div>Loading collections...</div>;
+ *
+ * return (
+ *   <div>
+ *     {collections?.map(collection => (
+ *       <div key={collection.itemsAddress}>
+ *         {collection.name}
+ *       </div>
+ *     ))}
+ *   </div>
+ * );
+ * ```
+ *
+ * @example
+ * Filtering by marketplace type:
+ * ```typescript
+ * const { data: marketCollections } = useListCollections({
+ *   marketplaceType: 'market'
+ * });
+ * ```
+ */
+export function useListCollections(params: UseListCollectionsParams = {}) {
+	const defaultConfig = useConfig();
 	const { data: marketplaceConfig } = useMarketplaceConfig();
 
+	const {
+		config = defaultConfig,
+		marketplaceConfig: paramMarketplaceConfig,
+		...rest
+	} = params;
+
+	const queryOptions = listCollectionsQueryOptions({
+		config,
+		marketplaceConfig: paramMarketplaceConfig || marketplaceConfig,
+		...rest,
+	});
+
 	return useQuery({
-		...args.query,
-		...listCollectionsOptions({
-			marketplaceType: args.marketplaceType,
-			marketplaceConfig,
-			config,
-		}),
+		...queryOptions,
 	});
-};
+}
+
+export { listCollectionsQueryOptions };
+
+export type { FetchListCollectionsParams, ListCollectionsQueryOptions };

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';
@@ -19,7 +19,8 @@ import { useListCollectibles } from './useListCollectibles';
 interface UseListMarketCardDataProps {
 	collectionAddress: Address;
 	chainId: number;
-	orderbookKind: OrderbookKind;
+	// orderbookKind is optional — used to override marketplace config for internal tests
+	orderbookKind?: OrderbookKind;
 	collectionType: ContractType;
 	filterOptions?: PropertyFilter[];
 	searchText?: string;

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.tsx

@@ -0,0 +1,66 @@
+'use client';
+
+import { useInfiniteQuery } from '@tanstack/react-query';
+import type { Optional } from '../_internal';
+import {
+	type ListPrimarySaleItemsQueryOptions,
+	listPrimarySaleItemsQueryOptions,
+} from '../queries/primarySaleItems';
+import { useConfig } from './useConfig';
+
+export type UseListPrimarySaleItemsParams = Optional<
+	ListPrimarySaleItemsQueryOptions,
+	'config'
+>;
+
+/**
+ * Hook to fetch primary sale items with pagination support
+ *
+ * Retrieves a paginated list of primary sale items for a specific contract address
+ * 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.primarySaleContractAddress - The primary sale contract address
+ * @param params.filter - Optional filter parameters for the query
+ * @param params.page - Optional pagination parameters
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Infinite query result containing the primary sale items data
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data, isLoading } = useListPrimarySaleItems({
+ *   chainId: 137,
+ *   primarySaleContractAddress: '0x...',
+ * })
+ * ```
+ *
+ * @example
+ * With filters and pagination:
+ * ```typescript
+ * const { data, isLoading } = useListPrimarySaleItems({
+ *   chainId: 1,
+ *   primarySaleContractAddress: '0x...',
+ *   filter: { status: 'active' },
+ *   page: { page: 1, pageSize: 20 },
+ *   query: {
+ *     enabled: isReady
+ *   }
+ * })
+ * ```
+ */
+export function useListPrimarySaleItems(params: UseListPrimarySaleItemsParams) {
+	const defaultConfig = useConfig();
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = listPrimarySaleItemsQueryOptions({
+		config,
+		...rest,
+	});
+
+	return useInfiniteQuery(queryOptions);
+}
+
+export type { ListPrimarySaleItemsQueryOptions };

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.ts

@@ -1,19 +1,71 @@
-import { useQuery } from '@tanstack/react-query';
-import { useConfig } from './useConfig';
+'use client';
 
+import { useQuery } from '@tanstack/react-query';
+import type { Optional } from '../_internal';
 import {
-	type FetchTokenMetadataArgs,
-	tokenMetadataOptions,
+	type FetchListTokenMetadataParams,
+	type ListTokenMetadataQueryOptions,
+	listTokenMetadataQueryOptions,
 } from '../queries/listTokenMetadata';
+import { useConfig } from './useConfig';
+
+export type UseListTokenMetadataParams = Optional<
+	ListTokenMetadataQueryOptions,
+	'config'
+>;
 
-export const useListTokenMetadata = (args: FetchTokenMetadataArgs) => {
-	const config = useConfig();
-	const { chainId, contractAddress, tokenIds, query } = args;
+/**
+ * Hook to fetch token metadata from the metadata API
+ *
+ * Retrieves metadata for a batch of tokens from a specific contract.
+ * Useful for getting token names, descriptions, images, and other attributes.
+ *
+ * @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.query - Optional React Query configuration
+ *
+ * @returns Query result containing token metadata array
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data, isLoading } = useListTokenMetadata({
+ *   chainId: 137,
+ *   contractAddress: '0x...',
+ *   tokenIds: ['1', '2', '3']
+ * })
+ * ```
+ *
+ * @example
+ * With conditional fetching:
+ * ```typescript
+ * const { data, isLoading } = useListTokenMetadata({
+ *   chainId: 1,
+ *   contractAddress: '0x...',
+ *   tokenIds: selectedTokenIds,
+ *   query: {
+ *     enabled: selectedTokenIds.length > 0
+ *   }
+ * })
+ * ```
+ */
+export function useListTokenMetadata(params: UseListTokenMetadataParams) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = listTokenMetadataQueryOptions({
+		config,
+		...rest,
+	});
 
 	return useQuery({
-		...tokenMetadataOptions(
-			{ chainId, contractAddress, tokenIds, query },
-			config,
-		),
+		...queryOptions,
 	});
-};
+}
+
+export { listTokenMetadataQueryOptions };
+
+export type { FetchListTokenMetadataParams, ListTokenMetadataQueryOptions };