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

package/docs/v1/api/actions/checkout-actions.md

@@ -12,7 +12,8 @@ Checkout actions allow you to programmatically control the checkout flow.
 openCheckout(): void
 ```
 
-Opens the checkout drawer or navigates to checkout page.
+Opens the checkout drawer or navigates to checkout page. Reports `begin_checkout` for the cart's items
+to GTM, as the cart's own Checkout button does, unless the drawer already shows the checkout.
 
 ```javascript
 window.LiquidCommerce.elements.actions.checkout.openCheckout();
@@ -36,7 +37,7 @@ window.LiquidCommerce.elements.actions.checkout.closeCheckout();
 toggleCheckout(): void
 ```
 
-Toggles checkout open/closed.
+Toggles checkout open/closed. Opening it reports `begin_checkout`, as `openCheckout()` does.
 
 ```javascript
 window.LiquidCommerce.elements.actions.checkout.toggleCheckout();
@@ -64,6 +65,8 @@ addProduct(params: IAddProductParams[], openCheckout?: boolean): Promise<void>
 
 Add products and open checkout in one call. Products are added to the cart (via the cart action, or directly when none is wired up), then checkout is prepared and opened. For a checkout without a cart session, use `addAnonymousProduct`.
 
+Reports `add_to_cart` for the added products and then `begin_checkout` for the cart to GTM, so don't report either again with [`actions.analytics`](./analytics-actions.md).
+
 `IAddProductParams.engravingLines?: string[]` — optional engraving. Same rules as [`actions.cart.addProduct()`](./cart-actions.md#actionscartaddproduct): invalid input is ignored, blanks stripped, lines clamped to the product's `maxLines` / `maxCharsPerLine`, and engraving is dropped (without failing) when the product, variant, or fulfillment doesn't support it.
 
 ```javascript

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()
 
@@ -73,6 +75,9 @@ Injects only the Apple Pay and Google Pay wallet buttons, anywhere on the page,
 the checkout UI. Confirming the wallet sheet places the order outright — the wallet's contact and
 billing details are sent to the checkout, so the shopper never fills a checkout form.
 
+Express checkout is off by default: pass `development.enableExpressCheckout: true` in the client config to show it. Without it this
+method renders nothing and resolves to `null`.
+
 ```typescript
 injectExpressCheckout(params: IInjectExpressCheckoutParams): Promise<IInjectedComponent | null>
 ```

package/docs/v1/api/configuration.md

@@ -563,6 +563,7 @@ interface ILiquidCommerceElementsDevelopmentConfig {
   customApiUrl?: string;
   openShadowDom?: boolean;
   mockMode?: boolean;
+  enableExpressCheckout?: boolean;
 }
 ```
 
@@ -571,6 +572,9 @@ interface ILiquidCommerceElementsDevelopmentConfig {
 | `customApiUrl` | `string` | Custom API URL for local or custom backend testing |
 | `openShadowDom` | `boolean` | Use an OPEN (inspectable) Shadow DOM instead of the default closed mode, for debugging. Shadow DOM is always attached; forced off in production (default: `false`) |
 | `mockMode` | `boolean` | Enable mock mode to receive mock data from the API; sends an `X-Liquid-Api-Mock-Mode` header with all requests (default: `false`) |
+| `enableExpressCheckout` | `boolean` | Show the Apple Pay / Google Pay express checkout and the checkout's delivery-method switch (same-day vs shipping) — the express block and delivery-method section in the checkout element, and `injectExpressCheckoutElement()` / `injectExpressCheckout()`, which otherwise render nothing and resolve to `null`. Honoured in every environment, production included (default: `false`) |
+
+> **Temporary:** this flag exists only while express checkout and the delivery-method switch are being verified. Once they are confirmed, the flag will be removed and both will always be on.
 
 > To pre-select a payment method and skip the card form (in any environment), use [`actions.checkout.setSavedPaymentMethod`](./actions/checkout-actions.md#actionscheckoutsetsavedpaymentmethod) instead.
 

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;
 }
 
@@ -158,6 +160,7 @@ interface ILiquidCommerceElementsDevelopmentConfig {
   customApiUrl?: string;
   openShadowDom?: boolean;
   mockMode?: boolean;  // when true, sends an 'X-Liquid-Api-Mock-Mode' header to receive mock data
+  enableExpressCheckout?: boolean;  // show express checkout and the delivery-method switch; off by default, honoured in production
 }
 ```
 
@@ -309,6 +312,7 @@ interface ILiquidCommerceElementsActions {
   address: IAddressActions;
   cart: ICartActions;
   checkout: ICheckoutActions;
+  analytics: IAnalyticsActions;
 }
 ```
 
@@ -320,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

@@ -373,7 +373,9 @@ window.addEventListener('lce:actions.checkout_item_quantity_decrease', (event) =
 
 ### Delivery Method
 
-Fires when the shopper switches a single-item checkout between same-day delivery and shipping.
+Fires when the shopper switches a single-item checkout between same-day delivery and shipping. The
+switch is shown only with `development.enableExpressCheckout: true`, the same opt-in as express
+checkout.
 
 ```javascript
 window.addEventListener('lce:actions.checkout_delivery_method_updated', (event) => {
@@ -427,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
@@ -563,7 +570,12 @@ Apple Pay and Google Pay are offered as express checkout buttons at the top of t
 the gift toggle. Tapping one collects the shopper's contact and billing details from the wallet and
 places the order without them completing the checkout forms.
 
-Express checkout is offered to every shopper whose platform can show a wallet. Each wallet is
+Express checkout is off by default: pass `development.enableExpressCheckout: true` in the client config to show it. Without it the checkout element renders
+no express block, and the injection methods below render nothing and resolve to `null`.
+
+> **Temporary:** this flag exists only while express checkout and the delivery-method switch are being verified. Once they are confirmed, the flag will be removed and both will always be on.
+
+Once enabled, express checkout is offered to every shopper whose platform can show a wallet. Each wallet is
 requested with Stripe's `always` policy, so the button renders wherever the device supports it rather
 than only where Stripe judges it good for conversion. The block hides itself entirely — heading,
 buttons and divider — in four cases: the device or browser offers no wallet, the order is a

package/docs/v1/guides/events.md

@@ -709,7 +709,8 @@ window.addEventListener('lce:actions.checkout_item_engraving_updated', (event) =
 ### `lce:actions.checkout_delivery_method_updated`
 
 Fires when the shopper moves a single-item checkout between same-day delivery and shipping. The order
-is re-priced, so the totals change with it.
+is re-priced, so the totals change with it. The switch is shown only with
+`development.enableExpressCheckout: true`.
 
 **Data includes:** `cartId`, `fulfillmentType`, `previousFulfillmentType`, `fulfillmentId`.
 
@@ -893,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.127",
+  "version": "2.6.0-beta.129",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",