@0xsequence/marketplace-sdk 0.9.0 → 1.0.0

package/src/react/hooks/utils/useCheckoutOptionsSalesContract.tsx

@@ -0,0 +1,108 @@
+'use client';
+
+import { skipToken, useQuery } from '@tanstack/react-query';
+import type { Address } from 'viem';
+import { useAccount } from 'wagmi';
+import type { CheckoutOptionsItem, Optional } from '../../_internal';
+import {
+	type CheckoutOptionsSalesContractQueryOptions,
+	checkoutOptionsSalesContractQueryOptions,
+	type FetchCheckoutOptionsSalesContractParams,
+	type fetchCheckoutOptionsSalesContract,
+} from '../../queries/checkoutOptionsSalesContract';
+import { useConfig } from '../config/useConfig';
+
+export type UseCheckoutOptionsSalesContractParams = Optional<
+	CheckoutOptionsSalesContractQueryOptions,
+	'config' | 'walletAddress'
+>;
+
+/**
+ * Hook to fetch checkout options for sales contract items
+ *
+ * Retrieves checkout options including available payment methods, fees, and transaction details
+ * for items from a sales contract. Requires a connected wallet to calculate wallet-specific options.
+ *
+ * @param params - Configuration parameters or skipToken to skip the query
+ * @param params.chainId - The chain ID (must be number, e.g., 1 for Ethereum, 137 for Polygon)
+ * @param params.contractAddress - The sales contract address
+ * @param params.collectionAddress - The collection contract address
+ * @param params.items - Array of items to purchase with tokenId and quantity
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing checkout options with payment methods and fees
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data: checkoutOptions, isLoading } = useCheckoutOptionsSalesContract({
+ *   chainId: 137,
+ *   contractAddress: '0x1234...',
+ *   collectionAddress: '0x5678...',
+ *   items: [{
+ *     tokenId: '1',
+ *     quantity: '1'
+ *   }]
+ * })
+ * ```
+ *
+ * @example
+ * With skipToken to conditionally skip:
+ * ```typescript
+ * const { data: checkoutOptions } = useCheckoutOptionsSalesContract(
+ *   items.length > 0 ? {
+ *     chainId: 1,
+ *     contractAddress: contractAddress,
+ *     collectionAddress: collectionAddress,
+ *     items: items
+ *   } : skipToken
+ * )
+ * ```
+ */
+export function useCheckoutOptionsSalesContract(
+	params: UseCheckoutOptionsSalesContractParams | typeof skipToken,
+) {
+	const { address } = useAccount();
+	const defaultConfig = useConfig();
+
+	const queryOptions = checkoutOptionsSalesContractQueryOptions(
+		params === skipToken
+			? {
+					config: defaultConfig,
+					walletAddress: address as Address,
+					chainId: 0,
+					contractAddress: '',
+					collectionAddress: '',
+					items: [],
+					query: { enabled: false },
+				}
+			: {
+					config: defaultConfig,
+					walletAddress: address as Address,
+					...params,
+				},
+	);
+
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { checkoutOptionsSalesContractQueryOptions };
+
+export type {
+	FetchCheckoutOptionsSalesContractParams,
+	CheckoutOptionsSalesContractQueryOptions,
+};
+
+// Legacy exports for backward compatibility
+export type UseCheckoutOptionsSalesContractArgs = {
+	chainId: number;
+	contractAddress: string;
+	collectionAddress: string;
+	items: Array<CheckoutOptionsItem>;
+};
+
+export type UseCheckoutOptionsSalesContractReturn = Awaited<
+	ReturnType<typeof fetchCheckoutOptionsSalesContract>
+>;

package/src/react/hooks/{__tests__ → utils}/useComparePrices.test.tsx

@@ -7,7 +7,7 @@ import {
 	mockCurrencies,
 	mockMarketplaceEndpoint,
 } from '../../_internal/api/__mocks__/marketplace.msw';
-import { useComparePrices } from '../useComparePrices';
+import { useComparePrices } from '../utils/useComparePrices';
 
 describe('useComparePrices', () => {
 	const defaultArgs = {

package/src/react/hooks/utils/useComparePrices.tsx

@@ -0,0 +1,102 @@
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import type { Address } from 'viem';
+import type { Optional } from '../../_internal';
+import {
+	type ComparePricesQueryOptions,
+	comparePricesQueryOptions,
+	type FetchComparePricesParams,
+} from '../../queries/comparePrices';
+import { useConfig } from '../config/useConfig';
+
+export type UseComparePricesParams = Optional<
+	ComparePricesQueryOptions,
+	'config'
+>;
+
+/**
+ * Hook to compare prices between different currencies by converting both to USD
+ *
+ * Compares two prices by converting both to USD using real-time exchange rates
+ * and returns the percentage difference with comparison status.
+ *
+ * @param params - Configuration parameters
+ * @param params.chainId - The chain ID (must be number, e.g., 1 for Ethereum, 137 for Polygon)
+ * @param params.priceAmountRaw - The raw amount of the first price (wei format)
+ * @param params.priceCurrencyAddress - The currency address of the first price
+ * @param params.compareToPriceAmountRaw - The raw amount of the second price to compare against (wei format)
+ * @param params.compareToPriceCurrencyAddress - The currency address of the second price
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing percentage difference and comparison status
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data: comparison, isLoading } = useComparePrices({
+ *   chainId: 1,
+ *   priceAmountRaw: '1000000000000000000', // 1 ETH in wei
+ *   priceCurrencyAddress: '0x0000000000000000000000000000000000000000', // ETH
+ *   compareToPriceAmountRaw: '2000000000', // 2000 USDC in wei (6 decimals)
+ *   compareToPriceCurrencyAddress: '0xA0b86a33E6B8DbF5E71Eaa9bfD3F6fD8e8Be3F69' // USDC
+ * })
+ *
+ * if (data) {
+ *   console.log(`${data.percentageDifferenceFormatted}% ${data.status}`);
+ *   // e.g., "25.50% above" or "10.25% below"
+ * }
+ * ```
+ *
+ * @example
+ * With custom query options:
+ * ```typescript
+ * const { data: comparison } = useComparePrices({
+ *   chainId: 137,
+ *   priceAmountRaw: price1,
+ *   priceCurrencyAddress: currency1Address,
+ *   compareToPriceAmountRaw: price2,
+ *   compareToPriceCurrencyAddress: currency2Address,
+ *   query: {
+ *     enabled: Boolean(price1 && price2),
+ *     refetchInterval: 30000 // Refresh every 30 seconds
+ *   }
+ * })
+ * ```
+ */
+export function useComparePrices(params: UseComparePricesParams) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = comparePricesQueryOptions({
+		config,
+		...rest,
+	});
+
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { comparePricesQueryOptions };
+
+export type { FetchComparePricesParams, ComparePricesQueryOptions };
+
+// Legacy exports for backward compatibility
+export type UseComparePricesArgs = {
+	chainId: number;
+	priceAmountRaw: string;
+	priceCurrencyAddress: Address;
+	compareToPriceAmountRaw: string;
+	compareToPriceCurrencyAddress: Address;
+	query?: {
+		enabled?: boolean;
+	};
+};
+
+export type UseComparePricesReturn = {
+	percentageDifference: number;
+	percentageDifferenceFormatted: string;
+	status: 'above' | 'same' | 'below';
+};

package/src/react/hooks/{__tests__ → utils}/useConvertPriceToUSD.test.tsx

@@ -6,11 +6,11 @@ import {
 	mockCurrencies,
 	mockMarketplaceEndpoint,
 } from '../../_internal/api/__mocks__/marketplace.msw';
-import type { UseConvertPriceToUSDArgs } from '../useConvertPriceToUSD';
-import { useConvertPriceToUSD } from '../useConvertPriceToUSD';
+import type { UseConvertPriceToUSDParams } from '../utils/useConvertPriceToUSD';
+import { useConvertPriceToUSD } from '../utils/useConvertPriceToUSD';
 
 describe('useConvertPriceToUSD', () => {
-	const defaultArgs: UseConvertPriceToUSDArgs = {
+	const defaultArgs: UseConvertPriceToUSDParams = {
 		chainId: 1,
 		currencyAddress: zeroAddress,
 		amountRaw: '1000000000000000000', // 1 ETH
@@ -113,7 +113,7 @@ describe('useConvertPriceToUSD', () => {
 		);
 
 		const { result, rerender } = renderHook(
-			(args: UseConvertPriceToUSDArgs = defaultArgs) =>
+			(args: UseConvertPriceToUSDParams = defaultArgs) =>
 				useConvertPriceToUSD(args),
 		);
 

package/src/react/hooks/utils/useConvertPriceToUSD.tsx

@@ -0,0 +1,96 @@
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import type { Address } from 'viem';
+import type { Optional } from '../../_internal';
+import {
+	type ConvertPriceToUSDQueryOptions,
+	type ConvertPriceToUSDReturn,
+	convertPriceToUSDQueryOptions,
+	type FetchConvertPriceToUSDParams,
+} from '../../queries/convertPriceToUSD';
+import { useConfig } from '../config/useConfig';
+
+export type UseConvertPriceToUSDParams = Optional<
+	ConvertPriceToUSDQueryOptions,
+	'config'
+>;
+
+/**
+ * Hook to convert a price amount from a specific currency to USD
+ *
+ * Converts cryptocurrency amounts to their USD equivalent using current exchange rates.
+ * Fetches currency data and calculates the USD value based on the provided amount
+ * and currency address.
+ *
+ * @param params - Configuration parameters
+ * @param params.chainId - The chain ID (must be number, e.g., 1 for Ethereum, 137 for Polygon)
+ * @param params.currencyAddress - The currency contract address to convert from
+ * @param params.amountRaw - The raw amount in smallest units (e.g., wei for ETH)
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing USD amount and formatted USD amount
+ *
+ * @example
+ * Basic ETH to USD conversion:
+ * ```typescript
+ * const { data: conversion, isLoading } = useConvertPriceToUSD({
+ *   chainId: 1,
+ *   currencyAddress: '0x0000000000000000000000000000000000000000', // ETH
+ *   amountRaw: '1000000000000000000' // 1 ETH in wei
+ * })
+ *
+ * if (data) {
+ *   console.log(`$${data.usdAmountFormatted}`); // e.g., "$2000.00"
+ *   console.log(data.usdAmount); // e.g., 2000
+ * }
+ * ```
+ *
+ * @example
+ * ERC-20 token conversion with conditional enabling:
+ * ```typescript
+ * const { data: conversion } = useConvertPriceToUSD({
+ *   chainId: 137,
+ *   currencyAddress: '0x2791bca1f2de4661ed88a30c99a7a9449aa84174', // USDC on Polygon
+ *   amountRaw: '1000000', // 1 USDC (6 decimals)
+ *   query: {
+ *     enabled: Boolean(userHasTokens),
+ *     refetchInterval: 30000 // Update price every 30 seconds
+ *   }
+ * })
+ * ```
+ */
+export function useConvertPriceToUSD(params: UseConvertPriceToUSDParams) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = convertPriceToUSDQueryOptions({
+		config,
+		...rest,
+	});
+
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { convertPriceToUSDQueryOptions };
+
+export type {
+	FetchConvertPriceToUSDParams,
+	ConvertPriceToUSDQueryOptions,
+	ConvertPriceToUSDReturn,
+};
+
+// Legacy exports for backward compatibility
+export type UseConvertPriceToUSDArgs = {
+	chainId: number;
+	currencyAddress: Address;
+	amountRaw: string;
+	query?: {
+		enabled?: boolean;
+	};
+};
+
+export type UseConvertPriceToUSDReturn = ConvertPriceToUSDReturn;

package/src/react/hooks/utils/useEnsureCorrectChain.ts

@@ -0,0 +1,74 @@
+import { useCallback } from 'react';
+import { useAccount, useSwitchChain } from 'wagmi';
+import { ChainSwitchUserRejectedError } from '../../../utils/_internal/error/transaction';
+import { useSwitchChainModal } from '../../ui/modals/_internal/components/switchChainModal';
+import { useConnectorMetadata } from '../config/useConnectorMetadata';
+
+export const useEnsureCorrectChain = () => {
+	const { chainId: currentChainId } = useAccount();
+	const { switchChain, switchChainAsync } = useSwitchChain();
+	const { show: showSwitchChainModal } = useSwitchChainModal();
+	const { isWaaS } = useConnectorMetadata();
+
+	const ensureCorrectChainAsync = useCallback(
+		async (targetChainId: number) => {
+			if (currentChainId === targetChainId) {
+				return Promise.resolve();
+			}
+			if (isWaaS) {
+				return switchChainAsync({ chainId: targetChainId });
+			}
+
+			return new Promise((resolve, reject) => {
+				showSwitchChainModal({
+					chainIdToSwitchTo: targetChainId,
+					onSuccess: () => resolve(targetChainId),
+					onError: (error) => reject(error),
+					onClose: () => reject(new ChainSwitchUserRejectedError()),
+				});
+			});
+		},
+		[currentChainId, isWaaS, switchChainAsync, showSwitchChainModal],
+	);
+
+	const ensureCorrectChain = useCallback(
+		(
+			targetChainId: number,
+			callbacks?: {
+				onSuccess?: () => void;
+				onError?: (error: Error) => void;
+				onClose?: () => void;
+			},
+		) => {
+			if (currentChainId === targetChainId) {
+				callbacks?.onSuccess?.();
+				return;
+			}
+
+			if (isWaaS) {
+				switchChain(
+					{ chainId: targetChainId },
+					{
+						onSuccess: callbacks?.onSuccess,
+						onError: callbacks?.onError,
+					},
+				);
+				return;
+			}
+
+			showSwitchChainModal({
+				chainIdToSwitchTo: targetChainId,
+				onSuccess: callbacks?.onSuccess,
+				onError: callbacks?.onError,
+				onClose: callbacks?.onClose,
+			});
+		},
+		[currentChainId, isWaaS, switchChain, showSwitchChainModal],
+	);
+
+	return {
+		ensureCorrectChain,
+		ensureCorrectChainAsync,
+		currentChainId,
+	};
+};

package/src/react/hooks/{__tests__ → utils}/useRoyalty.test.tsx

@@ -1,7 +1,7 @@
 import { renderHook, waitFor } from '@test';
 import { describe, expect, it } from 'vitest';
 import { TEST_COLLECTIBLE } from '../../../../test/const';
-import { useRoyalty } from '../useRoyalty';
+import { useRoyalty } from './useRoyalty';
 
 describe('useRoyaltyPercentage', () => {
 	it('should fetch royalty percentage successfully', async () => {

package/src/react/hooks/{useRoyalty.tsx → utils/useRoyalty.tsx}

@@ -2,9 +2,9 @@
 
 import type { Address } from 'viem';
 import { useReadContract } from 'wagmi';
-import { EIP2981_ABI } from '../../utils';
-import type { QueryArg } from '../_internal';
-import { collectableKeys } from '../_internal';
+import { EIP2981_ABI } from '../../../utils';
+import type { QueryArg } from '../../_internal';
+import { collectableKeys } from '../../_internal';
 
 export interface UseRoyaltyArgs {
 	chainId: number;

package/src/react/hooks/utils/useSwitchChainWithModal.ts

@@ -0,0 +1,38 @@
+import { useSwitchChain } from 'wagmi';
+import { ChainSwitchUserRejectedError } from '../../../utils/_internal/error/transaction';
+import { useSwitchChainModal } from '../../ui/modals/_internal/components/switchChainModal';
+import { useConnectorMetadata } from '../config/useConnectorMetadata';
+
+export const useSwitchChainWithModal = () => {
+	const { show: showSwitchChainModal } = useSwitchChainModal();
+	const { isWaaS } = useConnectorMetadata();
+	const { switchChainAsync } = useSwitchChain();
+
+	return {
+		switchChainWithModal: async (
+			currentChainId: number,
+			targetChainId: number,
+		) => {
+			const chainIdMismatch = currentChainId !== Number(targetChainId);
+
+			return new Promise((resolve, reject) => {
+				if (chainIdMismatch) {
+					if (isWaaS) {
+						switchChainAsync({ chainId: targetChainId })
+							.then(resolve)
+							.catch(reject);
+					} else {
+						showSwitchChainModal({
+							chainIdToSwitchTo: targetChainId,
+							onSuccess: () => resolve({ chainId: targetChainId }),
+							onError: (error) => reject(error),
+							onClose: () => reject(new ChainSwitchUserRejectedError()),
+						});
+					}
+				} else {
+					resolve({ chainId: targetChainId });
+				}
+			});
+		},
+	};
+};

package/src/react/index.ts

@@ -1,8 +1,7 @@
 export * from './_internal/api/get-query-client';
 export * from './_internal/wagmi/create-config';
 export * from './hooks';
-export * from './hooks/options';
-export * from './provider';
+export * from './providers';
 export * from './queries';
 export * from './types/query';
 export * from './ui/index';

package/src/react/providers/index.tsx

@@ -0,0 +1,110 @@
+'use client';
+
+import { useOpenConnectModal } from '@0xsequence/connect';
+import type { Auth } from '@databeat/tracker';
+import { QueryClientProvider } from '@tanstack/react-query';
+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';
+import { ThemeProvider } from './theme-provider';
+
+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}>
+					<ThemeProvider>
+						<div id={PROVIDER_ID}>{children}</div>
+					</ThemeProvider>
+				</MarketplaceSdkContext.Provider>
+			</MarketplaceQueryClientProvider>
+		);
+	}
+
+	return (
+		<MarketplaceProviderWithSequenceConnect
+			config={config}
+			analytics={analytics}
+		>
+			<ThemeProvider>{children}</ThemeProvider>
+		</MarketplaceProviderWithSequenceConnect>
+	);
+}
+
+export function MarketplaceQueryClientProvider({
+	children,
+}: {
+	children: React.ReactNode;
+}) {
+	const queryClient = getQueryClient();
+	return (
+		<QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+	);
+}
+
+function MarketplaceProviderWithSequenceConnect({
+	config,
+	children,
+	analytics,
+}: MarketplaceSdkProviderProps & { analytics: DatabeatAnalytics }) {
+	const { setOpenConnectModal } = useOpenConnectModal();
+
+	const context: MarketplaceSdkContextType = {
+		...config,
+		openConnectModal: () => setOpenConnectModal(true),
+		analytics,
+	};
+
+	return (
+		<MarketplaceQueryClientProvider>
+			<MarketplaceSdkContext.Provider value={context}>
+				<div id={PROVIDER_ID}>{children}</div>
+			</MarketplaceSdkContext.Provider>
+		</MarketplaceQueryClientProvider>
+	);
+}

package/src/react/providers/modal-provider.tsx

@@ -0,0 +1,43 @@
+import { SequenceCheckoutProvider } from '@0xsequence/checkout';
+import { observer } from '@legendapp/state/react';
+import type { ReactNode } from 'react';
+import { useConfig } from '../hooks';
+import SwitchChainModal from '../ui/modals/_internal/components/switchChainModal';
+import TransactionStatusModal from '../ui/modals/_internal/components/transactionStatusModal';
+import { BuyModal } from '../ui/modals/BuyModal/components/Modal';
+import { CreateListingModal } from '../ui/modals/CreateListingModal/Modal';
+import { MakeOfferModal } from '../ui/modals/MakeOfferModal/Modal';
+import { SellModal } from '../ui/modals/SellModal/Modal';
+import SuccessfulPurchaseModal from '../ui/modals/SuccessfulPurchaseModal';
+import { TransferModal } from '../ui/modals/TransferModal';
+import { ShadowRoot } from './shadow-root';
+
+interface ModalProviderProps {
+	children?: ReactNode;
+}
+
+export const ModalProvider = observer(({ children }: ModalProviderProps) => {
+	const { shadowDom, experimentalShadowDomCssOverride } = useConfig();
+
+	return (
+		<>
+			{children}
+			<SequenceCheckoutProvider>
+				<ShadowRoot
+					enabled={shadowDom ?? true}
+					customCSS={experimentalShadowDomCssOverride}
+				>
+					<CreateListingModal />
+					<MakeOfferModal />
+					<TransferModal />
+					<SellModal />
+					<BuyModal />
+					<SuccessfulPurchaseModal />
+					{/* Helper modals */}
+					<SwitchChainModal />
+					<TransactionStatusModal />
+				</ShadowRoot>
+			</SequenceCheckoutProvider>
+		</>
+	);
+});

package/src/react/{__tests__ → providers}/provider.test.tsx

@@ -1,12 +1,13 @@
 'use client';
 
 import * as matchers from '@testing-library/jest-dom/matchers';
-import { render, screen } from '@testing-library/react';
+import { render as rtlRender, screen } from '@testing-library/react';
 import { useContext } from 'react';
 import { beforeEach, describe, expect, it } from 'vitest';
+import { render } from '../../../test/test-utils';
 import type { SdkConfig } from '../../types';
 import { InvalidProjectAccessKeyError } from '../../utils/_internal/error/config';
-import { MarketplaceProvider, MarketplaceSdkContext } from '../provider';
+import { MarketplaceProvider, MarketplaceSdkContext } from '.';
 
 expect.extend(matchers);
 
@@ -33,8 +34,8 @@ describe('MarketplaceProvider', () => {
 		};
 
 		expect(() =>
-			render(
-				<MarketplaceProvider config={invalidConfig}>
+			rtlRender(
+				<MarketplaceProvider config={invalidConfig} openConnectModal={() => {}}>
 					<div>Test</div>
 				</MarketplaceProvider>,
 			),