@liquidcommerce/elements-sdk 2.3.0 → 2.4.0

package/docs/PROXY.md

@@ -0,0 +1,228 @@
+# 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'
+    }
+}
+```