@liquidcommerce/elements-sdk 2.7.1 → 2.7.2

package/docs/v1/guides/events.md

@@ -1,162 +1,895 @@
 # Events Guide
 
-The SDK publishes events for all user interactions and state changes.
+The SDK publishes browser events for user interactions and state changes. Use them to react to product selections, cart updates, and checkout progress.
 
 ## Event Format
 
-All SDK events follow this pattern:
+All SDK events are dispatched as native `CustomEvent` objects. The payload lives in `event.detail`:
 
 ```javascript
-window.addEventListener('lce:actions.event_name', (event) => {
+window.addEventListener('lce:actions.client_ready', (event) => {
+  const { data, metadata } = event.detail;
+
   const {
-    namespace,  // 'lce:actions'
-    event: eventName,  // 'cart_item_added'
-    timestamp,  // Unix timestamp
-    id,  // Unique event ID
-    data  // Event-specific data
-  } = event.detail;
+    event: eventName,
+    namespace,
+    originalEvent,
+    actionNamespace,
+    eventId,
+    timestamp
+  } = metadata;
 });
 ```
 
+`data` is event-specific. `metadata` describes the event (name, namespace, timestamp, etc).
+
 ## Event Namespaces
 
 - `lce:actions.*` - User actions and state changes
-- `lce:forms.*` - Form interactions (checkout)
+- `lce:forms.*` - Form field interactions (checkout)
+- `lce:actions` - All action events (namespace-level listener)
+- `lce:forms` - All form events (namespace-level listener)
+
+Example: listen to every action event:
+
+```javascript
+window.addEventListener('lce:actions', (event) => {
+  const { metadata } = event.detail;
+  console.log('Action event:', metadata.event);
+});
+```
 
 ## Core Events
 
-### Client Ready
+### `lce:actions.client_ready`
+
+Fires once when the SDK finishes initializing and is ready for actions.
+
+**Data includes:** `isReady`, `message`, `timestamp`, `version`.
+
+**Example**
 
 ```javascript
 window.addEventListener('lce:actions.client_ready', (event) => {
-  const { isReady, version, timestamp } = event.detail.data;
-  console.log(`Elements SDK v${version} is ready`);
+  const { data } = event.detail;
+  if (data.isReady) {
+    console.log('Elements SDK ready', data.version);
+  }
 });
 ```
 
 ## Product Events
 
+### `lce:actions.product_loaded`
+
+Fires when a product component finishes loading and product data is available.
+
+**Data includes:** `identifier`, `name`, `price`, `selectedSizeId`, `selectedFulfillmentType`.
+
+**Example**
+
 ```javascript
-// Product loaded
 window.addEventListener('lce:actions.product_loaded', (event) => {
-  const { identifier, name, price } = event.detail.data;
+  const { data } = event.detail;
+  console.log(`Loaded ${data.name} (${data.identifier})`);
 });
+```
+
+### `lce:actions.product_add_to_cart`
+
+Fires when the user triggers add-to-cart from a product component. Use cart events to confirm success or failure.
+
+**Data includes:** `identifier`, `quantity`, `fulfillmentId`, `partNumber`, `engravingLines`.
+
+**Example**
 
-// Add to cart clicked
+```javascript
 window.addEventListener('lce:actions.product_add_to_cart', (event) => {
-  const { identifier, quantity, fulfillmentType } = event.detail.data;
+  const { data } = event.detail;
+  gtag('event', 'add_to_cart_click', { item_id: data.identifier, quantity: data.quantity });
 });
+```
+
+### `lce:actions.product_size_changed`
+
+Fires when the user changes the selected size.
+
+**Data includes:** `identifier`, `selectedSizeId`, `selectedSize`, `previousSizeId`, `previousSize`.
+
+**Example**
 
-// Size changed
+```javascript
 window.addEventListener('lce:actions.product_size_changed', (event) => {
-  const { identifier, selectedSize } = event.detail.data;
+  const { data } = event.detail;
+  console.log(`Size changed to ${data.selectedSize}`);
 });
+```
+
+### `lce:actions.product_fulfillment_type_changed`
+
+Fires when the user switches between fulfillment types (for example shipping vs onDemand).
 
-// Fulfillment type changed
+**Data includes:** `identifier`, `selectedFulfillmentType`, `previousFulfillmentType`, `selectedFulfillmentId`, `previousFulfillmentId`.
+
+**Example**
+
+```javascript
 window.addEventListener('lce:actions.product_fulfillment_type_changed', (event) => {
-  const { identifier, fulfillmentType } = event.detail.data;
+  const { data } = event.detail;
+  console.log('Fulfillment type:', data.selectedFulfillmentType);
 });
+```
+
+### `lce:actions.product_fulfillment_changed`
+
+Fires when the user selects a different fulfillment option or retailer.
 
-// Retailer changed
+**Data includes:** `identifier`, `selectedFulfillmentId`, `previousFulfillmentId`, `selectedFulfillmentType`, `previousFulfillmentType`.
+
+**Example**
+
+```javascript
 window.addEventListener('lce:actions.product_fulfillment_changed', (event) => {
-  const { identifier, selectedRetailer } = event.detail.data;
+  const { data } = event.detail;
+  console.log('Fulfillment changed:', data.selectedFulfillmentId);
 });
+```
+
+### `lce:actions.product_quantity_increase`
+
+Fires when the product quantity is increased.
+
+**Data includes:** `identifier`, `quantity`, `previousQuantity`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.product_quantity_increase', (event) => {
+  const { data } = event.detail;
+  console.log('Quantity increased to', data.quantity);
+});
+```
+
+### `lce:actions.product_quantity_decrease`
+
+Fires when the product quantity is decreased.
+
+**Data includes:** `identifier`, `quantity`, `previousQuantity`.
 
-// Quantity changed
-window.addEventListener('lce:actions.product_quantity_increase', (event) => {});
-window.addEventListener('lce:actions.product_quantity_decrease', (event) => {});
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.product_quantity_decrease', (event) => {
+  const { data } = event.detail;
+  console.log('Quantity decreased to', data.quantity);
+});
 ```
 
 ## Address Events
 
+### `lce:actions.address_updated`
+
+Fires when an address is successfully set.
+
+**Data includes:** `googlePlacesId`, `formattedAddress`, `address`, `coordinates`.
+
+**Example**
+
 ```javascript
-// Address set
 window.addEventListener('lce:actions.address_updated', (event) => {
-  const { address, coordinates, formattedAddress } = event.detail.data;
+  const { data } = event.detail;
+  console.log('Address set:', data.formattedAddress);
+});
+```
+
+### `lce:actions.address_cleared`
+
+Fires when the current address is cleared.
+
+**Data includes:** `true`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.address_cleared', () => {
+  console.log('Address cleared');
 });
+```
+
+### `lce:actions.address_failed`
 
-// Address cleared
-window.addEventListener('lce:actions.address_cleared', (event) => {});
+Fires when setting the address fails.
 
-// Address error
+**Data includes:** `googlePlacesId`, `formattedAddress`, `address`, `coordinates`, `error`.
+
+**Example**
+
+```javascript
 window.addEventListener('lce:actions.address_failed', (event) => {
-  const { error } = event.detail.data;
+  const { data } = event.detail;
+  console.error('Address error:', data.error);
 });
 ```
 
 ## Cart Events
 
+### `lce:actions.cart_loaded`
+
+Fires when the cart is fully loaded or synced.
+
+**Data includes:** `cartId`, `itemCount`, `subtotal`, `items`, `promoCodeDiscount`.
+
+**Example**
+
 ```javascript
-// Cart loaded
 window.addEventListener('lce:actions.cart_loaded', (event) => {
-  const { cartId, itemsCount } = event.detail.data;
+  const { data } = event.detail;
+  console.log(`Cart ${data.cartId} has ${data.itemCount} items`);
 });
+```
+
+### `lce:actions.cart_opened`
 
-// Cart opened/closed
-window.addEventListener('lce:actions.cart_opened', (event) => {});
-window.addEventListener('lce:actions.cart_closed', (event) => {});
+Fires when the cart drawer opens.
 
-// Cart updated
+**Data includes:** `true`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.cart_opened', () => {
+  document.body.classList.add('cart-open');
+});
+```
+
+### `lce:actions.cart_closed`
+
+Fires when the cart drawer closes.
+
+**Data includes:** `true`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.cart_closed', () => {
+  document.body.classList.remove('cart-open');
+});
+```
+
+### `lce:actions.cart_updated`
+
+Fires when cart contents or totals change.
+
+**Data includes:** `previous`, `current`.
+
+**Example**
+
+```javascript
 window.addEventListener('lce:actions.cart_updated', (event) => {
-  const { cartId, itemsCount, subtotal } = event.detail.data;
+  const { data } = event.detail;
+  const delta = data.current.itemCount - data.previous.itemCount;
+  if (delta !== 0) {
+    console.log('Item count changed by', delta);
+  }
+});
+```
+
+### `lce:actions.cart_reset`
+
+Fires when the cart is cleared.
+
+**Data includes:** `true`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.cart_reset', () => {
+  console.log('Cart reset');
+});
+```
+
+### `lce:actions.cart_failed`
+
+Fires when a cart operation fails.
+
+**Data includes:** `cartId`, `message`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.cart_failed', (event) => {
+  const { data } = event.detail;
+  console.error('Cart error:', data.message);
+});
+```
+
+### `lce:actions.cart_item_added`
+
+Fires when an item is added to the cart.
+
+**Data includes:** `cartId`, `itemId`, `quantity`, `fulfillmentId`, `partNumber`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.cart_item_added', (event) => {
+  const { data } = event.detail;
+  console.log(`Added item ${data.itemId} (qty ${data.quantity})`);
+});
+```
+
+### `lce:actions.cart_item_removed`
+
+Fires when an item is removed from the cart.
+
+**Data includes:** `cartId`, `itemId`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.cart_item_removed', (event) => {
+  const { data } = event.detail;
+  console.log('Removed item', data.itemId);
 });
+```
+
+### `lce:actions.cart_item_quantity_increase`
+
+Fires when a cart item quantity increases.
+
+**Data includes:** `cartId`, `itemId`, `quantity`, `previousQuantity`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.cart_item_quantity_increase', (event) => {
+  const { data } = event.detail;
+  console.log('Quantity increased to', data.quantity);
+});
+```
+
+### `lce:actions.cart_item_quantity_decrease`
+
+Fires when a cart item quantity decreases.
+
+**Data includes:** `cartId`, `itemId`, `quantity`, `previousQuantity`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.cart_item_quantity_decrease', (event) => {
+  const { data } = event.detail;
+  console.log('Quantity decreased to', data.quantity);
+});
+```
+
+### `lce:actions.cart_item_engraving_updated`
+
+Fires when engraving text is updated for a cart item.
+
+**Data includes:** `cartId`, `itemId`, `engravingLines`, `previousEngravingLines`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.cart_item_engraving_updated', (event) => {
+  const { data } = event.detail;
+  console.log('Updated engraving for', data.itemId);
+});
+```
 
-// Item added/removed
-window.addEventListener('lce:actions.cart_item_added', (event) => {});
-window.addEventListener('lce:actions.cart_item_removed', (event) => {});
+### `lce:actions.cart_promo_code_applied`
 
-// Quantity changed
-window.addEventListener('lce:actions.cart_item_quantity_increase', (event) => {});
-window.addEventListener('lce:actions.cart_item_quantity_decrease', (event) => {});
+Fires when a promo code is applied to the cart.
 
-// Promo code events
+**Data includes:** `cartId`, `discount`, `newSubtotal`.
+
+**Example**
+
+```javascript
 window.addEventListener('lce:actions.cart_promo_code_applied', (event) => {
-  const { discount, newSubtotal } = event.detail.data;
+  const { data } = event.detail;
+  console.log('Promo applied, discount:', data.discount);
+});
+```
+
+### `lce:actions.cart_promo_code_removed`
+
+Fires when a promo code is removed from the cart.
+
+**Data includes:** `cartId`, `discount`, `newSubtotal`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.cart_promo_code_removed', (event) => {
+  const { data } = event.detail;
+  console.log('Promo removed');
+});
+```
+
+### `lce:actions.cart_promo_code_failed`
+
+Fires when a promo code fails to apply.
+
+**Data includes:** `cartId`, `error`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.cart_promo_code_failed', (event) => {
+  const { data } = event.detail;
+  console.error('Promo code failed:', data.error);
 });
-window.addEventListener('lce:actions.cart_promo_code_removed', (event) => {});
-window.addEventListener('lce:actions.cart_promo_code_failed', (event) => {});
+```
 
-// Product add success/failure
+### `lce:actions.cart_product_add_success`
+
+Fires when adding products via the actions API succeeds.
+
+**Data includes:** `cartId`, `itemsAdded`, `identifiers`.
+
+**Example**
+
+```javascript
 window.addEventListener('lce:actions.cart_product_add_success', (event) => {
-  const { itemsAdded, identifiers } = event.detail.data;
+  const { data } = event.detail;
+  console.log(`Added ${data.itemsAdded} products`);
 });
+```
+
+### `lce:actions.cart_product_add_failed`
+
+Fires when adding products via the actions API fails.
+
+**Data includes:** `cartId`, `identifiers`, `error`.
+
+**Example**
+
+```javascript
 window.addEventListener('lce:actions.cart_product_add_failed', (event) => {
-  const { error } = event.detail.data;
+  const { data } = event.detail;
+  console.error('Product add failed:', data.error);
 });
 ```
 
 ## Checkout Events
 
+### `lce:actions.checkout_loaded`
+
+Fires when checkout data loads.
+
+**Data includes:** `cartId`, `amounts`, `itemCount`, `isGift`, `billingSameAsShipping`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_loaded', (event) => {
+  const { data } = event.detail;
+  console.log('Checkout loaded for cart', data.cartId);
+});
+```
+
+### `lce:actions.checkout_opened`
+
+Fires when the checkout drawer opens.
+
+**Data includes:** `true`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_opened', () => {
+  console.log('Checkout opened');
+});
+```
+
+### `lce:actions.checkout_closed`
+
+Fires when the checkout drawer closes.
+
+**Data includes:** `true`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_closed', () => {
+  console.log('Checkout closed');
+});
+```
+
+### `lce:actions.checkout_failed`
+
+Fires when checkout fails to load or operate.
+
+**Data includes:** `message`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_failed', (event) => {
+  const { data } = event.detail;
+  console.error('Checkout error:', data.message);
+});
+```
+
+### `lce:actions.checkout_customer_information_updated`
+
+Fires when customer info (email, phone, name) is updated.
+
+**Data includes:** `cartId`.
+
+**Example**
+
 ```javascript
-// Lifecycle
-window.addEventListener('lce:actions.checkout_loaded', (event) => {});
-window.addEventListener('lce:actions.checkout_opened', (event) => {});
-window.addEventListener('lce:actions.checkout_closed', (event) => {});
+window.addEventListener('lce:actions.checkout_customer_information_updated', (event) => {
+  const { data } = event.detail;
+  console.log('Customer info updated for cart', data.cartId);
+});
+```
+
+### `lce:actions.checkout_billing_information_updated`
 
-// Form updates
-window.addEventListener('lce:actions.checkout_customer_information_updated', (event) => {});
-window.addEventListener('lce:actions.checkout_billing_information_updated', (event) => {});
-window.addEventListener('lce:actions.checkout_gift_information_updated', (event) => {});
+Fires when billing info is updated.
+
+**Data includes:** `cartId`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_billing_information_updated', (event) => {
+  const { data } = event.detail;
+  console.log('Billing info updated for cart', data.cartId);
+});
+```
 
-// Toggles
+### `lce:actions.checkout_gift_information_updated`
+
+Fires when gift recipient info is updated.
+
+**Data includes:** `cartId`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_gift_information_updated', (event) => {
+  const { data } = event.detail;
+  console.log('Gift info updated for cart', data.cartId);
+});
+```
+
+### `lce:actions.checkout_is_gift_toggled`
+
+Fires when gift mode is toggled.
+
+**Data includes:** `cartId`, `isActive`, `previousIsActive`.
+
+**Example**
+
+```javascript
 window.addEventListener('lce:actions.checkout_is_gift_toggled', (event) => {
-  const { isGift } = event.detail.data;
+  const { data } = event.detail;
+  console.log('Gift mode:', data.isActive);
+});
+```
+
+### `lce:actions.checkout_billing_same_as_shipping_toggled`
+
+Fires when the billing same-as-shipping option is toggled.
+
+**Data includes:** `cartId`, `isActive`, `previousIsActive`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_billing_same_as_shipping_toggled', (event) => {
+  const { data } = event.detail;
+  console.log('Billing same as shipping:', data.isActive);
+});
+```
+
+### `lce:actions.checkout_marketing_preferences_toggled`
+
+Fires when a marketing preference is toggled.
+
+**Data includes:** `cartId`, `fieldName`, `isActive`, `previousIsActive`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_marketing_preferences_toggled', (event) => {
+  const { data } = event.detail;
+  console.log(`Marketing ${data.fieldName}:`, data.isActive);
+});
+```
+
+### `lce:actions.checkout_item_removed`
+
+Fires when an item is removed during checkout.
+
+**Data includes:** `cartId`, `cartItemId`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_item_removed', (event) => {
+  const { data } = event.detail;
+  console.log('Checkout item removed', data.cartItemId);
+});
+```
+
+### `lce:actions.checkout_item_quantity_increase`
+
+Fires when a checkout item quantity increases.
+
+**Data includes:** `cartId`, `cartItemId`, `quantity`, `previousQuantity`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_item_quantity_increase', (event) => {
+  const { data } = event.detail;
+  console.log('Checkout quantity increased to', data.quantity);
+});
+```
+
+### `lce:actions.checkout_item_quantity_decrease`
+
+Fires when a checkout item quantity decreases.
+
+**Data includes:** `cartId`, `cartItemId`, `quantity`, `previousQuantity`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_item_quantity_decrease', (event) => {
+  const { data } = event.detail;
+  console.log('Checkout quantity decreased to', data.quantity);
+});
+```
+
+### `lce:actions.checkout_item_engraving_updated`
+
+Fires when engraving text is updated for a checkout item.
+
+**Data includes:** `cartId`, `cartItemId`, `engravingLines`, `previousEngravingLines`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_item_engraving_updated', (event) => {
+  const { data } = event.detail;
+  console.log('Checkout engraving updated for', data.cartItemId);
+});
+```
+
+### `lce:actions.checkout_tip_updated`
+
+Fires when delivery tips are updated.
+
+**Data includes:** `cartId`, `deliveryTips`, `previousDeliveryTips`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_tip_updated', (event) => {
+  const { data } = event.detail;
+  console.log('Tips updated for cart', data.cartId);
+});
+```
+
+### `lce:actions.checkout_submit_started`
+
+Fires when checkout submission starts.
+
+**Data includes:** `started`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_submit_started', (event) => {
+  const { data } = event.detail;
+  if (data.started) {
+    console.log('Checkout submission started');
+  }
 });
-window.addEventListener('lce:actions.checkout_billing_same_as_shipping_toggled', (event) => {});
-window.addEventListener('lce:actions.checkout_marketing_preferences_toggled', (event) => {});
+```
+
+### `lce:actions.checkout_submit_completed`
+
+Fires when checkout submission completes successfully.
 
-// Submission
-window.addEventListener('lce:actions.checkout_submit_started', (event) => {});
+**Data includes:** `orderNumber`, `orderTotal`.
+
+**Example**
+
+```javascript
 window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
-  const { orderId, total } = event.detail.data;
+  const { data } = event.detail;
+  console.log('Order completed:', data.orderNumber);
 });
+```
+
+### `lce:actions.checkout_submit_failed`
+
+Fires when checkout submission fails.
+
+**Data includes:** `message`.
+
+**Example**
+
+```javascript
 window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
-  const { error } = event.detail.data;
+  const { data } = event.detail;
+  console.error('Checkout submit failed:', data.message);
+});
+```
+
+### `lce:actions.checkout_promo_code_applied`
+
+Fires when a promo code is applied during checkout.
+
+**Data includes:** `cartId`, `discount`, `newTotal`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_promo_code_applied', (event) => {
+  const { data } = event.detail;
+  console.log('Checkout promo applied:', data.discount);
+});
+```
+
+### `lce:actions.checkout_promo_code_removed`
+
+Fires when a promo code is removed during checkout.
+
+**Data includes:** `cartId`, `discount`, `newTotal`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_promo_code_removed', (event) => {
+  const { data } = event.detail;
+  console.log('Checkout promo removed');
+});
+```
+
+### `lce:actions.checkout_promo_code_failed`
+
+Fires when a promo code fails during checkout.
+
+**Data includes:** `cartId`, `error`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_promo_code_failed', (event) => {
+  const { data } = event.detail;
+  console.error('Checkout promo failed:', data.error);
+});
+```
+
+### `lce:actions.checkout_gift_card_applied`
+
+Fires when a gift card is applied during checkout.
+
+**Data includes:** `cartId`, `newTotal`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_gift_card_applied', (event) => {
+  const { data } = event.detail;
+  console.log('Gift card applied, new total:', data.newTotal);
+});
+```
+
+### `lce:actions.checkout_gift_card_removed`
+
+Fires when a gift card is removed during checkout.
+
+**Data includes:** `cartId`, `newTotal`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_gift_card_removed', (event) => {
+  const { data } = event.detail;
+  console.log('Gift card removed');
+});
+```
+
+### `lce:actions.checkout_gift_card_failed`
+
+Fires when a gift card fails during checkout.
+
+**Data includes:** `cartId`, `error`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_gift_card_failed', (event) => {
+  const { data } = event.detail;
+  console.error('Gift card failed:', data.error);
+});
+```
+
+### `lce:actions.checkout_product_add_success`
+
+Fires when products are added to checkout via the actions API.
+
+**Data includes:** `cartId`, `itemsAdded`, `identifiers`, `isPresale`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_product_add_success', (event) => {
+  const { data } = event.detail;
+  console.log(`Checkout added ${data.itemsAdded} products`);
 });
+```
 
-// Promo codes & gift cards
-window.addEventListener('lce:actions.checkout_promo_code_applied', (event) => {});
-window.addEventListener('lce:actions.checkout_gift_card_applied', (event) => {});
+### `lce:actions.checkout_product_add_failed`
+
+Fires when adding products to checkout via the actions API fails.
+
+**Data includes:** `cartId`, `identifiers`, `error`, `isPresale`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_product_add_failed', (event) => {
+  const { data } = event.detail;
+  console.error('Checkout product add failed:', data.error);
+});
+```
+
+## Form Events
+
+### `lce:forms.customer`
+
+Fires when a customer form field changes in checkout.
+
+**Data includes:** `fieldName`, `fieldValue`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:forms.customer', (event) => {
+  const { data } = event.detail;
+  console.log('Customer field changed:', data.fieldName);
+});
+```
+
+### `lce:forms.billing`
+
+Fires when a billing form field changes in checkout.
+
+**Data includes:** `fieldName`, `fieldValue`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:forms.billing', (event) => {
+  const { data } = event.detail;
+  console.log('Billing field changed:', data.fieldName);
+});
+```
+
+### `lce:forms.gift`
+
+Fires when a gift form field changes in checkout.
+
+**Data includes:** `fieldName`, `fieldValue`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:forms.gift', (event) => {
+  const { data } = event.detail;
+  console.log('Gift field changed:', data.fieldName);
+});
 ```
 
 ## Use Cases
@@ -164,22 +897,24 @@ window.addEventListener('lce:actions.checkout_gift_card_applied', (event) => {})
 ### Analytics Integration
 
 ```javascript
-// Track page views
+// Track product views
 window.addEventListener('lce:actions.product_loaded', (event) => {
+  const { data } = event.detail;
   gtag('event', 'view_item', {
     items: [{
-      item_id: event.detail.data.identifier,
-      item_name: event.detail.data.name,
-      price: event.detail.data.price / 100
+      item_id: data.identifier,
+      item_name: data.name,
+      price: data.price / 100
     }]
   });
 });
 
 // Track purchases
 window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  const { data } = event.detail;
   gtag('event', 'purchase', {
-    transaction_id: event.detail.data.orderId,
-    value: event.detail.data.total / 100,
+    transaction_id: data.orderNumber,
+    value: data.orderTotal / 100,
     currency: 'USD'
   });
 });