@0xsequence/marketplace-sdk 0.8.11 → 0.9.0

package/src/react/hooks/useListCollectibles.tsx

@@ -1,41 +1,93 @@
+'use client';
+
 import { useInfiniteQuery } from '@tanstack/react-query';
-import { ContractType } from '../../types/api-types';
-import { listCollectiblesOptions } from '../queries/listCollectibles';
-import type { UseListCollectiblesArgs } from '../queries/listCollectibles';
+import type { Optional } from '../_internal';
+import {
+	type FetchListCollectiblesParams,
+	type ListCollectiblesQueryOptions,
+	listCollectiblesQueryOptions,
+} from '../queries/listCollectibles';
 import { useConfig } from './useConfig';
-import { useMarketplaceConfig } from './useMarketplaceConfig';
+
+export type UseListCollectiblesParams = Optional<
+	ListCollectiblesQueryOptions,
+	'config'
+>;
 
 /**
- * Hook to fetch a list of collectibles with pagination support
+ * Hook to fetch a list of collectibles with infinite pagination support
+ *
+ * Fetches collectibles from the marketplace with support for filtering, pagination,
+ * and special handling for shop marketplace types and LAOS721 contracts.
+ *
+ * @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.side - Order side (listing or bid)
+ * @param params.filter - Optional filtering parameters
+ * @param params.isLaos721 - Whether the collection is a LAOS721 contract
+ * @param params.marketplaceType - Type of marketplace (shop, etc.)
+ * @param params.query - Optional React Query configuration
  *
- * @param args - The arguments for fetching the collectibles
- * @returns Infinite query result containing the collectibles data including orders
+ * @returns Infinite query result containing collectibles data with pagination
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data, isLoading, fetchNextPage, hasNextPage } = useListCollectibles({
+ *   chainId: 137,
+ *   collectionAddress: '0x...',
+ *   side: OrderSide.listing
+ * })
+ * ```
  *
  * @example
- * ```tsx
- * const { data, isLoading, error, fetchNextPage } = useListCollectibles({
+ * With filtering:
+ * ```typescript
+ * const { data, fetchNextPage } = useListCollectibles({
  *   chainId: 1,
- *   collectionAddress: '0x123...',
- *   includeMetadata: true,
- *   query: {
- *     enabled: true,
- *     refetchInterval: 10000,
+ *   collectionAddress: '0x...',
+ *   side: OrderSide.listing,
+ *   filter: {
+ *     searchText: 'dragon',
+ *     includeEmpty: false,
+ *     marketplaces: [MarketplaceKind.sequence_marketplace_v2]
  *   }
- * });
+ * })
+ * ```
+ *
+ * @example
+ * For LAOS721 collections:
+ * ```typescript
+ * const { data } = useListCollectibles({
+ *   chainId: 137,
+ *   collectionAddress: '0x...',
+ *   side: OrderSide.listing,
+ *   isLaos721: true,
+ *   filter: {
+ *     inAccounts: ['0x...']
+ *   }
+ * })
  * ```
  */
-export function useListCollectibles(args: UseListCollectiblesArgs) {
-	const config = useConfig();
-	const { data: marketplaceConfig } = useMarketplaceConfig();
+export function useListCollectibles(params: UseListCollectiblesParams) {
+	const defaultConfig = useConfig();
 
-	const isLaos721 =
-		marketplaceConfig?.market.collections.find(
-			(collection) => collection.itemsAddress === args.collectionAddress,
-		)?.contractType === ContractType.LAOSERC721;
+	const { config = defaultConfig, ...rest } = params;
 
-	if (isLaos721) {
-		args.isLaos721 = true;
-	}
+	const queryOptions = listCollectiblesQueryOptions({
+		config,
+		...rest,
+	});
 
-	return useInfiniteQuery(listCollectiblesOptions(args, config));
+	return useInfiniteQuery({
+		...queryOptions,
+	});
 }
+
+export { listCollectiblesQueryOptions };
+
+export type { FetchListCollectiblesParams, ListCollectiblesQueryOptions };
+
+// Legacy export for backward compatibility during migration
+export type UseListCollectiblesArgs = UseListCollectiblesParams;

package/src/react/hooks/useListCollectiblesPaginated.tsx

@@ -1,74 +1,107 @@
-import { queryOptions, useQuery } from '@tanstack/react-query';
-import { z } from 'zod';
-import type { Page, SdkConfig } from '../../types';
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import type { Optional } from '../_internal';
 import {
-	AddressSchema,
-	type ListCollectiblesArgs,
-	collectableKeys,
-	getMarketplaceClient,
-} from '../_internal';
-import { listCollectiblesArgsSchema } from '../_internal/api/zod-schema';
+	type FetchListCollectiblesPaginatedParams,
+	type fetchListCollectiblesPaginated,
+	type ListCollectiblesPaginatedQueryOptions,
+	listCollectiblesPaginatedQueryOptions,
+} from '../queries/listCollectiblesPaginated';
 import { useConfig } from './useConfig';
 
-const UseListCollectiblesPaginatedArgsSchema = listCollectiblesArgsSchema
-	.omit({
-		contractAddress: true,
-	})
-	.extend({
-		collectionAddress: AddressSchema,
-		chainId: z.number(),
-		query: z
-			.object({
-				enabled: z.boolean().optional(),
-				page: z.number().optional().default(1),
-				pageSize: z.number().optional().default(30),
-			})
-			.optional()
-			.default({}),
-	});
-
-export type UseListCollectiblesPaginatedArgs = z.infer<
-	typeof UseListCollectiblesPaginatedArgsSchema
+export type UseListCollectiblesPaginatedParams = Optional<
+	ListCollectiblesPaginatedQueryOptions,
+	'config'
 >;
 
-export type UseListCollectiblesPaginatedReturn = Awaited<
-	ReturnType<typeof fetchCollectiblesPaginated>
->;
-
-const fetchCollectiblesPaginated = async (
-	args: UseListCollectiblesPaginatedArgs,
-	marketplaceClient: Awaited<ReturnType<typeof getMarketplaceClient>>,
-) => {
-	const parsedArgs = UseListCollectiblesPaginatedArgsSchema.parse(args);
-	const page: Page = {
-		page: parsedArgs.query?.page ?? 1,
-		pageSize: parsedArgs.query?.pageSize ?? 30,
-	};
+/**
+ * Hook to fetch a list of collectibles with pagination support
+ *
+ * Fetches collectibles from the marketplace with support for filtering and pagination.
+ * Unlike the infinite query version, this hook fetches a specific page of results.
+ *
+ * @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.side - Order side (listing or bid)
+ * @param params.filter - Optional filtering parameters
+ * @param params.page - Page number to fetch (default: 1)
+ * @param params.pageSize - Number of items per page (default: 30)
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing collectibles data for the specific page
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data, isLoading } = useListCollectiblesPaginated({
+ *   chainId: 137,
+ *   collectionAddress: '0x...',
+ *   side: OrderSide.listing,
+ *   page: 1,
+ *   pageSize: 20
+ * })
+ * ```
+ *
+ * @example
+ * With filtering:
+ * ```typescript
+ * const { data } = useListCollectiblesPaginated({
+ *   chainId: 1,
+ *   collectionAddress: '0x...',
+ *   side: OrderSide.listing,
+ *   page: 2,
+ *   pageSize: 50,
+ *   filter: {
+ *     searchText: 'rare',
+ *     includeEmpty: false
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * Controlled pagination:
+ * ```typescript
+ * const [currentPage, setCurrentPage] = useState(1);
+ * const { data, isLoading } = useListCollectiblesPaginated({
+ *   chainId: 137,
+ *   collectionAddress: '0x...',
+ *   side: OrderSide.listing,
+ *   page: currentPage,
+ *   pageSize: 25
+ * });
+ *
+ * const hasMorePages = data?.page?.more;
+ * ```
+ */
+export function useListCollectiblesPaginated(
+	params: UseListCollectiblesPaginatedParams,
+) {
+	const defaultConfig = useConfig();
 
-	const arg = {
-		...parsedArgs,
-		contractAddress: parsedArgs.collectionAddress,
-		page,
-	} as ListCollectiblesArgs;
+	const { config = defaultConfig, ...rest } = params;
 
-	return marketplaceClient.listCollectibles(arg);
-};
+	const queryOptions = listCollectiblesPaginatedQueryOptions({
+		config,
+		...rest,
+	});
 
-export const listCollectiblesPaginatedOptions = (
-	args: UseListCollectiblesPaginatedArgs,
-	config: SdkConfig,
-) => {
-	const marketplaceClient = getMarketplaceClient(args.chainId, config);
-	return queryOptions({
-		queryKey: [...collectableKeys.lists, 'paginated', args],
-		queryFn: () => fetchCollectiblesPaginated(args, marketplaceClient),
-		enabled: args.query?.enabled ?? true,
+	return useQuery({
+		...queryOptions,
 	});
-};
+}
+
+export { listCollectiblesPaginatedQueryOptions };
 
-export const useListCollectiblesPaginated = (
-	args: UseListCollectiblesPaginatedArgs,
-) => {
-	const config = useConfig();
-	return useQuery(listCollectiblesPaginatedOptions(args, config));
+export type {
+	FetchListCollectiblesPaginatedParams,
+	ListCollectiblesPaginatedQueryOptions,
 };
+
+// Legacy exports for backward compatibility during migration
+export type UseListCollectiblesPaginatedArgs =
+	UseListCollectiblesPaginatedParams;
+export type UseListCollectiblesPaginatedReturn = Awaited<
+	ReturnType<typeof fetchListCollectiblesPaginated>
+>;

package/src/react/hooks/useListCollectionActivities.tsx

@@ -1,58 +1,93 @@
-import { queryOptions, useQuery } from '@tanstack/react-query';
-import type { z } from 'zod';
-import type { SdkConfig } from '../../types';
-import { getMarketplaceClient } from '../_internal';
-import { collectionKeys } from '../_internal/api';
-import type {
-	getListCollectionActivitiesArgsSchema,
-	getListCollectionActivitiesReturnSchema,
-} from '../_internal/api/zod-schema';
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+import type { Optional } from '../_internal';
+import {
+	type FetchListCollectionActivitiesParams,
+	type fetchListCollectionActivities,
+	type ListCollectionActivitiesQueryOptions,
+	listCollectionActivitiesQueryOptions,
+} from '../queries/listCollectionActivities';
 import { useConfig } from './useConfig';
 
-export type UseListCollectionActivitiesArgs = z.infer<
-	typeof getListCollectionActivitiesArgsSchema
+export type UseListCollectionActivitiesParams = Optional<
+	ListCollectionActivitiesQueryOptions,
+	'config'
 >;
 
-export type UseListCollectionActivitiesReturn = z.infer<
-	typeof getListCollectionActivitiesReturnSchema
->;
+/**
+ * Hook to fetch a list of activities for an entire collection
+ *
+ * Fetches activities (transfers, sales, offers, etc.) for all tokens
+ * in a collection from the marketplace with support for pagination and sorting.
+ *
+ * @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.page - Page number to fetch (default: 1)
+ * @param params.pageSize - Number of activities per page (default: 10)
+ * @param params.sort - Sort order for activities
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing activities data for the collection
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data, isLoading } = useListCollectionActivities({
+ *   chainId: 137,
+ *   collectionAddress: '0x...'
+ * })
+ * ```
+ *
+ * @example
+ * With pagination:
+ * ```typescript
+ * const { data } = useListCollectionActivities({
+ *   chainId: 1,
+ *   collectionAddress: '0x...',
+ *   page: 2,
+ *   pageSize: 20
+ * })
+ * ```
+ *
+ * @example
+ * With sorting:
+ * ```typescript
+ * const { data } = useListCollectionActivities({
+ *   chainId: 137,
+ *   collectionAddress: '0x...',
+ *   sort: [{ column: 'createdAt', order: SortOrder.DESC }],
+ *   pageSize: 50
+ * })
+ * ```
+ */
+export function useListCollectionActivities(
+	params: UseListCollectionActivitiesParams,
+) {
+	const defaultConfig = useConfig();
 
-const fetchListCollectionActivities = async (
-	args: UseListCollectionActivitiesArgs,
-	config: SdkConfig,
-) => {
-	const marketplaceClient = getMarketplaceClient(args.chainId, config);
-	return marketplaceClient
-		.listCollectionActivities({
-			contractAddress: args.collectionAddress,
-			page: args.query?.enabled
-				? {
-						page: args.query.page ?? 1,
-						pageSize: args.query.pageSize ?? 10,
-						sort: args.query.sort,
-					}
-				: undefined,
-		})
-		.then((data) => ({
-			activities: data.activities,
-			page: data.page,
-		}));
-};
+	const { config = defaultConfig, ...rest } = params;
 
-export const listCollectionActivitiesOptions = (
-	args: UseListCollectionActivitiesArgs,
-	config: SdkConfig,
-) => {
-	return queryOptions({
-		queryKey: [...collectionKeys.collectionActivities, args, config],
-		queryFn: () => fetchListCollectionActivities(args, config),
-		enabled: args.query?.enabled ?? true,
+	const queryOptions = listCollectionActivitiesQueryOptions({
+		config,
+		...rest,
 	});
-};
 
-export const useListCollectionActivities = (
-	args: UseListCollectionActivitiesArgs,
-) => {
-	const config = useConfig();
-	return useQuery(listCollectionActivitiesOptions(args, config));
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { listCollectionActivitiesQueryOptions };
+
+export type {
+	FetchListCollectionActivitiesParams,
+	ListCollectionActivitiesQueryOptions,
 };
+
+// Legacy exports for backward compatibility during migration
+export type UseListCollectionActivitiesArgs = UseListCollectionActivitiesParams;
+export type UseListCollectionActivitiesReturn = Awaited<
+	ReturnType<typeof fetchListCollectionActivities>
+>;

package/src/react/hooks/useListCollections.tsx

@@ -1,26 +1,80 @@
+'use client';
+
 import { useQuery } from '@tanstack/react-query';
-import type { MarketplaceType } from '../../types/new-marketplace-types';
-import { listCollectionsOptions } from '../queries/listCollections';
+import type { Optional } from '../_internal';
+import {
+	type FetchListCollectionsParams,
+	type ListCollectionsQueryOptions,
+	listCollectionsQueryOptions,
+} from '../queries/listCollections';
 import { useConfig } from './useConfig';
 import { useMarketplaceConfig } from './useMarketplaceConfig';
 
-type UseListCollectionsArgs = {
-	marketplaceType?: MarketplaceType;
-	query?: {
-		enabled?: boolean;
-	};
-};
+export type UseListCollectionsParams = Optional<
+	ListCollectionsQueryOptions,
+	'config' | 'marketplaceConfig'
+>;
+
+/**
+ * Hook to fetch a list of collections from the marketplace
+ *
+ * This hook fetches collections from the marketplace configuration and enriches them with
+ * metadata from the metadata API. Collections can be filtered by marketplace type (market/shop).
+ *
+ * @param params - Configuration parameters
+ * @param params.marketplaceType - Optional filter for marketplace type ('market' or 'shop')
+ * @param params.marketplaceConfig - Optional marketplace configuration (defaults from context)
+ * @param params.config - Optional SDK configuration (defaults from context)
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing an array of collections with metadata
+ *
+ * @example
+ * Basic usage - fetch all collections:
+ * ```typescript
+ * const { data: collections, isLoading } = useListCollections()
+ * ```
+ *
+ * @example
+ * Filter by marketplace type:
+ * ```typescript
+ * const { data: marketCollections } = useListCollections({
+ *   marketplaceType: 'market'
+ * })
+ * ```
+ *
+ * @example
+ * With custom query options:
+ * ```typescript
+ * const { data: collections } = useListCollections({
+ *   query: {
+ *     enabled: isReady,
+ *     staleTime: 5 * 60 * 1000 // 5 minutes
+ *   }
+ * })
+ * ```
+ */
+export function useListCollections(params: UseListCollectionsParams = {}) {
+	const defaultConfig = useConfig();
+	const { data: defaultMarketplaceConfig } = useMarketplaceConfig();
+
+	const {
+		config = defaultConfig,
+		marketplaceConfig = defaultMarketplaceConfig,
+		...rest
+	} = params;
 
-export const useListCollections = (args: UseListCollectionsArgs = {}) => {
-	const config = useConfig();
-	const { data: marketplaceConfig } = useMarketplaceConfig();
+	const queryOptions = listCollectionsQueryOptions({
+		config,
+		marketplaceConfig,
+		...rest,
+	});
 
 	return useQuery({
-		...args.query,
-		...listCollectionsOptions({
-			marketplaceType: args.marketplaceType,
-			marketplaceConfig,
-			config,
-		}),
+		...queryOptions,
 	});
-};
+}
+
+export { listCollectionsQueryOptions };
+
+export type { FetchListCollectionsParams, ListCollectionsQueryOptions };

package/src/react/hooks/useListListingsForCollectible.tsx

@@ -1,60 +1,101 @@
-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 {
-	type ListListingsForCollectibleArgs,
-	collectableKeys,
-	getMarketplaceClient,
-} from '../_internal';
-import { listListingsForCollectibleArgsSchema } from '../_internal/api/zod-schema';
+	type FetchListListingsForCollectibleParams,
+	type fetchListListingsForCollectible,
+	type ListListingsForCollectibleQueryOptions,
+	listListingsForCollectibleQueryOptions,
+} from '../queries/listListingsForCollectible';
 import { useConfig } from './useConfig';
 
-const UseListListingsForCollectibleArgsSchema =
-	listListingsForCollectibleArgsSchema
-		.extend({
-			chainId: z.number(),
-			collectionAddress: z.string(),
-			collectibleId: z.string(),
-		})
-		.omit({ contractAddress: true, tokenId: true });
-
-type UseListListingsForCollectibleArgs = z.infer<
-	typeof UseListListingsForCollectibleArgsSchema
+export type UseListListingsForCollectibleParams = Optional<
+	ListListingsForCollectibleQueryOptions,
+	'config'
 >;
 
-export type UseListListingsForCollectibleReturn = Awaited<
-	ReturnType<typeof fetchListListingsForCollectible>
->;
+/**
+ * Hook to fetch listings for a specific collectible
+ *
+ * Fetches active listings (sales) for a specific token from the marketplace
+ * with support for filtering and pagination.
+ *
+ * @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 specific token ID to fetch listings for
+ * @param params.filter - Optional filtering parameters (marketplace, currencies, etc.)
+ * @param params.page - Optional pagination parameters
+ * @param params.query - Optional React Query configuration
+ *
+ * @returns Query result containing listings data for the collectible
+ *
+ * @example
+ * Basic usage:
+ * ```typescript
+ * const { data, isLoading } = useListListingsForCollectible({
+ *   chainId: 137,
+ *   collectionAddress: '0x...',
+ *   collectibleId: '123'
+ * })
+ * ```
+ *
+ * @example
+ * With pagination:
+ * ```typescript
+ * const { data } = useListListingsForCollectible({
+ *   chainId: 1,
+ *   collectionAddress: '0x...',
+ *   collectibleId: '456',
+ *   page: {
+ *     page: 2,
+ *     pageSize: 20
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * With filtering:
+ * ```typescript
+ * const { data } = useListListingsForCollectible({
+ *   chainId: 137,
+ *   collectionAddress: '0x...',
+ *   collectibleId: '789',
+ *   filter: {
+ *     marketplace: [MarketplaceKind.sequence_marketplace_v2],
+ *     currencies: ['0x...'] // Specific currency addresses
+ *   }
+ * })
+ * ```
+ */
+export function useListListingsForCollectible(
+	params: UseListListingsForCollectibleParams,
+) {
+	const defaultConfig = useConfig();
 
-const fetchListListingsForCollectible = async (
-	config: SdkConfig,
-	args: UseListListingsForCollectibleArgs,
-) => {
-	const arg = {
-		contractAddress: args.collectionAddress,
-		tokenId: args.collectibleId,
-		filter: args.filter,
-		page: args.page,
-	} satisfies ListListingsForCollectibleArgs;
-
-	const marketplaceClient = getMarketplaceClient(args.chainId, config);
-	return marketplaceClient.listCollectibleListings(arg);
-};
+	const { config = defaultConfig, ...rest } = params;
 
-export const listListingsForCollectibleOptions = (
-	args: UseListListingsForCollectibleArgs,
-	config: SdkConfig,
-) => {
-	return queryOptions({
-		queryKey: [...collectableKeys.listings, args, config],
-		queryFn: () => fetchListListingsForCollectible(config, args),
+	const queryOptions = listListingsForCollectibleQueryOptions({
+		config,
+		...rest,
 	});
-};
 
-export const useListListingsForCollectible = (
-	args: UseListListingsForCollectibleArgs,
-) => {
-	const config = useConfig();
+	return useQuery({
+		...queryOptions,
+	});
+}
+
+export { listListingsForCollectibleQueryOptions };
 
-	return useQuery(listListingsForCollectibleOptions(args, config));
+export type {
+	FetchListListingsForCollectibleParams,
+	ListListingsForCollectibleQueryOptions,
 };
+
+// Legacy exports for backward compatibility during migration
+export type UseListListingsForCollectibleArgs =
+	UseListListingsForCollectibleParams;
+export type UseListListingsForCollectibleReturn = Awaited<
+	ReturnType<typeof fetchListListingsForCollectible>
+>;