@liquidcommerce/elements-sdk 2.4.0 → 2.4.2

package/docs/EVENTS.md

@@ -21,15 +21,16 @@ When customers interact with your LiquidCommerce elements, events automatically
 // Example: When someone adds to cart, send them a discount code
 window.addEventListener('lce:actions.product_add_to_cart', function(event) {
   // Customer just added a product to cart!
-  const product = event.detail.data;
+  const data = event.detail.data;
   
   // Maybe send them a discount popup
-  showDiscountPopup(product.productName);
+  showDiscountPopup(data.identifier);
   
   // Or track in your analytics
   analytics.track('Product Added', {
-    product: product.productName,
-    price: product.price
+    identifier: data.identifier,
+    quantity: data.quantity,
+    upc: data.upc
   });
 });
 ```
@@ -45,13 +46,13 @@ What do you want to achieve? Pick one:
 window.addEventListener('lce:actions.product_loaded', function(event) {
   // Product was viewed - track in your analytics
   const product = event.detail.data;
-  console.log('Customer viewed:', product.productName);
+  console.log('Customer viewed:', product.name);
 });
 
 window.addEventListener('lce:actions.product_add_to_cart', function(event) {
   // Product was added to cart - this is a conversion!
-  const product = event.detail.data;
-  console.log('SALE OPPORTUNITY:', product.productName, '$' + product.price);
+  const data = event.detail.data;
+  console.log('SALE OPPORTUNITY:', data.identifier, 'qty:', data.quantity);
 });
 ```
 
@@ -75,12 +76,10 @@ window.addEventListener('lce:actions.checkout_submit_completed', function(event)
 ```javascript
 // Offer upsells when they add expensive items
 window.addEventListener('lce:actions.product_add_to_cart', function(event) {
-  const product = event.detail.data;
+  const data = event.detail.data;
   
-  if (product.price > 100) {
-    // Show them complementary products
-    showUpsellPopup(product.productId);
-  }
+  // Trigger upsell based on product identifier
+  showUpsellPopup(data.identifier);
 });
 ```
 
@@ -121,6 +120,63 @@ window.addEventListener('lce:actions.client_ready', function(event) {
 
 **Note on Personalization:** Product personalization (engraving) is added during the add-to-cart action. The personalization is included in the `product_add_to_cart` event data. Once in cart, use `cart_item_engraving_updated` to track changes.
 
+#### Product Details Event Data
+When `lce:actions.product_loaded` fires, you get comprehensive product information:
+
+```javascript
+window.addEventListener('lce:actions.product_loaded', function(event) {
+  const product = event.detail.data;
+  
+  // Basic Information
+  console.log(product.id);              // Product ID
+  console.log(product.name);            // Product name
+  console.log(product.brand);           // Brand name
+  console.log(product.category);        // Category
+  console.log(product.catPath);         // Category path
+  console.log(product.classification);  // Product classification
+  console.log(product.type);            // Product type
+  console.log(product.subType);         // Product sub-type
+  console.log(product.salsifyGrouping); // Salsify grouping ID
+  
+  // Visual Assets
+  console.log(product.mainImage);       // Main product image URL
+  console.log(product.images);          // Array of all product images
+  
+  // Product Attributes
+  console.log(product.region);          // Region (e.g., "Napa Valley")
+  console.log(product.country);         // Country of origin
+  console.log(product.material);        // Material type
+  console.log(product.abv);             // Alcohol by volume
+  console.log(product.proof);           // Proof
+  console.log(product.age);             // Age statement
+  console.log(product.color);           // Color description
+  console.log(product.flavor);          // Flavor profile
+  console.log(product.variety);         // Variety (e.g., "Cabernet Sauvignon")
+  console.log(product.appellation);     // Appellation
+  console.log(product.vintage);         // Vintage year
+  
+  // Descriptions
+  console.log(product.description);     // Plain text description
+  console.log(product.htmlDescription); // HTML formatted description
+  console.log(product.tastingNotes);    // Tasting notes
+  
+  // Pricing
+  console.log(product.priceInfo);       // { min, max, avg } pricing across fulfillments
+  
+  // Available Sizes & Fulfillments
+  console.log(product.sizes);           // All available sizes with fulfillment options
+  console.log(product.selectedSizeId);  // Currently selected size
+  console.log(product.selectedFulfillmentId);   // Currently selected fulfillment
+  console.log(product.selectedFulfillmentType); // 'shipping' or 'onDemand'
+});
+```
+
+**Use Cases:**
+- **Rich Analytics**: Track which product attributes drive conversions
+- **Personalized Recommendations**: Suggest similar products based on variety, region, or flavor
+- **Content Display**: Show detailed product information on your custom UI
+- **Search & Filtering**: Build custom search based on product attributes
+
 ### 🛒 Cart Events (Track Purchase Intent)
 ```javascript
 // Cart lifecycle
@@ -155,6 +211,75 @@ window.addEventListener('lce:actions.cart_item_engraving_updated', function(even
 });
 ```
 
+#### Cart Details Event Data
+When `lce:actions.cart_loaded` or `lce:actions.cart_updated` fires, you get complete cart information:
+
+```javascript
+window.addEventListener('lce:actions.cart_loaded', function(event) {
+  const cart = event.detail.data;
+  
+  // Cart Identification
+  console.log(cart.id);                 // Cart ID
+  console.log(cart.promoCode);          // Applied promo code (if any)
+  
+  // Cart Items
+  console.log(cart.items);              // Object with all cart items
+  console.log(cart.itemCount);          // Total number of items in cart
+  
+  // Each item contains:
+  Object.values(cart.items).forEach(item => {
+    console.log(item.id);               // Cart item ID
+    console.log(item.name);             // Product name
+    console.log(item.brand);            // Brand
+    console.log(item.salsifyGrouping);  // Salsify grouping ID
+    console.log(item.catPath);          // Category path
+    console.log(item.size);             // Size description
+    console.log(item.volume);           // Volume
+    console.log(item.uom);              // Unit of measure
+    console.log(item.pack);             // Is pack (boolean)
+    console.log(item.packDesc);         // Pack description
+    console.log(item.container);        // Container type
+    console.log(item.containerType);    // Container type classification
+    console.log(item.price);            // Total price (unitPrice × quantity)
+    console.log(item.unitPrice);        // Price per unit
+    console.log(item.quantity);         // Quantity
+    console.log(item.maxQuantity);      // Maximum allowed quantity
+    console.log(item.mainImage);        // Product image URL
+    console.log(item.upc);              // UPC code
+    console.log(item.sku);              // SKU
+    console.log(item.partNumber);       // Part number
+    console.log(item.retailerId);       // Retailer ID
+    console.log(item.fulfillmentId);    // Fulfillment ID
+    console.log(item.attributes);       // Item attributes (engraving, etc.)
+  });
+  
+  // Location Information
+  console.log(cart.location.placesId);           // Google Places ID
+  console.log(cart.location.address);            // Address object
+  console.log(cart.location.coordinates);        // Lat/long coordinates
+  
+  // Financial Breakdown
+  console.log(cart.amounts.subtotal);            // Subtotal
+  console.log(cart.amounts.deliveryFee);         // Delivery fee
+  console.log(cart.amounts.shippingFee);         // Shipping fee
+  console.log(cart.amounts.platformFee);         // Platform fee
+  console.log(cart.amounts.engravingFee);        // Engraving/personalization fee
+  console.log(cart.amounts.discounts);           // Total discounts
+  console.log(cart.amounts.giftCardTotal);       // Gift card total applied
+  console.log(cart.amounts.total);               // Final total
+  
+  // Timestamps
+  console.log(cart.createdAt);          // When cart was created
+  console.log(cart.updatedAt);          // Last update timestamp
+});
+```
+
+**Use Cases:**
+- **Abandoned Cart Recovery**: Track cart value and items for targeted recovery campaigns
+- **Revenue Analytics**: Monitor average cart value, most popular items, cart composition
+- **Inventory Management**: Track which products are frequently added/removed
+- **Pricing Analysis**: Analyze impact of fees, discounts, and gift cards on cart totals
+
 ### 💳 Checkout Events (Track Purchase Process)
 ```javascript
 // Checkout lifecycle
@@ -191,6 +316,105 @@ window.addEventListener('lce:actions.cart_item_engraving_updated', function(even
 **Important Note on Checkout Personalization:**  
 Personalization cannot be edited during checkout - only removed. This is by design to prevent order processing complications. If a customer wants to modify personalization, they must return to the cart. The checkout only displays personalization details and provides a remove option.
 
+#### Checkout Details Event Data
+When you call `actions.checkout.getDetails()`, you get comprehensive checkout information:
+
+**Note:** The `lce:actions.checkout_loaded` event only contains `{ cartId: string }`. To get full checkout details, use `actions.checkout.getDetails()`.
+
+```javascript
+// Get full checkout details via action
+const checkout = actions.checkout.getDetails();
+  
+  // Checkout Identification
+  console.log(checkout.cartId);                    // Associated cart ID
+  
+  // Checkout Status Flags
+  console.log(checkout.acceptedAccountCreation);   // Customer accepted account creation
+  console.log(checkout.hasAgeVerify);              // Age verification required
+  console.log(checkout.hasSubstitutionPolicy);     // Substitution policy accepted
+  console.log(checkout.isGift);                    // Order is a gift
+  console.log(checkout.billingSameAsShipping);     // Billing address same as shipping
+  console.log(checkout.hasPromoCode);              // Promo code applied
+  console.log(checkout.hasGiftCards);              // Gift cards applied
+  
+  // Marketing Preferences
+  console.log(checkout.marketingPreferences.canEmail); // Email opt-in status
+  console.log(checkout.marketingPreferences.canSms);   // SMS opt-in status
+  
+  // Order Summary
+  console.log(checkout.itemCount);                 // Total items in checkout
+  
+  // Financial Breakdown
+  console.log(checkout.amounts.subtotal);          // Subtotal
+  console.log(checkout.amounts.deliveryFee);       // Delivery fee
+  console.log(checkout.amounts.shippingFee);       // Shipping fee
+  console.log(checkout.amounts.platformFee);       // Platform fee
+  console.log(checkout.amounts.engravingFee);      // Engraving/personalization fee
+  console.log(checkout.amounts.discounts);         // Total discounts
+  console.log(checkout.amounts.giftCardTotal);     // Gift card total applied
+  console.log(checkout.amounts.tax);               // Tax amount
+  console.log(checkout.amounts.bottleDeposits);    // Bottle deposit fees
+  console.log(checkout.amounts.total);             // Final total
+  
+  // Checkout Items (detailed product information)
+  console.log(checkout.items);                     // Object with all checkout items
+  
+// Each checkout item contains comprehensive details:
+Object.values(checkout.items).forEach(item => {
+  console.log(item.cartItemId);        // Cart item ID
+  console.log(item.liquidId);          // Liquid ID
+  console.log(item.variantId);         // Variant ID
+  console.log(item.name);              // Product name
+  console.log(item.brand);             // Brand
+  console.log(item.salsifyGrouping);   // Salsify grouping ID
+  console.log(item.catPath);           // Category path
+  
+  // Size & Container Information
+  console.log(item.size);              // Size description
+  console.log(item.volume);            // Volume
+  console.log(item.uom);               // Unit of measure
+  console.log(item.pack);              // Is pack (boolean)
+  console.log(item.packDesc);          // Pack description
+  console.log(item.container);         // Container type
+  console.log(item.containerType);     // Container type classification
+  
+  // Product Attributes
+  console.log(item.proof);             // Proof
+  console.log(item.abv);               // Alcohol by volume
+  
+  // Pricing
+  console.log(item.price);             // Total price (unitPrice × quantity)
+  console.log(item.unitPrice);         // Price per unit
+  console.log(item.unitTax);           // Tax per unit
+  console.log(item.bottleDeposits);    // Bottle deposit fees
+  console.log(item.quantity);          // Quantity
+  
+  // Identifiers
+  console.log(item.upc);               // UPC code
+  console.log(item.sku);               // SKU
+  console.log(item.partNumber);        // Part number
+  
+  // Fulfillment Information
+  console.log(item.retailerId);        // Retailer ID
+  console.log(item.retailerName);      // Retailer name
+  console.log(item.fulfillmentId);     // Fulfillment ID
+  console.log(item.expectationDetail); // Delivery expectation details
+  
+  // Visual Assets
+  console.log(item.mainImage);         // Product image URL
+  
+  // Item Attributes (engraving, etc.)
+  console.log(item.attributes);        // Item attributes object
+});
+```
+
+**Use Cases:**
+- **Order Analytics**: Track checkout completion rates, average order values, popular items
+- **Marketing Optimization**: Analyze opt-in rates, gift order patterns, promo code effectiveness
+- **Revenue Tracking**: Monitor tax collection, fees, discounts, and gift card usage
+- **Customer Insights**: Understand purchasing patterns, preferred retailers, delivery preferences
+- **Compliance**: Track age verification requirements, substitution policy acceptance
+
 ### 📍 Address Events (Track Shipping Preferences)
 ```javascript
 'lce:actions.address_updated' // → "Customer entered shipping address"
@@ -333,9 +557,9 @@ applyPromoCodeWithFeedback('SAVE20');
 ```javascript
 // Automatically offer discounts for high-value carts
 window.addEventListener('lce:actions.cart_updated', function(event) {
-  const cart = event.detail.data;
+  const cart = event.detail.data.current;
   
-  if (cart.total > 200 && !cart.hasPromoCode) {
+  if (cart.amounts.total > 200 && !cart.promoCode) {
     // Show them a 10% off popup
     showPopup("Get 10% off orders over $200! Use code: SAVE10");
   }
@@ -392,35 +616,38 @@ window.addEventListener('lce:actions.product_loaded', function(event) {
   const product = event.detail.data;
   
   // Initialize stats if first time seeing this product
-  if (!productStats[product.productId]) {
-    productStats[product.productId] = {
-      name: product.productName,
+  if (!productStats[product.id]) {
+    productStats[product.id] = {
+      name: product.name,
       views: 0,
       addedToCarts: 0,
       conversions: 0
     };
   }
   
-  productStats[product.productId].views++;
+  productStats[product.id].views++;
 });
 
 window.addEventListener('lce:actions.product_add_to_cart', function(event) {
-  const product = event.detail.data;
-  productStats[product.productId].addedToCarts++;
+  const data = event.detail.data;
+  // Note: product_add_to_cart only has identifier, not full product details
+  if (productStats[data.identifier]) {
+    productStats[data.identifier].addedToCarts++;
+  }
 });
 
 window.addEventListener('lce:actions.checkout_submit_completed', function(event) {
   const order = event.detail.data;
-  
-  // Mark all purchased products as conversions
-  order.items.forEach(function(item) {
-    if (productStats[item.productId]) {
-      productStats[item.productId].conversions++;
-    }
-  });
+  console.log('Order completed:', order.orderNumber, 'Total:', order.orderTotal);
   
   // Send stats to your analytics dashboard
   console.log('Product Performance:', productStats);
+  
+  // Track conversion in analytics
+  analytics.track('Purchase', {
+    orderNumber: order.orderNumber,
+    total: order.orderTotal
+  });
 });
 ```
 
@@ -428,13 +655,13 @@ window.addEventListener('lce:actions.checkout_submit_completed', function(event)
 ```javascript
 // Show live activity to create FOMO (Fear of Missing Out)
 window.addEventListener('lce:actions.product_add_to_cart', function(event) {
-  const product = event.detail.data;
+  const data = event.detail.data;
   
   // Show notification to other visitors
-  showNotification(`Someone just bought ${product.productName}! Only 3 left!`);
+  showNotification(`Someone just bought product ${data.identifier}! Only 3 left!`);
   
   // Update inventory count on the page
-  updateInventoryDisplay(product.productId, -1);
+  updateInventoryDisplay(data.identifier, -1);
 });
 
 window.addEventListener('lce:actions.cart_opened', function(event) {
@@ -480,16 +707,22 @@ function triggerCartRecovery() {
 
 ```javascript
 window.addEventListener('lce:actions.product_add_to_cart', function(event) {
-  const product = event.detail.data;
+  const data = event.detail.data;
+  
+  // Offer upsells based on product identifier
+  const upsellMap = {
+    'phone-001': 'phone-cases',
+    'laptop-001': 'laptop-accessories'
+  };
   
-  // If they added a phone, suggest a case
-  if (product.category === 'phones') {
-    showUpsell('phone-cases');
+  if (upsellMap[data.identifier]) {
+    showUpsell(upsellMap[data.identifier]);
   }
   
-  // If cart total is close to free shipping, tell them
-  if (cart.total > 45 && cart.total < 50) {
-    showMessage("Add $" + (50 - cart.total) + " more for FREE shipping!");
+  // Check if cart is close to free shipping threshold
+  const cart = actions.cart.getDetails();
+  if (cart.amounts.total > 45 && cart.amounts.total < 50) {
+    showMessage("Add $" + (50 - cart.amounts.total) + " more for FREE shipping!");
   }
 });
 ```

package/docs/TROUBLESHOOTING.md

@@ -102,9 +102,26 @@ console.log('Container:', container);  // Should not be null
 // 2. Wait for DOM
 window.addEventListener('DOMContentLoaded', async () => {
   const client = await Elements('YOUR_API_KEY', { env: 'production' });
-  await client.injectProductElement([
+  const components = await client.injectProductElement([
     { containerId: 'product-container', identifier: 'product-123' }
   ]);
+  
+  // Check if injection was successful
+  if (components.length > 0) {
+    console.log('Product component injected successfully');
+    // components[0].rerender() - Rerender if needed
+    // components[0].getElement() - Get container element
+    // components[0].getType() - Get component type
+  } else {
+    console.log('Product injection failed');
+  }
+  
+  // Debug: Check all injected components
+  const allComponents = client.getInjectedComponents();
+  console.log('All injected components:', allComponents);
+  allComponents.forEach((component, containerId) => {
+    console.log(`Container: ${containerId}, Type: ${component.getType()}`);
+  });
 });
 
 // 3. Monitor product loading
@@ -636,7 +653,7 @@ onMounted(async () => {
   });
   
   window.addEventListener('lce:actions.cart_updated', (event) => {
-    cartData.value = event.detail.data;  // Vue reactivity
+    cartData.value = event.detail.data.current;  // Vue reactivity
   });
 });
 </script>

package/package.json

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",
@@ -71,7 +71,7 @@
     "embeddable commerce"
   ],
   "devDependencies": {
-    "@biomejs/biome": "2.2.6",
+    "@biomejs/biome": "2.2.7",
     "@commitlint/cli": "^20.1.0",
     "@commitlint/config-conventional": "^20.0.0",
     "@rollup/plugin-alias": "^5.1.1",
@@ -84,17 +84,17 @@
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.0",
-    "@semantic-release/npm": "^13.0.0",
+    "@semantic-release/npm": "^13.1.1",
     "@semantic-release/release-notes-generator": "^14.1.0",
     "@types/core-js": "^2.5.8",
-    "@types/node": "^24.8.0",
+    "@types/node": "^24.9.1",
     "conventional-changelog-cli": "^5.0.0",
     "husky": "^9.1.7",
     "process": "^0.11.10",
-    "rollup": "^4.52.4",
+    "rollup": "^4.52.5",
     "rollup-obfuscator": "^4.1.1",
     "rollup-plugin-typescript2": "^0.36.0",
-    "semantic-release": "^24.2.9",
+    "semantic-release": "^25.0.1",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   },