@cloudstreamsoftware/claude-tools 1.0.0 → 1.2.0

package/skills/zoho-patterns/catalyst/function-patterns.md

@@ -0,0 +1,439 @@
+# Catalyst Function Patterns
+
+## Function Types and Timeouts
+
+| Type | Timeout | Trigger | Use Case |
+|------|---------|---------|----------|
+| Basic I/O | 30 seconds | HTTP request (client SDK) | CRUD endpoints, widget backends |
+| Cron | 15 minutes | Schedule (cron expression) | Batch syncs, archival, reports |
+| Event | 15 minutes | Catalyst event (table ops, file ops) | Post-processing, notifications |
+
+> **CRITICAL**: `context.close()` is MANDATORY in ALL function types. Without it, the function hangs until timeout. ALWAYS place it in a `finally` block to guarantee execution.
+
+---
+
+## Basic I/O Function (30s timeout)
+
+### Pattern: CRUD Endpoint for Creator Widget
+
+```javascript
+'use strict';
+
+const catalyst = require('zcatalyst-sdk-node');
+
+module.exports = async (context, basicIO) => {
+  const app = catalyst.initialize(context);
+  const response = { status: 'success', data: null };
+
+  try {
+    const method = context.getHTTPMethod ? context.getHTTPMethod() : 'GET';
+    const input = JSON.parse(basicIO.getArgument('data') || '{}');
+
+    switch (input.action) {
+      case 'getContacts': {
+        const zcql = app.zcql();
+        const result = await zcql.executeZCQLQuery(
+          `SELECT * FROM Contacts WHERE Status = 'Active' LIMIT 200`
+        );
+        response.data = result;
+        break;
+      }
+
+      case 'createContact': {
+        const table = app.datastore().table('Contacts');
+        const row = await table.insertRow({
+          Name: input.name,
+          Email: input.email,
+          Phone: input.phone || '',
+          Status: 'Active',
+          Created_By: input.userId
+        });
+        response.data = { id: row.ROWID, message: 'Contact created' };
+        break;
+      }
+
+      case 'updateContact': {
+        const table = app.datastore().table('Contacts');
+        const row = await table.updateRow({
+          ROWID: input.recordId,
+          Name: input.name,
+          Email: input.email,
+          Phone: input.phone
+        });
+        response.data = { id: row.ROWID, message: 'Contact updated' };
+        break;
+      }
+
+      case 'deleteContact': {
+        const table = app.datastore().table('Contacts');
+        await table.deleteRow(input.recordId);
+        response.data = { message: 'Contact deleted' };
+        break;
+      }
+
+      default:
+        response.status = 'error';
+        response.message = `Unknown action: ${input.action}`;
+    }
+
+    basicIO.write(JSON.stringify(response));
+  } catch (error) {
+    console.error('Function error:', error.message);
+    response.status = 'error';
+    response.message = error.message;
+    basicIO.write(JSON.stringify(response));
+  } finally {
+    context.close(); // MANDATORY - always in finally block
+  }
+};
+```
+
+### Pattern: Webhook Handler (External API Callback)
+
+```javascript
+'use strict';
+
+const crypto = require('crypto');
+const catalyst = require('zcatalyst-sdk-node');
+
+module.exports = async (context, basicIO) => {
+  const app = catalyst.initialize(context);
+  const response = { status: 'received' };
+
+  try {
+    const payload = JSON.parse(basicIO.getArgument('data') || '{}');
+    const signature = basicIO.getArgument('signature') || '';
+
+    // Verify webhook signature
+    const secret = await app.cache()
+      .segment('config')
+      .getItem('webhook_secret');
+
+    const expectedSignature = crypto
+      .createHmac('sha256', secret.cache_value)
+      .update(JSON.stringify(payload))
+      .digest('hex');
+
+    if (!crypto.timingSafeEqual(
+      Buffer.from(signature, 'hex'),
+      Buffer.from(expectedSignature, 'hex')
+    )) {
+      console.error('Invalid webhook signature');
+      response.status = 'unauthorized';
+      basicIO.write(JSON.stringify(response));
+      return;
+    }
+
+    // Process webhook event
+    const eventType = payload.event_type;
+    console.log(`Processing webhook: ${eventType}`);
+
+    switch (eventType) {
+      case 'payment.succeeded':
+        await handlePaymentSuccess(app, payload.data);
+        break;
+      case 'payment.failed':
+        await handlePaymentFailure(app, payload.data);
+        break;
+      default:
+        console.log(`Unhandled event type: ${eventType}`);
+    }
+
+    response.status = 'processed';
+    basicIO.write(JSON.stringify(response));
+  } catch (error) {
+    console.error('Webhook processing error:', error.message);
+    response.status = 'error';
+    response.message = error.message;
+    basicIO.write(JSON.stringify(response));
+  } finally {
+    context.close(); // MANDATORY
+  }
+};
+
+async function handlePaymentSuccess(app, data) {
+  const table = app.datastore().table('Payments');
+  await table.insertRow({
+    Transaction_ID: data.transaction_id,
+    Amount: data.amount,
+    Currency: data.currency,
+    Customer_Email: data.customer_email,
+    Status: 'Succeeded',
+    Processed_At: new Date().toISOString()
+  });
+}
+
+async function handlePaymentFailure(app, data) {
+  const table = app.datastore().table('Payments');
+  await table.insertRow({
+    Transaction_ID: data.transaction_id,
+    Amount: data.amount,
+    Status: 'Failed',
+    Failure_Reason: data.failure_reason,
+    Processed_At: new Date().toISOString()
+  });
+
+  // Send notification via Catalyst Mail
+  const mail = app.email();
+  await mail.sendMail({
+    from_email: 'payments@clientapp.com',
+    to_email: data.customer_email,
+    subject: 'Payment Failed',
+    content: `Your payment of ${data.currency} ${data.amount / 100} could not be processed.`
+  });
+}
+```
+
+---
+
+## Cron Function (15min timeout)
+
+### Pattern: Scheduled Zoho-to-Datastore Sync
+
+```javascript
+'use strict';
+
+const catalyst = require('zcatalyst-sdk-node');
+const fetch = require('node-fetch');
+
+module.exports = async (cronDetails, context) => {
+  const app = catalyst.initialize(context);
+  const startTime = Date.now();
+  let syncedCount = 0;
+  let errorCount = 0;
+
+  try {
+    console.log(`Cron started: ${cronDetails.cron_name}`);
+
+    // Get last sync timestamp from Catalyst Cache
+    const cache = app.cache().segment('sync_state');
+    const lastSyncItem = await cache.getItem('zoho_contacts_last_sync')
+      .catch(() => null);
+    const lastSync = lastSyncItem
+      ? lastSyncItem.cache_value
+      : new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+
+    // Get Zoho access token from cache (refreshed by separate function)
+    const tokenItem = await cache.getItem('zoho_access_token');
+    if (!tokenItem) {
+      throw new Error('No Zoho access token in cache - run token refresh first');
+    }
+    const accessToken = tokenItem.cache_value;
+
+    // Fetch modified records from Zoho CRM (paginated)
+    let page = 1;
+    let hasMore = true;
+
+    while (hasMore) {
+      // Check if we're approaching the 15-minute timeout
+      if (Date.now() - startTime > 13 * 60 * 1000) {
+        console.log('Approaching timeout limit - stopping pagination');
+        break;
+      }
+
+      const response = await fetch(
+        `https://www.zohoapis.com/crm/v5/Contacts?modified_since=${lastSync}&page=${page}&per_page=200`,
+        { headers: { 'Authorization': `Zoho-oauthtoken ${accessToken}` } }
+      );
+
+      if (response.status === 204) {
+        hasMore = false;
+        continue;
+      }
+
+      if (!response.ok) {
+        throw new Error(`Zoho API error: ${response.status} ${await response.text()}`);
+      }
+
+      const data = await response.json();
+      const records = data.data || [];
+
+      // Batch insert into Catalyst Datastore
+      const table = app.datastore().table('CRM_Contacts');
+      for (const record of records) {
+        try {
+          await table.insertRow({
+            Zoho_ID: record.id,
+            Full_Name: `${record.First_Name || ''} ${record.Last_Name || ''}`.trim(),
+            Email: record.Email || '',
+            Phone: record.Phone || '',
+            Company: record.Account_Name?.name || '',
+            Modified_Time: record.Modified_Time,
+            Synced_At: new Date().toISOString()
+          });
+          syncedCount++;
+        } catch (insertError) {
+          // Record may already exist - try update
+          if (insertError.message.includes('already exists')) {
+            // Use ZCQL to find and update
+            const zcql = app.zcql();
+            const existing = await zcql.executeZCQLQuery(
+              `SELECT ROWID FROM CRM_Contacts WHERE Zoho_ID = '${record.id}'`
+            );
+            if (existing.length > 0) {
+              await table.updateRow({
+                ROWID: existing[0].CRM_Contacts.ROWID,
+                Full_Name: `${record.First_Name || ''} ${record.Last_Name || ''}`.trim(),
+                Email: record.Email || '',
+                Phone: record.Phone || '',
+                Modified_Time: record.Modified_Time,
+                Synced_At: new Date().toISOString()
+              });
+              syncedCount++;
+            }
+          } else {
+            errorCount++;
+            console.error(`Insert error for ${record.id}: ${insertError.message}`);
+          }
+        }
+      }
+
+      hasMore = data.info?.more_records || false;
+      page++;
+    }
+
+    // Update last sync timestamp
+    await cache.putItem('zoho_contacts_last_sync', new Date().toISOString());
+
+    console.log(`Cron complete: ${syncedCount} synced, ${errorCount} errors, ${Date.now() - startTime}ms`);
+  } catch (error) {
+    console.error(`Cron fatal error: ${error.message}`);
+    // Optionally notify admin via Catalyst Mail
+  } finally {
+    context.close(); // MANDATORY - always in finally block
+  }
+};
+```
+
+---
+
+## Event Function (15min timeout)
+
+### Pattern: Post-Insert Processing
+
+```javascript
+'use strict';
+
+const catalyst = require('zcatalyst-sdk-node');
+
+module.exports = async (eventData, context) => {
+  const app = catalyst.initialize(context);
+
+  try {
+    const { table_name, action, data } = eventData;
+    console.log(`Event: ${action} on ${table_name}`);
+
+    if (table_name === 'Orders' && action === 'INSERT') {
+      const order = data;
+
+      // Send order confirmation email
+      const mail = app.email();
+      await mail.sendMail({
+        from_email: 'orders@clientapp.com',
+        to_email: order.Customer_Email,
+        subject: `Order Confirmed #${order.ROWID}`,
+        content: `Your order of $${order.Amount} has been confirmed.`
+      });
+
+      // Update analytics counter in cache
+      const cache = app.cache().segment('analytics');
+      const countItem = await cache.getItem('daily_order_count').catch(() => null);
+      const currentCount = countItem ? parseInt(countItem.cache_value) : 0;
+      await cache.putItem('daily_order_count', String(currentCount + 1));
+    }
+  } catch (error) {
+    console.error(`Event processing error: ${error.message}`);
+  } finally {
+    context.close(); // MANDATORY - always in finally block
+  }
+};
+```
+
+---
+
+## AppSail Deployment (Long-Running)
+
+### Pattern: Express.js API Server
+
+```javascript
+'use strict';
+
+const express = require('express');
+const catalyst = require('zcatalyst-sdk-node');
+
+const app = express();
+app.use(express.json());
+
+// MUST bind to process.env.PORT (Catalyst requirement)
+const PORT = process.env.PORT || 9000;
+
+// Health check endpoint
+app.get('/health', (req, res) => {
+  res.json({ status: 'healthy', timestamp: new Date().toISOString() });
+});
+
+// CORS proxy for Creator Widgets (widgets can't call external APIs directly)
+app.post('/api/proxy', async (req, res) => {
+  const catalystApp = catalyst.initialize(req);
+
+  try {
+    const { url, method, headers, body } = req.body;
+
+    // Whitelist allowed domains
+    const allowedDomains = ['api.stripe.com', 'api.sendgrid.com'];
+    const requestUrl = new URL(url);
+    if (!allowedDomains.includes(requestUrl.hostname)) {
+      return res.status(403).json({ error: 'Domain not whitelisted' });
+    }
+
+    const response = await fetch(url, {
+      method: method || 'GET',
+      headers: headers || {},
+      body: body ? JSON.stringify(body) : undefined
+    });
+
+    const data = await response.json();
+    res.json({ status: response.status, data });
+  } catch (error) {
+    console.error('Proxy error:', error.message);
+    res.status(500).json({ error: error.message });
+  }
+});
+
+app.listen(PORT, () => {
+  console.log(`AppSail server running on port ${PORT}`);
+});
+```
+
+---
+
+## Catalyst Cache Usage
+
+```javascript
+// Cache has a 24-hour max TTL
+const cache = app.cache();
+const segment = cache.segment('my_segment');
+
+// Store value (expires in 24h max)
+await segment.putItem('key', 'value');
+
+// Retrieve value
+const item = await segment.getItem('key');
+const value = item.cache_value;
+
+// Delete value
+await segment.deleteItem('key');
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Consequence | Fix |
+|---------|-------------|-----|
+| Missing `context.close()` | Function hangs until timeout, wasted compute | Always use `finally { context.close(); }` |
+| Not binding to `process.env.PORT` | AppSail container fails to start | `app.listen(process.env.PORT)` |
+| Exceeding 30s in I/O function | Request timeout, 504 error | Move to Cron or Event function |
+| Synchronous file I/O | Blocks event loop, slow response | Use async `fs.promises` |
+| Not handling Catalyst SDK errors | Unhandled rejections crash function | Wrap all SDK calls in try-catch |
+| Storing secrets in code | Security vulnerability | Use Catalyst Cache or Vault |