@liquidcommerce/elements-sdk 2.2.0-beta.4 → 2.2.0-beta.40

package/docs/ACTIONS.md

@@ -0,0 +1,1300 @@
+# 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 { applied, discountAmount, newTotal } = event.detail.data;
+  showSuccessMessage(`🎉 Promo applied! You saved $${discountAmount}!`);
+  updateCartDisplay(newTotal);
+});
+
+window.addEventListener('lce:actions.cart_promo_code_failed', function(event) {
+  const { attempted, 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'     // { applied: true, discountAmount?: number, newTotal?: number }
+'lce:actions.cart_promo_code_removed'     // { applied: false }
+'lce:actions.cart_promo_code_failed'      // { attempted: true, error: string }
+```
+
+### **Checkout Action Events**
+```javascript
+// Product management  
+'lce:actions.checkout_product_add_success'  // { itemsAdded: number, identifiers: string[] }
+'lce:actions.checkout_product_add_failed'   // { identifiers: string[], error: string }
+
+// Promo code management
+'lce:actions.checkout_promo_code_applied'   // { applied: true, discountAmount?: number, newTotal?: number }
+'lce:actions.checkout_promo_code_removed'   // { applied: false }
+'lce:actions.checkout_promo_code_failed'    // { attempted: true, error: string }
+
+// Gift card management
+'lce:actions.checkout_gift_card_applied'    // { applied: true, newTotal?: number }
+'lce:actions.checkout_gift_card_removed'    // { applied: false }
+'lce:actions.checkout_gift_card_failed'     // { attempted: true, 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 { applied, discountAmount, newTotal } = event.detail.data;
+  showSuccessMessage(`Discount applied! Saved: $${discountAmount}`);
+  updatePriceDisplay(newTotal);
+  trackPromoSuccess(discountAmount);
+};
+
+const handlePromoFailure = (event) => {
+  const { attempted, 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 { applied, discountAmount, newTotal } = event.detail.data;
+  showMessage(`Welcome discount applied! You saved $${discountAmount}!`);
+  updateCartDisplay(newTotal);
+  
+  // Track successful promo usage
+  analytics.track('Promo Applied', { discount: discountAmount });
+});
+
+// Listen for failure and try fallback
+window.addEventListener('lce:actions.cart_promo_code_failed', function(event) {
+  const { attempted, 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 { applied } = 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();
+
+// 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 { applied, discountAmount, newTotal } = event.detail.data;
+  showCheckoutSuccess(`Discount applied! You saved $${discountAmount}`);
+  updateCheckoutTotal(newTotal);
+  
+  // Track successful conversion optimization
+  analytics.track('Checkout Discount Applied', { discount: discountAmount });
+});
+
+window.addEventListener('lce:actions.checkout_promo_code_failed', function(event) {
+  const { attempted, 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 { applied, newTotal } = event.detail.data;
+  showCheckoutSuccess('Gift card applied to your order!');
+  updateCheckoutTotal(newTotal);
+});
+
+window.addEventListener('lce:actions.checkout_gift_card_failed', function(event) {
+  const { attempted, 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!