@liquidcommerce/elements-sdk 2.6.0-beta.128 → 2.6.0-beta.129

package/docs/v1/api/client.md

@@ -64,8 +64,10 @@ const client = await ElementsCheckout('YOUR_API_KEY', {
 });
 ```
 
-The checkout-only client exposes `injectCheckout()`, `injectExpressCheckout()`, `actions.checkout`
-and `destroy()`.
+The checkout-only client exposes `injectCheckout()`, `injectExpressCheckout()`, `actions.checkout`,
+`actions.analytics` and `destroy()`. `actions.analytics` reports the steps your own UI renders —
+product views, address, availability, starting checkout — to the same GTM stream the checkout
+reports to; see [Analytics Actions](./actions/analytics-actions.md).
 
 #### injectExpressCheckout()
 

package/docs/v1/api/typescript-types.md

@@ -21,6 +21,8 @@ import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
 import type {
   IElementsCheckoutClient,
   IElementsCheckoutActions,
+  IAnalyticsActions,
+  IAnalyticsItem,
   ILiquidCommerceElementsCheckoutClientConfig,
   IInjectedComponent
 } from '@liquidcommerce/elements-sdk/checkout';
@@ -81,7 +83,7 @@ Checkout-only client interface returned by `ElementsCheckout()`.
 interface IElementsCheckoutClient {
   injectCheckout(params: IInjectCheckoutParams): Promise<IInjectedComponent | null>;
   injectExpressCheckout(params: IInjectExpressCheckoutParams): Promise<IInjectedComponent | null>;
-  actions: { checkout: IElementsCheckoutActions };
+  actions: { checkout: IElementsCheckoutActions; analytics: IAnalyticsActions };
   destroy(): void;
 }
 
@@ -310,6 +312,7 @@ interface ILiquidCommerceElementsActions {
   address: IAddressActions;
   cart: ICartActions;
   checkout: ICheckoutActions;
+  analytics: IAnalyticsActions;
 }
 ```
 
@@ -321,6 +324,74 @@ Checkout actions available in the checkout-only client. This is `ICheckoutAction
 interface IElementsCheckoutActions extends Omit<ICheckoutActions, 'openCheckout' | 'closeCheckout' | 'toggleCheckout'> {}
 ```
 
+### IAnalyticsActions
+
+Reports steps a host renders with its own UI to the SDK's GTM / GA4 stream. On both the full client
+and the checkout-only client. See [Analytics Actions](./actions/analytics-actions.md).
+
+```typescript
+interface IAnalyticsActions {
+  search(searchTerm: string): void;
+  viewItem(item: IAnalyticsItem): void;
+  viewItemList(items: IAnalyticsItem[], list?: IAnalyticsItemList): void;
+  selectItem(item: IAnalyticsItem, list?: IAnalyticsItemList): void;
+  addToCart(item: IAnalyticsItem): void;
+  removeFromCart(item: IAnalyticsItem): void;
+  viewCart(items: IAnalyticsItem[]): void;
+  beginCheckout(items: IAnalyticsItem[], options?: { coupon?: string }): void;
+  addressUpdated(address: IAnalyticsAddress): void;
+  addressFailed(failure: IAnalyticsAddressFailure): void;
+  productNoAvailability(details: IAnalyticsAvailability): void;
+  productSizeNoAvailability(details: IAnalyticsAvailability): void;
+  productFulfillmentNoAvailability(details: IAnalyticsFulfillmentAvailability): void;
+}
+
+interface IAnalyticsItem {
+  id: string;            // the selected size's id
+  name: string;
+  brand?: string;
+  size?: string;
+  categoryPath?: string; // product catPath
+  price?: number;        // cents
+  quantity?: number;
+  type?: string;
+  subType?: string;
+  image?: string;
+  upc?: string;
+  groupingId?: string;
+  index?: number;
+}
+
+interface IAnalyticsItemList {
+  id?: string;
+  name?: string;
+}
+
+interface IAnalyticsAddress {
+  placesId?: string;
+  formattedAddress?: string;
+  address: Partial<IAddressAddress>;
+  coordinates?: IAddressCoordinates;
+}
+
+interface IAnalyticsAddressFailure {
+  placesId?: string;
+  formattedAddress?: string;
+  address?: Partial<IAddressAddress>;
+  error: string;
+}
+
+interface IAnalyticsAvailability {
+  item: IAnalyticsItem;
+  reason: string;
+  address?: Partial<IAddressAddress>;
+}
+
+interface IAnalyticsFulfillmentAvailability extends IAnalyticsAvailability {
+  fulfillmentType: FulfillmentType;
+}
+```
+
 See [Actions API](./actions/) for detailed method signatures.
 
 ---

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

@@ -429,6 +429,11 @@ window.addEventListener('lce:actions.checkout_express_checkout_availability', (e
   const { data } = event.detail;
   console.log(data.available ? `Wallets: ${data.wallets.join(', ')}` : 'No wallets available');
 });
+
+// The shopper tapped a wallet button and its sheet opened
+window.addEventListener('lce:actions.checkout_express_checkout_started', (event) => {
+  console.log(`Wallet sheet opened: ${event.detail.data.wallet}`);
+});
 ```
 
 ### Promo Codes

package/docs/v1/guides/events.md

@@ -894,6 +894,26 @@ window.addEventListener('lce:actions.checkout_express_checkout_availability', (e
 });
 ```
 
+### `lce:actions.checkout_express_checkout_started`
+
+Fires when the shopper taps a wallet button and the SDK opens the wallet sheet, inside the checkout
+or on a block placed with `injectExpressCheckout` / `injectExpressCheckoutElement`. It fires for every
+tap, and not for a tap the block refuses (a total that moved, an unmet order minimum, a second tap
+while an order is being placed). The tap happens inside Stripe's frame, so this is the only way a host
+page learns of it — for instance, to report `add_to_cart` for a product-page wallet with
+[`actions.analytics`](../api/actions/analytics-actions.md).
+
+**Data includes:** `cartId`, `wallet` (Stripe's name for it: `'apple_pay'`, `'google_pay'`, …).
+
+**Example**
+
+```javascript
+window.addEventListener('lce:actions.checkout_express_checkout_started', (event) => {
+  const { wallet } = event.detail.data;
+  console.log(`Wallet sheet opened: ${wallet}`);
+});
+```
+
 ### `lce:actions.checkout_payment_form_failed`
 
 Fires when the card form cannot load Stripe.js, so the card fields cannot appear. The shopper sees a

package/docs/v1/reference/analytics.md

@@ -10,6 +10,11 @@ This runs entirely inside the SDK. In most cases you do not need to configure or
 
 It coexists with a host site's own GTM — see [Coexisting With Your Own GTM](#coexisting-with-your-own-gtm) below.
 
+The one case that needs code: if **your own UI** renders a step Elements would otherwise render — a
+product page, an address picker, a cart, or a "Proceed to checkout" in front of the checkout-only
+client — Elements never sees it. Report it with `actions.analytics` — see
+[Reporting Steps Your Own UI Renders](#reporting-steps-your-own-ui-renders).
+
 ## Supported Environments
 
 GTM initialization and every event push are enabled in production and staging. When the SDK is running in Builder mode, no container is loaded and no events are sent.
@@ -93,22 +98,23 @@ Every event automatically carries source-tracking fields identifying the tenant
 
 ## Events
 
-All events are GA4-shaped and follow the standard ecommerce schema (`items[]`, `value`, `currency` — the SDK uses `USD`, `coupon`, etc.).
+All events are GA4-shaped and follow the standard ecommerce schema (`items[]`, `value`, `currency` — the SDK uses `USD`, `coupon`, etc.). `search` is the exception: it carries only `search_term`.
 
 ### 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 |
+| `view_item` | A shopper views a product, and again on each size they switch to |
+| `view_item_list` | A product list loads products: its first load, a filtered or searched list, each "load more" |
+| `select_item` | A shopper opens a product from a product list card |
+| `add_to_cart` | A shopper adds an item: from the product component or a list card, `actions.cart.addProduct()` / `actions.checkout.addProduct()`, a cart or checkout quantity increase, or a presale added straight to checkout |
+| `view_cart` | The cart drawer opens with items in it — the cart button, `openCart()` / `toggleCart()`, the checkout's back button — or an add that opens it lands |
+| `remove_from_cart` | A shopper lowers an item's quantity or removes it, in the cart or in the checkout |
+| `begin_checkout` | A shopper begins checkout: the cart's Checkout button (also before its redirect to `checkout.pageUrl`), `actions.checkout.addProduct()`, `openCheckout()` / `toggleCheckout()` opening the drawer, a presale added straight to checkout, or the first wallet tap on express buttons placed on their own |
+| `add_shipping_info` | Shipping info is added during checkout: the customer or gift recipient form is saved, or a wallet (Apple Pay / Google Pay) order hands over the wallet's contact details |
 | `add_payment_info` | Payment info is added during checkout |
 | `purchase` | A purchase completes |
+| `search` | A search typed into the product list's search box runs |
 
 ### Custom events
 
@@ -126,8 +132,45 @@ All events are GA4-shaped and follow the standard ecommerce schema (`items[]`, `
 | `product_size_no_availability` | A selected size has no availability |
 | `product_fulfillment_no_availability` | A selected fulfillment type has no availability |
 
+## Reporting Steps Your Own UI Renders
+
+Elements reports the steps its components render. A host that renders some steps itself reports
+them through `actions.analytics`, on the full client and on the checkout-only client:
+
+| Action | Event |
+| --- | --- |
+| `search(searchTerm)` | `search` |
+| `viewItem(item)` | `view_item` |
+| `viewItemList(items, list?)` | `view_item_list` |
+| `selectItem(item, list?)` | `select_item` |
+| `addToCart(item)` | `add_to_cart` |
+| `removeFromCart(item)` | `remove_from_cart` |
+| `viewCart(items)` | `view_cart` |
+| `beginCheckout(items, { coupon? })` | `begin_checkout` |
+| `addressUpdated(address)` | `address_updated` |
+| `addressFailed(failure)` | `address_failed` |
+| `productNoAvailability(details)` | `product_no_availability` |
+| `productSizeNoAvailability(details)` | `product_size_no_availability` |
+| `productFulfillmentNoAvailability(details)` | `product_fulfillment_no_availability` |
+
+They go through the same pipeline as the SDK's own events — same shape, `tenant_*` fields,
+`send_to` targets, environment gating and queueing — so a report built on Elements events covers
+both. There are no actions for `add_shipping_info`, `add_payment_info`, `purchase` or the promo code
+and gift card events: the Elements checkout reports those itself, and a host reporting them too
+would count every order twice. For the same reason, don't report a step an Elements component
+renders — including `begin_checkout`, which Elements reports from the cart's Checkout button,
+`actions.checkout.addProduct()`, `openCheckout()` / `toggleCheckout()`, a presale, and the first
+wallet tap on express buttons placed on their own.
+
+Malformed input never throws: the event is skipped and a warning logged, so reporting can't break
+the host's page.
+
+Items take prices in cents, as product responses carry them, and send them in dollars. Full
+signatures and examples: [Analytics Actions](../api/actions/analytics-actions.md).
+
 ## Related Docs
 
 - [Events Guide](../guides/events.md)
+- [Analytics Actions](../api/actions/analytics-actions.md)
 - [Client API](../api/client.md)
 - [Troubleshooting](./troubleshooting.md)

package/package.json

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.6.0-beta.128",
+  "version": "2.6.0-beta.129",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",