@liquidcommerce/elements-sdk 2.2.0-beta.4 → 2.2.0-beta.40

package/docs/CONFIGURATION.md

@@ -0,0 +1,740 @@
+# 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) -->
+```
+
+#### `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) -->
+```
+
+**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.
+
+```html
+data-cart-button-hidden
+```
+
+### 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>
+```
+
+### 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
+