@liquidcommerce/elements-sdk 2.6.0-beta.40 → 2.6.0-beta.42

package/docs/product.md

@@ -1,250 +0,0 @@
-# Product
-
-The product element is the heart of the SDK - it displays product information, handles size and variant selection, shows real-time pricing based on delivery location, and lets customers add items to their cart.
-
-## Overview
-
-The product element renders a complete product card with:
-- Product imagery and details
-- Size/variant selection
-- Real-time pricing based on delivery address
-- Fulfillment options (shipping vs on-demand delivery)
-- Quantity controls
-- Add to cart functionality
-- Personalization/engraving options (when available)
-
-The component automatically adapts to the customer's delivery address, showing only available fulfillment options and location-specific pricing.
-
----
-
-## Declarative Setup (HTML Attributes)
-
-Add products to your page without writing JavaScript. Choose the method that fits your use case.
-
-### Method 1: Direct Attributes
-
-Best for static pages with known products. Add products directly in the script tag:
-
-```html
-<div id="product-1"></div>
-<div id="product-2"></div>
-
-<script
-  defer
-  type="text/javascript"
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-env="production"
-  data-container-1="product-1"
-  data-product-1="00619947000020"
-  data-container-2="product-2"
-  data-product-2="00832889005513"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-The pattern is `data-container-N` paired with `data-product-N` where N is any number.
-
-### Method 2: JSON Configuration
-
-Best for CMS platforms and dynamic content. Configure products via a JSON script block:
-
-```html
-<div id="product-1"></div>
-<div id="product-2"></div>
-
-<script data-liquid-commerce-elements-products type="application/json">
-[
-  { "containerId": "product-1", "identifier": "00619947000020" },
-  { "containerId": "product-2", "identifier": "00832889005513" }
-]
-</script>
-
-<script
-  defer
-  type="text/javascript"
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-env="production"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-This approach works well with templating engines and server-side rendering.
-
-### Method 3: Annotated Elements
-
-Best for product grids and lists. Mark any div with a data attribute:
-
-```html
-<div class="product-grid">
-  <div data-lce-product="00619947000020"></div>
-  <div data-lce-product="00832889005513"></div>
-  <div data-lce-product="00851468007252"></div>
-</div>
-
-<script
-  defer
-  type="text/javascript"
-  data-liquid-commerce-elements
-  data-token="YOUR_API_KEY"
-  data-env="production"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
-></script>
-```
-
-The SDK automatically finds and initializes all elements with `data-lce-product`.
-
----
-
-## Programmatic Setup (JavaScript API)
-
-For full control, inject products using the client API.
-
-### Basic Injection
-
-```javascript
-const client = await Elements('YOUR_API_KEY', { env: 'production' });
-
-const components = await client.injectProductElement([
-  { containerId: 'pdp-1', identifier: '00619947000020' },
-  { containerId: 'pdp-2', identifier: '00832889005513' }
-]);
-```
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `containerId` | string | Yes | ID of the container element |
-| `identifier` | string | Yes | Product UPC, ID, or Salsify grouping ID |
-
-### Return Value
-
-Returns `IInjectedComponent[]` - an array of component wrappers with these methods:
-
-```javascript
-// Get the container element
-const element = components[0].getElement();
-
-// Get the component type
-const type = components[0].getType(); // 'product'
-
-// Force a re-render
-components[0].rerender();
-```
-
-### Dynamic Product Loading
-
-Load products dynamically based on user actions:
-
-```javascript
-// Load product when user clicks a button
-document.querySelector('#load-product').addEventListener('click', async () => {
-  await client.injectProductElement([
-    { containerId: 'dynamic-product', identifier: selectedProductId }
-  ]);
-});
-```
-
----
-
-## Actions
-
-Control and query product state programmatically.
-
-### Get Product Details
-
-Retrieve the current state of a displayed product:
-
-```javascript
-const details = window.elements.actions.product.getDetails('00619947000020');
-
-// Returns product data including:
-// - name, brand, category
-// - selectedSizeId, selectedFulfillmentType
-// - availability status
-// - pricing information
-```
-
----
-
-## Events
-
-Listen to product interactions and state changes.
-
-### Subscribing to Events
-
-```javascript
-window.addEventListener('lce:actions.product_loaded', (event) => {
-  const { data, metadata } = event.detail;
-  console.log('Product loaded:', data.name);
-});
-```
-
-### Available Events
-
-| Event | Description | Key Data |
-|-------|-------------|----------|
-| `product_loaded` | Product data fetched and displayed | Full product details |
-| `product_add_to_cart` | Customer added product to cart | identifier, fulfillmentId, quantity |
-| `product_quantity_increase` | Quantity increased | identifier, quantity, previousQuantity |
-| `product_quantity_decrease` | Quantity decreased | identifier, quantity, previousQuantity |
-| `product_size_changed` | Size selection changed | identifier, selectedSizeId, previousSizeId |
-| `product_fulfillment_type_changed` | Shipping/on-demand changed | identifier, selectedFulfillmentType |
-| `product_fulfillment_changed` | Retailer selection changed | identifier, selectedFulfillmentId |
-
-### Example: Track Add to Cart
-
-```javascript
-window.addEventListener('lce:actions.product_add_to_cart', (event) => {
-  const { identifier, quantity, fulfillmentId } = event.detail.data;
-
-  // Send to analytics
-  analytics.track('Product Added', {
-    productId: identifier,
-    quantity: quantity,
-    fulfillment: fulfillmentId
-  });
-});
-```
-
----
-
-## Customization
-
-Style product components through the theme configuration.
-
-### Basic Theming
-
-```javascript
-const client = await Elements('YOUR_API_KEY', {
-  customTheme: {
-    global: {
-      theme: {
-        primaryColor: '#007bff',
-        buttonCornerRadius: '8px'
-      }
-    },
-    product: {
-      // Product-specific theme options
-    }
-  }
-});
-```
-
-### Product Theme Options
-
-See [theming.md](./theming.md) for the complete list of product theme options including:
-- Layout configuration
-- Color overrides
-- Typography settings
-- Spacing and sizing
-
----
-
-## See Also
-
-- [Actions Reference](./actions.md) - All available actions
-- [Events Reference](./events.md) - All available events
-- [Theming Guide](./theming.md) - Customization options

package/docs/proxy.md

@@ -1,228 +0,0 @@
-# Proxy Configuration Guide
-
-Configure the LiquidCommerce Elements SDK to route API requests through your own server to avoid ad blockers.
-
-## Quick Setup
-
-### 1. Configure the SDK
-
-```typescript
-const elements = await Elements('your-api-key', {
-    env: 'production',
-    proxy: {
-        baseUrl: 'https://yourdomain.com/api/liquidcommerce'
-    }
-});
-```
-
-### 2. How It Works
-
-```
-Without Proxy:  Your App → LiquidCommerce API
-With Proxy:     Your App → Your Server → LiquidCommerce API
-```
-
-The SDK automatically:
-- Changes API calls from `https://elements.liquidcommerce.us/api/*` to `https://yourdomain.com/api/liquidcommerce/api/*`
-- Adds `X-Liquid-Proxy-Target` header with the original LiquidCommerce URL
-- Sends all required LiquidCommerce headers that your proxy must forward
-
-## Required Headers
-
-The SDK sends these headers that **must be forwarded** to LiquidCommerce:
-
-### Authentication Headers
-- `X-Liquid-Api-Key` - Your LiquidCommerce API key
-- `X-Liquid-Api-Env` - Environment (staging, production, development)
-- `Authorization` - Bearer token (added automatically after authentication)
-
-### Tracking Headers
-- `X-Liquid-Api-Sdk` - Source URL (usually `window.location.href`)
-- `X-Liquid-Sdk-Version` - SDK version for debugging
-- `X-Liquid-Proxy` - Always `true` when using a proxy
-
-### Proxy Headers
-- `X-Liquid-Proxy-Target` - Original LiquidCommerce API URL to forward to
-- `Content-Type` - Always `application/json`
-
-### Your Custom Headers (optional)
-- Any headers you add in `proxy.headers` config
-
-## Next.js Implementation
-
-### API Route: `pages/api/liquidcommerce/[...path].js`
-
-```javascript
-export default async function handler(req, res) {
-    // Get the API path from the dynamic route
-    const { path } = req.query;
-    const apiPath = Array.isArray(path) ? path.join('/') : path;
-    
-    // Get target URL from SDK header
-    const targetUrl = req.headers['x-liquid-proxy-target'];
-    
-    if (!targetUrl) {
-        return res.status(400).json({ error: 'Missing target URL' });
-    }
-    
-    // Security: Validate target URL
-    const allowedTargets = [
-        'https://elements.liquidcommerce.us',
-        'https://staging-elements.liquidcommerce.us'
-    ];
-    
-    if (!allowedTargets.includes(targetUrl)) {
-        return res.status(400).json({ error: 'Invalid target URL' });
-    }
-    
-    try {
-        // Forward the request to LiquidCommerce with ALL required headers
-        const response = await fetch(`${targetUrl}/api/${apiPath}`, {
-            method: req.method,
-            headers: {
-                // Required LiquidCommerce headers
-                'Content-Type': 'application/json',
-                'X-Liquid-Api-Key': req.headers['x-liquid-api-key'],
-                'X-Liquid-Api-Env': req.headers['x-liquid-api-env'],
-                'X-Liquid-Api-Sdk': req.headers['x-liquid-api-sdk'],
-                'X-Liquid-Sdk-Version': req.headers['x-liquid-sdk-version'],
-                'X-Liquid-Proxy': req.headers['x-liquid-proxy'],
-                'Authorization': req.headers['authorization'],
-                // Don't forward the proxy target header to LiquidCommerce
-                // 'X-Liquid-Proxy-Target': NOT forwarded
-            },
-            body: req.method !== 'GET' ? JSON.stringify(req.body) : undefined,
-        });
-        
-        const data = await response.json();
-        res.status(response.status).json(data);
-        
-    } catch (error) {
-        console.error('Proxy error:', error);
-        res.status(500).json({ error: 'Proxy error' });
-    }
-}
-```
-
-### App Router: `app/api/liquidcommerce/[...path]/route.js`
-
-```javascript
-export async function GET(request, { params }) {
-    return handleRequest(request, params, 'GET');
-}
-
-export async function POST(request, { params }) {
-    return handleRequest(request, params, 'POST');
-}
-
-export async function PUT(request, { params }) {
-    return handleRequest(request, params, 'PUT');
-}
-
-async function handleRequest(request, params, method) {
-    const apiPath = params.path.join('/');
-    const targetUrl = request.headers.get('x-liquid-proxy-target');
-    
-    if (!targetUrl) {
-        return Response.json({ error: 'Missing target URL' }, { status: 400 });
-    }
-    
-    // Security check
-    const allowedTargets = [
-        'https://elements.liquidcommerce.us',
-        'https://staging-elements.liquidcommerce.us'
-    ];
-    
-    if (!allowedTargets.includes(targetUrl)) {
-        return Response.json({ error: 'Invalid target URL' }, { status: 400 });
-    }
-    
-    try {
-        const body = method !== 'GET' ? await request.json() : undefined;
-        
-        const response = await fetch(`${targetUrl}/api/${apiPath}`, {
-            method,
-            headers: {
-                // Required LiquidCommerce headers
-                'Content-Type': 'application/json',
-                'X-Liquid-Api-Key': request.headers.get('x-liquid-api-key'),
-                'X-Liquid-Api-Env': request.headers.get('x-liquid-api-env'),
-                'X-Liquid-Api-Sdk': request.headers.get('x-liquid-api-sdk'),
-                'X-Liquid-Sdk-Version': request.headers.get('x-liquid-sdk-version'),
-                'Authorization': request.headers.get('authorization'),
-                // Don't forward the proxy target header to LiquidCommerce
-                // 'X-Liquid-Proxy-Target': NOT forwarded
-            },
-            body: body ? JSON.stringify(body) : undefined,
-        });
-        
-        const data = await response.json();
-        return Response.json(data, { status: response.status });
-        
-    } catch (error) {
-        console.error('Proxy error:', error);
-        return Response.json({ error: 'Proxy error' }, { status: 500 });
-    }
-}
-```
-
-## Testing
-
-### 1. Test the proxy endpoint directly:
-
-```bash
-curl -X GET "https://yourdomain.com/api/liquidcommerce/configs" \
-  -H "Content-Type: application/json" \
-  -H "X-Liquid-Proxy-Target: https://staging-elements.liquidcommerce.us" \
-  -H "X-Liquid-Api-Key: your-api-key" \
-  -H "X-Liquid-Api-Env: staging" \
-  -H "X-Liquid-Api-Sdk: https://yoursite.com" \
-  -H "X-Liquid-Sdk-Version: 1.0.0"
-```
-
-### 2. Use the SDK with proxy:
-
-```javascript
-// This will automatically use your proxy
-const elements = await Elements('your-api-key', {
-    env: 'staging',
-    proxy: {
-        baseUrl: 'https://yourdomain.com/api/liquidcommerce'
-    }
-});
-
-await elements.prepare(); // Uses proxy for all API calls
-```
-
-## Security
-
-1. **Validate target URLs** - Only allow known LiquidCommerce domains
-2. **Forward required headers only** - Forward the headers listed above, exclude internal ones
-3. **Don't forward `X-Liquid-Proxy-Target`** - This is for your proxy only, not LiquidCommerce
-4. **Add rate limiting** if needed
-5. **Log requests** for monitoring
-
-## Important Notes
-
-- **All SDK headers must be forwarded** - Missing headers will cause authentication failures
-- **`Authorization` header is added automatically** - After the SDK authenticates with your API key
-- **`X-Liquid-Proxy-Target` stays with your proxy** - Don't send this to LiquidCommerce
-- **Content-Type must be `application/json`** - Required for all API requests
-
-## Benefits
-
-- ✅ **Bypass ad blockers** - Requests come from your domain
-- ✅ **Control requests** - Monitor and modify API calls
-- ✅ **Add authentication** - Include your own auth headers
-- ✅ **Zero client changes** - Transparent to the SDK
-
-## Configuration Options
-
-```typescript
-proxy: {
-    baseUrl: 'https://yourdomain.com/api/liquidcommerce',  // Required: Full proxy endpoint URL
-    headers: {                                             // Optional: Custom headers
-        'X-Custom-Header': 'value'
-    }
-}
-```