gufi-cli 0.1.50 → 0.1.52

package/docs/dev-guide/3-02-webhooks-api.md

@@ -0,0 +1,446 @@
+---
+id: webhooks-api
+title: "Webhooks & External APIs"
+description: "Integrate Gufi with external systems"
+icon: Wifi
+category: dev
+part: 3
+---
+
+# Webhooks & External APIs
+
+Integrate Gufi with external systems
+
+## Table Webhooks
+
+Expose any entity as a REST API with token-based authentication.
+
+### Enabling Webhooks
+
+Add to entity configuration in module JSON:
+
+```json
+{
+  "name": "products",
+  "webhook": {
+    "enabled": true
+  },
+  "fields": [...]
+}
+```
+
+### Generating Tokens
+
+Once enabled, users with Admin or Consultant role see an "API" button. Clicking it generates a unique token for that entity.
+
+### Webhook Endpoints
+
+```
+Base URL: https://api.gogufi.com/api/webhook/e/{entityId}/{token}
+```
+
+#### List Records
+
+```http
+GET /webhook/e/4589/abc123token
+```
+
+**Query Parameters:**
+| Param | Description |
+|---|---|
+| page | Page number |
+| pageSize | Records per page |
+| sort | Sort field |
+| order | asc or desc |
+| filter | JSON filter object |
+
+**Response:**
+```json
+{
+  "data": [...],
+  "meta": { "total": 100, "page": 1 }
+}
+```
+
+#### Get Single Record
+
+```http
+GET /webhook/e/4589/abc123token/42
+```
+
+#### Create Record
+
+```http
+POST /webhook/e/4589/abc123token
+Content-Type: application/json
+
+{
+  "name": "New Product",
+  "price": { "currency": "EUR", "amount": 99.99 }
+}
+```
+
+#### Update Record
+
+```http
+PUT /webhook/e/4589/abc123token/42
+Content-Type: application/json
+
+{
+  "stock": 50
+}
+```
+
+#### Delete Record
+
+```http
+DELETE /webhook/e/4589/abc123token/42
+```
+
+### Security
+
+- Token is unique per entity per company
+- Regenerate token to revoke old access
+- Tokens never expire (regenerate to rotate)
+- HTTPS only
+- Rate limited (100 req/min)
+
+## API Keys
+
+For authenticated access without user login.
+
+### Creating API Keys
+
+```bash
+# Via CLI
+gufi apikeys -c 146
+gufi apikey:create "My Integration" -c 146
+
+# Via API (admin only)
+POST /api/keys
+{
+  "name": "My Integration",
+  "company_id": 146,
+  "permissions": ["read", "write"]
+}
+```
+
+### Using API Keys
+
+```http
+GET /api/tables/products
+Authorization: Bearer api_key_xxxxx
+X-Company-ID: 146
+```
+
+### Key Permissions
+
+| Permission | Access |
+|---|---|
+| read | GET operations |
+| write | POST, PUT operations |
+| delete | DELETE operations |
+| admin | All operations |
+
+## Outbound Webhooks
+
+Send data to external systems when events occur.
+
+### Via Automations
+
+```javascript
+async function send_to_webhook(gufi) {
+  const { row, env } = gufi.context;
+
+  await gufi.http({
+    method: 'POST',
+    url: env.WEBHOOK_URL,
+    headers: {
+      'Authorization': 'Bearer ' + env.WEBHOOK_SECRET,
+      'Content-Type': 'application/json'
+    },
+    body: {
+      event: 'order.created',
+      data: row,
+      timestamp: new Date().toISOString()
+    }
+  });
+
+  gufi.logger.info('Webhook sent', { orderId: row.id });
+  return { success: true };
+}
+```
+
+### Attach to Entity
+
+```json
+{
+  "trigger": "insert",
+  "function_name": "send_to_webhook",
+  "enabled": true
+}
+```
+
+## External API Integration
+
+### From Automations
+
+```javascript
+async function sync_to_erp(gufi) {
+  const { row, env } = gufi.context;
+
+  try {
+    // Authenticate with external API
+    const authResponse = await gufi.http({
+      method: 'POST',
+      url: env.ERP_URL + '/auth/token',
+      body: {
+        client_id: env.ERP_CLIENT_ID,
+        client_secret: env.ERP_CLIENT_SECRET
+      }
+    });
+
+    const token = authResponse.body.access_token;
+
+    // Send data
+    const response = await gufi.http({
+      method: 'POST',
+      url: env.ERP_URL + '/orders',
+      headers: {
+        'Authorization': 'Bearer ' + token
+      },
+      body: {
+        external_id: row.id,
+        customer: row.customer_name,
+        total: row.total.amount
+      }
+    });
+
+    gufi.logger.info('Synced to ERP', {
+      gufiId: row.id,
+      erpId: response.body.id
+    });
+
+    return { success: true, erpId: response.body.id };
+
+  } catch (error) {
+    gufi.logger.error('ERP sync failed', { error: error.message });
+    throw error;
+  }
+}
+```
+
+### From Custom Views
+
+```typescript
+// In a custom view component
+const syncToExternal = async () => {
+  // 💜 Usar gufi.automation() - Simple y directo
+  const result = await gufi.automation('sync_to_external', {
+    record_id: selectedRecord.id
+  });
+
+  utils.toastSuccess('Sync completed');
+};
+```
+
+## Common Integration Patterns
+
+### Zapier-Style Triggers
+
+```javascript
+// Send to Zapier catch hook
+async function zapier_trigger(gufi) {
+  const { row, env } = gufi.context;
+
+  await gufi.http({
+    method: 'POST',
+    url: env.ZAPIER_WEBHOOK_URL,
+    body: row
+  });
+
+  return { success: true };
+}
+```
+
+### Slack Notifications
+
+```javascript
+async function notify_slack(gufi) {
+  const { row, env } = gufi.context;
+
+  await gufi.http({
+    method: 'POST',
+    url: env.SLACK_WEBHOOK_URL,
+    body: {
+      text: `New order #${row.id} from ${row.customer}`,
+      blocks: [
+        {
+          type: 'section',
+          text: {
+            type: 'mrkdwn',
+            text: `*New Order*\nCustomer: ${row.customer}\nTotal: €${row.total.amount}`
+          }
+        }
+      ]
+    }
+  });
+
+  return { success: true };
+}
+```
+
+### Two-Way Sync
+
+```javascript
+// Pull data from external system
+async function sync_from_external(gufi) {
+  const { env } = gufi.context;
+
+  // Get external data
+  const response = await gufi.http({
+    method: 'GET',
+    url: env.EXTERNAL_API + '/products',
+    headers: { 'Authorization': 'Bearer ' + env.EXTERNAL_KEY }
+  });
+
+  const externalProducts = response.body.data;
+
+  for (const product of externalProducts) {
+    // Check if exists
+    const existing = await gufi.query(
+      'SELECT id FROM products WHERE external_id = $1',
+      [product.id]
+    );
+
+    if (existing.length > 0) {
+      // Update
+      await gufi.query(
+        'UPDATE products SET name = $1, price = $2 WHERE external_id = $3',
+        [product.name, product.price, product.id]
+      );
+    } else {
+      // Insert
+      await gufi.query(
+        'INSERT INTO products (external_id, name, price) VALUES ($1, $2, $3)',
+        [product.id, product.name, product.price]
+      );
+    }
+  }
+
+  gufi.logger.info('Sync complete', { count: externalProducts.length });
+  return { success: true, synced: externalProducts.length };
+}
+```
+
+## Best Practices
+
+### Error Handling
+
+```javascript
+async function robust_webhook(gufi) {
+  const maxRetries = 3;
+  let lastError;
+
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const response = await gufi.http({
+        method: 'POST',
+        url: context.env.WEBHOOK_URL,
+        body: context.row,
+        timeout: 10000  // 10 second timeout
+      });
+
+      if (response.status >= 200 && response.status < 300) {
+        return { success: true };
+      }
+
+      throw new Error(`HTTP ${response.status}`);
+
+    } catch (error) {
+      lastError = error;
+      gufi.logger.warn(`Attempt ${i + 1} failed`, { error: error.message });
+
+      // Wait before retry (exponential backoff)
+      await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
+    }
+  }
+
+  throw lastError;
+}
+```
+
+### Rate Limiting
+
+```javascript
+// For bulk operations, add delays
+async function bulk_sync(gufi) {
+  const items = await gufi.query('SELECT * FROM products');
+
+  for (let i = 0; i < items.length; i++) {
+    await gufi.http({
+      method: 'POST',
+      url: context.env.EXTERNAL_API,
+      body: items[i]
+    });
+
+    // Respect rate limits
+    if (i % 10 === 0 && i > 0) {
+      await new Promise(r => setTimeout(r, 1000));
+      gufi.logger.info(`Processed ${i} items`);
+    }
+  }
+
+  return { success: true, count: items.length };
+}
+```
+
+### Idempotency
+
+```javascript
+// Use idempotency keys for safe retries
+async function safe_create(gufi) {
+  const { row } = gufi.context;
+  const idempotencyKey = `order-${row.id}-${Date.now()}`;
+
+  await gufi.http({
+    method: 'POST',
+    url: context.env.PAYMENT_API + '/charges',
+    headers: {
+      'Idempotency-Key': idempotencyKey
+    },
+    body: {
+      amount: row.total.amount * 100,
+      currency: row.total.currency
+    }
+  });
+
+  return { success: true };
+}
+```
+
+## Monitoring
+
+### Execution Logs
+
+```bash
+# View recent webhook calls
+gufi automations:executions -c 146 --script send_to_webhook --limit 20
+```
+
+### Success/Failure Metrics
+
+Check the Gufi dashboard for:
+
+- Execution success rate
+- Average execution time
+- Error trends
+- External API response times
+
+### Alerting
+
+Set up alerts for:
+
+- High failure rates (>10%)
+- Slow external APIs (>5s)
+- Authentication failures