@0xsequence/marketplace-sdk 0.9.0 → 0.10.0

package/src/react/queries/checkoutOptions.ts

@@ -0,0 +1,85 @@
+import { queryOptions } from '@tanstack/react-query';
+import type { Address } from 'viem';
+import type { SdkConfig } from '../../types';
+import type { MarketplaceKind } from '../_internal';
+import { getMarketplaceClient, type ValuesOptional } from '../_internal';
+import type {
+	CheckoutOptionsMarketplaceArgs,
+	CheckoutOptionsMarketplaceReturn,
+} from '../_internal/api/marketplace.gen';
+import type { StandardQueryOptions } from '../types/query';
+
+export interface FetchCheckoutOptionsParams
+	extends Omit<
+		CheckoutOptionsMarketplaceArgs,
+		'chainId' | 'wallet' | 'orders'
+	> {
+	chainId: number;
+	walletAddress: Address;
+	orders: Array<{
+		collectionAddress: string;
+		orderId: string;
+		marketplace: MarketplaceKind;
+	}>;
+	config: SdkConfig;
+}
+
+/**
+ * Fetches checkout options from the Marketplace API
+ */
+export async function fetchCheckoutOptions(
+	params: FetchCheckoutOptionsParams,
+): Promise<CheckoutOptionsMarketplaceReturn> {
+	const { chainId, walletAddress, orders, config, additionalFee } = params;
+
+	const client = getMarketplaceClient(config);
+
+	const apiArgs: CheckoutOptionsMarketplaceArgs = {
+		chainId: String(chainId),
+		wallet: walletAddress,
+		orders: orders.map((order) => ({
+			contractAddress: order.collectionAddress,
+			orderId: order.orderId,
+			marketplace: order.marketplace,
+		})),
+		additionalFee: additionalFee ?? 0,
+	};
+
+	const result = await client.checkoutOptionsMarketplace(apiArgs);
+	return result;
+}
+
+export type CheckoutOptionsQueryOptions =
+	ValuesOptional<FetchCheckoutOptionsParams> & {
+		query?: StandardQueryOptions;
+	};
+
+export function checkoutOptionsQueryOptions(
+	params: CheckoutOptionsQueryOptions,
+) {
+	const enabled = Boolean(
+		params.chainId &&
+			params.walletAddress &&
+			params.orders?.length &&
+			params.config &&
+			(params.query?.enabled ?? true),
+	);
+
+	return queryOptions({
+		queryKey: ['checkout', 'options', params],
+		queryFn: () =>
+			fetchCheckoutOptions({
+				// 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
+				walletAddress: params.walletAddress!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				orders: params.orders!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				config: params.config!,
+				additionalFee: params.additionalFee ?? 0,
+			}),
+		...params.query,
+		enabled,
+	});
+}

package/src/react/queries/checkoutOptionsSalesContract.ts

@@ -0,0 +1,89 @@
+import { queryOptions } from '@tanstack/react-query';
+import type { Address } from 'viem';
+import type { SdkConfig } from '../../types';
+import { getMarketplaceClient, type ValuesOptional } from '../_internal';
+import type {
+	CheckoutOptionsItem,
+	CheckoutOptionsSalesContractArgs,
+	CheckoutOptionsSalesContractReturn,
+} from '../_internal/api/marketplace.gen';
+import type { StandardQueryOptions } from '../types/query';
+
+export interface FetchCheckoutOptionsSalesContractParams
+	extends Omit<CheckoutOptionsSalesContractArgs, 'chainId' | 'wallet'> {
+	chainId: number;
+	walletAddress: Address;
+	contractAddress: string;
+	collectionAddress: string;
+	items: Array<CheckoutOptionsItem>;
+	config: SdkConfig;
+}
+
+/**
+ * Fetches checkout options for sales contract from the Marketplace API
+ */
+export async function fetchCheckoutOptionsSalesContract(
+	params: FetchCheckoutOptionsSalesContractParams,
+): Promise<CheckoutOptionsSalesContractReturn> {
+	const {
+		chainId,
+		walletAddress,
+		contractAddress,
+		collectionAddress,
+		items,
+		config,
+	} = params;
+
+	const client = getMarketplaceClient(config);
+
+	const apiArgs: CheckoutOptionsSalesContractArgs = {
+		chainId: String(chainId),
+		wallet: walletAddress,
+		contractAddress,
+		collectionAddress,
+		items,
+	};
+
+	const result = await client.checkoutOptionsSalesContract(apiArgs);
+	return result;
+}
+
+export type CheckoutOptionsSalesContractQueryOptions =
+	ValuesOptional<FetchCheckoutOptionsSalesContractParams> & {
+		query?: StandardQueryOptions;
+	};
+
+export function checkoutOptionsSalesContractQueryOptions(
+	params: CheckoutOptionsSalesContractQueryOptions,
+) {
+	const enabled = Boolean(
+		params.chainId &&
+			params.walletAddress &&
+			params.contractAddress &&
+			params.collectionAddress &&
+			params.items?.length &&
+			params.config &&
+			(params.query?.enabled ?? true),
+	);
+
+	return queryOptions({
+		queryKey: ['checkout', 'options', 'salesContract', params],
+		queryFn: () =>
+			fetchCheckoutOptionsSalesContract({
+				// 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
+				walletAddress: params.walletAddress!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				contractAddress: params.contractAddress!,
+				// 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
+				items: params.items!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				config: params.config!,
+			}),
+		...params.query,
+		enabled,
+	});
+}

package/src/react/queries/collectionBalanceDetails.ts

@@ -0,0 +1,92 @@
+import type { GetTokenBalancesDetailsReturn } 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 CollectionBalanceFilter {
+	accountAddresses: Array<Address>;
+	contractWhitelist?: Array<Address>;
+	omitNativeBalances: boolean;
+}
+
+export interface FetchCollectionBalanceDetailsParams {
+	chainId: number;
+	filter: CollectionBalanceFilter;
+	config: SdkConfig;
+}
+
+/**
+ * Fetches detailed balance information for multiple accounts from the Indexer API
+ */
+export async function fetchCollectionBalanceDetails(
+	params: FetchCollectionBalanceDetailsParams,
+): Promise<GetTokenBalancesDetailsReturn> {
+	const { chainId, filter, config } = params;
+
+	const indexerClient = getIndexerClient(chainId, config);
+
+	const promises = filter.accountAddresses.map((accountAddress) =>
+		indexerClient.getTokenBalancesDetails({
+			filter: {
+				accountAddresses: [accountAddress],
+				contractWhitelist: filter.contractWhitelist,
+				omitNativeBalances: filter.omitNativeBalances,
+			},
+		}),
+	);
+
+	const responses = await Promise.all(promises);
+	const mergedResponse = responses.reduce<GetTokenBalancesDetailsReturn>(
+		(acc, curr) => {
+			if (!curr) return acc;
+			return {
+				page: curr.page,
+				nativeBalances: [
+					...(acc.nativeBalances || []),
+					...(curr.nativeBalances || []),
+				],
+				balances: [...(acc.balances || []), ...(curr.balances || [])],
+			};
+		},
+		{ page: {}, nativeBalances: [], balances: [] },
+	);
+
+	if (!mergedResponse) {
+		throw new Error('Failed to fetch collection balance details');
+	}
+
+	return mergedResponse;
+}
+
+export type CollectionBalanceDetailsQueryOptions =
+	ValuesOptional<FetchCollectionBalanceDetailsParams> & {
+		query?: StandardQueryOptions;
+	};
+
+export function collectionBalanceDetailsQueryOptions(
+	params: CollectionBalanceDetailsQueryOptions,
+) {
+	const enabled = Boolean(
+		params.chainId &&
+			params.filter?.accountAddresses?.length &&
+			params.config &&
+			(params.query?.enabled ?? true),
+	);
+
+	return queryOptions({
+		queryKey: ['balances', 'collectionBalanceDetails', params],
+		queryFn: () =>
+			fetchCollectionBalanceDetails({
+				// 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
+				filter: params.filter!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				config: params.config!,
+			}),
+		...params.query,
+		enabled,
+	});
+}

package/src/react/queries/comparePrices.ts

@@ -0,0 +1,108 @@
+import { queryOptions } from '@tanstack/react-query';
+import type { Address } from 'viem';
+import type { SdkConfig } from '../../types';
+import type { ValuesOptional } from '../_internal';
+import type { StandardQueryOptions } from '../types/query';
+import { fetchConvertPriceToUSD } from './convertPriceToUSD';
+
+export interface FetchComparePricesParams {
+	chainId: number;
+	// First price details
+	priceAmountRaw: string;
+	priceCurrencyAddress: Address;
+	// Second price details (to compare against)
+	compareToPriceAmountRaw: string;
+	compareToPriceCurrencyAddress: Address;
+	config: SdkConfig;
+}
+
+export type ComparePricesReturn = {
+	percentageDifference: number;
+	percentageDifferenceFormatted: string;
+	status: 'above' | 'same' | 'below';
+};
+
+/**
+ * Compares prices between different currencies by converting both to USD
+ */
+export async function fetchComparePrices(
+	params: FetchComparePricesParams,
+): Promise<ComparePricesReturn> {
+	const {
+		chainId,
+		priceAmountRaw,
+		priceCurrencyAddress,
+		compareToPriceAmountRaw,
+		compareToPriceCurrencyAddress,
+		config,
+	} = params;
+
+	const [priceUSD, compareToPriceUSD] = await Promise.all([
+		fetchConvertPriceToUSD({
+			chainId,
+			currencyAddress: priceCurrencyAddress,
+			amountRaw: priceAmountRaw,
+			config,
+		}),
+		fetchConvertPriceToUSD({
+			chainId,
+			currencyAddress: compareToPriceCurrencyAddress,
+			amountRaw: compareToPriceAmountRaw,
+			config,
+		}),
+	]);
+
+	const difference = priceUSD.usdAmount - compareToPriceUSD.usdAmount;
+
+	if (compareToPriceUSD.usdAmount === 0) {
+		throw new Error('Cannot compare to zero price');
+	}
+
+	const percentageDifference = (difference / compareToPriceUSD.usdAmount) * 100;
+	const isAbove = percentageDifference > 0;
+	const isSame = percentageDifference === 0;
+
+	return {
+		percentageDifference,
+		percentageDifferenceFormatted: Math.abs(percentageDifference).toFixed(2),
+		status: isAbove ? 'above' : isSame ? 'same' : 'below',
+	};
+}
+
+export type ComparePricesQueryOptions =
+	ValuesOptional<FetchComparePricesParams> & {
+		query?: StandardQueryOptions;
+	};
+
+export function comparePricesQueryOptions(params: ComparePricesQueryOptions) {
+	const enabled = Boolean(
+		params.chainId &&
+			params.priceAmountRaw &&
+			params.priceCurrencyAddress &&
+			params.compareToPriceAmountRaw &&
+			params.compareToPriceCurrencyAddress &&
+			params.config &&
+			(params.query?.enabled ?? true),
+	);
+
+	return queryOptions({
+		queryKey: ['currency', 'conversion', 'compare', params],
+		queryFn: () =>
+			fetchComparePrices({
+				// 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
+				priceAmountRaw: params.priceAmountRaw!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				priceCurrencyAddress: params.priceCurrencyAddress!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				compareToPriceAmountRaw: params.compareToPriceAmountRaw!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				compareToPriceCurrencyAddress: params.compareToPriceCurrencyAddress!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				config: params.config!,
+			}),
+		...params.query,
+		enabled,
+	});
+}

package/src/react/queries/convertPriceToUSD.ts

@@ -0,0 +1,92 @@
+import { queryOptions } from '@tanstack/react-query';
+import { type Address, formatUnits } from 'viem';
+import type { SdkConfig } from '../../types';
+import {
+	type Currency,
+	getQueryClient,
+	type ValuesOptional,
+} from '../_internal';
+import type { StandardQueryOptions } from '../types/query';
+import { marketCurrenciesQueryOptions } from './marketCurrencies';
+
+export interface FetchConvertPriceToUSDParams {
+	chainId: number;
+	currencyAddress: Address;
+	amountRaw: string;
+	config: SdkConfig;
+}
+
+export interface ConvertPriceToUSDReturn {
+	usdAmount: number;
+	usdAmountFormatted: string;
+}
+
+/**
+ * Converts a price amount from a specific currency to USD using exchange rates
+ */
+export async function fetchConvertPriceToUSD(
+	params: FetchConvertPriceToUSDParams,
+): Promise<ConvertPriceToUSDReturn> {
+	const { chainId, currencyAddress, amountRaw, config } = params;
+
+	const queryClient = getQueryClient();
+	const currencies = (await queryClient.fetchQuery(
+		marketCurrenciesQueryOptions({
+			chainId,
+			config,
+		}),
+	)) as Currency[];
+
+	const currencyDetails = currencies.find(
+		(c: Currency) =>
+			c.contractAddress.toLowerCase() === currencyAddress.toLowerCase(),
+	);
+
+	if (!currencyDetails) {
+		throw new Error('Currency not found');
+	}
+
+	const amountDecimal = Number(
+		formatUnits(BigInt(amountRaw), currencyDetails.decimals),
+	);
+	const usdAmount = amountDecimal * currencyDetails.exchangeRate;
+
+	return {
+		usdAmount,
+		usdAmountFormatted: usdAmount.toFixed(2),
+	};
+}
+
+export type ConvertPriceToUSDQueryOptions =
+	ValuesOptional<FetchConvertPriceToUSDParams> & {
+		query?: StandardQueryOptions;
+	};
+
+export function convertPriceToUSDQueryOptions(
+	params: ConvertPriceToUSDQueryOptions,
+) {
+	const enabled = Boolean(
+		params.chainId &&
+			params.currencyAddress &&
+			params.amountRaw &&
+			params.config &&
+			(params.query?.enabled ?? true),
+	);
+
+	return queryOptions({
+		queryKey: ['currency', 'convertPriceToUSD', params],
+		queryFn: () =>
+			fetchConvertPriceToUSD({
+				// 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
+				currencyAddress: params.currencyAddress!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				amountRaw: params.amountRaw!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				config: params.config!,
+			}),
+		...params.query,
+		enabled,
+	});
+}

package/src/react/queries/filters.ts

@@ -0,0 +1,138 @@
+import type { PropertyFilter } from '@0xsequence/metadata';
+import { queryOptions } from '@tanstack/react-query';
+import { FilterCondition, type SdkConfig } from '../../types';
+import { compareAddress } from '../../utils';
+import {
+	getMetadataClient,
+	getQueryClient,
+	type ValuesOptional,
+} from '../_internal';
+import type { StandardQueryOptions } from '../types/query';
+import { marketplaceConfigOptions } from './marketplaceConfig';
+
+export interface FetchFiltersParams {
+	chainId: number;
+	collectionAddress: string;
+	showAllFilters?: boolean;
+	excludePropertyValues?: boolean;
+	config: SdkConfig;
+}
+
+/**
+ * Fetches collection filters from the Metadata API with optional marketplace filtering
+ */
+export async function fetchFilters(
+	params: FetchFiltersParams,
+): Promise<PropertyFilter[]> {
+	const {
+		chainId,
+		collectionAddress,
+		showAllFilters,
+		excludePropertyValues,
+		config,
+	} = params;
+
+	const metadataClient = getMetadataClient(config);
+
+	const filters = await metadataClient
+		.getTokenMetadataPropertyFilters({
+			chainID: chainId.toString(),
+			contractAddress: collectionAddress,
+			excludeProperties: [],
+			excludePropertyValues,
+		})
+		.then((resp) => resp.filters);
+
+	if (showAllFilters) return filters;
+
+	const queryClient = getQueryClient();
+	const marketplaceConfig = await queryClient.fetchQuery(
+		marketplaceConfigOptions(config),
+	);
+	const collectionFilters = marketplaceConfig.market.collections.find((c) =>
+		compareAddress(c.itemsAddress, collectionAddress),
+	)?.filterSettings;
+
+	if (
+		!collectionFilters?.exclusions ||
+		collectionFilters.exclusions.length === 0 ||
+		!collectionFilters.filterOrder ||
+		collectionFilters.filterOrder.length === 0
+	)
+		return filters;
+
+	const { filterOrder, exclusions } = collectionFilters;
+
+	const sortedFilters = filters.toSorted((a, b) => {
+		const aIndex =
+			filterOrder.indexOf(a.name) > -1
+				? filterOrder.indexOf(a.name)
+				: filterOrder.length;
+		const bIndex =
+			filterOrder.indexOf(b.name) > -1
+				? filterOrder.indexOf(b.name)
+				: filterOrder.length;
+		return aIndex - bIndex;
+	});
+
+	const filteredResults = sortedFilters.reduce<PropertyFilter[]>(
+		(acc, filter) => {
+			const exclusionRule = exclusions.find((rule) => rule.key === filter.name);
+
+			if (!exclusionRule) {
+				acc.push(filter);
+				return acc;
+			}
+
+			if (exclusionRule.condition === FilterCondition.ENTIRE_KEY) {
+				return acc;
+			}
+
+			if (
+				exclusionRule.condition === FilterCondition.SPECIFIC_VALUE &&
+				exclusionRule.value
+			) {
+				const filteredValues =
+					filter.values?.filter((value) => value !== exclusionRule.value) || [];
+				if (filteredValues.length > 0) {
+					acc.push({ ...filter, values: filteredValues });
+				}
+			}
+
+			return acc;
+		},
+		[],
+	);
+
+	return filteredResults;
+}
+
+export type FiltersQueryOptions = ValuesOptional<FetchFiltersParams> & {
+	query?: StandardQueryOptions;
+};
+
+export function filtersQueryOptions(params: FiltersQueryOptions) {
+	const enabled = Boolean(
+		params.chainId &&
+			params.collectionAddress &&
+			params.config &&
+			(params.query?.enabled ?? true),
+	);
+
+	return queryOptions({
+		queryKey: ['filters', params],
+		queryFn: () =>
+			fetchFilters({
+				// 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!,
+				showAllFilters: params.showAllFilters,
+				excludePropertyValues: params.excludePropertyValues,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				config: params.config!,
+			}),
+		...params.query,
+		enabled,
+	});
+}

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

@@ -2,11 +2,14 @@ export * from './balanceOfCollectible';
 export * from './collectible';
 export * from './collectionDetails';
 export * from './countOfPrimarySaleItems';
+export * from './currency';
 export * from './floorOrder';
 export * from './highestOffer';
 export * from './inventory';
 export * from './listBalances';
 export * from './listCollectibles';
+export * from './listCollections';
 export * from './listTokenMetadata';
 export * from './lowestListing';
 export * from './marketCurrencies';
+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: [
 					{