@0xsequence/marketplace-sdk 0.8.12 → 0.10.0

package/src/react/hooks/useCheckoutOptions.tsx

@@ -1,66 +1,96 @@
-import { queryOptions, useQuery } from '@tanstack/react-query';
-import type { Hex } from 'viem';
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import type { Address } from 'viem';
 import { useAccount } from 'wagmi';
-import { z } from 'zod';
-import type { SdkConfig } from '../../types';
+import type { MarketplaceKind, Optional } from '../_internal';
 import {
-	AddressSchema,
-	MarketplaceKind,
-	QueryArgSchema,
-	getMarketplaceClient,
-} from '../_internal';
+	type CheckoutOptionsQueryOptions,
+	checkoutOptionsQueryOptions,
+	type FetchCheckoutOptionsParams,
+} from '../queries/checkoutOptions';
 import { useConfig } from './useConfig';
 
-const UseCheckoutOptionsSchema = z.object({
-	chainId: z.number(),
-	orders: z.array(
-		z.object({
-			collectionAddress: AddressSchema,
-			orderId: z.string(),
-			marketplace: z.nativeEnum(MarketplaceKind),
-		}),
-	),
-	query: QueryArgSchema,
-});
+export type UseCheckoutOptionsParams = Optional<
+	CheckoutOptionsQueryOptions,
+	'config' | 'walletAddress'
+>;
 
-export type UseCheckoutOptionsArgs = z.infer<typeof UseCheckoutOptionsSchema>;
+/**
+ * Hook to fetch checkout options for marketplace orders
+ *
+ * Retrieves checkout options including available payment methods, fees, and transaction details
+ * for a set of marketplace orders. Requires a connected wallet to calculate wallet-specific options.
+ *
+ * @param params - Configuration parameters
+ * @param params.chainId - The chain ID (must be number, e.g., 1 for Ethereum, 137 for Polygon)
+ * @param params.orders - Array of orders to checkout containing collection address, order ID, and marketplace
+ * @param params.additionalFee - Additional fee to include in checkout (defaults to 0)
+ * @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 } = useCheckoutOptions({
+ *   chainId: 137,
+ *   orders: [{
+ *     collectionAddress: '0x1234...',
+ *     orderId: '123',
+ *     marketplace: MarketplaceKind.sequence_marketplace_v2
+ *   }],
+ *   additionalFee: 0
+ * })
+ * ```
+ *
+ * @example
+ * With custom query options:
+ * ```typescript
+ * const { data: checkoutOptions } = useCheckoutOptions({
+ *   chainId: 1,
+ *   orders: orders,
+ *   query: {
+ *     enabled: orders.length > 0,
+ *     staleTime: 30000
+ *   }
+ * })
+ * ```
+ */
+export function useCheckoutOptions(params: UseCheckoutOptionsParams) {
+	const { address } = useAccount();
+	const defaultConfig = useConfig();
 
-export type UseCheckoutOptionsReturn = Awaited<
-	ReturnType<typeof fetchCheckoutOptions>
->;
+	const { config = defaultConfig, ...rest } = params;
 
-const fetchCheckoutOptions = async (
-	args: UseCheckoutOptionsArgs & { walletAddress: Hex },
-	config: SdkConfig,
-) => {
-	const marketplaceClient = getMarketplaceClient(config);
-	return marketplaceClient.checkoutOptionsMarketplace({
-		chainId: String(args.chainId),
-		wallet: args.walletAddress,
-		orders: args.orders.map((order) => ({
-			contractAddress: order.collectionAddress,
-			orderId: order.orderId,
-			marketplace: order.marketplace,
-		})),
-		additionalFee: 0, //TODO: add additional fee
+	const queryOptions = checkoutOptionsQueryOptions({
+		config,
+		walletAddress: address as Address,
+		...rest,
 	});
-};
 
-export const checkoutOptionsOptions = (
-	args: UseCheckoutOptionsArgs & { walletAddress: Hex },
-	config: SdkConfig,
-) => {
-	return queryOptions({
-		queryKey: ['checkoutOptions', args],
-		queryFn: () => fetchCheckoutOptions(args, config),
+	return useQuery({
+		...queryOptions,
 	});
-};
+}
 
-export const useCheckoutOptions = (args: UseCheckoutOptionsArgs) => {
-	const { address } = useAccount();
-	const config = useConfig();
-	return useQuery(
-		// biome-ignore lint/style/noNonNullAssertion: <explanation>
-		checkoutOptionsOptions({ walletAddress: address!, ...args }, config),
-	);
+export { checkoutOptionsQueryOptions };
+
+export type { FetchCheckoutOptionsParams, CheckoutOptionsQueryOptions };
+
+// Legacy export for backward compatibility
+export type UseCheckoutOptionsArgs = {
+	chainId: number;
+	orders: Array<{
+		collectionAddress: string;
+		orderId: string;
+		marketplace: MarketplaceKind;
+	}>;
+	query?: {
+		enabled?: boolean;
+	};
 };
+
+export type UseCheckoutOptionsReturn = Awaited<
+	ReturnType<typeof import('../queries/checkoutOptions').fetchCheckoutOptions>
+>;

package/src/react/hooks/useCheckoutOptionsSalesContract.tsx

@@ -1,67 +1,108 @@
-import { queryOptions, skipToken, useQuery } from '@tanstack/react-query';
-import type { Hex } from 'viem';
+'use client';
+
+import { skipToken, useQuery } from '@tanstack/react-query';
+import type { Address } from 'viem';
 import { useAccount } from 'wagmi';
-import type { SdkConfig } from '../../types';
+import type { CheckoutOptionsItem, Optional } from '../_internal';
 import {
-	type CheckoutOptionsSalesContractArgs,
-	getMarketplaceClient,
-} from '../_internal';
+	type CheckoutOptionsSalesContractQueryOptions,
+	checkoutOptionsSalesContractQueryOptions,
+	type FetchCheckoutOptionsSalesContractParams,
+	type fetchCheckoutOptionsSalesContract,
+} from '../queries/checkoutOptionsSalesContract';
 import { useConfig } from './useConfig';
 
-type UseCheckoutOptionsSalesContractArgs = Omit<
-	CheckoutOptionsSalesContractArgs,
-	'wallet' | 'chainId'
-> & { chainId: number };
+export type UseCheckoutOptionsSalesContractParams = Optional<
+	CheckoutOptionsSalesContractQueryOptions,
+	'config' | 'walletAddress'
+>;
 
-const fetchCheckoutOptionsSalesContract = async (
-	args: CheckoutOptionsSalesContractArgs,
-	config: SdkConfig,
-) => {
-	const marketplaceClient = getMarketplaceClient(config);
-	return marketplaceClient.checkoutOptionsSalesContract({
-		chainId: args.chainId,
-		wallet: args.wallet,
-		contractAddress: args.contractAddress,
-		collectionAddress: args.collectionAddress,
-		items: args.items,
-	});
-};
+/**
+ * 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,
+				},
+	);
 
-export const checkoutOptionsSalesContractOptions = (
-	args:
-		| (UseCheckoutOptionsSalesContractArgs & { wallet?: Hex })
-		| typeof skipToken,
-	config: SdkConfig,
-) => {
-	return queryOptions({
-		queryKey: ['checkoutOptionsSalesContract', args],
-		queryFn:
-			skipToken === args
-				? skipToken
-				: () =>
-						fetchCheckoutOptionsSalesContract(
-							{
-								chainId: String(args.chainId),
-								// biome-ignore lint/style/noNonNullAssertion: <explanation>
-								wallet: args.wallet!,
-								contractAddress: args.contractAddress,
-								collectionAddress: args.collectionAddress,
-								items: args.items,
-							},
-							config,
-						),
+	return useQuery({
+		...queryOptions,
 	});
+}
+
+export { checkoutOptionsSalesContractQueryOptions };
+
+export type {
+	FetchCheckoutOptionsSalesContractParams,
+	CheckoutOptionsSalesContractQueryOptions,
 };
 
-export const useCheckoutOptionsSalesContract = (
-	args: UseCheckoutOptionsSalesContractArgs | typeof skipToken,
-) => {
-	const { address } = useAccount();
-	const config = useConfig();
-	return useQuery(
-		checkoutOptionsSalesContractOptions(
-			skipToken === args ? skipToken : { ...args, wallet: address },
-			config,
-		),
-	);
+// 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/useCollectible.tsx

@@ -1,54 +1,69 @@
-import { queryOptions, useQuery } from '@tanstack/react-query';
-import { z } from 'zod';
-import type { SdkConfig } from '../../types';
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import type { Optional } from '../_internal';
 import {
-	AddressSchema,
-	QueryArgSchema,
-	collectableKeys,
-	getMetadataClient,
-} from '../_internal';
+	type CollectibleQueryOptions,
+	collectibleQueryOptions,
+	type FetchCollectibleParams,
+} from '../queries/collectible';
 import { useConfig } from './useConfig';
 
-const UseCollectibleSchema = z.object({
-	chainId: z.number(),
-	collectionAddress: AddressSchema,
-	collectibleId: z.string().optional(),
-	query: QueryArgSchema,
-});
-
-export type UseCollectibleArgs = z.infer<typeof UseCollectibleSchema>;
-
-export type UseCollectibleReturn = Awaited<ReturnType<typeof fetchCollectible>>;
-
-const fetchCollectible = async (
-	args: UseCollectibleArgs,
-	config: SdkConfig,
-) => {
-	const parsedArgs = UseCollectibleSchema.parse(args);
-	const metadataClient = getMetadataClient(config);
-	const tokenIds = parsedArgs.collectibleId ? [parsedArgs.collectibleId] : [];
-
-	return metadataClient
-		.getTokenMetadata({
-			chainID: parsedArgs.chainId.toString(),
-			contractAddress: parsedArgs.collectionAddress,
-			tokenIDs: tokenIds,
-		})
-		.then((resp) => resp.tokenMetadata[0]);
-};
-
-export const collectibleOptions = (
-	args: UseCollectibleArgs,
-	config: SdkConfig,
-) => {
-	return queryOptions({
-		...args.query,
-		queryKey: [...collectableKeys.details, args, config],
-		queryFn: () => fetchCollectible(args, config),
+export type UseCollectibleParams = Optional<CollectibleQueryOptions, 'config'>;
+
+/**
+ * Hook to fetch metadata for a specific collectible
+ *
+ * This hook retrieves metadata for an individual NFT from a collection,
+ * including properties like name, description, image, attributes, etc.
+ *
+ * @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.collectibleId - The token ID of the collectible
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing the collectible metadata
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data: collectible, isLoading } = useCollectible({
+ *   chainId: 137,
+ *   collectionAddress: '0x631998e91476da5b870d741192fc5cbc55f5a52e',
+ *   collectibleId: '12345'
+ * })
+ * ```
+ *
+ * @example
+ * With custom query options:
+ * ```typescript
+ * const { data } = useCollectible({
+ *   chainId: 137,
+ *   collectionAddress: '0x631998e91476da5b870d741192fc5cbc55f5a52e',
+ *   collectibleId: '12345',
+ *   query: {
+ *     enabled: Boolean(collectionAddress && tokenId),
+ *     staleTime: 30_000
+ *   }
+ * })
+ * ```
+ */
+export function useCollectible(params: UseCollectibleParams) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = collectibleQueryOptions({
+		config,
+		...rest,
 	});
-};
 
-export const useCollectible = (args: UseCollectibleArgs) => {
-	const config = useConfig();
-	return useQuery(collectibleOptions(args, config));
-};
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { collectibleQueryOptions };
+
+export type { FetchCollectibleParams, CollectibleQueryOptions };

package/src/react/hooks/useCollection.tsx

@@ -1,17 +1,66 @@
+'use client';
+
 import { useQuery } from '@tanstack/react-query';
-import type { z } from 'zod';
+import type { Optional } from '../_internal';
 import {
-	type UseCollectionSchema,
-	collectionOptions,
-	type fetchCollection,
-} from './options/collectionOptions';
+	type CollectionQueryOptions,
+	collectionQueryOptions,
+	type FetchCollectionParams,
+} from '../queries/collection';
 import { useConfig } from './useConfig';
 
-export type UseCollectionArgs = z.input<typeof UseCollectionSchema>;
+export type UseCollectionParams = Optional<CollectionQueryOptions, 'config'>;
+
+/**
+ * Hook to fetch collection information from the metadata API
+ *
+ * Retrieves basic contract information including name, symbol, type,
+ * and extension data for a given collection contract.
+ *
+ * @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.query - Optional React Query configuration
+ *
+ * @returns Query result containing contract information
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data, isLoading } = useCollection({
+ *   chainId: 137,
+ *   collectionAddress: '0x...'
+ * })
+ * ```
+ *
+ * @example
+ * With custom query options:
+ * ```typescript
+ * const { data, isLoading } = useCollection({
+ *   chainId: 1,
+ *   collectionAddress: '0x...',
+ *   query: {
+ *     refetchInterval: 30000,
+ *     enabled: userWantsToFetch
+ *   }
+ * })
+ * ```
+ */
+export function useCollection(params: UseCollectionParams) {
+	const defaultConfig = useConfig();
+
+	const { config = defaultConfig, ...rest } = params;
+
+	const queryOptions = collectionQueryOptions({
+		config,
+		...rest,
+	});
+
+	return useQuery({
+		...queryOptions,
+	});
+}
 
-export type UseCollectionReturn = Awaited<ReturnType<typeof fetchCollection>>;
+export { collectionQueryOptions };
 
-export const useCollection = (args: UseCollectionArgs) => {
-	const config = useConfig();
-	return useQuery(collectionOptions(args, config));
-};
+export type { FetchCollectionParams, CollectionQueryOptions };