gufi-cli 0.1.50 → 0.1.52

package/docs/mcp/06-api.md

@@ -0,0 +1,480 @@
+# API Reference
+
+Endpoints principales del backend de Gufi.
+
+## Autenticacion
+
+### Login
+
+```
+POST /api/auth/login
+{
+  "email": "user@example.com",
+  "password": "password123"
+}
+
+Response:
+{
+  "accessToken": "eyJ...",
+  "refreshToken": "abc...",
+  "user": { "id": 16, "email": "...", "name": "..." }
+}
+```
+
+### Refresh token
+
+```
+POST /api/auth/refresh
+Headers:
+  X-Refresh-Token: {refreshToken}
+
+Response:
+{
+  "accessToken": "eyJ...",
+  "refreshToken": "abc..."
+}
+```
+
+### Headers requeridos
+
+```
+Authorization: Bearer {accessToken}
+X-Company-ID: {companyId}
+Content-Type: application/json
+```
+
+## Companies
+
+### Listar companies
+
+```
+GET /api/companies
+
+Response:
+{
+  "items": [
+    { "id": 116, "name": "Mi Empresa", "created_at": "..." }
+  ]
+}
+```
+
+### Schema de company
+
+```
+GET /api/company/schema
+
+Response:
+{
+  "modules": [
+    {
+      "id": 360,
+      "name": "Ventas",
+      "submodules": [...]
+    }
+  ]
+}
+```
+
+## Modules
+
+### Listar modulos
+
+```
+GET /api/company/modules
+
+Response:
+[
+  { "id": 360, "name": "ventas", "displayName": "Ventas", "entity_count": 3 }
+]
+```
+
+### Obtener modulo
+
+```
+GET /api/company/modules/{moduleId}
+
+Response:
+{
+  "id": 360,
+  "name": "ventas",
+  "json_definition": {...}
+}
+```
+
+### Actualizar modulo
+
+```
+PUT /api/company/modules/{moduleId}
+{
+  "json_definition": {...}
+}
+```
+
+### Crear modulo
+
+```
+POST /api/company/modules
+{
+  "json_definition": {...}
+}
+```
+
+## Tables (CRUD generico)
+
+### Listar registros
+
+```
+POST /api/tables/{tableName}/list
+{
+  "page": 1,
+  "perPage": 20,
+  "sorters": [{ "field": "created_at", "order": "desc" }],
+  "filter": [
+    { "field": "estado", "operator": "eq", "value": "pendiente" }
+  ]
+}
+
+Response:
+{
+  "data": [...],
+  "meta": { "page": 1, "perPage": 20, "hasMore": true }
+}
+```
+
+> **IMPORTANTE**: La paginacion usa `page` y `perPage` directamente en el body,
+> NO `pagination: { current, pageSize }`. Usar el formato incorrecto hace que
+> la API ignore la paginacion y siempre devuelva la primera pagina.
+
+### Obtener registro
+
+```
+POST /api/tables/{tableName}/getOne
+{
+  "id": 123
+}
+
+Response:
+{
+  "data": { "id": 123, "nombre": "...", ... }
+}
+```
+
+### Crear registro
+
+```
+POST /api/tables/{tableName}
+{
+  "nombre": "Nuevo",
+  "precio": 150,
+  "estado": "pendiente"
+}
+
+Response (objeto directamente, NO envuelto en data):
+{ "id": 124, "nombre": "Nuevo", "precio": 150, ... }
+```
+
+> **IMPORTANTE**: El endpoint de crear devuelve el objeto directamente,
+> NO envuelto en `{ data: {...} }`. Verificar con `'id' in response`, no `'data' in response`.
+
+### Actualizar registro
+
+```
+PUT /api/tables/{tableName}/{id}
+{
+  "estado": "completado",
+  "estado__display": "Completado"
+}
+```
+
+### Eliminar registro
+
+```
+DELETE /api/tables/{tableName}/{id}
+```
+
+### Eliminar multiples
+
+```
+POST /api/tables/{tableName}/deleteMany
+{
+  "ids": [1, 2, 3]
+}
+```
+
+## Agregaciones (Analytics)
+
+Usar `gufi_data` con `action: 'aggregate'` para métricas y agregaciones.
+
+### Count total
+
+```javascript
+gufi_data({
+  action: 'aggregate',
+  table: 'ventas.pedidos',
+  agg: 'count',
+  company_id: '146'
+})
+
+// Response: { value: 1250 }
+```
+
+### Sum, Avg, Min, Max
+
+```javascript
+// Suma total de ventas
+gufi_data({
+  action: 'aggregate',
+  table: 'ventas.pedidos',
+  agg: 'sum',
+  field: 'total',
+  company_id: '146'
+})
+
+// Precio promedio
+gufi_data({
+  action: 'aggregate',
+  table: 'ventas.productos',
+  agg: 'avg',
+  field: 'precio',
+  company_id: '146'
+})
+```
+
+### Group By
+
+```javascript
+// Ventas por cliente
+gufi_data({
+  action: 'aggregate',
+  table: 'ventas.pedidos',
+  agg: 'sum',
+  field: 'total',
+  groupBy: 'cliente_id',
+  limit: 10,
+  company_id: '146'
+})
+
+// Response:
+// { results: [
+//   { group: 'cliente_123', value: 15000 },
+//   { group: 'cliente_456', value: 12500 },
+//   ...
+// ]}
+```
+
+### Con filtros simples
+
+```javascript
+// Filtrar por campo = valor
+gufi_data({
+  action: 'aggregate',
+  table: 'ventas.pedidos',
+  agg: 'sum',
+  field: 'total',
+  filter: 'estado=completado',
+  company_id: '146'
+})
+```
+
+### Con filtros de fecha
+
+```javascript
+// Ventas del último mes
+gufi_data({
+  action: 'aggregate',
+  table: 'ventas.pedidos',
+  agg: 'sum',
+  field: 'total',
+  groupBy: 'cliente_id',
+  dateField: 'fecha_venta',
+  dateFrom: '2025-12-26T00:00:00Z',
+  dateTo: '2026-01-26T23:59:59Z',
+  company_id: '146'
+})
+
+// Top 10 máquinas por ventas del mes
+gufi_data({
+  action: 'aggregate',
+  table: 'nayax.machine_sales',
+  agg: 'sum',
+  field: 'settlement_value',
+  groupBy: 'machine_id',
+  dateField: 'settlement_datetime_gmt',
+  dateFrom: '2025-12-26T00:00:00Z',
+  dateTo: '2026-01-26T23:59:59Z',
+  company_id: '116'
+})
+```
+
+**Parámetros de fecha:**
+- `dateField`: Campo de fecha para filtrar (requerido para filtros de fecha)
+- `dateFrom`: Fecha inicio (ISO string, inclusive >=)
+- `dateTo`: Fecha fin (ISO string, inclusive <=)
+
+### Agregaciones disponibles
+
+| agg | Descripcion | Requiere field |
+|-----|-------------|----------------|
+| `count` | Cuenta registros | No (opcional) |
+| `sum` | Suma valores | Sí |
+| `avg` | Promedio | Sí |
+| `min` | Valor mínimo | Sí |
+| `max` | Valor máximo | Sí |
+
+## Automations
+
+### Listar scripts
+
+```
+GET /api/automation-scripts
+
+Response:
+[
+  { "id": 15, "name": "mi_script", "company_id": 116 }
+]
+```
+
+### Obtener script
+
+```
+GET /api/automation-scripts/{name}
+
+Response:
+{
+  "id": 15,
+  "name": "mi_script",
+  "js_code": "async function...",
+  "description": "..."
+}
+```
+
+### Crear/actualizar script
+
+```
+PUT /api/automation-scripts/{name}
+{
+  "js_code": "async function mi_script(gufi) {...}",
+  "description": "Descripcion"
+}
+```
+
+### Trigger click automation
+
+```
+POST /api/automation-scripts/triggerClick
+{
+  "table": "m360_t16192",
+  "row_id": 123,
+  "function_name": "generar_pdf",
+  "input": { "formato": "A4" }
+}
+```
+
+### Ver executions
+
+```
+GET /api/automation-executions?limit=20&script_name=mi_script
+
+Response:
+[
+  {
+    "id": 456,
+    "script_name": "mi_script",
+    "status": "completed",
+    "duration_ms": 234,
+    "created_at": "..."
+  }
+]
+```
+
+## Files
+
+### Upload
+
+```
+POST /api/files/upload
+Content-Type: multipart/form-data
+
+FormData:
+  file: (binary)
+
+Response:
+{
+  "url": "company_116/abc123_file.pdf",
+  "name": "documento.pdf",
+  "size": 12345,
+  "mime": "application/pdf"
+}
+```
+
+### Download
+
+```
+GET /api/files/download?path=company_116/abc123_file.pdf
+```
+
+## Environment Variables
+
+### Listar
+
+```
+GET /api/cli/env
+
+Response:
+[
+  { "key": "SLACK_WEBHOOK", "is_secret": true },
+  { "key": "PUBLIC_URL", "is_secret": false, "value": "https://..." }
+]
+```
+
+### Crear/actualizar
+
+```
+POST /api/cli/env
+{
+  "key": "NEW_API_KEY",
+  "value": "sk-..."
+}
+```
+
+### Eliminar
+
+```
+DELETE /api/cli/env/{key}
+```
+
+## Operadores de filtro
+
+Para usar en `/api/tables/{table}/list`:
+
+| Operador | Descripcion | Ejemplo |
+|----------|-------------|---------|
+| `eq` | Igual | `{ "field": "estado", "operator": "eq", "value": "activo" }` |
+| `ne` | No igual | `{ "field": "estado", "operator": "ne", "value": "cancelado" }` |
+| `gt` | Mayor que | `{ "field": "total", "operator": "gt", "value": 100 }` |
+| `gte` | Mayor o igual | `{ "field": "total", "operator": "gte", "value": 100 }` |
+| `lt` | Menor que | `{ "field": "total", "operator": "lt", "value": 1000 }` |
+| `lte` | Menor o igual | `{ "field": "total", "operator": "lte", "value": 1000 }` |
+| `contains` | Contiene texto | `{ "field": "nombre", "operator": "contains", "value": "juan" }` |
+| `in` | En lista | `{ "field": "estado", "operator": "in", "value": ["a", "b"] }` |
+| `null` | Es nulo | `{ "field": "deleted_at", "operator": "null", "value": true }` |
+
+## Codigos de error
+
+| Codigo | Significado |
+|--------|-------------|
+| 400 | Bad Request - Parametros invalidos |
+| 401 | Unauthorized - Token invalido/expirado |
+| 403 | Forbidden - Sin permisos |
+| 404 | Not Found - Recurso no existe |
+| 409 | Conflict - Ya existe |
+| 429 | Too Many Requests - Rate limit |
+| 500 | Internal Server Error |
+
+## Rate limits
+
+Por defecto (configurables):
+- Login: 5 intentos/minuto
+- Uploads: 20/minuto
+- AI: 10/minuto
+- General: 100/minuto

package/docs/mcp/07-packages.md

@@ -0,0 +1,246 @@
+# Packages y Marketplace
+
+Los packages agrupan modulos y vistas para distribucion en el Marketplace.
+
+## Estructura de un package
+
+```
+Package
+├── Modules (snapshots)
+│   └── Module JSON congelado
+├── Views (referencias)
+│   └── IDs de vistas marketplace
+└── Migrations
+    └── SQL para actualizaciones
+```
+
+## Flujo de desarrollo
+
+### 1. Crear package
+
+```
+gufi_package_create({
+  name: "CRM Basico",
+  description: "Gestion de clientes y contactos"
+})
+```
+
+### 2. Agregar modulos
+
+```
+gufi_package_add_module({
+  package_id: "14",
+  company_id: "116",
+  module_id: "360"
+})
+```
+
+Esto crea un **snapshot** del modulo (copia congelada).
+
+### 3. Agregar vistas
+
+```
+gufi_package_add_view({
+  package_id: "14",
+  view_id: "13"
+})
+```
+
+### 4. Publicar
+
+```
+gufi_package_publish({ package_id: "14" })
+```
+
+## Versionado
+
+### Sincronizar cambios
+
+Cuando modificas un modulo fuente, sincroniza el snapshot:
+
+```
+gufi_package_sync({ package_id: "14" })
+```
+
+Esto:
+- Actualiza snapshots de modulos
+- Incrementa version (1.0.0 -> 1.0.1)
+
+### Verificar cambios pendientes
+
+```
+gufi_package_check({ package_id: "14" })
+
+Response:
+{
+  "has_changes": true,
+  "modules_changed": [360],
+  "current_version": "1.0.0"
+}
+```
+
+## Migraciones
+
+Cuando cambias la estructura de un modulo publicado, necesitas migraciones para actualizar instalaciones existentes.
+
+### Listar migraciones
+
+```
+gufi_package_migrations({ package_id: "14" })
+```
+
+### Crear migracion
+
+```
+gufi_package_migration_create({
+  package_id: "14",
+  description: "Add phone column to clients",
+  target_entity: "crm.clientes",
+  up_sql: "ALTER TABLE {tableName} ADD COLUMN telefono JSONB",
+  down_sql: "ALTER TABLE {tableName} DROP COLUMN telefono",
+  is_breaking: false
+})
+```
+
+**Placeholders disponibles:**
+- `{tableName}` - Nombre fisico de la tabla (m360_t4136)
+- `{entityId}` - ID de la entidad
+- `{companyId}` - ID de la company instaladora
+
+### Eliminar migracion (solo si no aplicada)
+
+```
+gufi_package_migration_delete({
+  package_id: "14",
+  migration_id: "5"
+})
+```
+
+### Ver entidades para target_entity
+
+```
+gufi_package_entities({ package_id: "14" })
+
+Response:
+[
+  { "path": "crm.clientes", "name": "Clientes", "entity_id": 4136 },
+  { "path": "crm.contactos", "name": "Contactos", "entity_id": 4137 }
+]
+```
+
+## Operaciones con MCP
+
+### Listar mis packages
+
+```
+gufi_packages()
+```
+
+### Ver detalle de package
+
+```
+gufi_package({ package_id: "14" })
+
+Response:
+{
+  "id": 14,
+  "name": "CRM Basico",
+  "version": "1.0.3",
+  "published": true,
+  "modules": [...],
+  "views": [...],
+  "installations_count": 25
+}
+```
+
+### Quitar modulo
+
+```
+gufi_package_remove_module({
+  package_id: "14",
+  module_id: "5"  // ID del module DENTRO del package
+})
+```
+
+### Quitar vista
+
+```
+gufi_package_remove_view({
+  package_id: "14",
+  package_view_id: "3"  // ID de la relacion package-view
+})
+```
+
+### Despublicar
+
+```
+gufi_package_unpublish({ package_id: "14" })
+```
+
+### Eliminar package
+
+```
+gufi_package_delete({ package_id: "14" })
+```
+
+Solo funciona si NO esta publicado.
+
+## Instalacion (para compradores)
+
+Cuando alguien instala un package:
+
+1. Se crea copia de modulos en su company
+2. Se configuran vistas con sus tablas
+3. Se ejecutan migraciones pendientes
+
+## Actualizaciones
+
+Cuando publicas nueva version:
+
+1. Instalaciones existentes ven "actualizacion disponible"
+2. Al actualizar, se ejecutan migraciones en orden
+3. Se actualizan snapshots de modulos
+
+## Precios y monetizacion
+
+El Marketplace soporta:
+- **Gratis** - Cualquiera puede instalar
+- **Pago unico** - Se cobra una vez
+- **Suscripcion** - Cobro mensual/anual
+
+Configuracion via UI de Developer Center (no via MCP).
+
+## Buenas practicas
+
+### 1. Versionado semantico
+
+- **MAJOR** (2.0.0): Cambios breaking (eliminaciones, renombres)
+- **MINOR** (1.1.0): Nuevas features compatibles
+- **PATCH** (1.0.1): Fixes y mejoras menores
+
+### 2. Migraciones seguras
+
+```sql
+-- CORRECTO: Add column (safe)
+ALTER TABLE {tableName} ADD COLUMN IF NOT EXISTS nuevo_campo TEXT;
+
+-- CUIDADO: Drop column (perdida de datos)
+ALTER TABLE {tableName} DROP COLUMN IF EXISTS campo_viejo;
+
+-- INCORRECTO: Rename (no soportado bien)
+ALTER TABLE {tableName} RENAME COLUMN viejo TO nuevo;
+```
+
+### 3. Test antes de publicar
+
+1. Instalar en company de prueba
+2. Verificar que todo funciona
+3. Probar migraciones en BD de test
+
+### 4. Documentacion
+
+Incluir en descripcion del package:
+- Que hace
+- Como configurar
+- Requisitos previos
+- Changelog de versiones