@liquidcommerce/elements-sdk 2.7.0 → 2.7.2

package/docs/gitbook/actions.md

@@ -0,0 +1,964 @@
+# 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, and more). The product must already be injected and loaded.
+
+**Signature**
+
+```ts
+getDetails(identifier: string): IBaseProductEventData
+```
+
+**Return shape (TypeScript)**
+
+```ts
+export type FulfillmentType = 'onDemand' | 'shipping';
+
+export interface IBaseProductEventData {
+  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
+const product = window.elements.actions.product.getDetails('00619947000020');
+console.log(product.name, product.price / 100);
+```
+
+## Cart actions
+
+### `actions.cart.openCart()`
+
+Opens the cart drawer.
+
+**Signature**
+
+```ts
+openCart(): void
+```
+
+**Example**
+
+```js
+window.elements.actions.cart.openCart();
+```
+
+### `actions.cart.closeCart()`
+
+Closes the cart drawer.
+
+**Signature**
+
+```ts
+closeCart(): void
+```
+
+**Example**
+
+```js
+window.elements.actions.cart.closeCart();
+```
+
+### `actions.cart.toggleCart()`
+
+Toggles the cart drawer open/closed.
+
+**Signature**
+
+```ts
+toggleCart(): void
+```
+
+**Example**
+
+```js
+document.getElementById('cart-btn').addEventListener('click', () => {
+  window.elements.actions.cart.toggleCart();
+});
+```
+
+### `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.
+
+**Signature**
+
+```ts
+addProduct(params: IAddProductParams[], openCart?: boolean): Promise<void>
+```
+
+**Parameters (TypeScript)**
+
+```ts
+export type FulfillmentType = 'onDemand' | 'shipping';
+
+export interface IAddProductParams {
+  identifier: string;
+  fulfillmentType: FulfillmentType;
+  quantity: number;
+}
+```
+
+**Example**
+
+```js
+await window.elements.actions.cart.addProduct([
+  { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 },
+  { identifier: '08504405135', fulfillmentType: 'onDemand', quantity: 2 }
+], true);
+```
+
+### `actions.cart.applyPromoCode(promoCode)`
+
+Applies a promo code to the cart (replaces any existing code).
+
+**Signature**
+
+```ts
+applyPromoCode(promoCode: string): Promise<void>
+```
+
+**Example**
+
+```js
+try {
+  await window.elements.actions.cart.applyPromoCode('SUMMER20');
+} catch (error) {
+  console.error('Promo code invalid:', error);
+}
+```
+
+### `actions.cart.removePromoCode()`
+
+Removes the active promo code.
+
+**Signature**
+
+```ts
+removePromoCode(): Promise<void>
+```
+
+**Example**
+
+```js
+await window.elements.actions.cart.removePromoCode();
+```
+
+### `actions.cart.resetCart()`
+
+Clears all cart items (no undo).
+
+**Signature**
+
+```ts
+resetCart(): Promise<void>
+```
+
+**Example**
+
+```js
+await window.elements.actions.cart.resetCart();
+```
+
+### `actions.cart.getDetails()`
+
+Returns current cart data (items, totals, promo, retailers, location, etc.).
+
+**Signature**
+
+```ts
+getDetails(): IBaseCartEventData
+```
+
+**Return 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
+const cart = window.elements.actions.cart.getDetails();
+console.log(cart.cartId, cart.itemCount, cart.subtotal / 100);
+```
+
+## Checkout actions
+
+### `actions.checkout.openCheckout()`
+
+Opens the checkout drawer or navigates to checkout.
+
+**Signature**
+
+```ts
+openCheckout(): void
+```
+
+**Example**
+
+```js
+window.elements.actions.checkout.openCheckout();
+```
+
+### `actions.checkout.closeCheckout()`
+
+Closes the checkout drawer.
+
+**Signature**
+
+```ts
+closeCheckout(): void
+```
+
+**Example**
+
+```js
+window.elements.actions.checkout.closeCheckout();
+```
+
+### `actions.checkout.toggleCheckout()`
+
+Toggles the checkout drawer open/closed.
+
+**Signature**
+
+```ts
+toggleCheckout(): void
+```
+
+**Example**
+
+```js
+window.elements.actions.checkout.toggleCheckout();
+```
+
+### `actions.checkout.exitCheckout()`
+
+Navigates away from checkout (requires `exitUrl` configuration).
+
+**Signature**
+
+```ts
+exitCheckout(): void
+```
+
+**Example**
+
+```js
+window.elements.actions.checkout.exitCheckout();
+```
+
+### `actions.checkout.addProduct(params[], openCheckout?)`
+
+Adds products directly to checkout (bypasses cart).
+
+**Signature**
+
+```ts
+addProduct(params: IAddProductParams[], openCheckout?: boolean): Promise<void>
+```
+
+**Parameters (TypeScript)**
+
+```ts
+export type FulfillmentType = 'onDemand' | 'shipping';
+
+export interface IAddProductParams {
+  identifier: string;
+  fulfillmentType: FulfillmentType;
+  quantity: number;
+}
+```
+
+**Example**
+
+```js
+await window.elements.actions.checkout.addProduct([
+  { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }
+], true);
+```
+
+### `actions.checkout.applyPromoCode(promoCode)`
+
+Applies a promo code in checkout.
+
+**Signature**
+
+```ts
+applyPromoCode(promoCode: string): Promise<void>
+```
+
+**Example**
+
+```js
+await window.elements.actions.checkout.applyPromoCode('WELCOME10');
+```
+
+### `actions.checkout.removePromoCode()`
+
+Removes the active promo code in checkout.
+
+**Signature**
+
+```ts
+removePromoCode(): Promise<void>
+```
+
+**Example**
+
+```js
+await window.elements.actions.checkout.removePromoCode();
+```
+
+### `actions.checkout.applyGiftCard(code)`
+
+Applies a gift card.
+
+**Signature**
+
+```ts
+applyGiftCard(code: string): Promise<void>
+```
+
+**Example**
+
+```js
+await window.elements.actions.checkout.applyGiftCard('GIFT-1234-5678-9012');
+```
+
+### `actions.checkout.removeGiftCard(code)`
+
+Removes a gift card.
+
+**Signature**
+
+```ts
+removeGiftCard(code: string): Promise<void>
+```
+
+**Example**
+
+```js
+await window.elements.actions.checkout.removeGiftCard('GIFT-1234-5678-9012');
+```
+
+### `actions.checkout.toggleIsGift(active?)`
+
+Enables/disables gift mode (toggles when omitted).
+
+**Signature**
+
+```ts
+toggleIsGift(active?: boolean): Promise<void>
+```
+
+**Example**
+
+```js
+await window.elements.actions.checkout.toggleIsGift(true);
+```
+
+### `actions.checkout.toggleBillingSameAsShipping(active?)`
+
+Sets whether billing address matches shipping.
+
+**Signature**
+
+```ts
+toggleBillingSameAsShipping(active?: boolean): Promise<void>
+```
+
+**Example**
+
+```js
+await window.elements.actions.checkout.toggleBillingSameAsShipping(false);
+```
+
+### `actions.checkout.toggleMarketingPreferences(field, active)`
+
+Sets marketing opt-in (`canEmail` or `canSms`).
+
+**Signature**
+
+```ts
+toggleMarketingPreferences(field: 'canEmail' | 'canSms', active: boolean): Promise<void>
+```
+
+**Example**
+
+```js
+await window.elements.actions.checkout.toggleMarketingPreferences('canEmail', true);
+```
+
+### `actions.checkout.updateCustomerInfo(fields)`
+
+Prefills customer info (name, email, phone, birthdate, etc.).
+
+**Signature**
+
+```ts
+updateCustomerInfo(params: Record<CustomerFieldName, string>): void
+```
+
+**Parameters (TypeScript)**
+
+```ts
+export type CustomerFieldName =
+  | 'firstName'
+  | 'lastName'
+  | 'email'
+  | 'phone'
+  | 'birthDate'
+  | 'addressTwo'
+  | 'company';
+```
+
+**Example**
+
+```js
+window.elements.actions.checkout.updateCustomerInfo({
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john@example.com',
+  phone: '+15551234567'
+});
+```
+
+### `actions.checkout.updateBillingInfo(fields)`
+
+Prefills billing address fields.
+
+**Signature**
+
+```ts
+updateBillingInfo(params: Record<BillingFieldName, string>): void
+```
+
+**Parameters (TypeScript)**
+
+```ts
+export type BillingFieldName =
+  | 'firstName'
+  | 'lastName'
+  | 'email'
+  | 'phone'
+  | 'company'
+  | 'addressOne'
+  | 'addressTwo'
+  | 'city'
+  | 'state'
+  | 'zipCode';
+```
+
+**Example**
+
+```js
+window.elements.actions.checkout.updateBillingInfo({
+  firstName: 'John',
+  lastName: 'Doe',
+  addressOne: '789 Elm St',
+  city: 'Chicago',
+  state: 'IL',
+  zipCode: '60601'
+});
+```
+
+### `actions.checkout.updateGiftInfo(fields)`
+
+Prefills gift recipient information.
+
+**Signature**
+
+```ts
+updateGiftInfo(params: Record<GiftFieldName, string>): void
+```
+
+**Parameters (TypeScript)**
+
+```ts
+export type GiftFieldName =
+  | 'firstName'
+  | 'lastName'
+  | 'email'
+  | 'phone'
+  | 'addressTwo'
+  | 'message';
+```
+
+**Example**
+
+```js
+window.elements.actions.checkout.updateGiftInfo({
+  firstName: 'Jane',
+  lastName: 'Smith',
+  message: 'Happy Birthday!'
+});
+```
+
+### `actions.checkout.getDetails()`
+
+Returns current checkout data (amounts, items, preferences, addresses, gift info, etc.).
+
+**Signature**
+
+```ts
+getDetails(): ICheckoutDetailsEventData
+```
+
+**Return shape (TypeScript)**
+
+```ts
+export interface ICheckoutDetailsEventData {
+  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
+const checkout = window.elements.actions.checkout.getDetails();
+console.log(checkout.cartId, checkout.amounts.total / 100);
+```
+
+## Address actions
+
+### `actions.address.setAddressByPlacesId(placesId)`
+
+Sets address using a Google Places ID (recommended).
+
+**Signature**
+
+```ts
+setAddressByPlacesId(placesId: string): Promise<void>
+```
+
+**Example**
+
+```js
+await window.elements.actions.address.setAddressByPlacesId('ChIJOwg_06VPwokRYv534QaPC8g');
+```
+
+### `actions.address.setAddressManually(address, coordinates)`
+
+Sets address with your own address + lat/long data.
+
+**Signature**
+
+```ts
+setAddressManually(address: IAddressAddress, coordinates: IAddressCoordinates): Promise<void>
+```
+
+**Parameters (TypeScript)**
+
+```ts
+export interface IAddressAddress {
+  one: string;
+  two: string;
+  city: string;
+  state: string;
+  zip: string;
+  country: string;
+}
+
+export interface IAddressCoordinates {
+  latitude: number;
+  longitude: number;
+}
+```
+
+**Example**
+
+```js
+await window.elements.actions.address.setAddressManually(
+  { one: '123 Main Street', city: 'New York', state: 'NY', zip: '10001' },
+  { latitude: 40.7128, longitude: -74.0060 }
+);
+```
+
+### `actions.address.getDetails()`
+
+Returns the current address (or `null` if not set).
+
+**Signature**
+
+```ts
+getDetails(): IAddressData | null
+```
+
+**Return shape (TypeScript)**
+
+```ts
+export interface IAddressData {
+  id: 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
+const address = window.elements.actions.address.getDetails();
+console.log(address?.formattedAddress);
+```
+
+### `actions.address.clear()`
+
+Removes the stored address and resets availability.
+
+**Signature**
+
+```ts
+clear(): Promise<void>
+```
+
+**Example**
+
+```js
+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 });
+```