@liquidcommerce/elements-sdk 2.6.0-beta.40 → 2.6.0-beta.41

package/dist/types/auto-initialize/shared-utils.d.ts

@@ -1,7 +1,12 @@
 import type { IInjectCheckoutParams, IInjectedComponent, ILiquidCommerceElementsDevelopmentConfig } from '@/interfaces/core.interface';
 export declare const SHARED_ATTR: {
     readonly SCRIPT: {
+        readonly MAIN: "data-liquid-commerce-elements";
+        readonly TOKEN: "data-token";
+        readonly ENV: "data-env";
+        readonly DEBUG_MODE: "data-debug-mode";
         readonly CHECKOUT_PARAM: "data-checkout-param";
+        readonly CHECKOUT_URL: "data-checkout-url";
     };
     readonly ELEMENT: {
         readonly CHECKOUT: "data-lce-checkout";

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

@@ -1,5 +1,6 @@
 import type { ICheckoutAmounts, ICheckoutItem } from '@/interfaces/api/checkout.interface';
 export interface IBaseCheckoutEventData {
+    token: string;
     cartId: string;
     isGift: boolean;
     billingSameAsShipping: boolean;

package/docs/gitbook/actions.md

@@ -0,0 +1,160 @@
+# Actions
+
+Actions let you control Elements programmatically after the SDK initializes. All actions live under `window.elements.actions.*`.
+
+## Quick start
+```js
+window.addEventListener('lce:actions.client_ready', () => {
+  window.elements.actions.cart.openCart();
+});
+```
+
+## Product actions
+- `actions.product.getDetails(identifier)`
+  Returns the current loaded product data (price, size, fulfillment, retailer, quantity, images, etc.). The product must already be injected and loaded.
+
+```js
+const product = window.elements.actions.product.getDetails('00619947000020');
+console.log(product.name, product.price);
+```
+
+## Cart actions
+- `actions.cart.openCart()`
+  Opens the cart drawer.
+- `actions.cart.closeCart()`
+  Closes the cart drawer.
+- `actions.cart.toggleCart()`
+  Toggles the cart drawer open/closed.
+- `actions.cart.addProduct(params[], openCart?)`
+  Adds one or more products to the cart. If no address is set, the SDK prompts for one and retries automatically.
+- `actions.cart.applyPromoCode(promoCode)`
+  Applies a promo code (replaces any existing code).
+- `actions.cart.removePromoCode()`
+  Removes the active promo code.
+- `actions.cart.resetCart()`
+  Clears all cart items (no undo).
+- `actions.cart.getDetails()`
+  Returns current cart data (items, totals, promo, retailers, etc.).
+
+```js
+await window.elements.actions.cart.addProduct([
+  { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }
+], true);
+
+await window.elements.actions.cart.applyPromoCode('SUMMER20');
+await window.elements.actions.cart.removePromoCode();
+await window.elements.actions.cart.resetCart();
+
+const cart = window.elements.actions.cart.getDetails();
+```
+
+## Checkout actions
+- `actions.checkout.openCheckout()`
+  Opens the checkout drawer.
+- `actions.checkout.closeCheckout()`
+  Closes the checkout drawer.
+- `actions.checkout.toggleCheckout()`
+  Toggles the checkout drawer open/closed.
+- `actions.checkout.exitCheckout()`
+  Navigates away from checkout (requires `exitUrl` config).
+- `actions.checkout.addProduct(params[], openCheckout?)`
+  Adds products directly to checkout (bypasses cart).
+- `actions.checkout.applyPromoCode(promoCode)`
+  Applies a promo code in checkout.
+- `actions.checkout.removePromoCode()`
+  Removes the active promo code.
+- `actions.checkout.applyGiftCard(code)`
+  Applies a gift card.
+- `actions.checkout.removeGiftCard(code)`
+  Removes a gift card.
+- `actions.checkout.toggleIsGift(active?)`
+  Enables/disables gift mode (or toggles when omitted).
+- `actions.checkout.toggleBillingSameAsShipping(active?)`
+  Sets billing address to match shipping.
+- `actions.checkout.toggleMarketingPreferences(field, active)`
+  Sets marketing opt-in (`canEmail` or `canSms`).
+- `actions.checkout.updateCustomerInfo(fields)`
+  Prefills customer info (name, email, phone, birthdate, etc.).
+- `actions.checkout.updateBillingInfo(fields)`
+  Prefills billing address fields.
+- `actions.checkout.updateGiftInfo(fields)`
+  Prefills gift recipient information.
+
+```js
+window.elements.actions.checkout.openCheckout();
+window.elements.actions.checkout.closeCheckout();
+window.elements.actions.checkout.toggleCheckout();
+
+await window.elements.actions.checkout.addProduct([
+  { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }
+], true);
+
+await window.elements.actions.checkout.applyPromoCode('WELCOME10');
+await window.elements.actions.checkout.applyGiftCard('GIFT-1234-5678');
+
+await window.elements.actions.checkout.toggleIsGift(true);
+await window.elements.actions.checkout.toggleBillingSameAsShipping(false);
+await window.elements.actions.checkout.toggleMarketingPreferences('canEmail', true);
+
+window.elements.actions.checkout.updateCustomerInfo({
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john@example.com'
+});
+
+window.elements.actions.checkout.updateBillingInfo({
+  firstName: 'John',
+  lastName: 'Doe',
+  addressOne: '789 Elm St',
+  city: 'Chicago',
+  state: 'IL',
+  zipCode: '60601'
+});
+
+window.elements.actions.checkout.updateGiftInfo({
+  firstName: 'Jane',
+  lastName: 'Smith',
+  message: 'Happy Birthday!'
+});
+```
+
+## Address actions
+- `actions.address.setAddressByPlacesId(placesId)`
+  Sets address using a Google Places ID (recommended).
+- `actions.address.setAddressManually(address, coordinates)`
+  Sets address with your own address + lat/long data.
+- `actions.address.getDetails()`
+  Returns the current address (or null if not set).
+- `actions.address.clear()`
+  Removes the stored address and resets availability.
+
+```js
+await window.elements.actions.address.setAddressByPlacesId('ChIJOwg_06VPwokRYv534QaPC8g');
+
+await window.elements.actions.address.setAddressManually(
+  { one: '123 Main Street', city: 'New York', state: 'NY', zip: '10001' },
+  { latitude: 40.7128, longitude: -74.0060 }
+);
+
+const address = window.elements.actions.address.getDetails();
+await window.elements.actions.address.clear();
+```
+
+## UI helpers (non-actions)
+These helpers live under `window.elements.ui.*` and are commonly used with actions.
+
+- `ui.cartButton(containerId, showItemsCount?)`
+  Renders a cart button inside the given container.
+- `ui.floatingCartButton(showItemsCount?)`
+  Renders a floating cart button (bottom-right).
+- `ui.cartSubtotal(elementId)`
+  Keeps an element updated with cart subtotal.
+- `ui.cartItemsCount(elementId, { hideZero })`
+  Keeps an element updated with cart item count.
+
+```js
+window.elements.ui.cartButton('header-cart', true);
+window.elements.ui.floatingCartButton(true);
+window.elements.ui.cartSubtotal('cart-total');
+window.elements.ui.cartItemsCount('items-count', { hideZero: true });
+```

package/docs/gitbook/address.md

@@ -0,0 +1,48 @@
+# Address
+
+The Address component sets the delivery location used for availability, pricing, and fulfillment options.
+
+## How it works
+- Address is embedded in the Product component by default
+- If a user adds to cart without an address, the SDK prompts automatically
+- The address is reused across product, cart, and checkout
+
+## Standalone address component
+```js
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+await client.injectAddressElement('address', {
+  onAddressSet: (address) => {
+    console.log('Address set:', address);
+  }
+});
+```
+
+## Address actions
+```js
+await window.elements.actions.address.setAddressByPlacesId('ChIJOwg_06VPwokRYv534QaPC8g');
+
+await window.elements.actions.address.setAddressManually(
+  {
+    one: '123 Main Street',
+    two: 'Apt 4',
+    city: 'New York',
+    state: 'NY',
+    zip: '10001'
+  },
+  { latitude: 40.7128, longitude: -74.0060 }
+);
+
+const address = window.elements.actions.address.getDetails();
+await window.elements.actions.address.clear();
+```
+
+## Address events (examples)
+```js
+window.addEventListener('lce:actions.address_updated', (event) => {
+  const { formattedAddress } = event.detail.data;
+});
+
+window.addEventListener('lce:actions.address_failed', (event) => {
+  const { error } = event.detail.data;
+});
+```

package/docs/gitbook/cart.md

@@ -0,0 +1,65 @@
+# Cart
+
+The Cart component is a slide-out drawer that manages items, quantities, promo codes, and checkout.
+
+## What you get
+- Drawer UI with item list and totals
+- Grouped items by retailer
+- Quantity updates and removals
+- Promo code support
+- Cart persistence across sessions and tabs
+- Checkout entry point
+
+## Show a cart button (CDN)
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-cart-badge-button="header-cart"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+
+<div id="header-cart"></div>
+```
+
+## Cart UI helpers (programmatic)
+```js
+window.elements.ui.cartButton('header-cart', true);
+window.elements.ui.floatingCartButton(true);
+window.elements.ui.cartSubtotal('cart-total');
+window.elements.ui.cartItemsCount('items-count', { hideZero: true });
+```
+
+## Cart actions
+```js
+window.elements.actions.cart.openCart();
+window.elements.actions.cart.closeCart();
+window.elements.actions.cart.toggleCart();
+
+await window.elements.actions.cart.addProduct([
+  { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }
+], true);
+
+await window.elements.actions.cart.applyPromoCode('SUMMER20');
+await window.elements.actions.cart.removePromoCode();
+await window.elements.actions.cart.resetCart();
+
+const cart = window.elements.actions.cart.getDetails();
+```
+
+## Address behavior
+If no address is set, add-to-cart automatically opens the address prompt, then retries the add.
+
+## Cart events (examples)
+```js
+window.addEventListener('lce:actions.cart_item_added', (event) => {
+  const { identifiers, itemsAdded } = event.detail.data;
+});
+
+window.addEventListener('lce:actions.cart_updated', (event) => {
+  const { subtotal, itemsCount } = event.detail.data;
+});
+```

package/docs/gitbook/checkout.md

@@ -0,0 +1,131 @@
+# Checkout
+
+The Checkout component provides a complete purchase flow with customer info, payment (Stripe), and confirmation.
+
+## What you get
+- Customer, billing, and shipping info
+- Gift and marketing preferences
+- Promo codes and gift cards
+- Order summary and totals
+- Hosted checkout or drawer checkout
+
+## Default: drawer checkout
+Checkout opens automatically from the cart drawer. No setup required.
+
+## Hosted checkout (inject)
+```js
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+await client.injectCheckoutElement({
+  containerId: 'checkout',
+  checkoutId: 'optional_checkout_id',
+  hideHeader: false
+});
+```
+
+## Hosted checkout (URL param)
+Hosted checkout uses two things together:
+1) `data-checkout-url` on the main script (so the cart can redirect to your hosted checkout page).
+2) `data-checkout-param` on the hosted page (so it can read the checkout ID from the URL).
+
+Hosted page example:
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-checkout-param="lce_checkout"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+
+<div data-lce-checkout></div>
+```
+
+Main script example (cart redirects here):
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-checkout-url="https://yoursite.com/checkout?lce_checkout={token}"
+  data-checkout-param="lce_checkout"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+## Hosted checkout UI controls
+Use these attributes on the hosted checkout page to customize the UI:
+
+- `hide-header` on the checkout container  
+  Hides the SDK header so you can render your own.
+
+```html
+<div data-lce-checkout hide-header></div>
+```
+
+- `data-lce-exit-checkout` on any element  
+  Lets you build your own “Exit checkout” button or link.
+
+```html
+<button data-lce-exit-checkout>Exit checkout</button>
+```
+
+## Checkout-only build
+If a page only needs hosted checkout, use the checkout-only script. It supports the same hosted-checkout attributes but ships ~50% less JavaScript for faster load time.
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/checkout/elements.js"
+></script>
+```
+
+## Checkout actions
+```js
+window.elements.actions.checkout.openCheckout();
+window.elements.actions.checkout.closeCheckout();
+window.elements.actions.checkout.toggleCheckout();
+window.elements.actions.checkout.exitCheckout();
+
+await window.elements.actions.checkout.addProduct([
+  { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }
+], true);
+
+await window.elements.actions.checkout.applyPromoCode('WELCOME10');
+await window.elements.actions.checkout.removePromoCode();
+
+await window.elements.actions.checkout.applyGiftCard('GIFT-1234-5678');
+await window.elements.actions.checkout.removeGiftCard('GIFT-1234-5678');
+
+await window.elements.actions.checkout.toggleIsGift(true);
+await window.elements.actions.checkout.toggleBillingSameAsShipping(false);
+await window.elements.actions.checkout.toggleMarketingPreferences('canEmail', true);
+
+window.elements.actions.checkout.updateCustomerInfo({
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john@example.com'
+});
+
+window.elements.actions.checkout.updateBillingInfo({
+  firstName: 'John',
+  lastName: 'Doe',
+  addressOne: '789 Elm St',
+  city: 'Chicago',
+  state: 'IL',
+  zipCode: '60601'
+});
+```
+
+## Checkout events (examples)
+```js
+window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  const { orderId, total } = event.detail.data;
+});
+```

package/docs/gitbook/events.md

@@ -0,0 +1,137 @@
+# Events
+
+The SDK emits events for user actions and state changes. Listen on `window` using the `lce:actions.*` namespace.
+
+## Event shape
+```js
+window.addEventListener('lce:actions.event_name', (event) => {
+  const { namespace, event: eventName, timestamp, id, data } = event.detail;
+});
+```
+
+## Client lifecycle
+- `lce:actions.client_ready`
+  Fired when the SDK is initialized and safe to use.
+
+```js
+window.addEventListener('lce:actions.client_ready', (event) => {
+  const { isReady, version, timestamp } = event.detail.data;
+});
+```
+
+## Product events
+- `lce:actions.product_loaded`
+  Product data loaded into the component.
+- `lce:actions.product_add_to_cart`
+  User clicked Add to Cart.
+- `lce:actions.product_size_changed`
+  User changed the selected size.
+- `lce:actions.product_fulfillment_type_changed`
+  User switched fulfillment type (shipping/onDemand).
+- `lce:actions.product_fulfillment_changed`
+  Retailer selection changed.
+- `lce:actions.product_quantity_increase`
+  User increased quantity.
+- `lce:actions.product_quantity_decrease`
+  User decreased quantity.
+
+```js
+window.addEventListener('lce:actions.product_loaded', (event) => {
+  const { identifier, name, price } = event.detail.data;
+});
+```
+
+## Address events
+- `lce:actions.address_updated`
+  Address successfully set or changed.
+- `lce:actions.address_cleared`
+  Address removed.
+- `lce:actions.address_failed`
+  Address set failed (validation, geocode, etc.).
+
+```js
+window.addEventListener('lce:actions.address_updated', (event) => {
+  const { formattedAddress } = event.detail.data;
+});
+```
+
+## Cart events
+- `lce:actions.cart_loaded`
+  Cart state loaded.
+- `lce:actions.cart_opened`
+  Cart drawer opened.
+- `lce:actions.cart_closed`
+  Cart drawer closed.
+- `lce:actions.cart_updated`
+  Cart totals/items changed.
+- `lce:actions.cart_item_added`
+  Item added to cart.
+- `lce:actions.cart_item_removed`
+  Item removed from cart.
+- `lce:actions.cart_item_quantity_increase`
+  Cart item quantity increased.
+- `lce:actions.cart_item_quantity_decrease`
+  Cart item quantity decreased.
+- `lce:actions.cart_promo_code_applied`
+  Promo code applied to cart.
+- `lce:actions.cart_promo_code_removed`
+  Promo code removed from cart.
+- `lce:actions.cart_promo_code_failed`
+  Promo code failed validation.
+- `lce:actions.cart_product_add_success`
+  Programmatic add-to-cart succeeded.
+- `lce:actions.cart_product_add_failed`
+  Programmatic add-to-cart failed.
+
+```js
+window.addEventListener('lce:actions.cart_updated', (event) => {
+  const { cartId, itemsCount, subtotal } = event.detail.data;
+});
+```
+
+## Checkout events
+- `lce:actions.checkout_loaded`
+  Checkout state loaded.
+- `lce:actions.checkout_opened`
+  Checkout drawer opened.
+- `lce:actions.checkout_closed`
+  Checkout drawer closed.
+- `lce:actions.checkout_customer_information_updated`
+  Customer info updated.
+- `lce:actions.checkout_billing_information_updated`
+  Billing info updated.
+- `lce:actions.checkout_gift_information_updated`
+  Gift info updated.
+- `lce:actions.checkout_is_gift_toggled`
+  Gift mode toggled.
+- `lce:actions.checkout_billing_same_as_shipping_toggled`
+  Billing same as shipping toggled.
+- `lce:actions.checkout_marketing_preferences_toggled`
+  Marketing preferences toggled.
+- `lce:actions.checkout_submit_started`
+  Checkout submit started.
+- `lce:actions.checkout_submit_completed`
+  Checkout completed successfully.
+- `lce:actions.checkout_submit_failed`
+  Checkout submission failed.
+- `lce:actions.checkout_promo_code_applied`
+  Promo code applied in checkout.
+- `lce:actions.checkout_gift_card_applied`
+  Gift card applied in checkout.
+
+```js
+window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  const { orderId, total } = event.detail.data;
+});
+```
+
+## Analytics example
+```js
+window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  gtag('event', 'purchase', {
+    transaction_id: event.detail.data.orderId,
+    value: event.detail.data.total / 100,
+    currency: 'USD'
+  });
+});
+```