@liquidcommerce/elements-sdk 2.7.24 → 2.7.25

package/docs/v1/reference/telemetry.md

@@ -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

@@ -105,8 +105,7 @@ This is expected behavior. The SDK ships SSR stubs that are automatically resolv
 
 **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).
-- Ensure `global.layout.allowPromoCodes` is not set to `false`.
+- 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
 

package/package.json

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.7.24",
+  "version": "2.7.25",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",
@@ -78,8 +78,8 @@
     "embeddable commerce"
   ],
   "devDependencies": {
-    "@biomejs/biome": "^2.5.2",
-    "@commitlint/cli": "^21.2.0",
+    "@biomejs/biome": "^2.5.3",
+    "@commitlint/cli": "^21.2.1",
     "@commitlint/config-conventional": "^21.2.0",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-commonjs": "^29.0.3",
@@ -94,7 +94,7 @@
     "@semantic-release/npm": "^13.1.5",
     "@semantic-release/release-notes-generator": "^14.1.1",
     "@types/core-js": "^2.5.8",
-    "@types/node": "^26.1.0",
+    "@types/node": "^26.1.1",
     "conventional-changelog": "8.0.1",
     "husky": "^9.1.7",
     "process": "^0.11.10",