@liquidcommerce/elements-sdk 2.7.0 → 2.7.1

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'
+  });
+});
+```

package/docs/gitbook/overview.md

@@ -0,0 +1,166 @@
+# Elements SDK
+
+A lightweight, developer-facing guide to integrate LiquidCommerce Elements SDK into your site or app.
+
+## What it is
+Elements SDK is a Web Components-based e-commerce SDK that embeds product, cart, address, and checkout experiences into any website. It works with plain HTML or any framework and exposes a simple client + actions API.
+
+## Core components
+- Product: product detail display + add to cart
+- Cart: slide-out cart drawer + promo codes
+- Checkout: full checkout flow (drawer or hosted page)
+- Address: delivery location and availability
+
+## Quick start (CDN)
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-container-1="product"
+  data-product-1="00619947000020"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+
+<div id="product"></div>
+```
+
+## Quick start (NPM)
+```bash
+npm install @liquidcommerce/elements-sdk
+```
+
+```js
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+await client.injectProductElement([
+  { containerId: 'product', identifier: '00619947000020' }
+]);
+```
+
+## Initialization modes
+- Declarative (CDN): data attributes on the script tag, auto-initialized
+- Programmatic (NPM or CDN): call `Elements(...)` and inject components
+
+The client is available globally as `window.elements` as soon as the SDK is ready.
+
+## Quick Start Guide (auto-setup)
+Most partners use the auto-setup approach because it is the fastest to implement. It supports rich configuration via data attributes, including product injection, cart buttons, checkout, query param handling, and more.
+
+See [Quick Start Guide](./quick-start-guide.md) for the complete list of supported attributes and combinations.
+
+## Configuration basics
+```js
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production', // development | staging | production
+});
+```
+
+## Client surface (exposed methods)
+After initialization, the client exposes three main groups: injection methods, `actions`, and `ui` helpers, plus component management.
+
+### Injection methods
+Use these to mount SDK components into your DOM. Each method is shown with a minimal example.
+
+#### `injectProductElement(params[])`
+Inject one or more product components by container ID + product identifier.
+```js
+await client.injectProductElement([
+  { containerId: 'product-1', identifier: '00619947000020' },
+  { containerId: 'product-2', identifier: '08504405135' }
+]);
+```
+
+#### `injectAddressElement(containerId, options?)`
+Inject a standalone address component (optional callbacks like `onAddressSet`).
+```js
+await client.injectAddressElement('address', {
+  onAddressSet: (address) => console.log(address)
+});
+```
+
+#### `injectCartElement(containerId)`
+Inject a standalone cart component (rare; cart drawer is automatic).
+```js
+await client.injectCartElement('cart');
+```
+
+#### `injectCheckoutElement(params)`
+Inject a hosted checkout into a container.
+```js
+await client.injectCheckoutElement({
+  containerId: 'checkout',
+  checkoutId: 'checkout_abc123',
+  hideHeader: false
+});
+```
+
+
+### Actions (`client.actions.*`)
+Actions are programmatic controls for state changes and flows. The full list with details is in [Actions](./actions.md).
+
+```js
+// Example: add to cart and open cart
+await window.elements.actions.cart.addProduct([
+  { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }
+], true);
+```
+
+### UI helpers (`client.ui.*`)
+Helpers for common cart UI elements that stay in sync automatically.
+
+#### `ui.cartButton(containerId, showItemsCount?)`
+Renders a cart button in a container.
+```js
+window.elements.ui.cartButton('header-cart', true);
+```
+
+#### `ui.floatingCartButton(showItemsCount?)`
+Renders a floating cart button (bottom-right).
+```js
+window.elements.ui.floatingCartButton(true);
+```
+
+#### `ui.cartSubtotal(elementId)`
+Keeps a DOM element updated with cart subtotal.
+```html
+<span id="cart-total"></span>
+```
+```js
+window.elements.ui.cartSubtotal('cart-total');
+```
+
+#### `ui.cartItemsCount(elementId, { hideZero })`
+Keeps a DOM element updated with item count.
+```html
+<span id="items-count"></span>
+```
+```js
+window.elements.ui.cartItemsCount('items-count', { hideZero: true });
+```
+
+### Component management
+You can inspect and re-render injected components.
+
+- `getInjectedComponents()`  
+  Returns a map of injected components keyed by container ID.
+
+```js
+const components = client.getInjectedComponents();
+const productComponent = components.get('product-1');
+
+productComponent.getType();    // 'product'
+productComponent.getElement(); // underlying element
+productComponent.rerender();   // force re-render
+```
+
+## Recommended flow
+1. Initialize the client
+2. Inject product(s)
+3. Let the cart drawer handle checkout by default
+4. Use actions + events to track analytics and UI updates
+
+For details, see the component pages: Product, Cart, Checkout, Address, Actions, Events.

package/docs/gitbook/product.md

@@ -0,0 +1,64 @@
+# Product
+
+The Product component renders a complete product view with images, pricing, fulfillment options, and add-to-cart.
+
+## What you get
+- Image carousel
+- Name, description, pricing
+- Size selection (if applicable)
+- Fulfillment type selection (shipping or on-demand)
+- Retailer selection (when multiple retailers are available)
+- Personalization/engraving (when supported)
+- Quantity controls
+- Location-based availability and pricing
+
+## Add a product (CDN, declarative)
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-container-1="product"
+  data-product-1="00619947000020"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+
+<div id="product"></div>
+```
+
+## Add a product (programmatic)
+```js
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+await client.injectProductElement([
+  { containerId: 'product', identifier: '00619947000020' }
+]);
+```
+
+## Identifiers
+Use any of the supported identifiers:
+- UPC
+- Grouping ID
+
+The SDK resolves the correct product automatically.
+
+## Product actions
+```js
+const product = window.elements.actions.product.getDetails('00619947000020');
+console.log(product.name, product.price);
+```
+
+## Product events (examples)
+```js
+window.addEventListener('lce:actions.product_loaded', (event) => {
+  const { identifier, name, price } = event.detail.data;
+});
+
+window.addEventListener('lce:actions.product_add_to_cart', (event) => {
+  const { identifier, quantity, fulfillmentType } = event.detail.data;
+});
+```
+
+## Address requirement
+If an address is required for availability, the SDK automatically prompts the user to set it before adding to cart.