gufi-cli 0.1.49 → 0.1.51

package/docs/mcp/05-automations.md

@@ -0,0 +1,461 @@
+# Automations
+
+Las automations son **funciones JavaScript** que se ejecutan en respuesta a eventos en la base de datos.
+
+## Arquitectura
+
+```
+1. Evento en tabla (INSERT/UPDATE/DELETE)
+      |
+      v
+2. PostgreSQL NOTIFY --> pg-boss queue
+      |
+      v
+3. Worker ejecuta runAutomation()
+      |
+      v
+4. Resultado en __automation_executions__
+```
+
+## Tipos de triggers
+
+| Trigger | Cuando se ejecuta | Contexto disponible |
+|---------|-------------------|---------------------|
+| `INSERT` | Al crear registro | `row` |
+| `UPDATE` | Al modificar registro | `row`, `old_row` |
+| `DELETE` | Al eliminar registro | `old_row` |
+| `CLICK` | Botón manual en tabla | `row`, `input` |
+| `SCHEDULED` | Cron job | Solo `context` |
+
+---
+
+## 💜 Nueva Firma: Un Solo Objeto `gufi`
+
+```javascript
+/**
+ * @param {Object} gufi - Objeto único con todo lo necesario
+ */
+async function mi_automation(gufi) {
+  // 💜 Contexto: row, env, input, etc.
+  const { row, old_row, input, env, event, table } = gufi.context;
+
+  // 💜 Logging
+  gufi.logger.info('Procesando...', { id: row?.id });
+
+  // 💜 Database
+  const rows = await gufi.query('SELECT * FROM ventas.productos WHERE activo = $1', [true]);
+  await gufi.insert('ventas.pedidos', { cliente_id: 123, total: 500 });
+  await gufi.update('ventas.pedidos', { id: row.id, status: 'paid' });
+
+  // 💜 Integraciones
+  await gufi.integrations.stripe.createCheckoutSession({ ... });
+  await gufi.integrations.notifications.email({ ... });
+
+  return { success: true, message: 'OK' };
+}
+```
+
+### Qué contiene `gufi`:
+
+| Propiedad | Descripción |
+|-----------|-------------|
+| `gufi.context` | row, old_row, env, input, company_id, event, table |
+| `gufi.logger` | info, warn, error, debug (console con prefijo) |
+| `gufi.query()` | Consultas SQL (devuelve rows directamente) |
+| `gufi.insert()` | Insertar registro |
+| `gufi.update()` | Actualizar registro |
+| `gufi.remove()` | Eliminar registro |
+| `gufi.findOne()` | Buscar un registro |
+| `gufi.findWithFilters()` | Buscar con filtros |
+| `gufi.bulkInsert()` | Insert masivo |
+| `gufi.bulkUpdate()` | Update masivo |
+| `gufi.bulkDelete()` | Delete masivo |
+| `gufi.resolveTable()` | Resolver nombre lógico → físico |
+| `gufi.http()` | Peticiones HTTP |
+| `gufi.integrations.*` | Integraciones (stripe, nayax, notifications, documents) |
+
+---
+
+## Context (`gufi.context`)
+
+```javascript
+const {
+  company_id,      // ID de la company
+  module_id,       // ID del módulo
+  entity_id,       // ID de la entidad
+  table,           // Nombre físico (m308_t4136)
+  row,             // Registro actual (insert/update/click)
+  old_row,         // Registro anterior (update/delete)
+  input,           // Input del usuario (solo click)
+  env,             // Variables de entorno { EMAIL_USER: "xxx", ... }
+  event            // Tipo: INSERT, UPDATE, DELETE, CLICK, SCHEDULED
+} = gufi.context;
+```
+
+---
+
+## ⚠️ IMPORTANTE: Usar Nombres Lógicos, NO IDs
+
+**NUNCA uses IDs hardcodeados** - rompen entre entornos (DEV vs PROD tienen IDs diferentes).
+
+### ❌ MAL - IDs hardcodeados
+
+```javascript
+if (entity_id === 7140) { ... }  // ID solo válido en DEV
+await gufi.insert('m310_t4146', { ... });  // ID físico solo válido en DEV
+```
+
+### ✅ BIEN - Nombres lógicos
+
+```javascript
+// Usar context.table para detectar la entidad
+if (gufi.context.table?.includes('supplier_orders')) { ... }
+
+// Usar nombres lógicos para operaciones
+await gufi.insert('stock.stock_transactions', { ... });
+```
+
+---
+
+## CRUD Básico
+
+### gufi.query() - Consultas SQL
+
+**Devuelve rows directamente (NO destructuring)**
+
+```javascript
+// ✅ CORRECTO
+const rows = await gufi.query("SELECT * FROM ventas.productos WHERE id = $1", [id]);
+const firstRow = rows[0];
+
+// ❌ INCORRECTO - NO FUNCIONA
+const { rows } = await gufi.query(...);  // ERROR!
+```
+
+**Parametrización segura:**
+```javascript
+// ✅ CORRECTO - parámetros separados
+const rows = await gufi.query(
+  "SELECT * FROM ventas.productos WHERE estado = $1 AND total > $2",
+  ['activo', 1000]
+);
+
+// ❌ INCORRECTO - SQL injection!
+const rows = await gufi.query(`SELECT * FROM tabla WHERE estado = '${estado}'`);
+```
+
+### gufi.insert() - Crear registro
+
+```javascript
+await gufi.insert('ventas.productos', {
+  nombre: 'Nuevo producto',
+  precio: 150,
+  estado: 'activo'
+});
+```
+
+### gufi.update() - Actualizar registro
+
+```javascript
+await gufi.update('ventas.productos', {
+  id: row.id,  // REQUERIDO
+  estado: 'procesado',
+  estado__display: 'Procesado'  // Para select/relation
+});
+```
+
+### gufi.remove() - Eliminar registro
+
+```javascript
+await gufi.remove('ventas.productos', row.id);
+```
+
+### gufi.findOne() - Buscar un registro
+
+```javascript
+const cliente = await gufi.findOne('ventas.clientes', 'email', 'juan@test.com');
+if (cliente) {
+  gufi.logger.info('Cliente encontrado:', cliente.nombre);
+}
+```
+
+### gufi.findWithFilters() - Buscar con filtros
+
+```javascript
+const rows = await gufi.findWithFilters('ventas.productos', [
+  { field: 'estado', operator: 'eq', value: 'activo' },
+  { field: 'precio', operator: '>', value: 100 }
+], {
+  order: [{ field: 'created_at', order: 'DESC' }],
+  limit: 10
+});
+```
+
+---
+
+## Bulk Operations
+
+Para operaciones masivas SIN disparar automations individuales:
+
+```javascript
+// Insert múltiple
+const result = await gufi.bulkInsert('ventas.productos', [
+  { nombre: 'Producto 1', precio: 100 },
+  { nombre: 'Producto 2', precio: 200 }
+]);
+// Returns: { insertedIds: [1, 2], count: 2 }
+
+// Update múltiple
+await gufi.bulkUpdate('ventas.productos', [1, 2, 3], { estado: 'procesado' });
+
+// Delete múltiple
+await gufi.bulkDelete('ventas.productos', [1, 2, 3]);
+```
+
+---
+
+## Integraciones (`gufi.integrations`)
+
+Acceso a servicios externos. **Credenciales siempre desde `gufi.context.env`**.
+
+### Email
+
+```javascript
+const { env } = gufi.context;
+
+await gufi.integrations.notifications.email({
+  to: 'usuario@ejemplo.com',
+  subject: 'Asunto',
+  html: '<h1>Hola</h1>',
+  cc: 'copia@ejemplo.com',
+  attachments: [{ filename: 'doc.pdf', content: pdfBuffer }],
+  // 💜 Credenciales desde env
+  user: env.EMAIL_USER,
+  pass: env.EMAIL_PASS,
+  from: env.EMAIL_FROM
+});
+```
+
+### PDF
+
+```javascript
+const { pdf, size } = await gufi.integrations.documents.pdf({
+  html: '<h1>Reporte</h1><p>Contenido</p>',
+  format: 'A4'
+});
+// pdf es un Buffer
+```
+
+### Stripe
+
+```javascript
+const result = await gufi.integrations.stripe.createCheckoutSession({
+  secretKey: env.STRIPE_SECRET_KEY,
+  lineItems: [{ name: 'Producto', amount: 1999, quantity: 1 }],
+  successUrl: `${env.FRONTEND_URL}/success`,
+  cancelUrl: `${env.FRONTEND_URL}/cancel`
+});
+// result.url es la URL de checkout
+```
+
+### Telegram
+
+```javascript
+await gufi.integrations.notifications.telegram({
+  botToken: env.TELEGRAM_BOT_TOKEN,
+  chatId: env.TELEGRAM_CHAT_ID,
+  message: '🚨 *Alerta*: Nueva venta',
+  parseMode: 'Markdown'
+});
+```
+
+### HTTP (APIs externas)
+
+```javascript
+const response = await gufi.http(env.WEBHOOK_URL, {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${env.API_TOKEN}`
+  },
+  body: JSON.stringify({ data: row })
+});
+
+const data = await response.json();
+```
+
+---
+
+## Integraciones Disponibles
+
+| Integración | Métodos | Categoría |
+|-------------|---------|-----------|
+| `gufi.integrations.stripe` | `createCheckoutSession` | Pagos |
+| `gufi.integrations.notifications` | `email`, `emailWrapped`, `telegram` | Notificaciones |
+| `gufi.integrations.documents` | `pdf`, `invoice` | Documentos |
+| `gufi.integrations.nayax` | `sync_machines`, `sync_products`, `sync_sales`, etc. | Vending |
+| `gufi.integrations.seur` | `createShipment`, `getTracking`, `cancelShipment` | Envíos |
+
+---
+
+## Variables de entorno
+
+Cada company tiene variables privadas en `gufi.context.env`:
+
+```javascript
+const { env } = gufi.context;
+
+const apiKey = env.STRIPE_API_KEY;
+const webhookUrl = env.SLACK_WEBHOOK;
+const emailAdmin = env.ADMIN_EMAIL;
+```
+
+**Gestionar con MCP:**
+```javascript
+gufi_env({ action: "list", company_id: "116" })
+gufi_env({ action: "set", company_id: "116", key: "API_KEY", value: "xxx" })
+gufi_env({ action: "delete", company_id: "116", key: "OLD_KEY" })
+```
+
+---
+
+## Ejemplos Completos
+
+### Email con PDF adjunto
+
+```javascript
+async function enviar_factura(gufi) {
+  const { row, env } = gufi.context;
+
+  // Generar PDF
+  const { pdf } = await gufi.integrations.documents.pdf({
+    html: `<h1>Factura #${row.id}</h1><p>Total: ${row.total} EUR</p>`
+  });
+
+  // Enviar email
+  await gufi.integrations.notifications.email({
+    to: row.cliente_email,
+    subject: `Factura #${row.id}`,
+    html: '<p>Adjuntamos su factura.</p>',
+    attachments: [{ filename: `factura-${row.id}.pdf`, content: pdf }],
+    user: env.EMAIL_USER,
+    pass: env.EMAIL_PASS,
+    from: env.EMAIL_FROM
+  });
+
+  // Marcar como enviada
+  await gufi.update(gufi.context.table, {
+    id: row.id,
+    factura_enviada: true
+  });
+
+  return { success: true };
+}
+```
+
+### Sync con API externa
+
+```javascript
+async function sync_to_crm(gufi) {
+  const { row, old_row, event, env } = gufi.context;
+
+  // Solo sync si cambió el email
+  if (event === 'UPDATE' && row.email === old_row?.email) {
+    return { skipped: true };
+  }
+
+  const response = await gufi.http(`${env.CRM_URL}/api/contacts`, {
+    method: row.crm_id ? 'PUT' : 'POST',
+    headers: {
+      'Authorization': `Bearer ${env.CRM_TOKEN}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      id: row.crm_id,
+      email: row.email,
+      name: row.nombre
+    })
+  });
+
+  if (!response.ok) {
+    throw new Error(`CRM error: ${response.status}`);
+  }
+
+  const data = await response.json();
+
+  // Guardar ID del CRM si es nuevo
+  if (!row.crm_id && data.id) {
+    await gufi.update(gufi.context.table, {
+      id: row.id,
+      crm_id: data.id
+    });
+  }
+
+  return { success: true, crm_id: data.id };
+}
+```
+
+---
+
+## Operaciones con MCP
+
+### Listar scripts
+
+```javascript
+gufi_automation_scripts({ action: "list", company_id: "116" })
+```
+
+### Ver código
+
+```javascript
+gufi_automation_scripts({ action: "get", company_id: "116", id: "15" })
+```
+
+### Crear script
+
+```javascript
+gufi_automation_scripts({
+  action: "create",
+  company_id: "116",
+  name: "mi_automation",
+  code: "async function mi_automation(gufi) { ... }"
+})
+```
+
+### Configurar triggers
+
+```javascript
+gufi_automation_meta({
+  entity_id: "4136",
+  company_id: "116",
+  automations: [
+    { trigger: "insert", function_name: "notificar_nuevo" },
+    { trigger: "update", function_name: "sync_cambios" }
+  ]
+})
+```
+
+### Ver ejecuciones
+
+```javascript
+gufi_automation_executions({
+  company_id: "116",
+  script_name: "mi_automation",
+  limit: 20
+})
+```
+
+---
+
+## Debugging
+
+```javascript
+gufi.logger.info('Procesando', { id: row.id });
+gufi.logger.warn('Advertencia', { campo: row.estado });
+gufi.logger.error('Error', { err: error.message });
+
+// También funciona console.*
+console.log('Debug:', row);
+```
+
+Ver ejecuciones con `gufi_automation_executions()` para ver status, duración y errores.