@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/skills/zoho-patterns/deluge/api-patterns.md

@@ -0,0 +1,468 @@
+# Deluge API Patterns
+
+## invokeUrl Fundamentals
+
+> **CRITICAL:** invokeUrl has a hard 40-second timeout. If the external API doesn't respond within 40 seconds, the call FAILS with no retry. ALWAYS wrap in try-catch.
+
+> **NEVER** hardcode OAuth tokens in Deluge scripts. Always use Connections.
+
+## Basic invokeUrl with Try-Catch
+
+```deluge
+// ALWAYS use this pattern for API calls
+try
+{
+    response = invokeUrl [
+        url: "https://api.example.com/v1/data"
+        type: GET
+        headers: {"Content-Type": "application/json", "Accept": "application/json"}
+        connection: "my-api-connection"
+    ];
+
+    // Check response status
+    responseCode = response.getStatusCode();
+    if (responseCode == 200)
+    {
+        data = response.toJSON();
+        info "API call successful: " + data.size() + " records";
+    }
+    else
+    {
+        info "API returned error: " + responseCode + " - " + response.toString();
+    }
+}
+catch (e)
+{
+    info "API call failed: " + e.toString();
+    // Log error for debugging
+    errorLog = Map();
+    errorLog.put("Endpoint", "https://api.example.com/v1/data");
+    errorLog.put("Error", e.toString());
+    errorLog.put("Timestamp", zoho.currenttime);
+    zoho.creator.createRecord("admin-app", "API_Error_Log", errorLog);
+}
+```
+
+## Connection Usage
+
+Connections manage OAuth token refresh automatically:
+
+```deluge
+// Using a Zoho CRM connection
+response = invokeUrl [
+    url: "https://www.zohoapis.com/crm/v5/Deals"
+    type: GET
+    connection: "zoho-crm-connection"
+];
+
+// Using an external API connection (e.g., Stripe)
+response = invokeUrl [
+    url: "https://api.stripe.com/v1/customers"
+    type: GET
+    connection: "stripe-connection"
+];
+
+// Connection handles token refresh, you just use it
+```
+
+### Creating Connections
+
+1. Go to Setup > Developer > Connections
+2. Pick service (Zoho, custom OAuth, or API key)
+3. Define scopes (minimum necessary)
+4. Authorize and test
+5. Use connection name in `invokeUrl`
+
+> **WARNING:** If a Connection's OAuth grant expires (user revokes, org changes), all scripts using it will fail silently. Monitor for auth errors.
+
+## Response Handling
+
+### JSON Response Parsing
+
+```deluge
+try
+{
+    response = invokeUrl [
+        url: "https://api.example.com/users"
+        type: GET
+        connection: "example-connection"
+    ];
+
+    // Parse JSON response
+    jsonData = response.toJSON();
+
+    // Handle different response structures
+    if (jsonData.containsKey("data"))
+    {
+        records = jsonData.get("data");
+        for each record in records
+        {
+            name = record.get("name");
+            email = record.get("email");
+            info name + ": " + email;
+        }
+    }
+    else if (jsonData.containsKey("error"))
+    {
+        info "API Error: " + jsonData.get("error").get("message");
+    }
+}
+catch (e)
+{
+    info "Parse or network error: " + e.toString();
+}
+```
+
+### Status Code Checking
+
+```deluge
+try
+{
+    response = invokeUrl [
+        url: "https://api.example.com/resource"
+        type: GET
+        connection: "example-connection"
+    ];
+
+    statusCode = response.getStatusCode();
+
+    if (statusCode == 200)
+    {
+        // Success
+        return response.toJSON();
+    }
+    else if (statusCode == 401)
+    {
+        // Auth failed - connection may need reauthorization
+        info "AUTH FAILED - Reauthorize connection";
+        sendmail [
+            from: zoho.adminuserid
+            to: "admin@company.com"
+            subject: "[URGENT] API Connection Auth Failed"
+            message: "Connection needs reauthorization. Endpoint: /resource"
+        ];
+    }
+    else if (statusCode == 429)
+    {
+        // Rate limited
+        info "Rate limited - schedule retry";
+    }
+    else if (statusCode >= 500)
+    {
+        // Server error - transient, may retry
+        info "Server error: " + statusCode;
+    }
+}
+catch (e)
+{
+    // Network timeout or connection refused
+    info "Network error: " + e.toString();
+}
+```
+
+## Retry Pattern
+
+```deluge
+// Retry wrapper function
+// Arguments: url (TEXT), method (TEXT), body (TEXT), connectionName (TEXT)
+maxRetries = 3;
+lastError = "";
+result = null;
+
+for each attempt in {1, 2, 3}
+{
+    try
+    {
+        if (method == "GET")
+        {
+            response = invokeUrl [
+                url: url
+                type: GET
+                connection: connectionName
+            ];
+        }
+        else if (method == "POST")
+        {
+            response = invokeUrl [
+                url: url
+                type: POST
+                headers: {"Content-Type": "application/json"}
+                body: body
+                connection: connectionName
+            ];
+        }
+
+        statusCode = response.getStatusCode();
+
+        if (statusCode >= 200 && statusCode < 300)
+        {
+            result = response.toJSON();
+            break; // Success, exit retry loop
+        }
+        else if (statusCode == 429 || statusCode >= 500)
+        {
+            // Retryable error - will retry on next loop iteration
+            lastError = "HTTP " + statusCode;
+            // NOTE: Deluge has no sleep/delay mechanism.
+            // Retries happen immediately. For true backoff,
+            // use a Scheduled Function with retry state in a form record.
+        }
+        else
+        {
+            // Non-retryable error (4xx except 429)
+            lastError = "HTTP " + statusCode + ": " + response.toString();
+            break;
+        }
+    }
+    catch (e)
+    {
+        lastError = e.toString();
+        // Network error - worth retrying
+    }
+}
+
+if (result == null)
+{
+    info "All retries failed. Last error: " + lastError;
+}
+return result;
+```
+
+## Pagination of API Responses
+
+### Offset-Based Pagination
+
+```deluge
+// Fetch all pages from a paginated API
+allRecords = List();
+page = 1;
+pageSize = 200; // Max per request
+hasMore = true;
+
+while (hasMore)
+{
+    try
+    {
+        url = "https://api.example.com/records?page=" + page + "&limit=" + pageSize;
+        response = invokeUrl [
+            url: url
+            type: GET
+            connection: "example-connection"
+        ];
+
+        data = response.toJSON();
+        records = data.get("records");
+
+        if (records.size() > 0)
+        {
+            for each record in records
+            {
+                allRecords.add(record);
+            }
+            page = page + 1;
+        }
+
+        if (records.size() < pageSize)
+        {
+            hasMore = false;
+        }
+
+        // Safety: prevent infinite loop and statement limit
+        if (page > 50)
+        {
+            info "Safety limit: stopped at page 50";
+            hasMore = false;
+        }
+    }
+    catch (e)
+    {
+        info "Pagination failed at page " + page + ": " + e.toString();
+        hasMore = false;
+    }
+}
+
+info "Total records fetched: " + allRecords.size();
+```
+
+### Cursor-Based Pagination
+
+```deluge
+allRecords = List();
+cursor = "";
+hasMore = true;
+
+while (hasMore)
+{
+    try
+    {
+        url = "https://api.example.com/records";
+        if (cursor != "")
+        {
+            url = url + "?cursor=" + cursor;
+        }
+
+        response = invokeUrl [
+            url: url
+            type: GET
+            connection: "example-connection"
+        ];
+
+        data = response.toJSON();
+        allRecords.addAll(data.get("data"));
+
+        if (data.containsKey("next_cursor") && data.get("next_cursor") != null)
+        {
+            cursor = data.get("next_cursor");
+        }
+        else
+        {
+            hasMore = false;
+        }
+    }
+    catch (e)
+    {
+        info "Cursor pagination error: " + e.toString();
+        hasMore = false;
+    }
+}
+```
+
+## POST with JSON Body
+
+```deluge
+try
+{
+    payload = Map();
+    payload.put("name", input.Customer_Name);
+    payload.put("email", input.Email);
+    payload.put("amount", input.Total_Amount);
+    payload.put("line_items", List());
+
+    for each item in input.Line_Items
+    {
+        lineItem = Map();
+        lineItem.put("description", item.Description);
+        lineItem.put("quantity", item.Quantity);
+        lineItem.put("unit_price", item.Unit_Price);
+        payload.get("line_items").add(lineItem);
+    }
+
+    response = invokeUrl [
+        url: "https://api.example.com/invoices"
+        type: POST
+        headers: {"Content-Type": "application/json"}
+        body: payload.toString()
+        connection: "example-connection"
+    ];
+
+    if (response.getStatusCode() == 201)
+    {
+        externalId = response.toJSON().get("id");
+        input.External_Invoice_ID = externalId;
+        info "Invoice created externally: " + externalId;
+    }
+}
+catch (e)
+{
+    info "Invoice creation failed: " + e.toString();
+}
+```
+
+## Multipart Form Data / File Upload
+
+```deluge
+// Upload a file from Creator to an external API
+fileField = input.Attachment; // File field from form
+
+try
+{
+    response = invokeUrl [
+        url: "https://api.example.com/upload"
+        type: POST
+        files: fileField
+        connection: "example-connection"
+    ];
+
+    if (response.getStatusCode() == 200)
+    {
+        uploadResult = response.toJSON();
+        input.External_File_URL = uploadResult.get("url");
+    }
+}
+catch (e)
+{
+    info "File upload failed: " + e.toString();
+}
+```
+
+### Downloading Files
+
+```deluge
+try
+{
+    fileResponse = invokeUrl [
+        url: "https://api.example.com/files/12345/download"
+        type: GET
+        response_format: FILE
+        connection: "example-connection"
+    ];
+
+    // Attach to a form field
+    input.Downloaded_File = fileResponse;
+}
+catch (e)
+{
+    info "File download failed: " + e.toString();
+}
+```
+
+## Batch API Calls
+
+> **WARNING:** Each invokeUrl counts toward the 5000-statement limit AND each has a 40-second timeout risk. Batch carefully.
+
+```deluge
+// Batch pattern: collect, then single API call
+batchPayload = List();
+
+records = zoho.creator.getRecords("app", "Pending_Sync", "", 1, 50);
+for each record in records
+{
+    item = Map();
+    item.put("id", record.get("External_ID"));
+    item.put("status", record.get("Status"));
+    batchPayload.add(item);
+}
+
+// Single batch API call instead of 50 individual calls
+if (batchPayload.size() > 0)
+{
+    try
+    {
+        response = invokeUrl [
+            url: "https://api.example.com/batch-update"
+            type: POST
+            headers: {"Content-Type": "application/json"}
+            body: {"records": batchPayload}.toString()
+            connection: "example-connection"
+        ];
+
+        info "Batch update: " + response.getStatusCode();
+    }
+    catch (e)
+    {
+        info "Batch call failed: " + e.toString();
+    }
+}
+```
+
+## Common Pitfalls
+
+| Pitfall | Consequence | Prevention |
+|---------|-------------|-----------|
+| No try-catch on invokeUrl | Script crashes, no error info | ALWAYS wrap in try-catch |
+| Hardcoded tokens | Security risk, token expiry breaks | Use Connections |
+| No status code check | Silent failures | Always check getStatusCode() |
+| Unlimited pagination loop | 5000 statement limit hit | Add page count safety limit |
+| Large payload in single call | 40-second timeout | Chunk data, batch endpoints |
+| Ignoring rate limits (429) | Subsequent calls blocked | Implement backoff/retry |
+| Not logging errors | Can't debug production issues | Log to custom form/report |