@liquidcommerce/elements-sdk 2.6.0-beta.84 → 2.6.0-beta.86

package/docs/v1/guides/product-component.md

@@ -157,6 +157,20 @@ For products with multiple sizes:
 - Availability checking per size
 - Out-of-stock indication
 
+#### Preselect a Size via URL
+
+Use the `lce_size` query parameter to preselect a size when the product page loads:
+
+```
+https://yoursite.com/products/buffalo-trace?lce_size=750ml
+```
+
+- The value is matched against each size's display value (e.g. `750ml`).
+- Matching is case-insensitive and ignores whitespace, so `750 ML`, `750ml`, and `750ML` all select a `750ml` size.
+- If the value matches no size, the default size selection is used.
+
+`lce_size` is a fixed parameter name (not configured through a script attribute) and only applies to the product page.
+
 ### Fulfillment Types
 
 Two fulfillment options:
@@ -183,7 +197,7 @@ For products with multiple retailers:
 - Select with one tap
 
 **Popup View**
-- "Choose Retailer" button
+- "See Delivery Options" button (shows the available fulfillment count, e.g. "See Delivery Options (3)")
 - Modal with full retailer list
 - Filter and search capabilities
 
@@ -218,17 +232,38 @@ console.log(productData);
 // {
 //   identifier: '00619947000020',
 //   name: 'Premium Whiskey',
-//   price: 4999,
-//   selectedSize: { id: '750ml', upc: '00619947000020', ... },
+//   priceInfo: { currency: 'USD', minimum: 4999, average: 4999, maximum: 4999 },
+//   selectedSizeId: '750ml',
 //   selectedFulfillmentType: 'shipping',
-//   selectedRetailer: { id: 'retailer_123', name: 'Spirits Shop', ... },
-//   quantity: 1,
+//   selectedFulfillmentId: 'fulfillment_123',
+//   productHasAvailability: true,
+//   fulfillmentHasAvailability: true,
+//   sizes: { '750ml': { ... } },
 //   ...
 // }
 ```
 
 **Note:** The product must be injected and loaded before calling `getDetails()`. If the product hasn't been loaded, an error is thrown.
 
+### Get Product Availability by State
+
+Check availability for one or more products in a given state. Returns a `Promise<IProductAvailabilityResponse>`:
+
+```javascript
+const availability = await window.LiquidCommerce.elements.actions.product.getProductAvailabilityByState(
+  ['00619947000020', '08504405135'],
+  'NY'
+);
+
+console.log(availability);
+// {
+//   products: [...],
+//   retailers: { ... }
+// }
+```
+
+The `state` argument is optional; at least one product identifier is required.
+
 ## Events
 
 Listen for product-related events:
@@ -239,8 +274,8 @@ Fired when product data is successfully loaded:
 
 ```javascript
 window.addEventListener('lce:actions.product_loaded', (event) => {
-  const { identifier, name, price } = event.detail.data;
-  console.log(`Product loaded: ${name} - $${price / 100}`);
+  const { identifier, name, priceInfo } = event.detail.data;
+  console.log(`Product loaded: ${name} - $${priceInfo.minimum / 100}`);
 });
 ```
 
@@ -250,8 +285,8 @@ Fired when user clicks "Add to Cart":
 
 ```javascript
 window.addEventListener('lce:actions.product_add_to_cart', (event) => {
-  const { identifier, quantity, fulfillmentType } = event.detail.data;
-  console.log(`Adding ${quantity}x ${identifier} (${fulfillmentType})`);
+  const { identifier, quantity, fulfillmentId } = event.detail.data;
+  console.log(`Adding ${quantity}x ${identifier} (${fulfillmentId})`);
 });
 ```
 
@@ -261,8 +296,8 @@ Fired when user selects a different size:
 
 ```javascript
 window.addEventListener('lce:actions.product_size_changed', (event) => {
-  const { identifier, selectedSize, price } = event.detail.data;
-  console.log(`Size changed to ${selectedSize.name}: $${price / 100}`);
+  const { identifier, selectedSizeId, selectedSize } = event.detail.data;
+  console.log(`Size changed to ${selectedSize} (${selectedSizeId})`);
 });
 ```
 
@@ -272,8 +307,8 @@ Fired when user switches between shipping and on-demand:
 
 ```javascript
 window.addEventListener('lce:actions.product_fulfillment_type_changed', (event) => {
-  const { identifier, fulfillmentType } = event.detail.data;
-  console.log(`Fulfillment type changed to: ${fulfillmentType}`);
+  const { identifier, selectedFulfillmentType } = event.detail.data;
+  console.log(`Fulfillment type changed to: ${selectedFulfillmentType}`);
 });
 ```
 
@@ -283,8 +318,8 @@ Fired when user selects a different retailer:
 
 ```javascript
 window.addEventListener('lce:actions.product_fulfillment_changed', (event) => {
-  const { identifier, selectedRetailer, price } = event.detail.data;
-  console.log(`Retailer changed to ${selectedRetailer.name}: $${price / 100}`);
+  const { identifier, selectedFulfillmentId, selectedFulfillmentType } = event.detail.data;
+  console.log(`Fulfillment changed to ${selectedFulfillmentId} (${selectedFulfillmentType})`);
 });
 ```
 
@@ -397,7 +432,8 @@ await window.LiquidCommerce.elements.actions.address.setAddressManually(
     two: 'Apt 4',
     city: 'New York',
     state: 'NY',
-    zip: '10001'
+    zip: '10001',
+    country: 'US'
   },
   {
     latitude: 40.7128,
@@ -458,8 +494,9 @@ console.log(container); // <div id="product-1">...</div>
 If a product identifier doesn't exist:
 
 ```javascript
-// An error view is shown in the container
-// Console logs: [LiquidCommerce Elements] Product not found: invalid_id
+// An error view is shown in the container, and the store entry's `error`
+// is set to 'Product data not found'. In debug/logging mode the SDK warns:
+// "No product data found for the provided product IDs."
 ```
 
 ### No Availability
@@ -535,7 +572,7 @@ window.addEventListener('lce:actions.product_loaded', (event) => {
     items: [{
       item_id: event.detail.data.identifier,
       item_name: event.detail.data.name,
-      price: event.detail.data.price / 100
+      price: event.detail.data.priceInfo.minimum / 100
     }]
   });
 });

package/docs/v1/guides/product-list-component.md

@@ -39,7 +39,7 @@ Use data attributes to configure the product list:
 
 **Attributes:**
 - `data-liquid-commerce-elements-products-list`: Product list container; value is the collection slug
-- `data-rows`: Number of rows to display (default: 3)
+- `data-rows`: Number of rows to display (default: 4)
 - `data-columns`: Number of columns (default: 4)
 - `data-filters`: Comma-separated filter types
 - `data-product-url`: URL pattern for product detail pages (optional)
@@ -138,8 +138,8 @@ Only filter keys that are configured for the list are honored — anything else
 
 1. `data-filters` on `<div data-liquid-commerce-elements-products-list>` (use this when the page does **not** mount a filters UI but you still want URL filtering — e.g. a curated category page).
 2. `data-filters` on the matching `<... -products-list-filters>` container (the common case when a filters panel is mounted).
-3. `availableFilters` from the theme config for the list slug.
-4. `filters` array passed to `injectProductList(...)` programmatically.
+3. `filters` array passed to `injectProductList(...)` programmatically.
+4. `availableFilters` from the theme config for the list slug (fallback only).
 
 ### Supported formats
 
@@ -190,10 +190,9 @@ The search component provides full-text search across:
 
 ### Search Behavior
 
-- Real-time search as user types (debounced)
-- Minimum 2 characters to trigger search
-- Highlights matching terms in results
-- Shows result count
+- Real-time search as user types (500ms debounce; fires on any non-empty input — no minimum character count)
+- Input is limited to 100 characters; allowed characters: letters, numbers, spaces, and `- _ ' . , & ( )`
+- Server-side filtering by the search term
 - "Clear search" button appears when active
 
 ### Programmatic Search
@@ -262,7 +261,7 @@ Each product card shows:
 - Brand
 - Price (or price range for multiple sizes)
 - Rating (if available)
-- "Quick View" or "View Details" button
+- Clickable image/card linking to the product detail page (when `productUrl` is configured)
 - "Add to Cart" button (optional)
 - Availability indicator
 
@@ -619,7 +618,7 @@ await client.injectProductList({
 
 ### Search Not Finding Products
 
-1. Verify minimum character count is met (2 chars)
+1. Verify the input uses allowed characters and is under the 100-character limit
 2. Check search is not case-sensitive (it shouldn't be)
 3. Ensure products have searchable text fields
 4. Look for API errors in network tab

package/docs/v1/guides/theming.md

@@ -77,8 +77,7 @@ customTheme: {
       personalizationCardStyle: 'outlined',  // or 'filled'
       allowPromoCodes: true,
       inputFieldStyle: 'outlined',  // or 'filled'
-      showPoweredBy: true,
-      poweredByMode: 'light'  // or 'dark'
+      poweredByMode: 'light'  // or 'dark'  (note: showPoweredBy is controlled server-side and cannot be overridden via customTheme)
     }
   }
 }
@@ -152,16 +151,15 @@ customTheme: {
         text: 'Receive SMS updates about your order and exclusive deals.'
       },
       allowGiftCards: true,
-      legalMessage: 'By placing your order, you agree to our Terms of Service and Privacy Policy.',
+      legalMessage: { show: true, text: 'By placing your order, you agree to our Terms of Service and Privacy Policy.' },
       continueShoppingUrl: 'https://yoursite.com/shop',
       exitUrl: 'https://yoursite.com',
       thankYouButtonText: 'Continue Shopping',
       drawerHeaderText: 'Checkout',
       placeOrderButtonText: 'Place Order',
       checkoutCompleted: {
-          customLogo: 'https://yoursite.com/logo.png',
-          customText: 'Thank you for your purchase! Your order has been received.'
-        }
+        customLogo: 'https://yoursite.com/logo.png',
+        customText: 'Thank you for your purchase! Your order has been received.'
       }
     }
   }
@@ -191,8 +189,7 @@ const client = await Elements('YOUR_API_KEY', {
       },
       layout: {
         allowPromoCodes: true,
-        inputFieldStyle: 'outlined',
-        showPoweredBy: false
+        inputFieldStyle: 'outlined'
       }
     },
     product: {
@@ -203,7 +200,7 @@ const client = await Elements('YOUR_API_KEY', {
     },
     cart: {
       layout: {
-        checkoutButtonText: 'Checkout Now'
+        goToCheckoutButtonText: 'Checkout Now'
       }
     }
   }

package/docs/v1/integration/proxy-setup.md

@@ -12,7 +12,12 @@ import { Elements } from '@liquidcommerce/elements-sdk';
 const client = await Elements('YOUR_API_KEY', {
   env: 'production',
   proxy: {
-    baseUrl: 'https://yoursite.com/api/elements-proxy'
+    // Must be an ABSOLUTE URL ending with a trailing slash — the SDK resolves
+    // each request as `new URL('api' + path, baseUrl)`, so a missing trailing
+    // slash drops the last path segment.
+    baseUrl: 'https://yoursite.com/api/elements-proxy/',
+    // Optional: extra headers merged into every proxied request (e.g. credentials)
+    headers: { 'X-My-Auth': '...' }
   }
 });
 ```
@@ -30,7 +35,8 @@ export default function ProductPage() {
     (async () => {
       const client = await Elements('YOUR_API_KEY', {
         env: 'production',
-        proxy: { baseUrl: '/api/elements-proxy' }
+        // Absolute URL with a trailing slash (see note above)
+        proxy: { baseUrl: 'https://yoursite.com/api/elements-proxy/' }
       });
 
       await client.injectProductElement([
@@ -47,6 +53,8 @@ export default function ProductPage() {
 
 Your endpoint should forward requests to the LiquidCommerce Elements API, preserving method, headers, and body.
 
+The SDK does not hardcode the upstream host in the proxy path. Instead, it sends the correct environment-specific upstream base URL in the `X-Liquid-Proxy-Target` request header (along with `X-Liquid-Proxy: true`). Forward to that header value rather than to a literal host — this keeps the proxy environment-agnostic. The SDK calls your proxy at `<baseUrl>/api/<endpoint>`, so the path captured after your proxy mount is exactly the `api/<endpoint>` to append to the target.
+
 ### Minimal Express Example
 
 ```javascript
@@ -56,15 +64,24 @@ import fetch from 'node-fetch';
 const app = express();
 app.use(express.json());
 
+// Proxy is mounted at the path of your proxy.baseUrl ('/api/elements-proxy/').
 app.all('/api/elements-proxy/*', async (req, res) => {
-  const targetPath = req.params[0];
-  const targetUrl = `https://api.liquidcommerce.us/${targetPath}`;
+  // Upstream base URL the SDK wants this request forwarded to
+  // (e.g. https://elements-services-production-948630220003.us-central1.run.app)
+  const upstream = req.headers['x-liquid-proxy-target'];
+  if (!upstream) {
+    return res.status(400).send('Missing X-Liquid-Proxy-Target header');
+  }
+
+  // Everything after the proxy mount, e.g. 'api/auth/authenticate'
+  const forwardedPath = req.params[0];
+  const targetUrl = `${upstream}/${forwardedPath}`;
 
   const response = await fetch(targetUrl, {
     method: req.method,
     headers: {
       ...req.headers,
-      host: 'api.liquidcommerce.us'
+      host: new URL(upstream).host
     },
     body: ['GET', 'HEAD'].includes(req.method) ? undefined : JSON.stringify(req.body)
   });

package/docs/v1/reference/browser-support.md

@@ -15,7 +15,8 @@ The Elements SDK requires modern browser features (Web Components + Shadow DOM).
 - Shadow DOM
 - ES2018 JavaScript
 - Fetch API
-- LocalStorage
+
+**LocalStorage (optional, recommended):** used as a fast path for session persistence (cart/address). When unavailable (incognito, Safari/Firefox private mode, in-app webviews, cross-origin iframes), the SDK falls back to a generated device fingerprint plus server-side session persistence, so functionality is preserved.
 
 ## Server-Side Rendering (SSR)
 

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

@@ -19,9 +19,9 @@ class SDKError extends Error {
 
 ```javascript
 try {
-  await window.LiquidCommerce.elements.injectProductElement([
-    { containerId: 'product', identifier: 'invalid_id' }
-  ]);
+  // Structural input errors throw a catchable SDKError — e.g. a non-array
+  // argument or an empty array:
+  await window.LiquidCommerce.elements.injectProductElement([]);
 } catch (error) {
   if (error.name === 'SDKError') {
     console.error('SDK Error:', error);
@@ -29,13 +29,18 @@ try {
 }
 ```
 
+> A well-formed entry with an invalid product identifier does **not** throw — it renders an error view inside the component and sets an error in the store. `try/catch` here only catches structural input errors (a non-array argument or an empty array).
+
 ## Error Isolation
 
-The SDK catches and contains its own errors so your app keeps running:
+Component failures are contained — a component that fails to load renders an error view and logs to the console without crashing your page. Action methods (like `cart.addProduct`) emit a `*_FAILED` event on failure, and re-throw only on an unexpected error; several soft-failure paths (e.g. no product found, no items added) emit the failure event but still resolve. Wrap calls in try/catch **and** listen for the corresponding `*_failed` event to reliably detect failures:
 
 ```javascript
-window.LiquidCommerce.elements.actions.cart.addProduct([/* invalid */]);
-console.log('App still working');
+try {
+  await window.LiquidCommerce.elements.actions.cart.addProduct([/* invalid */]);
+} catch (error) {
+  console.log('Handled add-to-cart failure');
+}
 ```
 
 ## Error Events
@@ -55,7 +60,7 @@ window.addEventListener('lce:actions.address_failed', (event) => {
 
 // Checkout submit failed
 window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
-  console.error('Checkout failed:', event.detail.data.error);
+  console.error('Checkout failed:', event.detail.data.message);
 });
 ```
 

package/docs/v1/reference/performance.md

@@ -44,9 +44,7 @@ setTimeout(async () => {
 ## 5) Let the SDK Handle Media Optimization
 
 The SDK automatically:
-- Lazy loads images
-- Uses responsive image sizes
-- Virtualizes carousel images
+- Lazy loads carousel/thumbnail images (native `loading="lazy"`)
 
 ## Related Docs
 

package/docs/v1/reference/troubleshooting.md

@@ -60,7 +60,7 @@ Common setup issues and how to resolve them.
 
 **Symptoms:** Console warning "This SDK is designed for the browser. Calls made during SSR return null."
 
-This is expected behavior. The SDK ships an SSR stub that is automatically resolved when bundled for Node.js (via the `node` export condition in `package.json`). The stub exports all types and enums for TypeScript compatibility and returns `null` from factory functions (`Elements`, `ElementsBuilder`, `ElementsCheckout`).
+This is expected behavior. The SDK ships SSR stubs that are automatically resolved when bundled for Node.js (via the `node` export condition in `package.json`). There are two: the main build's stub (the `.` export) provides `Elements` and `ElementsBuilder` and warns with the `[LiquidCommerce Elements]` prefix; the checkout build's stub (the `./checkout` export) provides `ElementsCheckout` and warns with the `[LiquidCommerce Checkout]` prefix. Both re-export their types and enums for TypeScript compatibility and return `null` from the factory functions.
 
 **No action required** — initialize the SDK in a client-only lifecycle hook (`useEffect`, `onMounted`, etc.) and the real client will activate in the browser.
 
@@ -72,8 +72,8 @@ This is expected behavior. The SDK ships an SSR stub that is automatically resol
 
 **Fixes:**
 - Use `customTheme` in the client configuration to style components -- external CSS cannot penetrate Shadow DOM.
-- For debugging, enable `development.openShadowDom: true` to disable Shadow DOM temporarily.
-- Use the debug panel (`debugMode: 'panel'`) to inspect component state.
+- For debugging, enable `development.openShadowDom: true` to make the shadow root open (`mode: 'open'`) so you can inspect component internals in DevTools (via `element.shadowRoot`). This does **not** disable style isolation — external CSS still cannot reach the components; use `customTheme` to style them. (Forced off in production.)
+- Use the debug panel (`debugMode: 'panel'`) to inspect SDK logs, events, and GTM activity in real time — it surfaces a live stream of logger output and pubsub/GTM events (not component internal state), and auto-enables only in non-production environments.
 
 ## Component Not Updating After Data Changes
 

package/package.json

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.6.0-beta.84",
+  "version": "2.6.0-beta.86",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",
@@ -14,7 +14,7 @@
   },
   "module": "./dist/index.esm.js",
   "types": "./dist/types/index.d.ts",
-  "packageManager": "pnpm@10.33.4",
+  "packageManager": "pnpm@11.8.0",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
@@ -77,7 +77,7 @@
     "embeddable commerce"
   ],
   "devDependencies": {
-    "@biomejs/biome": "^2.4.16",
+    "@biomejs/biome": "^2.5.0",
     "@commitlint/cli": "^21.0.2",
     "@commitlint/config-conventional": "^21.0.2",
     "@rollup/plugin-alias": "^6.0.0",
@@ -93,27 +93,18 @@
     "@semantic-release/npm": "^13.1.5",
     "@semantic-release/release-notes-generator": "^14.1.1",
     "@types/core-js": "^2.5.8",
-    "@types/node": "^25.9.1",
-    "conventional-changelog": "^7.2.0",
+    "@types/node": "^26.0.0",
+    "conventional-changelog": "^7.2.1",
     "husky": "^9.1.7",
     "process": "^0.11.10",
-    "rollup": "^4.61.0",
+    "rollup": "^4.62.2",
     "rollup-obfuscator": "^4.1.1",
     "rollup-plugin-typescript2": "^0.37.0",
-    "semantic-release": "^25.0.3",
+    "semantic-release": "^25.0.5",
     "ts-node": "^10.9.2",
-    "typescript": "5.9.3"
+    "typescript": "6.0.3"
   },
   "engines": {
     "node": ">=22"
-  },
-  "pnpm": {
-    "peerDependencyRules": {
-      "ignoreMissing": []
-    },
-    "onlyBuiltDependencies": [
-      "@biomejs/biome",
-      "javascript-obfuscator"
-    ]
   }
 }