@liquidcommerce/elements-sdk 2.6.0-beta.84 → 2.6.0-beta.85

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

@@ -5,3 +5,6 @@ export interface IAddressActionEventData {
     address: IAddressAddress;
     coordinates: IAddressCoordinates;
 }
+export interface IAddressFailedEventData extends IAddressActionEventData {
+    error: string;
+}

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

@@ -1,4 +1,4 @@
-import type { IAddressActionEventData } from '@/core/pubsub/interfaces/address.interface';
+import type { IAddressActionEventData, IAddressFailedEventData } from '@/core/pubsub/interfaces/address.interface';
 import type { ICartFailedEventData, ICartItemAddedEventData, ICartItemEngravingUpdatedEventData, ICartItemQuantityChangedEventData, ICartItemRemovedEventData, ICartLoadedEventData, ICartProductAddEventData, ICartProductAddFailedEventData, ICartPromoCodeEventData, ICartPromoCodeFailedEventData, ICartUpdatedEventData } from '@/core/pubsub/interfaces/cart.interface';
 import type { ICheckoutBillingInformationUpdatedEventData, ICheckoutCustomerInformationUpdatedEventData, ICheckoutFailedEventData, ICheckoutGiftCardEventData, ICheckoutGiftCardFailedEventData, ICheckoutGiftInformationUpdatedEventData, ICheckoutItemEngravingUpdatedEventData, ICheckoutItemQuantityChangedEventData, ICheckoutItemRemovedEventData, ICheckoutLoadedEventData, ICheckoutMarketingPreferencesToggleEventData, ICheckoutProductAddEventData, ICheckoutProductAddFailedEventData, ICheckoutPromoCodeEventData, ICheckoutPromoCodeFailedEventData, ICheckoutSubmitCompletedEventData, ICheckoutSubmitFailedEventData, ICheckoutSubmitStartedEventData, ICheckoutTipUpdatedEventData, ICheckoutToggleEventData } from '@/core/pubsub/interfaces/checkout.interface';
 import type { IProductAddToCartEventData, IProductFulfillmentChangedEventData, IProductFulfillmentTypeChangedEventData, IProductLoadedEventData, IProductQuantityChangedEventData, IProductSizeChangedEventData } from '@/core/pubsub/interfaces/product.interface';
@@ -29,7 +29,7 @@ export interface IElementsActionsEventsMap {
     [ELEMENTS_ACTIONS_EVENT.CLIENT_READY]: IElementsClientIsReadyEventData;
     [ELEMENTS_ACTIONS_EVENT.ADDRESS_UPDATED]: IAddressActionEventData;
     [ELEMENTS_ACTIONS_EVENT.ADDRESS_CLEARED]: boolean;
-    [ELEMENTS_ACTIONS_EVENT.ADDRESS_FAILED]: IAddressActionEventData;
+    [ELEMENTS_ACTIONS_EVENT.ADDRESS_FAILED]: IAddressFailedEventData;
     [ELEMENTS_ACTIONS_EVENT.PRODUCT_LOADED]: IProductLoadedEventData;
     [ELEMENTS_ACTIONS_EVENT.PRODUCT_QUANTITY_DECREASE]: IProductQuantityChangedEventData;
     [ELEMENTS_ACTIONS_EVENT.PRODUCT_QUANTITY_INCREASE]: IProductQuantityChangedEventData;

package/docs/v1/api/actions/address-actions.md

@@ -49,11 +49,12 @@ setAddressManually(
 
 ```typescript
 interface IAddressAddress {
-  one: string;    // Street address
-  two?: string;   // Apt, suite, etc. (optional)
-  city: string;   // City name
-  state: string;  // Two-letter state code
-  zip: string;    // ZIP/postal code
+  one: string;     // Street address
+  two: string;     // Apt, suite, etc.
+  city: string;    // City name
+  state: string;   // Two-letter state code
+  zip: string;     // ZIP/postal code
+  country: string; // Country
 }
 
 interface IAddressCoordinates {
@@ -71,7 +72,8 @@ await window.LiquidCommerce.elements.actions.address.setAddressManually(
     two: 'Apt 4',
     city: 'New York',
     state: 'NY',
-    zip: '10001'
+    zip: '10001',
+    country: 'US'
   },
   {
     latitude: 40.7128,
@@ -83,17 +85,19 @@ await window.LiquidCommerce.elements.actions.address.setAddressManually(
 ### Validation
 
 The SDK validates:
-- All required fields are present
-- State is 2-letter code
+- All required fields are present (street, city, state, zip)
 - Latitude is between -90 and 90
 - Longitude is between -180 and 180
 
+> Note: the `state` field is expected to be a 2-letter code by convention, but the SDK does **not** enforce its format.
+
 ### Errors
 
 **Throws `SDKError` if:**
-- Required fields are missing
-- Coordinates are out of range
-- Address format is invalid
+- `address` or `coordinates` is missing
+- A required field is missing (street, city, state, zip)
+- Latitude or longitude is non-numeric
+- Coordinates are out of range (latitude outside -90..90, longitude outside -180..180)
 
 ---
 
@@ -135,13 +139,14 @@ getDetails(): IAddressData | null
 
 ```typescript
 interface IAddressData {
-  id: string;  // Google Places ID or generated ID
+  id: string;  // Google Places ID (always populated when an object is returned)
   address: {
     one: string;
-    two?: string;
+    two: string;
     city: string;
     state: string;
     zip: string;
+    country: string;
   };
   coordinates: {
     latitude: number;
@@ -151,7 +156,7 @@ interface IAddressData {
 }
 ```
 
-Returns `null` if no address is set.
+Returns `null` if no address is set. Manually-entered addresses (set via `setAddressManually`) are stored without a Google Places ID, so `getDetails()` also returns `null` for them.
 
 ### Example
 
@@ -194,7 +199,7 @@ Address actions trigger events:
 ```javascript
 // Address updated
 window.addEventListener('lce:actions.address_updated', (event) => {
-  const { address, coordinates, formattedAddress } = event.detail.data;
+  const { googlePlacesId, address, coordinates, formattedAddress } = event.detail.data;
   console.log('Address set:', formattedAddress);
 });
 

package/docs/v1/api/actions/cart-actions.md

@@ -78,7 +78,7 @@ addProduct(params: IAddProductParams[], openCart?: boolean): Promise<void>
 
 ```typescript
 interface IAddProductParams {
-  identifier: string;      // Product UPC, SKU, or ID
+  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)
@@ -145,8 +145,8 @@ If no address is set, the SDK automatically:
 - Identifier is invalid
 - Fulfillment type is not `'shipping'` or `'onDemand'`
 - Quantity is less than 1
-- Product is not available
-- Product is a presale item
+
+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).
 
 ---
 
@@ -242,17 +242,17 @@ getDetails(): IBaseCartEventData
 ```typescript
 interface IBaseCartEventData {
   cartId: string;
-  items: ICartItem[];
+  promoCodeDiscount: number | null;  // in cents
   subtotal: number;  // in cents
-  total: number;     // in cents
-  itemsCount: number;
-  itemsQuantity: number;
-  promoCode?: {
-    code: string;
-    discount: number;  // in cents
-  };
-  retailers: IRetailer[];
-  // ... additional fields
+  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;
 }
 ```
 
@@ -262,12 +262,11 @@ interface IBaseCartEventData {
 const cart = window.LiquidCommerce.elements.actions.cart.getDetails();
 
 console.log(`Cart ID: ${cart.cartId}`);
-console.log(`Items: ${cart.itemsCount}`);
+console.log(`Items: ${cart.itemCount}`);
 console.log(`Subtotal: $${cart.subtotal / 100}`);
-console.log(`Total: $${cart.total / 100}`);
 
-if (cart.promoCode) {
-  console.log(`Discount: $${cart.promoCode.discount / 100}`);
+if (cart.promoCodeDiscount) {
+  console.log(`Discount: $${cart.promoCodeDiscount / 100}`);
 }
 ```
 
@@ -279,8 +278,8 @@ if (cart.promoCode) {
 function updateCartSummary() {
   const cart = window.LiquidCommerce.elements.actions.cart.getDetails();
   
-  document.getElementById('cart-count').textContent = cart.itemsCount;
-  document.getElementById('cart-total').textContent = `$${cart.total / 100}`;
+  document.getElementById('cart-count').textContent = cart.itemCount;
+  document.getElementById('cart-total').textContent = `$${cart.subtotal / 100}`;
 }
 
 // Update on cart changes
@@ -293,7 +292,7 @@ window.addEventListener('lce:actions.cart_updated', updateCartSummary);
 document.getElementById('checkout-btn').addEventListener('click', () => {
   const cart = window.LiquidCommerce.elements.actions.cart.getDetails();
   
-  if (cart.itemsCount === 0) {
+  if (cart.itemCount === 0) {
     alert('Your cart is empty');
     return;
   }
@@ -308,10 +307,10 @@ document.getElementById('checkout-btn').addEventListener('click', () => {
 const cart = window.LiquidCommerce.elements.actions.cart.getDetails();
 
 gtag('event', 'view_cart', {
-  value: cart.total / 100,
+  value: cart.subtotal / 100,
   currency: 'USD',
-  items: cart.items.map(item => ({
-    item_id: item.identifier,
+  items: Object.values(cart.items).map(item => ({
+    item_id: item.partNumber,
     quantity: item.quantity
   }))
 });

package/docs/v1/api/actions/checkout-actions.md

@@ -60,7 +60,7 @@ window.LiquidCommerce.elements.actions.checkout.exitCheckout();
 addProduct(params: IAddProductParams[], openCheckout?: boolean): Promise<void>
 ```
 
-Add products directly to checkout, bypassing the cart.
+Add products and open checkout in one call. Products are added to the cart (via the cart action, or directly when none is wired up), then checkout is prepared and opened. For a checkout without a cart session, use `addAnonymousProduct`.
 
 `IAddProductParams.engravingLines?: string[]` — optional engraving. Same rules as [`actions.cart.addProduct()`](./cart-actions.md#actionscartaddproduct): invalid input is ignored, blanks stripped, lines clamped to the product's `maxLines` / `maxCharsPerLine`, and engraving is dropped (without failing) when the product, variant, or fulfillment doesn't support it.
 
@@ -94,15 +94,66 @@ addAnonymousProduct(
 
 Add a product to checkout without requiring a cart session. Used for direct-to-checkout flows.
 
+**Parameters** (`IAnonymousCheckoutAddProductParams`):
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `location` | `ILocation` | Yes | `{ address: IAddressAddress; coordinates: IAddressCoordinates }` |
+| `items` | `IAnonymousCheckoutAddProductItem[]` | No | Products to add: `{ identifier, fulfillmentType, quantity }`. Provide `items` **or** `cartItems`. |
+| `cartItems` | `ICartUpdateItem[]` | No | Pre-resolved cart line items: `{ id?, partNumber, quantity, fulfillmentId, engravingLines? }` (alternative to `items`). |
+| `promoCode` | `string` | No | Promo code applied while creating the anonymous checkout. |
+
 ```javascript
 const result = await window.LiquidCommerce.elements.actions.checkout
   .addAnonymousProduct({
-    identifier: '00619947000020',
-    fulfillmentType: 'shipping',
-    quantity: 1
+    items: [
+      { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }
+    ],
+    location: {
+      address: { one: '123 Main St', two: '', city: 'New York', state: 'NY', zip: '10001', country: 'US' },
+      coordinates: { latitude: 40.7128, longitude: -74.006 }
+    },
+    promoCode: 'WELCOME10'  // optional
   });
 ```
 
+**Returns** (`IAnonymousCheckoutAddProductResponse`):
+
+```typescript
+interface IAnonymousCheckoutAddProductResponse {
+  checkout: ICheckoutPrepare | null;        // the prepared checkout (see below), or null on failure
+  unavailableItems: IAnonymousCheckoutUnavailableItem[];
+}
+
+interface IAnonymousCheckoutUnavailableItem {
+  identifier: string;
+  productName: string | null;
+  fulfillmentType: FulfillmentType;         // 'shipping' | 'onDemand'
+  reason: 'product_not_available' | 'fulfillment_not_available';
+}
+
+interface ICheckoutPrepare {
+  token: string;
+  cartId: string;
+  customer: ICheckoutCustomer;
+  isGift: boolean;
+  billingSameAsShipping: boolean;
+  payment?: string;
+  giftOptions: ICheckoutGiftRecipient;
+  marketingPreferences: ICheckoutMarketingPreferences;
+  shippingAddress: ICheckoutShippingAddress;
+  billingAddress: ICheckoutBilling;
+  promoCode: ICheckoutPromoCode | null;
+  amounts: ICheckoutAmounts;
+  giftCards: ICheckoutGiftCard[];
+  presale: ICheckoutPresale | null;
+  itemsQuantity: number;
+  items: Record<string /* cart item ID */, ICheckoutItem>;
+  retailers: Record<string /* retailer ID */, ICheckoutRetailer>;
+  events: ICheckoutEvent[];
+}
+```
+
 ## Promo & Gift Card Actions
 
 ### actions.checkout.applyPromoCode()
@@ -219,7 +270,7 @@ Pre-fill customer information.
 **Available fields:**
 - `firstName`, `lastName`
 - `email`, `phone`
-- `birthdate`, `addressTwo`
+- `birthDate`, `addressTwo`
 - `company`
 
 ```javascript
@@ -228,7 +279,7 @@ window.LiquidCommerce.elements.actions.checkout.updateCustomerInfo({
   lastName: 'Doe',
   email: 'john@example.com',
   phone: '+15551234567',
-  birthdate: '1990-01-01',
+  birthDate: '1990-01-01',
   addressTwo: 'Apt 4B',
   company: 'Acme Corp'
 });
@@ -341,7 +392,7 @@ const checkout = window.LiquidCommerce.elements.actions.checkout.getDetails();
 
 console.log(`Cart ID: ${checkout.cartId}`);
 console.log(`Total: $${checkout.amounts.total / 100}`);
-console.log(`Items: ${checkout.items.length}`);
+console.log(`Items: ${checkout.itemCount}`);
 console.log(`Is Gift: ${checkout.isGift}`);
 ```
 
@@ -349,23 +400,19 @@ console.log(`Is Gift: ${checkout.isGift}`);
 
 ```typescript
 interface ICheckoutDetailsEventData {
+  token: string;
   cartId: string;
-  items: ICheckoutItem[];
-  amounts: {
-    subtotal: number;
-    tax: number;
-    shipping: number;
-    tip: number;
-    total: number;
-  };
-  customer: ICustomerInfo;
-  shippingAddress: IAddress;
-  billingAddress?: IAddress;
   isGift: boolean;
-  giftRecipient?: IGiftRecipient;
-  promoCode?: IPromoCode;
-  giftCards: IGiftCard[];
-  // ... additional fields
+  billingSameAsShipping: boolean;
+  marketingPreferences: {
+    canEmail: boolean;
+    canSms: boolean;
+  };
+  hasPromoCode: boolean;
+  hasGiftCards: boolean;
+  amounts: ICheckoutAmounts;
+  itemCount: number;
+  items: Record<string, ICheckoutItem>;
 }
 ```
 
@@ -419,11 +466,11 @@ window.addEventListener('lce:actions.checkout_submit_started', () => {
 });
 
 window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
-  const { orderId, total } = event.detail.data;
+  const { orderNumber, orderTotal } = event.detail.data;
   
   gtag('event', 'purchase', {
-    transaction_id: orderId,
-    value: total / 100,
+    transaction_id: orderNumber,
+    value: orderTotal / 100,
     currency: 'USD'
   });
 });

package/docs/v1/api/actions/product-actions.md

@@ -21,19 +21,22 @@ getDetails(identifier: string): IBaseProductEventData
 ### Returns
 
 ```typescript
+// Inherits all IProduct fields except `sizes` (see below for the overridden `sizes` shape)
 interface IBaseProductEventData {
   identifier: string;
   name: string;
   description: string;
-  price: number;  // in cents
-  selectedSize: IProductSize;
+  priceInfo: IProductPriceInfo | null;  // { currency, minimum, average, maximum }
+  selectedSizeId: string | null;
   selectedFulfillmentType: FulfillmentType;
-  selectedRetailer: IRetailer;
-  quantity: number;
+  selectedFulfillmentId: string | null;
+  productHasAvailability: boolean;
+  fulfillmentHasAvailability: boolean;
+  sizes: Record<string, IProductSizeEventData>;
   images: string[];
   brand: string;
   category: string;
-  // ... additional fields
+  // ... additional IProduct fields
 }
 ```
 
@@ -43,17 +46,16 @@ interface IBaseProductEventData {
 const productData = window.LiquidCommerce.elements.actions.product.getDetails('00619947000020');
 
 console.log(productData.name);        // "Premium Whiskey"
-console.log(productData.price / 100); // 49.99
-console.log(productData.selectedSize.name); // "750ml"
-console.log(productData.quantity);     // 1
+console.log(productData.priceInfo?.minimum / 100); // 49.99
+console.log(productData.sizes[productData.selectedSizeId]?.size); // "750ml"
+console.log(productData.selectedSizeId); // "size_123"
 ```
 
 ### Errors
 
 **Throws `SDKError` if:**
 - Identifier is empty or invalid
-- Product has not been loaded yet
-- Product does not exist
+- Product has not been loaded yet (a non-existent product surfaces as this same error)
 
 ```javascript
 try {
@@ -71,7 +73,7 @@ try {
 const product = window.LiquidCommerce.elements.actions.product.getDetails('00619947000020');
 
 document.getElementById('product-name').textContent = product.name;
-document.getElementById('product-price').textContent = `$${product.price / 100}`;
+document.getElementById('product-price').textContent = `$${product.priceInfo?.minimum / 100}`;
 ```
 
 #### Sync with Analytics
@@ -84,7 +86,7 @@ window.addEventListener('lce:actions.product_loaded', () => {
     items: [{
       item_id: product.identifier,
       item_name: product.name,
-      price: product.price / 100,
+      price: product.priceInfo?.minimum / 100,
       item_brand: product.brand
     }]
   });
@@ -97,7 +99,7 @@ window.addEventListener('lce:actions.product_loaded', () => {
 const product1 = window.LiquidCommerce.elements.actions.product.getDetails('00619947000020');
 const product2 = window.LiquidCommerce.elements.actions.product.getDetails('08504405135');
 
-if (product1.price < product2.price) {
+if (product1.priceInfo?.minimum < product2.priceInfo?.minimum) {
   console.log(`${product1.name} is cheaper`);
 }
 ```
@@ -124,14 +126,58 @@ getProductAvailabilityByState(
 | `identifiers` | string[] | Yes      | Array of product UPCs, SKUs, or IDs      |
 | `state`       | string   | No       | Two-letter state code (e.g., `'NY'`)     |
 
+### Returns
+
+Resolves to an `IProductAvailabilityResponse`:
+
+```typescript
+interface IProductAvailabilityResponse {
+  products: IProduct[];
+  retailers: Record<string /* retailer ID */, IRetailer>;
+}
+
+interface IRetailer {
+  id: string;
+  name: string;
+  address: IRetailerAddress;          // IAddressAddress & IAddressCoordinates
+  addressFormatted: string;
+  shippingFulfillment: IFulfillment | null;
+  onDemandFulfillment: IFulfillment | null;
+}
+
+interface IFulfillment {
+  id: string;
+  type: FulfillmentType;              // 'shipping' | 'onDemand'
+  doesAllowGiftCards: boolean;
+  doesAllowPromos: boolean;
+  expectation: string;
+  engravingExpectation: string;
+  fee: number;
+  timezone: string;
+  hourStatus: { isOpen: boolean; openTime: string; isClosed: boolean; closeTime: string };
+}
+
+interface IProduct {
+  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;
+  priceInfo: IProductPriceInfo | null;  // { currency, minimum, average, maximum } — cents
+  sizes: Record<string /* size ID */, IProductSize>;
+}
+```
+
 ### Example
 
 ```javascript
 // Check availability in a specific state
-const availability = await window.LiquidCommerce.elements.actions.product
+const availabilityCA = await window.LiquidCommerce.elements.actions.product
   .getProductAvailabilityByState(['00619947000020', '08504405135'], 'CA');
 
-// Check availability in the user's current state (uses address if set)
+// Omit the state to query without a state filter
+// (state: undefined is sent — the SDK does NOT derive it from the stored address)
 const availability = await window.LiquidCommerce.elements.actions.product
   .getProductAvailabilityByState(['00619947000020']);
 ```

package/docs/v1/api/client.md

@@ -64,6 +64,36 @@ const client = await ElementsCheckout('YOUR_API_KEY', {
 });
 ```
 
+### ElementsBuilder()
+
+Initialize the builder client, which exposes manual `inject*` / `update*` methods for fully programmatic composition.
+
+```typescript
+function ElementsBuilder(
+  apiKey: string,
+  config: ILiquidCommerceElementsBuilderConfig
+): Promise<ILiquidCommerceElementsBuilderClient | null>
+```
+
+**Parameters:**
+
+| Parameter | Type                                 | Required | Description                 |
+|-----------|--------------------------------------|----------|-----------------------------|
+| `apiKey`  | string                               | Yes      | Your LiquidCommerce API key |
+| `config`  | ILiquidCommerceElementsBuilderConfig | Yes      | Builder configuration object (same shape as `ILiquidCommerceElementsConfig`) |
+
+**Returns:** Promise that resolves to the builder client instance (`ILiquidCommerceElementsBuilderClient`), or `null` if initialization fails or it is called outside the browser.
+
+**Example:**
+
+```javascript
+import { ElementsBuilder } from '@liquidcommerce/elements-sdk';
+
+const builder = await ElementsBuilder('YOUR_API_KEY', {
+  env: 'production'
+});
+```
+
 ## Configuration
 
 ### ILiquidCommerceElementsConfig
@@ -72,10 +102,8 @@ Complete configuration interface for the full SDK.
 
 ```typescript
 interface ILiquidCommerceElementsConfig {
-  // Required
-  env: ElementsEnv;  // 'development' | 'staging' | 'production'
-
   // Optional
+  env?: ElementsEnv;  // defaults to 'production' ('development' | 'staging' | 'production')
   debugMode?: DebugMode;  // 'none' | 'console' | 'panel'
   customTheme?: IClientCustomThemeConfig;
   promoTicker?: IPromoTicker[];
@@ -168,7 +196,7 @@ See [Proxy Setup Guide](../integration/proxy-setup.md) for implementation.
 
 ```typescript
 interface ILiquidCommerceElementsCheckoutConfig {
-  pageUrl: string;  // URL pattern with {token} placeholder
+  pageUrl?: string;  // Optional. URL pattern with {token} placeholder
 }
 ```
 
@@ -186,6 +214,7 @@ checkout: {
 interface ILiquidCommerceElementsDevelopmentConfig {
   customApiUrl?: string;
   openShadowDom?: boolean;
+  mockMode?: boolean;  // enable mock data responses (sends 'X-Liquid-Api-Mock-Mode' header)
 }
 ```
 
@@ -194,16 +223,18 @@ interface ILiquidCommerceElementsDevelopmentConfig {
 ```javascript
 development: {
   customApiUrl: 'http://localhost:3000/api',
-  openShadowDom: true  // Disable Shadow DOM for debugging
+  openShadowDom: true  // Use an OPEN (inspectable) Shadow DOM instead of the default closed mode; forced off in production
 }
 ```
 
 ## Global Access
 
-After initialization, the client is available globally under the `window.LiquidCommerce` namespace:
+After initialization, each client is available globally under the `window.LiquidCommerce` namespace:
 
 ```javascript
-window.LiquidCommerce.elements
+window.LiquidCommerce.elements          // full client (from Elements())
+window.LiquidCommerce.elementsBuilder   // builder client (from ElementsBuilder())
+window.LiquidCommerce.elementsCheckout  // checkout-only client (from ElementsCheckout())
 ```
 
 This allows access from anywhere in your application:
@@ -397,13 +428,6 @@ import type {
   IInjectCheckoutParams,
   IInjectedComponent,
 
-  // Action types
-  IProductActions,
-  ICartActions,
-  ICheckoutActions,
-  IAddressActions,
-  IAddProductParams,
-
   // Configuration types
   IClientCustomThemeConfig,
   IComponentGlobalConfigs,

package/docs/v1/api/configuration.md

@@ -171,6 +171,7 @@ interface IProductLayout {
   showOnlyMainImage: boolean;
   showTitle: boolean;
   showDescription: boolean;
+  descriptionPosition: 'above' | 'below';
   showQuantityCounter: boolean;
   showOffHours: boolean;
   quantityCounterStyle: 'outlined' | 'ghost';
@@ -192,6 +193,7 @@ interface IProductLayout {
 | `showOnlyMainImage` | `boolean` | Show only the main product image (no carousel) |
 | `showTitle` | `boolean` | Show product title |
 | `showDescription` | `boolean` | Show product description |
+| `descriptionPosition` | `'above' \| 'below'` | Placement of the product description relative to other content |
 | `showQuantityCounter` | `boolean` | Show quantity selector |
 | `showOffHours` | `boolean` | Show off-hours messaging |
 | `quantityCounterStyle` | `'outlined' \| 'ghost'` | Visual style for quantity counter |
@@ -509,13 +511,15 @@ See [Proxy Setup Guide](../integration/proxy-setup.md) for implementation detail
 interface ILiquidCommerceElementsDevelopmentConfig {
   customApiUrl?: string;
   openShadowDom?: boolean;
+  mockMode?: boolean;
 }
 ```
 
 | Property | Type | Description |
 |----------|------|-------------|
 | `customApiUrl` | `string` | Custom API URL for local or custom backend testing |
-| `openShadowDom` | `boolean` | Disable Shadow DOM isolation for debugging (default: `false`) |
+| `openShadowDom` | `boolean` | Use an OPEN (inspectable) Shadow DOM instead of the default closed mode, for debugging. Shadow DOM is always attached; forced off in production (default: `false`) |
+| `mockMode` | `boolean` | Enable mock mode to receive mock data from the API; sends an `X-Liquid-Api-Mock-Mode` header with all requests (default: `false`) |
 
 > To pre-select a payment method and skip the card form (in any environment), use [`actions.checkout.setSavedPaymentMethod`](./actions/checkout-actions.md#actionscheckoutsetsavedpaymentmethod) instead.
 

package/docs/v1/api/injection-methods.md

@@ -53,9 +53,12 @@ injectAddressElement(
 
 ```javascript
 await client.injectAddressElement('address-container', {
-  onAddressSet: (address) => {
-    console.log('Address set:', address);
-  }
+  showLabel: true
+});
+
+// Listen for address changes via the published event (dispatched on window)
+window.addEventListener('lce:actions.address_updated', (event) => {
+  console.log('Address set:', event.detail.data);
 });
 ```
 
@@ -127,7 +130,7 @@ injectProductList(params: IInjectProductListParams): Promise<void>
 interface IInjectProductListParams {
   containerId: string;
   slug: string;              // Product list slug identifier
-  rows?: number;             // Default: 3
+  rows?: number;             // Default: 4
   columns?: number;          // Default: 4
   filters?: ProductListFilterType[];
   productUrl?: PLCProductUrl;  // string template OR Record<identifier, url> map
@@ -192,6 +195,7 @@ injectProductListSearch(params: IInjectProductListSearchParams): Promise<void>
 interface IInjectProductListSearchParams {
   containerId: string;
   slug: string;  // Product list slug identifier
+  filters?: ProductListFilterType[];
 }
 ```