@0xsequence/marketplace-sdk 0.9.0 → 1.0.0

package/src/react/queries/getTokenRanges.ts

@@ -0,0 +1,62 @@
+import type { GetTokenIDRangesReturn } from '@0xsequence/indexer';
+import { queryOptions } from '@tanstack/react-query';
+import type { Address } from 'viem';
+import type { SdkConfig } from '../../types';
+import { getIndexerClient, type ValuesOptional } from '../_internal';
+import type { StandardQueryOptions } from '../types/query';
+
+export interface FetchGetTokenRangesParams {
+	chainId: number;
+	collectionAddress: Address;
+	config: SdkConfig;
+}
+
+/**
+ * Fetches token ID ranges for a collection from the Indexer API
+ */
+export async function fetchGetTokenRanges(
+	params: FetchGetTokenRangesParams,
+): Promise<GetTokenIDRangesReturn> {
+	const { chainId, collectionAddress, config } = params;
+
+	const indexerClient = getIndexerClient(chainId, config);
+
+	const response = await indexerClient.getTokenIDRanges({
+		contractAddress: collectionAddress,
+	});
+
+	if (!response) {
+		throw new Error('Failed to fetch token ranges');
+	}
+
+	return response;
+}
+
+export type GetTokenRangesQueryOptions =
+	ValuesOptional<FetchGetTokenRangesParams> & {
+		query?: StandardQueryOptions;
+	};
+
+export function getTokenRangesQueryOptions(params: GetTokenRangesQueryOptions) {
+	const enabled = Boolean(
+		params.chainId &&
+			params.collectionAddress &&
+			params.config &&
+			(params.query?.enabled ?? true),
+	);
+
+	return queryOptions({
+		queryKey: ['indexer', 'tokenRanges', params],
+		queryFn: () =>
+			fetchGetTokenRanges({
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				chainId: params.chainId!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				collectionAddress: params.collectionAddress!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				config: params.config!,
+			}),
+		...params.query,
+		enabled,
+	});
+}

package/src/react/queries/index.ts

@@ -1,12 +1,34 @@
 export * from './balanceOfCollectible';
+export * from './checkoutOptions';
+export * from './checkoutOptionsSalesContract';
 export * from './collectible';
+export * from './collection';
+export * from './collectionBalanceDetails';
 export * from './collectionDetails';
+export * from './comparePrices';
+export * from './convertPriceToUSD';
+export * from './countListingsForCollectible';
+export * from './countOfCollectables';
+export * from './countOffersForCollectible';
 export * from './countOfPrimarySaleItems';
+export * from './currency';
+export * from './filters';
 export * from './floorOrder';
+export * from './getTokenRanges';
 export * from './highestOffer';
 export * from './inventory';
 export * from './listBalances';
+export * from './listCollectibleActivities';
 export * from './listCollectibles';
+export * from './listCollectiblesPaginated';
+export * from './listCollectionActivities';
+export * from './listCollections';
+export * from './listListingsForCollectible';
 export * from './listTokenMetadata';
 export * from './lowestListing';
 export * from './marketCurrencies';
+export * from './marketplaceConfig';
+export * from './primarySaleItems';
+export * from './primarySaleItemsCount';
+export * from './searchTokenMetadata';
+export * from './tokenSupplies';

package/src/react/queries/inventory.ts

@@ -38,6 +38,11 @@ interface InventoryState {
 // Store state per collection
 const stateByCollection = new Map<string, InventoryState>();
 
+// Test helper to clear state between tests
+export const clearInventoryState = () => {
+	stateByCollection.clear();
+};
+
 const getCollectionKey = (args: UseInventoryArgs) =>
 	`${args.chainId}-${args.collectionAddress}-${args.accountAddress}`;
 
@@ -105,6 +110,7 @@ async function fetchAllIndexerTokens(
 			chainId: chainId.toString(),
 			accountAddress,
 			includeMetadata: true,
+			contractAddress: collectionAddress,
 			page: {
 				sort: [
 					{

package/src/react/queries/listBalances.ts

@@ -1,13 +1,13 @@
 import type { GetTokenBalancesReturn, Page } from '@0xsequence/indexer';
 import { infiniteQueryOptions } from '@tanstack/react-query';
-import type { Hex } from 'viem';
+import type { Address, Hex } from 'viem';
 import type { SdkConfig } from '../../types';
 import { balanceQueries, getIndexerClient, LaosAPI } from '../_internal';
 
 export type UseListBalancesArgs = {
 	chainId: number;
-	accountAddress?: Hex;
-	contractAddress?: Hex;
+	accountAddress?: Address;
+	contractAddress?: Address;
 	tokenId?: string;
 	includeMetadata?: boolean;
 	metadataOptions?: {
@@ -34,6 +34,7 @@ export async function fetchBalances(
 		return laosClient.getTokenBalances({
 			chainId: args.chainId.toString(),
 			accountAddress: args.accountAddress,
+			contractAddress: args.contractAddress as Address,
 			includeMetadata: args.includeMetadata,
 			page: {
 				sort: [

package/src/react/queries/listCollections.ts

@@ -28,7 +28,7 @@ export interface FetchListCollectionsParams {
 }
 
 /**
- * Fetches list of collections from the metadata API with marketplace filtering
+ * Fetches collections from the metadata API with marketplace config filtering
  */
 export async function fetchListCollections(params: FetchListCollectionsParams) {
 	const { marketplaceType, marketplaceConfig, config } = params;
@@ -150,14 +150,18 @@ export const listCollectionsOptions = ({
 	config: SdkConfig;
 }) => {
 	return queryOptions({
-		queryKey: [...collectionKeys.list, marketplaceType],
+		queryKey: [
+			...collectionKeys.list,
+			{ marketplaceType, marketplaceConfig, config },
+		],
 		queryFn: marketplaceConfig
 			? () =>
 					fetchListCollections({
-						marketplaceType,
 						marketplaceConfig,
 						config,
+						marketplaceType,
 					})
 			: skipToken,
+		enabled: Boolean(marketplaceConfig),
 	});
 };

package/src/react/queries/listTokenMetadata.ts

@@ -2,7 +2,7 @@ import { queryOptions } from '@tanstack/react-query';
 import type { SdkConfig } from '../../types';
 import {
 	getMetadataClient,
-	metadataKeys,
+	tokenKeys,
 	type ValuesOptional,
 } from '../_internal';
 import type { StandardQueryOptions } from '../types/query';
@@ -49,7 +49,7 @@ export function listTokenMetadataQueryOptions(
 	);
 
 	return queryOptions({
-		queryKey: [...metadataKeys.tokenMetadata, params],
+		queryKey: [...tokenKeys.metadata, params],
 		queryFn: () =>
 			fetchListTokenMetadata({
 				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined

package/src/react/queries/marketplaceConfig.ts

@@ -1,5 +1,5 @@
 import { queryOptions } from '@tanstack/react-query';
-import type { ContractType, SdkConfig } from '../../types';
+import type { ContractType, OrderbookKind, SdkConfig } from '../../types';
 import type {
 	MarketCollection,
 	MarketPage,
@@ -9,6 +9,7 @@ import type {
 } from '../../types/new-marketplace-types';
 import { configKeys, getBuilderClient } from '../_internal';
 import type { LookupMarketplaceReturn } from '../_internal/api/builder.gen';
+import { persistentQueryMeta } from '../_internal/query-meta';
 
 export const fetchMarketplaceConfig = async ({
 	config,
@@ -34,11 +35,13 @@ export const fetchMarketplaceConfig = async ({
 		return {
 			...collection,
 			contractType: collection.contractType as ContractType,
+			destinationMarketplace:
+				collection.destinationMarketplace as OrderbookKind,
 			marketplaceType: 'market',
 		} satisfies MarketCollection;
 	});
 
-	const shopCollections = builderMarketplaceConfig.shopCollections.map(
+	const shopCollections = (builderMarketplaceConfig.shopCollections ?? []).map(
 		(collection) => {
 			return {
 				...collection,
@@ -100,5 +103,11 @@ export const marketplaceConfigOptions = (config: SdkConfig) => {
 				config,
 				prefetchedMarketplaceSettings,
 			}),
+		gcTime: Number.POSITIVE_INFINITY,
+		staleTime: Number.POSITIVE_INFINITY,
+		refetchOnMount: false,
+		refetchOnReconnect: false,
+		refetchOnWindowFocus: false,
+		meta: persistentQueryMeta,
 	});
 };

package/src/react/queries/primarySaleItems.ts

@@ -0,0 +1,80 @@
+import { infiniteQueryOptions } from '@tanstack/react-query';
+import type { Address } from 'viem';
+import type { SdkConfig } from '../../types';
+import {
+	getMarketplaceClient,
+	type ListPrimarySaleItemsArgs,
+	type ListPrimarySaleItemsReturn,
+	type Page,
+	type PrimarySaleItemsFilter,
+	type ValuesOptional,
+} from '../_internal';
+import type { StandardQueryOptions } from '../types/query';
+
+export interface FetchPrimarySaleItemsParams {
+	chainId: number;
+	primarySaleContractAddress: Address;
+	filter?: PrimarySaleItemsFilter;
+	page?: Page;
+	config: SdkConfig;
+}
+
+/**
+ * Fetches primary sale items from the marketplace API
+ */
+export async function fetchPrimarySaleItems(
+	params: FetchPrimarySaleItemsParams,
+): Promise<ListPrimarySaleItemsReturn> {
+	const { chainId, primarySaleContractAddress, filter, page, config } = params;
+
+	const marketplaceClient = getMarketplaceClient(config);
+
+	return marketplaceClient.listPrimarySaleItems({
+		chainId: String(chainId),
+		primarySaleContractAddress,
+		filter,
+		page,
+	});
+}
+
+export type ListPrimarySaleItemsQueryOptions =
+	ValuesOptional<FetchPrimarySaleItemsParams> & {
+		query?: StandardQueryOptions;
+	};
+
+export const listPrimarySaleItemsQueryOptions = (
+	params: ListPrimarySaleItemsQueryOptions,
+) => {
+	const enabled = Boolean(
+		params.primarySaleContractAddress &&
+			params.chainId &&
+			params.config &&
+			(params.query?.enabled ?? true),
+	);
+
+	type PageParam = { page: number; pageSize: number };
+	const initialPage: PageParam = params.page || { page: 1, pageSize: 30 };
+
+	return infiniteQueryOptions({
+		queryKey: ['listPrimarySaleItems', params],
+		queryFn: async ({ pageParam }) => {
+			return fetchPrimarySaleItems({
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				chainId: params.chainId!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				primarySaleContractAddress: params.primarySaleContractAddress!,
+				filter: params.filter,
+				page: pageParam,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				config: params.config!,
+			});
+		},
+		initialPageParam: initialPage,
+		getNextPageParam: (lastPage) =>
+			lastPage.page?.more ? lastPage.page : undefined,
+		...params.query,
+		enabled,
+	});
+};
+
+export type { ListPrimarySaleItemsArgs, ListPrimarySaleItemsReturn };

package/src/react/queries/primarySaleItemsCount.ts

@@ -0,0 +1,64 @@
+import { queryOptions } from '@tanstack/react-query';
+import type { Address } from 'viem';
+import type { SdkConfig } from '../../types';
+import {
+	type GetCountOfPrimarySaleItemsReturn,
+	getMarketplaceClient,
+	type PrimarySaleItemsFilter,
+} from '../_internal';
+import type { StandardQueryOptions } from '../types/query';
+
+export interface FetchPrimarySaleItemsCountParams {
+	chainId: number;
+	primarySaleContractAddress: Address;
+	filter?: PrimarySaleItemsFilter;
+	config: SdkConfig;
+}
+
+/**
+ * Fetches the count of primary sale items from the marketplace API
+ */
+export async function fetchPrimarySaleItemsCount(
+	params: FetchPrimarySaleItemsCountParams,
+): Promise<GetCountOfPrimarySaleItemsReturn> {
+	const { chainId, primarySaleContractAddress, filter, config } = params;
+
+	const marketplaceClient = getMarketplaceClient(config);
+	return marketplaceClient.getCountOfPrimarySaleItems({
+		chainId: String(chainId),
+		primarySaleContractAddress,
+		filter,
+	});
+}
+
+export type PrimarySaleItemsCountQueryOptions =
+	Partial<FetchPrimarySaleItemsCountParams> & {
+		query?: StandardQueryOptions;
+	};
+
+export const primarySaleItemsCountQueryOptions = (
+	args: PrimarySaleItemsCountQueryOptions,
+) => {
+	const enabled = Boolean(
+		args.primarySaleContractAddress &&
+			args.chainId &&
+			args.config &&
+			(args.query?.enabled ?? true),
+	);
+
+	return queryOptions({
+		queryKey: ['primarySaleItemsCount', args],
+		queryFn: () =>
+			fetchPrimarySaleItemsCount({
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				chainId: args.chainId!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				primarySaleContractAddress: args.primarySaleContractAddress!,
+				filter: args.filter,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				config: args.config!,
+			}),
+		...args.query,
+		enabled,
+	});
+};

package/src/react/queries/searchTokenMetadata.ts

@@ -0,0 +1,87 @@
+import type {
+	Filter,
+	Page,
+	SearchTokenMetadataReturn,
+} from '@0xsequence/metadata';
+import { infiniteQueryOptions } from '@tanstack/react-query';
+import type { SdkConfig } from '../../types';
+import {
+	getMetadataClient,
+	tokenKeys,
+	type ValuesOptional,
+} from '../_internal';
+import type { StandardQueryOptions } from '../types/query';
+
+export interface FetchSearchTokenMetadataParams {
+	chainId: number;
+	collectionAddress: string;
+	filter?: Filter;
+	page?: Page;
+	config: SdkConfig;
+}
+
+/**
+ * Fetches token metadata from the metadata API using search filters
+ */
+export async function fetchSearchTokenMetadata(
+	params: FetchSearchTokenMetadataParams,
+): Promise<SearchTokenMetadataReturn> {
+	const { chainId, collectionAddress, filter, page, config } = params;
+	const metadataClient = getMetadataClient(config);
+
+	const response = await metadataClient.searchTokenMetadata({
+		chainID: chainId.toString(),
+		contractAddress: collectionAddress,
+		filter: filter ?? {},
+		page,
+	});
+
+	return {
+		tokenMetadata: response.tokenMetadata,
+		page: response.page,
+	};
+}
+
+export type SearchTokenMetadataQueryOptions =
+	ValuesOptional<FetchSearchTokenMetadataParams> & {
+		query?: StandardQueryOptions;
+	};
+
+export function searchTokenMetadataQueryOptions(
+	params: SearchTokenMetadataQueryOptions,
+) {
+	const enabled = Boolean(
+		params.chainId &&
+			params.collectionAddress &&
+			params.config &&
+			(params.query?.enabled ?? true),
+	);
+
+	const initialPageParam = { page: 1, pageSize: 30 };
+
+	return infiniteQueryOptions({
+		queryKey: [...tokenKeys.metadata, 'search', params],
+		queryFn: ({ pageParam = initialPageParam }) =>
+			fetchSearchTokenMetadata({
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				chainId: params.chainId!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				collectionAddress: params.collectionAddress!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				filter: params.filter!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				config: params.config!,
+				page: pageParam,
+			}),
+		initialPageParam,
+		getNextPageParam: (lastPage) => {
+			if (!lastPage.page?.more) return undefined;
+			return {
+				page: (lastPage.page.page || 1) + 1,
+				pageSize: lastPage.page.pageSize || 20,
+			};
+		},
+		...params.query,
+		enabled,
+	});
+}

package/src/react/queries/tokenSupplies.ts

@@ -0,0 +1,101 @@
+import type { GetTokenSuppliesArgs, Page } from '@0xsequence/indexer';
+import { infiniteQueryOptions } from '@tanstack/react-query';
+import type { SdkConfig } from '../../types';
+import {
+	getIndexerClient,
+	LaosAPI,
+	tokenKeys,
+	type ValuesOptional,
+} from '../_internal';
+import type { StandardInfiniteQueryOptions } from '../types/query';
+
+export interface FetchTokenSuppliesParams
+	extends Omit<GetTokenSuppliesArgs, 'contractAddress'> {
+	chainId: number;
+	collectionAddress: string;
+	config: SdkConfig;
+	isLaos721?: boolean;
+	page?: Page;
+}
+
+/**
+ * Fetches token supplies with support for both indexer and LAOS APIs
+ * Uses the more efficient single-contract APIs from both services
+ */
+export async function fetchTokenSupplies(params: FetchTokenSuppliesParams) {
+	const { chainId, collectionAddress, config, isLaos721, ...rest } = params;
+
+	if (isLaos721) {
+		const laosApi = new LaosAPI();
+
+		// Convert indexer Page format to LAOS PaginationOptions format
+		const laosPage = rest.page
+			? {
+					sort:
+						rest.page.sort?.map((sortBy) => ({
+							column: sortBy.column,
+							order: sortBy.order,
+						})) || [],
+				}
+			: undefined;
+
+		const result = await laosApi.getTokenSupplies({
+			chainId: chainId.toString(),
+			contractAddress: collectionAddress,
+			includeMetadata: rest.includeMetadata,
+			page: laosPage,
+		});
+
+		return result;
+	}
+
+	const indexerClient = getIndexerClient(chainId, config);
+
+	const apiArgs: GetTokenSuppliesArgs = {
+		contractAddress: collectionAddress,
+		...rest,
+	};
+
+	const result = await indexerClient.getTokenSupplies(apiArgs);
+	return result;
+}
+
+export type TokenSuppliesQueryOptions =
+	ValuesOptional<FetchTokenSuppliesParams> & {
+		query?: StandardInfiniteQueryOptions;
+	};
+
+export function tokenSuppliesQueryOptions(params: TokenSuppliesQueryOptions) {
+	const enabled = Boolean(
+		params.chainId &&
+			params.collectionAddress &&
+			params.config &&
+			(params.query?.enabled ?? true),
+	);
+
+	const initialPageParam = { page: 1, pageSize: 30 } as Page;
+
+	const queryFn = async ({ pageParam = initialPageParam }) =>
+		fetchTokenSupplies({
+			// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+			chainId: params.chainId!,
+			// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+			collectionAddress: params.collectionAddress!,
+			// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+			config: params.config!,
+			isLaos721: params.isLaos721,
+			includeMetadata: params.includeMetadata,
+			metadataOptions: params.metadataOptions,
+			page: pageParam,
+		});
+
+	return infiniteQueryOptions({
+		queryKey: [...tokenKeys.supplies, params],
+		queryFn,
+		initialPageParam,
+		getNextPageParam: (lastPage) =>
+			lastPage.page?.more ? lastPage.page : undefined,
+		...params.query,
+		enabled,
+	});
+}

package/src/react/ssr/__tests__/__snapshots__/create-ssr-client.test.ts.snap

@@ -32,6 +32,7 @@ exports[`createSSRClient > should fetch marketplace config successfully 1`] = `
         "id": 1,
         "itemsAddress": "0x0000000000000000000000000000000000000000",
         "marketplaceType": "market",
+        "private": false,
         "projectId": 1,
         "updatedAt": "2025-03-16T13:04:16.098Z",
       },
@@ -66,6 +67,7 @@ exports[`createSSRClient > should fetch marketplace config successfully 1`] = `
         "id": 2,
         "itemsAddress": "0x1234567890123456789012345678901234567890",
         "marketplaceType": "market",
+        "private": false,
         "projectId": 1,
         "updatedAt": "2025-03-16T13:04:16.098Z",
       },
@@ -105,10 +107,12 @@ exports[`createSSRClient > should fetch marketplace config successfully 1`] = `
         "bannerUrl": "https://example.com/shop-banner.png",
         "chainId": 1,
         "createdAt": "2025-03-16T13:04:16.098Z",
+        "customTokenIds": [],
         "id": 1,
         "itemsAddress": "0x0000000000000000000000000000000000000000",
         "marketplaceType": "shop",
         "name": "Mock Shop Collection",
+        "private": false,
         "projectId": 1,
         "saleAddress": "0x0000000000000000000000000000000000000000",
         "saleBannerUrl": "https://example.com/shop-sale-banner.png",
@@ -123,10 +127,12 @@ exports[`createSSRClient > should fetch marketplace config successfully 1`] = `
         "bannerUrl": "https://example.com/polygon-shop-banner.png",
         "chainId": 137,
         "createdAt": "2025-03-16T13:04:16.098Z",
+        "customTokenIds": [],
         "id": 2,
         "itemsAddress": "0x1234567890123456789012345678901234567890",
         "marketplaceType": "shop",
         "name": "Polygon Shop Collection",
+        "private": false,
         "projectId": 1,
         "saleAddress": "0x1234567890123456789012345678901234567890",
         "saleBannerUrl": "https://example.com/polygon-shop-sale-banner.png",

package/src/react/ssr/__tests__/create-ssr-client.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import type { SdkConfig } from '../../../types';
+import type { SdkConfig } from '../../../types/index';
 import { createSSRClient } from '../create-ssr-client';
 
 const wagmiCookie =