@liquidcommerce/elements-sdk 2.6.0-beta.40 → 2.6.0-beta.42

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.6.0-beta.40",
+  "version": "2.6.0-beta.42",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",

package/docs/actions.md

@@ -1,320 +0,0 @@
-# Actions
-
-Actions let you control the SDK with JavaScript instead of (or in addition to) user interactions. Open the cart when a user clicks your custom button, pre-fill checkout forms for returning customers, or add products to cart from anywhere in your app.
-
-## Accessing Actions
-
-```javascript
-// Global access
-const { actions } = window.elements;
-
-// Or from client instance
-const client = await Elements('YOUR_API_KEY', config);
-// Access via client.actions
-```
-
-## How Actions Work
-
-Actions are fire-and-forget methods that return `void` or `Promise<void>`. All feedback comes through [events](./events.md) - this is by design for security.
-
-```javascript
-// 1. Listen for feedback
-window.addEventListener('lce:actions.cart_promo_code_applied', (event) => {
-  const { discount, newSubtotal } = event.detail.data;
-  showSuccess(`Saved $${discount}!`);
-});
-
-// 2. Fire the action
-await actions.cart.applyPromoCode('SUMMER20');
-```
-
----
-
-## Address Actions
-
-Manage the customer's delivery location.
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `setAddressByPlacesId(placesId)` | `Promise<void>` | Set location via Google Places ID |
-| `setAddressManually(address, coords)` | `Promise<void>` | Set location with address and coordinates |
-| `getDetails()` | `IAddressData \| null` | Get current address |
-| `clear()` | `Promise<void>` | Clear address (also resets cart) |
-
-### setAddressByPlacesId
-
-```javascript
-await actions.address.setAddressByPlacesId('ChIJN1t_tDeuEmsRUsoyG83frY4');
-```
-
-### setAddressManually
-
-```javascript
-await actions.address.setAddressManually(
-  {
-    one: '123 Main St',
-    two: 'Apt 4B',        // optional
-    city: 'New York',
-    state: 'NY',
-    zip: '10001',
-    country: 'US'         // optional
-  },
-  {
-    lat: 40.7128,
-    long: -74.0060
-  }
-);
-```
-
-### getDetails
-
-```javascript
-const address = actions.address.getDetails();
-if (address) {
-  console.log(address.formattedAddress);
-  console.log(address.coordinates);
-}
-```
-
-### clear
-
-```javascript
-await actions.address.clear();
-// Note: This also clears the cart
-```
-
-**Feedback Events:** `address_updated`, `address_cleared`, `address_failed`
-
----
-
-## Product Actions
-
-Query product information.
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `getDetails(identifier)` | `IBaseProductEventData` | Get product state |
-
-### getDetails
-
-```javascript
-const product = actions.product.getDetails('00619947000020');
-
-console.log(product.name);
-console.log(product.selectedSizeId);
-console.log(product.selectedFulfillmentType);
-console.log(product.priceInfo);
-```
-
----
-
-## Cart Actions
-
-Control the shopping cart.
-
-| Method | Returns | Description         |
-|--------|---------|---------------------|
-| `openCart()` | `void` | Show cart drawer    |
-| `closeCart()` | `void` | Hide cart drawer    |
-| `toggleCart()` | `void` | Toggle cart drawer  |
-| `addProduct(items[], openCart?)` | `Promise<void>` | Add items to cart   |
-| `applyPromoCode(code)` | `Promise<void>` | Apply discount code |
-| `removePromoCode()` | `Promise<void>` | Remove discount     |
-| `resetCart()` | `Promise<void>` | Clear all items     |
-| `getDetails()` | `IBaseCartEventData` | Get cart state      |
-
-### openCart / closeCart / toggleCart
-
-```javascript
-actions.cart.openCart();
-actions.cart.closeCart();
-actions.cart.toggleCart();
-```
-
-### addProduct
-
-```javascript
-await actions.cart.addProduct(
-  [
-    {
-      identifier: '00619947000020',
-      fulfillmentType: 'shipping',  // 'shipping' or 'onDemand'
-      quantity: 2
-    }
-  ],
-  true  // Open cart after adding (optional)
-);
-```
-
-### applyPromoCode / removePromoCode
-
-```javascript
-await actions.cart.applyPromoCode('SUMMER20');
-await actions.cart.removePromoCode();
-```
-
-### resetCart
-
-```javascript
-await actions.cart.resetCart();
-```
-
-### getDetails
-
-```javascript
-const cart = actions.cart.getDetails();
-
-console.log(cart.itemCount);
-console.log(cart.subtotal);
-console.log(cart.items);
-```
-
-**Feedback Events:** `cart_opened`, `cart_closed`, `cart_product_add_success`, `cart_product_add_failed`, `cart_promo_code_applied`, `cart_promo_code_removed`, `cart_promo_code_failed`, `cart_reset`
-
----
-
-## Checkout Actions
-
-Control the checkout flow.
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `openCheckout()` | `void` | Show checkout drawer |
-| `closeCheckout()` | `void` | Hide checkout drawer |
-| `toggleCheckout()` | `void` | Toggle checkout drawer |
-| `exitCheckout()` | `void` | Navigate to exit URL |
-| `addProduct(items[], open?)` | `Promise<void>` | Add to checkout directly |
-| `applyPromoCode(code)` | `Promise<void>` | Apply discount |
-| `removePromoCode()` | `Promise<void>` | Remove discount |
-| `applyGiftCard(code)` | `Promise<void>` | Apply gift card |
-| `removeGiftCard(code)` | `Promise<void>` | Remove gift card |
-| `toggleIsGift(active?)` | `Promise<void>` | Enable/disable gift mode |
-| `toggleBillingSameAsShipping(active?)` | `Promise<void>` | Use same address |
-| `toggleMarketingPreferences(field, active)` | `Promise<void>` | Set opt-in |
-| `updateCustomerInfo(params)` | `void` | Pre-fill customer form |
-| `updateBillingInfo(params)` | `void` | Pre-fill billing form |
-| `updateGiftInfo(params)` | `void` | Pre-fill gift form |
-| `getDetails()` | `ICheckoutDetailsEventData` | Get checkout state |
-
-### openCheckout / closeCheckout / toggleCheckout / exitCheckout
-
-```javascript
-actions.checkout.openCheckout();
-actions.checkout.closeCheckout();
-actions.checkout.toggleCheckout();
-actions.checkout.exitCheckout();  // Navigates to configured exit URL
-```
-
-### addProduct
-
-```javascript
-// Add products directly to checkout (skip cart)
-await actions.checkout.addProduct(
-  [{ identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }],
-  true  // Open checkout (optional)
-);
-```
-
-### applyPromoCode / removePromoCode
-
-```javascript
-await actions.checkout.applyPromoCode('SAVE10');
-await actions.checkout.removePromoCode();
-```
-
-### applyGiftCard / removeGiftCard
-
-```javascript
-await actions.checkout.applyGiftCard('GIFT-XXXX-XXXX');
-await actions.checkout.removeGiftCard('GIFT-XXXX-XXXX');
-```
-
-### toggleIsGift / toggleBillingSameAsShipping / toggleMarketingPreferences
-
-```javascript
-await actions.checkout.toggleIsGift(true);
-await actions.checkout.toggleBillingSameAsShipping(true);
-await actions.checkout.toggleMarketingPreferences('canEmail', true);
-await actions.checkout.toggleMarketingPreferences('canSms', false);
-```
-
-### updateCustomerInfo
-
-```javascript
-actions.checkout.updateCustomerInfo({
-  firstName: 'John',
-  lastName: 'Doe',
-  email: 'john@example.com',
-  phone: '555-123-4567'
-});
-```
-
-### updateBillingInfo
-
-```javascript
-actions.checkout.updateBillingInfo({
-  firstName: 'John',
-  lastName: 'Doe',
-  street1: '123 Billing St',
-  street2: 'Suite 100',  // optional
-  city: 'New York',
-  state: 'NY',
-  zipCode: '10001'
-});
-```
-
-### updateGiftInfo
-
-```javascript
-actions.checkout.updateGiftInfo({
-  recipientName: 'Jane Smith',
-  senderName: 'John Doe',
-  giftMessage: 'Happy Birthday!'
-});
-```
-
-### getDetails
-
-```javascript
-const checkout = actions.checkout.getDetails();
-
-console.log(checkout.subtotal);
-console.log(checkout.total);
-console.log(checkout.items);
-console.log(checkout.isGift);
-```
-
-**Feedback Events:** `checkout_opened`, `checkout_closed`, `checkout_product_add_success`, `checkout_product_add_failed`, `checkout_promo_code_applied`, `checkout_promo_code_removed`, `checkout_promo_code_failed`, `checkout_gift_card_applied`, `checkout_gift_card_removed`, `checkout_gift_card_failed`
-
----
-
-## Product List Actions
-
-Coming soon.
-
----
-
-## Security Notes
-
-Events never expose sensitive information:
-
-**Safe in events:**
-- Success/failure status
-- Discount amounts
-- Total amounts
-- Item counts and identifiers
-
-**Never exposed:**
-- Promo codes or gift card codes
-- Gift card balances
-- Sensitive financial details
-
----
-
-## See Also
-
-- [Events Reference](./events.md) - Event feedback for actions
-- [Product](./product.md) - Product component
-- [Cart](./cart.md) - Cart component
-- [Checkout](./checkout.md) - Checkout component
-- [Address](./address.md) - Address component