@liquidcommerce/elements-sdk 2.6.7 → 2.7.1

package/docs/v1/guides/events.md

@@ -0,0 +1,191 @@
+# Events Guide
+
+The SDK publishes events for all user interactions and state changes.
+
+## Event Format
+
+All SDK events follow this pattern:
+
+```javascript
+window.addEventListener('lce:actions.event_name', (event) => {
+  const {
+    namespace,  // 'lce:actions'
+    event: eventName,  // 'cart_item_added'
+    timestamp,  // Unix timestamp
+    id,  // Unique event ID
+    data  // Event-specific data
+  } = event.detail;
+});
+```
+
+## Event Namespaces
+
+- `lce:actions.*` - User actions and state changes
+- `lce:forms.*` - Form interactions (checkout)
+
+## Core Events
+
+### Client Ready
+
+```javascript
+window.addEventListener('lce:actions.client_ready', (event) => {
+  const { isReady, version, timestamp } = event.detail.data;
+  console.log(`Elements SDK v${version} is ready`);
+});
+```
+
+## Product Events
+
+```javascript
+// Product loaded
+window.addEventListener('lce:actions.product_loaded', (event) => {
+  const { identifier, name, price } = event.detail.data;
+});
+
+// Add to cart clicked
+window.addEventListener('lce:actions.product_add_to_cart', (event) => {
+  const { identifier, quantity, fulfillmentType } = event.detail.data;
+});
+
+// Size changed
+window.addEventListener('lce:actions.product_size_changed', (event) => {
+  const { identifier, selectedSize } = event.detail.data;
+});
+
+// Fulfillment type changed
+window.addEventListener('lce:actions.product_fulfillment_type_changed', (event) => {
+  const { identifier, fulfillmentType } = event.detail.data;
+});
+
+// Retailer changed
+window.addEventListener('lce:actions.product_fulfillment_changed', (event) => {
+  const { identifier, selectedRetailer } = event.detail.data;
+});
+
+// Quantity changed
+window.addEventListener('lce:actions.product_quantity_increase', (event) => {});
+window.addEventListener('lce:actions.product_quantity_decrease', (event) => {});
+```
+
+## Address Events
+
+```javascript
+// Address set
+window.addEventListener('lce:actions.address_updated', (event) => {
+  const { address, coordinates, formattedAddress } = event.detail.data;
+});
+
+// Address cleared
+window.addEventListener('lce:actions.address_cleared', (event) => {});
+
+// Address error
+window.addEventListener('lce:actions.address_failed', (event) => {
+  const { error } = event.detail.data;
+});
+```
+
+## Cart Events
+
+```javascript
+// Cart loaded
+window.addEventListener('lce:actions.cart_loaded', (event) => {
+  const { cartId, itemsCount } = event.detail.data;
+});
+
+// Cart opened/closed
+window.addEventListener('lce:actions.cart_opened', (event) => {});
+window.addEventListener('lce:actions.cart_closed', (event) => {});
+
+// Cart updated
+window.addEventListener('lce:actions.cart_updated', (event) => {
+  const { cartId, itemsCount, subtotal } = event.detail.data;
+});
+
+// Item added/removed
+window.addEventListener('lce:actions.cart_item_added', (event) => {});
+window.addEventListener('lce:actions.cart_item_removed', (event) => {});
+
+// Quantity changed
+window.addEventListener('lce:actions.cart_item_quantity_increase', (event) => {});
+window.addEventListener('lce:actions.cart_item_quantity_decrease', (event) => {});
+
+// Promo code events
+window.addEventListener('lce:actions.cart_promo_code_applied', (event) => {
+  const { discount, newSubtotal } = event.detail.data;
+});
+window.addEventListener('lce:actions.cart_promo_code_removed', (event) => {});
+window.addEventListener('lce:actions.cart_promo_code_failed', (event) => {});
+
+// Product add success/failure
+window.addEventListener('lce:actions.cart_product_add_success', (event) => {
+  const { itemsAdded, identifiers } = event.detail.data;
+});
+window.addEventListener('lce:actions.cart_product_add_failed', (event) => {
+  const { error } = event.detail.data;
+});
+```
+
+## Checkout Events
+
+```javascript
+// Lifecycle
+window.addEventListener('lce:actions.checkout_loaded', (event) => {});
+window.addEventListener('lce:actions.checkout_opened', (event) => {});
+window.addEventListener('lce:actions.checkout_closed', (event) => {});
+
+// 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) => {});
+
+// Toggles
+window.addEventListener('lce:actions.checkout_is_gift_toggled', (event) => {
+  const { isGift } = event.detail.data;
+});
+window.addEventListener('lce:actions.checkout_billing_same_as_shipping_toggled', (event) => {});
+window.addEventListener('lce:actions.checkout_marketing_preferences_toggled', (event) => {});
+
+// Submission
+window.addEventListener('lce:actions.checkout_submit_started', (event) => {});
+window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  const { orderId, total } = event.detail.data;
+});
+window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
+  const { error } = event.detail.data;
+});
+
+// Promo codes & gift cards
+window.addEventListener('lce:actions.checkout_promo_code_applied', (event) => {});
+window.addEventListener('lce:actions.checkout_gift_card_applied', (event) => {});
+```
+
+## Use Cases
+
+### Analytics Integration
+
+```javascript
+// Track page views
+window.addEventListener('lce:actions.product_loaded', (event) => {
+  gtag('event', 'view_item', {
+    items: [{
+      item_id: event.detail.data.identifier,
+      item_name: event.detail.data.name,
+      price: event.detail.data.price / 100
+    }]
+  });
+});
+
+// Track purchases
+window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  gtag('event', 'purchase', {
+    transaction_id: event.detail.data.orderId,
+    value: event.detail.data.total / 100,
+    currency: 'USD'
+  });
+});
+```
+
+## See Also
+
+- [Component Guides](../guides/)
+- [Actions API](../api/actions/)