@wix/headless-stores 0.0.0

package/dist/services/products-list-service.d.ts

@@ -0,0 +1,429 @@
+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.
+ *
+ * @param {string | { searchOptions: productsV3.V3ProductSearch; initialSearchState: InitialSearchState }} input - Either a URL to parse or parsed URL result from parseUrlToSearchOptions
+ * @returns {Promise<ProductsListServiceConfig>} Promise that resolves to the products list configuration
+ *
+ * @example
+ * ```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);
+ * ---
+ *
+ * <ProductList.Root productsConfig={productsConfig}>
+ *   <ProductList.ItemContent>
+ *     {({ product }) => (
+ *       <div>
+ *         <h3>{product.name}</h3>
+ *         <p>{product.description}</p>
+ *       </div>
+ *     )}
+ *   </ProductList.ItemContent>
+ * </ProductList.Root>
+ * ```
+ *
+ * @example
+ * ```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<ReturnType<typeof loadProductsListServiceConfig>>;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<ProductsPageProps> = 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 (
+ *     <ProductList.Root productsConfig={productsConfig}>
+ *       <ProductList.ItemContent>
+ *         {({ product }) => (
+ *           <div>
+ *             <h3>{product.name}</h3>
+ *             <p>{product.description}</p>
+ *           </div>
+ *         )}
+ *       </ProductList.ItemContent>
+ *     </ProductList.Root>
+ *   );
+ * }
+ * ```
+ *
+ * @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<ProductsListServiceConfig>;
+/**
+ * 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<productsV3.V3Product[]>;
+        /** Reactive signal containing aggregation data for filters and facets */
+        aggregations: Signal<productsV3.AggregationData>;
+        /** Reactive signal containing pagination metadata */
+        pagingMetadata: Signal<productsV3.CommonCursorPagingMetadata>;
+        /** Reactive signal containing current search options */
+        searchOptions: Signal<productsV3.V3ProductSearch>;
+        /** Reactive signal indicating if products are currently being loaded */
+        isLoading: Signal<boolean>;
+        /** Reactive signal containing any error message, or null if no error */
+        error: Signal<string | null>;
+        /** Reactive signal containing the minimum price of the products */
+        minPrice: Signal<number>;
+        /** Reactive signal containing the maximum price of the products */
+        maxPrice: Signal<number>;
+        /** Reactive signal containing the available inventory statuses */
+        availableInventoryStatuses: Signal<InventoryStatusType[]>;
+        /** Reactive signal containing the available product options */
+        availableProductOptions: Signal<ProductOption[]>;
+        /** 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<boolean>;
+        /** Function to load more products */
+        loadMore: (count: number) => void;
+        /** Reactive signal indicating if there are more products to load */
+        hasMoreProducts: ReadOnlySignal<boolean>;
+    };
+    __config: ProductsListServiceConfig;
+    isServiceDefinition?: boolean;
+} & {
+    /** Reactive signal containing the list of products */
+    products: Signal<productsV3.V3Product[]>;
+    /** Reactive signal containing aggregation data for filters and facets */
+    aggregations: Signal<productsV3.AggregationData>;
+    /** Reactive signal containing pagination metadata */
+    pagingMetadata: Signal<productsV3.CommonCursorPagingMetadata>;
+    /** Reactive signal containing current search options */
+    searchOptions: Signal<productsV3.V3ProductSearch>;
+    /** Reactive signal indicating if products are currently being loaded */
+    isLoading: Signal<boolean>;
+    /** Reactive signal containing any error message, or null if no error */
+    error: Signal<string | null>;
+    /** Reactive signal containing the minimum price of the products */
+    minPrice: Signal<number>;
+    /** Reactive signal containing the maximum price of the products */
+    maxPrice: Signal<number>;
+    /** Reactive signal containing the available inventory statuses */
+    availableInventoryStatuses: Signal<InventoryStatusType[]>;
+    /** Reactive signal containing the available product options */
+    availableProductOptions: Signal<ProductOption[]>;
+    /** 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<boolean>;
+    /** Function to load more products */
+    loadMore: (count: number) => void;
+    /** Reactive signal indicating if there are more products to load */
+    hasMoreProducts: ReadOnlySignal<boolean>;
+};
+/**
+ * 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 (
+ *     <ServiceProvider services={createServicesMap([
+ *       [ProductsListServiceDefinition, ProductListService.withConfig(productsConfig)]
+ *     ])}>
+ *       <ProductsDisplay />
+ *     </ServiceProvider>
+ *   );
+ * }
+ *
+ * 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 <div>Loading products...</div>;
+ *   if (error) return <div>Error: {error}</div>;
+ *
+ *   return (
+ *     <div>
+ *       {products.map(product => (
+ *         <div key={product._id}>
+ *           <h3>{product.name}</h3>
+ *           <p>{product.description}</p>
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare const ProductListService: import("@wix/services-definitions").ServiceFactory<string & {
+    __api: {
+        /** Reactive signal containing the list of products */
+        products: Signal<productsV3.V3Product[]>;
+        /** Reactive signal containing aggregation data for filters and facets */
+        aggregations: Signal<productsV3.AggregationData>;
+        /** Reactive signal containing pagination metadata */
+        pagingMetadata: Signal<productsV3.CommonCursorPagingMetadata>;
+        /** Reactive signal containing current search options */
+        searchOptions: Signal<productsV3.V3ProductSearch>;
+        /** Reactive signal indicating if products are currently being loaded */
+        isLoading: Signal<boolean>;
+        /** Reactive signal containing any error message, or null if no error */
+        error: Signal<string | null>;
+        /** Reactive signal containing the minimum price of the products */
+        minPrice: Signal<number>;
+        /** Reactive signal containing the maximum price of the products */
+        maxPrice: Signal<number>;
+        /** Reactive signal containing the available inventory statuses */
+        availableInventoryStatuses: Signal<InventoryStatusType[]>;
+        /** Reactive signal containing the available product options */
+        availableProductOptions: Signal<ProductOption[]>;
+        /** 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<boolean>;
+        /** Function to load more products */
+        loadMore: (count: number) => void;
+        /** Reactive signal indicating if there are more products to load */
+        hasMoreProducts: ReadOnlySignal<boolean>;
+    };
+    __config: ProductsListServiceConfig;
+    isServiceDefinition?: boolean;
+} & {
+    /** Reactive signal containing the list of products */
+    products: Signal<productsV3.V3Product[]>;
+    /** Reactive signal containing aggregation data for filters and facets */
+    aggregations: Signal<productsV3.AggregationData>;
+    /** Reactive signal containing pagination metadata */
+    pagingMetadata: Signal<productsV3.CommonCursorPagingMetadata>;
+    /** Reactive signal containing current search options */
+    searchOptions: Signal<productsV3.V3ProductSearch>;
+    /** Reactive signal indicating if products are currently being loaded */
+    isLoading: Signal<boolean>;
+    /** Reactive signal containing any error message, or null if no error */
+    error: Signal<string | null>;
+    /** Reactive signal containing the minimum price of the products */
+    minPrice: Signal<number>;
+    /** Reactive signal containing the maximum price of the products */
+    maxPrice: Signal<number>;
+    /** Reactive signal containing the available inventory statuses */
+    availableInventoryStatuses: Signal<InventoryStatusType[]>;
+    /** Reactive signal containing the available product options */
+    availableProductOptions: Signal<ProductOption[]>;
+    /** 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<boolean>;
+    /** Function to load more products */
+    loadMore: (count: number) => void;
+    /** Reactive signal indicating if there are more products to load */
+    hasMoreProducts: ReadOnlySignal<boolean>;
+}, 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<string, string[]>;
+    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.
+ *
+ * @param {string} url - The URL to parse search parameters from
+ * @param {Category[]} categoriesList - List of available categories for category slug resolution
+ * @param {productsV3.V3ProductSearch} [defaultSearchOptions] - Default search options to merge with parsed URL parameters
+ * @returns {Promise<{searchOptions: productsV3.V3ProductSearch, initialSearchState: InitialSearchState}>}
+ *   Object containing both API-ready search options and UI-ready initial state
+ *
+ * @example
+ * ```tsx
+ * // Parse URL with filters, sort, and pagination
+ * const categories = await loadCategoriesListServiceConfig();
+ * const { searchOptions, initialSearchState } = await parseUrlToSearchOptions(
+ *   'https://example.com/products?sort=price:desc&Color=red,blue&minPrice=50',
+ *   categories.categories
+ * );
+ *
+ * // 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;