@liquidcommerce/elements-sdk 2.6.0-beta.13 → 2.6.0-beta.131

package/docs/v1/guides/events.md

@@ -0,0 +1,1061 @@
+# 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_shop_retailer`
+
+A shopper activated **Shop {retailer}** from an unmet cart fulfillment minimum. Opt in with
+`customTheme.cart.layout.showShopRetailerButton: true` (default `false`). The cart command
+revalidates the fulfillment, its current retailer and items, fulfillment type, and remaining
+minimum before emitting. Unsupported, empty, stale or already-satisfied fulfillments emit nothing.
+
+```typescript
+interface ICartShopRetailerEventData {
+  retailerId: string;
+  fulfillmentId: string;
+  fulfillmentType: 'onDemand' | 'shipping';
+}
+```
+
+Listen with the exported constant; the usual event envelope is `{ data, metadata }`:
+
+```javascript
+window.addEventListener(`lce:actions.${ELEMENTS_ACTIONS_EVENT.CART_SHOP_RETAILER}`, (event) => {
+  const { retailerId, fulfillmentId, fulfillmentType } = event.detail.data;
+  // Revalidate against client.actions.cart.getDetails(), then close the drawer
+  // and route to your catalog scoped to this retailer and fulfillment type.
+});
+```
+
+The SDK leaves the drawer open and does not navigate. The host handles routing and derives
+retailer names, totals and minimums from current cart details. The event is also sent to `lce:actions`.
+
+
+
+### `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`, `deliveryScheduling` (keyed by fulfillment ID).
+
+**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_delivery_method_updated`
+
+Fires when the shopper moves a single-item checkout between same-day delivery and shipping. The order
+is re-priced, so the totals change with it. The switch is shown only with
+`development.enableExpressCheckout: true`.
+
+**Data includes:** `cartId`, `fulfillmentType`, `previousFulfillmentType`, `fulfillmentId`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_delivery_method_updated', (event) => {
+  const { data } = event.detail;
+  console.log('Delivery method now', data.fulfillmentType);
+});
+```
+
+### `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_express_checkout_availability`
+
+Fires once the express checkout block has settled which wallet buttons the shopper can reach, and
+again whenever that changes. It always fires at least once per block. `available` is `false` on a
+device or browser that offers no wallet, on a gift order, when a payment method is already bound to
+the checkout, and when Stripe.js cannot load; in every case the SDK hides the whole block including
+its divider.
+
+**Data includes:** `cartId`, `available`, `wallets`.
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_express_checkout_availability', (event) => {
+  const { data } = event.detail;
+  console.log(data.available ? `Wallets: ${data.wallets.join(', ')}` : 'No wallets available');
+});
+```
+
+### `lce:actions.checkout_express_checkout_started`
+
+Fires when the shopper taps a wallet button and the SDK opens the wallet sheet, inside the checkout
+or on a block placed with `injectExpressCheckout` / `injectExpressCheckoutElement`. It fires for every
+tap, and not for a tap the block refuses (a total that moved, an unmet order minimum, a second tap
+while an order is being placed). The tap happens inside Stripe's frame, so this is the only way a host
+page learns of it — for instance, to report `add_to_cart` for a product-page wallet with
+[`actions.analytics`](../api/actions/analytics-actions.md).
+
+**Data includes:** `cartId`, `wallet` (Stripe's name for it: `'apple_pay'`, `'google_pay'`, …).
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_express_checkout_started', (event) => {
+  const { wallet } = event.detail.data;
+  console.log(`Wallet sheet opened: ${wallet}`);
+});
+```
+
+### `lce:actions.checkout_payment_form_failed`
+
+Fires when the card form cannot load Stripe.js, so the card fields cannot appear. The shopper sees a
+message and a **Try again** button where the card form would be; each attempt that fails fires the
+event again. `reason` is `blocked` when something on the page held the script back before it was
+fetched — typically a cookie-consent tool with auto-blocking, for a shopper who has not accepted the
+category Stripe is filed under — and `timeout` or `error` when the load stalled or failed (`error` also when Stripe.js loads but cannot
+build the card form, as when `api.stripe.com` is blocked). See
+[Cookie consent and Content Security Policy](./checkout-component.md#cookie-consent-and-content-security-policy).
+
+**Data includes:** `cartId`, `reason` (`'blocked' | 'timeout' | 'error'`).
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_payment_form_failed', (event) => {
+  const { data } = event.detail;
+  if (data.reason === 'blocked') {
+    // For example, reopen your consent tool's preferences so the shopper can allow Stripe.
+  }
+});
+```
+
+### `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);
+});
+```
+
+### `lce:actions.checkout_delivery_selection_updated`
+
+Emitted once after checkout prepare accepts a delivery window or ASAP choice, from the built-in picker or from `actions.checkout.chooseDeliverySlot`. Draft choices in the picker and failed saves do not emit it.
+
+**Data:** `ICheckoutDetailsEventData`, including `deliveryScheduling: Record<string, CheckoutDeliveryScheduling>` keyed by fulfillment ID, with each accepted `selectedSlotId` and `selectedSlot`.
+
+```javascript
+window.addEventListener('lce:actions.checkout_delivery_selection_updated', (event) => {
+  const scheduling = event.detail.data.deliveryScheduling;
+  console.log('Delivery windows:', scheduling);
+});
+```
+
+## 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/)