@liquidcommerce/elements-sdk 2.6.0-beta.13 → 2.6.0-beta.130

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/cart-actions.md

@@ -0,0 +1,364 @@
+# Cart Actions API
+
+Cart actions allow you to programmatically control the shopping cart.
+
+## actions.cart.openCart()
+
+Open the cart drawer.
+
+### Signature
+
+```typescript
+openCart(): void
+```
+
+### Example
+
+```javascript
+window.LiquidCommerce.elements.actions.cart.openCart();
+```
+
+---
+
+## actions.cart.closeCart()
+
+Close the cart drawer.
+
+### Signature
+
+```typescript
+closeCart(): void
+```
+
+### Example
+
+```javascript
+window.LiquidCommerce.elements.actions.cart.closeCart();
+```
+
+---
+
+## actions.cart.toggleCart()
+
+Toggle the cart drawer open/closed.
+
+### Signature
+
+```typescript
+toggleCart(): void
+```
+
+### Example
+
+```javascript
+// Add to your cart button
+document.getElementById('cart-btn').addEventListener('click', () => {
+  window.LiquidCommerce.elements.actions.cart.toggleCart();
+});
+```
+
+---
+
+## actions.cart.addProduct()
+
+Add products to the cart programmatically.
+
+### Signature
+
+```typescript
+addProduct(params: IAddProductParams[], openCart?: boolean): Promise<void>
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `params` | IAddProductParams[] | Yes | Array of products to add |
+| `openCart` | boolean | No | Open cart after adding (default: false) |
+
+```typescript
+interface IAddProductParams {
+  identifier: string;      // Product UPC, size ID, or salsify grouping ID
+  fulfillmentType: FulfillmentType;  // 'shipping' or 'onDemand'
+  quantity: number;        // Number of items
+  engravingLines?: string[]; // Optional engraving (see below)
+}
+```
+
+#### `engravingLines` (optional)
+
+Pre-fills an engraving for the added item. The SDK enforces the product's engraving rules and degrades silently rather than failing the call:
+
+- Non-string-array input is ignored (warning logged).
+- Blank/whitespace-only entries are stripped; an empty result is treated as no engraving.
+- If the product/size doesn't support engraving, lines are dropped.
+- Lines beyond `maxLines` are sliced off; any line longer than `maxCharsPerLine` is truncated.
+- If no engravable variant is available for the chosen fulfillment, lines are dropped and the item is still added.
+
+### Example
+
+```javascript
+// Add single product
+await window.LiquidCommerce.elements.actions.cart.addProduct([
+  {
+    identifier: '00619947000020',
+    fulfillmentType: 'shipping',
+    quantity: 1
+  }
+], true);  // Open cart after adding
+
+// Add multiple products
+await window.LiquidCommerce.elements.actions.cart.addProduct([
+  {
+    identifier: '00619947000020',
+    fulfillmentType: 'shipping',
+    quantity: 2
+  },
+  {
+    identifier: '08504405135',
+    fulfillmentType: 'onDemand',
+    quantity: 1
+  }
+]);
+
+// Add a product with engraving
+await window.LiquidCommerce.elements.actions.cart.addProduct([
+  {
+    identifier: '00619947000020',
+    fulfillmentType: 'shipping',
+    quantity: 1,
+    engravingLines: ['Happy Birthday', 'Love, Sam']
+  }
+], true);
+```
+
+### Address Requirement
+
+If no address is set, the SDK automatically:
+1. Opens address input drawer
+2. Waits for user to set address
+3. Retries add-to-cart operation
+
+### Errors
+
+**Throws `SDKError` if:**
+- Identifier is invalid
+- Fulfillment type is not `'shipping'` or `'onDemand'`
+- Quantity is less than 1
+
+Unavailable products and presale items are **not** thrown — they are silently skipped (a `cart.error` is set on the store). If no products could be added, a `cart_product_add_failed` event is emitted with `{ cartId, identifiers, error }` and the returned promise still resolves (it does not reject).
+
+---
+
+## actions.cart.applyPromoCode()
+
+Apply a promo code to the cart.
+
+### Signature
+
+```typescript
+applyPromoCode(promoCode: string): Promise<void>
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `promoCode` | string | Yes | Promo code to apply |
+
+### Example
+
+```javascript
+// Listen for the outcome — an invalid code surfaces here, not as a rejection
+window.addEventListener('lce:actions.cart_promo_code_failed', (event) => {
+  console.error('Invalid promo code:', event.detail.data);
+});
+
+try {
+  await window.LiquidCommerce.elements.actions.cart.applyPromoCode('SUMMER20');
+} catch (error) {
+  // Only reached on unexpected errors, not for an invalid code
+  console.error('Failed to apply promo code:', error);
+}
+```
+
+### Notes
+
+- Code is automatically normalized (trimmed, uppercased)
+- Promo codes must be enabled in configuration
+- Only one promo code can be active at a time
+- Applying a new code replaces the existing one
+- An invalid/rejected code does **not** reject the promise — the failure is surfaced via the `lce:actions.cart_promo_code_failed` event. Listen for that event to handle invalid codes.
+- An empty or whitespace-only code is a silent no-op: it sets a `cart.error` on the store and returns without throwing.
+
+---
+
+## actions.cart.removePromoCode()
+
+Remove the active promo code.
+
+### Signature
+
+```typescript
+removePromoCode(): Promise<void>
+```
+
+### Example
+
+```javascript
+await window.LiquidCommerce.elements.actions.cart.removePromoCode();
+```
+
+---
+
+## actions.cart.resetCart()
+
+Clear all items from the cart.
+
+### Signature
+
+```typescript
+resetCart(): Promise<void>
+```
+
+### Example
+
+```javascript
+await window.LiquidCommerce.elements.actions.cart.resetCart();
+console.log('Cart cleared');
+```
+
+### Warning
+
+This permanently removes all cart items. There is no undo.
+
+---
+
+## actions.cart.getDetails()
+
+Retrieve current cart information.
+
+### Signature
+
+```typescript
+getDetails(): IBaseCartEventData
+```
+
+### Returns
+
+```typescript
+interface IBaseCartEventData {
+  cartId: string;
+  promoCodeDiscount: number | null;  // in cents
+  subtotal: number;  // in cents
+  itemCount: number;
+  items: Record<string, ICartItem>;       // keyed by item ID
+  retailers: Record<string, ICartRetailer>; // keyed by retailer ID
+  location: {
+    placesId: string;
+    formattedAddress: string;
+    address: IAddressAddress;
+    coordinates: IAddressCoordinates;
+  } | null;
+}
+```
+
+### Example
+
+```javascript
+const cart = window.LiquidCommerce.elements.actions.cart.getDetails();
+
+console.log(`Cart ID: ${cart.cartId}`);
+console.log(`Items: ${cart.itemCount}`);
+console.log(`Subtotal: $${cart.subtotal / 100}`);
+
+if (cart.promoCodeDiscount) {
+  console.log(`Discount: $${cart.promoCodeDiscount / 100}`);
+}
+```
+
+### Use Cases
+
+#### Display Cart Summary
+
+```javascript
+function updateCartSummary() {
+  const cart = window.LiquidCommerce.elements.actions.cart.getDetails();
+  
+  document.getElementById('cart-count').textContent = cart.itemCount;
+  document.getElementById('cart-total').textContent = `$${cart.subtotal / 100}`;
+}
+
+// Update on cart changes
+window.addEventListener('lce:actions.cart_updated', updateCartSummary);
+```
+
+#### Check Cart Before Checkout
+
+```javascript
+document.getElementById('checkout-btn').addEventListener('click', () => {
+  const cart = window.LiquidCommerce.elements.actions.cart.getDetails();
+  
+  if (cart.itemCount === 0) {
+    alert('Your cart is empty');
+    return;
+  }
+  
+  window.LiquidCommerce.elements.actions.checkout.openCheckout();
+});
+```
+
+#### Track Cart Value
+
+```javascript
+const cart = window.LiquidCommerce.elements.actions.cart.getDetails();
+
+gtag('event', 'view_cart', {
+  value: cart.subtotal / 100,
+  currency: 'USD',
+  items: Object.values(cart.items).map(item => ({
+    item_id: item.partNumber,
+    quantity: item.quantity
+  }))
+});
+```
+
+## Events
+
+Cart actions trigger events that you can listen for:
+
+```javascript
+// Item added
+window.addEventListener('lce:actions.cart_item_added', (event) => {
+  console.log('Item added:', event.detail.data);
+});
+
+// Cart updated
+window.addEventListener('lce:actions.cart_updated', (event) => {
+  console.log('Cart updated:', event.detail.data);
+});
+
+// Promo code applied
+window.addEventListener('lce:actions.cart_promo_code_applied', (event) => {
+  console.log('Promo applied:', event.detail.data);
+});
+
+// Product add success
+window.addEventListener('lce:actions.cart_product_add_success', (event) => {
+  console.log('Products added:', event.detail.data);
+});
+
+// Product add failed
+window.addEventListener('lce:actions.cart_product_add_failed', (event) => {
+  console.error('Failed to add:', event.detail.data);
+});
+```
+
+See [Events Guide](../../guides/events.md) for all cart events.
+
+## See Also
+
+- [Cart Component Guide](../../guides/cart-component.md)
+- [Cart Events](../../guides/events.md#cart-events)
+- [Product Actions](./product-actions.md)
+- [Checkout Actions](./checkout-actions.md)