import { type Signal, type ReadOnlySignal } from '@wix/services-definitions/core-services/signals'; import { customizationsV3, productsV3 } from '@wix/stores'; import { categories } from '@wix/categories'; type Category = categories.Category; export declare const DEFAULT_QUERY_LIMIT = 100; import { SortType } from './../enums/sort-enums.js'; export { SortType } from './../enums/sort-enums.js'; /** * Enumeration of inventory status types available for filtering. * Re-exports the Wix inventory availability status enum values. */ export declare const InventoryStatusType: typeof productsV3.InventoryAvailabilityStatus; /** * Type for inventory status values. * Re-exports the Wix inventory availability status enum type. */ export type InventoryStatusType = productsV3.InventoryAvailabilityStatus; /** * Interface representing a product option (like Size, Color, etc.). */ export interface ProductOption { id: string; name: string; choices: ProductChoice[]; optionRenderType?: string; } /** * Interface representing a choice within a product option. */ export interface ProductChoice { id: string; name: string; colorCode?: string; } /** * Configuration interface for the Products List service. * Contains the initial products data, search options, and metadata. * * @interface ProductsListServiceConfig */ export type ProductsListServiceConfig = { /** Array of product objects to initialize the service with */ products: productsV3.V3Product[]; /** Search options used to fetch the products */ searchOptions: productsV3.V3ProductSearch; /** Pagination metadata from the search response */ pagingMetadata: productsV3.CommonCursorPagingMetadata; /** Aggregation data containing filters, facets, and counts */ aggregations: productsV3.AggregationData; /** Customizations used to fetch the products */ customizations: customizationsV3.Customization[]; }; /** * Loads products list service configuration from the Wix Stores API for SSR initialization. * This function is designed to be used during Server-Side Rendering (SSR) to preload * a list of products based on search criteria or URL parameters. * * Accepts either a URL string or pre-parsed `{ searchOptions }` from `parseUrlToSearchOptions()`. * When passing a URL string, it internally calls `parseUrlToSearchOptions()` to extract * filters, sort, and pagination from URL parameters. See `parseUrlToSearchOptions` for * supported URL parameters and their formats. * * @param {string | { searchOptions: productsV3.V3ProductSearch }} input - Either a URL to parse or pre-parsed search options * @returns {Promise} Promise that resolves to the products list configuration * * @example Astro - SSR products page * ```astro * // Astro page example - pages/products.astro * --- * import { loadProductsListServiceConfig, parseUrlToSearchOptions, loadCategoriesListServiceConfig } from '@wix/stores/services'; * import { ProductList } from '@wix/stores/components'; * * // Option 1: Load from URL (will parse filters, sort, pagination from URL params) * const productsConfig = await loadProductsListServiceConfig(Astro.url.href); * * // Option 2: Custom parsing with defaults * const categories = await loadCategoriesListServiceConfig(); * const parsed = await parseUrlToSearchOptions( * Astro.url.href, * categories.categories, * { * cursorPaging: { limit: 12 }, * filter: {}, * sort: [{ fieldName: 'name' as const, order: 'ASC' as const }] * } * ); * const productsConfig = await loadProductsListServiceConfig(parsed); * --- * * * * {({ product }) => ( *
*

{product.name}

*

{product.description}

*
* )} * * * ``` * * @example Next.js - SSR products page * ```tsx * // Next.js page example - pages/products.tsx * import { GetServerSideProps } from 'next'; * import { loadProductsListServiceConfig, parseUrlToSearchOptions, loadCategoriesListServiceConfig } from '@wix/stores/services'; * import { ProductsList } from '@wix/stores/components'; * * interface ProductsPageProps { * productsConfig: Awaited>; * } * * export const getServerSideProps: GetServerSideProps = async ({ req }) => { * // Option 1: Parse from URL * const productsConfig = await loadProductsListServiceConfig(`${req.url}`); * * // Option 2: Custom parsing with filters * const categories = await loadCategoriesListServiceConfig(); * const parsed = await parseUrlToSearchOptions( * `${req.url}`, * categories.categories, * { * cursorPaging: { limit: 12 }, * filter: { * 'allCategoriesInfo.categories': { $matchItems: [{ _id: { $in: [category._id] } }] } * }, * sort: [{ fieldName: 'name' as const, order: 'ASC' as const }] * } * ); * const productsConfig = await loadProductsListServiceConfig(parsed); * * return { * props: { * productsConfig, * }, * }; * }; * * export default function ProductsPage({ productsConfig }: ProductsPageProps) { * return ( * * * {({ product }) => ( *
*

{product.name}

*

{product.description}

*
* )} * * * ); * } * ``` * * @example * ```tsx * // Advanced: Performance optimization when using both services * import { parseUrlToSearchOptions, loadProductsListServiceConfig, loadProductsListSearchServiceConfig, loadCategoriesListServiceConfig } from '@wix/stores/services'; * * const categories = await loadCategoriesListServiceConfig(); * const parsed = await parseUrlToSearchOptions(url, categories.categories); * * // Both services use the same parsed result (no duplicate URL parsing) * const [productsConfig, searchConfig] = await Promise.all([ * loadProductsListServiceConfig(parsed), * loadProductsListSearchServiceConfig(parsed) * ]); * ``` */ export declare function loadProductsListServiceConfig(input: string | { searchOptions: productsV3.V3ProductSearch; }): Promise; /** * Service definition for the Products List service. * This defines the reactive API contract for managing a list of products with search, pagination, and filtering capabilities. * * @constant */ export declare const ProductsListServiceDefinition: string & { __api: { /** Reactive signal containing the list of products */ products: Signal; /** Reactive signal containing aggregation data for filters and facets */ aggregations: Signal; /** Reactive signal containing pagination metadata */ pagingMetadata: Signal; /** Reactive signal containing current search options */ searchOptions: Signal; /** Reactive signal indicating if products are currently being loaded */ isLoading: Signal; /** Reactive signal containing any error message, or null if no error */ error: Signal; /** Reactive signal containing the minimum price of the products */ minPrice: Signal; /** Reactive signal containing the maximum price of the products */ maxPrice: Signal; /** Reactive signal containing the currency code from products */ currency: ReadOnlySignal; /** Reactive signal containing the available inventory statuses */ availableInventoryStatuses: Signal; /** Reactive signal containing the available product options */ availableProductOptions: Signal; /** Function to update search options and trigger a new search */ setSearchOptions: (searchOptions: productsV3.V3ProductSearch) => void; /** Function to update only the sort part of search options */ setSort: (sort: productsV3.V3ProductSearch["sort"]) => void; /** Function to update only the filter part of search options */ setFilter: (filter: productsV3.V3ProductSearch["filter"]) => void; /** Function to reset the filter part of search options */ resetFilter: () => void; /** Reactive signal indicating if any filters are currently applied */ isFiltered: () => ReadOnlySignal; /** Function to load more products */ loadMore: (count: number) => void; /** Reactive signal indicating if there are more products to load */ hasMoreProducts: ReadOnlySignal; }; __config: ProductsListServiceConfig; isServiceDefinition?: boolean; } & { /** Reactive signal containing the list of products */ products: Signal; /** Reactive signal containing aggregation data for filters and facets */ aggregations: Signal; /** Reactive signal containing pagination metadata */ pagingMetadata: Signal; /** Reactive signal containing current search options */ searchOptions: Signal; /** Reactive signal indicating if products are currently being loaded */ isLoading: Signal; /** Reactive signal containing any error message, or null if no error */ error: Signal; /** Reactive signal containing the minimum price of the products */ minPrice: Signal; /** Reactive signal containing the maximum price of the products */ maxPrice: Signal; /** Reactive signal containing the currency code from products */ currency: ReadOnlySignal; /** Reactive signal containing the available inventory statuses */ availableInventoryStatuses: Signal; /** Reactive signal containing the available product options */ availableProductOptions: Signal; /** Function to update search options and trigger a new search */ setSearchOptions: (searchOptions: productsV3.V3ProductSearch) => void; /** Function to update only the sort part of search options */ setSort: (sort: productsV3.V3ProductSearch["sort"]) => void; /** Function to update only the filter part of search options */ setFilter: (filter: productsV3.V3ProductSearch["filter"]) => void; /** Function to reset the filter part of search options */ resetFilter: () => void; /** Reactive signal indicating if any filters are currently applied */ isFiltered: () => ReadOnlySignal; /** Function to load more products */ loadMore: (count: number) => void; /** Reactive signal indicating if there are more products to load */ hasMoreProducts: ReadOnlySignal; }; /** * Implementation of the Products List service that manages reactive products data. * This service provides signals for products data, search options, pagination, aggregations, * loading state, and error handling. It automatically re-fetches products when search options change. * * @example * ```tsx * import { ProductListService, ProductsListServiceDefinition } from '@wix/stores/services'; * import { useService } from '@wix/services-manager-react'; * * function ProductsComponent({ productsConfig }) { * return ( * * * * ); * } * * function ProductsDisplay() { * const productsService = useService(ProductsListServiceDefinition); * const products = productsService.products.get(); * const isLoading = productsService.isLoading.get(); * const error = productsService.error.get(); * * // Update search options to filter by category * const filterByCategory = (categoryId: string) => { * const currentOptions = productsService.searchOptions.get(); * productsService.setSearchOptions({ * ...currentOptions, * filter: { * ...currentOptions.filter, * categoryIds: [categoryId] * } * }); * }; * * if (isLoading) return
Loading products...
; * if (error) return
Error: {error}
; * * return ( *
* {products.map(product => ( *
*

{product.name}

*

{product.description}

*
* ))} *
* ); * } * ``` */ export declare const ProductListService: import("@wix/services-definitions").ServiceFactory; /** Reactive signal containing aggregation data for filters and facets */ aggregations: Signal; /** Reactive signal containing pagination metadata */ pagingMetadata: Signal; /** Reactive signal containing current search options */ searchOptions: Signal; /** Reactive signal indicating if products are currently being loaded */ isLoading: Signal; /** Reactive signal containing any error message, or null if no error */ error: Signal; /** Reactive signal containing the minimum price of the products */ minPrice: Signal; /** Reactive signal containing the maximum price of the products */ maxPrice: Signal; /** Reactive signal containing the currency code from products */ currency: ReadOnlySignal; /** Reactive signal containing the available inventory statuses */ availableInventoryStatuses: Signal; /** Reactive signal containing the available product options */ availableProductOptions: Signal; /** Function to update search options and trigger a new search */ setSearchOptions: (searchOptions: productsV3.V3ProductSearch) => void; /** Function to update only the sort part of search options */ setSort: (sort: productsV3.V3ProductSearch["sort"]) => void; /** Function to update only the filter part of search options */ setFilter: (filter: productsV3.V3ProductSearch["filter"]) => void; /** Function to reset the filter part of search options */ resetFilter: () => void; /** Reactive signal indicating if any filters are currently applied */ isFiltered: () => ReadOnlySignal; /** Function to load more products */ loadMore: (count: number) => void; /** Reactive signal indicating if there are more products to load */ hasMoreProducts: ReadOnlySignal; }; __config: ProductsListServiceConfig; isServiceDefinition?: boolean; } & { /** Reactive signal containing the list of products */ products: Signal; /** Reactive signal containing aggregation data for filters and facets */ aggregations: Signal; /** Reactive signal containing pagination metadata */ pagingMetadata: Signal; /** Reactive signal containing current search options */ searchOptions: Signal; /** Reactive signal indicating if products are currently being loaded */ isLoading: Signal; /** Reactive signal containing any error message, or null if no error */ error: Signal; /** Reactive signal containing the minimum price of the products */ minPrice: Signal; /** Reactive signal containing the maximum price of the products */ maxPrice: Signal; /** Reactive signal containing the currency code from products */ currency: ReadOnlySignal; /** Reactive signal containing the available inventory statuses */ availableInventoryStatuses: Signal; /** Reactive signal containing the available product options */ availableProductOptions: Signal; /** Function to update search options and trigger a new search */ setSearchOptions: (searchOptions: productsV3.V3ProductSearch) => void; /** Function to update only the sort part of search options */ setSort: (sort: productsV3.V3ProductSearch["sort"]) => void; /** Function to update only the filter part of search options */ setFilter: (filter: productsV3.V3ProductSearch["filter"]) => void; /** Function to reset the filter part of search options */ resetFilter: () => void; /** Reactive signal indicating if any filters are currently applied */ isFiltered: () => ReadOnlySignal; /** Function to load more products */ loadMore: (count: number) => void; /** Reactive signal indicating if there are more products to load */ hasMoreProducts: ReadOnlySignal; }, ProductsListServiceConfig>; /** * Initial search state that can be loaded from URL parameters. */ export type InitialSearchState = { sort?: SortType; limit?: number; cursor?: string | null; priceRange?: { min?: number; max?: number; }; inventoryStatuses?: InventoryStatusType[]; productOptions?: Record; category?: Category; visible?: boolean; productType?: string; }; /** * Parse URL and build complete search options with all filters, sort, and pagination. * This function extracts search parameters, filters, sorting, and pagination from a URL * and converts them into the format expected by the Wix Stores API. * * You must specify a default search options object with `{ filter: {} }` when no URL filters are present. * * @param {string} url - The URL to parse search parameters from. * @param {Category[]} categoriesList - List of available categories for resolving category slug from URL path. Pass `[]` if additional category filtering isn't needed. * @param {customizationsV3.Customization[]} customizations - Store customizations for resolving product option filters. Pass `[]` if additional product option filtering isn't needed. * @param {productsV3.V3ProductSearch} [defaultSearchOptions] - Default search options to merge with parsed URL parameters. Must include `{ filter: {} }` when no URL filters are present. * @returns {Promise<{searchOptions: productsV3.V3ProductSearch, initialSearchState: InitialSearchState}>} * Object containing both API-ready search options and UI-ready initial state. * * @example * ```tsx * // Simple usage - no category or product option filtering needed * const { searchOptions } = await parseUrlToSearchOptions( * 'https://example.com/products?sort=price:desc&Color=red,blue&minPrice=50', * [], // No categories * [], // No customizations * { filter: {} } // Include empty filter for proper initialization since no filters are present in the URL * ); * ``` * * @example * ```tsx * // Full usage - with category and product option filtering * const categories = await loadCategoriesListServiceConfig(); * const customizations = await customizationsV3.queryCustomizations().find(); * const { searchOptions, initialSearchState } = await parseUrlToSearchOptions( * 'https://example.com/products?sort=price:desc&Color=red,blue&minPrice=50', * categories.categories, * customizations, * { filter: {} } // Include empty filter for proper initialization since no filters are present in the URL * ); * * // Use searchOptions for API calls * const products = await productsV3.searchProducts(searchOptions); * * // Use initialSearchState for UI initialization * const filterState = initialSearchState.productOptions; // { colorId: ['red-id', 'blue-id'] } * ``` */ export declare function parseUrlToSearchOptions(url: string, categoriesList: Category[], customizations: customizationsV3.Customization[], defaultSearchOptions?: productsV3.V3ProductSearch): Promise<{ searchOptions: productsV3.V3ProductSearch; initialSearchState: InitialSearchState; }>; /** * Convert URL sort format to SortType enum */ export declare function convertUrlSortToSortType(urlSort: string): SortType | null;