@liquidcommerce/elements-sdk 2.7.43 → 2.7.45

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

@@ -0,0 +1,53 @@
+import { BaseComponent } from '@/core/base-component.service';
+import type { ICheckoutComponent } from '@/interfaces/configs';
+export declare class CheckoutDeliverySchedulingComponent extends BaseComponent<null, ICheckoutComponent> {
+    private draft;
+    private dialog;
+    private paintScheduled;
+    private error;
+    private pendingFocus;
+    private restoreTrigger;
+    private releaseFocusTrap;
+    private readonly focusManager;
+    private handledExpired;
+    private loadToken;
+    private announcedNotice;
+    private timesScroll;
+    constructor();
+    private get busy();
+    private get expiredIds();
+    protected afterRender(): void;
+    protected onStoreChanged(): boolean;
+    private update;
+    private paint;
+    private showDialog;
+    private settle;
+    private keepTimeInView;
+    protected disconnected(): void;
+    private endPicker;
+    private draftFulfillment;
+    private openForNewlyExpired;
+    private dayKey;
+    private todayKey;
+    private draftScheduling;
+    private openPicker;
+    private loadSlots;
+    private whenIdle;
+    private closePicker;
+    private saveDraft;
+    private createGroup;
+    private get severalGroups();
+    private retailerOf;
+    private pickerTitle;
+    private summaryText;
+    private radio;
+    private createDates;
+    private createTimes;
+    private createNotice;
+    private createLoading;
+    private createDialogShell;
+    private fillDialog;
+    private captureViewState;
+    private createRows;
+    protected template(): HTMLElement[];
+}

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;
@@ -19,6 +20,7 @@ export declare class CheckoutExpressCheckoutComponent extends BaseComponent<IChe
     private hasAvailableWallets;
     private availableWallets;
     private hasSettledAvailability;
+    private scheduleReadyAtMount;
     private lastPublishedAvailability;
     get hostClasses(): string[];
     constructor();
@@ -27,6 +29,7 @@ export declare class CheckoutExpressCheckoutComponent extends BaseComponent<IChe
     private get isCompletingExpress();
     private get isButtonsOnly();
     private get isReadyForPayment();
+    private get isDeliveryScheduleReady();
     private get isGiftOrder();
     protected template(): HTMLElement[];
     protected afterRender(): void;

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

@@ -7,6 +7,8 @@ export declare class CheckoutItemComponent extends BaseComponent<ICheckoutItemCo
     get hostClasses(): string[];
     constructor();
     onStoreChanged(changes: IOnStoreChanged[]): boolean | undefined;
+    private deliveryExpectation;
+    private updateDeliveryExpectation;
     private updateEngravingElement;
     private setupMinimumPurchaseAlert;
     private updateTrashButtonState;

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

@@ -18,6 +18,8 @@ export declare class CheckoutPaymentComponent extends BaseComponent<ICheckoutSen
     get hostClasses(): string[];
     constructor();
     private getInjectedPaymentMethod;
+    private scheduleReady;
+    private deliveryPaymentReady;
     onStoreWatch(changes: IOnStoreChanged[]): void;
     private handleBillingSameAsShippingChange;
     afterRender(): Promise<void>;
@@ -28,6 +30,7 @@ export declare class CheckoutPaymentComponent extends BaseComponent<ICheckoutSen
     private lastAnnouncedPaymentError;
     private updateErrorMessage;
     private showError;
+    private createHeader;
     protected template(): HTMLElement[];
     private handleSaveButtonClick;
     private validatePrerequisites;

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

@@ -6,6 +6,7 @@ export * from './checkout-completed.component';
 export * from './checkout-deliver-to.component';
 export * from './checkout-deliver-to-summary.component';
 export * from './checkout-delivery-method.component';
+export * from './checkout-delivery-scheduling.component';
 export * from './checkout-express-checkout.component';
 export * from './checkout-express-completion.component';
 export * from './checkout-gift-cards.component';

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,8 @@
 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>;
+export type { CheckoutDeliveryScheduling, CheckoutDeliverySelection, DeliveryAvailability, DeliverySlot, } from '../interfaces/api/delivery.interface';

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

@@ -1,10 +1,12 @@
 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';
 export type { IBuilderInjectElementParams, IInjectCheckoutBuilderParams, IInjectCheckoutParams, IInjectProductElement, IInjectProductListFiltersParams, IInjectProductListParams, IInjectProductListSearchParams, ProductListFilterType, } from '../interfaces/injection.interface';
 export declare function Elements(..._args: any[]): Promise<null>;
 export declare function ElementsBuilder(..._args: any[]): Promise<null>;
+export type { CheckoutDeliveryScheduling, CheckoutDeliverySelection, DeliveryAvailability, DeliverySlot, } from '../interfaces/api/delivery.interface';

package/dist/types/utils/delivery-scheduling.d.ts

@@ -0,0 +1,75 @@
+import type { ApiError } from '@/core/api/api-result';
+import type { DeliveryWindowLapse } from '@/core/store/interfaces/checkout.interface';
+import type { StoreService } from '@/core/store/store.service';
+import { type FulfillmentType } from '@/enums';
+import type { ICart } from '@/interfaces/api/cart.interface';
+import type { ICheckoutFulfillment, ICheckoutItem, ICheckoutRetailer, ICheckoutShippingAddress } from '@/interfaces/api/checkout.interface';
+import type { CheckoutDeliveryScheduling, DeliverySlot } from '@/interfaces/api/delivery.interface';
+import type { IFulfillment } from '@/interfaces/api/product.interface';
+export declare const LAPSED_DELIVERY_WINDOW_CODES: readonly string[];
+export declare const DELIVERY_WINDOW_EXPIRED_MESSAGE = "Your delivery window has passed. Choose a new delivery time.";
+export declare const DELIVERY_WINDOW_UNAVAILABLE_MESSAGE = "Your delivery window is no longer available. Choose a new delivery time.";
+export declare const DELIVERY_WINDOW_REQUIRED_MESSAGE = "The store cannot deliver now. Choose a delivery time.";
+export declare const UNSUPPORTED_DELIVERY_SCHEDULING_CODES: readonly string[];
+export declare const DELIVERY_SELECTION_NOT_ACCEPTED_CODE = "delivery_selection_not_accepted";
+export declare const DELIVERY_SELECTION_NOT_ACCEPTED_MESSAGE = "We couldn't save that delivery time. Choose a delivery time again.";
+export declare const SAVED_DELIVERY_WINDOW_LABEL = "Scheduled delivery";
+export declare const DELIVERY_SCHEDULING_UNAVAILABLE_MESSAGE = "Scheduled delivery isn't available for this order right now. We'll deliver as soon as possible.";
+export declare const MULTIPLE_FULFILLMENT_OPTIONS_PER_STORE_CODE = "multiple_fulfillment_options_per_store";
+export declare const MULTIPLE_FULFILLMENT_OPTIONS_PER_STORE_MESSAGE = "Scheduled delivery cannot be combined with another delivery method from the same store. Choose ASAP delivery, or use one delivery method for all items from this store.";
+export declare const CLOSED_STORE_MULTIPLE_FULFILLMENT_OPTIONS_MESSAGE = "This store is closed now. Use one delivery method for all items from this store.";
+export declare function splitStoreMessageFromStore(store: Pick<StoreService, 'get'>): string;
+export declare function splitStoreMessageFromError(error: Pick<ApiError, 'errors'> | null | undefined): string | null;
+export declare function splitStoreRefusalText(error: Pick<ApiError, 'errors'> | null | undefined, store: Pick<StoreService, 'get'>): string;
+export declare function splitStoreMessageFromCart(cart: Pick<ICart, 'retailers'>): string;
+export declare function expiredDeliveryFulfillmentIds(store: Pick<StoreService, 'get'>): string[];
+export declare function deliveryWindowLapseOf(error: Pick<ApiError, 'errors'> | null | undefined): DeliveryWindowLapse;
+export type DeliveryWindowLapseText = 'message' | 'label';
+export declare function deliveryWindowLapseMessage(lapse: DeliveryWindowLapse | null | undefined, text?: DeliveryWindowLapseText): string;
+export declare function lapsedDeliveryWindowMessage(store: Pick<StoreService, 'get'>, fulfillmentId: string, text?: DeliveryWindowLapseText): string;
+export declare function withoutDeliveryWindow(fulfillment: ICheckoutFulfillment): ICheckoutFulfillment;
+export declare function deliveryErrorFulfillmentIds(error: Pick<ApiError, 'errors'> | null | undefined): string[];
+export declare function isLapsedDeliveryWindowError(error: Pick<ApiError, 'errors'> | null | undefined): boolean;
+export declare function isNotAcceptedDeliverySelectionError(error: Pick<ApiError, 'errors'> | null | undefined): boolean;
+export declare function isMultipleFulfillmentOptionsPerStoreError(error: Pick<ApiError, 'errors'> | null | undefined): boolean;
+export declare function isUnsupportedDeliverySchedulingError(error: Pick<ApiError, 'errors'> | null | undefined): boolean;
+export declare function deliveryAddressKey(address: ICheckoutShippingAddress | null | undefined): string;
+export declare function isFutureDeliverySlot(slot: DeliverySlot | null | undefined, now?: number): boolean;
+export declare function selectedDeliverySlot(scheduling: CheckoutDeliveryScheduling | null | undefined): DeliverySlot | null;
+export declare function isLapsedSelectedDeliverySlot(scheduling: CheckoutDeliveryScheduling | null | undefined, now?: number): boolean;
+export declare function deliverySchedulesReady(fulfillments: Record<string, ICheckoutFulfillment>, now?: number, expired?: string[]): boolean;
+export declare function deliveryChoicesMade(fulfillments: Record<string, ICheckoutFulfillment>, expired?: string[]): boolean;
+export declare function hasDeliveryScheduling(fulfillments: Record<string, ICheckoutFulfillment> | null | undefined): boolean;
+export declare function retailerOfFulfillment(retailers: Record<string, ICheckoutRetailer> | null | undefined, fulfillmentId: string): ICheckoutRetailer | undefined;
+export declare function deliveryWindowNeededMessage(store: Pick<StoreService, 'get'>, fulfillmentIds: string[]): string;
+export declare function hasSeveralDeliveryGroups(fulfillments: Record<string, ICheckoutFulfillment> | null | undefined): boolean;
+export declare function deliveryTimeZone(): string;
+export declare function deliveryDateTimeFormat(timezone: string, options: Omit<Intl.DateTimeFormatOptions, 'timeZone'>): Intl.DateTimeFormat;
+export declare function deliveryTimeZoneName(timezone: string, style?: 'short' | 'long'): string;
+export declare function deliveryTimeLabel(slot: DeliverySlot, timezone: string): string;
+export declare function deliveryWindowLabel(slot: DeliverySlot, timezone: string): string;
+export declare function deliveryScheduledLabel(slot: DeliverySlot, timezone: string): string;
+export declare function deliveryCutoffLabel(slot: DeliverySlot, timezone: string): string;
+export interface PlacedDeliveryLine {
+    heading: string;
+    label: string;
+}
+export interface PlacedDelivery {
+    perGroup: boolean;
+    lines: PlacedDeliveryLine[];
+}
+export declare function placedDeliveryLines(fulfillments: Record<string, ICheckoutFulfillment> | null | undefined, retailers: Record<string, ICheckoutRetailer> | null | undefined, items?: Record<string, ICheckoutItem> | null): PlacedDelivery;
+type FulfillmentAvailability = Pick<IFulfillment, 'hourStatus' | 'deliveryAvailability'>;
+type SchedulingAvailability = Pick<IFulfillment, 'deliveryAvailability'>;
+export declare function deliversNow(fulfillment: FulfillmentAvailability): boolean;
+export declare function takesOrdersForLater(fulfillment: SchedulingAvailability, now?: number): boolean;
+export declare function nextScheduledDeliverySlot(fulfillment: SchedulingAvailability, now?: number): DeliverySlot | null;
+export declare function isDeliveryPurchasable(fulfillment: FulfillmentAvailability, now?: number): boolean;
+export declare function isOnDemandUnpurchasable(type: FulfillmentType, fulfillment: FulfillmentAvailability): boolean;
+export declare function preferredOnDemandFulfillment<T extends FulfillmentAvailability>(fulfillments: T[], now?: number): T | undefined;
+export declare function nextArrivalLabel(fulfillment: SchedulingAvailability, now?: number): string | null;
+export declare const DELIVERY_TEXT_LINE_BREAK = "\n";
+export declare function scheduleDeliveryText(fulfillment: SchedulingAvailability, now?: number): string | null;
+export declare function spokenDeliveryText(text: string): string;
+export declare function resolveDeliverySlot(scheduling: CheckoutDeliveryScheduling | undefined, advertised: DeliverySlot, now?: number): DeliverySlot | null;
+export {};

package/dist/types/utils/fulfillment-unavailable.d.ts

@@ -0,0 +1,8 @@
+import type { ApiError } from '@/core/api/api-result';
+export declare const FULFILLMENT_UNAVAILABLE_CODE = "fulfillment_unavailable";
+export interface FulfillmentRetailer {
+    id: string;
+    name: string;
+    fulfillments: Record<string, unknown>;
+}
+export declare function fulfillmentUnavailableMessage(error: Pick<ApiError, 'errors'> | null | undefined, retailers: FulfillmentRetailer[]): string | null;

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)

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
@@ -402,6 +405,7 @@ console.log(`Is Gift: ${checkout.isGift}`);
 
 ```typescript
 interface ICheckoutDetailsEventData {
+  deliveryScheduling: Record<string, CheckoutDeliveryScheduling>; // keyed by fulfillment ID; empty without scheduled delivery
   token: string;
   cartId: string;
   isGift: boolean;
@@ -439,6 +443,47 @@ const availability = await window.LiquidCommerce.elements.actions.checkout
 | `identifiers` | string[] | Yes      | Array of product UPCs, SKUs, or IDs  |
 | `state`       | string   | No       | Two-letter state code (e.g., `'NY'`) |
 
+## Delivery scheduling actions
+
+Available on both `Elements()` and `ElementsCheckout()` when a checkout fulfillment carries `deliveryScheduling` (an AccelPay retailer with scheduled delivery turned on). Checkouts without it keep their usual behaviour, and `getDetails().deliveryScheduling` is an empty map.
+
+### `actions.checkout.loadDeliverySlots(fulfillmentId)`
+
+```typescript
+loadDeliverySlots(fulfillmentId: string): Promise<DeliverySlot[]>
+```
+
+Loads the full list of delivery windows for one fulfillment. Checkout prepare returns the list only on request, so outside this call `deliveryScheduling.slots` is empty and `availability.nextSlot` names the first window. The call sends the whole current checkout to prepare, plus `deliverySlotsFulfillmentId`, and resolves with the windows that can still be ordered. Each window's `cutoff` is the latest time to place the order for it ("Order by"). Show times in `availability.timezone`.
+
+### `actions.checkout.chooseDeliverySlot(fulfillmentId, slotId)`
+
+```typescript
+chooseDeliverySlot(fulfillmentId: string, slotId: string | null): Promise<void>
+```
+
+Saves a window from the last loaded list for one fulfillment, or `null` for as soon as possible (only when `availability.canDeliverNow` is true). The promise resolves after prepare accepts and echoes that exact selection. It rejects malformed arguments, unknown fulfillments, windows that were not offered, concurrent checkout updates and server errors; a rejected save keeps the previously accepted choice, except after `delivery_selection_not_accepted` (below). Slot IDs come from the server; do not build them.
+
+`getDetails().deliveryScheduling[fulfillmentId]` returns the availability, the accepted `selectedSlotId` and `selectedSlot` (the accepted window's `start`, `end` and `cutoff`).
+
+```javascript
+const actions = client.actions.checkout;
+const [fulfillmentId] = Object.keys(actions.getDetails().deliveryScheduling);
+if (fulfillmentId) {
+  const slots = await actions.loadDeliverySlots(fulfillmentId);
+  if (slots.length) await actions.chooseDeliverySlot(fulfillmentId, slots[0].id);
+}
+```
+
+### Expired windows
+
+If a saved window's cutoff passes, or the store's hours or zone rules no longer allow it, before the order is placed, the server answers Place Order, or any other checkout update, with error code `delivery_window_expired` or `delivery_window_unavailable`. Place Order on a store that cannot deliver now with no saved window answers `delivery_window_required`. All three are recovered the same way; only the message differs ("Your delivery window has passed. Choose a new delivery time.", "Your delivery window is no longer available. Choose a new delivery time." or "The store cannot deliver now. Choose a delivery time."). The SDK then clears the window, marks the fulfillment as needing a new choice, shows the message, opens the picker and blocks payment and Place Order until the shopper saves a new choice. An update that hit the error is sent once more without the window, so the shopper's change still applies. Customer, address, payment, tip and notes stay as they were. A custom UI recovers the same way: load the windows again and call `chooseDeliverySlot`.
+
+If prepare did not keep the window that was sent (error code `delivery_selection_not_accepted`, HTTP 409), the SDK drops the window it holds for that fulfillment so no later update sends it again. `chooseDeliverySlot` rejects with "We couldn't save that delivery time. Choose a delivery time again."; on any other update the window is recovered as an unavailable one.
+
+If a store cannot fulfill the selected delivery method at all, pickup included (error code `fulfillment_unavailable`, for example a closed store that offers no delivery window, or no estimate for the address), the SDK shows "W & J Wines & Spirits cannot fulfill this order now. Choose another store or delivery method." in place of the server's message, on loading the checkout, on any checkout update, on Place Order and on the cart's go-to-checkout. The store name comes from the cart or the checkout; when neither names the store, the message starts with "A store in your cart". The error detail carries the LC `retailerId` and `fulfillmentId` of each refused selection, so a custom UI can point at the store the same way. When AccelPay returns no estimates at all, Cloud refuses every selection, so the message names every store in the cart, even when the cause is the address.
+
+When scheduled delivery stops applying to the order (`delivery_scheduling_not_enabled`, `delivery_windows_unsupported` or `delivery_scheduling_unsupported`, and `multiple_fulfillment_groups` from an older server that schedules one group only), the SDK drops the saved window with a re-prepare, keeps the rest of checkout and shows "Scheduled delivery isn't available for this order right now. We'll deliver as soon as possible." The picker does not open; the response no longer carries `deliveryScheduling`, so the delivery time row goes away. Switching the delivery method never carries a window over to the new fulfillment.
+
 ## Use Cases
 
 ### Pre-fill for Logged-In Users