@liquidcommerce/elements-sdk 2.7.0 → 2.7.2

package/docs/v1/reference/error-handling.md

@@ -0,0 +1,70 @@
+# Error Handling
+
+The SDK emits errors as events and (when applicable) throws a custom `SDKError`. Your app should handle both.
+
+## SDKError
+
+All SDK errors use a custom error class:
+
+```typescript
+class SDKError extends Error {
+  constructor(message: string, reThrow?: boolean);
+  name: 'SDKError';
+  isSdk: boolean;
+  reThrow: boolean;
+}
+```
+
+## Catching Errors
+
+```javascript
+try {
+  await window.elements.injectProductElement([
+    { containerId: 'product', identifier: 'invalid_id' }
+  ]);
+} catch (error) {
+  if (error.name === 'SDKError') {
+    console.error('SDK Error:', error);
+  }
+}
+```
+
+## Error Isolation
+
+The SDK catches and contains its own errors so your app keeps running:
+
+```javascript
+window.elements.actions.cart.addProduct([/* invalid */]);
+console.log('App still working');
+```
+
+## Error Events
+
+Listen for failure events to show user-friendly messages or trigger retries:
+
+```javascript
+// Cart add failed
+window.addEventListener('lce:actions.cart_product_add_failed', (event) => {
+  console.error('Failed to add:', event.detail.data.error);
+});
+
+// Address failed
+window.addEventListener('lce:actions.address_failed', (event) => {
+  console.error('Address error:', event.detail.data.error);
+});
+
+// Checkout submit failed
+window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
+  console.error('Checkout failed:', event.detail.data.error);
+});
+```
+
+## UI Errors
+
+When a component fails to load, the SDK renders an error view inside the container and logs details to the console.
+
+## Related Docs
+
+- [Events Guide](../guides/events.md)
+- [Client API](../api/client.md)
+- [Troubleshooting](./troubleshooting.md)

package/docs/v1/reference/performance.md

@@ -0,0 +1,54 @@
+# Performance Guide
+
+The SDK is optimized out of the box. These tweaks help reduce load time and layout shift.
+
+## 1) Load Non-Blocking
+
+```html
+<script defer data-liquid-commerce-elements ...></script>
+```
+
+## 2) Use the Checkout-Only Build When Appropriate
+
+If you only need checkout, use the tree-shaken build:
+
+```javascript
+import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
+```
+
+## 3) Inject Components When Needed
+
+Inject above-the-fold products first, then load the rest:
+
+```javascript
+await client.injectProductElement([
+  { containerId: 'hero-product', identifier: '001' }
+]);
+
+setTimeout(async () => {
+  await client.injectProductElement([
+    { containerId: 'related-1', identifier: '002' },
+    { containerId: 'related-2', identifier: '003' }
+  ]);
+}, 1000);
+```
+
+## 4) Reserve Space to Prevent Layout Shift
+
+```css
+#product {
+  min-height: 600px;
+}
+```
+
+## 5) Let the SDK Handle Media Optimization
+
+The SDK automatically:
+- Lazy loads images
+- Uses responsive image sizes
+- Virtualizes carousel images
+
+## Related Docs
+
+- [Best Practices](../guides/best-practices.md)
+- [Product Component](../guides/product-component.md)

package/docs/v1/reference/troubleshooting.md

@@ -0,0 +1,64 @@
+# Troubleshooting
+
+Common setup issues and how to resolve them.
+
+## SDK Script Not Loading
+
+**Symptoms:** 404/CORS in Network tab, `window.elements` is undefined.
+
+**Fixes:**
+- Verify the script URL and that the tag includes `data-liquid-commerce-elements`.
+- Check ad blockers; proxy the API if needed.
+- Confirm `data-env` is set correctly.
+
+## Web Components Error
+
+**Symptoms:** Console logs about Custom Elements or Shadow DOM.
+
+**Fix:** Add the Web Components polyfill before the SDK:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@webcomponents/webcomponentsjs@2/webcomponents-bundle.js"></script>
+<script defer data-liquid-commerce-elements ...></script>
+```
+
+## Product Not Showing
+
+**Symptoms:** Empty container or error view.
+
+**Fixes:**
+- Confirm the container ID matches your HTML.
+- Verify the product identifier exists.
+- Check for errors in the console or network tab.
+
+## Cart Drawer Not Opening
+
+**Symptoms:** Add to cart works but cart stays closed.
+
+**Fixes:**
+- Ensure a cart button is configured or call `window.elements.actions.cart.openCart()`.
+- Check for JavaScript errors in the console.
+
+## Checkout Issues
+
+**Symptoms:** Checkout fails to load or submit.
+
+**Fixes:**
+- Verify you are on a supported browser.
+- Look for `checkout_*_failed` events in the console.
+- Check for Stripe-related errors in the browser console.
+
+## Address/Availability Problems
+
+**Symptoms:** Products show unavailable or address prompts fail.
+
+**Fixes:**
+- Make sure the address is set and valid.
+- Listen for `lce:actions.address_failed` to surface errors.
+
+## Related Docs
+
+- [Installation](../getting-started/installation.md)
+- [Browser Support](./browser-support.md)
+- [Error Handling](./error-handling.md)
+- [Proxy Setup](../integration/proxy-setup.md)

package/package.json

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.7.0",
+  "version": "2.7.2",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",