@liquidcommerce/elements-sdk 2.4.0 → 2.4.2

package/docs/ACTIONS.md

@@ -65,16 +65,19 @@ Events **never expose sensitive information** like promo codes, gift card codes,
 // Check product info before making decisions
 const product = actions.product.getDetails('product-123');
 
-if (product.price > 100) {
-  // Show premium support option
+// 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.isAvailable) {
-  // Enable add to cart
+if (product.sizes && Object.keys(product.sizes).length > 0) {
   enableAddToCart();
 } else {
-  // Show waitlist signup
   showWaitlistSignup();
 }
 ```
@@ -382,13 +385,11 @@ window.addEventListener('lce:actions.cart_product_add_failed', function(event) {
 // See what's in the cart to make smart decisions
 const cart = actions.cart.getDetails();
 
-if (cart.total > 100) {
-  // Offer free shipping
+if (cart.amounts.total > 100) {
   showFreeShippingBanner();
 }
 
-if (cart.items.length === 0) {
-  // Cart is empty - show recommendations
+if (cart.itemCount === 0) {
   showPopularProducts();
 }
 ```
@@ -499,7 +500,7 @@ actions.checkout.toggleCheckout();
 
 // Example: Open checkout automatically for high-value carts
 const cart = actions.cart.getDetails();
-if (cart.total > 500) {
+if (cart.amounts.total > 500) {
   actions.checkout.openCheckout(); // VIP checkout experience
 }
 ```
@@ -529,7 +530,43 @@ window.addEventListener('lce:actions.checkout_product_add_failed', function(even
 });
 ```
 
-**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.
+#### 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
@@ -625,14 +662,6 @@ if (customer.billingAddress === customer.shippingAddress) {
 // Get safe, non-sensitive checkout information
 const checkout = actions.checkout.getDetails();
 
-// Check checkout status and totals
-console.log('Checkout total:', checkout.amounts.total);
-console.log('Items in checkout:', checkout.itemCount);
-console.log('Is gift order:', checkout.isGift);
-console.log('Has age verification:', checkout.hasAgeVerify);
-console.log('Has promo code applied:', checkout.hasPromoCode);
-console.log('Has gift cards applied:', checkout.hasGiftCards);
-
 // Make business decisions based on checkout state
 if (checkout.amounts.total > 1000) {
   // High-value order - offer white glove service
@@ -700,24 +729,28 @@ async function handleVIPCustomer(customer) {
 
 ### 🛍️ Scenario 2: Smart Bundle Sales
 ```javascript
-// Automatically add complementary products
+// Automatically add complementary products based on specific product identifiers
 window.addEventListener('lce:actions.product_add_to_cart', async function(event) {
-  const product = event.detail.data;
+  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']
+  };
   
-  // If they bought a laptop, add accessories
-  if (product.category === 'laptops') {
-    const cart = actions.cart.getDetails();
-    const hasAccessories = cart.items.some(item => item.category === 'accessories');
+  // 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 
+      }))
+    );
     
-    if (!hasAccessories) {
-      // Add recommended accessories bundle
-      await actions.cart.addProduct([
-        { identifier: 'laptop-case-123', fulfillmentType: 'shipping', quantity: 1 },
-        { identifier: 'wireless-mouse-456', fulfillmentType: 'shipping', quantity: 1 }
-      ]);
-      
-      showMessage("We've added recommended accessories to your cart!");
-    }
+    showMessage("We've added recommended accessories to your cart!");
   }
 });
 ```
@@ -767,7 +800,7 @@ async function optimizeCheckout() {
   ];
   
   for (const strategy of discountStrategies) {
-    if (strategy.minTotal && cart.total >= strategy.minTotal) {
+    if (strategy.minTotal && cart.amounts.total >= strategy.minTotal) {
       try {
         await actions.checkout.applyPromoCode(strategy.code);
         break; // Success, stop trying
@@ -1023,15 +1056,20 @@ window.addEventListener('lce:actions.product_add_to_cart', async function(event)
   const product = event.detail.data;
   
   // Your business logic here
-  if (product.price > 100) {
+  if (product.priceInfo && product.priceInfo.avg > 100) {
     // High-value product - offer premium support
     showPremiumSupportOffer();
   }
   
-  // Maybe add complementary products
-  if (product.category === 'phones') {
+  // 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: 'phone-case-recommended',
+      identifier: crossSellMap[product.identifier],
       fulfillmentType: 'shipping',
       quantity: 1
     }]);
@@ -1054,7 +1092,7 @@ window.addEventListener('lce:actions.cart_opened', function() {
   const cart = actions.cart.getDetails();
   
   // If cart value is close to free shipping threshold
-  if (cart.total > 45 && cart.total < 50) {
+  if (cart.amounts.total > 45 && cart.amounts.total < 50) {
     showFreeShippingUpsell();
   }
 });
@@ -1136,16 +1174,16 @@ if (timeOnPage > 60 && pageViewCount > 3) {
 
 ### 🛍️ **Pattern 2: Cross-Sell Automation**
 ```javascript
-// Automatic product recommendations
+// Automatic product recommendations based on identifier
 const crossSellRules = {
-  'laptop': ['laptop-case', 'wireless-mouse', 'usb-hub'],
-  'phone': ['phone-case', 'screen-protector', 'wireless-charger'],
-  'camera': ['memory-card', 'camera-bag', 'tripod']
+  '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 product = event.detail.data;
-  const recommendations = crossSellRules[product.category];
+  const data = event.detail.data;
+  const recommendations = crossSellRules[data.identifier];
   
   if (recommendations) {
     // Add first recommendation automatically
@@ -1155,7 +1193,7 @@ window.addEventListener('lce:actions.product_add_to_cart', async function(event)
       quantity: 1
     }]);
     
-    showMessage(`We've added ${recommendations[0]} - customers who bought ${product.name} love this combo!`);
+    showMessage(`We've added ${recommendations[0]} - customers love this combo!`);
   }
 });
 ```
@@ -1174,7 +1212,7 @@ async function optimizePricing() {
   }
   
   // Volume discounts
-  else if (cart.total > 200) {
+  else if (cart.amounts.total > 200) {
     await actions.cart.applyPromoCode('BULK20');
   }
   

package/docs/CONFIGURATION.md

@@ -308,34 +308,158 @@ data-env="production"
 data-debug-mode="console"
 ```
 
-#### `data-cart-id`
+#### `data-cart-button`
 
 **Type:** `string`
 
-Container ID for cart button.
+Container ID, CSS selector, or position-prefixed selector for simple cart button (no badge).
 
 ```html
-data-cart-id="header-cart"
+<!-- Simple ID -->
+data-cart-button="header-cart"
+
+<!-- CSS Selector (from browser inspect tool) -->
+data-cart-button=".header .nav-links"
+data-cart-button="#main-navigation"
+
+<!-- Position-prefixed selectors -->
+data-cart-button="above:.header .logo"      <!-- Place above the target -->
+data-cart-button="below:#main-navigation"  <!-- Place below the target -->
+data-cart-button="replace:.old-cart"       <!-- Replace the target -->
+data-cart-button="inside:.header .nav"     <!-- Place inside the target (default) -->
 ```
 
-#### `data-show-cart-items`
+#### `data-cart-badge-button`
 
-**Type:** flag (no value)
+**Type:** `string`
 
-Show item count on cart button.
+Container ID, CSS selector, or position-prefixed selector for cart button with item count badge.
 
 ```html
-data-show-cart-items
+<!-- Simple ID -->
+data-cart-badge-button="header-cart"
+
+<!-- CSS Selector (from browser inspect tool) -->
+data-cart-badge-button=".header .nav-links"
+data-cart-badge-button="#main-navigation"
+
+<!-- Position-prefixed selectors -->
+data-cart-badge-button="above:.header .logo"      <!-- Place above the target -->
+data-cart-badge-button="below:#main-navigation"  <!-- Place below the target -->
+data-cart-badge-button="replace:.old-cart"       <!-- Replace the target -->
+data-cart-badge-button="inside:.header .nav"     <!-- Place inside the target (default) -->
 ```
 
-#### `data-hide-cart-floating-button`
+**Position Prefixes:**
+- `above:` - Place above the target element
+- `below:` - Place below the target element  
+- `replace:` - Replace the target element
+- `inside:` - Place inside the target element (default)
+
+#### `data-cart-button-hidden`
 
 **Type:** flag (no value)
 
-Hide the default floating cart button.
+Hide cart button completely.
 
 ```html
-data-hide-cart-floating-button
+data-cart-button-hidden
+```
+
+### Cart Button Examples
+
+**Simple cart button (no badge):**
+```html
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-button="header-cart"
+  src="elements.js">
+</script>
+```
+
+**Cart button with item count badge:**
+```html
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-badge-button="header-cart"
+  src="elements.js">
+</script>
+```
+
+**Using position-prefixed selectors:**
+```html
+<!-- Place inside the target element (default) -->
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-badge-button="inside:.header .nav-links"
+  src="elements.js">
+</script>
+
+<!-- Place above the target element -->
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-button="above:.header .logo"
+  src="elements.js">
+</script>
+
+<!-- Place below the target element -->
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-badge-button="below:#main-navigation"
+  src="elements.js">
+</script>
+
+<!-- Replace the target element -->
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-button="replace:.old-cart-button"
+  src="elements.js">
+</script>
+```
+
+**No cart button:**
+```html
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-button-hidden
+  src="elements.js">
+</script>
+```
+
+**Default behavior (floating cart button with badge):**
+```html
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  src="elements.js">
+</script>
+```
+
+### Getting CSS Selectors from Browser
+
+**Super Easy Method:**
+1. **Right-click** on any element where you want the cart button
+2. Select **"Inspect"** or **"Inspect Element"**
+3. In developer tools, **right-click** on the highlighted element
+4. Select **"Copy" → "Copy selector"**
+5. Paste the selector into your `data-cart-button` or `data-cart-badge-button` attribute
+
+**Example:**
+```html
+<!-- After copying selector from browser inspect tool -->
+<script 
+  data-liquid-commerce-elements
+  data-token="your-api-key"
+  data-cart-badge-button="body > div.container > header > nav > div.nav-links"
+  src="elements.js">
+</script>
 ```
 
 ### Product Configuration