@liquidcommerce/elements-sdk 2.7.0 → 2.7.2

package/docs/ACTIONS.md

@@ -1,1301 +0,0 @@
-# Elements SDK Actions - Partner Control 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 Actions and Why Use Them?
-
-Actions let you control the LiquidCommerce components programmatically - like having a remote control for your e-commerce experience. Instead of waiting for customers to click buttons, you can make things happen automatically based on your business logic.
-
-**Business Benefits:**
-- **Automate User Flow**: Guide customers through the purchase process
-- **Custom Experiences**: Build unique checkout flows that match your brand
-- **Reduce Cart Abandonment**: Pre-fill information and remove friction
-- **Increase Conversions**: Trigger actions at the perfect moment
-- **Integrate with Existing Systems**: Connect to your CRM, inventory, etc.
-
-## How It Works & Getting Feedback
-
-Actions are **fire-and-forget** methods that return `void` or `Promise<void>`. Instead of return values, **all feedback comes through events** - this is by design for security and flexibility.
-
-```javascript
-// Actions are available globally
-const actions = window.elements.actions;
-
-// 1. Fire the action (simple, clean)
-await actions.cart.applyPromoCode('SAVE20');
-
-// 2. Listen for success/failure feedback via events
-window.addEventListener('lce:actions.cart_promo_code_applied', function(event) {
-  const { discount, newTotal } = event.detail.data;
-  showSuccessMessage(`🎉 Promo applied! You saved $${discount}!`);
-  updateCartDisplay(newTotal);
-});
-
-window.addEventListener('lce:actions.cart_promo_code_failed', function(event) {
-  const { error } = event.detail.data;
-  showErrorMessage('Promo code could not be applied. Please try again.');
-});
-```
-
-### 🔒 **Security-First Design**
-
-Events **never expose sensitive information** like promo codes, gift card codes, or balance details that could be intercepted by malicious scripts. You get all the feedback you need without security risks.
-
-**✅ Safe Data in Events:**
-- Success/failure status  
-- Discount amounts (already visible in UI)
-- Total amounts (already visible in UI)
-- Item counts and identifiers
-- Generic error messages
-
-**🚫 Never Exposed:**
-- Promo codes or gift card codes
-- Gift card balances or details
-- Specific error messages that reveal codes
-- Any sensitive financial information
-
-## Your Action Toolkit
-
-### 🛍️ Product Control (`actions.product`)
-
-**What it does**: Get information about products to make smart business decisions
-
-#### Get Product Details
-```javascript
-// Check product info before making decisions
-const product = actions.product.getDetails('product-123');
-
-// Use product attributes for recommendations
-if (product.variety === 'Cabernet Sauvignon' && product.region === 'Napa Valley') {
-  showSimilarNapaWines();
-}
-
-// Pricing and availability
-if (product.priceInfo && product.priceInfo.avg > 100) {
-  showPremiumSupport();
-}
-
-if (product.sizes && Object.keys(product.sizes).length > 0) {
-  enableAddToCart();
-} else {
-  showWaitlistSignup();
-}
-```
-
-**Real Business Uses:**
-- **Dynamic Pricing**: Show different offers based on product price
-- **Inventory Management**: Hide out-of-stock items or show alternatives
-- **Personalization**: Recommend accessories based on main product
-- **A/B Testing**: Show different CTAs for different product categories
-
-### 📍 Address Control (`actions.address`)
-
-**What it does**: Manage shipping addresses to reduce checkout friction
-
-#### Set Address by Google Places ID
-```javascript
-// Set address using Google Places ID - fastest way to capture accurate addresses
-try {
-  await actions.address.setAddressByPlacesId('ChIJ0SRjyK5ZwokRp1TwT8dJSv8');
-  showMessage("Address set successfully!");
-} catch (error) {
-  showMessage("Address not found. Please try again.");
-}
-
-// Real-world example: Let customers pick from their recent locations
-const recentPlacesIds = getCustomerRecentPlaces();
-if (recentPlacesIds.length > 0) {
-  // Use their most recent address automatically
-  await actions.address.setAddressByPlacesId(recentPlacesIds[0]);
-}
-```
-
-**Find Google Places IDs**: Use the [Google Places ID Finder](https://developers.google.com/maps/documentation/places/web-service/place-id#find-id) to get Place IDs for any location.
-
-#### Set Address Manually
-```javascript
-// Set address manually without Google Places - perfect for custom address forms
-try {
-  await actions.address.setAddressManually(
-    {
-      one: '123 Main St',
-      two: 'Apt 4B',          // Optional apartment/suite
-      city: 'New York',
-      state: 'NY',
-      zip: '10001',
-      country: 'United States' // Optional, will be included in formatted address
-    },
-    {
-      lat: 40.7505045,        // Latitude coordinate
-      long: -73.9934387       // Longitude coordinate
-    }
-  );
-  showMessage("Manual address set successfully!");
-} catch (error) {
-  showMessage("Invalid address or coordinates. Please check and try again.");
-}
-
-// Real-world example: Custom address form integration
-function handleCustomAddressSubmit(formData) {
-  const addressData = {
-    one: formData.streetAddress,
-    two: formData.apartment || '',  // Optional
-    city: formData.city,
-    state: formData.state,
-    zip: formData.zipCode,
-    country: formData.country || 'United States'
-  };
-
-  const coordinates = {
-    lat: parseFloat(formData.latitude),
-    long: parseFloat(formData.longitude)
-  };
-
-  // Validate coordinates before setting
-  if (coordinates.lat >= -90 && coordinates.lat <= 90 && 
-      coordinates.long >= -180 && coordinates.long <= 180) {
-    await actions.address.setAddressManually(addressData, coordinates);
-  } else {
-    showMessage("Invalid coordinates provided");
-  }
-}
-
-// Integration with geocoding services
-async function setAddressWithGeocoding(streetAddress, city, state, zip) {
-  try {
-    // Use your preferred geocoding service to get coordinates
-    const coordinates = await geocodeAddress(`${streetAddress}, ${city}, ${state} ${zip}`);
-    
-    await actions.address.setAddressManually(
-      {
-        one: streetAddress,
-        two: '',
-        city: city,
-        state: state,
-        zip: zip,
-        country: 'United States'
-      },
-      coordinates
-    );
-    
-    showMessage("Address geocoded and set successfully!");
-  } catch (error) {
-    showMessage("Could not geocode address. Please verify the address.");
-  }
-}
-```
-
-**Key Features:**
-- **Automatic Formatting**: Generates Google Places API-formatted address strings automatically
-- **Empty Places ID**: Places ID is set to empty string (perfect for non-Google Places addresses) 
-- **Flexible Input**: Works with any address structure and coordinate source
-- **Validation**: Built-in validation for required fields and coordinate ranges
-- **Same Events**: Triggers the same success/failure events as Google Places addresses
-
-#### Check Address
-```javascript
-// See if customer has an address saved
-const address = actions.address.getDetails();
-
-if (address) {
-  // Address is saved - express checkout available!
-  showExpressCheckout();
-} else {
-  // No address - guide them through address entry
-  highlightAddressForm();
-}
-```
-
-#### Clear Address
-```javascript
-// Clear address (useful for guest checkout option)
-actions.address.clear();
-```
-
-**Complete Reset Behavior:**
-The `actions.address.clear()` action performs a comprehensive reset of the user's address and shopping session:
-
-**What gets cleared:**
-- ✅ **Address Data**: All saved address information (street, city, state, zip, coordinates, Places ID)
-- ✅ **Cart Contents**: Complete cart reset (removes all items, totals, promo codes, retailers)
-- ✅ **Local Storage**: Completely removes the localStorage entry and its value
-- ✅ **Database**: Deletes the persisted store from the server database
-- ✅ **Checkout State**: Resets any pending checkout information
-
-**Why the cart is reset:**
-When an address is cleared, the cart must be reset because:
-- Cart items have location-specific pricing and availability
-- Fulfillment options are tied to specific addresses  
-- Delivery fees and shipping costs depend on location
-- Without a valid address, cart operations would fail or show incorrect data
-
-**Events fired:**
-- `lce:actions.address_cleared` - Address successfully cleared
-- `lce:actions.cart_reset` - Cart successfully reset
-
-**Use cases:**
-- Guest checkout option (clear previous user's data)
-- Location change (start fresh with new address)
-- Privacy compliance (complete data removal)
-- Testing/development (reset to clean state)
-
-**Real Business Uses:**
-- **One-Click Address**: Let customers select from saved Google Places
-- **Custom Address Forms**: Build your own address input forms with full control
-- **Third-Party Integration**: Connect with non-Google geocoding services
-- **Legacy System Migration**: Import addresses from existing customer databases
-- **International Addresses**: Handle addresses that may not be in Google Places
-- **Location-Based Services**: Auto-detect customer location and set address
-- **Express Checkout**: Skip address forms for returning customers
-- **Shipping Calculator**: Calculate shipping costs before checkout
-- **Local Pickup**: Show pickup options based on their address
-- **Tax Calculation**: Display accurate taxes before purchase
-
-## 📡 **Complete Action Feedback Events Reference**
-
-All actions provide feedback through events. Here are all available success/failure events:
-
-### **Cart Action Events**
-```javascript
-// Product management
-'lce:actions.cart_product_add_success'    // { itemsAdded: number, identifiers: string[] }
-'lce:actions.cart_product_add_failed'     // { identifiers: string[], error: string }
-
-// Promo code management
-'lce:actions.cart_promo_code_applied'     // { discount?: number, newTotal?: number }
-'lce:actions.cart_promo_code_removed'     // { newTotal?: number }
-'lce:actions.cart_promo_code_failed'      // { error: string }
-```
-
-### **Checkout Action Events**
-```javascript
-// Product management
-'lce:actions.checkout_product_add_success'  // { itemsAdded: number, identifiers: string[], isPresale?: boolean }
-'lce:actions.checkout_product_add_failed'   // { identifiers: string[], error: string, isPresale?: boolean }
-
-// Promo code management
-'lce:actions.checkout_promo_code_applied'   // { discount?: number, newTotal?: number }
-'lce:actions.checkout_promo_code_removed'   // { newTotal?: number }
-'lce:actions.checkout_promo_code_failed'    // { error: string }
-
-// Gift card management
-'lce:actions.checkout_gift_card_applied'    // { newTotal?: number }
-'lce:actions.checkout_gift_card_removed'    // { newTotal?: number }
-'lce:actions.checkout_gift_card_failed'     // { error: string }
-```
-
-### **Address Action Events** 
-```javascript
-// Address management (already available)
-'lce:actions.address_updated'               // { googlePlacesId: string, formattedAddress: string, address: {...}, coordinates: {...} }
-'lce:actions.address_failed'                // { error: string, googlePlacesId?: string }
-'lce:actions.address_cleared'               // boolean
-```
-
-### **Event Handling Best Practices**
-
-#### **1. Set Up Listeners Before Actions**
-```javascript
-// ✅ Good: Set up listener first
-window.addEventListener('lce:actions.cart_promo_code_applied', handleSuccess);
-await actions.cart.applyPromoCode('SAVE20');
-
-// ❌ Bad: Listener after action (might miss event)
-await actions.cart.applyPromoCode('SAVE20');
-window.addEventListener('lce:actions.cart_promo_code_applied', handleSuccess);
-```
-
-#### **2. Handle Both Success and Failure**
-```javascript
-// ✅ Always handle both outcomes
-window.addEventListener('lce:actions.cart_promo_code_applied', handleSuccess);
-window.addEventListener('lce:actions.cart_promo_code_failed', handleFailure);
-await actions.cart.applyPromoCode('SAVE20');
-```
-
-#### **3. Use Event Data Effectively**
-```javascript
-// ✅ Use all available event data
-window.addEventListener('lce:actions.cart_product_add_success', function(event) {
-  const { itemsAdded, identifiers } = event.detail.data;
-  
-  // Show success message
-  showMessage(`Added ${itemsAdded} items to cart`);
-  
-  // Track analytics
-  analytics.track('Products Added', { items: identifiers, count: itemsAdded });
-  
-  // Update UI
-  updateCartCount();
-  showUpsellRecommendations(identifiers);
-});
-```
-
-#### **4. Create Reusable Event Handlers**
-```javascript
-// ✅ Create reusable handlers
-const handlePromoSuccess = (event) => {
-  const { discount, newTotal } = event.detail.data;
-  showSuccessMessage(`Discount applied! Saved: $${discount}`);
-  updatePriceDisplay(newTotal);
-  trackPromoSuccess(discount);
-};
-
-const handlePromoFailure = (event) => {
-  const { error } = event.detail.data;
-  showErrorMessage('Promo code could not be applied');
-  trackPromoFailure();
-};
-
-// Use for both cart and checkout
-window.addEventListener('lce:actions.cart_promo_code_applied', handlePromoSuccess);
-window.addEventListener('lce:actions.checkout_promo_code_applied', handlePromoSuccess);
-window.addEventListener('lce:actions.cart_promo_code_failed', handlePromoFailure);
-window.addEventListener('lce:actions.checkout_promo_code_failed', handlePromoFailure);
-```
-
-### 🛒 Cart Control (`actions.cart`)
-
-**What it does**: Control the shopping cart to optimize conversions
-
-#### Show/Hide Cart
-```javascript
-// Show cart at strategic moments
-actions.cart.openCart();    // Open cart
-actions.cart.closeCart();   // Close cart
-actions.cart.toggleCart();  // Toggle visibility
-
-// Example: Open cart automatically after second product add
-let addToCartCount = 0;
-window.addEventListener('lce:actions.product_add_to_cart', function() {
-  addToCartCount++;
-  if (addToCartCount === 2) {
-    actions.cart.openCart(); // "Look what you've got!"
-  }
-});
-```
-
-#### Programmatically Add Products to Cart
-```javascript
-// Add products directly to cart without product component
-await actions.cart.addProduct([
-  {
-    identifier: 'product-123',  // Product UPC, ID, or Salsify grouping
-    fulfillmentType: 'shipping', // or 'onDemand'
-    quantity: 2
-  },
-  {
-    identifier: 'product-456',
-    fulfillmentType: 'onDemand',
-    quantity: 1
-  }
-], true); // Optional: open cart after adding (default: false)
-
-// Listen for success/failure feedback
-window.addEventListener('lce:actions.cart_product_add_success', function(event) {
-  const { itemsAdded, identifiers } = event.detail.data;
-  console.log(`✅ Added ${itemsAdded} products:`, identifiers);
-  showSuccessMessage('Products added to cart!');
-});
-
-window.addEventListener('lce:actions.cart_product_add_failed', function(event) {
-  const { identifiers, error } = event.detail.data;
-  console.log(`❌ Failed to add products:`, identifiers, error);
-  showErrorMessage('Could not add products. Please try again.');
-});
-```
-
-**Real Business Use**: Perfect for "Buy Now" buttons, quick add flows, bundle purchases, or any scenario where you want to add products without displaying the full product component first.
-
-#### Check Cart Contents
-```javascript
-// See what's in the cart to make smart decisions
-const cart = actions.cart.getDetails();
-
-if (cart.amounts.total > 100) {
-  showFreeShippingBanner();
-}
-
-if (cart.itemCount === 0) {
-  showPopularProducts();
-}
-```
-
-#### Add Products to Cart with Event Feedback
-```javascript
-// Add products programmatically
-await actions.cart.addProduct([{
-  identifier: 'product-123',
-  fulfillmentType: 'shipping',
-  quantity: 1
-}]);
-
-// Listen for success
-window.addEventListener('lce:actions.cart_product_add_success', function(event) {
-  const { itemsAdded, identifiers } = event.detail.data;
-  showMessage(`✅ Added ${itemsAdded} items to cart!`);
-  
-  // Track conversion
-  analytics.track('Products Added to Cart', {
-    items: identifiers,
-    count: itemsAdded
-  });
-  
-  // Maybe show related products
-  showRelatedProducts(identifiers);
-});
-
-// Listen for failures
-window.addEventListener('lce:actions.cart_product_add_failed', function(event) {
-  const { identifiers, error } = event.detail.data;
-  showErrorMessage('Could not add some products. Please try again.');
-  
-  // Log for debugging
-  console.error('Failed to add products:', identifiers, error);
-  
-  // Show alternatives
-  showAlternativeProducts(identifiers);
-});
-
-// Add bundles or cross-sells
-await actions.cart.addProduct([
-  { identifier: 'phone-123', fulfillmentType: 'shipping', quantity: 1 },
-  { identifier: 'case-456', fulfillmentType: 'shipping', quantity: 1 },
-  { identifier: 'charger-789', fulfillmentType: 'shipping', quantity: 1 }
-]);
-```
-
-#### Apply Discounts with Event Feedback
-```javascript
-// Apply promo codes automatically
-await actions.cart.applyPromoCode('WELCOME10');
-
-// Listen for success
-window.addEventListener('lce:actions.cart_promo_code_applied', function(event) {
-  const { discount, newTotal } = event.detail.data;
-  showMessage(`Welcome discount applied! You saved $${discount}!`);
-  updateCartDisplay(newTotal);
-
-  // Track successful promo usage
-  analytics.track('Promo Applied', { discount: discount });
-});
-
-// Listen for failure and try fallback
-window.addEventListener('lce:actions.cart_promo_code_failed', function(event) {
-  const { error } = event.detail.data;
-  console.log('First promo failed, trying backup promo');
-
-  // Try another strategy
-  actions.cart.applyPromoCode('FIRSTTIME');
-});
-
-// Remove promo code with feedback
-await actions.cart.removePromoCode();
-
-// Listen for removal confirmation
-window.addEventListener('lce:actions.cart_promo_code_removed', function(event) {
-  const { newTotal } = event.detail.data;
-  showMessage("Previous promo removed. Applying better discount...");
-
-  // Apply better deal
-  actions.cart.applyPromoCode('BETTER20');
-});
-```
-
-#### Reset Cart
-```javascript
-// Clear cart for fresh start
-await actions.cart.resetCart();
-```
-
-**Real Business Uses:**
-- **Smart Cart Timing**: Open cart when customer is most likely to buy
-- **Bundle Sales**: Add complementary products automatically
-- **Discount Strategy**: Apply best available discount automatically
-- **Abandonment Prevention**: Show cart contents at right moment
-
-### 💳 Checkout Control (`actions.checkout`)
-
-**What it does**: Streamline the checkout process to maximize conversions
-
-#### Control Checkout Flow
-```javascript
-// Open checkout at the perfect moment
-actions.checkout.openCheckout();
-actions.checkout.closeCheckout();
-actions.checkout.toggleCheckout();
-actions.checkout.exitCheckout();
-
-// Example: Open checkout automatically for high-value carts
-const cart = actions.cart.getDetails();
-if (cart.amounts.total > 500) {
-  actions.checkout.openCheckout(); // VIP checkout experience
-}
-```
-
-#### Programmatically Add Products to Checkout
-```javascript
-// Add products directly to checkout (bypasses cart, goes straight to checkout)
-await actions.checkout.addProduct([
-  {
-    identifier: 'product-123',
-    fulfillmentType: 'shipping',
-    quantity: 1
-  }
-], true); // Optional: open checkout after adding (default: false)
-
-// Listen for success/failure feedback
-window.addEventListener('lce:actions.checkout_product_add_success', function(event) {
-  const { itemsAdded, identifiers } = event.detail.data;
-  console.log(`✅ Added ${itemsAdded} products to checkout:`, identifiers);
-  showSuccessMessage('Ready for checkout!');
-});
-
-window.addEventListener('lce:actions.checkout_product_add_failed', function(event) {
-  const { identifiers, error } = event.detail.data;
-  console.log(`❌ Failed to add products to checkout:`, identifiers, error);
-  showErrorMessage('Could not proceed to checkout. Please try again.');
-});
-```
-
-#### Add Presale Product to Checkout
-```javascript
-// Add a single presale product directly to checkout (bypasses cart, always opens checkout drawer)
-// The method automatically validates product availability and fulfillment options
-await actions.checkout.addPresaleProduct({
-  identifier: 'presale-product-123',
-  fulfillmentType: 'shipping',
-  quantity: 1
-});
-
-// Listen for success/failure feedback (same events as regular addProduct)
-window.addEventListener('lce:actions.checkout_product_add_success', function(event) {
-  const { itemsAdded, identifiers, isPresale } = event.detail.data;
-  if (isPresale) {
-    console.log(`✅ Added ${itemsAdded} presale product to checkout:`, identifiers);
-    showSuccessMessage('Presale item ready for checkout!');
-  }
-});
-
-window.addEventListener('lce:actions.checkout_product_add_failed', function(event) {
-  const { identifiers, error, isPresale } = event.detail.data;
-  if (isPresale) {
-    console.log(`❌ Failed to add presale product to checkout:`, identifiers, error);
-    showErrorMessage('Could not proceed with presale checkout. Please try again.');
-  }
-});
-```
-
-**Key Features:**
-- **Product Availability Validation**: Automatically fetches and validates product data
-- **Fulfillment Type Support**: Checks if the requested fulfillment type is available
-- **Presale Verification**: Ensures the product is actually a presale item
-- **Always Opens Checkout**: Automatically opens checkout drawer after adding presale product
-- **Address Requirement**: Opens address input if location is not available
-- **Error Handling**: Comprehensive error handling with detailed feedback
-
-**Real Business Use**: Perfect for "Buy Now" buttons, one-click purchasing, express checkout flows, or any scenario where you want to skip the cart and go straight to checkout. The `addPresaleProduct` method is specifically designed for presale items that need to bypass the regular cart flow and go directly to checkout.
-
-#### Pre-fill Customer Information
-```javascript
-// Speed up checkout by pre-filling known information
-actions.checkout.updateCustomerInfo({
-  firstName: 'John',
-  lastName: 'Doe',
-  email: 'john@example.com',
-  phone: '+1234567890'
-});
-
-// Pre-fill billing from your CRM
-const customerData = getCRMData(customerId);
-actions.checkout.updateBillingInfo({
-  firstName: customerData.firstName,
-  lastName: customerData.lastName,
-  street1: customerData.address,
-  city: customerData.city,
-  state: customerData.state,
-  zipCode: customerData.zip
-});
-```
-
-#### Smart Discount Application with Event Feedback
-```javascript
-// Apply the best available discount automatically
-const customer = getCurrentCustomer();
-
-// Set up event listeners first
-window.addEventListener('lce:actions.checkout_promo_code_applied', function(event) {
-  const { discount, newTotal } = event.detail.data;
-  showCheckoutSuccess(`Discount applied! You saved $${discount}`);
-  updateCheckoutTotal(newTotal);
-
-  // Track successful conversion optimization
-  analytics.track('Checkout Discount Applied', { discount: discount });
-});
-
-window.addEventListener('lce:actions.checkout_promo_code_failed', function(event) {
-  const { error } = event.detail.data;
-  console.log('Promo code failed:', error);
-
-  // Try fallback strategies or notify user
-  showCheckoutError('Discount could not be applied');
-});
-
-// Apply gift card event listeners
-window.addEventListener('lce:actions.checkout_gift_card_applied', function(event) {
-  const { newTotal } = event.detail.data;
-  showCheckoutSuccess('Gift card applied to your order!');
-  updateCheckoutTotal(newTotal);
-});
-
-window.addEventListener('lce:actions.checkout_gift_card_failed', function(event) {
-  const { error } = event.detail.data;
-  showCheckoutError('Gift card could not be applied. Please check and try again.');
-});
-
-// Now apply the discounts
-if (customer.isFirstTime) {
-  await actions.checkout.applyPromoCode('WELCOME20');
-} else if (customer.isVIP) {
-  await actions.checkout.applyPromoCode('VIP15');
-}
-
-// Apply gift cards automatically
-if (customer.hasGiftCard) {
-  await actions.checkout.applyGiftCard(customer.giftCardCode);
-}
-```
-
-#### Optimize Checkout Options
-```javascript
-// Smart defaults based on customer behavior
-if (customer.prefersGifts) {
-  await actions.checkout.toggleIsGift(true);
-}
-
-// Auto-enable marketing for engaged customers
-if (customer.engagementScore > 8) {
-  actions.checkout.toggleMarketingPreferences('canEmail', true);
-  actions.checkout.toggleMarketingPreferences('canSms', true);
-}
-
-// Smart billing address handling
-if (customer.billingAddress === customer.shippingAddress) {
-  await actions.checkout.toggleBillingSameAsShipping(true);
-}
-```
-
-#### Get Checkout Details
-```javascript
-// Get safe, non-sensitive checkout information
-const checkout = actions.checkout.getDetails();
-
-// Make business decisions based on checkout state
-if (checkout.amounts.total > 1000) {
-  // High-value order - offer white glove service
-  showWhiteGloveService();
-}
-
-if (checkout.itemCount > 5) {
-  // Large order - offer bulk discount
-  await actions.checkout.applyPromoCode('BULK15');
-}
-
-if (checkout.isGift && checkout.hasAgeVerify) {
-  // Gift order with age verification - show age verification requirements
-  showAgeVerificationNotice();
-}
-
-if (!checkout.hasPromoCode) {
-  // No promo code applied - suggest best available discount
-  suggestBestPromoCode(checkout.amounts.total);
-}
-
-if (checkout.hasGiftCards && checkout.amounts.total < 50) {
-  // Gift cards applied but low total - suggest adding more items
-  showUpsellSuggestions();
-}
-
-// Available checkout details (all non-sensitive):
-// - amounts: { total, subtotal, shipping, discounts, tax, etc. }
-// - items: { [itemId]: { name, price, quantity, brand, etc. } }
-// - isGift: boolean, hasAgeVerify: boolean
-// - hasPromoCode: boolean, hasGiftCards: boolean
-// - itemCount: number
-```
-
-**Real Business Uses:**
-- **Reduce Checkout Time**: Pre-fill known customer information
-- **Maximize Discounts**: Apply best available offer automatically
-- **VIP Experience**: Different checkout flow for high-value customers
-- **Gift Optimization**: Auto-enable gift options for gift buyers
-
-## Real-World Business Scenarios
-
-### 🎯 Scenario 1: VIP Customer Experience
-```javascript
-// Detect VIP customers and give them special treatment
-async function handleVIPCustomer(customer) {
-  if (customer.totalSpent > 5000) {
-    // Pre-fill everything for express checkout
-    actions.checkout.updateCustomerInfo(customer.profile);
-    actions.checkout.updateBillingInfo(customer.billingAddress);
-    
-    // Apply VIP discount automatically
-    await actions.checkout.applyPromoCode('VIP20');
-    
-    // Enable premium features
-    actions.checkout.toggleMarketingPreferences('canEmail', true);
-    
-    // Open checkout immediately - no cart friction
-    actions.checkout.openCheckout();
-    
-    showVIPMessage("Welcome back! Your VIP checkout is ready.");
-  }
-}
-```
-
-### 🛍️ Scenario 2: Smart Bundle Sales
-```javascript
-// Automatically add complementary products based on specific product identifiers
-window.addEventListener('lce:actions.product_add_to_cart', async function(event) {
-  const data = event.detail.data;
-  
-  // Define cross-sell rules by identifier
-  const crossSellMap = {
-    'laptop-001': ['laptop-case-123', 'wireless-mouse-456'],
-    'camera-001': ['camera-bag-789', 'sd-card-512gb']
-  };
-  
-  // Check if this product has recommended accessories
-  if (crossSellMap[data.identifier]) {
-    const accessories = crossSellMap[data.identifier];
-    await actions.cart.addProduct(
-      accessories.map(id => ({ 
-        identifier: id, 
-        fulfillmentType: 'shipping', 
-        quantity: 1 
-      }))
-    );
-    
-    showMessage("We've added recommended accessories to your cart!");
-  }
-});
-```
-
-### 📱 Scenario 3: Mobile-First Quick Checkout
-```javascript
-// Streamlined mobile experience
-function mobileQuickCheckout() {
-  if (isMobileDevice()) {
-    // Get customer data from their last purchase
-    const lastOrder = getLastOrder();
-    
-    if (lastOrder) {
-      // Pre-fill everything
-      actions.checkout.updateCustomerInfo(lastOrder.customer);
-      actions.checkout.updateBillingInfo(lastOrder.billing);
-      
-      // Skip cart, go straight to checkout
-      actions.checkout.openCheckout();
-      
-      showMessage("Express checkout ready! Same info as last time.");
-    }
-  }
-}
-
-// Trigger on Add to Cart for mobile users
-window.addEventListener('lce:actions.product_add_to_cart', function() {
-  if (isMobileDevice() && isReturningCustomer()) {
-    mobileQuickCheckout();
-  }
-});
-```
-
-### 💰 Scenario 4: Dynamic Pricing & Promotions
-```javascript
-// Apply the best available discount
-async function optimizeCheckout() {
-  const cart = actions.cart.getDetails();
-  const customer = getCurrentCustomer();
-  
-  // Try different discount strategies
-  const discountStrategies = [
-    { code: 'BULK25', minTotal: 200 },
-    { code: 'RETURNING15', condition: customer.orderCount > 1 },
-    { code: 'FIRSTTIME10', condition: customer.orderCount === 0 },
-    { code: 'SEASONAL20', condition: isHolidaySeason() }
-  ];
-  
-  for (const strategy of discountStrategies) {
-    if (strategy.minTotal && cart.amounts.total >= strategy.minTotal) {
-      try {
-        await actions.checkout.applyPromoCode(strategy.code);
-        break; // Success, stop trying
-      } catch (error) {
-        continue; // Try next strategy
-      }
-    } else if (strategy.condition) {
-      try {
-        await actions.checkout.applyPromoCode(strategy.code);
-        break;
-      } catch (error) {
-        continue;
-      }
-    }
-  }
-}
-```
-
-### 🎁 Scenario 5: Holiday Gift Flow
-```javascript
-// Optimize for gift purchases during holidays
-async function holidayGiftOptimization() {
-  if (isHolidaySeason()) {
-    // Auto-enable gift features
-    actions.checkout.toggleIsGift(true);
-    
-    // Pre-populate gift message templates
-    const giftMessages = [
-      "Happy Holidays!",
-      "Merry Christmas!",
-      "With love and best wishes"
-    ];
-    
-    showGiftMessageSuggestions(giftMessages);
-    
-    // Suggest gift wrapping
-    showGiftWrappingOption();
-    
-    // Apply holiday shipping discount
-    await actions.checkout.applyPromoCode('FREEHOLIDAYSHIP');
-  }
-}
-
-// Trigger during checkout
-window.addEventListener('lce:actions.checkout_opened', holidayGiftOptimization);
-```
-
-### 📍 Scenario 6: Smart Address Auto-Complete
-```javascript
-// Use Google Places to streamline address entry
-async function smartAddressFlow() {
-  const customer = getCurrentCustomer();
-  
-  // For returning customers, use their recent addresses
-  if (customer.recentPlacesIds && customer.recentPlacesIds.length > 0) {
-    try {
-      // Auto-set their most recent address
-      await actions.address.setAddressByPlacesId(customer.recentPlacesIds[0]);
-      
-      showMessage("We've set your address to your recent location. Change it if needed!");
-      
-      // Show other recent addresses as quick options
-      showRecentAddressOptions(customer.recentPlacesIds.slice(1, 4));
-      
-    } catch (error) {
-      // Fallback to manual entry
-      showAddressForm();
-    }
-  }
-  
-  // For location-aware features
-  if (customer.hasLocationPermission) {
-    const nearbyBusinesses = await getNearbyBusinessPlaces();
-    
-    // If they're near a business location, suggest it
-    if (nearbyBusinesses.length > 0) {
-      showMessage("We found you're near our store location. Use it for pickup?");
-      
-      document.getElementById('use-store-address').onclick = async () => {
-        await actions.address.setAddressByPlacesId(nearbyBusinesses[0].placeId);
-        showMessage("Store pickup address set!");
-      };
-    }
-  }
-}
-
-// Use when address is updated
-smartAddressFlow();
-
-// Quick address selection from saved places
-async function useQuickAddress(placeId, displayName) {
-  try {
-    await actions.address.setAddressByPlacesId(placeId);
-    showMessage(`Address set to ${displayName}`);
-    
-    // Automatically proceed to shipping options
-    showShippingOptionsForAddress();
-    
-  } catch (error) {
-    showMessage("That address is no longer available. Please select another.");
-  }
-}
-```
-
-### 🏢 Scenario 7: Custom Address Form Integration
-```javascript
-// Integrate with your own address forms and geocoding services
-async function customAddressFormFlow() {
-  const customer = getCurrentCustomer();
-  
-  // If customer has saved addresses in your database (not Google Places)
-  if (customer.savedAddresses && customer.savedAddresses.length > 0) {
-    showSavedAddressOptions(customer.savedAddresses);
-  }
-  
-  // Handle custom form submission
-  document.getElementById('custom-address-form').addEventListener('submit', async (event) => {
-    event.preventDefault();
-    
-    const formData = new FormData(event.target);
-    const addressData = {
-      one: formData.get('street'),
-      two: formData.get('apartment') || '',
-      city: formData.get('city'),
-      state: formData.get('state'),
-      zip: formData.get('zip'),
-      country: formData.get('country') || 'United States'
-    };
-    
-    try {
-      // Use your geocoding service to get coordinates
-      const coordinates = await yourGeocodingService.geocode(
-        `${addressData.one}, ${addressData.city}, ${addressData.state} ${addressData.zip}`
-      );
-      
-      // Set the address manually
-      await actions.address.setAddressManually(addressData, {
-        lat: coordinates.latitude,
-        long: coordinates.longitude
-      });
-      
-      showMessage("Your address has been set successfully!");
-      
-      // Save to your database for future use
-      saveCustomerAddress(customer.id, addressData, coordinates);
-      
-    } catch (geocodeError) {
-      showError("Could not find coordinates for this address. Please verify and try again.");
-    }
-  });
-  
-  // Handle saved address selection
-  async function useSavedAddress(savedAddress) {
-    try {
-      await actions.address.setAddressManually(
-        {
-          one: savedAddress.street,
-          two: savedAddress.apartment || '',
-          city: savedAddress.city,
-          state: savedAddress.state,
-          zip: savedAddress.zip,
-          country: savedAddress.country || 'United States'
-        },
-        {
-          lat: savedAddress.coordinates.lat,
-          long: savedAddress.coordinates.long
-        }
-      );
-      
-      showMessage(`Address set to your saved location: ${savedAddress.nickname}`);
-      
-    } catch (error) {
-      showError("There was an issue with your saved address. Please try entering it again.");
-    }
-  }
-}
-
-// Import addresses from legacy system
-async function importLegacyAddresses() {
-  const legacyAddresses = await getLegacyCustomerAddresses();
-  
-  for (const address of legacyAddresses) {
-    try {
-      // Convert legacy format to Elements format
-      const elementsAddress = {
-        one: address.address_line_1,
-        two: address.address_line_2 || '',
-        city: address.city_name,
-        state: address.state_code,
-        zip: address.postal_code,
-        country: address.country_name || 'United States'
-      };
-      
-      const coordinates = {
-        lat: address.latitude,
-        long: address.longitude
-      };
-      
-      // Set address in Elements system
-      await actions.address.setAddressManually(elementsAddress, coordinates);
-      
-      console.log(`Successfully imported address for customer ${address.customer_id}`);
-      
-    } catch (error) {
-      console.error(`Failed to import address for customer ${address.customer_id}:`, error);
-    }
-  }
-}
-
-// Handle international addresses that might not be in Google Places
-async function handleInternationalAddress(internationalAddressData) {
-  try {
-    // Use an international geocoding service
-    const coordinates = await internationalGeocodingService.geocode(
-      internationalAddressData.fullAddress, 
-      internationalAddressData.country
-    );
-    
-    await actions.address.setAddressManually(
-      {
-        one: internationalAddressData.addressLine1,
-        two: internationalAddressData.addressLine2 || '',
-        city: internationalAddressData.city,
-        state: internationalAddressData.region, // Province, state, etc.
-        zip: internationalAddressData.postalCode,
-        country: internationalAddressData.country
-      },
-      coordinates
-    );
-    
-    showMessage("International address set successfully!");
-    
-  } catch (error) {
-    showError("Could not process this international address. Please contact support.");
-  }
-}
-```
-
-## Implementation Strategy
-
-### 🚀 Quick Start (5-Minute Setup)
-
-**Step 1: Choose Your Goal**
-- Increase conversions? → Focus on cart and checkout actions
-- Reduce abandonment? → Use pre-filling and automation
-- Boost sales? → Implement bundle and upsell logic
-- Improve UX? → Create smart defaults and express flows
-
-**Step 2: Start Simple**
-```javascript
-// Copy this basic template and customize
-window.addEventListener('lce:actions.product_add_to_cart', async function(event) {
-  const product = event.detail.data;
-  
-  // Your business logic here
-  if (product.priceInfo && product.priceInfo.avg > 100) {
-    // High-value product - offer premium support
-    showPremiumSupportOffer();
-  }
-  
-  // Maybe add complementary products based on identifier
-  const crossSellMap = {
-    'phone-001': 'phone-case-recommended',
-    'laptop-001': 'laptop-case-recommended'
-  };
-  
-  if (crossSellMap[product.identifier]) {
-    await actions.cart.addProduct([{
-      identifier: crossSellMap[product.identifier],
-      fulfillmentType: 'shipping',
-      quantity: 1
-    }]);
-  }
-});
-```
-
-**Step 3: Test & Iterate**
-1. Add one action at a time
-2. Test with real user flows
-3. Monitor conversion impact
-4. Adjust based on results
-
-### 💡 Pro Implementation Tips
-
-#### Combine Actions with Events
-```javascript
-// Listen for events, respond with actions
-window.addEventListener('lce:actions.cart_opened', function() {
-  const cart = actions.cart.getDetails();
-  
-  // If cart value is close to free shipping threshold
-  if (cart.amounts.total > 45 && cart.amounts.total < 50) {
-    showFreeShippingUpsell();
-  }
-});
-
-// Pre-fill checkout for VIP customers
-window.addEventListener('lce:actions.checkout_opened', async function() {
-  const customer = getCurrentCustomer();
-  
-  if (customer.isVIP) {
-    actions.checkout.updateCustomerInfo(customer.profile);
-    await actions.checkout.applyPromoCode('VIP20');
-  }
-});
-```
-
-#### Chain Actions for Workflows
-```javascript
-// Create complete automated flows
-async function expressCheckoutFlow(productId, customerId) {
-  // 1. Add product to cart
-  await actions.cart.addProduct([{
-    identifier: productId,
-    fulfillmentType: 'shipping',
-    quantity: 1
-  }]);
-  
-  // 2. Pre-fill customer data
-  const customer = getCustomerData(customerId);
-  actions.checkout.updateCustomerInfo(customer);
-  
-  // 3. Apply best discount
-  await actions.checkout.applyPromoCode(getBestDiscountFor(customer));
-  
-  // 4. Open checkout
-  actions.checkout.openCheckout();
-  
-  showMessage("Express checkout ready! Review and complete your order.");
-}
-```
-
-#### Smart Error Handling
-```javascript
-// Graceful degradation
-async function smartAddToCart(productId) {
-  try {
-    await actions.cart.addProduct([{
-      identifier: productId,
-      fulfillmentType: 'shipping',
-      quantity: 1
-    }]);
-    
-    showSuccessMessage("Added to cart!");
-  } catch (error) {
-    // Fallback - maybe the product is out of stock
-    showMessage("This item isn't available, but here are similar options:");
-    showAlternativeProducts(productId);
-  }
-}
-```
-
-## Common Integration Patterns
-
-### 🎯 **Pattern 1: Behavioral Triggers**
-```javascript
-// Trigger actions based on customer behavior
-let pageViewCount = 0;
-let timeOnPage = 0;
-
-// Track engagement
-setInterval(() => timeOnPage++, 1000);
-
-// Act based on engagement
-if (timeOnPage > 60 && pageViewCount > 3) {
-  // Engaged user - show special offer
-  await actions.cart.applyPromoCode('ENGAGED15');
-  showSpecialOffer();
-}
-```
-
-### 🛍️ **Pattern 2: Cross-Sell Automation**
-```javascript
-// Automatic product recommendations based on identifier
-const crossSellRules = {
-  'laptop-001': ['laptop-case', 'wireless-mouse', 'usb-hub'],
-  'phone-001': ['phone-case', 'screen-protector', 'wireless-charger'],
-  'camera-001': ['memory-card', 'camera-bag', 'tripod']
-};
-
-window.addEventListener('lce:actions.product_add_to_cart', async function(event) {
-  const data = event.detail.data;
-  const recommendations = crossSellRules[data.identifier];
-  
-  if (recommendations) {
-    // Add first recommendation automatically
-    await actions.cart.addProduct([{
-      identifier: recommendations[0],
-      fulfillmentType: 'shipping',
-      quantity: 1
-    }]);
-    
-    showMessage(`We've added ${recommendations[0]} - customers love this combo!`);
-  }
-});
-```
-
-### 💰 **Pattern 3: Dynamic Pricing**
-```javascript
-// Apply best available discount automatically
-async function optimizePricing() {
-  const cart = actions.cart.getDetails();
-  const customer = getCurrentCustomer();
-  const now = new Date();
-  
-  // Time-based discounts
-  if (now.getHours() < 10) {
-    await actions.cart.applyPromoCode('EARLYBIRD10');
-  }
-  
-  // Volume discounts
-  else if (cart.amounts.total > 200) {
-    await actions.cart.applyPromoCode('BULK20');
-  }
-  
-  // Customer-specific discounts
-  else if (customer.orderCount === 0) {
-    await actions.cart.applyPromoCode('WELCOME15');
-  }
-  
-  // Seasonal discounts
-  else if (isBlackFriday()) {
-    await actions.cart.applyPromoCode('BLACKFRIDAY25');
-  }
-}
-```
-
-## Business ROI Tracking
-
-Track the impact of your action implementations:
-
-```javascript
-// Track business metrics
-const metrics = {
-  automatedDiscountsApplied: 0,
-  bundleSalesCreated: 0,
-  expressCheckoutsCompleted: 0,
-  cartAbandonmentsPrevented: 0
-};
-
-// Track when actions create business value
-window.addEventListener('lce:actions.cart_updated', function() {
-  if (wasDiscountAppliedAutomatically()) {
-    metrics.automatedDiscountsApplied++;
-  }
-});
-
-window.addEventListener('lce:actions.checkout_submit_completed', function() {
-  if (wasExpressCheckout()) {
-    metrics.expressCheckoutsCompleted++;
-  }
-});
-
-// Send metrics to your analytics
-setInterval(() => {
-  sendBusinessMetrics(metrics);
-}, 60000); // Every minute
-```
-
-## Getting Started Today
-
-1. **Pick ONE scenario** from the examples above that matches your biggest business need
-2. **Copy the code** and customize it for your products/customers
-3. **Test it** with a small group first
-4. **Measure the impact** on your conversion rates
-5. **Scale up** what works, iterate on what doesn't
-
-**Remember**: The power is in combining the right actions with the right business logic for YOUR specific use case. Start simple, then build more sophisticated flows as you see results!
-
-Need help implementing? The actions work automatically once LiquidCommerce Elements are installed - just add your business logic and watch conversions improve!