@wix/headless-stores 0.0.35 → 0.0.37

package/cjs/dist/services/buy-now-service.d.ts

@@ -1,57 +1,155 @@
 import { type Signal } from "@wix/services-definitions/core-services/signals";
+/**
+ * Service definition for the Buy Now service.
+ * This defines the reactive API contract for managing buy now functionality.
+ *
+ * @constant
+ */
 export declare const BuyNowServiceDefinition: string & {
     __api: {
+        /** Function to redirect to checkout with the current product */
         redirectToCheckout: () => Promise<void>;
+        /** Reactive signal indicating if a checkout redirect is in progress */
         loadingSignal: Signal<boolean>;
+        /** Reactive signal containing any error message, or null if no error */
         errorSignal: Signal<string | null>;
+        /** Reactive signal indicating if the product is in stock */
         inStockSignal: Signal<boolean>;
+        /** Reactive signal indicating if pre-order is available */
         preOrderAvailableSignal: Signal<boolean>;
+        /** The name of the product */
         productName: string;
+        /** The price of the product as a string */
         price: string;
+        /** The currency code for the product price */
         currency: string;
     };
     __config: {};
     isServiceDefinition?: boolean;
 } & {
+    /** Function to redirect to checkout with the current product */
     redirectToCheckout: () => Promise<void>;
+    /** Reactive signal indicating if a checkout redirect is in progress */
     loadingSignal: Signal<boolean>;
+    /** Reactive signal containing any error message, or null if no error */
     errorSignal: Signal<string | null>;
+    /** Reactive signal indicating if the product is in stock */
     inStockSignal: Signal<boolean>;
+    /** Reactive signal indicating if pre-order is available */
     preOrderAvailableSignal: Signal<boolean>;
+    /** The name of the product */
     productName: string;
+    /** The price of the product as a string */
     price: string;
+    /** The currency code for the product price */
     currency: string;
 };
+/**
+ * Configuration interface for the Buy Now service.
+ * Contains all the product information needed to initialize the buy now functionality.
+ *
+ * @interface BuyNowServiceConfig
+ */
 export interface BuyNowServiceConfig {
+    /** The unique product ID */
     productId: string;
+    /** The optional variant ID if a specific variant is selected */
     variantId?: string;
+    /** The display name of the product */
     productName: string;
+    /** The price of the product as a string */
     price: string;
+    /** The currency code for the product price */
     currency: string;
+    /** Whether the product is currently in stock */
     inStock: boolean;
+    /** Whether pre-order is available for this product */
     preOrderAvailable: boolean;
 }
+/**
+ * Implementation of the Buy Now service that manages buy now functionality.
+ * This service provides signals for loading state, stock status, and error handling,
+ * along with a method to redirect directly to checkout.
+ *
+ * @example
+ * ```tsx
+ * import { BuyNowServiceImplementation, BuyNowServiceDefinition } from '@wix/stores/services';
+ * import { useService } from '@wix/services-manager-react';
+ *
+ * function BuyNowComponent({ buyNowConfig }) {
+ *   return (
+ *     <ServiceProvider services={createServicesMap([
+ *       [BuyNowServiceDefinition, BuyNowServiceImplementation.withConfig(buyNowConfig)]
+ *     ])}>
+ *       <BuyNowButton />
+ *     </ServiceProvider>
+ *   );
+ * }
+ *
+ * function BuyNowButton() {
+ *   const buyNowService = useService(BuyNowServiceDefinition);
+ *   const isLoading = buyNowService.loadingSignal.get();
+ *   const error = buyNowService.errorSignal.get();
+ *   const inStock = buyNowService.inStockSignal.get();
+ *
+ *   const handleBuyNow = async () => {
+ *     await buyNowService.redirectToCheckout();
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       {error && <div className="error">{error}</div>}
+ *       <button
+ *         onClick={handleBuyNow}
+ *         disabled={!inStock || isLoading}
+ *         className={`buy-now-btn ${!inStock ? 'out-of-stock' : ''}`}
+ *       >
+ *         {isLoading ? 'Processing...' :
+ *          !inStock ? 'Out of Stock' :
+ *          `Buy Now - ${buyNowService.currency}${buyNowService.price}`}
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export declare const BuyNowServiceImplementation: import("@wix/services-definitions").ServiceFactory<string & {
     __api: {
+        /** Function to redirect to checkout with the current product */
         redirectToCheckout: () => Promise<void>;
+        /** Reactive signal indicating if a checkout redirect is in progress */
         loadingSignal: Signal<boolean>;
+        /** Reactive signal containing any error message, or null if no error */
         errorSignal: Signal<string | null>;
+        /** Reactive signal indicating if the product is in stock */
         inStockSignal: Signal<boolean>;
+        /** Reactive signal indicating if pre-order is available */
         preOrderAvailableSignal: Signal<boolean>;
+        /** The name of the product */
         productName: string;
+        /** The price of the product as a string */
         price: string;
+        /** The currency code for the product price */
         currency: string;
     };
     __config: {};
     isServiceDefinition?: boolean;
 } & {
+    /** Function to redirect to checkout with the current product */
     redirectToCheckout: () => Promise<void>;
+    /** Reactive signal indicating if a checkout redirect is in progress */
     loadingSignal: Signal<boolean>;
+    /** Reactive signal containing any error message, or null if no error */
     errorSignal: Signal<string | null>;
+    /** Reactive signal indicating if the product is in stock */
     inStockSignal: Signal<boolean>;
+    /** Reactive signal indicating if pre-order is available */
     preOrderAvailableSignal: Signal<boolean>;
+    /** The name of the product */
     productName: string;
+    /** The price of the product as a string */
     price: string;
+    /** The currency code for the product price */
     currency: string;
 }, {
     productId: string;
@@ -62,6 +160,58 @@ export declare const BuyNowServiceImplementation: import("@wix/services-definiti
     inStock: boolean;
     preOrderAvailable: boolean;
 }>;
+/**
+ * Loads buy now service initial data from the Wix Stores API for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to preload
+ * product data required for the buy now functionality.
+ *
+ * @param {string} productSlug - The product slug to load data for
+ * @param {string} [variantId] - Optional variant ID if a specific variant should be used
+ * @returns {Promise} Promise that resolves to the buy now service configuration data
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/product/[slug].astro
+ * import { loadBuyNowServiceInitialData } from '@wix/stores/services';
+ * import { BuyNow } from '@wix/stores/components';
+ *
+ * const { slug } = Astro.params;
+ * const variantId = Astro.url.searchParams.get('variant');
+ *
+ * // Load buy now data during SSR
+ * const buyNowData = await loadBuyNowServiceInitialData(slug, variantId);
+ * ---
+ *
+ * <BuyNow.BuyNow buyNowConfig={buyNowData.BuyNow}>
+ *   {({ redirectToCheckout, isLoading, inStock, price, currency }) => (
+ *     <button onClick={redirectToCheckout} disabled={!inStock || isLoading}>
+ *       {isLoading ? 'Loading...' : `Buy Now ${currency}${price}`}
+ *     </button>
+ *   )}
+ * </BuyNow.BuyNow>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example
+ * import { GetServerSideProps } from 'next';
+ * import { loadBuyNowServiceInitialData } from '@wix/stores/services';
+ *
+ * export const getServerSideProps: GetServerSideProps = async ({ params, query }) => {
+ *   const slug = params?.slug as string;
+ *   const variantId = query.variant as string | undefined;
+ *
+ *   const buyNowData = await loadBuyNowServiceInitialData(slug, variantId);
+ *
+ *   return {
+ *     props: {
+ *       buyNowData,
+ *     },
+ *   };
+ * };
+ * ```
+ */
 export declare const loadBuyNowServiceInitialData: (productSlug: string, variantId?: string) => Promise<{
     [BuyNowServiceDefinition]: {
         productId: string;
@@ -73,51 +223,109 @@ export declare const loadBuyNowServiceInitialData: (productSlug: string, variant
         preOrderAvailable: boolean | undefined;
     };
 }>;
+/**
+ * Helper function to create a buy now service binding with configuration.
+ * This function simplifies the process of binding the buy now service with its configuration
+ * and allows for additional configuration overrides.
+ *
+ * @template T - Type of the services configurations object
+ * @param {T} servicesConfigs - Object containing service configurations
+ * @param {Partial<BuyNowServiceConfig>} [additionalConfig={}] - Additional configuration to override defaults
+ * @returns Tuple containing service definition, implementation, and merged configuration
+ *
+ * @example
+ * ```tsx
+ * import { buyNowServiceBinding, loadBuyNowServiceInitialData } from '@wix/stores/services';
+ *
+ * // Load initial data
+ * const initialData = await loadBuyNowServiceInitialData('my-product-slug');
+ *
+ * // Create service binding with additional config
+ * const buyNowBinding = buyNowServiceBinding(initialData, {
+ *   inStock: false, // Override stock status
+ * });
+ *
+ * // Use in service provider
+ * const services = createServicesMap([buyNowBinding]);
+ * ```
+ */
 export declare const buyNowServiceBinding: <T extends {
     [key: string]: Awaited<ReturnType<typeof loadBuyNowServiceInitialData>>[typeof BuyNowServiceDefinition];
 }>(servicesConfigs: T, additionalConfig?: Partial<BuyNowServiceConfig>) => readonly [string & {
     __api: {
+        /** Function to redirect to checkout with the current product */
         redirectToCheckout: () => Promise<void>;
+        /** Reactive signal indicating if a checkout redirect is in progress */
         loadingSignal: Signal<boolean>;
+        /** Reactive signal containing any error message, or null if no error */
         errorSignal: Signal<string | null>;
+        /** Reactive signal indicating if the product is in stock */
         inStockSignal: Signal<boolean>;
+        /** Reactive signal indicating if pre-order is available */
         preOrderAvailableSignal: Signal<boolean>;
+        /** The name of the product */
         productName: string;
+        /** The price of the product as a string */
         price: string;
+        /** The currency code for the product price */
         currency: string;
     };
     __config: {};
     isServiceDefinition?: boolean;
 } & {
+    /** Function to redirect to checkout with the current product */
     redirectToCheckout: () => Promise<void>;
+    /** Reactive signal indicating if a checkout redirect is in progress */
     loadingSignal: Signal<boolean>;
+    /** Reactive signal containing any error message, or null if no error */
     errorSignal: Signal<string | null>;
+    /** Reactive signal indicating if the product is in stock */
     inStockSignal: Signal<boolean>;
+    /** Reactive signal indicating if pre-order is available */
     preOrderAvailableSignal: Signal<boolean>;
+    /** The name of the product */
     productName: string;
+    /** The price of the product as a string */
     price: string;
+    /** The currency code for the product price */
     currency: string;
 }, import("@wix/services-definitions").ServiceFactory<string & {
     __api: {
+        /** Function to redirect to checkout with the current product */
         redirectToCheckout: () => Promise<void>;
+        /** Reactive signal indicating if a checkout redirect is in progress */
         loadingSignal: Signal<boolean>;
+        /** Reactive signal containing any error message, or null if no error */
         errorSignal: Signal<string | null>;
+        /** Reactive signal indicating if the product is in stock */
         inStockSignal: Signal<boolean>;
+        /** Reactive signal indicating if pre-order is available */
         preOrderAvailableSignal: Signal<boolean>;
+        /** The name of the product */
         productName: string;
+        /** The price of the product as a string */
         price: string;
+        /** The currency code for the product price */
         currency: string;
     };
     __config: {};
     isServiceDefinition?: boolean;
 } & {
+    /** Function to redirect to checkout with the current product */
     redirectToCheckout: () => Promise<void>;
+    /** Reactive signal indicating if a checkout redirect is in progress */
     loadingSignal: Signal<boolean>;
+    /** Reactive signal containing any error message, or null if no error */
     errorSignal: Signal<string | null>;
+    /** Reactive signal indicating if the product is in stock */
     inStockSignal: Signal<boolean>;
+    /** Reactive signal indicating if pre-order is available */
     preOrderAvailableSignal: Signal<boolean>;
+    /** The name of the product */
     productName: string;
+    /** The price of the product as a string */
     price: string;
+    /** The currency code for the product price */
     currency: string;
 }, {
     productId: string;

package/cjs/dist/services/buy-now-service.js

@@ -1,8 +1,61 @@
-import { defineService, implementService, } from "@wix/services-definitions";
+import { defineService, implementService } from "@wix/services-definitions";
 import { SignalsServiceDefinition, } from "@wix/services-definitions/core-services/signals";
 import { getCheckoutUrlForProduct } from "../utils/index.js";
 import { getProductBySlug } from "@wix/auto_sdk_stores_products-v-3";
+/**
+ * Service definition for the Buy Now service.
+ * This defines the reactive API contract for managing buy now functionality.
+ *
+ * @constant
+ */
 export const BuyNowServiceDefinition = defineService("BuyNow");
+/**
+ * Implementation of the Buy Now service that manages buy now functionality.
+ * This service provides signals for loading state, stock status, and error handling,
+ * along with a method to redirect directly to checkout.
+ *
+ * @example
+ * ```tsx
+ * import { BuyNowServiceImplementation, BuyNowServiceDefinition } from '@wix/stores/services';
+ * import { useService } from '@wix/services-manager-react';
+ *
+ * function BuyNowComponent({ buyNowConfig }) {
+ *   return (
+ *     <ServiceProvider services={createServicesMap([
+ *       [BuyNowServiceDefinition, BuyNowServiceImplementation.withConfig(buyNowConfig)]
+ *     ])}>
+ *       <BuyNowButton />
+ *     </ServiceProvider>
+ *   );
+ * }
+ *
+ * function BuyNowButton() {
+ *   const buyNowService = useService(BuyNowServiceDefinition);
+ *   const isLoading = buyNowService.loadingSignal.get();
+ *   const error = buyNowService.errorSignal.get();
+ *   const inStock = buyNowService.inStockSignal.get();
+ *
+ *   const handleBuyNow = async () => {
+ *     await buyNowService.redirectToCheckout();
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       {error && <div className="error">{error}</div>}
+ *       <button
+ *         onClick={handleBuyNow}
+ *         disabled={!inStock || isLoading}
+ *         className={`buy-now-btn ${!inStock ? 'out-of-stock' : ''}`}
+ *       >
+ *         {isLoading ? 'Processing...' :
+ *          !inStock ? 'Out of Stock' :
+ *          `Buy Now - ${buyNowService.currency}${buyNowService.price}`}
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export const BuyNowServiceImplementation = implementService.withConfig()(BuyNowServiceDefinition, ({ getService, config }) => {
     const signalsService = getService(SignalsServiceDefinition);
     const loadingSignal = signalsService.signal(false);
@@ -30,6 +83,58 @@ export const BuyNowServiceImplementation = implementService.withConfig()(BuyNowS
         currency: config.currency,
     };
 });
+/**
+ * Loads buy now service initial data from the Wix Stores API for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to preload
+ * product data required for the buy now functionality.
+ *
+ * @param {string} productSlug - The product slug to load data for
+ * @param {string} [variantId] - Optional variant ID if a specific variant should be used
+ * @returns {Promise} Promise that resolves to the buy now service configuration data
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/product/[slug].astro
+ * import { loadBuyNowServiceInitialData } from '@wix/stores/services';
+ * import { BuyNow } from '@wix/stores/components';
+ *
+ * const { slug } = Astro.params;
+ * const variantId = Astro.url.searchParams.get('variant');
+ *
+ * // Load buy now data during SSR
+ * const buyNowData = await loadBuyNowServiceInitialData(slug, variantId);
+ * ---
+ *
+ * <BuyNow.BuyNow buyNowConfig={buyNowData.BuyNow}>
+ *   {({ redirectToCheckout, isLoading, inStock, price, currency }) => (
+ *     <button onClick={redirectToCheckout} disabled={!inStock || isLoading}>
+ *       {isLoading ? 'Loading...' : `Buy Now ${currency}${price}`}
+ *     </button>
+ *   )}
+ * </BuyNow.BuyNow>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example
+ * import { GetServerSideProps } from 'next';
+ * import { loadBuyNowServiceInitialData } from '@wix/stores/services';
+ *
+ * export const getServerSideProps: GetServerSideProps = async ({ params, query }) => {
+ *   const slug = params?.slug as string;
+ *   const variantId = query.variant as string | undefined;
+ *
+ *   const buyNowData = await loadBuyNowServiceInitialData(slug, variantId);
+ *
+ *   return {
+ *     props: {
+ *       buyNowData,
+ *     },
+ *   };
+ * };
+ * ```
+ */
 export const loadBuyNowServiceInitialData = async (productSlug, variantId) => {
     const res = await getProductBySlug(productSlug, {
         fields: ["CURRENCY"],
@@ -54,6 +159,32 @@ export const loadBuyNowServiceInitialData = async (productSlug, variantId) => {
         },
     };
 };
+/**
+ * Helper function to create a buy now service binding with configuration.
+ * This function simplifies the process of binding the buy now service with its configuration
+ * and allows for additional configuration overrides.
+ *
+ * @template T - Type of the services configurations object
+ * @param {T} servicesConfigs - Object containing service configurations
+ * @param {Partial<BuyNowServiceConfig>} [additionalConfig={}] - Additional configuration to override defaults
+ * @returns Tuple containing service definition, implementation, and merged configuration
+ *
+ * @example
+ * ```tsx
+ * import { buyNowServiceBinding, loadBuyNowServiceInitialData } from '@wix/stores/services';
+ *
+ * // Load initial data
+ * const initialData = await loadBuyNowServiceInitialData('my-product-slug');
+ *
+ * // Create service binding with additional config
+ * const buyNowBinding = buyNowServiceBinding(initialData, {
+ *   inStock: false, // Override stock status
+ * });
+ *
+ * // Use in service provider
+ * const services = createServicesMap([buyNowBinding]);
+ * ```
+ */
 export const buyNowServiceBinding = (servicesConfigs, additionalConfig = {}) => {
     return [
         BuyNowServiceDefinition,

package/cjs/dist/services/categories-list-service.d.ts

@@ -0,0 +1,163 @@
+import { type Signal } from "@wix/services-definitions/core-services/signals";
+import { categories } from "@wix/categories";
+/**
+ * Configuration interface for the Categories List service.
+ * Contains the initial categories data that will be loaded into the service.
+ *
+ * @interface CategoriesListServiceConfig
+ */
+export type CategoriesListServiceConfig = {
+    /** Array of category objects to initialize the service with */
+    categories: categories.Category[];
+};
+/**
+ * Service definition for the Categories List service.
+ * This defines the reactive API contract for managing a list of product categories.
+ *
+ * @constant
+ */
+export declare const CategoriesListServiceDefinition: string & {
+    __api: {
+        /** Reactive signal containing the list of categories */
+        categories: Signal<categories.Category[]>;
+        /** Reactive signal indicating if categories are currently being loaded */
+        isLoading: Signal<boolean>;
+        /** Reactive signal containing any error message, or null if no error */
+        error: Signal<string | null>;
+    };
+    __config: CategoriesListServiceConfig;
+    isServiceDefinition?: boolean;
+} & {
+    /** Reactive signal containing the list of categories */
+    categories: Signal<categories.Category[]>;
+    /** Reactive signal indicating if categories are currently being loaded */
+    isLoading: Signal<boolean>;
+    /** Reactive signal containing any error message, or null if no error */
+    error: Signal<string | null>;
+};
+/**
+ * Implementation of the Categories List service that manages reactive categories data.
+ * This service provides signals for categories data, loading state, and error handling.
+ * The service is initialized with pre-loaded categories and maintains them in reactive signals.
+ *
+ * @example
+ * ```tsx
+ * import { CategoriesListService, CategoriesListServiceDefinition } from '@wix/stores/services';
+ * import { useService } from '@wix/services-manager-react';
+ *
+ * function CategoriesComponent({ categoriesConfig }) {
+ *   return (
+ *     <ServiceProvider services={createServicesMap([
+ *       [CategoriesListServiceDefinition, CategoriesListService.withConfig(categoriesConfig)]
+ *     ])}>
+ *       <CategoriesDisplay />
+ *     </ServiceProvider>
+ *   );
+ * }
+ *
+ * function CategoriesDisplay() {
+ *   const categoriesService = useService(CategoriesListServiceDefinition);
+ *   const categories = categoriesService.categories.get();
+ *   const isLoading = categoriesService.isLoading.get();
+ *   const error = categoriesService.error.get();
+ *
+ *   if (isLoading) return <div>Loading categories...</div>;
+ *   if (error) return <div>Error: {error}</div>;
+ *
+ *   return (
+ *     <ul>
+ *       {categories.map(category => (
+ *         <li key={category._id}>{category.name}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export declare const CategoriesListService: import("@wix/services-definitions").ServiceFactory<string & {
+    __api: {
+        /** Reactive signal containing the list of categories */
+        categories: Signal<categories.Category[]>;
+        /** Reactive signal indicating if categories are currently being loaded */
+        isLoading: Signal<boolean>;
+        /** Reactive signal containing any error message, or null if no error */
+        error: Signal<string | null>;
+    };
+    __config: CategoriesListServiceConfig;
+    isServiceDefinition?: boolean;
+} & {
+    /** Reactive signal containing the list of categories */
+    categories: Signal<categories.Category[]>;
+    /** Reactive signal indicating if categories are currently being loaded */
+    isLoading: Signal<boolean>;
+    /** Reactive signal containing any error message, or null if no error */
+    error: Signal<string | null>;
+}, CategoriesListServiceConfig>;
+/**
+ * Loads categories list service configuration from the Wix Categories API for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to preload
+ * all visible product categories. The "all-products" category is automatically moved to the front of the list.
+ *
+ * @returns {Promise<CategoriesListServiceConfig>} Promise that resolves to the categories configuration
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/categories.astro
+ * import { loadCategoriesListServiceConfig } from '@wix/stores/services';
+  * import { CategoryList } from '@wix/stores/components';
+ *
+ * // Load categories data during SSR
+ * const categoriesConfig = await loadCategoriesListServiceConfig();
+ * ---
+ *
+ * <CategoryList.Root categoriesConfig={categoriesConfig}>
+ *   <CategoryList.ItemContent>
+ *     {({ category }) => (
+ *       <div>
+ *         <h3>{category.name}</h3>
+ *         <p>{category.description}</p>
+ *       </div>
+ *     )}
+ *   </CategoryList.ItemContent>
+ * </CategoryList.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example - pages/categories.tsx
+ * import { GetServerSideProps } from 'next';
+ * import { loadCategoriesListServiceConfig } from '@wix/stores/services';
+  * import { CategoryList } from '@wix/stores/components';
+ *
+ * interface CategoriesPageProps {
+ *   categoriesConfig: Awaited<ReturnType<typeof loadCategoriesListServiceConfig>>;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<CategoriesPageProps> = async () => {
+ *   const categoriesConfig = await loadCategoriesListServiceConfig();
+ *
+ *   return {
+ *     props: {
+ *       categoriesConfig,
+ *     },
+ *   };
+ * };
+ *
+ * export default function CategoriesPage({ categoriesConfig }: CategoriesPageProps) {
+ *   return (
+ *     <CategoryList.Root categoriesConfig={categoriesConfig}>
+ *       <CategoryList.ItemContent>
+ *         {({ category }) => (
+ *           <div>
+ *             <h3>{category.name}</h3>
+ *             <p>{category.description}</p>
+ *           </div>
+ *         )}
+ *       </CategoryList.ItemContent>
+ *     </CategoryList.Root>
+ *   );
+ * }
+ * ```
+ */
+export declare function loadCategoriesListServiceConfig(): Promise<CategoriesListServiceConfig>;