@ikas/bp-storefront 0.15.0

package/dist/storefront/src/functions/models/product/index.d.ts

@@ -0,0 +1,1055 @@
+import { CustomerReviewForm, IkasBundleProduct, IkasDisplayedProductGroup, IkasDisplayedVariantType, IkasProduct, IkasProductAttributeMap, IkasProductVariant, IkasVariantValue } from "../../../../../storefront-models/src";
+/**
+ * Initialize product state on the browser by reading variant selections from URL parameters.
+ * Sets the selected variant values based on `vid` query param or variant type slugs in the URL.
+ *
+ * @ai-category Product, ProductDetail
+ * @ai-related getSelectedProductVariant, selectVariantValue, initIkasProductExtraFields
+ *
+ * @param product - The product instance to initialize (modified in place)
+ *
+ * @example
+ * ```typescript
+ * import { initProductOnBrowser } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function initProduct(product: IkasProduct) {
+ *   initProductOnBrowser(product);
+ *   // product.selectedVariantValues is now set based on URL params
+ * }
+ * ```
+ */
+export declare function initProductOnBrowser(product: IkasProduct): void;
+/**
+ * Check if a product has multiple variants (e.g., different sizes or colors).
+ *
+ * @ai-category ProductDetail, ProductList
+ * @ai-related getSelectedProductVariant, getDisplayedProductVariantTypes
+ *
+ * @param product - The product to check
+ * @param showVariantsInGroup - Whether to consider product group variants
+ * @returns True if product has variants, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { hasProductVariant } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function ProductCard({ product }: { product: IkasProduct }) {
+ *   const hasVariants = hasProductVariant(product);
+ *
+ *   return (
+ *     <div>
+ *       {hasVariants && <span>Multiple options available</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function hasProductVariant(product: IkasProduct, showVariantsInGroup?: boolean): boolean;
+/**
+ * Check if any variant of a product has stock available.
+ *
+ * @ai-category ProductDetail, ProductList
+ * @ai-related hasProductVariantStock, getSelectedProductVariant
+ *
+ * @param product - The product to check
+ * @returns True if any variant has stock, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { hasProductStock } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function ProductCard({ product }: { product: IkasProduct }) {
+ *   const inStock = hasProductStock(product);
+ *
+ *   return (
+ *     <div>
+ *       {!inStock && <span className="out-of-stock">Out of Stock</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function hasProductStock(product: IkasProduct): boolean;
+/**
+ * Check if all required product options have been selected.
+ * Used to validate before adding to cart.
+ *
+ * @ai-category ProductDetail
+ * @ai-related addItemToCart, getSelectedProductVariant
+ *
+ * @param product - The product to validate
+ * @returns True if all required options are selected, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { hasProductValidOptionValues, addItemToCart, getSelectedProductVariant } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * async function handleAddToCart(product: IkasProduct) {
+ *   if (!hasProductValidOptionValues(product)) {
+ *     showToast("Please select all required options");
+ *     return;
+ *   }
+ *
+ *   const variant = getSelectedProductVariant(product);
+ *   await addItemToCart(variant, product, 1);
+ * }
+ * ```
+ */
+export declare function hasProductValidOptionValues(product: IkasProduct): boolean;
+/**
+ * Get the currently selected product variant based on selected variant values.
+ * This is the primary function for getting the variant to add to cart.
+ *
+ * @ai-category ProductDetail, ProductList, Cart
+ * @ai-related addItemToCart, hasProductVariantStock, getProductVariantFormattedFinalPrice
+ *
+ * @param product - The product with selectedVariantValues set
+ * @returns The matching product variant
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   getSelectedProductVariant,
+ *   hasProductVariantStock,
+ *   getProductVariantFormattedFinalPrice
+ * } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function ProductDetail({ product }: { product: IkasProduct }) {
+ *   const selectedVariant = getSelectedProductVariant(product);
+ *
+ *   return (
+ *     <div>
+ *       <p>Price: {getProductVariantFormattedFinalPrice(selectedVariant)}</p>
+ *       <p>In Stock: {hasProductVariantStock(selectedVariant) ? "Yes" : "No"}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function getSelectedProductVariant(product: IkasProduct): IkasProductVariant;
+/**
+ * Get the first (main) selected variant value for a product.
+ * Useful for displaying the primary variant selection such as color or size.
+ *
+ * @ai-category ProductDetail, Variant
+ * @ai-related getMainProductVariantType, getSelectedProductVariant, selectVariantValue
+ *
+ * @param product - The product to get the main variant value from
+ * @returns The first selected variant value, or undefined if none selected
+ *
+ * @example
+ * ```typescript
+ * import { getMainProductVariantValue } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function ProductCard({ product }: { product: IkasProduct }) {
+ *   const mainValue = getMainProductVariantValue(product);
+ *   return <span>{mainValue?.name}</span>;
+ * }
+ * ```
+ */
+export declare function getMainProductVariantValue(product: IkasProduct): IkasVariantValue | undefined;
+/**
+ * Get the first (main) variant type for a product (e.g., "Color" or "Size").
+ * Returns undefined if the product has no variants.
+ *
+ * @ai-category ProductDetail, Variant
+ * @ai-related getMainProductVariantValue, getDisplayedProductVariantTypes, hasProductVariant
+ *
+ * @param product - The product to get the main variant type from
+ * @returns The first variant type, or undefined if the product has no variants
+ *
+ * @example
+ * ```typescript
+ * import { getMainProductVariantType } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function ProductCard({ product }: { product: IkasProduct }) {
+ *   const mainType = getMainProductVariantType(product);
+ *   if (mainType) {
+ *     return <span>{mainType.name}: {mainType.values.length} options</span>;
+ *   }
+ *   return null;
+ * }
+ * ```
+ */
+export declare function getMainProductVariantType(product: IkasProduct): import("../../../../../storefront-models/src").IkasVariantType | undefined;
+/**
+ * Get the URL for the currently selected product variant.
+ * Includes variant selection parameters in the URL.
+ *
+ * @ai-category ProductDetail, Navigation
+ * @ai-related getProductHref, Router.navigate
+ *
+ * @param product - The product with selectedVariantValues set
+ * @returns The full URL path including variant parameters
+ *
+ * @example
+ * ```typescript
+ * import { getSelectedProductVariantHref } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function ProductLink({ product }: { product: IkasProduct }) {
+ *   const href = getSelectedProductVariantHref(product);
+ *   return <a href={href}>View Product</a>;
+ * }
+ * ```
+ */
+export declare function getSelectedProductVariantHref(product: IkasProduct): string;
+/**
+ * Get the base URL for a product (without variant parameters).
+ *
+ * @ai-category ProductList, Navigation
+ * @ai-related getSelectedProductVariantHref, Router.navigate
+ *
+ * @param product - The product to get URL for
+ * @returns The product URL path
+ *
+ * @example
+ * ```typescript
+ * import { getProductHref } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function ProductCard({ product }: { product: IkasProduct }) {
+ *   return (
+ *     <a href={getProductHref(product)}>
+ *       <img src={product.images[0]?.src} alt={product.name} />
+ *       <h3>{product.name}</h3>
+ *     </a>
+ *   );
+ * }
+ * ```
+ */
+export declare function getProductHref(product: IkasProduct): string;
+/**
+ * Get variant types with their available values for building variant selectors.
+ * Returns data needed to render size/color/etc. selection UI.
+ *
+ * @ai-category ProductDetail
+ * @ai-related selectVariantValue, getSelectedProductVariant
+ *
+ * @param product - The product to get variant types for
+ * @returns Array of variant types with their displayable values
+ *
+ * @example
+ * ```typescript
+ * import { getDisplayedProductVariantTypes, selectVariantValue } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function VariantSelector({ product }: { product: IkasProduct }) {
+ *   const variantTypes = getDisplayedProductVariantTypes(product);
+ *
+ *   return (
+ *     <div>
+ *       {variantTypes.map(vt => (
+ *         <div key={vt.variantType.id}>
+ *           <label>{vt.variantType.name}</label>
+ *           <div>
+ *             {vt.displayedVariantValues.map(dvv => (
+ *               <button
+ *                 key={dvv.variantValue.id}
+ *                 className={dvv.isSelected ? "selected" : ""}
+ *                 disabled={!dvv.hasStock}
+ *                 onClick={() => selectVariantValue(product, dvv.variantValue)}
+ *               >
+ *                 {dvv.variantValue.name}
+ *                 {!dvv.hasStock && " (Out of stock)"}
+ *               </button>
+ *             ))}
+ *           </div>
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function getDisplayedProductVariantTypes(product: IkasProduct): IkasDisplayedVariantType[];
+/**
+ * Check whether the "Add to Cart" action should be enabled for a product.
+ * Validates that all required option values are selected and the selected variant has stock (or allows overselling).
+ *
+ * @ai-category ProductDetail, Cart
+ * @ai-related hasProductValidOptionValues, hasProductVariantStock, getSelectedProductVariant
+ *
+ * @param product - The product to check
+ * @returns True if the product can be added to cart, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isAddToCartEnabled } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function AddToCartButton({ product }: { product: IkasProduct }) {
+ *   const enabled = isAddToCartEnabled(product);
+ *   return (
+ *     <button disabled={!enabled}>
+ *       {enabled ? "Add to Cart" : "Unavailable"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function isAddToCartEnabled(product: IkasProduct): boolean;
+/**
+ * Check if customer reviews are enabled for the storefront.
+ *
+ * @ai-category Product, ProductDetail
+ * @ai-related isCustomerReviewLoginRequired, getIkasProductCustomerReviewForm
+ *
+ * @param product - The product to check (currently unused; reads from storefront config)
+ * @returns True if customer reviews are enabled in the storefront configuration
+ *
+ * @example
+ * ```typescript
+ * import { isCustomerReviewEnabled } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function ProductReviews({ product }: { product: IkasProduct }) {
+ *   if (!isCustomerReviewEnabled(product)) return null;
+ *   return <div>Reviews section...</div>;
+ * }
+ * ```
+ */
+export declare function isCustomerReviewEnabled(product: IkasProduct): boolean;
+/**
+ * Check if customers must be logged in to leave a review.
+ *
+ * @ai-category Product, ProductDetail
+ * @ai-related isCustomerReviewEnabled, getIkasProductCustomerReviewForm
+ *
+ * @param product - The product to check (currently unused; reads from storefront config)
+ * @returns True if login is required for leaving reviews
+ *
+ * @example
+ * ```typescript
+ * import { isCustomerReviewLoginRequired, isCustomerReviewEnabled, customerStore } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function ReviewForm({ product }: { product: IkasProduct }) {
+ *   if (!isCustomerReviewEnabled(product)) return null;
+ *   if (isCustomerReviewLoginRequired(product) && !customerStore.customer) {
+ *     return <p>Please log in to leave a review.</p>;
+ *   }
+ *   return <form>...</form>;
+ * }
+ * ```
+ */
+export declare function isCustomerReviewLoginRequired(product: IkasProduct): boolean;
+/**
+ * Get product attributes grouped by their attribute ID.
+ * Returns an array of attribute maps with the attribute definition and its values.
+ *
+ * @ai-category Product, Attribute
+ * @ai-related getSelectedProductVariant, getDisplayedProductGroups
+ *
+ * @param product - The product to get attributes from
+ * @returns Array of attribute maps, each containing the attribute definition and its values
+ *
+ * @example
+ * ```typescript
+ * import { getGroupedAttributeValues } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function ProductAttributes({ product }: { product: IkasProduct }) {
+ *   const attributes = getGroupedAttributeValues(product);
+ *   return (
+ *     <ul>
+ *       {attributes.map(attr => (
+ *         <li key={attr.attribute.id}>
+ *           <strong>{attr.attribute.name}:</strong> {attr.values.map(v => v.value).join(", ")}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export declare function getGroupedAttributeValues(product: IkasProduct): IkasProductAttributeMap[];
+/**
+ * Get product group items organized by group type for display.
+ * Builds selectable group options (e.g., different product colors within a product group) with selection state and links.
+ *
+ * @ai-category Product, ProductDetail
+ * @ai-related getSelectedProductVariantHref, getDisplayedProductVariantTypes
+ *
+ * @param product - The product whose group items to display
+ * @returns Array of displayed product groups, each containing group name and selectable items
+ *
+ * @example
+ * ```typescript
+ * import { getDisplayedProductGroups } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function ProductGroupSelector({ product }: { product: IkasProduct }) {
+ *   const groups = getDisplayedProductGroups(product);
+ *   return (
+ *     <div>
+ *       {groups.map(group => (
+ *         <div key={group.name}>
+ *           <h4>{group.name}</h4>
+ *           {group.items.map(item => (
+ *             <a
+ *               key={item.value}
+ *               href={item.href}
+ *               className={item.isSelected ? "selected" : ""}
+ *             >
+ *               {item.value}
+ *             </a>
+ *           ))}
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function getDisplayedProductGroups(product: IkasProduct): IkasDisplayedProductGroup[];
+/**
+ * Select a variant value (e.g., choose a size or color).
+ * Updates product.selectedVariantValues and optionally updates the URL.
+ *
+ * @ai-category ProductDetail
+ * @ai-related getDisplayedProductVariantTypes, getSelectedProductVariant
+ *
+ * @param product - The product to update
+ * @param variantValue - The variant value to select
+ * @param disableRoute - If true, don't update the browser URL
+ *
+ * @example
+ * ```typescript
+ * import { selectVariantValue, getDisplayedProductVariantTypes } from "@ikas/bp-storefront";
+ * import { IkasProduct, IkasVariantValue } from "@ikas/bp-storefront-models";
+ *
+ * function SizeSelector({ product }: { product: IkasProduct }) {
+ *   const variantTypes = getDisplayedProductVariantTypes(product);
+ *   const sizeType = variantTypes.find(vt => vt.variantType.name === "Size");
+ *
+ *   const handleSizeChange = (value: IkasVariantValue) => {
+ *     selectVariantValue(product, value);
+ *     // URL will automatically update with the new selection
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       {sizeType?.displayedVariantValues.map(dvv => (
+ *         <button
+ *           key={dvv.variantValue.id}
+ *           onClick={() => handleSizeChange(dvv.variantValue)}
+ *         >
+ *           {dvv.variantValue.name}
+ *         </button>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function selectVariantValue(product: IkasProduct, variantValue: IkasVariantValue, disableRoute?: boolean): void;
+/**
+ * Fetch and attach active campaigns for a product's variants.
+ * Retrieves campaign data from the API and assigns matching campaigns to each variant.
+ *
+ * @ai-category Product, Pricing
+ * @ai-related getSelectedProductVariant, getProductVariantFormattedFinalPrice
+ *
+ * @param product - The product to fetch campaigns for (modified in place)
+ * @returns The array of campaigns, or undefined if none exist
+ *
+ * @example
+ * ```typescript
+ * import { getProductCampaigns } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * async function loadCampaigns(product: IkasProduct) {
+ *   const campaigns = await getProductCampaigns(product);
+ *   if (campaigns?.length) {
+ *     console.log("Active campaigns:", campaigns);
+ *   }
+ * }
+ * ```
+ */
+export declare function getProductCampaigns(product: IkasProduct): Promise<import("../../../../../storefront-models/src").IkasProductCampaign[] | undefined>;
+/**
+ * Fetch available stock locations for a product's variants.
+ * Queries the API using configured pickup stock location IDs and the product's variant IDs.
+ *
+ * @ai-category Product, Variant
+ * @ai-related getSelectedProductVariant, hasProductStock
+ *
+ * @param product - The product to get stock locations for
+ * @returns Array of variant stock location data
+ *
+ * @example
+ * ```typescript
+ * import { getProductAvailableStockLocations } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * async function showPickupLocations(product: IkasProduct) {
+ *   const locations = await getProductAvailableStockLocations(product);
+ *   locations.forEach(loc => {
+ *     console.log("Available at:", loc);
+ *   });
+ * }
+ * ```
+ */
+export declare function getProductAvailableStockLocations(product: IkasProduct): Promise<import("../../../../../storefront-models/src").IkasProductStockLocations[]>;
+/**
+ * Fetch and attach the product option set if not already loaded.
+ * Loads option set data from the API and sets currency-specific prices for each option.
+ *
+ * @ai-category Product, ProductDetail
+ * @ai-related hasProductValidOptionValues, isAddToCartEnabled
+ *
+ * @param product - The product to load the option set for (modified in place)
+ * @returns True if the product has an option set (already loaded or fetched), false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { getProductOptionSet } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * async function loadProductOptions(product: IkasProduct) {
+ *   const hasOptions = await getProductOptionSet(product);
+ *   if (hasOptions) {
+ *     console.log("Product options:", product.productOptionSet);
+ *   }
+ * }
+ * ```
+ */
+export declare function getProductOptionSet(product: IkasProduct): Promise<boolean>;
+/**
+ * Initialize bundle product data for a product.
+ * If an `editLineID` URL param is present, restores bundle selections from the cart line item;
+ * otherwise loads bundle products for the currently selected variant.
+ *
+ * @ai-category Product, ProductDetail
+ * @ai-related getBundleProductsOfVariant, getSelectedProductVariant, isBundleProductQuantityEditable
+ *
+ * @param product - The product whose bundle products to initialize (modified in place)
+ *
+ * @example
+ * ```typescript
+ * import { initBundleProducts } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * async function loadProduct(product: IkasProduct) {
+ *   await initBundleProducts(product);
+ *   // Bundle products are now loaded on each variant's bundleSettings
+ * }
+ * ```
+ */
+export declare function initBundleProducts(product: IkasProduct): Promise<void>;
+/**
+ * Fetch and attach bundle product data for a specific variant.
+ * Loads the full product data for each bundle product and caches the results on the parent product.
+ *
+ * @ai-category Product, Variant
+ * @ai-related initBundleProducts, setProductOfBundleProduct, getSelectedProductVariant
+ *
+ * @param product - The parent product (modified in place; uses bundleProductCache)
+ * @param variant - The variant whose bundle products to load
+ *
+ * @example
+ * ```typescript
+ * import { getBundleProductsOfVariant, getSelectedProductVariant } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * async function refreshBundleProducts(product: IkasProduct) {
+ *   const variant = getSelectedProductVariant(product);
+ *   await getBundleProductsOfVariant(product, variant);
+ * }
+ * ```
+ */
+export declare function getBundleProductsOfVariant(product: IkasProduct, variant: IkasProductVariant): Promise<void>;
+/**
+ * Check if a bundle product's quantity can be edited by the customer.
+ * Returns true when either a min or max quantity constraint is set.
+ *
+ * @ai-category Product, Pricing
+ * @ai-related setBundleProductQuantity, shouldDisplayBundleProductPrice, initBundleProducts
+ *
+ * @param bundleProduct - The bundle product to check
+ * @returns True if quantity is editable (has min or max constraints), false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isBundleProductQuantityEditable, setBundleProductQuantity } from "@ikas/bp-storefront";
+ * import { IkasBundleProduct } from "@ikas/bp-storefront-models";
+ *
+ * function BundleItem({ bundleProduct }: { bundleProduct: IkasBundleProduct }) {
+ *   const editable = isBundleProductQuantityEditable(bundleProduct);
+ *   return editable ? (
+ *     <input
+ *       type="number"
+ *       value={bundleProduct.quantity}
+ *       onChange={(e) => setBundleProductQuantity(bundleProduct, Number(e.target.value))}
+ *     />
+ *   ) : (
+ *     <span>Qty: {bundleProduct.quantity}</span>
+ *   );
+ * }
+ * ```
+ */
+export declare function isBundleProductQuantityEditable(bundleProduct: IkasBundleProduct): boolean;
+/**
+ * Check if the price of a bundle product should be displayed to the customer.
+ * Only shows the price when the bundle product adds to the bundle's base price.
+ *
+ * @ai-category Product, Pricing
+ * @ai-related getBundleProductFinalPrice, getBundleProductFormattedFinalPrice, isBundleProductQuantityEditable
+ *
+ * @param bundleProduct - The bundle product to check
+ * @returns True if the bundle product price should be displayed
+ *
+ * @example
+ * ```typescript
+ * import { shouldDisplayBundleProductPrice, getBundleProductFormattedFinalPrice } from "@ikas/bp-storefront";
+ * import { IkasBundleProduct } from "@ikas/bp-storefront-models";
+ *
+ * function BundleItem({ bundleProduct }: { bundleProduct: IkasBundleProduct }) {
+ *   return (
+ *     <div>
+ *       <span>{bundleProduct.product?.name}</span>
+ *       {shouldDisplayBundleProductPrice(bundleProduct) && (
+ *         <span>{getBundleProductFormattedFinalPrice(bundleProduct)}</span>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function shouldDisplayBundleProductPrice(bundleProduct: IkasBundleProduct): boolean;
+/**
+ * Calculate the final price of a bundle product after applying any discount ratio.
+ * Uses the selected variant's final price and applies the bundle-specific discount if applicable.
+ *
+ * @ai-category Product, Pricing
+ * @ai-related getBundleProductFormattedFinalPrice, getBundleProductFinalPriceWithQuantity, shouldDisplayBundleProductPrice
+ *
+ * @param bundleProduct - The bundle product to calculate price for
+ * @returns The final price as a number, or 0 if no product is attached
+ *
+ * @example
+ * ```typescript
+ * import { getBundleProductFinalPrice } from "@ikas/bp-storefront";
+ * import { IkasBundleProduct } from "@ikas/bp-storefront-models";
+ *
+ * function BundlePrice({ bundleProduct }: { bundleProduct: IkasBundleProduct }) {
+ *   const price = getBundleProductFinalPrice(bundleProduct);
+ *   return <span>{price.toFixed(2)}</span>;
+ * }
+ * ```
+ */
+export declare function getBundleProductFinalPrice(bundleProduct: IkasBundleProduct): number;
+/**
+ * Get the formatted (currency-aware) final price string for a bundle product.
+ *
+ * @ai-category Product, Pricing
+ * @ai-related getBundleProductFinalPrice, getBundleProductFormattedFinalPriceWithQuantity, shouldDisplayBundleProductPrice
+ *
+ * @param bundleProduct - The bundle product to format price for
+ * @returns Formatted price string with currency symbol
+ *
+ * @example
+ * ```typescript
+ * import { getBundleProductFormattedFinalPrice, shouldDisplayBundleProductPrice } from "@ikas/bp-storefront";
+ * import { IkasBundleProduct } from "@ikas/bp-storefront-models";
+ *
+ * function BundleItemPrice({ bundleProduct }: { bundleProduct: IkasBundleProduct }) {
+ *   if (!shouldDisplayBundleProductPrice(bundleProduct)) return null;
+ *   return <span>{getBundleProductFormattedFinalPrice(bundleProduct)}</span>;
+ * }
+ * ```
+ */
+export declare function getBundleProductFormattedFinalPrice(bundleProduct: IkasBundleProduct): string;
+/**
+ * Calculate the total final price of a bundle product multiplied by its quantity.
+ *
+ * @ai-category Product, Pricing
+ * @ai-related getBundleProductFinalPrice, getBundleProductFormattedFinalPriceWithQuantity
+ *
+ * @param bundleProduct - The bundle product to calculate total price for
+ * @returns The total price (unit final price times quantity)
+ *
+ * @example
+ * ```typescript
+ * import { getBundleProductFinalPriceWithQuantity } from "@ikas/bp-storefront";
+ * import { IkasBundleProduct } from "@ikas/bp-storefront-models";
+ *
+ * function BundleTotal({ bundleProduct }: { bundleProduct: IkasBundleProduct }) {
+ *   const total = getBundleProductFinalPriceWithQuantity(bundleProduct);
+ *   return <span>Total: {total.toFixed(2)}</span>;
+ * }
+ * ```
+ */
+export declare function getBundleProductFinalPriceWithQuantity(bundleProduct: IkasBundleProduct): number;
+/**
+ * Get the formatted total final price string for a bundle product (unit price times quantity).
+ *
+ * @ai-category Product, Pricing
+ * @ai-related getBundleProductFinalPriceWithQuantity, getBundleProductFormattedFinalPrice
+ *
+ * @param bundleProduct - The bundle product to format total price for
+ * @returns Formatted total price string with currency symbol
+ *
+ * @example
+ * ```typescript
+ * import { getBundleProductFormattedFinalPriceWithQuantity } from "@ikas/bp-storefront";
+ * import { IkasBundleProduct } from "@ikas/bp-storefront-models";
+ *
+ * function BundleItemTotal({ bundleProduct }: { bundleProduct: IkasBundleProduct }) {
+ *   return <span>{getBundleProductFormattedFinalPriceWithQuantity(bundleProduct)}</span>;
+ * }
+ * ```
+ */
+export declare function getBundleProductFormattedFinalPriceWithQuantity(bundleProduct: IkasBundleProduct): string;
+/**
+ * Get the sell price (before discounts) of a bundle product's selected variant.
+ *
+ * @ai-category Product, Pricing
+ * @ai-related getBundleProductFormattedSellPrice, getBundleProductSellPriceWithQuantity, getBundleProductFinalPrice
+ *
+ * @param bundleProduct - The bundle product to get sell price for
+ * @returns The sell price as a number, or 0 if no product is attached
+ *
+ * @example
+ * ```typescript
+ * import { getBundleProductSellPrice, getBundleProductFinalPrice } from "@ikas/bp-storefront";
+ * import { IkasBundleProduct } from "@ikas/bp-storefront-models";
+ *
+ * function BundleDiscount({ bundleProduct }: { bundleProduct: IkasBundleProduct }) {
+ *   const sell = getBundleProductSellPrice(bundleProduct);
+ *   const final = getBundleProductFinalPrice(bundleProduct);
+ *   const discount = sell - final;
+ *   return discount > 0 ? <span>You save: {discount.toFixed(2)}</span> : null;
+ * }
+ * ```
+ */
+export declare function getBundleProductSellPrice(bundleProduct: IkasBundleProduct): number;
+/**
+ * Get the formatted (currency-aware) sell price string for a bundle product.
+ *
+ * @ai-category Product, Pricing
+ * @ai-related getBundleProductSellPrice, getBundleProductFormattedSellPriceWithQuantity, getBundleProductFormattedFinalPrice
+ *
+ * @param bundleProduct - The bundle product to format sell price for
+ * @returns Formatted sell price string with currency symbol
+ *
+ * @example
+ * ```typescript
+ * import { getBundleProductFormattedSellPrice } from "@ikas/bp-storefront";
+ * import { IkasBundleProduct } from "@ikas/bp-storefront-models";
+ *
+ * function BundleOriginalPrice({ bundleProduct }: { bundleProduct: IkasBundleProduct }) {
+ *   return <span className="original-price">{getBundleProductFormattedSellPrice(bundleProduct)}</span>;
+ * }
+ * ```
+ */
+export declare function getBundleProductFormattedSellPrice(bundleProduct: IkasBundleProduct): string;
+/**
+ * Calculate the total sell price of a bundle product multiplied by its quantity.
+ *
+ * @ai-category Product, Pricing
+ * @ai-related getBundleProductSellPrice, getBundleProductFormattedSellPriceWithQuantity, getBundleProductFinalPriceWithQuantity
+ *
+ * @param bundleProduct - The bundle product to calculate total sell price for
+ * @returns The total sell price (unit sell price times quantity)
+ *
+ * @example
+ * ```typescript
+ * import { getBundleProductSellPriceWithQuantity } from "@ikas/bp-storefront";
+ * import { IkasBundleProduct } from "@ikas/bp-storefront-models";
+ *
+ * function BundleOriginalTotal({ bundleProduct }: { bundleProduct: IkasBundleProduct }) {
+ *   const total = getBundleProductSellPriceWithQuantity(bundleProduct);
+ *   return <span className="original-price">Total: {total.toFixed(2)}</span>;
+ * }
+ * ```
+ */
+export declare function getBundleProductSellPriceWithQuantity(bundleProduct: IkasBundleProduct): number;
+/**
+ * Get the formatted total sell price string for a bundle product (unit sell price times quantity).
+ *
+ * @ai-category Product, Pricing
+ * @ai-related getBundleProductSellPriceWithQuantity, getBundleProductFormattedSellPrice, getBundleProductFormattedFinalPriceWithQuantity
+ *
+ * @param bundleProduct - The bundle product to format total sell price for
+ * @returns Formatted total sell price string with currency symbol
+ *
+ * @example
+ * ```typescript
+ * import { getBundleProductFormattedSellPriceWithQuantity } from "@ikas/bp-storefront";
+ * import { IkasBundleProduct } from "@ikas/bp-storefront-models";
+ *
+ * function BundleOriginalTotal({ bundleProduct }: { bundleProduct: IkasBundleProduct }) {
+ *   return (
+ *     <span className="original-price">
+ *       {getBundleProductFormattedSellPriceWithQuantity(bundleProduct)}
+ *     </span>
+ *   );
+ * }
+ * ```
+ */
+export declare function getBundleProductFormattedSellPriceWithQuantity(bundleProduct: IkasBundleProduct): string;
+/**
+ * Attach a product to a bundle product entry, filtering its variants to only those allowed by the bundle.
+ * Sets default selected variant values to the first filtered variant and resets quantity.
+ *
+ * @ai-category Product, Variant
+ * @ai-related getBundleProductsOfVariant, initBundleProducts, setBundleProductQuantity
+ *
+ * @param bundleProduct - The bundle product entry to attach the product to (modified in place)
+ * @param product - The full product data to attach (filtered and modified in place)
+ *
+ * @example
+ * ```typescript
+ * import { setProductOfBundleProduct } from "@ikas/bp-storefront";
+ * import { IkasBundleProduct, IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function attachProduct(bundleProduct: IkasBundleProduct, product: IkasProduct) {
+ *   setProductOfBundleProduct(bundleProduct, product);
+ *   // bundleProduct.product is now set with filtered variants
+ * }
+ * ```
+ */
+export declare function setProductOfBundleProduct(bundleProduct: IkasBundleProduct, product: IkasProduct): void;
+/**
+ * Set the quantity for a bundle product, respecting min/max constraints and available stock.
+ * Clamps the value to the allowed range and does nothing if quantity is negative or no product is attached.
+ *
+ * @ai-category Product, Pricing
+ * @ai-related isBundleProductQuantityEditable, getBundleProductFinalPriceWithQuantity, initBundleProducts
+ *
+ * @param bundleProduct - The bundle product to update (modified in place)
+ * @param quantity - The desired quantity
+ *
+ * @example
+ * ```typescript
+ * import { setBundleProductQuantity, isBundleProductQuantityEditable } from "@ikas/bp-storefront";
+ * import { IkasBundleProduct } from "@ikas/bp-storefront-models";
+ *
+ * function QuantityControl({ bundleProduct }: { bundleProduct: IkasBundleProduct }) {
+ *   if (!isBundleProductQuantityEditable(bundleProduct)) return null;
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => setBundleProductQuantity(bundleProduct, bundleProduct.quantity - 1)}>-</button>
+ *       <span>{bundleProduct.quantity}</span>
+ *       <button onClick={() => setBundleProductQuantity(bundleProduct, bundleProduct.quantity + 1)}>+</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function setBundleProductQuantity(bundleProduct: IkasBundleProduct, quantity: number): void;
+/**
+ * Recalculate option prices based on the selected variant's price list and final price.
+ * For ratio-based options, computes the actual price from the variant's final price and the ratio.
+ *
+ * @ai-category Product, Pricing
+ * @ai-related getProductOptionSet, getSelectedProductVariant, selectVariantValue
+ *
+ * @param product - The product whose option prices to recalculate (modified in place)
+ *
+ * @example
+ * ```typescript
+ * import { setOptionRealPrices } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function recalculateOptions(product: IkasProduct) {
+ *   setOptionRealPrices(product);
+ *   // product.productOptionSet option prices are now updated
+ * }
+ * ```
+ */
+export declare function setOptionRealPrices(product: IkasProduct): void;
+/**
+ * Get the full category breadcrumb path for a product based on its first category.
+ * Returns an empty array if the product has no categories.
+ *
+ * @ai-category Product, Navigation
+ * @ai-related getProductFirstCategory, getProductHref
+ *
+ * @param product - The product to get category path for
+ * @returns Array of categories forming the breadcrumb path
+ *
+ * @example
+ * ```typescript
+ * import { getProductCategoryPath } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function Breadcrumb({ product }: { product: IkasProduct }) {
+ *   const path = getProductCategoryPath(product);
+ *   return (
+ *     <nav>
+ *       {path.map((category, i) => (
+ *         <span key={category.id}>
+ *           {i > 0 && " / "}
+ *           <a href={category.href}>{category.name}</a>
+ *         </span>
+ *       ))}
+ *     </nav>
+ *   );
+ * }
+ * ```
+ */
+export declare function getProductCategoryPath(product: IkasProduct): import("../../../../../storefront-models/src").IkasCategoryPathItem[];
+/**
+ * Get the first category assigned to a product.
+ * Returns null if the product has no categories.
+ *
+ * @ai-category Product, Navigation
+ * @ai-related getProductCategoryPath, getProductHref
+ *
+ * @param product - The product to get the first category from
+ * @returns The first category, or null if none exist
+ *
+ * @example
+ * ```typescript
+ * import { getProductFirstCategory } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function ProductCategory({ product }: { product: IkasProduct }) {
+ *   const category = getProductFirstCategory(product);
+ *   return category ? <span>{category.name}</span> : null;
+ * }
+ * ```
+ */
+export declare function getProductFirstCategory(product: IkasProduct): import("../../../../../storefront-models/src").IkasCategory | null;
+/**
+ * Get or create the customer review form for a product.
+ * Lazily initializes the form on first access and caches it in the customer store.
+ *
+ * @ai-category Product, ProductDetail
+ * @ai-related clearIkasProductCustomerReviewForm, isCustomerReviewEnabled, isCustomerReviewLoginRequired
+ *
+ * @param product - The product to get the review form for
+ * @returns The customer review form instance for this product
+ *
+ * @example
+ * ```typescript
+ * import { getIkasProductCustomerReviewForm, isCustomerReviewEnabled } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function ReviewForm({ product }: { product: IkasProduct }) {
+ *   if (!isCustomerReviewEnabled(product)) return null;
+ *   const form = getIkasProductCustomerReviewForm(product);
+ *   return (
+ *     <form>
+ *       <textarea value={form.comment} />
+ *     </form>
+ *   );
+ * }
+ * ```
+ */
+export declare function getIkasProductCustomerReviewForm(product: IkasProduct): CustomerReviewForm;
+/**
+ * Clear the cached customer review form for a product.
+ * Removes the form from the customer store so it will be re-initialized on next access.
+ *
+ * @ai-category Product, ProductDetail
+ * @ai-related getIkasProductCustomerReviewForm, isCustomerReviewEnabled
+ *
+ * @param product - The product whose review form to clear
+ *
+ * @example
+ * ```typescript
+ * import { clearIkasProductCustomerReviewForm } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function handleReviewSubmitted(product: IkasProduct) {
+ *   clearIkasProductCustomerReviewForm(product);
+ *   // Form will be fresh when the user opens the review form again
+ * }
+ * ```
+ */
+export declare function clearIkasProductCustomerReviewForm(product: IkasProduct): void;
+/**
+ * Check if a product is in the customer's favorites list.
+ *
+ * @ai-category ProductList, ProductDetail, Customer
+ * @ai-related addIkasProductToFavorites, removeIkasProductFromFavorites
+ *
+ * @param product - The product to check
+ * @returns True if product is favorited, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isFavoriteIkasProduct, addIkasProductToFavorites, removeIkasProductFromFavorites } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * function FavoriteButton({ product }: { product: IkasProduct }) {
+ *   const isFavorite = isFavoriteIkasProduct(product);
+ *
+ *   const handleClick = async () => {
+ *     if (isFavorite) {
+ *       await removeIkasProductFromFavorites(product);
+ *     } else {
+ *       await addIkasProductToFavorites(product);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleClick}>
+ *       {isFavorite ? "Remove from favorites" : "Add to favorites"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function isFavoriteIkasProduct(product: IkasProduct): boolean;
+/**
+ * Add a product to the customer's favorites list.
+ * Requires customer to be logged in.
+ *
+ * @ai-category ProductList, ProductDetail, Customer
+ * @ai-related isFavoriteIkasProduct, removeIkasProductFromFavorites
+ *
+ * @param product - The product to add to favorites
+ * @returns True if successful
+ *
+ * @example
+ * ```typescript
+ * import { addIkasProductToFavorites, customerStore } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * async function handleAddToFavorites(product: IkasProduct) {
+ *   if (!customerStore.customer) {
+ *     // Redirect to login
+ *     Router.navigateToPage("LOGIN");
+ *     return;
+ *   }
+ *
+ *   await addIkasProductToFavorites(product);
+ *   showToast("Added to favorites!");
+ * }
+ * ```
+ */
+export declare function addIkasProductToFavorites(product: IkasProduct): Promise<boolean>;
+/**
+ * Remove a product from the customer's favorites list.
+ *
+ * @ai-category ProductList, ProductDetail, Customer
+ * @ai-related isFavoriteIkasProduct, addIkasProductToFavorites
+ *
+ * @param product - The product to remove from favorites
+ * @returns True if successful
+ *
+ * @example
+ * ```typescript
+ * import { removeIkasProductFromFavorites } from "@ikas/bp-storefront";
+ * import { IkasProduct } from "@ikas/bp-storefront-models";
+ *
+ * async function handleRemoveFromFavorites(product: IkasProduct) {
+ *   await removeIkasProductFromFavorites(product);
+ *   showToast("Removed from favorites");
+ * }
+ * ```
+ */
+export declare function removeIkasProductFromFavorites(product: IkasProduct): Promise<boolean>;