@liquidcommerce/elements-sdk 2.6.0-beta.93 → 2.6.0-beta.95

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 (50) hide show
  1. package/dist/index.checkout.esm.js +7862 -7146
  2. package/dist/index.esm.js +12759 -11541
  3. package/dist/types/core/a11y/announcer.service.d.ts +16 -0
  4. package/dist/types/core/a11y/focus-manager.service.d.ts +21 -0
  5. package/dist/types/core/a11y/focusable.d.ts +5 -0
  6. package/dist/types/core/a11y/index.d.ts +3 -0
  7. package/dist/types/core/base-component.service.d.ts +2 -0
  8. package/dist/types/core/google-tag-manager.service.d.ts +1 -0
  9. package/dist/types/interfaces/configs/global.interface.d.ts +2 -0
  10. package/dist/types/modules/address/address-input.component.d.ts +10 -1
  11. package/dist/types/modules/cart/components/cart-body.component.d.ts +1 -0
  12. package/dist/types/modules/cart/components/cart-item-quantity-price.component.d.ts +5 -0
  13. package/dist/types/modules/cart/components/cart-item.component.d.ts +6 -0
  14. package/dist/types/modules/checkout/components/checkout-completed.component.d.ts +2 -0
  15. package/dist/types/modules/checkout/components/checkout-item-quantity.component.d.ts +1 -0
  16. package/dist/types/modules/checkout/components/checkout-payment.component.d.ts +1 -0
  17. package/dist/types/modules/checkout/components/checkout-place-order-button.component.d.ts +2 -0
  18. package/dist/types/modules/product/components/product-drawer.component.d.ts +6 -0
  19. package/dist/types/modules/product/product.commands.d.ts +2 -2
  20. package/dist/types/modules/product-list/components/card-components/product-price-and-personalization.d.ts +2 -1
  21. package/dist/types/modules/product-list/components/card-components/product-sizes-list.d.ts +1 -0
  22. package/dist/types/modules/product-list/components/filter-components/product-list-fulfillment-filter.d.ts +1 -0
  23. package/dist/types/modules/product-list/components/product-list-filters.component.d.ts +1 -0
  24. package/dist/types/modules/product-list/components/product-list-product-pre-cart.component.d.ts +2 -0
  25. package/dist/types/modules/product-list/product-list.commands.d.ts +1 -1
  26. package/dist/types/modules/product-list/product-list.component.d.ts +3 -0
  27. package/dist/types/modules/ui-components/alert/alert.component.d.ts +1 -1
  28. package/dist/types/modules/ui-components/buttons/buttons-open-cart.component.d.ts +5 -0
  29. package/dist/types/modules/ui-components/drawer/drawer.component.d.ts +14 -0
  30. package/dist/types/modules/ui-components/engraving/engraving-form.component.d.ts +2 -0
  31. package/dist/types/modules/ui-components/engraving/engraving-view.component.d.ts +1 -0
  32. package/dist/types/modules/ui-components/input/input.component.d.ts +4 -0
  33. package/dist/types/modules/ui-components/ui.commands.d.ts +3 -1
  34. package/docs/v1/api/actions/cart-actions.md +9 -2
  35. package/docs/v1/api/actions/checkout-actions.md +2 -0
  36. package/docs/v1/api/client.md +84 -6
  37. package/docs/v1/api/configuration.md +10 -0
  38. package/docs/v1/api/typescript-types.md +5 -1
  39. package/docs/v1/getting-started/concepts.md +5 -3
  40. package/docs/v1/getting-started/installation.md +22 -1
  41. package/docs/v1/guides/cart-component.md +32 -0
  42. package/docs/v1/guides/product-component.md +6 -2
  43. package/docs/v1/guides/product-list-component.md +4 -5
  44. package/docs/v1/guides/theming.md +10 -0
  45. package/docs/v1/reference/analytics.md +108 -0
  46. package/docs/v1/reference/browser-support.md +3 -1
  47. package/docs/v1/reference/error-handling.md +8 -0
  48. package/docs/v1/reference/telemetry.md +85 -0
  49. package/docs/v1/reference/troubleshooting.md +1 -2
  50. package/package.json +44 -15
@@ -178,6 +178,8 @@ interface IInjectCheckoutParams {
178
178
 
179
179
  ### IInjectCheckoutBuilderParams
180
180
 
181
+ `simulatePresale` and `presaleExpiresInMinutes` are builder-only preview controls (presale lock defaults to 15 minutes) and only take effect via `ElementsBuilder().injectCheckoutElement()`.
182
+
181
183
  ```typescript
182
184
  interface IInjectCheckoutBuilderParams extends IInjectCheckoutParams {
183
185
  simulatePresale?: boolean;
@@ -293,7 +295,7 @@ interface ILiquidCommerceElementsActions {
293
295
 
294
296
  ### IElementsCheckoutActions
295
297
 
296
- Checkout actions available in the checkout-only client. Omits drawer-related methods.
298
+ Checkout actions available in the checkout-only client. This is `ICheckoutActions` with `openCheckout`, `closeCheckout`, and `toggleCheckout` omitted -- the checkout-only client renders checkout independently and has no drawer navigation to open, close, or toggle.
297
299
 
298
300
  ```typescript
299
301
  interface IElementsCheckoutActions extends Omit<ICheckoutActions, 'openCheckout' | 'closeCheckout' | 'toggleCheckout'> {}
@@ -378,6 +380,8 @@ interface UpdateProductListComponent {
378
380
  }
379
381
  ```
380
382
 
383
+ These `Update*Component` types are the arguments to the `ElementsBuilder()` client's `update*Component` methods; see [Client API](./client.md) for their behavior and usage.
384
+
381
385
  See [Configuration Reference](./configuration.md) for detailed theme property descriptions.
382
386
 
383
387
  ---
@@ -96,11 +96,11 @@ The SDK uses a two-phase initialization strategy for optimal performance:
96
96
  - Store initialization
97
97
  - Theme setup
98
98
  - Core component registration
99
- - Telemetry / logger wiring
99
+ - Telemetry / logger wiring (see [Telemetry & Privacy](../reference/telemetry.md))
100
100
  - Debug panel (if enabled)
101
101
 
102
102
  **Phase 2: Deferred Services (next macrotask, via `setTimeout(…, 0)`)**
103
- - Analytics (Google Tag Manager)
103
+ - Analytics (Google Tag Manager — see [Analytics (GTM/GA4)](../reference/analytics.md))
104
104
  - Cart pre-loading
105
105
  - Heavy component registration
106
106
 
@@ -368,10 +368,12 @@ const client = await Elements('YOUR_API_KEY', {
368
368
  ```
369
369
 
370
370
  **Debug Modes:**
371
- - `'none'` - No debug output (production default)
371
+ - `'none'` - No debug output (default)
372
372
  - `'console'` - Log to browser console
373
373
  - `'panel'` - Show debug panel on page
374
374
 
375
+ > **Production note:** `debugMode` has no effect when `env` is `'production'`. All debug output — console logging and the debug panel — is disabled in production regardless of the `debugMode` you pass. `'console'` and `'panel'` only take effect in non-production environments.
376
+
375
377
  ## Security & API Keys
376
378
 
377
379
  ### API Key Protection
@@ -30,6 +30,16 @@ Add the following script tag to your page's `<head>` section:
30
30
  ></script>
31
31
  ```
32
32
 
33
+ > **Note:** The host `elements.reservebar-worker.workers.dev` shown above is an example, partner-specific endpoint. Use the CDN URL provided by your LiquidCommerce representative in place of this host.
34
+
35
+ The path segment selects which bundle is served:
36
+
37
+ | Path | Bundle |
38
+ |------|--------|
39
+ | `/all/elements.js` | Full SDK bundle (product, cart, checkout, and all other elements) |
40
+ | `/checkout/elements.js` | Checkout-only bundle (tree-shaken, smaller) |
41
+ | `/all/beta/elements.js` | Beta channel of the full SDK bundle |
42
+
33
43
  ### Script Attributes
34
44
 
35
45
  | Attribute | Required | Description |
@@ -140,7 +150,16 @@ const config: ILiquidCommerceElementsConfig = {
140
150
  }
141
151
  };
142
152
 
143
- const client: ILiquidCommerceElementsClient = await Elements('YOUR_API_KEY', config);
153
+ // Elements() returns `null` in SSR / non-browser environments, so the
154
+ // client is typed as `ILiquidCommerceElementsClient | null`.
155
+ const client: ILiquidCommerceElementsClient | null = await Elements('YOUR_API_KEY', config);
156
+
157
+ if (client) {
158
+ // Safe to use the client here
159
+ client.injectProductElement([
160
+ { containerId: 'product-1', identifier: '00619947000020' }
161
+ ]);
162
+ }
144
163
  ```
145
164
 
146
165
  ## Framework Integration
@@ -255,6 +274,8 @@ const client = await Elements('YOUR_API_KEY', {
255
274
  });
256
275
  ```
257
276
 
277
+ > **Note:** `debugMode` is ignored when `env` is `'production'`. Debug logging and the debug panel are only activated in non-production environments (`development` or `staging`).
278
+
258
279
  See [Configuration Reference](../api/configuration.md) for complete configuration options.
259
280
 
260
281
  ## Verification
@@ -6,6 +6,7 @@ The Cart component provides a slide-out drawer for managing shopping cart items,
6
6
 
7
7
  The Cart component automatically:
8
8
  - Displays cart items with images and details
9
+ - Removes white / near-white backgrounds from item images so products blend into the drawer (automatic, not host-configurable)
9
10
  - Groups items by retailer
10
11
  - Shows real-time pricing and totals
11
12
  - Supports quantity updates
@@ -342,6 +343,17 @@ window.addEventListener('lce:actions.cart_item_quantity_decrease', (event) => {
342
343
  });
343
344
  ```
344
345
 
346
+ ### Engraving Updated
347
+
348
+ Fired when a cart line item's engraving is added or edited from the drawer (see [Engraving](#engraving)):
349
+
350
+ ```javascript
351
+ window.addEventListener('lce:actions.cart_item_engraving_updated', (event) => {
352
+ const { cartId, itemId, engravingLines, previousEngravingLines } = event.detail.data;
353
+ console.log(`Engraving updated for ${itemId}:`, engravingLines);
354
+ });
355
+ ```
356
+
345
357
  ### Promo Code Events
346
358
 
347
359
  ```javascript
@@ -546,6 +558,26 @@ Items are automatically grouped by retailer in the cart:
546
558
  └─────────────────────────────────────┘
547
559
  ```
548
560
 
561
+ ## Order Minimums
562
+
563
+ Retailers can require a minimum purchase amount before their items can be checked out. The cart enforces this per retailer:
564
+
565
+ - When a retailer's minimum is not met, the cart drawer shows a per-retailer alert reading `+$X needed for order minimum`, where `$X` is the remaining amount required for that retailer.
566
+ - The **Checkout** button is disabled until every retailer's minimum is met. (It is also disabled while the cart is loading/updating or when the cart is empty.)
567
+
568
+ No configuration is required — the minimums are defined by each retailer and enforced automatically.
569
+
570
+ ## Engraving
571
+
572
+ For engravable items, shoppers can add or edit engraving directly from a cart line item, without leaving the drawer.
573
+
574
+ - If an engravable item has no engraving yet, the line item shows an **Add personalization** action (with the engraving fee) that opens the engraving form.
575
+ - If the item already has engraving, its engraving is shown on the line item with an **Edit** button that reopens the form.
576
+
577
+ The form respects the item's engraving constraints — `maxLines`, `maxCharsPerLine`, and the per-item `fee`. Saving emits [`lce:actions.cart_item_engraving_updated`](#engraving-updated) with the item's `engravingLines` and `previousEngravingLines`.
578
+
579
+ **Note:** This in-drawer editing is distinct from the `engravingLines` array passed to [`addProduct`](#add-product-to-cart), which pre-fills engraving at the time an item is added.
580
+
549
581
  ## Checkout Navigation
550
582
 
551
583
  ### Checkout Drawer (Default)
@@ -148,6 +148,8 @@ Products with multiple images display in an interactive carousel:
148
148
  - Thumbnail preview
149
149
  - Lazy loading for performance
150
150
 
151
+ **Background removal:** Product images (the main detail image and the gallery) automatically have their white/near-white background removed so photos blend into the surrounding page background instead of sitting on a white box. The SDK picks the technique per image based on the host background — blending the white away on light backgrounds, or keying it out to true transparency on dark or transparent backgrounds — and skips SVG artwork, which is already transparent. This is applied automatically and is not currently host-configurable.
152
+
151
153
  ### Size Selection
152
154
 
153
155
  For products with multiple sizes:
@@ -206,8 +208,8 @@ For products with multiple retailers:
206
208
 
207
209
  **Popup View**
208
210
  - "See Delivery Options" button (shows the available fulfillment count, e.g. "See Delivery Options (3)")
209
- - Modal with full retailer list
210
- - Filter and search capabilities
211
+ - Opens a plain, scrollable list of the available delivery/retailer options
212
+ - No filtering or search — select a retailer from the list to choose it
211
213
 
212
214
  ### Personalization/Engraving
213
215
 
@@ -366,6 +368,7 @@ const client = await Elements('YOUR_API_KEY', {
366
368
  showOnlyMainImage: false, // Show all images or just the main one
367
369
  showTitle: true,
368
370
  showDescription: true,
371
+ descriptionPosition: 'below', // Description placement: 'above' or 'below'
369
372
  showQuantityCounter: true,
370
373
  showOffHours: true, // Show when retailer is closed
371
374
  quantityCounterStyle: 'outlined', // or 'ghost'
@@ -376,6 +379,7 @@ const client = await Elements('YOUR_API_KEY', {
376
379
  addToCartButtonShowTotalPrice: true,
377
380
  buyNowButtonText: 'Buy Now',
378
381
  preSaleButtonText: 'Pre-Order',
382
+ prioritizeEngraving: false, // Show engraving option before add-to-cart
379
383
  noAvailabilityText: 'Not available in your area'
380
384
  }
381
385
  }
@@ -260,18 +260,19 @@ Each product card shows:
260
260
  - Product name
261
261
  - Brand
262
262
  - Price (or price range for multiple sizes)
263
- - Rating (if available)
264
263
  - Clickable image/card linking to the product detail page (when `productUrl` is configured)
265
264
  - "Add to Cart" button (optional)
266
265
  - Availability indicator
267
266
 
267
+ Product card images automatically have their white/near-white backgrounds removed so the product blends into the surrounding card and page background. This treatment is applied at render time and is not host-configurable.
268
+
268
269
  ### Card Interaction
269
270
 
270
271
  **Click on card:** Navigate to product detail page (if `productUrl` configured — see [Product URL Map](#product-url-map) for partner-owned PDP URLs that aren't derivable from a token).
271
272
 
272
273
  **Quick Add:** Add product to cart directly from list view (if enabled)
273
274
 
274
- **Click on image:** Open image in lightbox or navigate to product page
275
+ **Click on image:** Navigate to the configured `productUrl` (only when `productUrl` is set — otherwise the image is not a link)
275
276
 
276
277
  ## Customization
277
278
 
@@ -514,10 +515,8 @@ The product list component includes:
514
515
  ### Optimization Features
515
516
 
516
517
  - **Image lazy loading**: Images load as they enter viewport
517
- - **Virtual scrolling**: Only renders visible products
518
+ - **Progressive loading**: Products load in batches via an `IntersectionObserver` sentinel as you scroll — each page is appended to the grid and loaded cards remain in the DOM
518
519
  - **Debounced search**: Reduces API calls during typing
519
- - **Filter caching**: Caches filter results
520
- - **Progressive loading**: Loads in batches
521
520
 
522
521
  ### Large Catalogs
523
522
 
@@ -53,6 +53,12 @@ customTheme: {
53
53
  }
54
54
  ```
55
55
 
56
+ **Constraints:**
57
+
58
+ - Only Google Fonts are supported. Each font's `name` must be a valid Google Font name (for example, `'Poppins'` or `'Inter'`).
59
+ - `Poppins` is always loaded as the default font regardless of your configuration, so it remains available even if you do not specify it.
60
+ - Font loading requires network access to `fonts.googleapis.com` and `fonts.gstatic.com`. If your environment enforces a Content Security Policy or routes traffic through a proxy, allow these hosts so fonts can load.
61
+
56
62
  ### Border Radius
57
63
 
58
64
  ```javascript
@@ -77,12 +83,16 @@ customTheme: {
77
83
  personalizationCardStyle: 'outlined', // or 'filled'
78
84
  allowPromoCodes: true,
79
85
  inputFieldStyle: 'outlined', // or 'filled'
86
+ enableOrderedProductSizes: true, // enable custom ordering of the size selectors
87
+ orderedProductSizes: ['750ml', '1L', '1.75L'], // order applied to product and product-list size selectors
80
88
  poweredByMode: 'light' // or 'dark' (note: showPoweredBy is controlled server-side and cannot be overridden via customTheme)
81
89
  }
82
90
  }
83
91
  }
84
92
  ```
85
93
 
94
+ `enableOrderedProductSizes` and `orderedProductSizes` control the ordering of the size selectors rendered by the product and product-list components. When `enableOrderedProductSizes` is `true`, size options are sorted to match the sequence in the `orderedProductSizes` string array. Updating either key triggers a targeted rerender of the affected size selectors.
95
+
86
96
  ## Component Themes
87
97
 
88
98
  ### Product Component
@@ -0,0 +1,108 @@
1
+ # Analytics & Google Tag Manager
2
+
3
+ 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.
4
+
5
+ This runs entirely inside the SDK. In most cases you do not need to configure or code anything.
6
+
7
+ ## What You Need To Do
8
+
9
+ **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.
10
+
11
+ It coexists with a host site's own GTM — see [Coexisting With Your Own GTM](#coexisting-with-your-own-gtm) below.
12
+
13
+ ## Supported Environments
14
+
15
+ 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.
16
+
17
+ Events are suppressed when any of the following is true:
18
+
19
+ - `window` is undefined (server-side rendering).
20
+ - The SDK is running in Builder mode.
21
+ - The environment is `development`.
22
+
23
+ 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.
24
+
25
+ ## How It Works
26
+
27
+ ### Container injection
28
+
29
+ When enabled, the SDK injects the GTM container script:
30
+
31
+ ```
32
+ https://www.googletagmanager.com/gtm.js?id=<containerId>
33
+ ```
34
+
35
+ The script is appended to `<head>` with `async` and `crossorigin="anonymous"`, and the SDK waits for GTM to initialize before flushing events.
36
+
37
+ ### dataLayer and gtag
38
+
39
+ The SDK initializes the standard GTM globals **without clobbering an existing setup**:
40
+
41
+ - `window.dataLayer` is created only if it does not already exist.
42
+ - `window.gtag` is defined only if it is not already present.
43
+
44
+ Events are delivered using Google's recommended `window.dataLayer.push()` pattern.
45
+
46
+ ### Event queueing
47
+
48
+ 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.
49
+
50
+ ## Coexisting With Your Own GTM
51
+
52
+ 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.
53
+
54
+ 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.
55
+
56
+ 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.
57
+
58
+ ## Source Tracking (`tenant_*`)
59
+
60
+ Every event automatically carries source-tracking fields identifying the tenant and the SDK build:
61
+
62
+ | Field | Value |
63
+ | --- | --- |
64
+ | `tenant_name` | Partner name |
65
+ | `tenant_code` | Partner code |
66
+ | `tenant_env` | SDK environment |
67
+ | `tenant_source` | SDK package description and version |
68
+
69
+ ## Events
70
+
71
+ All events are GA4-shaped and follow the standard ecommerce schema (`items[]`, `value`, `currency` — the SDK uses `USD`, `coupon`, etc.).
72
+
73
+ ### Standard GA4 ecommerce events
74
+
75
+ | Event | Fired when |
76
+ | --- | --- |
77
+ | `view_item` | A shopper views a product |
78
+ | `view_item_list` | A shopper views a list of products |
79
+ | `select_item` | A shopper selects a product from a list |
80
+ | `add_to_cart` | A shopper adds an item to the cart |
81
+ | `view_cart` | A shopper views the cart |
82
+ | `remove_from_cart` | A shopper removes an item from the cart |
83
+ | `begin_checkout` | A shopper begins checkout |
84
+ | `add_shipping_info` | Shipping info is added during checkout |
85
+ | `add_payment_info` | Payment info is added during checkout |
86
+ | `purchase` | A purchase completes |
87
+
88
+ ### Custom events
89
+
90
+ | Event | Fired when |
91
+ | --- | --- |
92
+ | `promo_code_attempt` | A promo code is submitted |
93
+ | `promo_code_applied` | A promo code is successfully applied |
94
+ | `promo_code_failed` | A promo code fails to apply |
95
+ | `gift_card_attempt` | A gift card is submitted |
96
+ | `gift_card_applied` | A gift card is successfully applied |
97
+ | `gift_card_failed` | A gift card fails to apply |
98
+ | `address_updated` | An address is successfully updated |
99
+ | `address_failed` | An address operation fails |
100
+ | `product_no_availability` | A product has no availability for any size/fulfillment |
101
+ | `product_size_no_availability` | A selected size has no availability |
102
+ | `product_fulfillment_no_availability` | A selected fulfillment type has no availability |
103
+
104
+ ## Related Docs
105
+
106
+ - [Events Guide](../guides/events.md)
107
+ - [Client API](../api/client.md)
108
+ - [Troubleshooting](./troubleshooting.md)
@@ -25,7 +25,9 @@ In non-browser environments, initialization is skipped. If you call the SDK on t
25
25
  it returns `null` and logs a warning instead of throwing.
26
26
 
27
27
  Call `Elements`, `ElementsCheckout`, or `ElementsBuilder` from client-only code (e.g., after mount)
28
- to render components.
28
+ to render components. `Elements` and `ElementsBuilder` resolve to no-op stubs from the main SSR
29
+ entry; `ElementsCheckout` ships in its own tree-shaken entry with a separate stub, so it is safe to
30
+ import even if you never use the other two.
29
31
 
30
32
  ## Polyfills (Legacy Browsers)
31
33
 
@@ -68,6 +68,14 @@ window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
68
68
 
69
69
  When a component fails to load, the SDK renders an error view inside the container and logs details to the console.
70
70
 
71
+ ## Global Error Interception
72
+
73
+ 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.
74
+
75
+ 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.
76
+
77
+ > **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.
78
+
71
79
  ## Related Docs
72
80
 
73
81
  - [Events Guide](../guides/events.md)
@@ -0,0 +1,85 @@
1
+ # Telemetry & Privacy
2
+
3
+ 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**.
4
+
5
+ Telemetry never blocks or breaks your page — capture and sending are wrapped so internal failures are swallowed silently.
6
+
7
+ ## When It Is Enabled
8
+
9
+ Telemetry is enabled **only** when both conditions are true:
10
+
11
+ - The SDK is running in the **production** environment (`env === 'production'`), and
12
+ - **No custom API URL is configured** (`hasCustomApiUrl` is `false`).
13
+
14
+ In every other case it is **disabled** and no events are queued or sent:
15
+
16
+ - Non-production environments (e.g. staging/development).
17
+ - A custom API URL / proxy is configured via `development.customApiUrl`.
18
+ - Internal telemetry errors are only logged to the console in non-production or when debugging is enabled — never sent.
19
+
20
+ ## What Is Collected
21
+
22
+ Each event carries the message, severity level, and timestamp, plus three context blocks.
23
+
24
+ **Browser context**
25
+
26
+ - `userAgent` — the browser user-agent string
27
+ - `url` — the full current page URL (`window.location.href`)
28
+ - `referrer` — the referring URL, if any
29
+ - `timezone` — the resolved IANA timezone (e.g. `America/New_York`)
30
+ - `deviceType` — device classification (desktop/mobile/tablet)
31
+
32
+ **User context**
33
+
34
+ - `deviceId` — the SDK-generated device id (falls back to `not_defined`)
35
+ - `isLocalStorageAvailable` — whether localStorage is usable
36
+ - `selectedAddress` — the user's currently selected **formatted address string**, if one is set
37
+
38
+ **SDK context**
39
+
40
+ - `version`, `env`, `isBuilder`, and `partnerCode`
41
+
42
+ **Errors** (when the event represents one) include the error `name`, `message`, `code`, and a stack trace **truncated to the first 10 lines**.
43
+
44
+ Only **warnings** and **errors/fatal** events are captured. Debug/log/info events are excluded by default (`includeDebugLogs: false`).
45
+
46
+ ## Where It Is Sent
47
+
48
+ Events are **batched** and sent to:
49
+
50
+ ```
51
+ <baseUrl>/api/telemetry
52
+ ```
53
+
54
+ `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.
55
+
56
+ Batches are delivered with `navigator.sendBeacon`, falling back to a **synchronous `XMLHttpRequest`** if sendBeacon is unavailable or fails. Payloads are sent as `text/plain`.
57
+
58
+ Batches flush:
59
+
60
+ - When the queue reaches the batch size (5 events in production),
61
+ - On a periodic timer (every 5s in production), and
62
+ - On page teardown (`beforeunload` / `pagehide`), so pending events are not lost.
63
+
64
+ The queue is capped (max 50 events); oldest events are dropped first if it overflows.
65
+
66
+ ## Disabling Telemetry
67
+
68
+ There is no separate opt-out flag — telemetry follows the two conditions above. To ensure it never runs, do either of the following:
69
+
70
+ - Run the SDK in a **non-production** environment, or
71
+ - Configure a **custom API URL** so events are routed through your own infrastructure and SDK telemetry is switched off:
72
+
73
+ ```javascript
74
+ const client = await Elements('YOUR_API_KEY', {
75
+ development: {
76
+ customApiUrl: 'https://your-proxy.example.com'
77
+ }
78
+ });
79
+ ```
80
+
81
+ ## Related Docs
82
+
83
+ - [Error Handling](./error-handling.md)
84
+ - [Client API](../api/client.md)
85
+ - [Troubleshooting](./troubleshooting.md)
@@ -105,8 +105,7 @@ This is expected behavior. The SDK ships SSR stubs that are automatically resolv
105
105
 
106
106
  **Fixes:**
107
107
  - Verify all 5 required fields are set: `promoCode`, `text`, `separator`, `activeFrom`, `activeUntil`.
108
- - Check that the current time falls between `activeFrom` and `activeUntil` (ISO 8601 UTC format).
109
- - Ensure `global.layout.allowPromoCodes` is not set to `false`.
108
+ - 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.
110
109
 
111
110
  ## Ad Blockers Blocking SDK Requests
112
111
 
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "description": "LiquidCommerce Elements SDK",
4
4
  "license": "UNLICENSED",
5
5
  "author": "LiquidCommerce Team",
6
- "version": "2.6.0-beta.93",
6
+ "version": "2.6.0-beta.95",
7
7
  "homepage": "https://docs.liquidcommerce.co/elements-sdk",
8
8
  "repository": {
9
9
  "type": "git",
@@ -14,7 +14,7 @@
14
14
  },
15
15
  "module": "./dist/index.esm.js",
16
16
  "types": "./dist/types/index.d.ts",
17
- "packageManager": "pnpm@11.10.0",
17
+ "packageManager": "pnpm@11.18.0",
18
18
  "exports": {
19
19
  ".": {
20
20
  "types": "./dist/types/index.d.ts",
@@ -68,18 +68,47 @@
68
68
  },
69
69
  "keywords": [
70
70
  "liquidcommerce",
71
+ "vesper",
72
+ "vesper-commerce",
73
+ "accelpay",
74
+ "reservebar",
75
+ "minibar",
71
76
  "alcohol",
72
77
  "beverage",
73
- "alcohol tech",
74
78
  "elements",
75
- "custom web components",
76
- "embeddable components",
77
- "embeddable web components",
78
- "embeddable commerce"
79
+ "alcohol-ecommerce",
80
+ "ecommerce",
81
+ "ecommerce-sdk",
82
+ "headless-commerce",
83
+ "embeddable-commerce",
84
+ "embeddable-components",
85
+ "web-components",
86
+ "custom-elements",
87
+ "shadow-dom",
88
+ "framework-agnostic",
89
+ "typescript",
90
+ "zero-dependencies",
91
+ "product-display",
92
+ "product-list",
93
+ "shopping-cart",
94
+ "cart-drawer",
95
+ "checkout",
96
+ "hosted-checkout",
97
+ "stripe",
98
+ "payments",
99
+ "promo-codes",
100
+ "gift-cards",
101
+ "address-autocomplete",
102
+ "delivery",
103
+ "shipping",
104
+ "pickup",
105
+ "presale",
106
+ "fulfillment",
107
+ "theming"
79
108
  ],
80
109
  "devDependencies": {
81
- "@biomejs/biome": "^2.5.2",
82
- "@commitlint/cli": "^21.2.0",
110
+ "@biomejs/biome": "^2.5.6",
111
+ "@commitlint/cli": "^21.2.1",
83
112
  "@commitlint/config-conventional": "^21.2.0",
84
113
  "@rollup/plugin-alias": "^6.0.0",
85
114
  "@rollup/plugin-commonjs": "^29.0.3",
@@ -87,21 +116,21 @@
87
116
  "@rollup/plugin-node-resolve": "^16.0.3",
88
117
  "@rollup/plugin-replace": "^6.0.3",
89
118
  "@rollup/plugin-terser": "^1.0.0",
90
- "@semantic-release/changelog": "^6.0.3",
119
+ "@semantic-release/changelog": "^7.0.0",
91
120
  "@semantic-release/commit-analyzer": "^13.0.1",
92
- "@semantic-release/git": "^10.0.1",
121
+ "@semantic-release/git": "^11.0.1",
93
122
  "@semantic-release/github": "^12.0.9",
94
123
  "@semantic-release/npm": "^13.1.5",
95
124
  "@semantic-release/release-notes-generator": "^14.1.1",
96
125
  "@types/core-js": "^2.5.8",
97
- "@types/node": "^26.1.0",
98
- "conventional-changelog": "8.0.1",
126
+ "@types/node": "^26.1.2",
127
+ "conventional-changelog": "8.1.0",
99
128
  "husky": "^9.1.7",
100
129
  "process": "^0.11.10",
101
- "rollup": "^4.62.2",
130
+ "rollup": "^4.62.3",
102
131
  "rollup-obfuscator": "^4.1.1",
103
132
  "rollup-plugin-typescript2": "^0.37.0",
104
- "semantic-release": "^25.0.5",
133
+ "semantic-release": "^25.0.8",
105
134
  "ts-node": "^10.9.2",
106
135
  "typescript": "6.0.3"
107
136
  },