@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/skills/zoho-patterns/SKILL.md

@@ -0,0 +1,446 @@
+---
+name: zoho-patterns
+description: Zoho platform development patterns covering Creator, Catalyst, Deluge, integrations, and analytics. Core skill for all Zoho development work.
+version: 1.0.0
+status: active
+introduced: 1.0.0
+lastUpdated: 2026-01-25
+activation: Any Zoho development task, Creator forms, Catalyst functions, Deluge scripts, Zoho integrations
+---
+
+# Zoho Development Patterns
+
+Comprehensive patterns for Zoho Creator, Catalyst, Deluge, and cross-app integrations. This skill is activated for all Zoho platform development tasks.
+
+## Platform Constraints (CRITICAL)
+
+These hard limits are enforced by the platform and cannot be circumvented:
+
+| Constraint | Limit | Workaround |
+|------------|-------|------------|
+| Deluge statement limit | 5,000 per execution | Chunk into multiple functions |
+| `invokeUrl` timeout | 40 seconds | Use Catalyst for long-running |
+| Catalyst Basic I/O | 30 seconds | Move heavy work to Cron/Event |
+| Catalyst Cron/Event | 15 minutes | Paginate, checkpoint progress |
+| Subform row limit | 200 rows | Use separate form for more |
+| OAuth token expiry | 1 hour | Implement refresh, use Connections |
+| Creator audit retention | 1 year | Export to Analytics for archival |
+| File upload size | 50 MB | Use external storage + URL reference |
+| CRM→Books native sync | 2-hour cycle | Trigger sync via API if urgent |
+
+### Catalyst-Specific Requirements
+
+```
+CRITICAL: context.close() is MANDATORY in ALL Catalyst functions.
+Without it, the function hangs until timeout. ALWAYS use finally block:
+
+try {
+    // Your logic
+} finally {
+    context.close(); // MANDATORY
+}
+```
+
+---
+
+## Skill Files Reference
+
+| Directory | Focus Area | Key Files |
+|-----------|------------|-----------|
+| `creator/` | Forms, workflows, widgets | form-design.md, workflow-automation.md, widget-integration.md |
+| `catalyst/` | Functions, deployment | function-patterns.md, cron-batch-processing.md, appsail-deployment.md |
+| `deluge/` | Scripting, APIs | syntax-reference.md, error-handling.md, batch-processing.md |
+| `integration/` | Cross-app, OAuth | oauth-token-management.md, cors-proxy-architecture.md |
+| `analytics/` | Dashboards, pipelines | dashboard-patterns.md, zoho-to-bigquery-pipeline.md |
+
+---
+
+## Creator Patterns
+
+### Form Hierarchy
+
+| Level | Purpose | Relationship |
+|-------|---------|--------------|
+| Parent form | Core entity (Customers, Projects) | Standalone |
+| Child form | Related record (Invoices) | Lookup field to parent |
+| Subform | Inline 1:N data (Line Items) | Embedded, max 200 rows |
+
+**When to Use Subforms vs. Separate Forms:**
+
+| Use Subform | Use Separate Form |
+|-------------|-------------------|
+| Items always viewed with parent | Records accessed independently |
+| Under 50 rows typical (200 max) | Could grow to thousands |
+| No complex workflows on items | Needs own workflows/blueprints |
+
+### Field Types Quick Reference
+
+| Type | Use For | Avoid When |
+|------|---------|------------|
+| Single Line | Names, short text, IDs | > 255 characters |
+| Multi Line | Notes, descriptions | Need rich formatting |
+| Rich Text | Formatted content | Simple text (heavy storage) |
+| Number | Integers, quantities | Decimal values needed |
+| Decimal | Currency, rates | Integer-only values |
+| Lookup | Relationships | Storing IDs as text |
+| Formula | Computed values | User needs to edit |
+| Subform | Inline related records | > 200 rows expected |
+
+### HIPAA-Compliant Forms
+
+When `CLOUDSTREAM_COMPLIANCE_MODE=hipaa`, apply to forms with ePHI:
+
+```
+Field: Patient_Name [PHI]
+  - Help Text: "[PHI] Patient's full legal name"
+  - Encryption: ENABLED
+  - Access: Minimum necessary roles
+  - Audit: ON (log all reads/writes)
+  - Reports: HIDDEN by default
+```
+
+**HIPAA Form Rules:**
+1. Add `[PHI]` prefix to help text of every ePHI field
+2. Enable field-level encryption for all ePHI fields
+3. Set field permissions to minimum necessary roles
+4. Hide ePHI from all reports by default
+5. Never include ePHI in email notifications
+
+→ See [creator/form-design.md](creator/form-design.md) for complete patterns
+
+---
+
+## Catalyst Patterns
+
+### Function Types
+
+| Type | Timeout | Trigger | Use Case |
+|------|---------|---------|----------|
+| Basic I/O | 30 sec | HTTP (SDK) | CRUD endpoints, widget backends |
+| Cron | 15 min | Schedule | Batch syncs, archival, reports |
+| Event | 15 min | Table/file ops | Post-processing, notifications |
+| AppSail | Unlimited | HTTP | Long-running, full web apps |
+
+### Basic I/O Pattern
+
+```javascript
+module.exports = async (context, basicIO) => {
+  const catalyst = require('zcatalyst-sdk-node');
+  const app = catalyst.initialize(context);
+
+  try {
+    const input = JSON.parse(basicIO.getArgument('data') || '{}');
+
+    // Your business logic here
+    const result = await processRequest(app, input);
+
+    basicIO.write(JSON.stringify({ status: 'success', data: result }));
+  } catch (error) {
+    basicIO.write(JSON.stringify({ status: 'error', message: error.message }));
+  } finally {
+    context.close(); // MANDATORY
+  }
+};
+```
+
+### Cron Pattern (Paginated Sync)
+
+```javascript
+module.exports = async (cronDetails, context) => {
+  const startTime = Date.now();
+
+  try {
+    let hasMore = true;
+    while (hasMore) {
+      // Check timeout (leave 2 min buffer)
+      if (Date.now() - startTime > 13 * 60 * 1000) {
+        console.log('Approaching timeout - stopping');
+        break;
+      }
+
+      // Process batch...
+      hasMore = await processBatch();
+    }
+  } finally {
+    context.close(); // MANDATORY
+  }
+};
+```
+
+### AppSail Requirements
+
+```javascript
+// MUST bind to process.env.PORT (Catalyst requirement)
+const PORT = process.env.PORT || 9000;
+app.listen(PORT, () => console.log(`Running on ${PORT}`));
+```
+
+→ See [catalyst/function-patterns.md](catalyst/function-patterns.md) for complete examples
+
+---
+
+## Deluge Patterns
+
+### Data Types
+
+`TEXT`, `NUMBER`, `DECIMAL`, `BOOLEAN`, `DATE`, `DATETIME`, `LIST`, `MAP`, `FILE`, `JSON`
+
+### Common Operations
+
+```deluge
+// CREATE record
+newRecord = zoho.creator.createRecord("app", "Form_Name", dataMap);
+
+// READ with pagination
+records = zoho.creator.getRecords("app", "Report_Name", criteria, 1, 200);
+
+// UPDATE record
+zoho.creator.updateRecord("app", "Form_Name", recordId, updateMap);
+
+// DELETE record
+zoho.creator.deleteRecord("app", "Form_Name", recordId);
+```
+
+### CRM Operations
+
+```deluge
+// Get records
+records = zoho.crm.getRecords("Contacts", criteria, 1, 200);
+
+// Search records
+results = zoho.crm.searchRecords("Contacts", "(Email:equals:" + email + ")");
+
+// Create record
+newId = zoho.crm.createRecord("Deals", dataMap);
+```
+
+### Error Handling Pattern
+
+```deluge
+try
+{
+    result = zoho.crm.getRecordById("Deals", dealId);
+    if (result == null)
+    {
+        return {"status": "error", "code": "NOT_FOUND"};
+    }
+    return {"status": "success", "data": result};
+}
+catch (e)
+{
+    // Log to Error_Logs form
+    logError("CRM_ERROR", e.toString(), "getDeal", "Error", dealId);
+    return {"status": "error", "message": e.toString()};
+}
+```
+
+### Validation Pattern
+
+```deluge
+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 (errors.size() > 0)
+{
+    cancel submit;
+    alert errors.toString("\n");
+}
+```
+
+→ See [deluge/syntax-reference.md](deluge/syntax-reference.md) and [deluge/error-handling.md](deluge/error-handling.md)
+
+---
+
+## Integration Patterns
+
+### OAuth Token Management
+
+**Zoho Access Token Lifecycle:**
+```
+Auth Code (10 min TTL) → Access Token (1 hour TTL) → Refresh Token (no expiry)
+```
+
+**Preferred: Use Connections (auto-refresh)**
+
+```deluge
+response = invokeUrl [
+    url: "https://www.zohoapis.com/crm/v5/Deals"
+    type: GET
+    connection: "zoho-crm-connection"  // Handles refresh automatically
+];
+```
+
+**Standalone Apps: Manual Refresh**
+
+```javascript
+class ZohoTokenManager {
+    async getAccessToken() {
+        // Refresh proactively at 50 minutes
+        const bufferMs = 10 * 60 * 1000;
+        if (this.accessToken && Date.now() < this.expiresAt - bufferMs) {
+            return this.accessToken;
+        }
+        // Refresh logic...
+    }
+}
+```
+
+### Multi-DC Support
+
+| DC | Accounts URL | API Domain | Region |
+|----|--------------|------------|--------|
+| com | accounts.zoho.com | zohoapis.com | US |
+| eu | accounts.zoho.eu | zohoapis.eu | Europe |
+| in | accounts.zoho.in | zohoapis.in | India |
+| com.au | accounts.zoho.com.au | zohoapis.com.au | Australia |
+
+**Per-Client Token Management:**
+
+```javascript
+// Each client has separate OAuth app - NEVER share tokens
+const zoho = new ZohoTokenManager(
+    process.env.ZOHO_CLIENT_ID,
+    process.env.ZOHO_CLIENT_SECRET,
+    process.env.ZOHO_REFRESH_TOKEN,
+    process.env.ZOHO_DC || "com"
+);
+```
+
+### Token Storage Rules
+
+| ✅ Safe Storage | ❌ Never Store In |
+|-----------------|-------------------|
+| Catalyst Segments | Deluge variables |
+| Environment variables | Git repos (even private) |
+| GCP Secret Manager | Client-side JS |
+| .env file (gitignored) | Log files |
+
+→ See [integration/oauth-token-management.md](integration/oauth-token-management.md)
+
+### CORS Proxy (for Widgets)
+
+Creator widgets cannot call external APIs directly. Use Catalyst AppSail:
+
+```javascript
+// AppSail CORS proxy
+app.post('/api/proxy', async (req, res) => {
+    const { url, method, headers, body } = req.body;
+
+    // Whitelist allowed domains
+    const allowedDomains = ['api.stripe.com', 'api.sendgrid.com'];
+    if (!allowedDomains.includes(new URL(url).hostname)) {
+        return res.status(403).json({ error: 'Domain not whitelisted' });
+    }
+
+    const response = await fetch(url, { method, headers, body });
+    res.json(await response.json());
+});
+```
+
+→ See [integration/cors-proxy-architecture.md](integration/cors-proxy-architecture.md)
+
+---
+
+## Analytics Patterns
+
+### Report Types
+
+| Type | Best For |
+|------|----------|
+| Chart | Trends, comparisons |
+| Pivot Table | Multi-dimensional analysis |
+| KPI Widget | Single metric display |
+| Dashboard | Combined executive views |
+| Tabular | Detailed listings, audit trails |
+
+### SQL Queries in Analytics
+
+```sql
+-- Revenue by month
+SELECT
+    YEAR("Invoice_Date") AS year,
+    MONTH("Invoice_Date") AS month,
+    SUM("Amount") AS total_revenue
+FROM "Invoices"
+WHERE "Status" = 'Paid'
+GROUP BY YEAR("Invoice_Date"), MONTH("Invoice_Date")
+ORDER BY year DESC, month DESC
+
+-- Customer lifetime value
+SELECT
+    "Customer_Name",
+    SUM("Amount") AS lifetime_value,
+    COUNT("Invoice_ID") AS total_invoices
+FROM "Invoices"
+GROUP BY "Customer_Name"
+HAVING SUM("Amount") > 1000
+ORDER BY lifetime_value DESC
+```
+
+### Embedding Analytics in Creator
+
+```html
+<iframe
+    src="https://analytics.zoho.com/open-view/{workspace}/{view}?ZOHO_CRITERIA=%22Status%22%3D%27Active%27"
+    width="100%"
+    height="500">
+</iframe>
+```
+
+### Row-Level Security
+
+```sql
+-- Sales reps: only their own data
+"Owner_Email" = ZOHO_LOGINUSER_EMAIL
+
+-- Managers: their team's data
+"Team" = ZOHO_LOGINUSER_ROLE
+```
+
+→ See [analytics/dashboard-patterns.md](analytics/dashboard-patterns.md)
+
+---
+
+## Common Mistakes
+
+| Mistake | Consequence | Fix |
+|---------|-------------|-----|
+| Missing `context.close()` | Function hangs until timeout | Always use `finally` block |
+| Not binding to `PORT` | AppSail container fails | `app.listen(process.env.PORT)` |
+| Exceeding 30s in I/O | Request timeout (504) | Use Cron/Event function |
+| Hardcoded tokens | Security vulnerability | Use Connections or env vars |
+| Over-scoped OAuth | Security risk | Minimum necessary scopes |
+| Ignoring DC | Wrong API domain | Detect from client config |
+| Subform > 200 rows | Data loss | Use separate form |
+| No error logging | Silent failures | Log to Error_Logs form |
+
+---
+
+## Related Skills
+
+| Skill | When Used Together |
+|-------|-------------------|
+| [compliance-patterns](../compliance-patterns/) | HIPAA/SOC2 forms and data handling |
+| [bigquery-patterns](../bigquery-patterns/) | Zoho Analytics → BigQuery pipelines |
+| [backend-patterns](../backend-patterns/) | Catalyst function architecture |
+| [gcp-data-engineering](../gcp-data-engineering/) | Data warehouse integration |
+
+---
+
+## Quick Command Reference
+
+| Command | Purpose |
+|---------|---------|
+| `/zoho-scaffold` | Generate Creator app, Catalyst function, or Widget |
+| `/deluge` | Generate or fix Deluge script |
+| `/compliance-check` | Audit Zoho forms for compliance |
+| `/code-review` | Review Deluge and Catalyst code |