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

package/dist/ssr-stub.esm.js

@@ -142,6 +142,7 @@ const ELEMENTS_ACTIONS_EVENT = {
     CHECKOUT_PRODUCT_ADD_SUCCESS: 'checkout_product_add_success',
     CHECKOUT_PRODUCT_ADD_FAILED: 'checkout_product_add_failed',
     CHECKOUT_EXPRESS_CHECKOUT_AVAILABILITY: 'checkout_express_checkout_availability',
+    CHECKOUT_EXPRESS_CHECKOUT_STARTED: 'checkout_express_checkout_started',
     CHECKOUT_PAYMENT_FORM_FAILED: 'checkout_payment_form_failed',
 };
 const ELEMENTS_FORM = {

package/dist/types/core/client/actions/client-analytics-action.service.d.ts

@@ -0,0 +1,35 @@
+import type { IAnalyticsAddress, IAnalyticsAddressFailure, IAnalyticsAvailability, IAnalyticsFulfillmentAvailability, IAnalyticsItem, IAnalyticsItemList } from '@/interfaces/analytics.interface';
+import { BaseActionService } from './base-action.service';
+export 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;
+}
+export declare class ClientAnalyticsActionService extends BaseActionService {
+    private readonly googleTagManager;
+    constructor();
+    static getInstance(): ClientAnalyticsActionService;
+    get actions(): IAnalyticsActions;
+    private report;
+    private check;
+    private toGtmItem;
+    private toGtmItems;
+    private toList;
+    private toAvailability;
+    private toOptionalString;
+    private toAddress;
+    private toCoordinates;
+    private validateItem;
+}

package/dist/types/core/client/actions/client-checkout-action.service.d.ts

@@ -53,6 +53,7 @@ export declare class ClientCheckoutActionService extends BaseActionService {
     private openCheckout;
     private closeCheckout;
     private toggleCheckout;
+    private reportCheckoutOpened;
     private exitCheckout;
     private setSavedPaymentMethod;
     private clearSavedPaymentMethod;

package/dist/types/core/client/client-action.service.d.ts

@@ -4,6 +4,7 @@ export declare class ClientActionService {
     private readonly addressActionService;
     private readonly cartActionService;
     private readonly checkoutActionService;
+    private readonly analyticsActionService;
     constructor();
     static getInstance(): ClientActionService;
     get actions(): ILiquidCommerceElementsActions;

package/dist/types/core/client/client-config.service.d.ts

@@ -23,6 +23,7 @@ export interface IClientConfigs {
     openShadowDom?: boolean;
     hasCustomApiUrl?: boolean;
     mockMode: boolean;
+    enableExpressCheckout: boolean;
     checkout: ILiquidCommerceElementsCheckoutConfig | null;
     isCheckoutOnly: boolean;
 }
@@ -38,6 +39,7 @@ export interface IClientConfigInput {
         customApiUrl?: string;
         openShadowDom?: boolean;
         mockMode?: boolean;
+        enableExpressCheckout?: boolean;
     };
     checkout?: ILiquidCommerceElementsCheckoutConfig;
     isCheckoutOnly?: boolean;

package/dist/types/core/google-tag-manager.service.d.ts

@@ -101,6 +101,7 @@ export declare class GoogleTagManagerService {
         gift_cards?: number;
         net_total?: number;
     }): void;
+    search(searchTerm: string): void;
     promoCodeAttempt(code: string): void;
     promoCodeApplied(code: string, discount?: number): void;
     promoCodeFailed(code: string, reason?: string): void;
@@ -108,8 +109,8 @@ export declare class GoogleTagManagerService {
     giftCardApplied(code: string, appliedAmount?: number): void;
     giftCardFailed(code: string, reason?: string): void;
     addressUpdated(addressData: {
-        googlePlacesId: string;
-        formattedAddress: string;
+        googlePlacesId?: string;
+        formattedAddress?: string;
         address: {
             one?: string;
             two?: string;

package/dist/types/core/pubsub/interfaces/checkout.interface.d.ts

@@ -118,6 +118,10 @@ export interface ICheckoutExpressCheckoutAvailabilityEventData {
     available: boolean;
     wallets: string[];
 }
+export interface ICheckoutExpressCheckoutStartedEventData {
+    cartId: string;
+    wallet: string;
+}
 export interface ICheckoutPaymentFormFailedEventData {
     cartId: string;
     reason: 'blocked' | 'timeout' | 'error';

package/dist/types/core/pubsub/interfaces/core.interface.d.ts

@@ -1,6 +1,6 @@
 import type { IAddressActionEventData, IAddressFailedEventData } from '@/core/pubsub/interfaces/address.interface';
 import type { ICartFailedEventData, ICartItemAddedEventData, ICartItemEngravingUpdatedEventData, ICartItemQuantityChangedEventData, ICartItemRemovedEventData, ICartLoadedEventData, ICartProductAddEventData, ICartProductAddFailedEventData, ICartPromoCodeEventData, ICartPromoCodeFailedEventData, ICartShopRetailerEventData, ICartUpdatedEventData } from '@/core/pubsub/interfaces/cart.interface';
-import type { ICheckoutBillingInformationUpdatedEventData, ICheckoutCustomerInformationUpdatedEventData, ICheckoutDeliveryMethodUpdatedEventData, ICheckoutExpressCheckoutAvailabilityEventData, ICheckoutFailedEventData, ICheckoutGiftCardEventData, ICheckoutGiftCardFailedEventData, ICheckoutGiftInformationUpdatedEventData, ICheckoutItemEngravingUpdatedEventData, ICheckoutItemQuantityChangedEventData, ICheckoutItemRemovedEventData, ICheckoutLoadedEventData, ICheckoutMarketingPreferencesToggleEventData, ICheckoutPaymentFormFailedEventData, ICheckoutProductAddEventData, ICheckoutProductAddFailedEventData, ICheckoutPromoCodeEventData, ICheckoutPromoCodeFailedEventData, ICheckoutSubmitCompletedEventData, ICheckoutSubmitFailedEventData, ICheckoutSubmitStartedEventData, ICheckoutTipUpdatedEventData, ICheckoutToggleEventData } from '@/core/pubsub/interfaces/checkout.interface';
+import type { ICheckoutBillingInformationUpdatedEventData, ICheckoutCustomerInformationUpdatedEventData, ICheckoutDeliveryMethodUpdatedEventData, ICheckoutExpressCheckoutAvailabilityEventData, ICheckoutExpressCheckoutStartedEventData, ICheckoutFailedEventData, ICheckoutGiftCardEventData, ICheckoutGiftCardFailedEventData, ICheckoutGiftInformationUpdatedEventData, ICheckoutItemEngravingUpdatedEventData, ICheckoutItemQuantityChangedEventData, ICheckoutItemRemovedEventData, ICheckoutLoadedEventData, ICheckoutMarketingPreferencesToggleEventData, ICheckoutPaymentFormFailedEventData, ICheckoutProductAddEventData, ICheckoutProductAddFailedEventData, ICheckoutPromoCodeEventData, ICheckoutPromoCodeFailedEventData, ICheckoutSubmitCompletedEventData, ICheckoutSubmitFailedEventData, ICheckoutSubmitStartedEventData, ICheckoutTipUpdatedEventData, ICheckoutToggleEventData } from '@/core/pubsub/interfaces/checkout.interface';
 import type { IProductAddToCartEventData, IProductFulfillmentChangedEventData, IProductFulfillmentTypeChangedEventData, IProductLoadedEventData, IProductQuantityChangedEventData, IProductSizeChangedEventData } from '@/core/pubsub/interfaces/product.interface';
 import { ELEMENTS_ACTIONS_EVENT } from '@/enums';
 export interface IElementsClientIsReadyEventData {
@@ -83,6 +83,7 @@ export interface IElementsActionsEventsMap {
     [ELEMENTS_ACTIONS_EVENT.CHECKOUT_PRODUCT_ADD_SUCCESS]: ICheckoutProductAddEventData;
     [ELEMENTS_ACTIONS_EVENT.CHECKOUT_PRODUCT_ADD_FAILED]: ICheckoutProductAddFailedEventData;
     [ELEMENTS_ACTIONS_EVENT.CHECKOUT_EXPRESS_CHECKOUT_AVAILABILITY]: ICheckoutExpressCheckoutAvailabilityEventData;
+    [ELEMENTS_ACTIONS_EVENT.CHECKOUT_EXPRESS_CHECKOUT_STARTED]: ICheckoutExpressCheckoutStartedEventData;
     [ELEMENTS_ACTIONS_EVENT.CHECKOUT_PAYMENT_FORM_FAILED]: ICheckoutPaymentFormFailedEventData;
 }
 export type SpecificActionEvent = keyof IElementsActionsEventsMap;

package/dist/types/enums/core.enum.d.ts

@@ -61,6 +61,7 @@ export declare const ELEMENTS_ACTIONS_EVENT: {
     readonly CHECKOUT_PRODUCT_ADD_SUCCESS: "checkout_product_add_success";
     readonly CHECKOUT_PRODUCT_ADD_FAILED: "checkout_product_add_failed";
     readonly CHECKOUT_EXPRESS_CHECKOUT_AVAILABILITY: "checkout_express_checkout_availability";
+    readonly CHECKOUT_EXPRESS_CHECKOUT_STARTED: "checkout_express_checkout_started";
     readonly CHECKOUT_PAYMENT_FORM_FAILED: "checkout_payment_form_failed";
 };
 export declare const ELEMENTS_FORM: {

package/dist/types/index.checkout.d.ts

@@ -1,9 +1,10 @@
 import { ElementsCheckout } from '@/clients/checkout';
 import type { DebugMode, ElementsEnv } from '@/enums';
 import { DEBUG_MODE, ELEMENTS_ENV } from '@/enums';
-import type { IElementsCheckoutActions, IElementsCheckoutClient } from '@/interfaces/client.interface';
+import type { IAnalyticsAddress, IAnalyticsAddressFailure, IAnalyticsAvailability, IAnalyticsFulfillmentAvailability, IAnalyticsItem, IAnalyticsItemList } from '@/interfaces/analytics.interface';
+import type { IAnalyticsActions, IElementsCheckoutActions, IElementsCheckoutClient } from '@/interfaces/client.interface';
 import type { IInjectedComponent } from '@/interfaces/component.interface';
 import type { ILiquidCommerceElementsCheckoutClientConfig } from '@/interfaces/config.interface';
 import type { IInjectCheckoutParams, IInjectExpressCheckoutParams } from '@/interfaces/injection.interface';
-export type { DebugMode, ElementsEnv, IElementsCheckoutActions, IElementsCheckoutClient, IInjectCheckoutParams, IInjectExpressCheckoutParams, IInjectedComponent, ILiquidCommerceElementsCheckoutClientConfig, };
+export type { DebugMode, ElementsEnv, IAnalyticsActions, IAnalyticsAddress, IAnalyticsAddressFailure, IAnalyticsAvailability, IAnalyticsFulfillmentAvailability, IAnalyticsItem, IAnalyticsItemList, IElementsCheckoutActions, IElementsCheckoutClient, IInjectCheckoutParams, IInjectExpressCheckoutParams, IInjectedComponent, ILiquidCommerceElementsCheckoutClientConfig, };
 export { DEBUG_MODE, ELEMENTS_ENV, ElementsCheckout };

package/dist/types/index.d.ts

@@ -3,6 +3,7 @@ export * from './clients/main';
 export * from './core/sdk-error-handler';
 export * from './enums';
 export type { LiquidCommerceGlobal } from './global';
+export * from './interfaces/analytics.interface';
 export * from './interfaces/api';
 export * from './interfaces/client.interface';
 export * from './interfaces/component.interface';

package/dist/types/interfaces/analytics.interface.d.ts

@@ -0,0 +1,41 @@
+import type { FulfillmentType } from '@/enums';
+import type { IAddressAddress, IAddressCoordinates } from '@/interfaces/api/address.interface';
+export interface IAnalyticsItem {
+    id: string;
+    name: string;
+    brand?: string;
+    size?: string;
+    categoryPath?: string;
+    price?: number;
+    quantity?: number;
+    type?: string;
+    subType?: string;
+    image?: string;
+    upc?: string;
+    groupingId?: string;
+    index?: number;
+}
+export interface IAnalyticsItemList {
+    id?: string;
+    name?: string;
+}
+export interface IAnalyticsAddress {
+    placesId?: string;
+    formattedAddress?: string;
+    address: Partial<IAddressAddress>;
+    coordinates?: IAddressCoordinates;
+}
+export interface IAnalyticsAddressFailure {
+    placesId?: string;
+    formattedAddress?: string;
+    address?: Partial<IAddressAddress>;
+    error: string;
+}
+export interface IAnalyticsAvailability {
+    item: IAnalyticsItem;
+    reason: string;
+    address?: Partial<IAddressAddress>;
+}
+export interface IAnalyticsFulfillmentAvailability extends IAnalyticsAvailability {
+    fulfillmentType: FulfillmentType;
+}

package/dist/types/interfaces/client.interface.d.ts

@@ -1,4 +1,5 @@
 import type { IAddressActions } from '@/core/client/actions/client-address-action.service';
+import type { IAnalyticsActions } from '@/core/client/actions/client-analytics-action.service';
 import type { ICartActions } from '@/core/client/actions/client-cart-action.service';
 import type { ICheckoutActions } from '@/core/client/actions/client-checkout-action.service';
 import type { IProductActions } from '@/core/client/actions/client-product-action.service';
@@ -7,6 +8,7 @@ import type { IAddressOptions } from '@/modules/address/address.interface';
 import type { IInjectedComponent } from './component.interface';
 import type { UpdateAddressComponent, UpdateCartComponent, UpdateCheckoutComponent, UpdateComponentGlobalConfigs, UpdateProductComponent, UpdateProductListComponent } from './configs';
 import type { IBuilderInjectElementParams, IInjectCheckoutBuilderParams, IInjectCheckoutParams, IInjectExpressCheckoutParams, IInjectProductElement, IInjectProductListFiltersParams, IInjectProductListParams, IInjectProductListSearchParams } from './injection.interface';
+export type { IAnalyticsActions };
 export interface ILiquidCommerceElementsUIMethod {
     cartButton(containerId: string, showItemsCount?: boolean): void;
     floatingCartButton(showItemsCount?: boolean): void;
@@ -20,6 +22,7 @@ export interface ILiquidCommerceElementsActions {
     address: IAddressActions;
     cart: ICartActions;
     checkout: ICheckoutActions;
+    analytics: IAnalyticsActions;
 }
 export interface IElementsCheckoutActions extends Omit<ICheckoutActions, 'openCheckout' | 'closeCheckout' | 'toggleCheckout'> {
 }
@@ -28,6 +31,7 @@ export interface IElementsCheckoutClient {
     injectExpressCheckout: (params: IInjectExpressCheckoutParams) => Promise<IInjectedComponent | null>;
     actions: {
         checkout: IElementsCheckoutActions;
+        analytics: IAnalyticsActions;
     };
     destroy(): void;
 }
@@ -66,6 +70,7 @@ export interface ILiquidCommerceElementsCheckoutClient {
     injectCheckout(params: IInjectCheckoutParams): Promise<IInjectedComponent | null>;
     actions: {
         checkout: IElementsCheckoutActions;
+        analytics: IAnalyticsActions;
     };
     destroy(): void;
 }

package/dist/types/interfaces/config.interface.d.ts

@@ -14,6 +14,7 @@ export interface ILiquidCommerceElementsDevelopmentConfig {
     customApiUrl?: string;
     openShadowDom?: boolean;
     mockMode?: boolean;
+    enableExpressCheckout?: boolean;
 }
 export interface IClientCustomThemeConfig {
     global?: UpdateComponentGlobalConfigs;

package/dist/types/modules/cart/cart.commands.d.ts

@@ -1,5 +1,6 @@
 import { BaseCommand } from '@/core/command/base-command.service';
 import type { IBaseCartEventData, ICartShopRetailerEventData } from '@/core/pubsub/interfaces/cart.interface';
+import type { ICartStore } from '@/core/store/interfaces/cart.interface';
 export interface AddItemParams {
     fulfillmentId: string;
     partNumber: string;
@@ -19,7 +20,8 @@ export declare class CartCommands extends BaseCommand {
     updateItemEngraving(productItemId: string, engravingLines: string[]): Promise<void>;
     addItem(params: AddItemParams): Promise<void>;
     handleGoToCheckout(): Promise<void>;
-    private trackBeginCheckout;
+    trackViewCart(): void;
+    trackBeginCheckout(cartStore: ICartStore): void;
     private resolveCheckoutRedirectUrl;
     applyPromoCode(promoCode: string): Promise<void>;
     removePromoCode(): Promise<void>;

package/dist/types/modules/checkout/checkout.commands.d.ts

@@ -135,4 +135,12 @@ export declare class CheckoutCommands extends BaseCommand {
     private dataForCheckoutPrepare;
     private normalizeForApi;
     getDetails(): ICheckoutDetailsEventData;
+    trackBeginCheckout(): void;
+    trackPresaleCheckoutStart(): void;
+    reportExpressCheckoutStarted({ wallet, reportBeginCheckout }: {
+        wallet: string;
+        reportBeginCheckout: boolean;
+    }): void;
+    private checkoutItemsForAnalytics;
+    private toAnalyticsItem;
 }

package/dist/types/modules/checkout/components/checkout-express-checkout.component.d.ts

@@ -8,6 +8,7 @@ export declare class CheckoutExpressCheckoutComponent extends BaseComponent<IChe
     private section;
     private walletHost;
     private completionElement;
+    private beginCheckoutReported;
     private stripe;
     private stripeElements;
     private expressElement;

package/dist/types/modules/product-list/product-list.commands.d.ts

@@ -28,4 +28,9 @@ export declare class ProductListCommands extends BaseCommand {
     selectFulfillment: (slug: string, productId: string, selectedFulfillmentId: string) => Promise<void>;
     updateQuantity: (slug: string, productId: string, quantity: number) => void;
     saveEngravingLines(slug: string, productId: string, engravingLines: string[]): void;
+    private trackListPage;
+    trackSelectItem(slug: string, productId: string): void;
+    trackSearch(searchTerm: string): void;
+    private toAnalyticsItem;
+    private getListName;
 }

package/dist/types/ssr/stub.checkout.d.ts

@@ -1,6 +1,7 @@
 export type { DebugMode, ElementsEnv } from '../enums/core.enum';
 export { DEBUG_MODE, ELEMENTS_ENV } from '../enums/core.enum';
-export type { IElementsCheckoutActions, IElementsCheckoutClient, } from '../interfaces/client.interface';
+export type { IAnalyticsAddress, IAnalyticsAddressFailure, IAnalyticsAvailability, IAnalyticsFulfillmentAvailability, IAnalyticsItem, IAnalyticsItemList, } from '../interfaces/analytics.interface';
+export type { IAnalyticsActions, IElementsCheckoutActions, IElementsCheckoutClient, } from '../interfaces/client.interface';
 export type { IInjectedComponent } from '../interfaces/component.interface';
 export type { ILiquidCommerceElementsCheckoutClientConfig } from '../interfaces/config.interface';
 export declare function ElementsCheckout(..._args: any[]): Promise<null>;

package/dist/types/ssr/stub.d.ts

@@ -1,7 +1,8 @@
 export { SDKError, isSDKError } from '../core/sdk-error-handler';
 export type { CartEventLevel, CartEventType, CheckoutEventLevel, CheckoutEventType, ComponentType, DebugMode, DisplayModeType, ElementsEnv, FulfillmentType, NavigationSourceType, } from '../enums/core.enum';
 export { CART_EVENT_LEVEL, CART_EVENT_TYPE, CHECKOUT_EVENT_LEVEL, CHECKOUT_EVENT_TYPE, COMPONENT_TYPE, DEBUG_MODE, DISPLAY_MODE, ELEMENTS_ACTIONS_EVENT, ELEMENTS_ENV, ELEMENTS_FORM, FULFILLMENT_TYPE, NAVIGATION_SOURCE, } from '../enums/core.enum';
-export type { ILiquidCommerceElementsActions, ILiquidCommerceElementsBuilderClient, ILiquidCommerceElementsClient, } from '../interfaces/client.interface';
+export type { IAnalyticsAddress, IAnalyticsAddressFailure, IAnalyticsAvailability, IAnalyticsFulfillmentAvailability, IAnalyticsItem, IAnalyticsItemList, } from '../interfaces/analytics.interface';
+export type { IAnalyticsActions, ILiquidCommerceElementsActions, ILiquidCommerceElementsBuilderClient, ILiquidCommerceElementsClient, } from '../interfaces/client.interface';
 export type { IInjectedComponent } from '../interfaces/component.interface';
 export type { IElementsGTMConfig, IElementsProxyConfig, ILiquidCommerceElementsBuilderConfig, ILiquidCommerceElementsCheckoutConfig, ILiquidCommerceElementsConfig, ILiquidCommerceElementsDevelopmentConfig, } from '../interfaces/config.interface';
 export type * from '../interfaces/configs';

package/docs/v1/README.md

@@ -52,6 +52,7 @@ Complete API documentation:
 - **[Address Actions](./api/actions/address-actions.md)** - `actions.address.*`
 - **[Cart Actions](./api/actions/cart-actions.md)** - `actions.cart.*`
 - **[Checkout Actions](./api/actions/checkout-actions.md)** - `actions.checkout.*`
+- **[Analytics Actions](./api/actions/analytics-actions.md)** - `actions.analytics.*`
 
 ### Architecture (To Be Done In Future Versions)
 

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

@@ -0,0 +1,326 @@
+# Analytics Actions API
+
+Analytics actions report shopper steps that **your own UI** renders to the same Google Tag Manager /
+GA4 stream that Elements components report to. Use them when you build part of the shopping
+experience yourself — a product page, an address picker, a cart — and use Elements for the rest,
+typically the checkout. They are available on the full client (`actions.analytics.*`) and on the
+checkout-only client (`ElementsCheckout(...).actions.analytics.*`).
+
+Each action pushes a GA4 event onto `window.dataLayer` in exactly the shape the SDK's own components
+use — the same event name, the same `items[]` fields, the same `tenant_*` source fields and
+`send_to` targets — so your reports and GTM triggers treat them like any other Elements event. See
+[Analytics & Google Tag Manager](../../reference/analytics.md) for how the containers are loaded and
+how events are queued.
+
+## What to report, and what not to
+
+- **Report only steps your UI renders.** A step an Elements component renders is already reported
+  by that component: reporting it again counts it twice. A product shown with `injectProductElement`
+  sends its own `view_item`, and adding it to the cart from that component sends `add_to_cart` and
+  `view_cart`. A list placed with `injectProductList` sends `view_item_list`, `select_item` and, from
+  its search box, `search`. The Elements cart sends `view_cart` when it opens and `remove_from_cart`
+  when an item goes.
+- **The checkout reports itself.** `add_shipping_info`, `add_payment_info`, `purchase`, and the promo
+  code and gift card events come from the Elements checkout, so there are no actions for them.
+- **Report once per state, not once per render.** A framework that re-renders, or runs effects
+  twice in development, should guard each report with the state it describes (for example the
+  product and size a `view_item` was sent for).
+- **Where events go.** Events are sent only in `production` and `staging`, never in Builder mode.
+  They target the partner's enabled LiquidCommerce and partner GTM containers through `send_to`.
+  When neither container is enabled, an event still goes onto a `window.dataLayer` that is already on
+  the page — your own GTM's, for example — without `send_to`, exactly as the SDK's own events do.
+  Events reported before GTM finishes initializing are queued and sent once it is ready.
+- **Reporting never breaks your page.** Malformed input does not throw: the event is skipped and a
+  warning is logged (visible with `debugMode: 'console'`, and sent to LiquidCommerce telemetry).
+
+## The item
+
+Every ecommerce action takes `IAnalyticsItem`, built from the product data your page already has:
+
+```typescript
+interface IAnalyticsItem {
+  id: string;            // the selected size's id → item_id and product_id
+  name: string;          // → item_name
+  brand?: string;
+  size?: string;         // "750 ML"
+  categoryPath?: string; // product catPath, "spirits > whiskey > bourbon" → item_category 1–3
+  price?: number;        // unit price in CENTS, as product responses carry it → dollars
+  quantity?: number;
+  type?: string;
+  subType?: string;
+  image?: string;
+  upc?: string;
+  groupingId?: string;   // product salsifyGrouping
+  index?: number;        // position in a list (viewItemList / selectItem)
+}
+```
+
+From a product response (`getProductAvailabilityByState`, or the availability API your page loads
+the product with):
+
+```javascript
+const product = response.products[0];
+const size = product.sizes[selectedSizeId];
+
+const item = {
+  id: size.id,
+  name: product.name,
+  brand: product.brand,
+  size: size.size,
+  categoryPath: product.catPath,
+  price: selectedVariant ? selectedVariant.price : product.priceInfo.average,
+  type: product.type,
+  subType: product.subType,
+  image: size.image,
+  upc: size.upc,
+  groupingId: product.salsifyGrouping,
+};
+```
+
+`price` is in cents and is sent in dollars, like every Elements ecommerce event. Before the shopper
+has an address, the SDK's own product component reports the product's average price; report the
+selected variant's price once there is one.
+
+An event is skipped, with a warning naming the problem, when an item has no `id` or `name`, a
+negative or non-numeric `price`, a `quantity` that is not a positive integer, an `index` that is not
+a non-negative integer, or a non-string text field; when a list of items is empty; when a list, an
+option, an address field or coordinates have the wrong type; or when a `reason` / `error` is missing.
+An omitted or empty `placesId` / `formattedAddress` is left out of the event rather than sent blank.
+
+---
+
+## actions.analytics.search()
+
+`search` — the shopper searches the catalog with your own search box. Sent as `search_term`, trimmed.
+A product list's own search box reports its searches itself.
+
+```typescript
+search(searchTerm: string): void
+```
+
+```javascript
+actions.analytics.search(input.value);
+```
+
+---
+
+## actions.analytics.viewItem()
+
+`view_item` — the shopper sees a product. Report it when the product is shown and again when the
+shopper switches size, as the SDK's product component does.
+
+```typescript
+viewItem(item: IAnalyticsItem): void
+```
+
+```javascript
+actions.analytics.viewItem(item);
+```
+
+---
+
+## actions.analytics.viewItemList()
+
+`view_item_list` — the shopper sees a list of products.
+
+```typescript
+viewItemList(items: IAnalyticsItem[], list?: { id?: string; name?: string }): void
+```
+
+```javascript
+actions.analytics.viewItemList(
+  products.map((item, index) => ({ ...item, index })),
+  { id: 'holiday-gifts', name: 'Holiday Gifts' }
+);
+```
+
+---
+
+## actions.analytics.selectItem()
+
+`select_item` — the shopper picks a product from a list.
+
+```typescript
+selectItem(item: IAnalyticsItem, list?: { id?: string; name?: string }): void
+```
+
+---
+
+## actions.analytics.addToCart()
+
+`add_to_cart` — `item.quantity` is the quantity added (default 1). `value` is `price × quantity`.
+
+```typescript
+addToCart(item: IAnalyticsItem): void
+```
+
+Report it when the shopper commits to the product in your UI. `actions.cart.addProduct()` and
+`actions.checkout.addProduct()` already report it (the latter reports `begin_checkout` too); `actions.checkout.addAnonymousProduct()` does
+not, because hosts often call it ahead of time to prepare a checkout before the shopper commits.
+
+```javascript
+actions.analytics.addToCart({ ...item, quantity: 2 });
+```
+
+---
+
+## actions.analytics.removeFromCart()
+
+`remove_from_cart` — `item.quantity` is the quantity removed.
+
+```typescript
+removeFromCart(item: IAnalyticsItem): void
+```
+
+---
+
+## actions.analytics.viewCart()
+
+`view_cart` — the shopper sees a cart your UI renders.
+
+```typescript
+viewCart(items: IAnalyticsItem[]): void
+```
+
+---
+
+## actions.analytics.beginCheckout()
+
+`begin_checkout` — the shopper commits to buying `items`. `value` is the sum of `price × quantity`.
+
+```typescript
+beginCheckout(items: IAnalyticsItem[], options?: { coupon?: string }): void
+```
+
+```javascript
+// "Proceed to checkout" in your own UI, before injecting the Elements checkout
+actions.analytics.addToCart({ ...item, quantity });
+actions.analytics.beginCheckout([{ ...item, quantity }], { coupon: 'WELCOME10' });
+await client.injectCheckout({ containerId: 'checkout', checkoutId });
+```
+
+Report it when **you** inject the checkout (`injectCheckout()` / `injectCheckoutElement()`) after
+your own "Proceed" control. Don't report it when Elements started the checkout — it reports these
+itself:
+
+- the Elements cart's Checkout button, including when it redirects to your checkout page
+  (`checkout.pageUrl`) — so a page that injects the checkout for a shopper arriving from that
+  button must not report it again;
+- `actions.checkout.addProduct()`;
+- `actions.checkout.openCheckout()` and `toggleCheckout()` when they open the drawer;
+- a presale added from the product component, which goes straight to checkout;
+- the first wallet tap on express buttons placed on their own (below).
+
+Wallet (Apple Pay / Google Pay) buttons placed on their own with `injectExpressCheckout` /
+`injectExpressCheckoutElement` report `begin_checkout` themselves on the first tap — a wallet order
+never passes through your "Proceed" control. Don't report it for them. If the buttons sit on your
+product page and the checkout behind them was created with `addAnonymousProduct`, report the add
+when the shopper taps: the tap happens inside Stripe's frame, and
+[`lce:actions.checkout_express_checkout_started`](../../guides/events.md) is how your page hears of
+it.
+
+```javascript
+window.addEventListener('lce:actions.checkout_express_checkout_started', () => {
+  actions.analytics.addToCart({ ...item, quantity });
+});
+```
+
+---
+
+## actions.analytics.addressUpdated()
+
+`address_updated` — an address the shopper chose in your UI resolved.
+
+```typescript
+addressUpdated(address: {
+  placesId?: string;          // → address_id
+  formattedAddress?: string;
+  address: Partial<IAddressAddress>;
+  coordinates?: IAddressCoordinates;
+}): void
+```
+
+```javascript
+actions.analytics.addressUpdated({
+  placesId,
+  formattedAddress: details.formattedAddress,
+  address: details.address,
+  coordinates: details.coordinates,
+});
+```
+
+`actions.address.setAddressByPlacesId()` and `setAddressManually()` already report it.
+
+---
+
+## actions.analytics.addressFailed()
+
+`address_failed` — an address the shopper chose could not be resolved or used.
+
+```typescript
+addressFailed(failure: {
+  placesId?: string;
+  formattedAddress?: string;
+  address?: Partial<IAddressAddress>;
+  error: string;              // → address_error_message
+}): void
+```
+
+---
+
+## actions.analytics.productNoAvailability()
+
+`product_no_availability` — no size of the product sells where the shopper is.
+
+```typescript
+productNoAvailability(details: {
+  item: IAnalyticsItem;       // the product, keyed on the selected size
+  reason: string;             // → availability_reason
+  address?: Partial<IAddressAddress>;
+}): void
+```
+
+The no-availability events carry `product_*` fields rather than an `items[]` array, as the SDK's own
+do, and `product_price` is sent **in cents** (the raw `item.price`), matching them.
+
+---
+
+## actions.analytics.productSizeNoAvailability()
+
+`product_size_no_availability` — the selected size has no fulfillment at the shopper's address,
+though another size does. `item.id` and `item.size` are sent as `size_id` and `size_name`.
+
+```typescript
+productSizeNoAvailability(details: { item: IAnalyticsItem; reason: string; address?: Partial<IAddressAddress> }): void
+```
+
+---
+
+## actions.analytics.productFulfillmentNoAvailability()
+
+`product_fulfillment_no_availability` — one fulfillment method (`onDemand` or `shipping`) can't be
+used for the selected size: not offered there, or the retailer is closed.
+
+```typescript
+productFulfillmentNoAvailability(details: {
+  item: IAnalyticsItem;
+  reason: string;
+  address?: Partial<IAddressAddress>;
+  fulfillmentType: 'onDemand' | 'shipping';
+}): void
+```
+
+```javascript
+actions.analytics.productFulfillmentNoAvailability({
+  item,
+  reason: 'Not available in NY',
+  address: details.address,
+  fulfillmentType: 'onDemand',
+});
+```
+
+## Related
+
+- [Analytics & Google Tag Manager](../../reference/analytics.md)
+- [Product Actions](./product-actions.md) · [Address Actions](./address-actions.md) · [Cart Actions](./cart-actions.md) · [Checkout Actions](./checkout-actions.md)
+- [TypeScript Types](../typescript-types.md)