@0xsequence/marketplace-sdk 0.9.0 → 0.10.0

package/src/react/hooks/useGetCountOfPrimarySaleItems.tsx

@@ -0,0 +1,48 @@
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import type { Optional } from '../_internal';
+import type { ListPrimarySaleItemsQueryOptions } from '../queries/primarySaleItems';
+import { primarySaleItemsCountQueryOptions } from '../queries/primarySaleItemsCount';
+import { useConfig } from './useConfig';
+
+export type UseGetCountParams = Optional<
+	ListPrimarySaleItemsQueryOptions,
+	'config'
+>;
+
+/**
+ * Hook to get the total count of primary sale items
+ *
+ * Retrieves the total count 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.query - Optional React Query configuration
+ *
+ * @returns Query result containing the count of primary sale items
+ *
+ * @example
+ * ```typescript
+ * const { data: count, isLoading } = useGetCountOfPrimarySaleItems({
+ *   chainId: 137,
+ *   primarySaleContractAddress: '0x...',
+ * })
+ * ```
+ */
+export function useGetCountOfPrimarySaleItems(params: UseGetCountParams) {
+	const defaultConfig = useConfig();
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = primarySaleItemsCountQueryOptions({
+		config,
+		...rest,
+	});
+
+	return useQuery(queryOptions);
+}
+
+export type { ListPrimarySaleItemsQueryOptions };

package/src/react/hooks/useGetTokenRanges.tsx

@@ -1,31 +1,92 @@
+'use client';
+
 import { useQuery } from '@tanstack/react-query';
 import type { Address } from 'viem';
-import { useConfig } from '..';
-import { getIndexerClient } from '../_internal';
+import type { Optional } from '../_internal';
+import {
+	type FetchGetTokenRangesParams,
+	type GetTokenRangesQueryOptions,
+	getTokenRangesQueryOptions,
+} from '../queries/getTokenRanges';
+import { useConfig } from './useConfig';
+
+export type UseGetTokenRangesParams = Optional<
+	GetTokenRangesQueryOptions,
+	'config'
+>;
+
+/**
+ * Hook to fetch token ID ranges for a collection
+ *
+ * Retrieves the available token ID ranges for a specific collection,
+ * which is useful for understanding the token distribution and
+ * available tokens within a collection.
+ *
+ * @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 to fetch ranges for
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing token ID ranges for the collection
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data: tokenRanges, isLoading } = useGetTokenRanges({
+ *   chainId: 137,
+ *   collectionAddress: '0x1234...'
+ * })
+ *
+ * if (data) {
+ *   console.log(`Token ranges: ${JSON.stringify(data.tokenIDRanges)}`);
+ *   data.tokenIDRanges?.forEach(range => {
+ *     console.log(`Range: ${range.start} - ${range.end}`);
+ *   });
+ * }
+ * ```
+ *
+ * @example
+ * With conditional enabling:
+ * ```typescript
+ * const { data: tokenRanges } = useGetTokenRanges({
+ *   chainId: 1,
+ *   collectionAddress: selectedCollection?.address,
+ *   query: {
+ *     enabled: Boolean(selectedCollection?.address),
+ *     staleTime: 300000, // Cache for 5 minutes
+ *     refetchInterval: 60000 // Refresh every minute
+ *   }
+ * })
+ * ```
+ */
+export function useGetTokenRanges(params: UseGetTokenRangesParams) {
+	const defaultConfig = useConfig();
 
-interface UseGetTokenRangesProps {
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = getTokenRangesQueryOptions({
+		config,
+		...rest,
+	});
+
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { getTokenRangesQueryOptions };
+
+export type { FetchGetTokenRangesParams, GetTokenRangesQueryOptions };
+
+// Legacy exports for backward compatibility
+export type UseGetTokenRangesProps = {
 	chainId: number;
 	collectionAddress: Address;
 	query?: {
 		enabled?: boolean;
 	};
-}
+};
 
-export function useGetTokenRanges({
-	chainId,
-	collectionAddress,
-	query = {},
-}: UseGetTokenRangesProps) {
-	const config = useConfig();
-	const indexerClient = getIndexerClient(chainId, config);
-
-	return useQuery({
-		queryKey: ['indexer-tokenRanges', chainId, collectionAddress],
-		queryFn: () => {
-			return indexerClient.getTokenIDRanges({
-				contractAddress: collectionAddress,
-			});
-		},
-		enabled: query?.enabled,
-	});
-}
+export type UseGetTokenRangesReturn = Awaited<
+	ReturnType<typeof import('../queries/getTokenRanges').fetchGetTokenRanges>
+>;

package/src/react/hooks/useList1155ShopCardData.tsx

@@ -75,6 +75,7 @@ export function useList1155ShopCardData({
 		};
 
 		const supply = saleData?.supply?.toString();
+		const unlimitedSupply = saleData?.unlimitedSupply;
 
 		return {
 			collectibleId: tokenId,
@@ -88,6 +89,7 @@ export function useList1155ShopCardData({
 			quantityInitial: supply,
 			quantityDecimals: collection?.decimals || 0,
 			quantityRemaining: supply,
+			unlimitedSupply,
 			saleStartsAt: saleData?.startDate?.toString(),
 			saleEndsAt: saleData?.endDate?.toString(),
 			marketplaceType: 'shop',

package/src/react/hooks/useList721ShopCardData.tsx

@@ -1,8 +1,8 @@
 import type { Address } from 'viem';
 import { useReadContract } from 'wagmi';
-import { ContractType, OrderSide, type TokenMetadata } from '../../types';
 import { ERC721_SALE_ABI } from '../../utils';
-import type { ShopCollectibleCardProps } from '../ui/components/marketplace-collectible-card/types';
+import { ContractType, OrderSide, type TokenMetadata } from '../_internal';
+import type { ShopCollectibleCardProps } from '../ui';
 import { useFilterState } from './useFilterState';
 import { useListCollectibles } from './useListCollectibles';
 import { useListPrimarySaleItems } from './useListPrimarySaleItems';
@@ -92,10 +92,15 @@ export function useList721ShopCardData({
 			hasMintedTokens && Number(tokenId) < Number(firstAvailableTokenId);
 
 		const matchingPrimarySaleItem = primarySaleItems?.pages
-			.flatMap((page) => page.primarySaleItems)
-			.find(
-				(item: { primarySaleItem: { tokenId: { toString: () => string } } }) =>
-					item.primarySaleItem.tokenId?.toString() === tokenId,
+			.find((item) =>
+				item.primarySaleItems.find(
+					(primarySaleItem) =>
+						primarySaleItem.primarySaleItem.tokenId?.toString() === tokenId,
+				),
+			)
+			?.primarySaleItems.find(
+				(primarySaleItem) =>
+					primarySaleItem.primarySaleItem.tokenId?.toString() === tokenId,
 			);
 
 		const saleData = matchingPrimarySaleItem?.primarySaleItem;
@@ -135,7 +140,7 @@ export function useList721ShopCardData({
 			chainId,
 			collectionAddress: contractAddress,
 			collectionType: ContractType.ERC721,
-			tokenMetadata: tokenMetadata,
+			tokenMetadata,
 			cardLoading: isLoading,
 			salesContractAddress: salesContractAddress,
 			salePrice,

package/src/react/hooks/useListCollections.tsx

@@ -16,57 +16,57 @@ export type UseListCollectionsParams = Optional<
 >;
 
 /**
- * Hook to fetch a list of collections from the marketplace
+ * Hook to fetch collections from marketplace configuration
  *
- * This hook fetches collections from the marketplace configuration and enriches them with
- * metadata from the metadata API. Collections can be filtered by marketplace type (market/shop).
+ * 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 for marketplace type ('market' or 'shop')
- * @param params.marketplaceConfig - Optional marketplace configuration (defaults from context)
- * @param params.config - Optional SDK configuration (defaults from context)
+ * @param params.marketplaceType - Optional filter by marketplace type
  * @param params.query - Optional React Query configuration
  *
- * @returns Query result containing an array of collections with metadata
+ * @returns Query result containing array of collections with metadata
  *
  * @example
- * Basic usage - fetch all collections:
+ * Basic usage:
  * ```typescript
- * const { data: collections, isLoading } = useListCollections()
+ * 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
- * Filter by marketplace type:
+ * Filtering by marketplace type:
  * ```typescript
  * const { data: marketCollections } = useListCollections({
  *   marketplaceType: 'market'
- * })
- * ```
- *
- * @example
- * With custom query options:
- * ```typescript
- * const { data: collections } = useListCollections({
- *   query: {
- *     enabled: isReady,
- *     staleTime: 5 * 60 * 1000 // 5 minutes
- *   }
- * })
+ * });
  * ```
  */
 export function useListCollections(params: UseListCollectionsParams = {}) {
 	const defaultConfig = useConfig();
-	const { data: defaultMarketplaceConfig } = useMarketplaceConfig();
+	const { data: marketplaceConfig } = useMarketplaceConfig();
 
 	const {
 		config = defaultConfig,
-		marketplaceConfig = defaultMarketplaceConfig,
+		marketplaceConfig: paramMarketplaceConfig,
 		...rest
 	} = params;
 
 	const queryOptions = listCollectionsQueryOptions({
 		config,
-		marketplaceConfig,
+		marketplaceConfig: paramMarketplaceConfig || marketplaceConfig,
 		...rest,
 	});
 

package/src/react/hooks/useListMarketCardData.tsx

@@ -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/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/useListTokenMetadata.ts

@@ -0,0 +1,71 @@
+'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 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({
+		...queryOptions,
+	});
+}
+
+export { listTokenMetadataQueryOptions };
+
+export type { FetchListTokenMetadataParams, ListTokenMetadataQueryOptions };

package/src/react/hooks/useOpenConnectModal.tsx

@@ -0,0 +1,9 @@
+import { useConfig } from './useConfig';
+
+export const useOpenConnectModal = () => {
+	const context = useConfig();
+
+	return {
+		openConnectModal: context.openConnectModal,
+	};
+};

package/src/react/hooks/useTokenSaleDetailsBatch.tsx

@@ -62,15 +62,11 @@ export function useTokenSaleDetailsBatch({
 			const supplies = await Promise.all(
 				tokenIds.map(async (tokenId) => {
 					try {
-						const result = await indexerClient.getTokenSuppliesMap({
-							tokenMap: {
-								[collectionAddress]: [tokenId],
-							},
+						const result = await indexerClient.getTokenSupplies({
+							contractAddress: collectionAddress,
 							includeMetadata: false,
 						});
-						const supply = result.supplies?.[collectionAddress]?.find(
-							(s) => s.tokenID === tokenId,
-						);
+						const supply = result.tokenIDs?.find((s) => s.tokenID === tokenId);
 						return {
 							tokenId,
 							supply: supply ? Number(supply.supply) : 0,

package/src/react/hooks/useTokenSupplies.ts

@@ -0,0 +1,81 @@
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import type { Optional } from '../_internal';
+import {
+	type FetchTokenSuppliesParams,
+	type TokenSuppliesQueryOptions,
+	tokenSuppliesQueryOptions,
+} from '../queries/tokenSupplies';
+import { useConfig } from './useConfig';
+
+export type UseTokenSuppliesParams = Optional<
+	TokenSuppliesQueryOptions,
+	'config'
+>;
+
+/**
+ * Hook to fetch token supplies from the indexer or LAOS API
+ *
+ * Retrieves supply information for tokens from a specific collection.
+ * Automatically chooses between indexer and LAOS APIs based on the isLaos721 flag.
+ *
+ * @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.isLaos721 - Whether to use LAOS API instead of indexer
+ * @param params.includeMetadata - Whether to include token metadata
+ * @param params.page - Pagination options
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing token supplies
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data, isLoading } = useTokenSupplies({
+ *   chainId: 137,
+ *   collectionAddress: '0x...'
+ * })
+ * ```
+ *
+ * @example
+ * With LAOS API:
+ * ```typescript
+ * const { data, isLoading } = useTokenSupplies({
+ *   chainId: 1,
+ *   collectionAddress: '0x...',
+ *   isLaos721: true
+ * })
+ * ```
+ *
+ * @example
+ * With conditional fetching:
+ * ```typescript
+ * const { data, isLoading } = useTokenSupplies({
+ *   chainId: 1,
+ *   collectionAddress: selectedCollection,
+ *   query: {
+ *     enabled: !!selectedCollection
+ *   }
+ * })
+ * ```
+ */
+export function useTokenSupplies(params: UseTokenSuppliesParams) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = tokenSuppliesQueryOptions({
+		config,
+		...rest,
+	});
+
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { tokenSuppliesQueryOptions };
+
+export type { FetchTokenSuppliesParams, TokenSuppliesQueryOptions };

package/src/react/hooks/useTransferTokens.tsx

@@ -1,4 +1,4 @@
-import { type Abi, type Address, erc721Abi, type Hex } from 'viem';
+import { type Abi, type Address, erc721Abi } from 'viem';
 import { useAccount, useWriteContract } from 'wagmi';
 import { ERC1155_ABI } from '../../utils';
 import { NoWalletConnectedError } from '../../utils/_internal/error/transaction';
@@ -6,7 +6,7 @@ import type { ContractType } from '../_internal';
 
 interface BaseTransferParams {
 	chainId: number;
-	collectionAddress: Hex;
+	collectionAddress: Address;
 	tokenId: string;
 	receiverAddress: Address;
 }

package/src/react/provider.tsx

@@ -1,19 +1,78 @@
 'use client';
 
+import { useOpenConnectModal } from '@0xsequence/connect';
+import type { Auth } from '@databeat/tracker';
 import { QueryClientProvider } from '@tanstack/react-query';
-import { createContext } from 'react';
-import type { SdkConfig } from '../types';
+import { createContext, useMemo } from 'react';
+import type {
+	MarketplaceSdkContext as MarketplaceSdkContextType,
+	SdkConfig,
+} from '../types';
 import { InvalidProjectAccessKeyError } from '../utils/_internal/error/config';
 import { getQueryClient } from './_internal/api/get-query-client';
+import { DatabeatAnalytics } from './_internal/databeat';
 import { PROVIDER_ID } from './_internal/get-provider';
 
-export const MarketplaceSdkContext = createContext({} as SdkConfig);
+export const MarketplaceSdkContext = createContext(
+	{} as MarketplaceSdkContextType,
+);
 
 export type MarketplaceSdkProviderProps = {
 	config: SdkConfig;
 	children: React.ReactNode;
+	openConnectModal?: () => void;
 };
 
+export function MarketplaceProvider({
+	config,
+	children,
+	openConnectModal,
+}: MarketplaceSdkProviderProps) {
+	if (config.projectAccessKey === '' || !config.projectAccessKey) {
+		throw new InvalidProjectAccessKeyError(config.projectAccessKey);
+	}
+
+	const analytics = useMemo(() => {
+		const server = 'https://nodes.sequence.app';
+		const auth: Auth = {};
+		auth.headers = { 'X-Access-Key': config.projectAccessKey };
+
+		return new DatabeatAnalytics(server, auth, {
+			defaultEnabled: true,
+			initProps: () => {
+				return {
+					origin: typeof window !== 'undefined' ? window.location.origin : '',
+				};
+			},
+		});
+	}, [config.projectAccessKey, window]);
+
+	if (openConnectModal) {
+		const context: MarketplaceSdkContextType = {
+			...config,
+			openConnectModal,
+			analytics,
+		};
+
+		return (
+			<MarketplaceQueryClientProvider>
+				<MarketplaceSdkContext.Provider value={context}>
+					<div id={PROVIDER_ID}>{children}</div>
+				</MarketplaceSdkContext.Provider>
+			</MarketplaceQueryClientProvider>
+		);
+	}
+
+	return (
+		<MarketplaceProviderWithSequenceConnect
+			config={config}
+			analytics={analytics}
+		>
+			{children}
+		</MarketplaceProviderWithSequenceConnect>
+	);
+}
+
 export function MarketplaceQueryClientProvider({
 	children,
 }: {
@@ -25,17 +84,22 @@ export function MarketplaceQueryClientProvider({
 	);
 }
 
-export function MarketplaceProvider({
+function MarketplaceProviderWithSequenceConnect({
 	config,
 	children,
-}: MarketplaceSdkProviderProps) {
-	if (config.projectAccessKey === '' || !config.projectAccessKey) {
-		throw new InvalidProjectAccessKeyError(config.projectAccessKey);
-	}
+	analytics,
+}: MarketplaceSdkProviderProps & { analytics: DatabeatAnalytics }) {
+	const { setOpenConnectModal } = useOpenConnectModal();
+
+	const context: MarketplaceSdkContextType = {
+		...config,
+		openConnectModal: () => setOpenConnectModal(true),
+		analytics,
+	};
 
 	return (
 		<MarketplaceQueryClientProvider>
-			<MarketplaceSdkContext.Provider value={config}>
+			<MarketplaceSdkContext.Provider value={context}>
 				<div id={PROVIDER_ID}>{children}</div>
 			</MarketplaceSdkContext.Provider>
 		</MarketplaceQueryClientProvider>