@liquidcommerce/elements-sdk 2.6.0-beta.13 → 2.6.0-beta.131

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'
-    }
-}
-```