@liquidcommerce/elements-sdk 2.6.0-beta.11 → 2.6.0-beta.111

package/docs/v1/guides/events.md

@@ -0,0 +1,939 @@
+# Events Guide
+
+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 are dispatched as native `CustomEvent` objects. The payload lives in `event.detail`:
+
+```javascript
+window.addEventListener('lce:actions.client_ready', (event) => {
+  const { data, metadata } = event.detail;
+
+  const {
+    event: eventName,
+    namespace,
+    originalEvent,
+    actionNamespace,
+    eventId,
+    timestamp,
+    sdkVersion,
+    env,
+    tenantName,
+    tenantCode
+  } = metadata;
+}, { once: true });
+```
+
+`data` is event-specific. `metadata` carries the same ten fields on **every** event — including
+`sdkVersion`, `env`, `tenantName` and `tenantCode`, so partner/tenant identification is already
+present and does not need to be re-derived in your analytics layer.
+
+## Event Namespaces
+
+- `lce:actions.*` - User actions and state changes
+- `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
+
+### `lce:actions.client_ready`
+
+Fires when the SDK finishes initializing and is ready for actions.
+
+> **Always register this listener with `{ once: true }`.** The specific topic
+> `lce:actions.client_ready` is dispatched **twice** — once synchronously, and once again on a
+> microtask, so that listeners attached immediately after `await Elements(...)` resolves still catch
+> it. Without `{ once: true }`, a handler registered before initialization runs **twice**, which
+> double-injects components and double-counts analytics. (The namespace-level `lce:actions` listener
+> receives it only once.)
+
+**Data includes:** `isReady`, `message`, `timestamp`, `version`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.client_ready', (event) => {
+  const { data } = event.detail;
+  if (data.isReady) {
+    console.log('Elements SDK ready', data.version);
+  }
+}, { once: true });
+```
+
+## Product Events
+
+### `lce:actions.product_loaded`
+
+Fires when a product component finishes loading and product data is available.
+
+**Data includes:** `identifier`, `name`, `priceInfo`, `selectedSizeId`, `selectedFulfillmentType`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.product_loaded', (event) => {
+  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**
+
+```javascript
+window.addEventListener('lce:actions.product_add_to_cart', (event) => {
+  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**
+
+```javascript
+window.addEventListener('lce:actions.product_size_changed', (event) => {
+  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).
+
+**Data includes:** `identifier`, `selectedFulfillmentType`, `previousFulfillmentType`, `selectedFulfillmentId`, `previousFulfillmentId`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.product_fulfillment_type_changed', (event) => {
+  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.
+
+**Data includes:** `identifier`, `selectedFulfillmentId`, `previousFulfillmentId`, `selectedFulfillmentType`, `previousFulfillmentType`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.product_fulfillment_changed', (event) => {
+  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`.
+
+**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
+window.addEventListener('lce:actions.address_updated', (event) => {
+  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`
+
+Fires when setting the address fails.
+
+**Data includes:** `googlePlacesId`, `formattedAddress`, `address`, `coordinates`, `error`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.address_failed', (event) => {
+  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
+window.addEventListener('lce:actions.cart_loaded', (event) => {
+  const { data } = event.detail;
+  console.log(`Cart ${data.cartId} has ${data.itemCount} items`);
+});
+```
+
+### `lce:actions.cart_opened`
+
+Fires when the cart drawer opens.
+
+**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 { 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);
+});
+```
+
+### `lce:actions.cart_promo_code_applied`
+
+Fires when a promo code is applied to the cart.
+
+**Data includes:** `cartId`, `discount`, `newSubtotal`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.cart_promo_code_applied', (event) => {
+  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);
+});
+```
+
+### `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 { 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 { 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
+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`
+
+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);
+});
+```
+
+### `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 { 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');
+  }
+});
+```
+
+### `lce:actions.checkout_submit_completed`
+
+Fires when checkout submission completes successfully.
+
+**Data includes:** `orderNumber`, `orderTotal`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  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 { 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`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_product_add_success', (event) => {
+  const { data } = event.detail;
+  console.log(`Checkout added ${data.itemsAdded} products`);
+});
+```
+
+### `lce:actions.checkout_product_add_failed`
+
+Fires when adding products to checkout via the actions API fails.
+
+**Data includes:** `cartId`, `identifiers`, `error`.
+
+**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
+
+### Analytics Integration
+
+```javascript
+// Track product views
+window.addEventListener('lce:actions.product_loaded', (event) => {
+  const { data } = event.detail;
+  gtag('event', 'view_item', {
+    items: [{
+      item_id: data.identifier,
+      item_name: data.name,
+      price: data.priceInfo?.minimum / 100
+    }]
+  });
+});
+
+// Track purchases
+window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  const { data } = event.detail;
+  gtag('event', 'purchase', {
+    transaction_id: data.orderNumber,
+    value: data.orderTotal / 100,
+    currency: 'USD'
+  });
+});
+```
+
+## See Also
+
+- [Component Guides](../guides/)
+- [Actions API](../api/actions/)