@0xsequence/marketplace-sdk 0.8.12 → 0.10.0

package/src/react/queries/collectible.ts

@@ -0,0 +1,66 @@
+import type { GetTokenMetadataArgs } from '@0xsequence/metadata';
+import { queryOptions } from '@tanstack/react-query';
+import type { SdkConfig } from '../../types';
+import { getMetadataClient, type ValuesOptional } from '../_internal';
+import { collectableKeys } from '../_internal/api/query-keys';
+import type { StandardQueryOptions } from '../types/query';
+
+export interface FetchCollectibleParams
+	extends Omit<
+		GetTokenMetadataArgs,
+		'chainID' | 'contractAddress' | 'tokenIDs'
+	> {
+	chainId: number;
+	collectionAddress: string;
+	collectibleId: string;
+	config: SdkConfig;
+}
+
+/**
+ * Fetches collectible metadata from the metadata API
+ */
+export async function fetchCollectible(params: FetchCollectibleParams) {
+	const { collectionAddress, collectibleId, chainId, config } = params;
+
+	const metadataClient = getMetadataClient(config);
+
+	const apiArgs: GetTokenMetadataArgs = {
+		contractAddress: collectionAddress,
+		chainID: String(chainId),
+		tokenIDs: [collectibleId],
+	};
+
+	const result = await metadataClient.getTokenMetadata(apiArgs);
+	return result.tokenMetadata[0];
+}
+
+export type CollectibleQueryOptions = ValuesOptional<FetchCollectibleParams> & {
+	query?: StandardQueryOptions;
+};
+
+export function collectibleQueryOptions(params: CollectibleQueryOptions) {
+	const enabled = Boolean(
+		params.collectionAddress &&
+			params.collectibleId &&
+			params.chainId &&
+			params.config &&
+			(params.query?.enabled ?? true),
+	);
+
+	return queryOptions({
+		queryKey: [...collectableKeys.details, params],
+		queryFn: () =>
+			fetchCollectible({
+				// 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
+				collectibleId: params.collectibleId!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				config: params.config!,
+			}),
+		...params.query,
+		enabled,
+	});
+}

package/src/react/queries/collection.ts

@@ -0,0 +1,55 @@
+import { queryOptions } from '@tanstack/react-query';
+import type { SdkConfig } from '../../types';
+import { getMetadataClient, type ValuesOptional } from '../_internal';
+import { collectionKeys } from '../_internal/api/query-keys';
+import type { StandardQueryOptions } from '../types/query';
+
+export interface FetchCollectionParams {
+	chainId: number;
+	collectionAddress: string;
+	config: SdkConfig;
+}
+
+/**
+ * Fetches collection information from the metadata API
+ */
+export async function fetchCollection(params: FetchCollectionParams) {
+	const { collectionAddress, chainId, config } = params;
+
+	const metadataClient = getMetadataClient(config);
+
+	const result = await metadataClient.getContractInfo({
+		chainID: chainId.toString(),
+		contractAddress: collectionAddress,
+	});
+
+	return result.contractInfo;
+}
+
+export type CollectionQueryOptions = ValuesOptional<FetchCollectionParams> & {
+	query?: StandardQueryOptions;
+};
+
+export function collectionQueryOptions(params: CollectionQueryOptions) {
+	const enabled = Boolean(
+		params.collectionAddress &&
+			params.chainId &&
+			params.config &&
+			(params.query?.enabled ?? true),
+	);
+
+	return queryOptions({
+		queryKey: [...collectionKeys.detail, params],
+		queryFn: () =>
+			fetchCollection({
+				// 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/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/collectionDetails.ts

@@ -0,0 +1,64 @@
+import { queryOptions } from '@tanstack/react-query';
+import type { SdkConfig } from '../../types';
+import { getMarketplaceClient, type ValuesOptional } from '../_internal';
+import type { GetCollectionDetailArgs } from '../_internal/api/marketplace.gen';
+import { collectionKeys } from '../_internal/api/query-keys';
+import type { StandardQueryOptions } from '../types/query';
+
+export interface FetchCollectionDetailsParams
+	extends Omit<GetCollectionDetailArgs, 'chainId' | 'contractAddress'> {
+	chainId: number;
+	collectionAddress: string;
+	config: SdkConfig;
+}
+
+/**
+ * Fetches collection details from the marketplace API
+ */
+export async function fetchCollectionDetails(
+	params: FetchCollectionDetailsParams,
+) {
+	const { collectionAddress, chainId, config, ...additionalApiParams } = params;
+
+	const marketplaceClient = getMarketplaceClient(config);
+
+	const apiArgs: GetCollectionDetailArgs = {
+		contractAddress: collectionAddress,
+		chainId: String(chainId),
+		...additionalApiParams,
+	};
+
+	const result = await marketplaceClient.getCollectionDetail(apiArgs);
+	return result.collection;
+}
+
+export type CollectionDetailsQueryOptions =
+	ValuesOptional<FetchCollectionDetailsParams> & {
+		query?: StandardQueryOptions;
+	};
+
+export function collectionDetailsQueryOptions(
+	params: CollectionDetailsQueryOptions,
+) {
+	const enabled = Boolean(
+		params.collectionAddress &&
+			params.chainId &&
+			params.config &&
+			(params.query?.enabled ?? true),
+	);
+
+	return queryOptions({
+		queryKey: [...collectionKeys.detail, params],
+		queryFn: () =>
+			fetchCollectionDetails({
+				// 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/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/countListingsForCollectible.ts

@@ -0,0 +1,73 @@
+import { queryOptions } from '@tanstack/react-query';
+import type { SdkConfig } from '../../types';
+import { getMarketplaceClient, type ValuesOptional } from '../_internal';
+import type {
+	GetCountOfListingsForCollectibleArgs,
+	OrderFilter,
+} from '../_internal/api/marketplace.gen';
+import { collectableKeys } from '../_internal/api/query-keys';
+import type { StandardQueryOptions } from '../types/query';
+
+export interface FetchCountListingsForCollectibleParams {
+	chainId: number;
+	collectionAddress: string;
+	collectibleId: string;
+	config: SdkConfig;
+	filter?: OrderFilter;
+}
+
+/**
+ * Fetches count of listings for a collectible from the marketplace API
+ */
+export async function fetchCountListingsForCollectible(
+	params: FetchCountListingsForCollectibleParams,
+) {
+	const { collectionAddress, chainId, collectibleId, config, filter } = params;
+
+	const client = getMarketplaceClient(config);
+
+	const apiArgs: GetCountOfListingsForCollectibleArgs = {
+		contractAddress: collectionAddress,
+		chainId: String(chainId),
+		tokenId: collectibleId,
+		filter,
+	};
+
+	const result = await client.getCountOfListingsForCollectible(apiArgs);
+	return result.count;
+}
+
+export type CountListingsForCollectibleQueryOptions =
+	ValuesOptional<FetchCountListingsForCollectibleParams> & {
+		query?: StandardQueryOptions;
+	};
+
+export function countListingsForCollectibleQueryOptions(
+	params: CountListingsForCollectibleQueryOptions,
+) {
+	const enabled = Boolean(
+		params.collectionAddress &&
+			params.chainId &&
+			params.collectibleId &&
+			params.config &&
+			(params.query?.enabled ?? true),
+	);
+
+	return queryOptions({
+		queryKey: [...collectableKeys.listingsCount, params],
+		queryFn: () =>
+			fetchCountListingsForCollectible({
+				// 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
+				collectibleId: params.collectibleId!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				config: params.config!,
+				filter: params.filter,
+			}),
+		...params.query,
+		enabled,
+	});
+}

package/src/react/queries/countOfCollectables.ts

@@ -0,0 +1,83 @@
+import { queryOptions } from '@tanstack/react-query';
+import type { SdkConfig } from '../../types';
+import { getMarketplaceClient, type ValuesOptional } from '../_internal';
+import type {
+	CollectiblesFilter,
+	GetCountOfAllCollectiblesArgs,
+	GetCountOfFilteredCollectiblesArgs,
+	OrderSide,
+} from '../_internal/api/marketplace.gen';
+import { collectableKeys } from '../_internal/api/query-keys';
+import type { StandardQueryOptions } from '../types/query';
+
+export interface FetchCountOfCollectablesParams {
+	chainId: number;
+	collectionAddress: string;
+	config: SdkConfig;
+	filter?: CollectiblesFilter;
+	side?: OrderSide;
+}
+
+/**
+ * Fetches count of collectibles from the marketplace API
+ */
+export async function fetchCountOfCollectables(
+	params: FetchCountOfCollectablesParams,
+) {
+	const { collectionAddress, chainId, config, filter, side } = params;
+
+	const client = getMarketplaceClient(config);
+
+	if (filter && side) {
+		const apiArgs: GetCountOfFilteredCollectiblesArgs = {
+			contractAddress: collectionAddress,
+			chainId: String(chainId),
+			filter,
+			side,
+		};
+
+		const result = await client.getCountOfFilteredCollectibles(apiArgs);
+		return result.count;
+	}
+
+	const apiArgs: GetCountOfAllCollectiblesArgs = {
+		contractAddress: collectionAddress,
+		chainId: String(chainId),
+	};
+
+	const result = await client.getCountOfAllCollectibles(apiArgs);
+	return result.count;
+}
+
+export type CountOfCollectablesQueryOptions =
+	ValuesOptional<FetchCountOfCollectablesParams> & {
+		query?: StandardQueryOptions;
+	};
+
+export function countOfCollectablesQueryOptions(
+	params: CountOfCollectablesQueryOptions,
+) {
+	const enabled = Boolean(
+		params.collectionAddress &&
+			params.chainId &&
+			params.config &&
+			(params.query?.enabled ?? true),
+	);
+
+	return queryOptions({
+		queryKey: [...collectableKeys.counts, params],
+		queryFn: () =>
+			fetchCountOfCollectables({
+				// 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!,
+				filter: params.filter,
+				side: params.side,
+			}),
+		...params.query,
+		enabled,
+	});
+}

package/src/react/queries/countOfPrimarySaleItems.ts

@@ -0,0 +1,48 @@
+import { queryOptions } from '@tanstack/react-query';
+import type { Address } from 'viem';
+import type { SdkConfig } from '../../types';
+import {
+	type GetCountOfPrimarySaleItemsArgs,
+	getMarketplaceClient,
+	type PrimarySaleItemsFilter,
+} from '../_internal';
+
+export interface UseCountOfPrimarySaleItemsArgs
+	extends Omit<
+		GetCountOfPrimarySaleItemsArgs,
+		'chainId' | 'primarySaleContractAddress'
+	> {
+	chainId: number;
+	primarySaleContractAddress: Address;
+	filter?: PrimarySaleItemsFilter;
+	query?: {
+		enabled?: boolean;
+	};
+}
+
+export async function fetchCountOfPrimarySaleItems(
+	args: UseCountOfPrimarySaleItemsArgs,
+	config: SdkConfig,
+) {
+	const marketplaceClient = getMarketplaceClient(config);
+
+	const { chainId, primarySaleContractAddress, filter } = args;
+	const data = await marketplaceClient.getCountOfPrimarySaleItems({
+		chainId: String(chainId),
+		primarySaleContractAddress,
+		filter,
+	});
+
+	return data.count;
+}
+
+export function countOfPrimarySaleItemsOptions(
+	args: UseCountOfPrimarySaleItemsArgs,
+	config: SdkConfig,
+) {
+	return queryOptions({
+		enabled: args.query?.enabled ?? true,
+		queryKey: ['countOfPrimarySaleItems', args],
+		queryFn: () => fetchCountOfPrimarySaleItems(args, config),
+	});
+}