@liquidcommerce/elements-sdk 2.2.2 → 2.4.0

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,755 @@
+# Troubleshooting Guide
+
+Common issues and solutions for the LiquidCommerce Elements SDK.
+
+## SDK Initialization Issues
+
+### SDK Not Loading
+
+**Symptom:** `Elements is not defined` or SDK not initializing
+
+**Causes & Solutions:**
+
+#### 1. Script Not Loaded
+
+```html
+<!-- ❌ Wrong -->
+<script src="https://assets-elements.liquidcommerce.us/all/elements.js" async></script>
+
+<!-- ✅ Correct - Remove async or use onload -->
+<script src="https://assets-elements.liquidcommerce.us/all/elements.js"></script>
+
+<!-- Or with async -->
+<script src="https://assets-elements.liquidcommerce.us/all/elements.js" async onload="initSDK()"></script>
+```
+
+#### 2. Content Security Policy (CSP)
+
+```html
+<!-- Add to your CSP -->
+<meta http-equiv="Content-Security-Policy" 
+      content="script-src 'self' https://assets-elements.liquidcommerce.us;">
+```
+
+#### 3. Ad Blockers
+
+**Solution:** Configure a [proxy](./PROXY.md) to route requests through your domain.
+
+### Authentication Failures
+
+**Symptom:** `401 Unauthorized` or `Invalid API key`
+
+**Solutions:**
+
+```javascript
+// ✅ Check API key is correct
+const client = await Elements('YOUR_ACTUAL_API_KEY', {
+  env: 'production'  // Make sure env matches your key
+});
+
+// ✅ Verify environment
+// Production keys won't work in development env
+const client = await Elements('PROD_KEY', {
+  env: 'production'  // Not 'development'
+});
+```
+
+**Check:**
+- API key is correct
+- Environment matches key (prod key → prod env)
+- Key hasn't been revoked
+- Domain is whitelisted in LiquidCommerce dashboard
+
+### Configuration Errors
+
+**Symptom:** `Invalid configuration` errors
+
+**Common mistakes:**
+
+```javascript
+// ❌ Wrong - Invalid env value
+{ env: 'prod' }  // Should be 'production'
+
+// ❌ Wrong - Invalid debugMode
+{ debugMode: 'debug' }  // Should be 'console' or 'panel'
+
+// ❌ Wrong - Invalid proxy config
+{ proxy: 'https://...' }  // Should be object with baseUrl
+
+// ✅ Correct
+{
+  env: 'production',
+  debugMode: 'none',
+  proxy: {
+    baseUrl: 'https://...'
+  }
+}
+```
+
+## Component Rendering Issues
+
+### Components Not Appearing
+
+**Symptom:** Container div is empty
+
+**Debugging steps:**
+
+```javascript
+// 1. Check container exists
+const container = document.getElementById('product-container');
+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([
+    { containerId: 'product-container', identifier: 'product-123' }
+  ]);
+});
+
+// 3. Monitor product loading
+window.addEventListener('lce:actions.product_loaded', (event) => {
+  console.log('Product loaded:', event.detail.data);
+});
+```
+
+**Common issues:**
+- Container doesn't exist when SDK tries to inject
+- Product identifier is invalid
+- Product not available in current environment
+
+### Styling Issues
+
+**Symptom:** Components look broken or unstyled
+
+**Solutions:**
+
+```javascript
+// 1. Check for CSS conflicts
+// Look for these in your CSS:
+// - * { all: unset }
+// - Overly broad selectors affecting [data-lce-*]
+
+// 2. Verify theme config
+const client = await Elements('YOUR_API_KEY', {
+  customTheme: {
+    global: {
+      colors: {
+        primary: '#007bff'  // Valid hex color
+      }
+    }
+  }
+});
+
+// 3. Check z-index conflicts
+// SDK uses z-index 1000-1070 for modals/drawers
+```
+
+### Layout Issues
+
+**Symptom:** Components overlapping or misaligned
+
+**Solutions:**
+
+```css
+/* Ensure container has proper display */
+#product-container {
+  display: block;
+  width: 100%;
+  min-height: 400px;  /* Prevent collapsing */
+}
+
+/* Fix flexbox/grid conflicts */
+#product-container > * {
+  flex: initial;
+  grid-column: initial;
+}
+```
+
+## Event Handling Issues
+
+### Events Not Firing
+
+**Symptom:** Event listeners not being called
+
+**Solutions:**
+
+```javascript
+// ✅ Correct - Set up listener BEFORE action
+window.addEventListener('lce:actions.cart_updated', handleUpdate);
+await client.actions.cart.addProduct([...]);
+
+// ❌ Wrong - Listener after action (might miss event)
+await client.actions.cart.addProduct([...]);
+window.addEventListener('lce:actions.cart_updated', handleUpdate);
+
+// ✅ Use capture phase for guaranteed delivery
+window.addEventListener('lce:actions.cart_updated', handleUpdate, true);
+```
+
+### Event Data Missing
+
+**Symptom:** `event.detail.data` is undefined
+
+**Check:**
+
+```javascript
+window.addEventListener('lce:actions.cart_updated', (event) => {
+  // ❌ Wrong
+  const data = event.data;
+  
+  // ✅ Correct
+  const data = event.detail.data;
+  
+  console.log('Cart data:', data);
+});
+```
+
+### Multiple Event Firings
+
+**Symptom:** Event listener called multiple times unexpectedly
+
+**Solution:**
+
+```javascript
+// ❌ Problem - Adding listener multiple times
+function setupListeners() {
+  window.addEventListener('lce:actions.cart_updated', handleUpdate);
+}
+
+// ✅ Solution - Remove before adding
+function setupListeners() {
+  window.removeEventListener('lce:actions.cart_updated', handleUpdate);
+  window.addEventListener('lce:actions.cart_updated', handleUpdate);
+}
+
+// Or use once option
+window.addEventListener('lce:actions.cart_updated', handleUpdate, { once: true });
+```
+
+## Cart & Checkout Issues
+
+### Cart Not Persisting
+
+**Symptom:** Cart clears on page reload
+
+**Causes:**
+
+```javascript
+// 1. LocalStorage disabled
+if (!('localStorage' in window)) {
+  console.error('LocalStorage not available');
+}
+
+// 2. Private/Incognito mode
+// LocalStorage is disabled in private browsing
+
+// 3. Storage quota exceeded
+try {
+  localStorage.setItem('test', 'test');
+} catch (e) {
+  console.error('Storage error:', e);
+}
+```
+
+**Solutions:**
+- Ask users to enable cookies/storage
+- Warn users about private mode limitations
+- Clear old localStorage data
+
+### Checkout Failing
+
+**Symptom:** Checkout submit errors
+
+**Common causes:**
+
+```javascript
+// Listen for specific errors
+window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
+  const { error, reason } = event.detail.data;
+  
+  if (reason.includes('payment')) {
+    // Payment declined
+    showPaymentError();
+  } else if (reason.includes('inventory')) {
+    // Out of stock
+    showInventoryError();
+  } else if (reason.includes('address')) {
+    // Invalid address
+    showAddressError();
+  }
+});
+```
+
+**Debug steps:**
+1. Check address is set: `client.actions.address.getDetails()`
+2. Check cart has items: `client.actions.cart.getDetails()`
+3. Verify payment info is complete
+4. Check for form validation errors
+5. Look for network errors in console
+
+### Promo Code Issues
+
+**Symptom:** Promo codes not applying
+
+**Debug:**
+
+```javascript
+// Listen for promo failures
+window.addEventListener('lce:actions.cart_promo_code_failed', (event) => {
+  const { error } = event.detail.data;
+  console.error('Promo failed:', error);
+  
+  // Common errors:
+  // - "Promo code expired"
+  // - "Cart minimum not met"
+  // - "Promo code invalid"
+  // - "Promo already applied"
+});
+
+// Verify promo is active
+// Check LiquidCommerce dashboard for promo settings
+```
+
+## Address Validation Issues
+
+### Google Places Not Working
+
+**Symptom:** Address autocomplete not appearing
+
+**Causes:**
+
+```javascript
+// 1. Google Places API key missing/invalid
+// Check browser console for Google API errors
+
+// 2. Domain not authorized
+// Add your domain to Google Cloud Console
+
+// 3. API not enabled
+// Enable Places API in Google Cloud Console
+```
+
+### Manual Address Issues
+
+**Symptom:** Manual address not working
+
+**Solutions:**
+
+```javascript
+// Ensure coordinates are valid
+const isValidLat = lat >= -90 && lat <= 90;
+const isValidLng = lng >= -180 && lng <= 180;
+
+if (!isValidLat || !isValidLng) {
+  console.error('Invalid coordinates');
+}
+
+// Use proper format
+await client.actions.address.setAddressManually(
+  {
+    one: '123 Main St',
+    two: 'Apt 4B',  // Optional but must be string
+    city: 'New York',
+    state: 'NY',
+    zip: '10001',
+    country: 'United States'
+  },
+  {
+    lat: 40.7505045,
+    long: -73.9934387  // Note: "long" not "lng"
+  }
+);
+```
+
+## Network & API Issues
+
+### CORS Errors
+
+**Symptom:** `Access-Control-Allow-Origin` errors
+
+**Solutions:**
+
+```javascript
+// 1. Use proxy to avoid CORS
+const client = await Elements('YOUR_API_KEY', {
+  proxy: {
+    baseUrl: 'https://yourdomain.com/api/liquidcommerce'
+  }
+});
+
+// 2. Check domain whitelist
+// Verify your domain is whitelisted in LiquidCommerce dashboard
+
+// 3. Development workaround
+// Use browser extension to disable CORS (dev only!)
+```
+
+### Slow API Responses
+
+**Symptom:** Components take long to load
+
+**Debug:**
+
+```javascript
+// 1. Enable debug mode
+const client = await Elements('YOUR_API_KEY', {
+  debugMode: 'console'
+});
+
+// 2. Check network tab
+// Look for slow API calls
+
+// 3. Monitor for failures
+window.addEventListener('lce:actions.cart_failed', (event) => {
+  console.warn('Cart operation failed:', event.detail);
+});
+```
+
+**Solutions:**
+- Configure proxy for better routing
+- Check internet connection
+- Verify API status (LiquidCommerce status page)
+- Use CDN for SDK script (automatic caching)
+
+### API Rate Limiting
+
+**Symptom:** `429 Too Many Requests`
+
+**Solutions:**
+
+```javascript
+// Implement retry logic
+async function addToCartWithRetry(params, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      await client.actions.cart.addProduct(params);
+      return;
+    } catch (error) {
+      if (error.status === 429) {
+        // Wait before retry
+        await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
+      } else {
+        throw error;
+      }
+    }
+  }
+}
+```
+
+## Performance Issues
+
+### Slow Page Load
+
+**Symptom:** SDK slows down page load
+
+**Solutions:**
+
+```html
+<!-- 1. Use defer attribute -->
+<script defer src="https://assets-elements.liquidcommerce.us/all/elements.js"></script>
+
+<!-- 2. Load at end of body -->
+<body>
+  <!-- Page content -->
+  <script src="https://assets-elements.liquidcommerce.us/all/elements.js"></script>
+</body>
+
+<!-- 3. Lazy load components -->
+<script>
+window.addEventListener('load', async () => {
+  const client = await Elements('YOUR_API_KEY', { env: 'production' });
+  // Initialize after page load
+});
+</script>
+```
+
+### Memory Leaks
+
+**Symptom:** Page becomes slow over time
+
+**Solutions:**
+
+```javascript
+// Remove event listeners when done
+function cleanup() {
+  window.removeEventListener('lce:actions.cart_updated', handleUpdate);
+  window.removeEventListener('lce:actions.product_loaded', handleProduct);
+}
+
+// In React/Vue
+useEffect(() => {
+  window.addEventListener('lce:actions.cart_updated', handleUpdate);
+  
+  return () => {
+    window.removeEventListener('lce:actions.cart_updated', handleUpdate);
+  };
+}, []);
+```
+
+### High CPU Usage
+
+**Symptom:** Browser tab using excessive CPU
+
+**Check:**
+
+```javascript
+// 1. Disable debug mode in production
+{
+  debugMode: 'none'  // Not 'panel'
+}
+
+// 2. Minimize theme complexity
+{
+  customTheme: {
+    global: {
+      colors: {
+        primary: '#007bff'  // Only override what's needed
+      }
+    }
+  }
+}
+
+// 3. Reduce event listeners
+// Use event delegation instead of many listeners
+```
+
+## Mobile-Specific Issues
+
+### Touch Events Not Working
+
+**Symptom:** Buttons/interactions not responding on mobile
+
+**Check:**
+
+```css
+/* Ensure touch targets are large enough */
+button {
+  min-height: 44px;  /* iOS minimum */
+  min-width: 44px;
+}
+
+/* Fix iOS double-tap zoom */
+button {
+  touch-action: manipulation;
+}
+```
+
+### Viewport Issues
+
+**Symptom:** Components too small or zoomed on mobile
+
+**Solution:**
+
+```html
+<!-- Ensure viewport meta tag is present -->
+<meta name="viewport" content="width=device-width, initial-scale=1">
+```
+
+### Keyboard Covering Input
+
+**Symptom:** Keyboard covers form fields on mobile
+
+**Solution:**
+
+```javascript
+// SDK handles this automatically, but if issues persist:
+document.addEventListener('focusin', (e) => {
+  if (e.target.tagName === 'INPUT') {
+    setTimeout(() => {
+      e.target.scrollIntoView({ behavior: 'smooth', block: 'center' });
+    }, 300);
+  }
+});
+```
+
+## Framework-Specific Issues
+
+### React Issues
+
+**Problem:** SDK initializes multiple times
+
+**Solution:**
+
+```jsx
+import { useEffect, useRef } from 'react';
+
+function App() {
+  const clientRef = useRef(null);
+  
+  useEffect(() => {
+    async function init() {
+      if (!clientRef.current) {
+        clientRef.current = await Elements('YOUR_API_KEY', { env: 'production' });
+      }
+    }
+    init();
+  }, []);  // Empty deps - initialize once
+  
+  return <div id="product-container"></div>;
+}
+```
+
+### Next.js Issues
+
+**Problem:** `window is not defined` (SSR)
+
+**Solution:**
+
+```javascript
+// pages/product.js
+import { useEffect } from 'react';
+
+export default function Product() {
+  useEffect(() => {
+    // Only run on client
+    async function init() {
+      if (typeof window !== 'undefined') {
+        const { Elements } = await import('@liquidcommerce/elements-sdk');
+        const client = await Elements(process.env.NEXT_PUBLIC_LCE_API_KEY, {
+          env: 'production'
+        });
+      }
+    }
+    init();
+  }, []);
+  
+  return <div id="product-container"></div>;
+}
+```
+
+### Vue Issues
+
+**Problem:** Components not reactive
+
+**Solution:**
+
+```vue
+<script setup>
+import { onMounted, ref } from 'vue';
+
+const cartData = ref(null);
+
+onMounted(async () => {
+  const client = await Elements(import.meta.env.VITE_LCE_API_KEY, {
+    env: 'production'
+  });
+  
+  window.addEventListener('lce:actions.cart_updated', (event) => {
+    cartData.value = event.detail.data;  // Vue reactivity
+  });
+});
+</script>
+```
+
+## Browser-Specific Issues
+
+### Safari Issues
+
+**Problem:** LocalStorage quota exceeded
+
+**Solution:**
+
+```javascript
+try {
+  localStorage.setItem('lce_cart', JSON.stringify(cart));
+} catch (e) {
+  if (e.name === 'QuotaExceededError') {
+    // Clear old data
+    localStorage.removeItem('lce_old_cart');
+    // Retry
+    localStorage.setItem('lce_cart', JSON.stringify(cart));
+  }
+}
+```
+
+### Firefox Issues
+
+**Problem:** Different rendering/layout
+
+**Solution:**
+
+```css
+/* Add Firefox-specific fixes if needed */
+@-moz-document url-prefix() {
+  .lce-component {
+    /* Firefox-specific styles */
+  }
+}
+```
+
+## Debugging Tools
+
+### Enable Debug Mode
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  debugMode: 'panel'  // Shows visual debug panel
+});
+```
+
+### Check SDK State
+
+```javascript
+// Get current state
+const cart = await client.actions.cart.getDetails();
+const address = await client.actions.address.getDetails();
+const checkout = await client.actions.checkout.getDetails();
+
+console.log('Cart:', cart);
+console.log('Address:', address);
+console.log('Checkout:', checkout);
+```
+
+### Monitor All Events
+
+```javascript
+// Log all SDK events
+window.elements.onAllActions((data, metadata) => {
+  console.log('Action:', metadata.eventName, data);
+});
+
+window.elements.onAllForms((data, metadata) => {
+  console.log('Form:', metadata.eventName, data);
+});
+```
+
+### Network Inspection
+
+```javascript
+// Monitor cart operations
+window.addEventListener('lce:actions.cart_loaded', (event) => {
+  console.log('Cart loaded:', event.detail.data);
+});
+
+window.addEventListener('lce:actions.cart_failed', (event) => {
+  console.error('Cart operation failed:', event.detail.data);
+});
+```
+
+## Getting Help
+
+If you're still experiencing issues:
+
+1. **Check the console** for error messages
+2. **Enable debug mode** to see detailed logs
+3. **Check network tab** for failed requests
+4. **Verify configuration** matches documentation
+5. **Test in incognito mode** to rule out extensions
+6. **Try a different browser** to isolate browser-specific issues
+7. **Check LiquidCommerce status page** for API issues
+8. **Contact support** with:
+   - SDK version
+   - Browser and OS
+   - Console errors
+   - Steps to reproduce
+   - Minimal code example
+
+## Related Documentation
+
+- [Configuration Reference](./CONFIGURATION.md) - Configuration options
+- [Actions Reference](./ACTIONS.md) - Programmatic control
+- [Events Reference](./EVENTS.md) - Event system
+- [Browser Support](./BROWSER_SUPPORT.md) - Browser compatibility
+- [Proxy Setup](./PROXY.md) - Proxy configuration
+