npm - @liquidcommerce/elements-sdk - Versions diffs - 2.6.0-beta.1 → 2.6.0-beta.100 - Mend

@liquidcommerce/elements-sdk 2.6.0-beta.1 → 2.6.0-beta.100

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (274) hide show

package/docs/v1/reference/analytics.md ADDED Viewed

@@ -0,0 +1,108 @@
+# Analytics & Google Tag Manager
+The SDK ships with a built-in Google Tag Manager (GTM) / Google Analytics 4 (GA4) integration. It automatically pushes GA4 ecommerce events for the interactions your shoppers perform in Elements components — product views, cart changes, checkout steps, purchases, and more.
+This runs entirely inside the SDK. In most cases you do not need to configure or code anything.
+## What You Need To Do
+**Typically nothing.** The integration is automatic in production and staging. The SDK receives its GTM container configuration from the LiquidCommerce platform (per partner) and initializes itself after the DOM is ready.
+It coexists with a host site's own GTM — see [Coexisting With Your Own GTM](#coexisting-with-your-own-gtm) below.
+## Supported Environments
+GTM initialization and every event push are enabled in production and staging. When the SDK is running in development or Builder mode, no container is loaded and no events are sent.
+Events are suppressed when any of the following is true:
+- `window` is undefined (server-side rendering).
+- The SDK is running in Builder mode.
+- The environment is `development`.
+The environment defaults to `production` when none is provided, so a standard production embed is analytics-enabled out of the box; a staging embed is also analytics-enabled when server GTM config is enabled for the partner.
+## How It Works
+### Container injection
+When enabled, the SDK injects the GTM container script:
+```
+https://www.googletagmanager.com/gtm.js?id=<containerId>
+```
+The script is appended to `<head>` with `async` and `crossorigin="anonymous"`, and the SDK waits for GTM to initialize before flushing events.
+### dataLayer and gtag
+The SDK initializes the standard GTM globals **without clobbering an existing setup**:
+- `window.dataLayer` is created only if it does not already exist.
+- `window.gtag` is defined only if it is not already present.
+Events are delivered using Google's recommended `window.dataLayer.push()` pattern.
+### Event queueing
+Events fired before GTM finishes initializing are queued (up to 100, oldest dropped first) and flushed once the container is ready. Queued events older than 30 seconds at flush time are discarded.
+## Coexisting With Your Own GTM
+The SDK detects an already-present partner/host GTM container rather than replacing it. When a host GTM install (an existing `gtag` function or an existing `googletagmanager.com/gtm.js` script tag) is detected, the SDK integrates with it.
+When both the LiquidCommerce container and a partner container are initialized, events are sent to both using GA4's `send_to` targeting (a dual-container send). Only containers that are actually initialized are added to `send_to`, so events are never routed to a container that failed to load.
+If the LiquidCommerce container can't be loaded, the SDK falls back — in order — to the partner container, any initialized GTM container on the page, or the basic `dataLayer` — so event tracking degrades gracefully instead of failing.
+## Source Tracking (`tenant_*`)
+Every event automatically carries source-tracking fields identifying the tenant and the SDK build:
+| Field | Value |
+| --- | --- |
+| `tenant_name` | Partner name |
+| `tenant_code` | Partner code |
+| `tenant_env` | SDK environment |
+| `tenant_source` | SDK package description and version |
+## Events
+All events are GA4-shaped and follow the standard ecommerce schema (`items[]`, `value`, `currency` — the SDK uses `USD`, `coupon`, etc.).
+### Standard GA4 ecommerce events
+| Event | Fired when |
+| --- | --- |
+| `view_item` | A shopper views a product |
+| `view_item_list` | A shopper views a list of products |
+| `select_item` | A shopper selects a product from a list |
+| `add_to_cart` | A shopper adds an item to the cart |
+| `view_cart` | A shopper views the cart |
+| `remove_from_cart` | A shopper removes an item from the cart |
+| `begin_checkout` | A shopper begins checkout |
+| `add_shipping_info` | Shipping info is added during checkout |
+| `add_payment_info` | Payment info is added during checkout |
+| `purchase` | A purchase completes |
+### Custom events
+| Event | Fired when |
+| --- | --- |
+| `promo_code_attempt` | A promo code is submitted |
+| `promo_code_applied` | A promo code is successfully applied |
+| `promo_code_failed` | A promo code fails to apply |
+| `gift_card_attempt` | A gift card is submitted |
+| `gift_card_applied` | A gift card is successfully applied |
+| `gift_card_failed` | A gift card fails to apply |
+| `address_updated` | An address is successfully updated |
+| `address_failed` | An address operation fails |
+| `product_no_availability` | A product has no availability for any size/fulfillment |
+| `product_size_no_availability` | A selected size has no availability |
+| `product_fulfillment_no_availability` | A selected fulfillment type has no availability |
+## Related Docs
+- [Events Guide](../guides/events.md)
+- [Client API](../api/client.md)
+- [Troubleshooting](./troubleshooting.md)

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

@@ -0,0 +1,47 @@
+# Browser Support
+The Elements SDK requires modern browser features (Web Components + Shadow DOM). If you need to support older browsers, include polyfills.
+## Minimum Versions
+- Chrome 66+
+- Firefox 60+
+- Safari 12+
+- Edge 79+
+## Required Features
+- Custom Elements (Web Components)
+- Shadow DOM
+- ES2018 JavaScript
+- Fetch API
+**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)
+The SDK is browser-only, but it is safe to import in SSR frameworks (Next.js, Remix, Nuxt).
+In non-browser environments, initialization is skipped. If you call the SDK on the server,
+it returns `null` and logs a warning instead of throwing.
+Call `Elements`, `ElementsCheckout`, or `ElementsBuilder` from client-only code (e.g., after mount)
+to render components. `Elements` and `ElementsBuilder` resolve to no-op stubs from the main SSR
+entry; `ElementsCheckout` ships in its own tree-shaken entry with a separate stub, so it is safe to
+import even if you never use the other two.
+## Polyfills (Legacy Browsers)
+```html
+<script src="https://cdn.jsdelivr.net/npm/@webcomponents/webcomponentsjs@2/webcomponents-bundle.js"></script>
+<script defer data-liquid-commerce-elements ...></script>
+```
+## Notes
+- Always load the SDK script with `defer` to avoid blocking page render.
+- If you see Web Components errors in the console, add the polyfill before the SDK.
+## Related Docs
+- [Installation](../getting-started/installation.md)
+- [Troubleshooting](./troubleshooting.md)

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

@@ -0,0 +1,83 @@
+# 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 {
+  // 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);
+  }
+}
+```
+> 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 malformed input: a missing or non-string `identifier`, a `fulfillmentType` other than `shipping`/`onDemand`, or a `quantity` below 1. An **empty array logs a warning and resolves** — it does not throw and emits no event.
+## Error Isolation
+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
+try {
+  await window.LiquidCommerce.elements.actions.cart.addProduct([/* invalid */]);
+} catch (error) {
+  console.log('Handled add-to-cart failure');
+}
+```
+## 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.message);
+});
+```
+## UI Errors
+When a component fails to load, the SDK renders an error view inside the container and logs details to the console.
+## Global Error Interception
+On load, the SDK installs its own global handlers by reassigning `window.onerror` and `window.onunhandledrejection`. Each incoming error or rejection is classified by an `isSDKError` heuristic that inspects the error's message, stack, and source — matching a script `src` ending in `/elements.js`, known SDK class and directory patterns, and an `isSdk` flag on `SDKError` instances.
+When an error is classified as SDK-originated, the handler logs it to the console and returns `true` (for `onerror`) or calls `event.preventDefault()` (for `onunhandledrejection`), so the error is swallowed and never reaches your app. Errors that are not classified as SDK-originated are chained to any handler that was already installed before the SDK loaded.
+> **Implications:** SDK-originated errors are intentionally suppressed and will **not** surface in your host error monitoring (e.g. Sentry). Conversely, the heuristic is pattern-based and can occasionally match a non-SDK error, causing it to be swallowed too. If you rely on catching failures, use the `*_failed` events and `try/catch` described above rather than global error monitoring.
+## Related Docs
+- [Events Guide](../guides/events.md)
+- [Client API](../api/client.md)
+- [Troubleshooting](./troubleshooting.md)

package/docs/v1/reference/performance.md ADDED Viewed

@@ -0,0 +1,52 @@
+# 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 carousel/thumbnail images (native `loading="lazy"`)
+## Related Docs
+- [Best Practices](../guides/best-practices.md)
+- [Product Component](../guides/product-component.md)

package/docs/v1/reference/telemetry.md ADDED Viewed

@@ -0,0 +1,85 @@
+# Telemetry & Privacy
+The SDK includes lightweight, privacy-conscious telemetry that reports errors and warnings back to LiquidCommerce so the platform can detect and fix production issues. This page is a full disclosure of **what** is collected, **when**, **where** it is sent, and **how to turn it off**.
+Telemetry never blocks or breaks your page — capture and sending are wrapped so internal failures are swallowed silently.
+## When It Is Enabled
+Telemetry is enabled **only** when both conditions are true:
+- The SDK is running in the **production** environment (`env === 'production'`), and
+- **No custom API URL is configured** (`hasCustomApiUrl` is `false`).
+In every other case it is **disabled** and no events are queued or sent:
+- Non-production environments (e.g. staging/development).
+- A custom API URL / proxy is configured via `development.customApiUrl`.
+- Internal telemetry errors are only logged to the console in non-production or when debugging is enabled — never sent.
+## What Is Collected
+Each event carries the message, severity level, and timestamp, plus three context blocks.
+**Browser context**
+- `userAgent` — the browser user-agent string
+- `url` — the full current page URL (`window.location.href`)
+- `referrer` — the referring URL, if any
+- `timezone` — the resolved IANA timezone (e.g. `America/New_York`)
+- `deviceType` — device classification (desktop/mobile/tablet)
+**User context**
+- `deviceId` — the SDK-generated device id (falls back to `not_defined`)
+- `isLocalStorageAvailable` — whether localStorage is usable
+- `selectedAddress` — the user's currently selected **formatted address string**, if one is set
+**SDK context**
+- `version`, `env`, `isBuilder`, and `partnerCode`
+**Errors** (when the event represents one) include the error `name`, `message`, `code`, and a stack trace **truncated to the first 10 lines**.
+Only **warnings** and **errors/fatal** events are captured. Debug/log/info events are excluded by default (`includeDebugLogs: false`).
+## Where It Is Sent
+Events are **batched** and sent to:
+```
+<baseUrl>/api/telemetry
+```
+`baseUrl` is the SDK's configured API host. Because telemetry is disabled whenever a custom API URL is set, events are only ever sent to LiquidCommerce's own endpoint — never to a partner proxy.
+Batches are delivered with `navigator.sendBeacon`, falling back to a **synchronous `XMLHttpRequest`** if sendBeacon is unavailable or fails. Payloads are sent as `text/plain`.
+Batches flush:
+- When the queue reaches the batch size (5 events in production),
+- On a periodic timer (every 5s in production), and
+- On page teardown (`beforeunload` / `pagehide`), so pending events are not lost.
+The queue is capped (max 50 events); oldest events are dropped first if it overflows.
+## Disabling Telemetry
+There is no separate opt-out flag — telemetry follows the two conditions above. To ensure it never runs, do either of the following:
+- Run the SDK in a **non-production** environment, or
+- Configure a **custom API URL** so events are routed through your own infrastructure and SDK telemetry is switched off:
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  development: {
+    customApiUrl: 'https://your-proxy.example.com'
+  }
+});
+```
+## Related Docs
+- [Error Handling](./error-handling.md)
+- [Client API](../api/client.md)
+- [Troubleshooting](./troubleshooting.md)

package/docs/v1/reference/troubleshooting.md ADDED Viewed

@@ -0,0 +1,135 @@
+# Troubleshooting
+Common setup issues and how to resolve them.
+## SDK Script Not Loading
+**Symptoms:** 404/CORS in Network tab, `window.LiquidCommerce.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.LiquidCommerce.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.
+## SSR / Server-Side Rendering
+**Symptoms:** Console warning "This SDK is designed for the browser. Calls made during SSR return null."
+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.
+## Styling Not Applied / CSS Not Working
+**Symptoms:** Components render but custom styles are ignored, or host page styles leak into components.
+**Cause:** Components use Shadow DOM for style isolation.
+**Fixes:**
+- Use `customTheme` in the client configuration to style components -- external CSS cannot penetrate Shadow DOM.
+- 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
+**Symptoms:** Component shows stale data after an action completes.
+**Fixes:**
+- Call `.rerender()` on the injected component to force a refresh:
+  ```javascript
+  const components = client.getInjectedComponents();
+  components.get('product-1')?.rerender();
+  ```
+- Ensure you're not holding a stale reference -- call `getInjectedComponents()` again after injection.
+## Cleanup / Memory Leaks
+**Symptoms:** Components persist after navigating away in SPA, or duplicate components appear.
+**Fixes:**
+- Call `destroy()` on individual injected components when removing them:
+  ```javascript
+  const component = client.getInjectedComponents().get('product-1');
+  component?.destroy();
+  ```
+- Call `client.destroy()` when tearing down the entire SDK (e.g., on SPA route change).
+## Promo Ticker Not Showing
+**Symptoms:** Promo ticker is configured but not visible.
+**Fixes:**
+- Verify all 5 required fields are set: `promoCode`, `text`, `separator`, `activeFrom`, `activeUntil`.
+- Check that the current time falls between `activeFrom` and `activeUntil` (ISO 8601 UTC format). The ticker only renders when at least one configured ticker is currently active — the active window is evaluated against the shopper's timezone (derived from the current address state, falling back to the browser timezone), so a ticker with a valid but out-of-window range will not appear.
+## Ad Blockers Blocking SDK Requests
+**Symptoms:** Network requests fail, products don't load, but no code errors.
+**Fixes:**
+- Set up a proxy to route API requests through your own domain:
+  ```javascript
+  proxy: { baseUrl: 'https://yoursite.com/api/elements-proxy' }
+  ```
+- See [Proxy Setup Guide](../integration/proxy-setup.md) for server-side implementation.
+## Performance Issues on Large Product Lists
+**Symptoms:** Slow rendering or high memory usage with many products.
+**Fixes:**
+- Reduce `rows` and `columns` to load fewer products per page.
+- Limit the number of active filters.
+- Use the checkout-only build on checkout pages to reduce bundle size.
+## Related Docs
+- [Installation](../getting-started/installation.md)
+- [Browser Support](./browser-support.md)
+- [Error Handling](./error-handling.md)
+- [Proxy Setup](../integration/proxy-setup.md)