@liquidcommerce/elements-sdk 2.7.0 → 2.7.2

package/docs/EVENTS.md

@@ -1,798 +0,0 @@
-# Elements SDK Events - Partner Implementation Guide
-
-> **Browser Support**: This SDK supports 2018+ browsers (Chrome 66+, Firefox 60+, Safari 12+) with comprehensive polyfills. See `docs/BROWSER_SUPPORT.md` for details.
-
-## What Are Events and Why Use Them?
-
-Events are real-time notifications that tell you exactly what your customers are doing on your site. Think of them as your digital sales assistant that whispers in your ear every time a customer looks at a product, adds something to cart, or starts checkout.
-
-**Business Benefits:**
-- **Track Revenue Impact**: See which products drive the most sales
-- **Optimize Conversion**: Identify where customers drop off
-- **Personalize Experience**: Trigger custom actions based on customer behavior
-- **Measure Performance**: Get real metrics on your e-commerce funnel
-- **Automate Marketing**: Send targeted emails/SMS based on customer actions
-
-## How It Works
-
-When customers interact with your LiquidCommerce elements, events automatically fire. You simply "listen" for these events and take action:
-
-```javascript
-// Example: When someone adds to cart, send them a discount code
-window.addEventListener('lce:actions.product_add_to_cart', function(event) {
-  // Customer just added a product to cart!
-  const data = event.detail.data;
-  
-  // Maybe send them a discount popup
-  showDiscountPopup(data.identifier);
-  
-  // Or track in your analytics
-  analytics.track('Product Added', {
-    identifier: data.identifier,
-    quantity: data.quantity,
-    upc: data.upc
-  });
-});
-```
-
-## Quick Implementation Guide
-
-### Step 1: Choose Your Goal
-What do you want to achieve? Pick one:
-
-**🎯 Track Sales Performance**
-```javascript
-// Track when products are viewed and added to cart
-window.addEventListener('lce:actions.product_loaded', function(event) {
-  // Product was viewed - track in your analytics
-  const product = event.detail.data;
-  console.log('Customer viewed:', product.name);
-});
-
-window.addEventListener('lce:actions.product_add_to_cart', function(event) {
-  // Product was added to cart - this is a conversion!
-  const data = event.detail.data;
-  console.log('SALE OPPORTUNITY:', data.identifier, 'qty:', data.quantity);
-});
-```
-
-**🛒 Recover Abandoned Carts**
-```javascript
-// Detect when someone opens cart but doesn't buy
-window.addEventListener('lce:actions.cart_opened', function(event) {
-  // Start a timer - if they don't complete purchase in 10 minutes, send email
-  setTimeout(function() {
-    sendAbandonedCartEmail();
-  }, 10 * 60 * 1000); // 10 minutes
-});
-
-window.addEventListener('lce:actions.checkout_submit_completed', function(event) {
-  // They bought! Cancel the abandoned cart email
-  cancelAbandonedCartEmail();
-});
-```
-
-**💰 Maximize Revenue**
-```javascript
-// Offer upsells when they add expensive items
-window.addEventListener('lce:actions.product_add_to_cart', function(event) {
-  const data = event.detail.data;
-  
-  // Trigger upsell based on product identifier
-  showUpsellPopup(data.identifier);
-});
-```
-
-## Step 2: Complete Event List & What They Mean
-
-### 🚀 SDK Lifecycle Events
-```javascript
-// When SDK is ready to use
-'lce:actions.client_ready' // → "SDK is initialized and ready to use"
-```
-
-**Example Usage:**
-```javascript
-window.addEventListener('lce:actions.client_ready', function(event) {
-  const { isReady, message, timestamp, version } = event.detail.data;
-  console.log('SDK Ready:', version);
-  // Now safe to call SDK methods
-});
-```
-
-### 🛍️ Product Events (Track Customer Interest)
-```javascript
-// When a customer views a product
-'lce:actions.product_loaded' // → "Customer is interested in this product"
-
-// When they add to cart
-'lce:actions.product_add_to_cart' // → "Hot lead! Customer wants to buy"
-
-// When they change quantity
-'lce:actions.product_quantity_increase' // → "Customer wants more"
-'lce:actions.product_quantity_decrease' // → "Customer wants less"
-
-// When they change options
-'lce:actions.product_size_changed' // → "Customer has size preferences"
-'lce:actions.product_fulfillment_type_changed' // → "Delivery preference changed"
-'lce:actions.product_fulfillment_changed' // → "Customer selected specific retailer/fulfillment"
-```
-
-**Note on Personalization:** Product personalization (engraving) is added during the add-to-cart action. The personalization is included in the `product_add_to_cart` event data. Once in cart, use `cart_item_engraving_updated` to track changes.
-
-#### Product Details Event Data
-When `lce:actions.product_loaded` fires, you get comprehensive product information:
-
-```javascript
-window.addEventListener('lce:actions.product_loaded', function(event) {
-  const product = event.detail.data;
-  
-  // Basic Information
-  console.log(product.id);              // Product ID
-  console.log(product.name);            // Product name
-  console.log(product.brand);           // Brand name
-  console.log(product.category);        // Category
-  console.log(product.catPath);         // Category path
-  console.log(product.classification);  // Product classification
-  console.log(product.type);            // Product type
-  console.log(product.subType);         // Product sub-type
-  console.log(product.salsifyGrouping); // Salsify grouping ID
-  
-  // Visual Assets
-  console.log(product.mainImage);       // Main product image URL
-  console.log(product.images);          // Array of all product images
-  
-  // Product Attributes
-  console.log(product.region);          // Region (e.g., "Napa Valley")
-  console.log(product.country);         // Country of origin
-  console.log(product.material);        // Material type
-  console.log(product.abv);             // Alcohol by volume
-  console.log(product.proof);           // Proof
-  console.log(product.age);             // Age statement
-  console.log(product.color);           // Color description
-  console.log(product.flavor);          // Flavor profile
-  console.log(product.variety);         // Variety (e.g., "Cabernet Sauvignon")
-  console.log(product.appellation);     // Appellation
-  console.log(product.vintage);         // Vintage year
-  
-  // Descriptions
-  console.log(product.description);     // Plain text description
-  console.log(product.htmlDescription); // HTML formatted description
-  console.log(product.tastingNotes);    // Tasting notes
-  
-  // Pricing
-  console.log(product.priceInfo);       // { min, max, avg } pricing across fulfillments
-  
-  // Available Sizes & Fulfillments
-  console.log(product.sizes);           // All available sizes with fulfillment options
-  console.log(product.selectedSizeId);  // Currently selected size
-  console.log(product.selectedFulfillmentId);   // Currently selected fulfillment
-  console.log(product.selectedFulfillmentType); // 'shipping' or 'onDemand'
-});
-```
-
-**Use Cases:**
-- **Rich Analytics**: Track which product attributes drive conversions
-- **Personalized Recommendations**: Suggest similar products based on variety, region, or flavor
-- **Content Display**: Show detailed product information on your custom UI
-- **Search & Filtering**: Build custom search based on product attributes
-
-### 🛒 Cart Events (Track Purchase Intent)
-```javascript
-// Cart lifecycle
-'lce:actions.cart_loaded' // → "Cart data has been loaded and is ready"
-'lce:actions.cart_opened' // → "Customer is reviewing their purchase"
-'lce:actions.cart_closed' // → "Customer might be comparison shopping"
-
-// Cart changes
-'lce:actions.cart_updated' // → "Customer modified their order"
-'lce:actions.cart_reset' // → "Customer cleared everything - intervention needed!"
-'lce:actions.cart_failed' // → "Cart operation failed"
-
-// Item management
-'lce:actions.cart_item_added' // → "Customer committed to another product"
-'lce:actions.cart_item_removed' // → "Customer changed their mind"
-'lce:actions.cart_item_quantity_increase' // → "Customer added more of an item"
-'lce:actions.cart_item_quantity_decrease' // → "Customer reduced item quantity"
-'lce:actions.cart_item_engraving_updated' // → "Customer updated/removed item personalization"
-```
-
-**Personalization Events:**
-```javascript
-// Track when customers add or modify personalization
-window.addEventListener('lce:actions.cart_item_engraving_updated', function(event) {
-  const { identifier, engravingLines, hasEngraving } = event.detail.data;
-  
-  if (hasEngraving && engravingLines.length > 0) {
-    console.log(`Personalization added/updated: ${engravingLines.join(', ')}`);
-  } else {
-    console.log('Personalization removed from item');
-  }
-});
-```
-
-#### Cart Details Event Data
-When `lce:actions.cart_loaded` or `lce:actions.cart_updated` fires, you get complete cart information:
-
-```javascript
-window.addEventListener('lce:actions.cart_loaded', function(event) {
-  const cart = event.detail.data;
-  
-  // Cart Identification
-  console.log(cart.id);                 // Cart ID
-  console.log(cart.promoCode);          // Applied promo code (if any)
-  
-  // Cart Items
-  console.log(cart.items);              // Object with all cart items
-  console.log(cart.itemCount);          // Total number of items in cart
-  
-  // Each item contains:
-  Object.values(cart.items).forEach(item => {
-    console.log(item.id);               // Cart item ID
-    console.log(item.name);             // Product name
-    console.log(item.brand);            // Brand
-    console.log(item.salsifyGrouping);  // Salsify grouping ID
-    console.log(item.catPath);          // Category path
-    console.log(item.size);             // Size description
-    console.log(item.volume);           // Volume
-    console.log(item.uom);              // Unit of measure
-    console.log(item.pack);             // Is pack (boolean)
-    console.log(item.packDesc);         // Pack description
-    console.log(item.container);        // Container type
-    console.log(item.containerType);    // Container type classification
-    console.log(item.price);            // Total price (unitPrice × quantity)
-    console.log(item.unitPrice);        // Price per unit
-    console.log(item.quantity);         // Quantity
-    console.log(item.maxQuantity);      // Maximum allowed quantity
-    console.log(item.mainImage);        // Product image URL
-    console.log(item.upc);              // UPC code
-    console.log(item.sku);              // SKU
-    console.log(item.partNumber);       // Part number
-    console.log(item.retailerId);       // Retailer ID
-    console.log(item.fulfillmentId);    // Fulfillment ID
-    console.log(item.attributes);       // Item attributes (engraving, etc.)
-  });
-  
-  // Location Information
-  console.log(cart.location.placesId);           // Google Places ID
-  console.log(cart.location.address);            // Address object
-  console.log(cart.location.coordinates);        // Lat/long coordinates
-  
-  // Financial Breakdown
-  console.log(cart.amounts.subtotal);            // Subtotal
-  console.log(cart.amounts.deliveryFee);         // Delivery fee
-  console.log(cart.amounts.shippingFee);         // Shipping fee
-  console.log(cart.amounts.platformFee);         // Platform fee
-  console.log(cart.amounts.engravingFee);        // Engraving/personalization fee
-  console.log(cart.amounts.discounts);           // Total discounts
-  console.log(cart.amounts.giftCardTotal);       // Gift card total applied
-  console.log(cart.amounts.total);               // Final total
-  
-  // Timestamps
-  console.log(cart.createdAt);          // When cart was created
-  console.log(cart.updatedAt);          // Last update timestamp
-});
-```
-
-**Use Cases:**
-- **Abandoned Cart Recovery**: Track cart value and items for targeted recovery campaigns
-- **Revenue Analytics**: Monitor average cart value, most popular items, cart composition
-- **Inventory Management**: Track which products are frequently added/removed
-- **Pricing Analysis**: Analyze impact of fees, discounts, and gift cards on cart totals
-
-### 💳 Checkout Events (Track Purchase Process)
-```javascript
-// Checkout lifecycle
-'lce:actions.checkout_loaded' // → "Checkout data has been loaded and is ready"
-'lce:actions.checkout_opened' // → "Customer is ready to buy!"
-'lce:actions.checkout_closed' // → "Customer left checkout"
-'lce:actions.checkout_failed' // → "Checkout operation failed"
-
-// Checkout submission
-'lce:actions.checkout_submit_started' // → "Payment processing..."
-'lce:actions.checkout_submit_completed' // → "SALE COMPLETED! 🎉"
-'lce:actions.checkout_submit_failed' // → "Sale lost - fix the issue!"
-
-// Form updates (Security: returns boolean only, no sensitive data)
-'lce:actions.checkout_customer_information_updated' // → "Customer filling out details"
-// Data: boolean (true) - No customer data exposed for security
-'lce:actions.checkout_billing_information_updated' // → "Payment info being entered"
-// Data: boolean (true) - No billing data exposed for security
-'lce:actions.checkout_gift_information_updated' // → "Gift recipient info updated"
-// Data: boolean (true) - No recipient data exposed for security
-
-// Checkout options
-'lce:actions.checkout_is_gift_toggled' // → "Customer toggled gift option"
-'lce:actions.checkout_billing_same_as_shipping_toggled' // → "Customer toggled billing address option"
-'lce:actions.checkout_marketing_preferences_toggled' // → "Customer updated marketing preferences"
-
-// Item management in checkout
-'lce:actions.checkout_item_removed' // → "Customer removed item from checkout"
-'lce:actions.checkout_item_quantity_increase' // → "Customer increased item quantity in checkout"
-'lce:actions.checkout_item_quantity_decrease' // → "Customer decreased item quantity in checkout"
-'lce:actions.checkout_item_engraving_updated' // → "Customer removed personalization in checkout"
-
-// Tips (for on-demand delivery)
-'lce:actions.checkout_tip_updated' // → "Customer updated delivery tip"
-```
-
-**🔒 Security Note on Form Update Events:**
-The following events return only a boolean `true` value instead of customer data for security reasons:
-- `checkout_customer_information_updated` - No customer contact details exposed
-- `checkout_billing_information_updated` - No payment or billing address details exposed
-- `checkout_gift_information_updated` - No gift recipient details exposed
-
-This design prevents malicious scripts from intercepting sensitive customer information (names, emails, phone numbers, addresses, etc.) while still allowing you to track form completion for analytics. **This is intentional and prioritizes customer privacy and security.**
-
-```javascript
-// ✅ Correct: Track form completion securely
-window.addEventListener('lce:actions.checkout_customer_information_updated', function(event) {
-  const completed = event.detail.data; // boolean: true
-
-  // Track the milestone without exposing customer data
-  analytics.track('Checkout Step Completed', { step: 'customer_info' });
-  updateProgressBar('customer_info');
-});
-
-window.addEventListener('lce:actions.checkout_billing_information_updated', function(event) {
-  const completed = event.detail.data; // boolean: true
-
-  // Track billing form completion
-  analytics.track('Checkout Step Completed', { step: 'billing_info' });
-  updateProgressBar('billing_info');
-});
-
-// 🚫 You will NOT receive customer data like names, emails, addresses, etc.
-// This protects your customers from malicious scripts and data breaches.
-```
-
-**Important Note on Checkout Personalization:**
-Personalization cannot be edited during checkout - only removed. This is by design to prevent order processing complications. If a customer wants to modify personalization, they must return to the cart. The checkout only displays personalization details and provides a remove option.
-
-#### Checkout Details Event Data
-When you call `actions.checkout.getDetails()`, you get comprehensive checkout information:
-
-**Note:** The `lce:actions.checkout_loaded` event only contains `{ cartId: string }`. To get full checkout details, use `actions.checkout.getDetails()`.
-
-```javascript
-// Get full checkout details via action
-const checkout = actions.checkout.getDetails();
-  
-  // Checkout Identification
-  console.log(checkout.cartId);                    // Associated cart ID
-  
-  // Checkout Status Flags
-  console.log(checkout.acceptedAccountCreation);   // Customer accepted account creation
-  console.log(checkout.hasAgeVerify);              // Age verification required
-  console.log(checkout.hasSubstitutionPolicy);     // Substitution policy accepted
-  console.log(checkout.isGift);                    // Order is a gift
-  console.log(checkout.billingSameAsShipping);     // Billing address same as shipping
-  console.log(checkout.hasPromoCode);              // Promo code applied
-  console.log(checkout.hasGiftCards);              // Gift cards applied
-  
-  // Marketing Preferences
-  console.log(checkout.marketingPreferences.canEmail); // Email opt-in status
-  console.log(checkout.marketingPreferences.canSms);   // SMS opt-in status
-  
-  // Order Summary
-  console.log(checkout.itemCount);                 // Total items in checkout
-  
-  // Financial Breakdown
-  console.log(checkout.amounts.subtotal);          // Subtotal
-  console.log(checkout.amounts.deliveryFee);       // Delivery fee
-  console.log(checkout.amounts.shippingFee);       // Shipping fee
-  console.log(checkout.amounts.platformFee);       // Platform fee
-  console.log(checkout.amounts.engravingFee);      // Engraving/personalization fee
-  console.log(checkout.amounts.discounts);         // Total discounts
-  console.log(checkout.amounts.giftCardTotal);     // Gift card total applied
-  console.log(checkout.amounts.tax);               // Tax amount
-  console.log(checkout.amounts.bottleDeposits);    // Bottle deposit fees
-  console.log(checkout.amounts.total);             // Final total
-  
-  // Checkout Items (detailed product information)
-  console.log(checkout.items);                     // Object with all checkout items
-  
-// Each checkout item contains comprehensive details:
-Object.values(checkout.items).forEach(item => {
-  console.log(item.cartItemId);        // Cart item ID
-  console.log(item.liquidId);          // Liquid ID
-  console.log(item.variantId);         // Variant ID
-  console.log(item.name);              // Product name
-  console.log(item.brand);             // Brand
-  console.log(item.salsifyGrouping);   // Salsify grouping ID
-  console.log(item.catPath);           // Category path
-  
-  // Size & Container Information
-  console.log(item.size);              // Size description
-  console.log(item.volume);            // Volume
-  console.log(item.uom);               // Unit of measure
-  console.log(item.pack);              // Is pack (boolean)
-  console.log(item.packDesc);          // Pack description
-  console.log(item.container);         // Container type
-  console.log(item.containerType);     // Container type classification
-  
-  // Product Attributes
-  console.log(item.proof);             // Proof
-  console.log(item.abv);               // Alcohol by volume
-  
-  // Pricing
-  console.log(item.price);             // Total price (unitPrice × quantity)
-  console.log(item.unitPrice);         // Price per unit
-  console.log(item.unitTax);           // Tax per unit
-  console.log(item.bottleDeposits);    // Bottle deposit fees
-  console.log(item.quantity);          // Quantity
-  
-  // Identifiers
-  console.log(item.upc);               // UPC code
-  console.log(item.sku);               // SKU
-  console.log(item.partNumber);        // Part number
-  
-  // Fulfillment Information
-  console.log(item.retailerId);        // Retailer ID
-  console.log(item.retailerName);      // Retailer name
-  console.log(item.fulfillmentId);     // Fulfillment ID
-  console.log(item.expectationDetail); // Delivery expectation details
-  
-  // Visual Assets
-  console.log(item.mainImage);         // Product image URL
-  
-  // Item Attributes (engraving, etc.)
-  console.log(item.attributes);        // Item attributes object
-});
-```
-
-**Use Cases:**
-- **Order Analytics**: Track checkout completion rates, average order values, popular items
-- **Marketing Optimization**: Analyze opt-in rates, gift order patterns, promo code effectiveness
-- **Revenue Tracking**: Monitor tax collection, fees, discounts, and gift card usage
-- **Customer Insights**: Understand purchasing patterns, preferred retailers, delivery preferences
-- **Compliance**: Track age verification requirements, substitution policy acceptance
-
-### 📍 Address Events (Track Shipping Preferences)
-```javascript
-'lce:actions.address_updated' // → "Customer entered shipping address"
-'lce:actions.address_cleared' // → "Customer removed address"
-'lce:actions.address_failed' // → "Address validation failed"
-```
-
-### 🔔 **NEW: Action Feedback Events** (Track Action Success/Failure)
-
-These events fire when programmatic actions succeed or fail, giving you complete control over user feedback:
-
-#### 🛒 **Cart Action Feedback**
-```javascript
-// Product addition feedback
-'lce:actions.cart_product_add_success' // → "Products successfully added to cart"
-// Data: { itemsAdded: number, identifiers: string[] }
-
-'lce:actions.cart_product_add_failed' // → "Products could not be added to cart"
-// Data: { identifiers: string[], error: string }
-
-// Promo code feedback
-'lce:actions.cart_promo_code_applied' // → "Promo code worked - show success!"
-// Data: { discount?: number, newTotal?: number }
-
-'lce:actions.cart_promo_code_removed' // → "Promo code removed successfully"
-// Data: { newTotal?: number }
-
-'lce:actions.cart_promo_code_failed' // → "Promo code didn't work - show error"
-// Data: { error: string }
-```
-
-#### 💳 **Checkout Action Feedback**
-```javascript
-// Product addition feedback
-'lce:actions.checkout_product_add_success' // → "Products added to checkout successfully"
-// Data: { itemsAdded: number, identifiers: string[], isPresale?: boolean }
-
-'lce:actions.checkout_product_add_failed' // → "Could not add products to checkout"
-// Data: { identifiers: string[], error: string, isPresale?: boolean }
-
-// Promo code feedback
-'lce:actions.checkout_promo_code_applied' // → "Checkout discount applied!"
-// Data: { discount?: number, newTotal?: number }
-
-'lce:actions.checkout_promo_code_removed' // → "Checkout discount removed"
-// Data: { newTotal?: number }
-
-'lce:actions.checkout_promo_code_failed' // → "Checkout discount failed"
-// Data: { error: string }
-
-// Gift card feedback
-'lce:actions.checkout_gift_card_applied' // → "Gift card applied successfully!"
-// Data: { newTotal?: number }
-
-'lce:actions.checkout_gift_card_removed' // → "Gift card removed"
-// Data: { newTotal?: number }
-
-'lce:actions.checkout_gift_card_failed' // → "Gift card could not be applied"
-// Data: { error: string }
-```
-
-#### 🔒 **Security Note**
-Action feedback events **never expose sensitive information** like promo codes or gift card codes. This prevents malicious scripts from stealing sensitive data while still providing rich feedback for legitimate developers.
-
-**Example: Secure Action Feedback**
-```javascript
-// Fire the action (simple)
-await actions.cart.applyPromoCode('SECRET20');
-
-// Get feedback (secure)
-window.addEventListener('lce:actions.cart_promo_code_applied', function(event) {
-  const { discount, newTotal } = event.detail.data;
-  // ✅ You get: discount amount, new total
-  // 🚫 You DON'T get: 'SECRET20' (secure!)
-
-  showSuccessMessage(`🎉 Discount applied! You saved $${discount}!`);
-  updateCartTotal(newTotal);
-});
-```
-
-## Step 3: Real-World Implementation Examples
-
-### 🔔 **NEW Example: Smart Action Feedback with Perfect UX**
-```javascript
-// Perfect promo code experience with action feedback
-async function applyPromoCodeWithFeedback(code) {
-  // Show loading state
-  showLoadingMessage('Applying promo code...');
-  
-  // Set up event listeners BEFORE firing action
-  const successHandler = (event) => {
-    const { discount, newTotal } = event.detail.data;
-    hideLoadingMessage();
-    showSuccessMessage(`🎉 Success! You saved $${discount}!`);
-    updatePriceDisplay(newTotal);
-
-    // Track successful promo usage
-    analytics.track('Promo Applied', {
-      discount: discount,
-      newTotal: newTotal
-    });
-
-    // Clean up
-    cleanup();
-  };
-
-  const failureHandler = (event) => {
-    const { error } = event.detail.data;
-    hideLoadingMessage();
-    showErrorMessage('Promo code could not be applied. Please try again.');
-
-    // Track failed attempts (for optimization)
-    analytics.track('Promo Failed', { error: error });
-
-    // Maybe suggest alternatives
-    suggestAlternativePromos();
-
-    // Clean up
-    cleanup();
-  };
-  
-  const cleanup = () => {
-    window.removeEventListener('lce:actions.cart_promo_code_applied', successHandler);
-    window.removeEventListener('lce:actions.cart_promo_code_failed', failureHandler);
-  };
-  
-  // Attach listeners
-  window.addEventListener('lce:actions.cart_promo_code_applied', successHandler);
-  window.addEventListener('lce:actions.cart_promo_code_failed', failureHandler);
-  
-  // Fire the action
-  await actions.cart.applyPromoCode(code);
-}
-
-// Usage: Perfect UX every time!
-applyPromoCodeWithFeedback('SAVE20');
-```
-
-### 🎯 Example 1: Boost Your Sales with Smart Promotions
-```javascript
-// Automatically offer discounts for high-value carts
-window.addEventListener('lce:actions.cart_updated', function(event) {
-  const cart = event.detail.data.current;
-  
-  if (cart.amounts.total > 200 && !cart.promoCode) {
-    // Show them a 10% off popup
-    showPopup("Get 10% off orders over $200! Use code: SAVE10");
-  }
-});
-
-// Track which products make people abandon checkout
-window.addEventListener('lce:actions.checkout_opened', function(event) {
-  window.checkoutStartTime = new Date();
-});
-
-window.addEventListener('lce:actions.checkout_closed', function(event) {
-  // If they close checkout without buying, they abandoned
-  if (window.checkoutStartTime) {
-    const timeSpent = new Date() - window.checkoutStartTime;
-    console.log('Checkout abandoned after', timeSpent/1000, 'seconds');
-    // Send this data to your analytics to find problem products
-  }
-});
-```
-
-### 📧 Example 2: Automated Email Marketing
-```javascript
-// Build an email list from cart abandoners
-window.addEventListener('lce:actions.cart_opened', function(event) {
-  // Customer opened cart - start tracking
-  window.cartOpenTime = new Date();
-  window.cartItems = event.detail.data.items;
-});
-
-window.addEventListener('lce:actions.checkout_submit_completed', function(event) {
-  // They bought! No need for abandonment email
-  window.cartOpenTime = null;
-});
-
-// Check every 5 minutes if cart was abandoned
-setInterval(function() {
-  if (window.cartOpenTime) {
-    const timeSinceOpen = new Date() - window.cartOpenTime;
-    if (timeSinceOpen > 15 * 60 * 1000) { // 15 minutes
-      // Send abandonment email with cart items
-      sendAbandonmentEmail(window.cartItems);
-      window.cartOpenTime = null; // Don't send again
-    }
-  }
-}, 5 * 60 * 1000);
-```
-
-### 📊 Example 3: Track Your Best-Performing Products
-```javascript
-// Keep a running tally of product performance
-let productStats = {};
-
-window.addEventListener('lce:actions.product_loaded', function(event) {
-  const product = event.detail.data;
-  
-  // Initialize stats if first time seeing this product
-  if (!productStats[product.id]) {
-    productStats[product.id] = {
-      name: product.name,
-      views: 0,
-      addedToCarts: 0,
-      conversions: 0
-    };
-  }
-  
-  productStats[product.id].views++;
-});
-
-window.addEventListener('lce:actions.product_add_to_cart', function(event) {
-  const data = event.detail.data;
-  // Note: product_add_to_cart only has identifier, not full product details
-  if (productStats[data.identifier]) {
-    productStats[data.identifier].addedToCarts++;
-  }
-});
-
-window.addEventListener('lce:actions.checkout_submit_completed', function(event) {
-  const order = event.detail.data;
-  console.log('Order completed:', order.orderNumber, 'Total:', order.orderTotal);
-  
-  // Send stats to your analytics dashboard
-  console.log('Product Performance:', productStats);
-  
-  // Track conversion in analytics
-  analytics.track('Purchase', {
-    orderNumber: order.orderNumber,
-    total: order.orderTotal
-  });
-});
-```
-
-### 🔥 Example 4: Create Urgency with Live Updates
-```javascript
-// Show live activity to create FOMO (Fear of Missing Out)
-window.addEventListener('lce:actions.product_add_to_cart', function(event) {
-  const data = event.detail.data;
-  
-  // Show notification to other visitors
-  showNotification(`Someone just bought product ${data.identifier}! Only 3 left!`);
-  
-  // Update inventory count on the page
-  updateInventoryDisplay(data.identifier, -1);
-});
-
-window.addEventListener('lce:actions.cart_opened', function(event) {
-  // Show how many people are currently viewing this product
-  showViewerCount("👀 5 people are looking at this right now");
-});
-```
-
-## Common Use Cases & How to Implement
-
-### 🛒 **Cart Abandonment Recovery**
-**The Problem**: 70% of carts are abandoned
-**The Solution**: Automatic follow-up based on events
-
-```javascript
-// Set up cart abandonment tracking
-let abandonmentTimer;
-
-window.addEventListener('lce:actions.cart_opened', function() {
-  // Reset timer each time they open cart
-  clearTimeout(abandonmentTimer);
-  
-  abandonmentTimer = setTimeout(function() {
-    // After 30 minutes of inactivity, trigger recovery
-    triggerCartRecovery();
-  }, 30 * 60 * 1000);
-});
-
-window.addEventListener('lce:actions.checkout_submit_completed', function() {
-  // They completed purchase - cancel recovery
-  clearTimeout(abandonmentTimer);
-});
-
-function triggerCartRecovery() {
-  // Send email, show popup, etc.
-  console.log("Time to recover this cart!");
-}
-```
-
-### 📈 **Revenue Optimization**
-**The Goal**: Increase average order value
-**The Method**: Smart upselling based on behavior
-
-```javascript
-window.addEventListener('lce:actions.product_add_to_cart', function(event) {
-  const data = event.detail.data;
-  
-  // Offer upsells based on product identifier
-  const upsellMap = {
-    'phone-001': 'phone-cases',
-    'laptop-001': 'laptop-accessories'
-  };
-  
-  if (upsellMap[data.identifier]) {
-    showUpsell(upsellMap[data.identifier]);
-  }
-  
-  // Check if cart is close to free shipping threshold
-  const cart = actions.cart.getDetails();
-  if (cart.amounts.total > 45 && cart.amounts.total < 50) {
-    showMessage("Add $" + (50 - cart.amounts.total) + " more for FREE shipping!");
-  }
-});
-```
-
-### 🎯 **Conversion Tracking**
-**The Need**: Measure what's working
-**The Implementation**: Track the entire funnel
-
-```javascript
-// Track the complete conversion funnel
-const funnelSteps = {
-  productView: 0,
-  addToCart: 0,
-  cartView: 0,
-  checkoutStart: 0,
-  purchase: 0
-};
-
-window.addEventListener('lce:actions.product_loaded', () => funnelSteps.productView++);
-window.addEventListener('lce:actions.product_add_to_cart', () => funnelSteps.addToCart++);
-window.addEventListener('lce:actions.cart_opened', () => funnelSteps.cartView++);
-window.addEventListener('lce:actions.checkout_opened', () => funnelSteps.checkoutStart++);
-window.addEventListener('lce:actions.checkout_submit_completed', () => funnelSteps.purchase++);
-
-// Send to your analytics every 10 minutes
-setInterval(() => {
-  console.log('Conversion Funnel:', funnelSteps);
-  // Send to your dashboard/analytics
-}, 10 * 60 * 1000);
-```
-
-## Getting Started in 5 Minutes
-
-1. **Pick one goal** from the examples above
-2. **Copy the code** into your website
-3. **Replace the console.log** with your actual actions (send email, show popup, etc.)
-4. **Test it** by going through the flow yourself
-5. **Monitor the results** and adjust as needed
-
-**Need help?** The events automatically work once LiquidCommerce Elements are on your page. Just add the JavaScript code and you're ready to go!