@liquidcommerce/elements-sdk 2.7.0 → 2.7.2

package/docs/gitbook/events.md

@@ -0,0 +1,1765 @@
+# Events
+
+The SDK emits browser events for user actions and state changes. Listen on `window` using `lce:actions.*` and `lce:forms.*`.
+
+## Event shape
+
+All SDK events are native `CustomEvent` objects. The payload lives in `event.detail`:
+
+```ts
+export interface IEventMetadata {
+  eventId: string;
+  namespace: 'actions' | 'forms';
+  event: string;
+  originalEvent: string;
+  actionNamespace?: 'address' | 'product' | 'cart' | 'checkout' | 'other';
+  timestamp: number;
+}
+
+export interface IEnhancedEventData<T> {
+  data: T;
+  metadata: IEventMetadata;
+}
+```
+
+```js
+window.addEventListener('lce:actions.event_name', (event) => {
+  const { data, metadata } = event.detail;
+});
+```
+
+**TypeScript interfaces:** The interface names used below match the SDK type definitions. You can inspect them in your install at `node_modules/@liquidcommerce/elements-sdk/dist/types/core/pubsub/interfaces/*`.
+
+## Namespaces
+
+- `lce:actions.*` - User actions and state changes
+- `lce:forms.*` - Form field interactions (checkout)
+- `lce:actions` - All action events (namespace listener)
+- `lce:forms` - All form events (namespace listener)
+
+Example: listen to every action event:
+
+```js
+window.addEventListener('lce:actions', (event) => {
+  const { metadata } = event.detail;
+  console.log('Action event:', metadata.event);
+});
+```
+
+## Client lifecycle
+
+### `lce:actions.client_ready`
+
+Fired once when the SDK is initialized and safe to use.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface IElementsClientIsReadyEventData {
+  isReady: boolean;
+  message: string;
+  timestamp: number;
+  version?: string;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.client_ready', (event) => {
+  const { data } = event.detail;
+  if (data.isReady) {
+    console.log('Elements SDK ready', data.version);
+  }
+});
+```
+
+## Product events
+
+### `lce:actions.product_loaded`
+
+Product data finished loading into a product component.
+
+**Data shape (TypeScript)**
+
+```ts
+export type FulfillmentType = 'onDemand' | 'shipping';
+
+export interface IProductLoadedEventData {
+  identifier: string;
+  selectedSizeId: string | null;
+  selectedFulfillmentType: FulfillmentType;
+  selectedFulfillmentId: string | null;
+  productHasAvailability: boolean;
+  fulfillmentHasAvailability: boolean;
+  sizes: Record<string, IProductSizeEventData>;
+
+  id: string;
+  name: string;
+  description: string;
+  htmlDescription: string;
+  images: string[];
+  brand: string;
+  region: string;
+  country: string;
+  material: string;
+  abv: string;
+  proof: string;
+  age: string;
+  color: string;
+  flavor: string;
+  variety: string;
+  appellation: string;
+  vintage: string;
+  tastingNotes: string;
+  catPath: string;
+  category: string;
+  classification: string;
+  type: string;
+  subType: string;
+  salsifyGrouping: string;
+  noAvailabilityPrice: number;
+}
+
+export interface IProductSizeEventData {
+  id: string;
+  upc: string;
+  size: string;
+  pack: boolean;
+  packDesc: string;
+  container: string;
+  containerType: string;
+  image: string;
+  uom: string;
+  volume: string;
+  maxQuantityPerOrder: number;
+  attributes: IProductSizeAttributes;
+  onDemandFulfillments: Record<string, IProductFulfillmentEventData>;
+  shippingFulfillments: Record<string, IProductFulfillmentEventData>;
+}
+
+export interface IProductSizeAttributes {
+  presale: IProductPresale;
+  engraving: IProductSizeEngraving;
+}
+
+export interface IProductSizeEngraving {
+  maxLines: number;
+  maxCharsPerLine: number;
+  fee: number;
+  location: string;
+}
+
+export interface IProductPresale {
+  canPurchaseOn: string | null;
+  estimatedShipBy: string | null;
+  isActive: boolean;
+  language: string;
+}
+
+export interface IProductFulfillmentEventData {
+  id: string;
+  type: FulfillmentType;
+  doesAllowGiftCards: boolean;
+  doesAllowPromos: boolean;
+  expectation: string;
+  engravingExpectation: string;
+  fee: number;
+  timezone: string;
+  hourStatus: IProductFulfillmentHourStatus;
+  retailerName: string;
+  retailerAddress: IRetailerAddress;
+  retailerAddressFormatted: string;
+  variant: IProductVariant;
+}
+
+export interface IProductFulfillmentHourStatus {
+  isOpen: boolean;
+  openTime: string;
+  isClosed: boolean;
+  closeTime: string;
+}
+
+export interface IProductVariant {
+  retailerId: string;
+  shippingFulfillmentId: string;
+  onDemandFulfillmentId: string;
+  isEngravable: boolean;
+  partNumber: string;
+  price: number;
+  stock: number;
+}
+
+export type IRetailerAddress = IAddressAddress & IAddressCoordinates;
+
+export interface IAddressAddress {
+  one: string;
+  two: string;
+  city: string;
+  state: string;
+  zip: string;
+  country: string;
+}
+
+export interface IAddressCoordinates {
+  latitude: number;
+  longitude: number;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.product_loaded', (event) => {
+  const { data } = event.detail;
+  console.log(`Loaded ${data.name} (${data.identifier})`);
+});
+```
+
+### `lce:actions.product_add_to_cart`
+
+User triggered add-to-cart from a product component. Use cart events to confirm success or failure.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface IProductAddToCartEventData {
+  identifier: string;
+  fulfillmentId: string;
+  partNumber: string;
+  quantity: number;
+  engravingLines?: string[];
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.product_add_to_cart', (event) => {
+  const { data } = event.detail;
+  gtag('event', 'add_to_cart_click', { item_id: data.identifier, quantity: data.quantity });
+});
+```
+
+### `lce:actions.product_size_changed`
+
+User changed the selected size.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface IProductSizeChangedEventData {
+  identifier: string;
+  selectedSizeId: string;
+  selectedSize: string;
+  previousSizeId: string;
+  previousSize: string;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.product_size_changed', (event) => {
+  const { data } = event.detail;
+  console.log('Size changed to', data.selectedSize);
+});
+```
+
+### `lce:actions.product_fulfillment_type_changed`
+
+User switched fulfillment type (for example shipping vs onDemand).
+
+**Data shape (TypeScript)**
+
+```ts
+export type FulfillmentType = 'onDemand' | 'shipping';
+
+export interface IProductFulfillmentTypeChangedEventData {
+  identifier: string;
+  selectedFulfillmentType: FulfillmentType;
+  selectedFulfillmentId: string | null;
+  previousFulfillmentType: FulfillmentType;
+  previousFulfillmentId: string | null;
+  fulfillmentHasAvailability: boolean;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.product_fulfillment_type_changed', (event) => {
+  const { data } = event.detail;
+  console.log('Fulfillment type:', data.selectedFulfillmentType);
+});
+```
+
+### `lce:actions.product_fulfillment_changed`
+
+User selected a different fulfillment option or retailer.
+
+**Data shape (TypeScript)**
+
+```ts
+export type FulfillmentType = 'onDemand' | 'shipping';
+
+export interface IProductFulfillmentChangedEventData {
+  identifier: string;
+  selectedFulfillmentId: string;
+  selectedFulfillmentType: FulfillmentType;
+  previousFulfillmentId: string;
+  previousFulfillmentType: FulfillmentType;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.product_fulfillment_changed', (event) => {
+  const { data } = event.detail;
+  console.log('Fulfillment changed:', data.selectedFulfillmentId);
+});
+```
+
+### `lce:actions.product_quantity_increase`
+
+Product quantity increased.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface IProductQuantityChangedEventData {
+  identifier: string;
+  quantity: number;
+  previousQuantity: number;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.product_quantity_increase', (event) => {
+  const { data } = event.detail;
+  console.log('Quantity increased to', data.quantity);
+});
+```
+
+### `lce:actions.product_quantity_decrease`
+
+Product quantity decreased.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface IProductQuantityChangedEventData {
+  identifier: string;
+  quantity: number;
+  previousQuantity: number;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.product_quantity_decrease', (event) => {
+  const { data } = event.detail;
+  console.log('Quantity decreased to', data.quantity);
+});
+```
+
+## Address events
+
+### `lce:actions.address_updated`
+
+Address successfully set or changed.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface IAddressActionEventData {
+  googlePlacesId: string;
+  formattedAddress: string;
+  address: IAddressAddress;
+  coordinates: IAddressCoordinates;
+}
+
+export interface IAddressAddress {
+  one: string;
+  two: string;
+  city: string;
+  state: string;
+  zip: string;
+  country: string;
+}
+
+export interface IAddressCoordinates {
+  latitude: number;
+  longitude: number;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.address_updated', (event) => {
+  const { data } = event.detail;
+  console.log('Address set:', data.formattedAddress);
+});
+```
+
+### `lce:actions.address_cleared`
+
+Address removed.
+
+**Data shape (TypeScript)**
+
+```ts
+export type AddressClearedEventData = boolean;
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.address_cleared', () => {
+  console.log('Address cleared');
+});
+```
+
+### `lce:actions.address_failed`
+
+Address set failed (validation, geocode, etc.).
+
+**Data shape (TypeScript)**
+
+```ts
+export interface IAddressFailedEventData {
+  googlePlacesId: string;
+  formattedAddress: string;
+  address: IAddressAddress;
+  coordinates: IAddressCoordinates;
+  error: string;
+}
+
+export interface IAddressAddress {
+  one: string;
+  two: string;
+  city: string;
+  state: string;
+  zip: string;
+  country: string;
+}
+
+export interface IAddressCoordinates {
+  latitude: number;
+  longitude: number;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.address_failed', (event) => {
+  const { data } = event.detail;
+  console.error('Address error:', data.error);
+});
+```
+
+## Cart events
+
+### `lce:actions.cart_loaded`
+
+Cart state loaded or synced.
+
+**Data shape (TypeScript)**
+
+```ts
+export type FulfillmentType = 'onDemand' | 'shipping';
+
+export interface IBaseCartEventData {
+  cartId: string;
+  promoCodeDiscount: number | null;
+  subtotal: number;
+  itemCount: number;
+  items: Record<string, ICartItem>;
+  retailers: Record<string, ICartRetailer>;
+  location: {
+    placesId: string;
+    formattedAddress: string;
+    address: IAddressAddress;
+    coordinates: IAddressCoordinates;
+  } | null;
+}
+
+export interface ICartItem {
+  id: string;
+  variantId: string;
+  liquidId: string;
+  retailerId: string;
+  partNumber: string;
+  fulfillmentId: string;
+  upc: string;
+  sku: string;
+  salsifyGrouping: string;
+  catPath: string;
+  volume: string;
+  uom: string;
+  pack: boolean;
+  packDesc: string;
+  container: string;
+  containerType: string;
+  name: string;
+  brand: string;
+  size: string;
+  price: number;
+  quantity: number;
+  maxQuantity: number;
+  unitPrice: number;
+  mainImage: string;
+  attributes: ICartItemAttributes;
+}
+
+export interface ICartItemAttributes {
+  engraving: ICartItemEngraving;
+  presale: IProductPresale;
+}
+
+export interface ICartItemEngraving {
+  isEngravable: boolean;
+  hasEngraving: boolean;
+  fee: number;
+  maxCharsPerLine: number;
+  maxLines: number;
+  location: string;
+  lines: string[];
+}
+
+export interface IProductPresale {
+  canPurchaseOn: string | null;
+  estimatedShipBy: string | null;
+  isActive: boolean;
+  language: string;
+}
+
+export interface ICartRetailer {
+  id: string;
+  name: string;
+  subtotal: number;
+  itemsQuantity: number;
+  fulfillments: Record<string, ICartFulfillment>;
+}
+
+export interface ICartFulfillment {
+  id: string;
+  canEngrave: boolean;
+  type: FulfillmentType;
+  expectation: string;
+  engravingExpectation: string;
+  itemIds: string[];
+  subtotal: number;
+  hasUnmetMinimumPurchaseAmount: boolean;
+  minimumPurchaseAmount: number;
+}
+
+export interface IAddressAddress {
+  one: string;
+  two: string;
+  city: string;
+  state: string;
+  zip: string;
+  country: string;
+}
+
+export interface IAddressCoordinates {
+  latitude: number;
+  longitude: number;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.cart_loaded', (event) => {
+  const { data } = event.detail;
+  console.log(`Cart ${data.cartId} has ${data.itemCount} items`);
+});
+```
+
+### `lce:actions.cart_opened`
+
+Cart drawer opened.
+
+**Data shape (TypeScript)**
+
+```ts
+export type CartOpenedEventData = boolean;
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.cart_opened', () => {
+  document.body.classList.add('cart-open');
+});
+```
+
+### `lce:actions.cart_closed`
+
+Cart drawer closed.
+
+**Data shape (TypeScript)**
+
+```ts
+export type CartClosedEventData = boolean;
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.cart_closed', () => {
+  document.body.classList.remove('cart-open');
+});
+```
+
+### `lce:actions.cart_updated`
+
+Cart totals/items changed.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICartUpdatedEventData {
+  previous: IBaseCartEventData;
+  current: IBaseCartEventData;
+}
+
+export type FulfillmentType = 'onDemand' | 'shipping';
+
+export interface IBaseCartEventData {
+  cartId: string;
+  promoCodeDiscount: number | null;
+  subtotal: number;
+  itemCount: number;
+  items: Record<string, ICartItem>;
+  retailers: Record<string, ICartRetailer>;
+  location: {
+    placesId: string;
+    formattedAddress: string;
+    address: IAddressAddress;
+    coordinates: IAddressCoordinates;
+  } | null;
+}
+
+export interface ICartItem {
+  id: string;
+  variantId: string;
+  liquidId: string;
+  retailerId: string;
+  partNumber: string;
+  fulfillmentId: string;
+  upc: string;
+  sku: string;
+  salsifyGrouping: string;
+  catPath: string;
+  volume: string;
+  uom: string;
+  pack: boolean;
+  packDesc: string;
+  container: string;
+  containerType: string;
+  name: string;
+  brand: string;
+  size: string;
+  price: number;
+  quantity: number;
+  maxQuantity: number;
+  unitPrice: number;
+  mainImage: string;
+  attributes: ICartItemAttributes;
+}
+
+export interface ICartItemAttributes {
+  engraving: ICartItemEngraving;
+  presale: IProductPresale;
+}
+
+export interface ICartItemEngraving {
+  isEngravable: boolean;
+  hasEngraving: boolean;
+  fee: number;
+  maxCharsPerLine: number;
+  maxLines: number;
+  location: string;
+  lines: string[];
+}
+
+export interface IProductPresale {
+  canPurchaseOn: string | null;
+  estimatedShipBy: string | null;
+  isActive: boolean;
+  language: string;
+}
+
+export interface ICartRetailer {
+  id: string;
+  name: string;
+  subtotal: number;
+  itemsQuantity: number;
+  fulfillments: Record<string, ICartFulfillment>;
+}
+
+export interface ICartFulfillment {
+  id: string;
+  canEngrave: boolean;
+  type: FulfillmentType;
+  expectation: string;
+  engravingExpectation: string;
+  itemIds: string[];
+  subtotal: number;
+  hasUnmetMinimumPurchaseAmount: boolean;
+  minimumPurchaseAmount: number;
+}
+
+export interface IAddressAddress {
+  one: string;
+  two: string;
+  city: string;
+  state: string;
+  zip: string;
+  country: string;
+}
+
+export interface IAddressCoordinates {
+  latitude: number;
+  longitude: number;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.cart_updated', (event) => {
+  const { data } = event.detail;
+  const delta = data.current.itemCount - data.previous.itemCount;
+  if (delta !== 0) console.log('Item count changed by', delta);
+});
+```
+
+### `lce:actions.cart_reset`
+
+Cart cleared.
+
+**Data shape (TypeScript)**
+
+```ts
+export type CartResetEventData = boolean;
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.cart_reset', () => {
+  console.log('Cart reset');
+});
+```
+
+### `lce:actions.cart_failed`
+
+Cart operation failed.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICartFailedEventData {
+  cartId: string;
+  message: string;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.cart_failed', (event) => {
+  const { data } = event.detail;
+  console.error('Cart error:', data.message);
+});
+```
+
+### `lce:actions.cart_item_added`
+
+Item added to cart.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICartItemAddedEventData {
+  cartId: string;
+  itemId: string;
+  fulfillmentId: string;
+  partNumber: string;
+  quantity: number;
+  engravingLines?: string[];
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.cart_item_added', (event) => {
+  const { data } = event.detail;
+  console.log(`Added item ${data.itemId} (qty ${data.quantity})`);
+});
+```
+
+### `lce:actions.cart_item_removed`
+
+Item removed from cart.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICartItemRemovedEventData {
+  cartId: string;
+  itemId: string;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.cart_item_removed', (event) => {
+  const { data } = event.detail;
+  console.log('Removed item', data.itemId);
+});
+```
+
+### `lce:actions.cart_item_quantity_increase`
+
+Cart item quantity increased.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICartItemQuantityChangedEventData {
+  cartId: string;
+  itemId: string;
+  quantity: number;
+  previousQuantity: number;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.cart_item_quantity_increase', (event) => {
+  const { data } = event.detail;
+  console.log('Quantity increased to', data.quantity);
+});
+```
+
+### `lce:actions.cart_item_quantity_decrease`
+
+Cart item quantity decreased.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICartItemQuantityChangedEventData {
+  cartId: string;
+  itemId: string;
+  quantity: number;
+  previousQuantity: number;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.cart_item_quantity_decrease', (event) => {
+  const { data } = event.detail;
+  console.log('Quantity decreased to', data.quantity);
+});
+```
+
+### `lce:actions.cart_item_engraving_updated`
+
+Engraving text updated for a cart item.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICartItemEngravingUpdatedEventData {
+  cartId: string;
+  itemId: string;
+  engravingLines: string[];
+  previousEngravingLines: string[];
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.cart_item_engraving_updated', (event) => {
+  const { data } = event.detail;
+  console.log('Updated engraving for', data.itemId);
+});
+```
+
+### `lce:actions.cart_promo_code_applied`
+
+Promo code applied to cart.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICartPromoCodeEventData {
+  cartId: string;
+  discount?: number;
+  newSubtotal?: number;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.cart_promo_code_applied', (event) => {
+  const { data } = event.detail;
+  console.log('Promo applied, discount:', data.discount);
+});
+```
+
+### `lce:actions.cart_promo_code_removed`
+
+Promo code removed from cart.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICartPromoCodeEventData {
+  cartId: string;
+  discount?: number;
+  newSubtotal?: number;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.cart_promo_code_removed', (event) => {
+  const { data } = event.detail;
+  console.log('Promo removed');
+});
+```
+
+### `lce:actions.cart_promo_code_failed`
+
+Promo code failed validation.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICartPromoCodeFailedEventData {
+  cartId: string;
+  error: string;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.cart_promo_code_failed', (event) => {
+  const { data } = event.detail;
+  console.error('Promo failed:', data.error);
+});
+```
+
+### `lce:actions.cart_product_add_success`
+
+Programmatic add-to-cart succeeded.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICartProductAddEventData {
+  cartId: string;
+  itemsAdded: number;
+  identifiers: string[];
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.cart_product_add_success', (event) => {
+  const { data } = event.detail;
+  console.log(`Added ${data.itemsAdded} products`);
+});
+```
+
+### `lce:actions.cart_product_add_failed`
+
+Programmatic add-to-cart failed.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICartProductAddFailedEventData {
+  cartId: string;
+  identifiers: string[];
+  error: string;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.cart_product_add_failed', (event) => {
+  const { data } = event.detail;
+  console.error('Product add failed:', data.error);
+});
+```
+
+## Checkout events
+
+### `lce:actions.checkout_loaded`
+
+Checkout state loaded.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface IBaseCheckoutEventData {
+  token: string;
+  cartId: string;
+  isGift: boolean;
+  billingSameAsShipping: boolean;
+  marketingPreferences: ICheckoutMarketingPreferences;
+  hasPromoCode: boolean;
+  hasGiftCards: boolean;
+  amounts: ICheckoutAmounts;
+  itemCount: number;
+  items: Record<string, ICheckoutItem>;
+}
+
+export interface ICheckoutMarketingPreferences {
+  canEmail: boolean;
+  canSms: boolean;
+}
+
+export interface ICheckoutAmounts {
+  subtotal: number;
+  engraving: number;
+  service: number;
+  shipping: number;
+  delivery: number;
+  platform: number;
+  discounts: number;
+  giftCards: number;
+  tax: number;
+  tip: number;
+  total: number;
+}
+
+export interface ICheckoutItem {
+  variantId: string;
+  cartItemId: string;
+  liquidId: string;
+  retailerId: string;
+  fulfillmentId: string;
+  salsifyPid?: string;
+  salsifyGrouping?: string;
+  name: string;
+  catPath: string;
+  volume: string;
+  uom: string;
+  proof: string;
+  abv: string;
+  containerType: string;
+  container: string;
+  size: string;
+  pack: boolean;
+  packDesc: string;
+  mainImage: string;
+  brand: string;
+  partNumber: string;
+  upc: string;
+  sku: string;
+  price: number;
+  unitPrice: number;
+  quantity: number;
+  tax: number;
+  unitTax: number;
+  bottleDeposits: number;
+  attributes: ICheckoutItemAttributes;
+}
+
+export interface ICheckoutItemAttributes {
+  engraving: ICheckoutItemEngraving;
+  presale: IProductPresale;
+}
+
+export interface ICheckoutItemEngraving {
+  isEngravable: boolean;
+  hasEngraving: boolean;
+  fee: number;
+  maxCharsPerLine: number;
+  maxLines: number;
+  location: string;
+  lines: string[];
+}
+
+export interface IProductPresale {
+  canPurchaseOn: string | null;
+  estimatedShipBy: string | null;
+  isActive: boolean;
+  language: string;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_loaded', (event) => {
+  const { data } = event.detail;
+  console.log('Checkout loaded for cart', data.cartId);
+});
+```
+
+### `lce:actions.checkout_opened`
+
+Checkout drawer opened.
+
+**Data shape (TypeScript)**
+
+```ts
+export type CheckoutOpenedEventData = boolean;
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_opened', () => {
+  console.log('Checkout opened');
+});
+```
+
+### `lce:actions.checkout_closed`
+
+Checkout drawer closed.
+
+**Data shape (TypeScript)**
+
+```ts
+export type CheckoutClosedEventData = boolean;
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_closed', () => {
+  console.log('Checkout closed');
+});
+```
+
+### `lce:actions.checkout_failed`
+
+Checkout failed to load or operate.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutFailedEventData {
+  message: string;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_failed', (event) => {
+  const { data } = event.detail;
+  console.error('Checkout error:', data.message);
+});
+```
+
+### `lce:actions.checkout_customer_information_updated`
+
+Customer info updated.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutCustomerInformationUpdatedEventData {
+  cartId: string;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_customer_information_updated', (event) => {
+  const { data } = event.detail;
+  console.log('Customer info updated for cart', data.cartId);
+});
+```
+
+### `lce:actions.checkout_billing_information_updated`
+
+Billing info updated.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutBillingInformationUpdatedEventData {
+  cartId: string;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_billing_information_updated', (event) => {
+  const { data } = event.detail;
+  console.log('Billing info updated for cart', data.cartId);
+});
+```
+
+### `lce:actions.checkout_gift_information_updated`
+
+Gift recipient info updated.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutGiftInformationUpdatedEventData {
+  cartId: string;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_gift_information_updated', (event) => {
+  const { data } = event.detail;
+  console.log('Gift info updated for cart', data.cartId);
+});
+```
+
+### `lce:actions.checkout_is_gift_toggled`
+
+Gift mode toggled.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutToggleEventData {
+  cartId: string;
+  isActive: boolean;
+  previousIsActive: boolean;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_is_gift_toggled', (event) => {
+  const { data } = event.detail;
+  console.log('Gift mode:', data.isActive);
+});
+```
+
+### `lce:actions.checkout_billing_same_as_shipping_toggled`
+
+Billing same-as-shipping toggled.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutToggleEventData {
+  cartId: string;
+  isActive: boolean;
+  previousIsActive: boolean;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_billing_same_as_shipping_toggled', (event) => {
+  const { data } = event.detail;
+  console.log('Billing same as shipping:', data.isActive);
+});
+```
+
+### `lce:actions.checkout_marketing_preferences_toggled`
+
+Marketing preference toggled.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutMarketingPreferencesToggleEventData {
+  cartId: string;
+  fieldName: 'canEmail' | 'canSms';
+  isActive: boolean;
+  previousIsActive: boolean;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_marketing_preferences_toggled', (event) => {
+  const { data } = event.detail;
+  console.log(`Marketing ${data.fieldName}:`, data.isActive);
+});
+```
+
+### `lce:actions.checkout_item_removed`
+
+Item removed during checkout.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutItemRemovedEventData {
+  cartId: string;
+  cartItemId: string;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_item_removed', (event) => {
+  const { data } = event.detail;
+  console.log('Checkout item removed', data.cartItemId);
+});
+```
+
+### `lce:actions.checkout_item_quantity_increase`
+
+Checkout item quantity increased.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutItemQuantityChangedEventData {
+  cartId: string;
+  cartItemId: string;
+  quantity: number;
+  previousQuantity: number;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_item_quantity_increase', (event) => {
+  const { data } = event.detail;
+  console.log('Checkout quantity increased to', data.quantity);
+});
+```
+
+### `lce:actions.checkout_item_quantity_decrease`
+
+Checkout item quantity decreased.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutItemQuantityChangedEventData {
+  cartId: string;
+  cartItemId: string;
+  quantity: number;
+  previousQuantity: number;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_item_quantity_decrease', (event) => {
+  const { data } = event.detail;
+  console.log('Checkout quantity decreased to', data.quantity);
+});
+```
+
+### `lce:actions.checkout_item_engraving_updated`
+
+Engraving text updated for a checkout item.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutItemEngravingUpdatedEventData {
+  cartId: string;
+  cartItemId: string;
+  engravingLines: string[];
+  previousEngravingLines: string[];
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_item_engraving_updated', (event) => {
+  const { data } = event.detail;
+  console.log('Checkout engraving updated for', data.cartItemId);
+});
+```
+
+### `lce:actions.checkout_tip_updated`
+
+Delivery tips updated.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutTipUpdatedEventData {
+  cartId: string;
+  deliveryTips: Array<{
+    fulfillmentId: string;
+    tip: number;
+  }>;
+  previousDeliveryTips: Array<{
+    fulfillmentId: string;
+    tip: number;
+  }>;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_tip_updated', (event) => {
+  const { data } = event.detail;
+  console.log('Tips updated for cart', data.cartId);
+});
+```
+
+### `lce:actions.checkout_submit_started`
+
+Checkout submit started.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutSubmitStartedEventData {
+  started: boolean;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_submit_started', (event) => {
+  const { data } = event.detail;
+  if (data.started) console.log('Checkout submit started');
+});
+```
+
+### `lce:actions.checkout_submit_completed`
+
+Checkout completed successfully.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutSubmitCompletedEventData {
+  orderNumber: string;
+  orderTotal: number;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  const { data } = event.detail;
+  console.log('Order completed:', data.orderNumber);
+});
+```
+
+### `lce:actions.checkout_submit_failed`
+
+Checkout submission failed.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutSubmitFailedEventData {
+  message: string;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
+  const { data } = event.detail;
+  console.error('Checkout submit failed:', data.message);
+});
+```
+
+### `lce:actions.checkout_promo_code_applied`
+
+Promo code applied in checkout.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutPromoCodeEventData {
+  cartId: string;
+  discount?: number;
+  newTotal?: number;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_promo_code_applied', (event) => {
+  const { data } = event.detail;
+  console.log('Checkout promo applied:', data.discount);
+});
+```
+
+### `lce:actions.checkout_promo_code_removed`
+
+Promo code removed in checkout.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutPromoCodeEventData {
+  cartId: string;
+  discount?: number;
+  newTotal?: number;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_promo_code_removed', (event) => {
+  const { data } = event.detail;
+  console.log('Checkout promo removed');
+});
+```
+
+### `lce:actions.checkout_promo_code_failed`
+
+Promo code failed in checkout.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutPromoCodeFailedEventData {
+  cartId: string;
+  error: string;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_promo_code_failed', (event) => {
+  const { data } = event.detail;
+  console.error('Checkout promo failed:', data.error);
+});
+```
+
+### `lce:actions.checkout_gift_card_applied`
+
+Gift card applied in checkout.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutGiftCardEventData {
+  cartId: string;
+  newTotal?: number;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_gift_card_applied', (event) => {
+  const { data } = event.detail;
+  console.log('Gift card applied, new total:', data.newTotal);
+});
+```
+
+### `lce:actions.checkout_gift_card_removed`
+
+Gift card removed in checkout.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutGiftCardEventData {
+  cartId: string;
+  newTotal?: number;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_gift_card_removed', (event) => {
+  const { data } = event.detail;
+  console.log('Gift card removed');
+});
+```
+
+### `lce:actions.checkout_gift_card_failed`
+
+Gift card failed in checkout.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutGiftCardFailedEventData {
+  cartId: string;
+  error: string;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_gift_card_failed', (event) => {
+  const { data } = event.detail;
+  console.error('Gift card failed:', data.error);
+});
+```
+
+### `lce:actions.checkout_product_add_success`
+
+Programmatic add-to-checkout succeeded.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutProductAddEventData {
+  cartId: string;
+  itemsAdded: number;
+  identifiers: string[];
+  isPresale?: boolean;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_product_add_success', (event) => {
+  const { data } = event.detail;
+  console.log(`Checkout added ${data.itemsAdded} products`);
+});
+```
+
+### `lce:actions.checkout_product_add_failed`
+
+Programmatic add-to-checkout failed.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface ICheckoutProductAddFailedEventData {
+  cartId: string;
+  identifiers: string[];
+  error: string;
+  isPresale?: boolean;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:actions.checkout_product_add_failed', (event) => {
+  const { data } = event.detail;
+  console.error('Checkout product add failed:', data.error);
+});
+```
+
+## Form events
+
+### `lce:forms.customer`
+
+Fires when a customer form field changes in checkout.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface IFormEventData {
+  fieldName: string;
+  fieldValue?: string;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:forms.customer', (event) => {
+  const { data } = event.detail;
+  console.log('Customer field changed:', data.fieldName);
+});
+```
+
+### `lce:forms.billing`
+
+Fires when a billing form field changes in checkout.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface IFormEventData {
+  fieldName: string;
+  fieldValue?: string;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:forms.billing', (event) => {
+  const { data } = event.detail;
+  console.log('Billing field changed:', data.fieldName);
+});
+```
+
+### `lce:forms.gift`
+
+Fires when a gift form field changes in checkout.
+
+**Data shape (TypeScript)**
+
+```ts
+export interface IFormEventData {
+  fieldName: string;
+  fieldValue?: string;
+}
+```
+
+**Example**
+
+```js
+window.addEventListener('lce:forms.gift', (event) => {
+  const { data } = event.detail;
+  console.log('Gift field changed:', data.fieldName);
+});
+```
+
+## Analytics example
+
+```js
+window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  const { data } = event.detail;
+  gtag('event', 'purchase', {
+    transaction_id: data.orderNumber,
+    value: data.orderTotal / 100,
+    currency: 'USD'
+  });
+});
+```