@cloudstreamsoftware/claude-tools 1.0.0 → 1.1.0

package/skills/zoho-patterns/creator/form-design.md

@@ -0,0 +1,304 @@
+# Creator Form Design Patterns
+
+## Form Hierarchy
+
+| Level | Purpose | Example | Relationship |
+|-------|---------|---------|--------------|
+| Parent form | Core entity | Customers, Projects | Standalone |
+| Child form | Related record | Invoices (via Lookup to Customer) | Lookup field |
+| Subform | Inline 1:N data | Invoice Line Items (max 200 rows) | Embedded in parent |
+
+### When to Use Subforms vs. Separate Forms
+
+| Use Subform | Use Separate Form |
+|-------------|-------------------|
+| Items always viewed/edited with parent | Records accessed independently |
+| Under 50 rows typical (200 max) | Could grow to thousands of records |
+| No complex workflows on child items | Needs its own workflows/blueprints |
+| Line items, addresses, phone numbers | Invoices, tickets, projects |
+
+---
+
+## Field Types and When to Use Each
+
+| Field Type | Use For | Avoid When |
+|-----------|---------|-----------|
+| **Single Line** | Names, short labels, IDs | Content exceeds 255 chars |
+| **Multi Line** | Notes, descriptions, logs | Need rich formatting |
+| **Rich Text** | Formatted content, templates | Simple text (heavy on storage) |
+| **Email** | Email addresses | Already using Single Line (lose validation) |
+| **Number** | Integers, quantities, IDs | Decimal values needed |
+| **Decimal** | Currency, measurements, rates | Integer-only values |
+| **Currency** | Monetary values | Non-monetary decimals |
+| **Date** | Dates without time | Need time component |
+| **DateTime** | Timestamps, audit events | Date-only values |
+| **Decision Box** | Boolean yes/no values | Need multiple options |
+| **Picklist** | Fixed set of options (up to ~50) | Values change frequently |
+| **Multi-Select** | Multiple options from fixed set | Single selection needed |
+| **Lookup** | Relationship to another form | Storing IDs as text |
+| **Formula** | Computed values | Value needs user editing |
+| **Auto-number** | Sequential IDs, reference numbers | User-supplied IDs |
+| **File Upload** | Documents, images (50 MB max) | Storing file paths as text |
+
+---
+
+## Validation Rules
+
+### Built-in Validation
+
+```
+Field: Customer_Email
+  Type: Email
+  Required: YES
+  Unique: YES (prevents duplicate customers)
+
+Field: Phone_Number
+  Type: Single Line
+  Regex: ^\+?[1-9]\d{1,14}$
+  Error: "Enter a valid phone number with country code"
+
+Field: Invoice_Amount
+  Type: Currency
+  Min Value: 0.01
+  Max Value: 999999.99
+```
+
+### Deluge Validation (on Form Submit)
+
+```deluge
+// Custom validation rules in "on validate" workflow
+errors = List();
+
+// Cross-field validation
+if (input.End_Date < input.Start_Date)
+{
+    errors.add("End date must be after start date");
+}
+
+// Business rule validation
+if (input.Discount_Percent > 30 && input.Approved_By == "")
+{
+    errors.add("Discounts over 30% require manager approval");
+}
+
+// Conditional required fields
+if (input.Payment_Method == "ACH" && input.Routing_Number == "")
+{
+    errors.add("Routing number is required for ACH payments");
+}
+
+if (errors.size() > 0)
+{
+    cancel submit;
+    alert errors.toString("\n");
+}
+```
+
+---
+
+## Formula Fields
+
+### Common Patterns
+
+```
+// Full name from first + last
+Field: Full_Name
+Formula: First_Name + " " + Last_Name
+
+// Age from date of birth
+Field: Age
+Formula: ((zoho.currentdate - Date_of_Birth) / 365).floor()
+
+// Days since last contact
+Field: Days_Since_Contact
+Formula: if(Last_Contact_Date != null, (zoho.currentdate - Last_Contact_Date), -1)
+
+// Total from subform
+Field: Invoice_Total
+Formula: sum(Line_Items.Amount)
+
+// Status based on date
+Field: Overdue_Status
+Formula: if(Due_Date < zoho.currentdate && Status != "Paid", "OVERDUE", "OK")
+```
+
+---
+
+## Conditional Visibility (Page Rules)
+
+Use page rules to show/hide fields based on other field values:
+
+```
+Rule: Show HIPAA Fields
+  Condition: Compliance_Mode == "hipaa"
+  Show: PHI_Consent_Date, BAA_Status, Encryption_Level
+
+Rule: Show Payment Details
+  Condition: Payment_Method == "Credit Card"
+  Show: Card_Last_Four, Expiry_Month, Token_ID
+
+Rule: Show Approval Section
+  Condition: Amount > 10000
+  Show: Approver, Approval_Date, Approval_Notes
+  Make Required: Approver
+```
+
+---
+
+## Subform Patterns
+
+### Line Items Subform
+
+```
+Parent Form: Invoices
+Subform: Line_Items
+
+Fields:
+  - Item_Name (Single Line, required)
+  - Description (Multi Line)
+  - Quantity (Number, required, min: 1)
+  - Unit_Price (Currency, required)
+  - Discount_Percent (Decimal, default: 0)
+  - Line_Total (Formula: Quantity * Unit_Price * (1 - Discount_Percent / 100))
+```
+
+### Performance Guidelines for Subforms
+
+- Keep row count under 50 for responsive UI
+- Avoid lookup fields in subforms (each triggers a query)
+- Use formula fields over workflow calculations
+- Don't put subforms inside subforms (not supported)
+- Consider a separate form if rows exceed 100 regularly
+
+---
+
+## HIPAA-Compliant Form Design
+
+When compliance mode is `hipaa`, apply these rules to any form containing ePHI:
+
+### Field Marking
+
+```
+Field: Patient_Name [PHI]
+  - Help Text: "[PHI] Patient's full legal name"
+  - Encryption: ENABLED
+  - Access: Roles [Doctor, Nurse, Admin]
+  - Audit: ON (log all reads and writes)
+  - Reports: HIDDEN by default
+
+Field: Diagnosis_Code [PHI]
+  - Help Text: "[PHI] ICD-10 code"
+  - Encryption: ENABLED
+  - Access: Roles [Doctor]
+  - Audit: ON
+  - Reports: Aggregates only (never individual values)
+
+Field: SSN [PHI]
+  - Help Text: "[PHI] Social Security Number"
+  - Encryption: ENABLED
+  - Display Mask: ***-**-{last4}
+  - Access: Roles [Admin] only
+  - Audit: ON
+```
+
+### 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 fields from all reports by default
+5. Add audit trigger on form `on load` to log reads
+6. Never include ePHI in email notifications
+7. Implement "break-glass" access pattern for emergencies
+
+---
+
+## Field Permissions
+
+### Role-Based Access Matrix
+
+```
+Form: Patient_Records
+                    | View | Edit | Delete |
+  Admin             |  ALL |  ALL |  YES   |
+  Doctor            |  ALL | Medical fields | NO |
+  Nurse             | Non-sensitive | Vitals only | NO |
+  Billing           | Name, Insurance | Billing fields | NO |
+  Front Desk        | Name, Phone, Appt | Contact info | NO |
+```
+
+### Field-Level Permissions in Creator
+
+```
+Field: Annual_Revenue
+  View: Manager, Director, Admin
+  Edit: Director, Admin
+
+Field: Internal_Notes
+  View: All internal roles
+  Edit: All internal roles
+  HIDDEN from: Client portal users
+
+Field: Commission_Rate
+  View: HR, Finance
+  Edit: HR only
+```
+
+---
+
+## Lookup Relationships
+
+### One-to-Many (Lookup)
+
+```
+Form: Projects
+  Field: Client (Lookup → Clients form)
+  Display: Client.Company_Name
+  Filter: Client.Status == "Active"
+```
+
+### Many-to-Many (Junction Form)
+
+```
+Form: Project_Team_Members (junction form)
+  Field: Project (Lookup → Projects)
+  Field: Team_Member (Lookup → Employees)
+  Field: Role (Picklist: Lead, Member, Reviewer)
+  Field: Start_Date (Date)
+```
+
+### Cascading Lookups
+
+```
+Form: Support_Tickets
+  Field: Client (Lookup → Clients)
+  Field: Project (Lookup → Projects, filtered by Client)
+  Field: Contact (Lookup → Contacts, filtered by Client)
+```
+
+---
+
+## Performance Optimization
+
+| Technique | Impact | When to Apply |
+|-----------|--------|---------------|
+| Limit subform rows to <50 | Faster form load | Always |
+| Use page rules to hide sections | Less DOM rendering | Forms with 20+ fields |
+| Formula fields over workflows | No script execution | Computed values |
+| Limit lookup display fields | Fewer DB queries | Lookups showing 3+ columns |
+| Aggregate fields on parent | Avoid report calculations | Dashboards, summaries |
+| Archive old records | Smaller active dataset | Records >2 years old |
+| Index frequently-filtered fields | Faster report loading | High-traffic reports |
+
+---
+
+## Form Naming Conventions
+
+| Convention | Example | Rule |
+|-----------|---------|------|
+| Form name | `Customer_Intake` | PascalCase with underscores |
+| Field name | `First_Name` | PascalCase with underscores |
+| Subform | `Line_Items` | Plural, PascalCase |
+| Lookup field | `Client_ID` | Referenced form + `_ID` |
+| Formula field | `Calculated_Total` | Prefix with purpose |
+| Audit field | `Last_Modified_By` | Clear description |

package/skills/zoho-patterns/creator/publish-api-patterns.md

@@ -0,0 +1,313 @@
+# Creator Publish API Patterns
+
+## Why Publish API?
+
+> **CRITICAL:** Widgets do NOT work on published (external-facing) Creator pages. When you need to provide interactive functionality to external users (customers, vendors, partners), use the Publish API instead.
+
+## Decision Framework
+
+| Scenario | Use Widget | Use Publish API |
+|----------|-----------|-----------------|
+| Internal team data entry | Yes | No |
+| Customer-facing portal | No | Yes |
+| Embedded in Zoho apps | Yes | No |
+| Public data submission | No | Yes |
+| Complex UI with React/Vue | Maybe (internal) | Yes (external) |
+| Needs Zoho SDK context | Yes | No |
+
+## Publish API Authentication
+
+### API Key Method (Simple)
+
+```javascript
+// Generate API key: Setup > Developer > API Key
+const API_KEY = process.env.ZOHO_CREATOR_API_KEY;
+
+// Include in all requests
+const headers = {
+    "Authorization": `Zoho-oauthtoken ${accessToken}`
+};
+```
+
+### OAuth Method (Production)
+
+```javascript
+// For server-to-server or user-delegated access
+const axios = require("axios");
+
+async function getCreatorData(appName, reportName, criteria) {
+    const accessToken = await getValidAccessToken(); // See oauth-token-management.md
+
+    const response = await axios.get(
+        `https://creator.zoho.com/api/v2/${process.env.ZOHO_OWNER}/${appName}/report/${reportName}`,
+        {
+            headers: {
+                "Authorization": `Zoho-oauthtoken ${accessToken}`
+            },
+            params: {
+                criteria: criteria,
+                limit: 200,
+                start_index: 0
+            }
+        }
+    );
+
+    return response.data;
+}
+```
+
+## Rate Limits
+
+| Plan | Requests/Day | Requests/Minute |
+|------|-------------|-----------------|
+| Free | 1,000 | 20 |
+| Standard | 5,000 | 50 |
+| Professional | 10,000 | 100 |
+| Enterprise | 25,000 | 200 |
+
+> **WARNING:** Rate limits are per-org, not per-app. Multiple apps share the same quota.
+
+### Rate Limit Handling
+
+```javascript
+async function apiCallWithRetry(fn, maxRetries = 3) {
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            const response = await fn();
+            return response;
+        } catch (error) {
+            if (error.response && error.response.status === 429) {
+                // Rate limited - wait with exponential backoff
+                const waitMs = Math.pow(2, attempt) * 1000;
+                console.warn(`Rate limited. Retry ${attempt}/${maxRetries} in ${waitMs}ms`);
+                await new Promise(resolve => setTimeout(resolve, waitMs));
+            } else {
+                throw error; // Non-rate-limit error, don't retry
+            }
+        }
+    }
+    throw new Error("Max retries exceeded for rate-limited API call");
+}
+```
+
+## CRUD Operations via API
+
+### Create Record
+
+```javascript
+async function createRecord(appName, formName, data) {
+    const accessToken = await getValidAccessToken();
+
+    const response = await axios.post(
+        `https://creator.zoho.com/api/v2/${OWNER}/${appName}/form/${formName}`,
+        { data: data },
+        {
+            headers: {
+                "Authorization": `Zoho-oauthtoken ${accessToken}`,
+                "Content-Type": "application/json"
+            }
+        }
+    );
+
+    return response.data; // { code: 3000, data: { ID: "123456" } }
+}
+
+// Usage
+const newRecord = await createRecord("billing-app", "Invoices", {
+    Customer_Name: "Acme Corp",
+    Amount: 5000,
+    Due_Date: "2024-03-15",
+    Line_Items: [
+        { Item: "Consulting", Quantity: 10, Rate: 500 }
+    ]
+});
+```
+
+### Read Records (with Pagination)
+
+```javascript
+async function getAllRecords(appName, reportName, criteria = "") {
+    const accessToken = await getValidAccessToken();
+    let allRecords = [];
+    let startIndex = 0;
+    const pageSize = 200; // Max per page
+    let hasMore = true;
+
+    while (hasMore) {
+        const response = await axios.get(
+            `https://creator.zoho.com/api/v2/${OWNER}/${appName}/report/${reportName}`,
+            {
+                headers: { "Authorization": `Zoho-oauthtoken ${accessToken}` },
+                params: {
+                    criteria: criteria,
+                    limit: pageSize,
+                    start_index: startIndex
+                }
+            }
+        );
+
+        const records = response.data.data || [];
+        allRecords = allRecords.concat(records);
+
+        // Check if more pages exist
+        if (records.length < pageSize) {
+            hasMore = false;
+        } else {
+            startIndex += pageSize;
+        }
+    }
+
+    return allRecords;
+}
+```
+
+### Update Record
+
+```javascript
+async function updateRecord(appName, formName, recordId, data) {
+    const accessToken = await getValidAccessToken();
+
+    const response = await axios.patch(
+        `https://creator.zoho.com/api/v2/${OWNER}/${appName}/form/${formName}/${recordId}`,
+        { data: data },
+        {
+            headers: {
+                "Authorization": `Zoho-oauthtoken ${accessToken}`,
+                "Content-Type": "application/json"
+            }
+        }
+    );
+
+    return response.data;
+}
+```
+
+### Delete Record
+
+```javascript
+async function deleteRecord(appName, formName, recordId) {
+    const accessToken = await getValidAccessToken();
+
+    const response = await axios.delete(
+        `https://creator.zoho.com/api/v2/${OWNER}/${appName}/form/${formName}/${recordId}`,
+        {
+            headers: { "Authorization": `Zoho-oauthtoken ${accessToken}` }
+        }
+    );
+
+    return response.data;
+}
+```
+
+## Response Format
+
+### Success Response
+
+```json
+{
+    "code": 3000,
+    "data": {
+        "ID": "1234567890",
+        "Customer_Name": "Acme Corp",
+        "Amount": 5000
+    }
+}
+```
+
+### Error Response
+
+```json
+{
+    "code": 2900,
+    "error": {
+        "message": "Invalid criteria format",
+        "details": {
+            "field": "criteria",
+            "expected": "valid Zoho criteria expression"
+        }
+    }
+}
+```
+
+### Error Codes
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 3000 | Success | Process data |
+| 2890 | Invalid auth | Refresh token |
+| 2900 | Bad request | Check request format |
+| 2891 | Permission denied | Check app sharing settings |
+| 4000 | Rate limit exceeded | Retry with backoff |
+| 4100 | Record not found | Verify record ID |
+
+## Webhook Alternatives
+
+For real-time notifications instead of polling the API:
+
+```deluge
+// In Creator workflow (On Create/Edit), push data to external webhook
+webhookUrl = "https://your-app.com/webhook/creator-update";
+
+payload = Map();
+payload.put("event", "record_created");
+payload.put("form", "Invoices");
+payload.put("record_id", input.ID.toString());
+payload.put("data", {
+    "customer": input.Customer_Name,
+    "amount": input.Amount,
+    "status": input.Status
+});
+
+try
+{
+    response = invokeUrl [
+        url: webhookUrl
+        type: POST
+        headers: {
+            "Content-Type": "application/json",
+            "X-Webhook-Secret": "your-shared-secret"
+        }
+        body: payload.toString()
+    ];
+    info "Webhook delivered: " + response;
+}
+catch (e)
+{
+    // Log failure but don't block record creation
+    info "Webhook delivery failed: " + e.toString();
+}
+```
+
+### Webhook Verification (Receiving End)
+
+```javascript
+// Express.js webhook receiver
+const crypto = require("crypto");
+
+app.post("/webhook/creator-update", (req, res) => {
+    // Verify webhook signature
+    const secret = process.env.WEBHOOK_SECRET;
+    const signature = req.headers["x-webhook-secret"];
+
+    if (signature !== secret) {
+        return res.status(401).json({ error: "Invalid signature" });
+    }
+
+    const { event, form, record_id, data } = req.body;
+
+    // Process async to respond quickly
+    processWebhookAsync(event, form, record_id, data);
+
+    // Respond immediately (Creator invokeUrl has 40-second timeout)
+    res.status(200).json({ received: true });
+});
+```
+
+## Security Best Practices
+
+1. **Never expose API keys in client-side code** - Use server-side proxy
+2. **Validate all input** before passing to Creator API
+3. **Use field-level permissions** to restrict API access to specific fields
+4. **Enable IP whitelisting** in Creator API settings for production servers
+5. **Rotate credentials** quarterly for SOC2 compliance clients
+6. **Log all API access** for audit trail (HIPAA requirement)