@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/skills/zoho-patterns/integration/cors-proxy-architecture.md

@@ -0,0 +1,426 @@
+# CORS Proxy Architecture
+
+## Why Widgets Can't Call External APIs Directly
+
+> **PROBLEM:** Creator widgets run inside an iframe on `*.zoho.com`. Browser CORS policy blocks cross-origin requests to external APIs. Even if the external API has CORS headers, they won't include Zoho's origin.
+
+```
+Widget (iframe on zoho.com)
+    ↓ fetch("https://api.stripe.com/...")
+    ✗ BLOCKED by browser CORS policy
+```
+
+## The Solution: Catalyst Proxy
+
+```
+Widget (iframe)
+    ↓ ZOHO.CREATOR.DATA.invokeFunction() [Same origin - no CORS]
+    ↓
+Catalyst Function (server-side)
+    ↓ axios/fetch to external API [Server-side - no CORS]
+    ↓
+External API
+    ↓ Response
+    ↓
+Catalyst Function
+    ↓ Transform + return
+    ↓
+Widget (receives data)
+```
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Creator Widget (Browser)                                 │
+│                                                          │
+│  ┌─────────────────────────────────────────────────┐    │
+│  │  ZOHO.CREATOR.DATA.invokeFunction({             │    │
+│  │    functionName: "proxy_api",                    │    │
+│  │    data: { endpoint, method, body, headers }     │    │
+│  │  })                                              │    │
+│  └─────────────────┬───────────────────────────────┘    │
+│                     │ (Same Zoho domain = OK)            │
+└─────────────────────┼───────────────────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────────────────┐
+│ Catalyst I/O Function (Server)                           │
+│                                                          │
+│  - Validates request                                     │
+│  - Adds auth credentials (from env vars)                │
+│  - Calls external API                                    │
+│  - Transforms response                                   │
+│  - Returns to widget                                     │
+│                                                          │
+│  ⚠️ 30-second timeout for I/O functions                  │
+│  ⚠️ context.close() MANDATORY                            │
+└─────────────────────┬───────────────────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────────────────┐
+│ External API (Stripe, Twilio, Google, etc.)              │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Catalyst Proxy Function Implementation
+
+### Basic Proxy (Node.js)
+
+```javascript
+const catalyst = require("zcatalyst-sdk-node");
+const axios = require("axios");
+
+module.exports = async (req, res, context) => {
+    const app = catalyst.initialize(context);
+
+    try {
+        // Validate request
+        const { endpoint, method, body, headers: customHeaders } = req.body;
+
+        if (!endpoint) {
+            res.status(400).json({ error: "endpoint is required" });
+            return;
+        }
+
+        // Whitelist allowed endpoints (SECURITY: prevent SSRF)
+        const allowedDomains = [
+            "api.stripe.com",
+            "api.twilio.com",
+            "maps.googleapis.com"
+        ];
+
+        const url = new URL(endpoint);
+        if (!allowedDomains.includes(url.hostname)) {
+            res.status(403).json({ error: "Domain not allowed: " + url.hostname });
+            return;
+        }
+
+        // Build request
+        const axiosConfig = {
+            method: method || "GET",
+            url: endpoint,
+            headers: {
+                "Content-Type": "application/json",
+                ...customHeaders
+            },
+            timeout: 25000 // 25s (buffer for 30s Catalyst timeout)
+        };
+
+        if (body && (method === "POST" || method === "PUT" || method === "PATCH")) {
+            axiosConfig.data = typeof body === "string" ? JSON.parse(body) : body;
+        }
+
+        // Add server-side credentials
+        axiosConfig.headers["Authorization"] = getAuthForDomain(url.hostname);
+
+        // Execute request
+        const response = await axios(axiosConfig);
+
+        res.status(200).json({
+            status: response.status,
+            data: response.data
+        });
+
+    } catch (error) {
+        if (error.response) {
+            // External API returned an error
+            res.status(200).json({
+                status: error.response.status,
+                error: error.response.data
+            });
+        } else if (error.code === "ECONNABORTED") {
+            res.status(504).json({ error: "External API timeout" });
+        } else {
+            res.status(500).json({ error: error.message });
+        }
+    } finally {
+        context.close();
+    }
+};
+
+function getAuthForDomain(domain) {
+    const authMap = {
+        "api.stripe.com": `Bearer ${process.env.STRIPE_SECRET_KEY}`,
+        "api.twilio.com": `Basic ${Buffer.from(process.env.TWILIO_SID + ":" + process.env.TWILIO_TOKEN).toString("base64")}`,
+        "maps.googleapis.com": "" // Uses query param key instead
+    };
+    return authMap[domain] || "";
+}
+```
+
+### Widget-Side Code
+
+```javascript
+// Generic proxy caller for widgets
+async function proxyApiCall(endpoint, method = "GET", body = null) {
+    try {
+        const response = await ZOHO.CREATOR.DATA.invokeFunction({
+            appName: "my-app",
+            functionName: "proxy_api",
+            data: {
+                endpoint: endpoint,
+                method: method,
+                body: body ? JSON.stringify(body) : null
+            }
+        });
+
+        const result = JSON.parse(response.data);
+
+        if (result.status >= 200 && result.status < 300) {
+            return { success: true, data: result.data };
+        } else {
+            return { success: false, error: result.error || result.data };
+        }
+    } catch (error) {
+        console.error("Proxy call failed:", error);
+        return { success: false, error: error.message };
+    }
+}
+
+// Usage examples
+async function getStripeCustomer(customerId) {
+    return await proxyApiCall(
+        `https://api.stripe.com/v1/customers/${customerId}`,
+        "GET"
+    );
+}
+
+async function sendTwilioSMS(to, message) {
+    return await proxyApiCall(
+        `https://api.twilio.com/2010-04-01/Accounts/${ACCOUNT_SID}/Messages.json`,
+        "POST",
+        { To: to, From: TWILIO_NUMBER, Body: message }
+    );
+}
+```
+
+## Authentication Passthrough
+
+### Pattern 1: Server-Side Credentials (Recommended)
+
+```javascript
+// Credentials stored in Catalyst environment variables
+// Widget NEVER sees API keys
+function getAuthForDomain(domain) {
+    switch (domain) {
+        case "api.stripe.com":
+            return `Bearer ${process.env.STRIPE_SECRET_KEY}`;
+        case "api.openai.com":
+            return `Bearer ${process.env.OPENAI_API_KEY}`;
+        default:
+            return "";
+    }
+}
+```
+
+### Pattern 2: User-Specific Tokens (OAuth)
+
+```javascript
+// For APIs where each user has their own token
+// Store user tokens in Catalyst Data Store
+async function getUserToken(app, userId, service) {
+    const result = await app.zcql().executeZCQLQuery(
+        `SELECT access_token, refresh_token, expires_at FROM UserTokens WHERE user_id = '${userId}' AND service = '${service}'`
+    );
+
+    if (result.length === 0) {
+        throw new Error("No token found. User must authenticate first.");
+    }
+
+    const tokenData = result[0].UserTokens;
+
+    // Check if token expired
+    if (new Date(tokenData.expires_at) < new Date()) {
+        // Refresh token
+        return await refreshUserToken(app, userId, service, tokenData.refresh_token);
+    }
+
+    return tokenData.access_token;
+}
+```
+
+## Response Transformation
+
+Transform external API responses to match widget expectations:
+
+```javascript
+// Transform Stripe response to simplified format for widget
+function transformStripeCustomer(stripeData) {
+    return {
+        id: stripeData.id,
+        name: stripeData.name,
+        email: stripeData.email,
+        balance: stripeData.balance / 100, // Cents to dollars
+        subscriptions: (stripeData.subscriptions?.data || []).map(sub => ({
+            id: sub.id,
+            plan: sub.plan.nickname,
+            status: sub.status,
+            amount: sub.plan.amount / 100,
+            interval: sub.plan.interval
+        })),
+        created: new Date(stripeData.created * 1000).toISOString()
+    };
+}
+```
+
+## Caching Layer
+
+Reduce external API calls with caching:
+
+```javascript
+const NodeCache = require("node-cache");
+const cache = new NodeCache({ stdTTL: 300 }); // 5-minute default TTL
+
+async function cachedProxyCall(endpoint, method, body, cacheTTL = 300) {
+    // Only cache GET requests
+    if (method === "GET") {
+        const cacheKey = `proxy:${endpoint}`;
+        const cached = cache.get(cacheKey);
+
+        if (cached) {
+            console.log("Cache hit:", endpoint);
+            return cached;
+        }
+    }
+
+    // Make actual API call
+    const response = await axios({ method, url: endpoint, data: body });
+
+    // Cache successful GET responses
+    if (method === "GET" && response.status === 200) {
+        cache.set(`proxy:${endpoint}`, response.data, cacheTTL);
+    }
+
+    return response.data;
+}
+```
+
+> **NOTE:** In-memory cache resets on function cold starts. For persistent caching, use Catalyst Data Store or Cache service.
+
+## Rate Limiting at Proxy Level
+
+```javascript
+// Simple rate limiter per client/endpoint
+const rateLimits = {};
+const WINDOW_MS = 60000; // 1 minute window
+const MAX_REQUESTS = 30; // 30 requests per minute per endpoint
+
+function checkRateLimit(endpoint, userId) {
+    const key = `${userId}:${endpoint}`;
+    const now = Date.now();
+
+    if (!rateLimits[key]) {
+        rateLimits[key] = { count: 0, windowStart: now };
+    }
+
+    const limit = rateLimits[key];
+
+    // Reset window if expired
+    if (now - limit.windowStart > WINDOW_MS) {
+        limit.count = 0;
+        limit.windowStart = now;
+    }
+
+    limit.count++;
+
+    if (limit.count > MAX_REQUESTS) {
+        return { allowed: false, retryAfter: Math.ceil((WINDOW_MS - (now - limit.windowStart)) / 1000) };
+    }
+
+    return { allowed: true, remaining: MAX_REQUESTS - limit.count };
+}
+
+// Usage in handler
+const rateCheck = checkRateLimit(endpoint, req.headers["x-user-id"] || "anonymous");
+if (!rateCheck.allowed) {
+    res.status(429).json({
+        error: "Rate limit exceeded",
+        retry_after: rateCheck.retryAfter
+    });
+    context.close();
+    return;
+}
+```
+
+## Security Considerations
+
+> **WARNING:** A proxy that forwards arbitrary URLs is an SSRF vulnerability. Always implement:
+
+1. **Domain whitelist** - Only allow known, approved external domains
+2. **Method restrictions** - Only allow needed HTTP methods
+3. **Request size limits** - Prevent large payload attacks
+4. **Authentication** - Verify the widget caller is a legitimate Zoho user
+5. **Logging** - Log all proxy requests for audit trail
+6. **No credential exposure** - Never return API keys to the client
+
+### SSRF Prevention
+
+```javascript
+// NEVER do this:
+const response = await axios.get(req.body.url); // Attacker can access internal network!
+
+// ALWAYS do this:
+const allowedDomains = ["api.stripe.com", "api.twilio.com"];
+const url = new URL(req.body.endpoint);
+
+if (!allowedDomains.includes(url.hostname)) {
+    res.status(403).json({ error: "Forbidden domain" });
+    context.close();
+    return;
+}
+
+// Also block internal IPs
+const blockedPatterns = ["127.0.0.1", "localhost", "10.", "172.16.", "192.168.", "169.254."];
+if (blockedPatterns.some(p => url.hostname.startsWith(p))) {
+    res.status(403).json({ error: "Internal addresses not allowed" });
+    context.close();
+    return;
+}
+```
+
+## Alternative: Deluge Custom Function as Proxy
+
+For simpler cases where Catalyst is not needed:
+
+```deluge
+// Creator custom function: proxy_api_call
+// Arguments: endpoint (TEXT), method (TEXT), payload (TEXT)
+
+// Whitelist check
+allowedDomains = {"api.stripe.com", "api.example.com"};
+urlDomain = endpoint.getPrefix("//").getSuffix("//").getPrefix("/");
+
+if (!allowedDomains.contains(urlDomain))
+{
+    return {"status": "error", "message": "Domain not allowed"};
+}
+
+try
+{
+    if (method == "GET")
+    {
+        response = invokeUrl [
+            url: endpoint
+            type: GET
+            connection: "external-api-connection"
+        ];
+    }
+    else
+    {
+        response = invokeUrl [
+            url: endpoint
+            type: POST
+            headers: {"Content-Type": "application/json"}
+            body: payload
+            connection: "external-api-connection"
+        ];
+    }
+
+    return {"status": "success", "data": response.toString()};
+}
+catch (e)
+{
+    return {"status": "error", "message": e.toString()};
+}
+```
+
+> **TRADE-OFF:** Deluge proxy is simpler but limited to 40-second timeout and uses the 5000-statement budget. Catalyst proxy has 30-second timeout but is more flexible for complex transformations.

package/skills/zoho-patterns/integration/crm-books-native-sync.md

@@ -0,0 +1,277 @@
+# CRM-Books Native Sync
+
+> Last verified: 2026-01 (Zoho CRM v5 API, Books API v3)
+
+## Overview
+
+> **CRITICAL:** Zoho CRM and Zoho Books have a built-in native sync that runs on a 2-hour cycle. Before building custom sync logic, verify the native sync doesn't already cover your use case. Rebuilding what already exists creates data conflicts, maintenance burden, and billing waste.
+
+## What Syncs Automatically
+
+### CRM → Books (Entities)
+
+| CRM Entity | Books Entity | Sync Direction | Notes |
+|-----------|-------------|----------------|-------|
+| Accounts | Customers | CRM → Books | Company records |
+| Contacts | Contact Persons | CRM → Books | Individual contacts |
+| Products | Items | Bidirectional | Shared catalog |
+| Quotes | Estimates | CRM → Books | When accepted |
+| Sales Orders | Sales Orders | CRM → Books | When confirmed |
+| Invoices | Invoices | CRM → Books | When created |
+| Purchase Orders | Purchase Orders | CRM → Books | When issued |
+
+### Fields That Sync
+
+| Category | Fields | Notes |
+|----------|--------|-------|
+| Contact Info | Name, Email, Phone, Address | All standard fields |
+| Financial | Amount, Tax, Discount | Line item details |
+| Products | Name, SKU, Price, Description | Full catalog sync |
+| Status | Invoice status, Payment status | Read from Books |
+| Custom Fields | Only if mapped in sync settings | Manual configuration required |
+
+### What Does NOT Sync Automatically
+
+- **Custom modules** in CRM
+- **Activities** (Tasks, Events, Calls)
+- **Notes** and attachments
+- **Custom fields** unless explicitly mapped
+- **Deals/Opportunities** (only Quotes/Orders/Invoices)
+- **Vendors** (must configure separately)
+- **Payment receipts** and credit notes (Books → CRM)
+- **Expense records**
+- **Timesheet data**
+
+## Sync Cycle Details
+
+```
+Every 2 Hours:
+┌─────────────────────────────────────────┐
+│ 1. CRM checks for modified records      │
+│ 2. Compares with last sync timestamp    │
+│ 3. Pushes changed records to Books      │
+│ 4. Books processes and confirms         │
+│ 5. Updates sync status in CRM           │
+│ 6. Next cycle scheduled                 │
+└─────────────────────────────────────────┘
+```
+
+### Sync Timing
+
+- Default interval: Every 2 hours
+- Manual sync: Available in CRM Settings > Zoho Finance > Sync Now
+- First sync: Can take longer for large datasets
+- Conflict resolution: Last-modified-wins (CRM takes priority on shared fields)
+
+## When to NOT Rebuild This
+
+> **RULE:** If the native sync handles your data flow, do NOT create custom Deluge scripts that duplicate it. Custom sync will conflict with native sync and cause data inconsistencies.
+
+### Scenarios Where Native Sync is Sufficient
+
+1. Standard contact/customer sync between CRM and Books
+2. Product catalog shared between both apps
+3. Quote-to-Invoice conversion flow
+4. Basic sales order processing
+5. Standard invoice creation from CRM deals
+
+### Decision Framework
+
+| Need | Native Sync | Extend Native | Build Custom |
+|------|-------------|---------------|-------------|
+| Contacts CRM→Books | Use native | - | - |
+| Real-time sync (< 5 min) | No | No | Yes (webhook) |
+| Custom field mapping | - | Yes (configure) | - |
+| Conditional sync (filter) | No | No | Yes |
+| Transform data during sync | No | No | Yes |
+| Multi-org sync | No | No | Yes |
+| Custom module sync | No | No | Yes |
+| Sync with non-Zoho app | No | No | Yes |
+| Payment status → CRM | Partial | Yes | Maybe |
+
+## How to Extend (Not Replace) Native Sync
+
+### Adding Custom Field Mapping
+
+1. Go to CRM > Settings > Zoho Finance Suite
+2. Click "Sync Preferences"
+3. Map additional fields under "Field Mapping"
+4. Custom fields must exist in BOTH apps first
+
+### Supplementing with Workflow Triggers
+
+```deluge
+// In CRM: On Edit of Contact, push extra fields to Books
+// This SUPPLEMENTS native sync (doesn't replace it)
+// Only sync fields that native sync DOESN'T handle
+
+if (input.Custom_Field_1 != input.Custom_Field_1_previous)
+{
+    // Find corresponding Books contact
+    try
+    {
+        booksContacts = zoho.books.getRecords("contacts", orgId, {
+            "email": input.Email
+        }, "books-connection");
+
+        if (booksContacts.get("contacts").size() > 0)
+        {
+            booksContactId = booksContacts.get("contacts").get(0).get("contact_id");
+
+            // Update ONLY custom fields (let native sync handle standard fields)
+            updateData = Map();
+            updateData.put("cf_custom_field_1", input.Custom_Field_1);
+            updateData.put("cf_custom_field_2", input.Custom_Field_2);
+
+            zoho.books.updateRecord("contacts", orgId, booksContactId, updateData, "books-connection");
+        }
+    }
+    catch (e)
+    {
+        info "Custom field sync failed: " + e.toString();
+    }
+}
+```
+
+### Triggering Actions After Sync
+
+```deluge
+// Scheduled function: Check for recently synced records and post-process
+// Runs every 30 minutes to catch records synced by native 2-hour cycle
+
+lastCheck = zoho.creator.getRecords("admin-app", "Sync_State", "Key == \"last_books_check\"", 1, 1);
+lastCheckTime = lastCheck.get(0).get("Value");
+
+// Get recently created invoices in Books (created by native sync)
+try
+{
+    newInvoices = zoho.books.getRecords("invoices", orgId, {
+        "date_start": lastCheckTime,
+        "date_end": zoho.currentdate.toString("yyyy-MM-dd"),
+        "status": "draft"
+    }, "books-connection");
+
+    for each invoice in newInvoices.get("invoices")
+    {
+        // Post-processing: auto-send draft invoices over $100
+        if (invoice.get("total").toDecimal() > 100)
+        {
+            zoho.books.updateRecord("invoices", orgId, invoice.get("invoice_id"),
+                {"status": "sent"}, "books-connection");
+        }
+    }
+}
+catch (e)
+{
+    info "Post-sync processing failed: " + e.toString();
+}
+
+// Update last check timestamp
+zoho.creator.updateRecord("admin-app", "Sync_State",
+    lastCheck.get(0).get("ID").toLong(), {"Value": zoho.currenttime.toString()});
+```
+
+## Sync Status Checking
+
+### Check Sync Status in CRM
+
+```deluge
+// Get sync status for a specific record
+function checkSyncStatus(module, recordId)
+{
+    try
+    {
+        record = zoho.crm.getRecordById(module, recordId);
+
+        // Check Books-related fields
+        booksId = record.get("Books_Contact_ID"); // Populated after sync
+        lastSync = record.get("Last_Synced_Time"); // If available
+
+        if (booksId != null && booksId != "")
+        {
+            return {"synced": true, "books_id": booksId, "last_sync": lastSync};
+        }
+        else
+        {
+            return {"synced": false, "reason": "Not yet synced or sync failed"};
+        }
+    }
+    catch (e)
+    {
+        return {"synced": false, "reason": e.toString()};
+    }
+}
+```
+
+### Monitor Sync Health
+
+```deluge
+// Scheduled: Daily check for sync issues
+// Find CRM records that should have synced but haven't
+
+criteria = "Created_Time < \"" + zoho.currentdate.subDay(1).toString("yyyy-MM-dd") + "\" && Books_Contact_ID is null";
+unsyncedContacts = zoho.crm.getRecords("Contacts", criteria, 1, 200);
+
+if (unsyncedContacts.size() > 10)
+{
+    sendmail [
+        from: zoho.adminuserid
+        to: "admin@company.com"
+        subject: "[WARNING] " + unsyncedContacts.size() + " contacts not synced to Books"
+        message: "Found " + unsyncedContacts.size() + " contacts created over 24 hours ago that have not synced to Books. Check sync configuration."
+    ];
+}
+```
+
+## Troubleshooting Sync Failures
+
+| Symptom | Likely Cause | Fix |
+|---------|-------------|-----|
+| Records not syncing | Sync disabled in settings | CRM Settings > Zoho Finance > Enable |
+| Only some records sync | Filter criteria in sync settings | Review sync filters |
+| Custom fields missing | Fields not mapped | Add mapping in sync preferences |
+| Duplicate records in Books | Multiple sync sources configured | Disable duplicate sources |
+| Sync errors in log | Field validation failure in Books | Check Books mandatory fields |
+| Payment status not updating | Books→CRM sync disabled | Enable bidirectional sync |
+| Products not syncing | Product sync not enabled | Enable in sync preferences |
+
+### Sync Error Log Location
+
+1. CRM: Settings > Zoho Finance > Sync History
+2. Books: Settings > Integrations > Zoho CRM > Sync History
+3. Logs retained for 90 days
+
+### Common Sync Errors
+
+```
+Error: "Contact already exists in Books"
+→ Duplicate email address. Merge contacts in Books first.
+
+Error: "Mandatory field missing"
+→ Books requires fields that CRM doesn't. Set defaults in Books.
+
+Error: "Currency mismatch"
+→ Multi-currency not enabled in Books. Enable or map currencies.
+
+Error: "Tax rate not found"
+→ Tax configuration differs between apps. Create matching tax rates.
+```
+
+## Integration Architecture Recommendation
+
+```
+For Standard Flows:
+  CRM ──[Native 2h Sync]──→ Books
+        └──[Supplement: Custom fields via workflow]──→ Books
+
+For Real-Time Needs:
+  CRM ──[On-Edit Workflow]──→ Catalyst Function ──→ Books API
+  (Only for fields/entities NOT covered by native sync)
+
+For Reporting:
+  CRM ──[Native Sync]──→ Books
+  Books ──[Analytics Sync]──→ Zoho Analytics
+  (Do NOT pull directly from CRM if Books has the data)
+```
+
+> **FINAL WARNING:** If you find yourself writing Deluge code that syncs Contacts, Accounts, Products, or Invoices between CRM and Books - STOP. The native sync handles this. You are likely duplicating built-in functionality and creating future conflicts.