@liquidcommerce/elements-sdk 2.6.7 → 2.7.1

package/docs/CONFIGURATION.md

@@ -1,853 +0,0 @@
-# Configuration Reference
-
-Complete reference for all LiquidCommerce Elements SDK configuration options.
-
-## Basic Configuration
-
-```javascript
-const client = await Elements('YOUR_API_KEY', {
-  env: 'production',
-  debugMode: 'none',
-  isBuilder: false,
-  customTheme: {},
-  proxy: {},
-  promoTicker: []
-});
-```
-
-## Configuration Options
-
-### `env` (required)
-
-**Type:** `'local' | 'development' | 'staging' | 'production'`  
-**Default:** `'production'`
-
-Specifies the API environment to use.
-
-```javascript
-env: 'production'  // Live environment
-env: 'staging'     // Pre-production testing
-env: 'development' // Development with extra logging
-env: 'local'       // Local development
-```
-
-**Environment URLs:**
-- `production`: `https://elements.liquidcommerce.us`
-- `staging`: `https://staging-elements.liquidcommerce.us`
-- `development`: `https://dev-elements.liquidcommerce.us`
-- `local`: `http://localhost:3000`
-
-### `debugMode`
-
-**Type:** `'none' | 'console' | 'panel'`  
-**Default:** `'none'`
-
-Controls logging and debugging output.
-
-```javascript
-debugMode: 'none'     // No logging (production)
-debugMode: 'console'  // Console logs only
-debugMode: 'panel'    // Visual debug panel + console
-```
-
-**Debug panel features:**
-- Real-time event stream
-- API call inspector
-- State viewer
-- Performance metrics
-
-**Note:** Automatically disabled in production environment regardless of setting.
-
-### `isBuilder`
-
-**Type:** `boolean`  
-**Default:** `false`
-
-Enables builder mode for theme development and testing.
-
-```javascript
-isBuilder: true  // Enables builder.* methods
-```
-
-**Builder mode provides:**
-- `client.builder.updateComponentGlobalConfigs()`
-- `client.builder.updateProductComponent()`
-- `client.builder.updateCartComponent()`
-- `client.builder.updateCheckoutComponent()`
-- `client.builder.updateAddressComponent()`
-
-**Use case:** Theme customization and testing.
-
-### `customTheme`
-
-**Type:** `object`  
-**Default:** `{}`
-
-Custom theme configuration. See [`THEMING.md`](./THEMING.md) for complete reference.
-
-```javascript
-customTheme: {
-  global: {
-    colors: {
-      primary: '#007bff',
-      secondary: '#6c757d'
-    },
-    typography: {
-      fontFamily: 'Inter, sans-serif',
-      fontSize: '16px'
-    },
-    layout: {
-      enablePersonalization: true,
-      personalizationText: 'Personalize your product',
-      personalizationCardStyle: 'outlined',
-      allowPromoCodes: true,
-      inputFieldStyle: 'outlined',
-      poweredByMode: 'light' // Can be customized
-      // Note: showPoweredBy cannot be customized (controlled by LiquidCommerce)
-    }
-  },
-  product: { /* product theme */ },
-  cart: { /* cart theme */ },
-  checkout: { /* checkout theme */ },
-  address: { /* address theme */ }
-}
-```
-
-**Key Theme Categories:**
-
-- **`global`**: Affects all components (colors, fonts, personalization settings)
-- **`product`**: Product display customization
-- **`cart`**: Cart drawer and item display
-- **`checkout`**: Checkout flow and completion screen
-- **`address`**: Address input and selection
-
-**Personalization (Engraving) Settings:**
-
-The personalization feature is configured in `global.layout`:
-
-```javascript
-customTheme: {
-  global: {
-    layout: {
-      enablePersonalization: true,              // Enable/disable engraving globally
-      personalizationText: 'Make it yours',     // Button text for adding personalization
-      personalizationCardStyle: 'outlined'      // Style: 'outlined' | 'filled'
-    }
-  }
-}
-```
-
-- **`enablePersonalization`**: Master switch for engraving feature
-- **`personalizationText`**: Call-to-action text on product pages
-- **`personalizationCardStyle`**: Visual style in cart/checkout ('outlined' or 'filled')
-- **`poweredByMode`**: Visual mode for "Powered by" branding ('light' or 'dark')
-
-**Protected Setting:**  
-⚠️ **`showPoweredBy`** is a read-only setting controlled by LiquidCommerce. This paid feature cannot be customized through the `customTheme` configuration and is managed via your LiquidCommerce dashboard. However, you can customize `poweredByMode` to match your site's theme.
-
-### `proxy`
-
-**Type:** `object`  
-**Default:** `null`
-
-Proxy configuration for routing API requests through your server.
-
-```javascript
-proxy: {
-  baseUrl: 'https://yourdomain.com/api/liquidcommerce',
-  headers: {
-    'X-Custom-Header': 'value'
-  }
-}
-```
-
-**Properties:**
-
-#### `proxy.baseUrl`
-
-**Type:** `string` (required)
-
-Base URL for your proxy endpoint.
-
-```javascript
-baseUrl: 'https://yourdomain.com/api/liquidcommerce'
-```
-
-The SDK automatically appends API paths: `/api/products`, `/api/cart`, etc.
-
-#### `proxy.headers`
-
-**Type:** `object` (optional)
-
-Custom headers to include in proxied requests.
-
-```javascript
-headers: {
-  'X-Custom-Auth': 'your-token',
-  'X-Request-Id': 'unique-id'
-}
-```
-
-See [`PROXY.md`](./PROXY.md) for implementation guide.
-
-### `promoTicker`
-
-**Type:** `array`  
-**Default:** `[]`
-
-Promotional ticker configuration for rotating messages.
-
-```javascript
-promoTicker: [
-  {
-    promoCode: 'FREESHIP',
-    text: ['Free Shipping Today!', 'Use code FREESHIP'],
-    separator: '•',
-    activeFrom: '2025-01-01T00:00:00Z',
-    activeUntil: '2025-12-31T23:59:59Z'
-  }
-]
-```
-
-**Properties:**
-
-#### `promoCode` (required)
-
-**Type:** `string`
-
-The promo code to apply when clicked.
-
-#### `text` (required)
-
-**Type:** `string[]`
-
-Array of messages to rotate through.
-
-```javascript
-text: ['Message 1', 'Message 2', 'Message 3']
-```
-
-#### `separator` (optional)
-
-**Type:** `string`  
-**Default:** `'•'`
-
-Separator between rotating messages.
-
-```javascript
-separator: '•'   // Bullet
-separator: '|'   // Pipe
-separator: '→'   // Arrow
-```
-
-#### `activeFrom` (optional)
-
-**Type:** `string` (ISO 8601)
-
-Start date/time for the promotion.
-
-```javascript
-activeFrom: '2025-01-01T00:00:00Z'
-```
-
-#### `activeUntil` (optional)
-
-**Type:** `string` (ISO 8601)
-
-End date/time for the promotion.
-
-```javascript
-activeUntil: '2025-12-31T23:59:59Z'
-```
-
-**Note:** Only active promotions are displayed.
-
-## Auto-Initialization Configuration
-
-When using auto-initialization, configure via `data-` attributes on the script tag.
-
-### Required Attributes
-
-```html
-<script
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-#### `data-liquid-commerce-elements`
-
-**Type:** flag (no value)
-
-Enables auto-initialization.
-
-#### `data-token`
-
-**Type:** `string` (required)
-
-Your LiquidCommerce API key.
-
-### Optional Attributes
-
-#### `data-env`
-
-**Type:** `'production' | 'staging' | 'development' | 'local'`  
-**Default:** `'production'`
-
-```html
-data-env="production"
-```
-
-#### `data-debug-mode`
-
-**Type:** `'console' | 'panel'`  
-**Default:** Not set
-
-```html
-data-debug-mode="console"
-```
-
-#### `data-cart-button`
-
-**Type:** `string`
-
-Container ID, CSS selector, or position-prefixed selector for simple cart button (no badge).
-
-```html
-<!-- Simple ID (with or without # prefix) -->
-data-cart-button="header-cart"              <!-- Works with or without # -->
-data-cart-button="#header-cart"             <!-- Also works with # prefix -->
-
-<!-- CSS Selector (from browser inspect tool) -->
-data-cart-button=".header .nav-links"
-data-cart-button="#main-navigation"
-
-<!-- Position-prefixed selectors -->
-data-cart-button="above:.header .logo"      <!-- Place above the target -->
-data-cart-button="below:#main-navigation"  <!-- Place below the target -->
-data-cart-button="below:main-navigation"   <!-- Also works without # prefix -->
-data-cart-button="replace:.old-cart"       <!-- Replace the target -->
-data-cart-button="inside:.header .nav"     <!-- Place inside the target (default) -->
-
-<!-- Floating cart button (no badge) -->
-data-cart-button=""                         <!-- Empty value = floating button -->
-```
-
-**Smart Fallback Behavior:**
-- If the target element is not found, automatically falls back to floating cart button
-- If attribute is present but empty (`data-cart-button=""`), creates floating cart button without badge
-- Element IDs are automatically prefixed with `#` if needed (e.g., `header-cart` becomes `#header-cart`)
-
-#### `data-cart-badge-button`
-
-**Type:** `string`
-
-Container ID, CSS selector, or position-prefixed selector for cart button with item count badge.
-
-```html
-<!-- Simple ID (with or without # prefix) -->
-data-cart-badge-button="header-cart"        <!-- Works with or without # -->
-data-cart-badge-button="#header-cart"       <!-- Also works with # prefix -->
-
-<!-- CSS Selector (from browser inspect tool) -->
-data-cart-badge-button=".header .nav-links"
-data-cart-badge-button="#main-navigation"
-
-<!-- Position-prefixed selectors -->
-data-cart-badge-button="above:.header .logo"      <!-- Place above the target -->
-data-cart-badge-button="below:#main-navigation"  <!-- Place below the target -->
-data-cart-badge-button="replace:.old-cart"       <!-- Replace the target -->
-data-cart-badge-button="inside:.header .nav"     <!-- Place inside the target (default) -->
-
-<!-- Floating cart button with badge (default) -->
-data-cart-badge-button=""                   <!-- Empty value = floating button with badge -->
-```
-
-**Smart Fallback Behavior:**
-- If the target element is not found, automatically falls back to floating cart button with badge
-- If attribute is present but empty (`data-cart-badge-button=""`), creates floating cart button with badge
-- Element IDs are automatically prefixed with `#` if needed
-- If neither `data-cart-button` nor `data-cart-badge-button` is provided, defaults to floating cart button with badge
-
-**Position Prefixes:**
-- `above:` - Place above the target element
-- `below:` - Place below the target element  
-- `replace:` - Replace the target element
-- `inside:` - Place inside the target element (default)
-
-#### `data-cart-button-hidden`
-
-**Type:** flag (no value)
-
-Hide cart button completely. Use this when you want to manage cart display manually via `client.actions.cart.openCart()`.
-
-```html
-data-cart-button-hidden
-```
-
-**Important:** When this attribute is present, the SDK will skip all cart button setup, including floating buttons. This takes precedence over `data-cart-button` and `data-cart-badge-button` attributes.
-
-### Cart Button Examples
-
-**Simple cart button (no badge):**
-```html
-<script 
-  data-liquid-commerce-elements
-  data-token="your-api-key"
-  data-cart-button="header-cart"
-  src="elements.js">
-</script>
-```
-
-**Cart button with item count badge:**
-```html
-<script 
-  data-liquid-commerce-elements
-  data-token="your-api-key"
-  data-cart-badge-button="header-cart"
-  src="elements.js">
-</script>
-```
-
-**Using position-prefixed selectors:**
-```html
-<!-- Place inside the target element (default) -->
-<script 
-  data-liquid-commerce-elements
-  data-token="your-api-key"
-  data-cart-badge-button="inside:.header .nav-links"
-  src="elements.js">
-</script>
-
-<!-- Place above the target element -->
-<script 
-  data-liquid-commerce-elements
-  data-token="your-api-key"
-  data-cart-button="above:.header .logo"
-  src="elements.js">
-</script>
-
-<!-- Place below the target element -->
-<script 
-  data-liquid-commerce-elements
-  data-token="your-api-key"
-  data-cart-badge-button="below:#main-navigation"
-  src="elements.js">
-</script>
-
-<!-- Replace the target element -->
-<script 
-  data-liquid-commerce-elements
-  data-token="your-api-key"
-  data-cart-button="replace:.old-cart-button"
-  src="elements.js">
-</script>
-```
-
-**No cart button:**
-```html
-<script 
-  data-liquid-commerce-elements
-  data-token="your-api-key"
-  data-cart-button-hidden
-  src="elements.js">
-</script>
-```
-
-**Default behavior (floating cart button with badge):**
-```html
-<script 
-  data-liquid-commerce-elements
-  data-token="your-api-key"
-  src="elements.js">
-</script>
-```
-
-### Getting CSS Selectors from Browser
-
-**Super Easy Method:**
-1. **Right-click** on any element where you want the cart button
-2. Select **"Inspect"** or **"Inspect Element"**
-3. In developer tools, **right-click** on the highlighted element
-4. Select **"Copy" → "Copy selector"**
-5. Paste the selector into your `data-cart-button` or `data-cart-badge-button` attribute
-
-**Example:**
-```html
-<!-- After copying selector from browser inspect tool -->
-<script 
-  data-liquid-commerce-elements
-  data-token="your-api-key"
-  data-cart-badge-button="body > div.container > header > nav > div.nav-links"
-  src="elements.js">
-</script>
-```
-
-### Product Configuration
-
-#### Method 1: Direct Attributes
-
-```html
-data-container-1="product-1"
-data-product-1="00619947000020"
-data-container-2="product-2"
-data-product-2="00832889005513"
-```
-
-#### Method 2: JSON Configuration
-
-```html
-<script data-liquid-commerce-elements-products type="application/json">
-[
-  { "containerId": "product-1", "identifier": "00619947000020" },
-  { "containerId": "product-2", "identifier": "00832889005513" }
-]
-</script>
-```
-
-#### Method 3: Annotated Elements
-
-```html
-<div data-lce-product="00619947000020"></div>
-<div data-lce-product="00832889005513"></div>
-```
-
-### Product List Configuration
-
-```html
-<div data-liquid-commerce-elements-products-list
-     data-card="standard"
-     data-rows="3"
-     data-columns="4"
-     data-card-fill
-     data-filters="personalization,pre-order,delivery-options"
-     data-product-url="/product/{upc}">
-</div>
-```
-
-**Attributes:**
-
-##### `data-liquid-commerce-elements-products-list`
-
-**Type:** flag (no value)
-
-Enables product list on this div element.
-
-##### `data-card`
-
-**Type:** `'standard'`  
-**Default:** `'standard'`
-
-Card variant style.
-
-```html
-data-card="standard"
-```
-
-##### `data-rows`
-
-**Type:** `number`  
-**Default:** `3`
-
-Number of rows to display per page.
-
-```html
-data-rows="4"
-```
-
-##### `data-columns`
-
-**Type:** `number`  
-**Default:** `4`
-
-Number of columns in the grid.
-
-```html
-data-columns="4"
-```
-
-##### `data-card-fill`
-
-**Type:** flag (no value)
-
-Whether cards should fill the whole card with white background color to match the image background color.
-
-```html
-data-card-fill
-```
-
-##### `data-filters`
-
-**Type:** `string` (comma-separated)
-
-Filter types to enable: `personalization`, `pre-order`, `delivery-options`.
-
-```html
-data-filters="personalization,pre-order,delivery-options"
-```
-
-**Available filters:**
-- `personalization` - Show filter for personalized/engravable products
-- `pre-order` - Show filter for pre-order products
-- `delivery-options` - Show filter for delivery type (all, shipping, onDemand)
-
-##### `data-product-url`
-
-**Type:** `string`
-
-Product detail page URL template. Use `{upc}` or `{grouping}` placeholder.
-
-```html
-data-product-url="/product/{upc}"
-data-product-url="/products/{grouping}"
-```
-
-**Placeholders:**
-- `{upc}` - Replaced with product UPC
-- `{grouping}` - Replaced with Salsify grouping ID
-
-### URL Parameter Configuration
-
-#### `data-product-param`
-
-**Type:** `string`
-
-URL parameter name for auto-adding products to cart.
-
-```html
-data-product-param="lce_product"
-```
-
-**Usage:** `?lce_product=00619947000020&lce_fulfillment=shipping`
-
-#### `data-product-fulfillment-type-param`
-
-**Type:** `string`
-
-URL parameter name for fulfillment type.
-
-```html
-data-product-fulfillment-type-param="lce_fulfillment"
-```
-
-**Values:** `shipping` or `onDemand`
-
-#### `data-promo-code-param`
-
-**Type:** `string`
-
-URL parameter name for auto-applying promo codes.
-
-```html
-data-promo-code-param="lce_promo"
-```
-
-**Usage:** `?lce_promo=SUMMER20`
-
-### Promo Ticker Configuration
-
-#### `data-promo-code`
-
-**Type:** `string`
-
-Promo code to apply.
-
-```html
-data-promo-code="FREESHIP"
-```
-
-#### `data-promo-text`
-
-**Type:** `string` (pipe-separated)
-
-Messages to display.
-
-```html
-data-promo-text="Free Shipping Today!|Use code FREESHIP"
-```
-
-#### `data-promo-separator`
-
-**Type:** `string`  
-**Default:** `'•'`
-
-```html
-data-promo-separator="•"
-```
-
-#### `data-promo-active-from`
-
-**Type:** `string` (ISO 8601)
-
-```html
-data-promo-active-from="2025-01-01T00:00:00Z"
-```
-
-#### `data-promo-active-until`
-
-**Type:** `string` (ISO 8601)
-
-```html
-data-promo-active-until="2025-12-31T23:59:59Z"
-```
-
-## TypeScript Types
-
-### `ILiquidCommerceElementsConfig`
-
-```typescript
-interface ILiquidCommerceElementsConfig {
-  env?: 'local' | 'development' | 'staging' | 'production';
-  debugMode?: 'none' | 'console' | 'panel';
-  isBuilder?: boolean;
-  customTheme?: IClientCustomThemeConfig;
-  proxy?: IElementsProxyConfig;
-  promoTicker?: IPromoTicker[];
-}
-```
-
-### `IElementsProxyConfig`
-
-```typescript
-interface IElementsProxyConfig {
-  baseUrl: string;
-  headers?: Record<string, string>;
-}
-```
-
-### `IPromoTicker`
-
-```typescript
-interface IPromoTicker {
-  promoCode: string;
-  text: string[];
-  separator: string;
-  activeFrom: string; // ISO 8601 UTC format
-  activeUntil: string; // ISO 8601 UTC format
-}
-```
-
-## Configuration Examples
-
-### Production Setup
-
-```javascript
-const client = await Elements('YOUR_PRODUCTION_API_KEY', {
-  env: 'production',
-  debugMode: 'none',
-  proxy: {
-    baseUrl: 'https://yourdomain.com/api/liquidcommerce'
-  },
-  customTheme: {
-    global: {
-      colors: {
-        primary: '#007bff'
-      }
-    }
-  }
-});
-```
-
-### Development Setup
-
-```javascript
-const client = await Elements('YOUR_DEV_API_KEY', {
-  env: 'development',
-  debugMode: 'panel',
-  isBuilder: true,
-  customTheme: {
-    global: {
-      colors: {
-        primary: '#ff6b6b'
-      }
-    }
-  }
-});
-```
-
-### With Promo Ticker
-
-```javascript
-const client = await Elements('YOUR_API_KEY', {
-  env: 'production',
-  promoTicker: [
-    {
-      promoCode: 'SUMMER20',
-      text: ['20% Off Summer Sale!', 'Use code SUMMER20'],
-      separator: '•',
-      activeFrom: '2025-06-01T00:00:00Z',
-      activeUntil: '2025-08-31T23:59:59Z'
-    }
-  ]
-});
-```
-
-## Configuration Validation
-
-The SDK validates configuration on initialization:
-
-```javascript
-try {
-  const client = await Elements('YOUR_API_KEY', {
-    env: 'invalid'  // ❌ Will throw error
-  });
-} catch (error) {
-  console.error('Invalid configuration:', error);
-}
-```
-
-**Common validation errors:**
-- Invalid environment value
-- Missing API key
-- Invalid proxy baseUrl
-- Malformed promo ticker dates
-
-## Environment Variables
-
-For framework integrations, use environment variables:
-
-### React / Next.js
-
-```javascript
-const client = await Elements(process.env.REACT_APP_LCE_API_KEY, {
-  env: process.env.REACT_APP_LCE_ENV || 'production'
-});
-```
-
-### Vue
-
-```javascript
-const client = await Elements(process.env.VUE_APP_LCE_API_KEY, {
-  env: process.env.VUE_APP_LCE_ENV || 'production'
-});
-```
-
-### Node.js / Server-Side
-
-```javascript
-const client = await Elements(process.env.LCE_API_KEY, {
-  env: process.env.NODE_ENV === 'production' ? 'production' : 'development'
-});
-```
-
-## Configuration Best Practices
-
-1. **Use environment variables** for API keys (never hardcode)
-2. **Enable debug mode only in development** (security risk in production)
-3. **Pin to specific version** in production for stability
-4. **Configure proxy** if targeting ad blocker-heavy audiences
-5. **Use minimal theme overrides** for optimal performance
-6. **Set GTM container ID** for analytics tracking
-7. **Test configuration** in staging before production
-8. **Validate promo dates** to avoid expired promotions
-9. **Use builder mode** only in development (performance overhead)
-10. **Monitor proxy** health if using custom proxy
-
-## Related Documentation
-
-- [Theming Guide](./THEMING.md) - Complete theme configuration reference
-- [Proxy Setup](./PROXY.md) - Proxy implementation guide
-- [Actions Reference](./ACTIONS.md) - Programmatic control API
-- [Events Reference](./EVENTS.md) - Event system and tracking
-