gufi-cli 0.1.49 → 0.1.51

package/docs/dev-guide/2-02-automations.md

@@ -0,0 +1,508 @@
+---
+id: automations
+title: "Automations System"
+description: "Automate business logic with scripts"
+icon: Zap
+category: dev
+part: 2
+---
+
+# Automations System
+
+Automate business logic with scripts
+
+## Overview
+
+Gufi's automation system lets you run JavaScript code in response to events. Automations can:
+
+- Send emails and notifications
+- Update records across entities
+- Call external APIs
+- Perform calculations
+- Enforce business rules
+
+## Architecture
+
+### Components
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  Automation System                       │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐ │
+│  │   Trigger   │───▶│    Queue    │───▶│   Worker    │ │
+│  │   Events    │    │  (pg-boss)  │    │   (Node)    │ │
+│  └─────────────┘    └─────────────┘    └─────────────┘ │
+│         │                                     │        │
+│         │                                     │        │
+│         ▼                                     ▼        │
+│  ┌─────────────────────────────────────────────────┐  │
+│  │           core.automation_scripts               │  │
+│  │              (JavaScript code)                  │  │
+│  └─────────────────────────────────────────────────┘  │
+│                         │                             │
+│                         ▼                             │
+│  ┌─────────────────────────────────────────────────┐  │
+│  │           core.automation_executions            │  │
+│  │              (execution history)                │  │
+│  └─────────────────────────────────────────────────┘  │
+│                                                       │
+└───────────────────────────────────────────────────────┘
+```
+
+### Data Model
+
+**core.automation_scripts** - The code
+
+```sql
+id, company_id, name, code, created_at, updated_at
+```
+
+**core.entities.automations** - Triggers per entity (JSONB column)
+
+```json
+[
+  {
+    "trigger": "insert",
+    "function_name": "send_welcome_email",
+    "script_id": 42,
+    "label": "Send Welcome Email",
+    "enabled": true
+  }
+]
+```
+
+**core.automation_meta** - Worker index (synced from entities.automations)
+
+**core.automation_executions** - Execution log
+
+## Trigger Types
+
+### insert
+
+Fires when a new record is created.
+
+```json
+{
+  "trigger": "insert",
+  "function_name": "on_order_created"
+}
+```
+
+**Context available:**
+- `row` - The new record
+- `old_row` - null
+
+### update
+
+Fires when a record is modified.
+
+```json
+{
+  "trigger": "update",
+  "function_name": "on_status_change"
+}
+```
+
+**Context available:**
+- `row` - The updated record
+- `old_row` - Previous values
+
+### delete
+
+Fires when a record is deleted.
+
+```json
+{
+  "trigger": "delete",
+  "function_name": "on_customer_deleted"
+}
+```
+
+**Context available:**
+- `row` - The deleted record
+- `old_row` - Same as row
+
+### click
+
+Manual button trigger (user clicks).
+
+```json
+{
+  "trigger": "click",
+  "function_name": "send_invoice",
+  "label": "Send Invoice"
+}
+```
+
+Requires `label` for the UI button.
+
+### scheduled
+
+Cron-based scheduling.
+
+```json
+{
+  "trigger": "scheduled",
+  "function_name": "daily_report",
+  "cron_pattern": "0 8 * * *"
+}
+```
+
+Cron patterns: `minute hour day month weekday`
+
+## Writing Automation Scripts
+
+### Basic Structure
+
+```javascript
+async function my_automation(gufi) {
+  // Your code here
+
+  return { success: true };
+}
+```
+
+### Context Object
+
+```javascript
+const {
+  company_id,     // Company ID
+  module_id,      // Module ID
+  entity_id,      // Entity ID
+  table,          // Physical table name
+  row,            // Current record data
+  old_row,        // Previous data (update only)
+  input,          // Custom input (click trigger)
+  env             // Environment variables
+} = context;
+```
+
+### API Object
+
+The `api` object provides:
+
+#### Query Database
+
+```javascript
+// IMPORTANT: api.query returns rows directly, NOT { rows }
+const customers = await gufi.query(
+  "SELECT * FROM customers WHERE status = $1",
+  ["active"]
+);
+
+// Access results directly
+if (customers.length === 0) {
+  throw new Error("No customers found");
+}
+const firstCustomer = customers[0];
+```
+
+#### Send Email
+
+```javascript
+await gufi.integrations.notifications.email({
+  to: "customer@example.com",
+  subject: "Order Confirmation",
+  body: "Your order has been confirmed.",
+  html: "<h1>Order Confirmed</h1><p>Thank you!</p>"
+});
+```
+
+#### HTTP Requests
+
+```javascript
+const response = await gufi.http({
+  method: "POST",
+  url: "https://external-api.com/webhook",
+  headers: {
+    "Authorization": "Bearer " + context.env.API_KEY
+  },
+  body: { order_id: context.row.id }
+});
+```
+
+### Logger Object
+
+```javascript
+logger.info("Processing order", { orderId: row.id });
+logger.warn("Low stock detected");
+logger.error("Failed to send email", { error: err.message });
+```
+
+Logs appear in execution history.
+
+## Complete Examples
+
+### Send Email on Order
+
+```javascript
+async function send_order_confirmation(gufi) {
+  const { row, env } = gufi.context;
+
+  gufi.logger.info("Sending order confirmation", { orderId: row.id });
+
+  // Get customer details
+  const customers = await gufi.query(
+    "SELECT * FROM customers WHERE id = $1",
+    [row.customer_id]
+  );
+
+  if (customers.length === 0) {
+    throw new Error("Customer not found");
+  }
+
+  const customer = customers[0];
+
+  // Send email
+  await gufi.integrations.notifications.email({
+    to: customer.email,
+    subject: `Order #${row.id} Confirmed`,
+    html: `
+      <h1>Thank you for your order!</h1>
+      <p>Order #${row.id} has been confirmed.</p>
+      <p>Total: ${row.total.currency} ${row.total.amount}</p>
+    `
+  });
+
+  gufi.logger.info("Email sent successfully");
+
+  return { success: true, emailSent: true };
+}
+```
+
+### Update Inventory on Sale
+
+```javascript
+async function update_stock_on_sale(gufi) {
+  const { row } = gufi.context;
+
+  // Get order items
+  const items = await gufi.query(
+    "SELECT * FROM order_items WHERE order_id = $1",
+    [row.id]
+  );
+
+  // Update each product's stock
+  for (const item of items) {
+    await gufi.query(
+      "UPDATE products SET stock = stock - $1 WHERE id = $2",
+      [item.quantity, item.product_id]
+    );
+
+    gufi.logger.info("Updated stock", {
+      productId: item.product_id,
+      quantity: item.quantity
+    });
+  }
+
+  return { success: true, itemsUpdated: items.length };
+}
+```
+
+### Call External API
+
+```javascript
+async function sync_to_external_system(gufi) {
+  const { row, env } = gufi.context;
+
+  try {
+    const response = await gufi.http({
+      method: "POST",
+      url: env.EXTERNAL_API_URL + "/customers",
+      headers: {
+        "Authorization": "Bearer " + env.EXTERNAL_API_KEY,
+        "Content-Type": "application/json"
+      },
+      body: {
+        external_id: row.id,
+        name: row.name,
+        email: row.email
+      }
+    });
+
+    gufi.logger.info("Synced to external system", {
+      externalId: response.body.id
+    });
+
+    return { success: true, externalId: response.body.id };
+
+  } catch (error) {
+    gufi.logger.error("Sync failed", { error: error.message });
+    throw error;
+  }
+}
+```
+
+### Scheduled Daily Report
+
+```javascript
+async function daily_sales_report(gufi) {
+  const { env } = gufi.context;
+
+  // Get yesterday's sales
+  const sales = await gufi.query(`
+    SELECT
+      COUNT(*) as count,
+      SUM((total->>'amount')::numeric) as total
+    FROM orders
+    WHERE created_at >= CURRENT_DATE - INTERVAL '1 day'
+      AND created_at < CURRENT_DATE
+  `);
+
+  const report = sales[0];
+
+  // Send report email
+  await gufi.integrations.notifications.email({
+    to: env.REPORT_EMAIL,
+    subject: "Daily Sales Report",
+    html: `
+      <h1>Daily Sales Report</h1>
+      <p>Orders: ${report.count}</p>
+      <p>Total Revenue: €${report.total || 0}</p>
+    `
+  });
+
+  gufi.logger.info("Report sent", report);
+
+  return { success: true, ...report };
+}
+```
+
+## Managing Automations
+
+### CLI Commands
+
+```bash
+# List scripts
+gufi automations -c 146
+
+# View script code
+gufi automation 42
+
+# Edit script
+gufi automation 42 --edit
+
+# Create script
+gufi automation:create send_email script.js -c 146
+
+# View entity triggers
+gufi entity:automations 4589
+
+# Edit triggers
+gufi entity:automations 4589 --edit
+
+# View execution history
+gufi automations:executions -c 146 --limit 50
+
+# Filter by script
+gufi automations:executions -c 146 --script send_email
+```
+
+### API Endpoints
+
+```http
+# List scripts
+GET /automations/scripts?company_id=146
+
+# Create/update script
+POST /automations/scripts
+{ "company_id": 146, "name": "my_script", "code": "..." }
+
+# Get entity automations
+GET /entities/:entityId/automations
+
+# Update entity automations
+PUT /entities/:entityId/automations
+[{ "trigger": "insert", "function_name": "my_script" }]
+
+# Run click automation
+POST /automations/click
+{ "company_id": 146, "table_id": 4589, "function_name": "send_email", "input": {...} }
+```
+
+## Environment Variables
+
+Store secrets and configuration:
+
+```bash
+# Set variable
+gufi env:set SMTP_HOST smtp.gmail.com
+gufi env:set API_KEY sk_live_xxxxx
+
+# Access in automation
+const { env } = gufi.context;
+const apiKey = env.API_KEY;
+```
+
+## Error Handling
+
+### Best Practices
+
+```javascript
+async function robust_automation(gufi) {
+  try {
+    // Main logic
+    const result = await gufi.query("...");
+
+    if (!result.length) {
+      gufi.logger.warn("No data found, skipping");
+      return { success: true, skipped: true };
+    }
+
+    // Continue processing...
+
+  } catch (error) {
+    gufi.logger.error("Automation failed", {
+      error: error.message,
+      stack: error.stack
+    });
+
+    // Re-throw to mark execution as failed
+    throw error;
+  }
+}
+```
+
+### Retry Configuration
+
+Failed automations retry automatically:
+
+| Attempt | Delay |
+|---|---|
+| 1 | Immediate |
+| 2 | 1 minute |
+| 3 | 5 minutes |
+| 4 | 30 minutes |
+| 5 | Failed permanently |
+
+## Security
+
+### Sandboxed Execution
+
+Automations run in isolated-vm:
+
+- No filesystem access
+- No require/import
+- Limited memory (128MB)
+- Timeout (30 seconds)
+
+### What's Available
+
+| Available | Not Available |
+|---|---|
+| api.query | require() |
+| api.email | import |
+| api.http | fs, path |
+| logger | process |
+| context | child_process |
+| JSON, Date, Math | eval |
+
+### Data Access
+
+Automations can only access:
+
+- Data within the same company
+- Tables the trigger is attached to
+- Environment variables set for that company