@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/skills/zoho-patterns/deluge/error-handling.md

@@ -0,0 +1,423 @@
+# Deluge Error Handling
+
+## Structured Error Response Pattern
+
+All custom functions should return consistent error structures:
+
+```deluge
+// Standard response format
+successResponse = Map();
+successResponse.put("status", "success");
+successResponse.put("message", "Operation completed");
+successResponse.put("data", resultData);
+return successResponse;
+
+errorResponse = Map();
+errorResponse.put("status", "error");
+errorResponse.put("message", "Human-readable error description");
+errorResponse.put("code", "ERR_VALIDATION_FAILED");
+errorResponse.put("data", null);
+return errorResponse;
+```
+
+### Response Structure
+
+```json
+{
+    "status": "success | error | warning",
+    "message": "Human-readable description",
+    "code": "MACHINE_READABLE_ERROR_CODE",
+    "data": {},
+    "errors": [],
+    "timestamp": "2024-01-15T10:30:00Z"
+}
+```
+
+## Try-Catch Patterns
+
+### Basic Try-Catch
+
+```deluge
+try
+{
+    result = zoho.crm.getRecordById("Deals", dealId);
+    if (result == null)
+    {
+        return {"status": "error", "code": "NOT_FOUND", "message": "Deal not found: " + dealId};
+    }
+    return {"status": "success", "data": result};
+}
+catch (e)
+{
+    return {"status": "error", "code": "SYSTEM_ERROR", "message": e.toString()};
+}
+```
+
+### Nested Try-Catch (Multiple Operations)
+
+```deluge
+// When one operation depends on another
+try
+{
+    // Step 1: Fetch customer
+    customer = zoho.crm.getRecordById("Contacts", contactId);
+    if (customer == null)
+    {
+        return {"status": "error", "code": "CUSTOMER_NOT_FOUND", "message": "Contact " + contactId + " not found"};
+    }
+
+    // Step 2: Create invoice (separate try-catch for different error handling)
+    try
+    {
+        invoice = zoho.books.createRecord("invoices", orgId, invoiceData, "books-connection");
+        if (invoice.get("code") != 0)
+        {
+            return {"status": "error", "code": "BOOKS_ERROR", "message": invoice.get("message")};
+        }
+    }
+    catch (booksError)
+    {
+        return {"status": "error", "code": "BOOKS_UNAVAILABLE", "message": "Books API error: " + booksError.toString()};
+    }
+
+    // Step 3: Update CRM with invoice reference
+    try
+    {
+        zoho.crm.updateRecord("Contacts", contactId, {"Last_Invoice_ID": invoice.get("invoice").get("invoice_id")});
+    }
+    catch (crmError)
+    {
+        // Non-critical failure - log but don't fail the whole operation
+        info "Warning: CRM update failed: " + crmError.toString();
+    }
+
+    return {"status": "success", "data": {"invoice_id": invoice.get("invoice").get("invoice_id")}};
+}
+catch (e)
+{
+    return {"status": "error", "code": "UNEXPECTED", "message": e.toString()};
+}
+```
+
+## Logging to Custom Form
+
+### Error Log Form Structure
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| Error_Code | Text | Machine-readable code |
+| Error_Message | Multi-line | Human-readable description |
+| Source_Function | Text | Which function generated the error |
+| Source_Record_ID | Text | Related record if applicable |
+| Stack_Trace | Multi-line | Full error details |
+| Severity | Dropdown | Critical, Error, Warning, Info |
+| Timestamp | DateTime | When the error occurred |
+| User | Text | Who triggered the action |
+| Resolution | Multi-line | How it was fixed (filled later) |
+| Resolved | Decision Box | Whether issue is resolved |
+
+### Logging Function
+
+```deluge
+// Custom function: logError(code, message, source, severity, recordId)
+logMap = Map();
+logMap.put("Error_Code", code);
+logMap.put("Error_Message", message);
+logMap.put("Source_Function", source);
+logMap.put("Severity", severity);
+logMap.put("Source_Record_ID", if(recordId != null, recordId.toString(), ""));
+logMap.put("Timestamp", zoho.currenttime);
+logMap.put("User", zoho.loginuserid);
+logMap.put("Resolved", false);
+
+try
+{
+    zoho.creator.createRecord("admin-app", "Error_Logs", logMap);
+}
+catch (logError)
+{
+    // If even logging fails, use info as last resort
+    info "CRITICAL: Error logging failed. Original error: " + code + " - " + message;
+}
+```
+
+### Usage in Workflows
+
+```deluge
+try
+{
+    // Business logic here
+    processInvoice(input);
+}
+catch (e)
+{
+    // Log the error
+    logError(
+        "INVOICE_PROCESS_FAIL",
+        e.toString(),
+        "Invoice_OnCreate_Workflow",
+        "Error",
+        input.ID
+    );
+
+    // Also notify if critical
+    if (input.Amount > 10000)
+    {
+        notifyAdmin("Critical invoice processing failure", e.toString(), input.ID);
+    }
+}
+```
+
+## Admin Notification Patterns
+
+### Email Notification
+
+```deluge
+// Custom function: notifyAdmin(subject, details, recordId)
+body = "<h3>Error Alert</h3>";
+body = body + "<p><strong>Time:</strong> " + zoho.currenttime + "</p>";
+body = body + "<p><strong>Record:</strong> " + recordId + "</p>";
+body = body + "<p><strong>Details:</strong></p><pre>" + details + "</pre>";
+body = body + "<p><a href='https://creator.zoho.com/app/admin-app#Form:Error_Logs'>View Error Logs</a></p>";
+
+sendmail [
+    from: zoho.adminuserid
+    to: "admin@company.com"
+    subject: "[ERROR] " + subject
+    message: body
+    content_type: html
+];
+```
+
+### Cliq Notification (Instant)
+
+```deluge
+// Post to Zoho Cliq channel for real-time alerts
+cliqMessage = Map();
+cliqMessage.put("text", "*Error Alert*\n" + subject + "\n```" + details + "```");
+
+try
+{
+    postToCliq = invokeUrl [
+        url: "https://cliq.zoho.com/api/v2/channelsbyname/error-alerts/message"
+        type: POST
+        headers: {"Content-Type": "application/json"}
+        body: cliqMessage.toString()
+        connection: "zoho-cliq-connection"
+    ];
+}
+catch (cliqError)
+{
+    info "Cliq notification failed: " + cliqError.toString();
+    // Fall back to email
+    sendmail [
+        from: zoho.adminuserid
+        to: "admin@company.com"
+        subject: "[ERROR] " + subject
+        message: details
+    ];
+}
+```
+
+## Error Categorization
+
+```deluge
+// Categorize errors for appropriate handling
+function categorizeError(errorString)
+{
+    if (errorString.contains("timeout") || errorString.contains("timed out"))
+    {
+        return "TIMEOUT";
+    }
+    else if (errorString.contains("401") || errorString.contains("unauthorized"))
+    {
+        return "AUTH_FAILURE";
+    }
+    else if (errorString.contains("429") || errorString.contains("rate limit"))
+    {
+        return "RATE_LIMITED";
+    }
+    else if (errorString.contains("404") || errorString.contains("not found"))
+    {
+        return "NOT_FOUND";
+    }
+    else if (errorString.contains("500") || errorString.contains("internal server"))
+    {
+        return "EXTERNAL_SERVER_ERROR";
+    }
+    else if (errorString.contains("null") || errorString.contains("NullPointer"))
+    {
+        return "NULL_REFERENCE";
+    }
+    else
+    {
+        return "UNKNOWN";
+    }
+}
+
+// Usage
+try
+{
+    response = invokeUrl [ url: apiUrl type: GET connection: "conn" ];
+}
+catch (e)
+{
+    category = categorizeError(e.toString());
+
+    if (category == "TIMEOUT" || category == "RATE_LIMITED" || category == "EXTERNAL_SERVER_ERROR")
+    {
+        // Transient - safe to retry
+        logError(category, e.toString(), "api_call", "Warning", null);
+    }
+    else if (category == "AUTH_FAILURE")
+    {
+        // Critical - needs human intervention
+        logError(category, e.toString(), "api_call", "Critical", null);
+        notifyAdmin("Connection auth failure - reauthorization needed", e.toString(), null);
+    }
+    else
+    {
+        // Log for investigation
+        logError(category, e.toString(), "api_call", "Error", null);
+    }
+}
+```
+
+## Graceful Degradation
+
+```deluge
+// When a non-critical external service fails, continue with defaults
+function getExchangeRate(currency)
+{
+    try
+    {
+        response = invokeUrl [
+            url: "https://api.exchangerate.com/latest/" + currency
+            type: GET
+            connection: "exchange-rate-connection"
+        ];
+        return response.toJSON().get("rates").get("USD").toDecimal();
+    }
+    catch (e)
+    {
+        // Graceful degradation: use last known rate from cache
+        cachedRates = zoho.creator.getRecords("admin-app", "Exchange_Rates",
+            "Currency == \"" + currency + "\"", 1, 1);
+
+        if (cachedRates.size() > 0)
+        {
+            info "Using cached exchange rate for " + currency;
+            return cachedRates.get(0).get("Rate").toDecimal();
+        }
+        else
+        {
+            info "No cached rate available, using 1.0 default for " + currency;
+            return 1.0;
+        }
+    }
+}
+```
+
+## User-Facing vs Internal Errors
+
+```deluge
+// Never expose internal details to end users
+try
+{
+    result = processOrder(input);
+    return {"status": "success", "message": "Your order has been submitted successfully."};
+}
+catch (e)
+{
+    // Internal: Full error details for debugging
+    logError("ORDER_FAIL", e.toString(), "processOrder", "Error", input.ID);
+
+    // User-facing: Friendly message only
+    errorCategory = categorizeError(e.toString());
+
+    userMessage = "";
+    if (errorCategory == "TIMEOUT")
+    {
+        userMessage = "The system is experiencing delays. Please try again in a few minutes.";
+    }
+    else if (errorCategory == "AUTH_FAILURE")
+    {
+        userMessage = "There was a configuration issue. Our team has been notified.";
+    }
+    else
+    {
+        userMessage = "An unexpected error occurred. Please contact support with reference: " + input.ID;
+    }
+
+    return {"status": "error", "message": userMessage};
+}
+```
+
+## Validation Error Pattern
+
+```deluge
+// Collect all validation errors before failing
+function validateInvoice(input)
+{
+    errors = List();
+
+    if (input.Customer_Name == null || input.Customer_Name == "")
+    {
+        errors.add("Customer name is required");
+    }
+
+    if (input.Amount == null || input.Amount <= 0)
+    {
+        errors.add("Amount must be greater than zero");
+    }
+
+    if (input.Due_Date != null && input.Due_Date < zoho.currentdate)
+    {
+        errors.add("Due date cannot be in the past");
+    }
+
+    if (input.Line_Items == null || input.Line_Items.size() == 0)
+    {
+        errors.add("At least one line item is required");
+    }
+
+    if (input.Line_Items != null && input.Line_Items.size() > 200)
+    {
+        errors.add("Cannot exceed 200 line items (subform limit)");
+    }
+
+    if (errors.size() > 0)
+    {
+        return {
+            "status": "error",
+            "code": "VALIDATION_FAILED",
+            "message": "Validation failed with " + errors.size() + " error(s)",
+            "errors": errors
+        };
+    }
+
+    return {"status": "success"};
+}
+
+// Usage
+validation = validateInvoice(input);
+if (validation.get("status") == "error")
+{
+    alert validation.get("errors").toString("\n");
+    cancel submit;
+}
+```
+
+## Error Monitoring Dashboard Query
+
+Create a report in Creator with this criteria for monitoring:
+
+```
+Severity == "Critical" && Resolved == false && Timestamp >= zoho.currentdate.subDay(7)
+```
+
+Key metrics to track:
+- Error count by category (last 7 days)
+- Mean time to resolution
+- Top 5 error sources
+- Unresolved critical errors (alert if > 0)

package/skills/zoho-patterns/deluge/syntax-reference.md

@@ -0,0 +1,65 @@
+# Deluge Quick Reference
+
+## Data Types
+- TEXT, NUMBER, DECIMAL, BOOLEAN, DATE, DATETIME
+- LIST, MAP, FILE, JSON
+
+## Common Operations
+
+### Record Operations
+```deluge
+// Create
+newRecord = zoho.creator.createRecord("app", "Form_Name", dataMap);
+
+// Read (with pagination)
+records = zoho.creator.getRecords("app", "Report_Name", criteria, 1, 200);
+
+// Update
+zoho.creator.updateRecord("app", "Form_Name", recordId, updateMap);
+
+// Delete
+zoho.creator.deleteRecord("app", "Form_Name", recordId);
+```
+
+### CRM Operations
+```deluge
+// Get records
+records = zoho.crm.getRecords("Contacts", criteria, 1, 200);
+
+// Create record
+newId = zoho.crm.createRecord("Deals", dataMap);
+
+// Search
+results = zoho.crm.searchRecords("Contacts", "(Email:equals:" + email + ")");
+```
+
+### String Operations
+```deluge
+str.contains("search")
+str.startsWith("prefix")
+str.length()
+str.toUpperCase()
+str.replaceAll("old", "new")
+str.getPrefix(",")  // Before first comma
+str.getSuffix(",")  // After first comma
+```
+
+### List Operations
+```deluge
+list.add(item)
+list.remove(index)
+list.size()
+list.get(index)
+list.contains(item)
+list.sort(true)  // ascending
+```
+
+### Map Operations
+```deluge
+map.put("key", value)
+map.get("key")
+map.containsKey("key")
+map.keys()
+map.values()
+map.size()
+```