@wix/headless-stores 0.0.30 → 0.0.31

package/dist/services/collection-service.js

@@ -432,6 +432,95 @@ function parseOptionFilters(urlParams, optionsMap, filters) {
         }
     });
 }
+/**
+ * Loads collection service configuration from the Wix Products API for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to preload
+ * initial products data, categories, filters, and sorting that will be used to configure the CollectionService.
+ * Fetches products for a specific category, parses URL parameters for filters and sorting, and returns initial state.
+ *
+ * @param categoryId Optional category ID to filter products by
+ * @param searchParams Optional URLSearchParams for initial filters and sorting
+ * @param preloadedCategories Optional pre-loaded categories to avoid redundant API calls
+ * @returns Promise that resolves to CollectionServiceConfig with initial data
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/products/[categorySlug].astro
+ * import { loadCollectionServiceConfig } from '@wix/stores/services';
+ * import { Collection } from '@wix/stores/components';
+ *
+ * // Get category from URL params
+ * const { categorySlug } = Astro.params;
+ * const categoryId = categorySlug === 'all' ? undefined : categorySlug;
+ *
+ * // Load collection data during SSR
+ * const collectionConfig = await loadCollectionServiceConfig(
+ *   categoryId,
+ *   Astro.url.searchParams
+ * );
+ * ---
+ *
+ * <Collection.Root collectionConfig={collectionConfig}>
+ *   <Collection.Grid>
+ *     {({ products, isLoading }) => (
+ *       <div>
+ *         {isLoading ? 'Loading...' : `${products.length} products`}
+ *       </div>
+ *     )}
+ *   </Collection.Grid>
+ * </Collection.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example - pages/products/[categorySlug].tsx
+ * import { GetServerSideProps } from 'next';
+ * import { loadCollectionServiceConfig } from '@wix/stores/services';
+ * import { Collection } from '@wix/stores/components';
+ *
+ * interface ProductsPageProps {
+ *   collectionConfig: Awaited<ReturnType<typeof loadCollectionServiceConfig>>;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<ProductsPageProps> = async ({ params, query }) => {
+ *   const categorySlug = params?.categorySlug as string;
+ *   const categoryId = categorySlug === 'all' ? undefined : categorySlug;
+ *
+ *   // Convert Next.js query to URLSearchParams
+ *   const searchParams = new URLSearchParams();
+ *   Object.entries(query).forEach(([key, value]) => {
+ *     if (typeof value === 'string') searchParams.set(key, value);
+ *   });
+ *
+ *   // Load collection data during SSR
+ *   const collectionConfig = await loadCollectionServiceConfig(
+ *     categoryId,
+ *     searchParams
+ *   );
+ *
+ *   return {
+ *     props: {
+ *       collectionConfig,
+ *     },
+ *   };
+ * };
+ *
+ * export default function ProductsPage({ collectionConfig }: ProductsPageProps) {
+ *   return (
+ *     <Collection.Root collectionConfig={collectionConfig}>
+ *       <Collection.Grid>
+ *         {({ products, isLoading }) => (
+ *           <div>
+ *             {isLoading ? 'Loading...' : `${products.length} products`}
+ *           </div>
+ *         )}
+ *       </Collection.Grid>
+ *     </Collection.Root>
+ *   );
+ * }
+ * ```
+ */
 export async function loadCollectionServiceConfig(categoryId, searchParams, preloadedCategories) {
     try {
         // Use pre-loaded categories if provided, otherwise load them

package/dist/services/product-service.d.ts

@@ -25,4 +25,80 @@ export type ProductServiceConfigResult = {
 } | {
     type: "notFound";
 };
+/**
+ * Loads product service configuration from the Wix Products API for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to preload
+ * a specific product by slug that will be used to configure the ProductService.
+ *
+ * @param productSlug The product slug to load
+ * @returns Promise that resolves to ProductServiceConfigResult (success with config or notFound)
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/product/[slug].astro
+ * import { loadProductServiceConfig } from '@wix/stores/services';
+ * import { Product } from '@wix/stores/components';
+ *
+ * // Get product slug from URL params
+ * const { slug } = Astro.params;
+ *
+ * // Load product data during SSR
+ * const productResult = await loadProductServiceConfig(slug);
+ *
+ * // Handle not found case
+ * if (productResult.type === 'notFound') {
+ *   return Astro.redirect('/404');
+ * }
+ * ---
+ *
+ * <Product.Root productConfig={productResult.config}>
+ *   <Product.Name>
+ *     {({ name }) => <h1>{name}</h1>}
+ *   </Product.Name>
+ * </Product.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example - pages/product/[slug].tsx
+ * import { GetServerSideProps } from 'next';
+ * import { loadProductServiceConfig } from '@wix/stores/services';
+ * import { Product } from '@wix/stores/components';
+ *
+ * interface ProductPageProps {
+ *   productConfig: Awaited<ReturnType<typeof loadProductServiceConfig>>['config'];
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<ProductPageProps> = async ({ params }) => {
+ *   const slug = params?.slug as string;
+ *
+ *   // Load product data during SSR
+ *   const productResult = await loadProductServiceConfig(slug);
+ *
+ *   // Handle not found case
+ *   if (productResult.type === 'notFound') {
+ *     return {
+ *       notFound: true,
+ *     };
+ *   }
+ *
+ *   return {
+ *     props: {
+ *       productConfig: productResult.config,
+ *     },
+ *   };
+ * };
+ *
+ * export default function ProductPage({ productConfig }: ProductPageProps) {
+ *   return (
+ *     <Product.Root productConfig={productConfig}>
+ *       <Product.Name>
+ *         {({ name }) => <h1>{name}</h1>}
+ *       </Product.Name>
+ *     </Product.Root>
+ *   );
+ * }
+ * ```
+ */
 export declare function loadProductServiceConfig(productSlug: string): Promise<ProductServiceConfigResult>;

package/dist/services/product-service.js

@@ -43,6 +43,82 @@ const loadProductBySlug = async (slug) => {
     });
     return productResponse;
 };
+/**
+ * Loads product service configuration from the Wix Products API for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to preload
+ * a specific product by slug that will be used to configure the ProductService.
+ *
+ * @param productSlug The product slug to load
+ * @returns Promise that resolves to ProductServiceConfigResult (success with config or notFound)
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/product/[slug].astro
+ * import { loadProductServiceConfig } from '@wix/stores/services';
+ * import { Product } from '@wix/stores/components';
+ *
+ * // Get product slug from URL params
+ * const { slug } = Astro.params;
+ *
+ * // Load product data during SSR
+ * const productResult = await loadProductServiceConfig(slug);
+ *
+ * // Handle not found case
+ * if (productResult.type === 'notFound') {
+ *   return Astro.redirect('/404');
+ * }
+ * ---
+ *
+ * <Product.Root productConfig={productResult.config}>
+ *   <Product.Name>
+ *     {({ name }) => <h1>{name}</h1>}
+ *   </Product.Name>
+ * </Product.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example - pages/product/[slug].tsx
+ * import { GetServerSideProps } from 'next';
+ * import { loadProductServiceConfig } from '@wix/stores/services';
+ * import { Product } from '@wix/stores/components';
+ *
+ * interface ProductPageProps {
+ *   productConfig: Awaited<ReturnType<typeof loadProductServiceConfig>>['config'];
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<ProductPageProps> = async ({ params }) => {
+ *   const slug = params?.slug as string;
+ *
+ *   // Load product data during SSR
+ *   const productResult = await loadProductServiceConfig(slug);
+ *
+ *   // Handle not found case
+ *   if (productResult.type === 'notFound') {
+ *     return {
+ *       notFound: true,
+ *     };
+ *   }
+ *
+ *   return {
+ *     props: {
+ *       productConfig: productResult.config,
+ *     },
+ *   };
+ * };
+ *
+ * export default function ProductPage({ productConfig }: ProductPageProps) {
+ *   return (
+ *     <Product.Root productConfig={productConfig}>
+ *       <Product.Name>
+ *         {({ name }) => <h1>{name}</h1>}
+ *       </Product.Name>
+ *     </Product.Root>
+ *   );
+ * }
+ * ```
+ */
 export async function loadProductServiceConfig(productSlug) {
     try {
         // Use getProductBySlug directly - single API call with comprehensive fields

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

@@ -6,6 +6,99 @@ export interface ProductsListServiceConfig {
     pagingMetadata: productsV3.CommonCursorPagingMetadata;
     aggregations: productsV3.AggregationData;
 }
+/**
+ * Loads products list service configuration from the Wix Products API for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to preload
+ * products based on search criteria that will be used to configure the ProductsListService.
+ *
+ * @param searchOptions Search options for filtering and querying products
+ * @returns Promise that resolves to ProductsListServiceConfig with products, metadata, and aggregations
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/search.astro
+ * import { loadProductsListServiceConfig } from '@wix/stores/services';
+ * import { ProductsList } from '@wix/stores/components';
+ *
+ * // Get search query from URL params
+ * const searchQuery = Astro.url.searchParams.get('q') || '';
+ * const category = Astro.url.searchParams.get('category');
+ *
+ * // Build search options
+ * const searchOptions = {
+ *   query: { search: searchQuery },
+ *   filter: category ? { categories: [category] } : undefined,
+ *   paging: { limit: 12 }
+ * };
+ *
+ * // Load products during SSR
+ * const productsListConfig = await loadProductsListServiceConfig(searchOptions);
+ * ---
+ *
+ * <ProductsList.Root productsListConfig={productsListConfig}>
+ *   <ProductsList.ItemContent>
+ *     {({ product }) => (
+ *       <div class="product-item">
+ *         <h3>{product.name}</h3>
+ *       </div>
+ *     )}
+ *   </ProductsList.ItemContent>
+ * </ProductsList.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example - pages/search.tsx
+ * import { GetServerSideProps } from 'next';
+ * import { loadProductsListServiceConfig } from '@wix/stores/services';
+ * import { ProductsList } from '@wix/stores/components';
+ *
+ * interface SearchPageProps {
+ *   productsListConfig: Awaited<ReturnType<typeof loadProductsListServiceConfig>>;
+ *   searchQuery: string;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<SearchPageProps> = async ({ query }) => {
+ *   const searchQuery = (query.q as string) || '';
+ *   const category = query.category as string;
+ *
+ *   // Build search options
+ *   const searchOptions = {
+ *     query: { search: searchQuery },
+ *     filter: category ? { categories: [category] } : undefined,
+ *     paging: { limit: 12 }
+ *   };
+ *
+ *   // Load products during SSR
+ *   const productsListConfig = await loadProductsListServiceConfig(searchOptions);
+ *
+ *   return {
+ *     props: {
+ *       productsListConfig,
+ *       searchQuery,
+ *     },
+ *   };
+ * };
+ *
+ * export default function SearchPage({ productsListConfig, searchQuery }: SearchPageProps) {
+ *   return (
+ *     <div>
+ *       <h1>Search Results for "{searchQuery}"</h1>
+ *       <ProductsList.Root productsListConfig={productsListConfig}>
+ *         <ProductsList.ItemContent>
+ *           {({ product }) => (
+ *             <div className="product-item">
+ *               <h3>{product.name}</h3>
+ *             </div>
+ *           )}
+ *         </ProductsList.ItemContent>
+ *       </ProductsList.Root>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export declare function loadProductsListServiceConfig(searchOptions: Parameters<typeof productsV3.searchProducts>[0]): Promise<ProductsListServiceConfig>;
 export declare const ProductsListServiceDefinition: string & {
     __api: {

package/dist/services/products-list-service.js

@@ -2,6 +2,99 @@ import { defineService, implementService } from "@wix/services-definitions";
 import { SignalsServiceDefinition, } from "@wix/services-definitions/core-services/signals";
 import { productsV3 } from "@wix/stores";
 ;
+/**
+ * Loads products list service configuration from the Wix Products API for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to preload
+ * products based on search criteria that will be used to configure the ProductsListService.
+ *
+ * @param searchOptions Search options for filtering and querying products
+ * @returns Promise that resolves to ProductsListServiceConfig with products, metadata, and aggregations
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/search.astro
+ * import { loadProductsListServiceConfig } from '@wix/stores/services';
+ * import { ProductsList } from '@wix/stores/components';
+ *
+ * // Get search query from URL params
+ * const searchQuery = Astro.url.searchParams.get('q') || '';
+ * const category = Astro.url.searchParams.get('category');
+ *
+ * // Build search options
+ * const searchOptions = {
+ *   query: { search: searchQuery },
+ *   filter: category ? { categories: [category] } : undefined,
+ *   paging: { limit: 12 }
+ * };
+ *
+ * // Load products during SSR
+ * const productsListConfig = await loadProductsListServiceConfig(searchOptions);
+ * ---
+ *
+ * <ProductsList.Root productsListConfig={productsListConfig}>
+ *   <ProductsList.ItemContent>
+ *     {({ product }) => (
+ *       <div class="product-item">
+ *         <h3>{product.name}</h3>
+ *       </div>
+ *     )}
+ *   </ProductsList.ItemContent>
+ * </ProductsList.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example - pages/search.tsx
+ * import { GetServerSideProps } from 'next';
+ * import { loadProductsListServiceConfig } from '@wix/stores/services';
+ * import { ProductsList } from '@wix/stores/components';
+ *
+ * interface SearchPageProps {
+ *   productsListConfig: Awaited<ReturnType<typeof loadProductsListServiceConfig>>;
+ *   searchQuery: string;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<SearchPageProps> = async ({ query }) => {
+ *   const searchQuery = (query.q as string) || '';
+ *   const category = query.category as string;
+ *
+ *   // Build search options
+ *   const searchOptions = {
+ *     query: { search: searchQuery },
+ *     filter: category ? { categories: [category] } : undefined,
+ *     paging: { limit: 12 }
+ *   };
+ *
+ *   // Load products during SSR
+ *   const productsListConfig = await loadProductsListServiceConfig(searchOptions);
+ *
+ *   return {
+ *     props: {
+ *       productsListConfig,
+ *       searchQuery,
+ *     },
+ *   };
+ * };
+ *
+ * export default function SearchPage({ productsListConfig, searchQuery }: SearchPageProps) {
+ *   return (
+ *     <div>
+ *       <h1>Search Results for "{searchQuery}"</h1>
+ *       <ProductsList.Root productsListConfig={productsListConfig}>
+ *         <ProductsList.ItemContent>
+ *           {({ product }) => (
+ *             <div className="product-item">
+ *               <h3>{product.name}</h3>
+ *             </div>
+ *           )}
+ *         </ProductsList.ItemContent>
+ *       </ProductsList.Root>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export async function loadProductsListServiceConfig(searchOptions) {
     const result = await productsV3.searchProducts(searchOptions);
     return {

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

@@ -22,4 +22,79 @@ export declare const RelatedProductsService: import("@wix/services-definitions")
     __config: {};
     isServiceDefinition?: boolean;
 } & RelatedProductsServiceAPI, RelatedProductsServiceConfig>;
+/**
+ * Loads related products service configuration for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to create
+ * configuration that tells the RelatedProductsService which product to load related products for.
+ * Unlike other loaders, this creates configuration rather than fetching data during SSR.
+ *
+ * @param productId The ID of the product to find related products for
+ * @param limit Optional number of related products to load (default: 4)
+ * @returns Promise that resolves to RelatedProductsServiceConfig
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/product/[slug].astro
+ * import { loadRelatedProductsServiceConfig } from '@wix/stores/services';
+ * import { RelatedProducts } from '@wix/stores/components';
+ *
+ * // Create related products config for a specific product
+ * const relatedProductsConfig = await loadRelatedProductsServiceConfig(
+ *   'product-id-123',
+ *   6
+ * );
+ * ---
+ *
+ * <RelatedProducts.Root relatedProductsConfig={relatedProductsConfig}>
+ *   <RelatedProducts.List>
+ *     {({ products, isLoading }) => (
+ *       <div>
+ *         {isLoading ? 'Loading...' : `${products.length} related products`}
+ *       </div>
+ *     )}
+ *   </RelatedProducts.List>
+ * </RelatedProducts.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example - pages/product/[slug].tsx
+ * import { GetServerSideProps } from 'next';
+ * import { loadRelatedProductsServiceConfig } from '@wix/stores/services';
+ * import { RelatedProducts } from '@wix/stores/components';
+ *
+ * interface ProductPageProps {
+ *   relatedProductsConfig: Awaited<ReturnType<typeof loadRelatedProductsServiceConfig>>;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<ProductPageProps> = async () => {
+ *   // Create related products config for a specific product
+ *   const relatedProductsConfig = await loadRelatedProductsServiceConfig(
+ *     'product-id-123',
+ *     6
+ *   );
+ *
+ *   return {
+ *     props: {
+ *       relatedProductsConfig,
+ *     },
+ *   };
+ * };
+ *
+ * export default function ProductPage({ relatedProductsConfig }: ProductPageProps) {
+ *   return (
+ *     <RelatedProducts.Root relatedProductsConfig={relatedProductsConfig}>
+ *       <RelatedProducts.List>
+ *         {({ products, isLoading }) => (
+ *           <div>
+ *             {isLoading ? 'Loading...' : `${products.length} related products`}
+ *           </div>
+ *         )}
+ *       </RelatedProducts.List>
+ *     </RelatedProducts.Root>
+ *   );
+ * }
+ * ```
+ */
 export declare function loadRelatedProductsServiceConfig(productId: string, limit?: number): Promise<RelatedProductsServiceConfig>;

package/dist/services/related-products-service.js

@@ -44,6 +44,81 @@ export const RelatedProductsService = implementService.withConfig()(RelatedProdu
         refreshRelatedProducts,
     };
 });
+/**
+ * Loads related products service configuration for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to create
+ * configuration that tells the RelatedProductsService which product to load related products for.
+ * Unlike other loaders, this creates configuration rather than fetching data during SSR.
+ *
+ * @param productId The ID of the product to find related products for
+ * @param limit Optional number of related products to load (default: 4)
+ * @returns Promise that resolves to RelatedProductsServiceConfig
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/product/[slug].astro
+ * import { loadRelatedProductsServiceConfig } from '@wix/stores/services';
+ * import { RelatedProducts } from '@wix/stores/components';
+ *
+ * // Create related products config for a specific product
+ * const relatedProductsConfig = await loadRelatedProductsServiceConfig(
+ *   'product-id-123',
+ *   6
+ * );
+ * ---
+ *
+ * <RelatedProducts.Root relatedProductsConfig={relatedProductsConfig}>
+ *   <RelatedProducts.List>
+ *     {({ products, isLoading }) => (
+ *       <div>
+ *         {isLoading ? 'Loading...' : `${products.length} related products`}
+ *       </div>
+ *     )}
+ *   </RelatedProducts.List>
+ * </RelatedProducts.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example - pages/product/[slug].tsx
+ * import { GetServerSideProps } from 'next';
+ * import { loadRelatedProductsServiceConfig } from '@wix/stores/services';
+ * import { RelatedProducts } from '@wix/stores/components';
+ *
+ * interface ProductPageProps {
+ *   relatedProductsConfig: Awaited<ReturnType<typeof loadRelatedProductsServiceConfig>>;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<ProductPageProps> = async () => {
+ *   // Create related products config for a specific product
+ *   const relatedProductsConfig = await loadRelatedProductsServiceConfig(
+ *     'product-id-123',
+ *     6
+ *   );
+ *
+ *   return {
+ *     props: {
+ *       relatedProductsConfig,
+ *     },
+ *   };
+ * };
+ *
+ * export default function ProductPage({ relatedProductsConfig }: ProductPageProps) {
+ *   return (
+ *     <RelatedProducts.Root relatedProductsConfig={relatedProductsConfig}>
+ *       <RelatedProducts.List>
+ *         {({ products, isLoading }) => (
+ *           <div>
+ *             {isLoading ? 'Loading...' : `${products.length} related products`}
+ *           </div>
+ *         )}
+ *       </RelatedProducts.List>
+ *     </RelatedProducts.Root>
+ *   );
+ * }
+ * ```
+ */
 export async function loadRelatedProductsServiceConfig(productId, limit = 4) {
     return {
         productId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/headless-stores",
-  "version": "0.0.30",
+  "version": "0.0.31",
   "type": "module",
   "scripts": {
     "prebuild": "cd ../media && yarn build && cd ../ecom && yarn build",