nexabase-report 0.1.0

package/docs/API_REST.md

@@ -0,0 +1,376 @@
+# NexaBase Report - API REST
+
+Guía de despliegue y uso de la API REST del reporteador.
+
+---
+
+## 📡 Endpoints Disponibles
+
+| Método | Endpoint | Descripción |
+|--------|----------|-------------|
+| `GET` | `/api/reports` | Listar todos los reportes guardados |
+| `GET` | `/api/reports/:id` | Obtener definición completa de un reporte |
+| `POST` | `/api/reports/:id/render` | Renderizar reporte con datos y parámetros |
+| `POST` | `/api/reports/:id/export/pdf` | Preparar exportación a PDF |
+| `POST` | `/api/reports/:id/export/excel` | Preparar exportación a Excel |
+| `POST` | `/api/reports/:id/export/csv` | Preparar exportación a CSV |
+| `POST` | `/api/reports/:id/export/word` | Preparar exportación a Word (.docx) |
+
+---
+
+## 🔐 Autenticación
+
+Todos los endpoints requieren autenticación vía API Key:
+
+### Opción 1: Header dedicado
+```
+X-API-Key: nb_sk_tu_api_key_aqui
+```
+
+### Opción 2: Bearer token
+```
+Authorization: Bearer nb_sk_tu_api_key_aqui
+```
+
+---
+
+## 📋 Ejemplos de Uso
+
+### 1. Listar Reportes
+
+```bash
+curl -X GET "https://tu-nexabase.url/api/reports" \
+  -H "X-API-Key: nb_sk_tu_api_key"
+```
+
+**Respuesta:**
+```json
+{
+  "success": true,
+  "count": 3,
+  "reports": [
+    {
+      "id": "abc123",
+      "name": "Ventas Mensuales",
+      "description": "Reporte de ventas del mes",
+      "author": "Admin",
+      "createdAt": "2024-01-15T10:00:00.000Z",
+      "updatedAt": "2024-01-20T14:30:00.000Z"
+    }
+  ]
+}
+```
+
+---
+
+### 2. Obtener Definición de Reporte
+
+```bash
+curl -X GET "https://tu-nexabase.url/api/reports/abc123" \
+  -H "X-API-Key: nb_sk_tu_api_key"
+```
+
+**Respuesta:**
+```json
+{
+  "success": true,
+  "report": {
+    "id": "abc123",
+    "metadata": {
+      "version": "1.0",
+      "name": "Ventas Mensuales",
+      "author": "Admin",
+      "createdAt": "2024-01-15T10:00:00.000Z"
+    },
+    "layout": { ... },
+    "dataSources": [ ... ]
+  }
+}
+```
+
+---
+
+### 3. Renderizar Reporte con Parámetros
+
+```bash
+curl -X POST "https://tu-nexabase.url/api/reports/abc123/render" \
+  -H "X-API-Key: nb_sk_tu_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "parameters": {
+      "fecha_inicio": "2024-01-01",
+      "fecha_fin": "2024-01-31"
+    },
+    "limit": 500
+  }'
+```
+
+**Respuesta:**
+```json
+{
+  "success": true,
+  "report": { ... },
+  "parameters": {
+    "fecha_inicio": "2024-01-01",
+    "fecha_fin": "2024-01-31"
+  },
+  "data": {
+    "main": [ ... ],
+    "detalle": [ ... ]
+  },
+  "metadata": {
+    "renderedAt": "2024-01-20T15:00:00.000Z",
+    "dataSources": 2,
+    "bands": 5
+  }
+}
+```
+
+---
+
+### 4. Exportar a PDF
+
+```bash
+curl -X POST "https://tu-nexabase.url/api/reports/abc123/export/pdf" \
+  -H "X-API-Key: nb_sk_tu_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "parameters": {
+      "fecha_inicio": "2024-01-01"
+    },
+    "limit": 1000
+  }'
+```
+
+**Respuesta:**
+```json
+{
+  "success": true,
+  "format": "pdf",
+  "filename": "Ventas_Mensuales.pdf",
+  "report": { ... },
+  "data": { ... },
+  "parameters": { ... },
+  "exportedAt": "2024-01-20T15:00:00.000Z",
+  "note": "Para exportación completa de PDF, use el cliente con los datos devueltos"
+}
+```
+
+---
+
+## 🚀 Despliegue en NexaBase
+
+### Opción 1: Usando MCP (Recomendado)
+
+Ejecuta en Qwen Code:
+
+```
+mcp__nexabase__create_function({
+  name: "report-api",
+  code: "<contenido de src/functions/report-api.ts>",
+  trigger: "http",
+  config: {
+    path: "/api/reports/*",
+    httpMethod: ["GET", "POST", "OPTIONS"],
+    memoryLimit: 256,
+    timeout: 60
+  },
+  environment: {
+    "NEXABASE_URL": "https://api.nexabase.online",
+    "NEXABASE_API_KEY": "nb_sk_tu_api_key"
+  }
+})
+```
+
+### Opción 2: Usando NexaBase Dashboard
+
+1. Ve a **Functions** → **Nueva Función**
+2. Nombre: `report-api`
+3. Runtime: `typescript`
+4. Trigger: `http`
+5. Path: `/api/reports/*`
+6. Pega el código de `src/functions/report-api.ts`
+7. Agrega variables de entorno:
+   - `NEXABASE_URL`
+   - `NEXABASE_API_KEY`
+8. Despliega
+
+---
+
+## 🔧 Uso desde Cliente (Ejemplo)
+
+### JavaScript/TypeScript
+
+```typescript
+const API_URL = 'https://tu-nexabase.url';
+const API_KEY = 'nb_sk_tu_api_key';
+
+// Listar reportes
+async function listReports() {
+  const res = await fetch(`${API_URL}/api/reports`, {
+    headers: { 'X-API-Key': API_KEY }
+  });
+  return res.json();
+}
+
+// Renderizar reporte
+async function renderReport(id: string, params: Record<string, any>) {
+  const res = await fetch(`${API_URL}/api/reports/${id}/render`, {
+    method: 'POST',
+    headers: { 
+      'X-API-Key': API_KEY,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({ parameters: params })
+  });
+  return res.json();
+}
+
+// Exportar a PDF (requiere html2pdf.js en cliente)
+async function exportPdf(reportDef: any, data: any) {
+  // 1. Obtener datos renderizados
+  const rendered = await renderReport(reportDef.id, {});
+  
+  // 2. Usar nexabase-report viewer para exportar
+  import { registerNexaReport } from 'nexabase-report';
+  registerNexaReport();
+  
+  // 3. Crear elemento viewer y llamar exportPdf
+  const viewer = document.createElement('nexa-viewer');
+  viewer.report = rendered.report;
+  viewer.data = rendered.data;
+  document.body.appendChild(viewer);
+  
+  // 4. Esperar render y exportar
+  await viewer.exportPdf();
+}
+```
+
+---
+
+### Python
+
+```python
+import requests
+
+API_URL = "https://tu-nexabase.url"
+API_KEY = "nb_sk_tu_api_key"
+
+def list_reports():
+    res = requests.get(
+        f"{API_URL}/api/reports",
+        headers={"X-API-Key": API_KEY}
+    )
+    return res.json()
+
+def render_report(report_id: str, params: dict = None):
+    res = requests.post(
+        f"{API_URL}/api/reports/{report_id}/render",
+        headers={
+            "X-API-Key": API_KEY,
+            "Content-Type": "application/json"
+        },
+        json={"parameters": params or {}}
+    )
+    return res.json()
+
+# Ejemplo
+reports = list_reports()
+print(f"Encontrados {reports['count']} reportes")
+
+data = render_report("abc123", {"fecha": "2024-01-01"})
+print(f"Reporte renderizado con {len(data['data']['main'])} registros")
+```
+
+---
+
+## ⚠️ Notas Importantes
+
+### Exportación PDF/Excel/Word
+
+La API REST **prepara los datos** para exportación pero la generación final del archivo requiere ejecución en cliente (browser) debido a:
+
+- **PDF**: Usa `html2pdf.js` que requiere DOM del navegador
+- **Excel**: Usa `xlsx` (SheetJS) que funciona en cliente
+- **Word**: Usa `docx` que genera archivo en memoria del cliente
+
+**Flujo recomendado:**
+
+1. Cliente llama `POST /api/reports/:id/export/pdf`
+2. API devuelve `{ report, data, parameters }`
+3. Cliente crea elemento `<nexa-viewer>` con los datos
+4. Cliente llama `viewer.exportPdf()` (ejecuta html2pdf.js)
+5. Archivo se descarga automáticamente
+
+### Límites
+
+- **Timeout**: 60 segundos (configurable en función)
+- **Memoria**: 256MB recomendado
+- **Registros por defecto**: 1000 (configurable con `limit`)
+
+### CORS
+
+Todos los endpoints incluyen headers CORS:
+```
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Methods: GET, POST, OPTIONS
+Access-Control-Allow-Headers: Content-Type, Authorization, X-API-Key
+```
+
+---
+
+## 📊 Códigos de Error
+
+| Código | Significado |
+|--------|-------------|
+| `200` | Éxito |
+| `404` | Reporte no encontrado |
+| `500` | Error interno del servidor |
+
+---
+
+## 🔄 Migración de Funciones Existentes
+
+Si ya tienes una función serverless en NexaBase, actualiza con:
+
+```typescript
+mcp__nexabase__update_function({
+  functionId: "report-api",
+  code: "<nuevo código>"
+})
+```
+
+---
+
+## 🛡️ Seguridad
+
+### Mejores Prácticas
+
+1. **No expongas API Keys en cliente frontend**
+2. Usa **CORS restringido** para producción:
+   ```
+   Access-Control-Allow-Origin: https://tu-dominio.com
+   ```
+3. **Rate limiting**: Configura en NexaBase dashboard
+4. **Validación de parámetros**: Agrega middleware si es necesario
+
+### Ejemplo con Validación
+
+```typescript
+// Dentro de renderReport()
+if (parameters.fecha_inicio && !isValidDate(parameters.fecha_inicio)) {
+  return jsonResponse({ error: 'Invalid date format' }, 400);
+}
+
+function isValidDate(dateStr: string): boolean {
+  return /^\d{4}-\d{2}-\d{2}$/.test(dateStr) && !isNaN(Date.parse(dateStr));
+}
+```
+
+---
+
+## 📞 Soporte
+
+- **Docs**: `docs/VIEWER_API.md`, `docs/PUBLISHING.md`
+- **Issues**: GitHub Issues
+- **API SDK**: `@nexabase/sdk` v2.12.6+

package/docs/EXPORT_REGRESSION.md

@@ -0,0 +1,54 @@
+# Export Regression Checklist
+
+Checklist corto para validar fidelidad de export después de cada cambio.
+
+## 1) Setup
+
+- Ejecutar: `npm.cmd run build`
+- En local, reiniciar dev server si cambió `vite.config.ts`: `npm.cmd run dev`
+
+## 2) PDF (Alta prioridad)
+
+- Caso A: imágenes same-origin (`/assets/...`)
+  - Deben verse en visor y PDF.
+- Caso B: imágenes cross-origin (`https://...`)
+  - Deben verse en visor.
+  - En PDF deben verse vía `/api/image?url=...`.
+- Caso C: imágenes base64 (`data:image/...`)
+  - Deben verse en visor y PDF sin depender de proxy.
+- Validar:
+  - Sin página extra al final.
+  - Header/footer correctos por página.
+  - Tabla multipágina continua (sin huecos/saltos extraños).
+
+## 3) Excel
+
+- Hojas de tablas:
+  - Columnas y encabezados correctos.
+  - Filas deben coincidir con filtros/sort/joins del viewer.
+- Hojas por datasource:
+  - Alias correcto.
+  - Datos procesados (no crudos) si aplica lógica de datasource.
+- Validar:
+  - Celdas no vacías cuando en visor sí hay valores.
+
+## 4) Word
+
+- ReportHeader y PageHeader deben exportar textos correctos.
+- DataBand:
+  - Si hay `Table`, exporta tabla con encabezados + filas.
+  - Si no hay `Table`, exporta textos por fila.
+- Validar:
+  - Valores iguales al visor para 5-10 registros de muestra.
+
+## 5) Casos de estrés
+
+- Dataset mediano (200 filas) y grande (1000 filas).
+- Con filtros (`dataSource.filter` + `band.filter`).
+- Con `starts_with` y `regex` en formato condicional.
+
+## 6) Criterio de OK
+
+- PDF fiel al visor (incluyendo imágenes).
+- Excel/Word con datos completos y coherentes con visor.
+- Sin errores en consola durante export.

package/docs/EXTERNAL_INTEGRATION.md

@@ -0,0 +1,211 @@
+# Integración Externa con NexaReport
+
+## Visión General
+
+NexaReport puede usarse en cualquier aplicación externa (Vue, React, Angular, HTML puro) pasando los datos del reporte via JSON. No requiere conexión a NexaBase para funcionar.
+
+## Uso Básico
+
+### 1. Instalar
+
+```bash
+npm install nexabase-report
+```
+
+### 2. Registrar el componente
+
+```ts
+import { registerNexaReport } from 'nexabase-report';
+import 'nexabase-report/style.css';
+
+registerNexaReport();
+```
+
+### 3. Usar en tu app
+
+```vue
+<template>
+  <nexa-viewer 
+    :definition="reportDefinition" 
+    :data="reportData" 
+    minimal 
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+// Definición del reporte (puede venir de un archivo JSON o API)
+const reportDefinition = ref({
+  metadata: { name: 'Mi Reporte', version: '1.0', createdAt: '2024-01-15' },
+  layout: {
+    page: { format: 'A4', orientation: 'portrait' },
+    bands: [ /* ... */ ]
+  },
+  dataSources: [{ id: 'ds1', alias: 'main', collection: '', enabled: true }]
+});
+
+// Datos del reporte
+const reportData = ref([
+  { id: 1, nombre: 'Producto A', precio: 100, cantidad: 5 },
+  { id: 2, nombre: 'Producto B', precio: 200, cantidad: 3 }
+]);
+</script>
+```
+
+## Formato de Datos
+
+### Single DataSource (array simple)
+
+```json
+[
+  { "id": 1, "nombre": "Juan Pérez", "email": "juan@mail.com" },
+  { "id": 2, "nombre": "María López", "email": "maria@mail.com" }
+]
+```
+
+### Multiple DataSources (objeto con alias)
+
+```json
+{
+  "clientes": [
+    { "id": 1, "nombre": "Juan Pérez", "email": "juan@mail.com" },
+    { "id": 2, "nombre": "María López", "email": "maria@mail.com" }
+  ],
+  "pedidos": [
+    { "id": 101, "cliente_id": 1, "monto": 1500, "fecha": "2024-03-01" },
+    { "id": 102, "cliente_id": 2, "monto": 2300, "fecha": "2024-03-02" }
+  ]
+}
+```
+
+## API del Viewer
+
+### Métodos
+
+```ts
+const viewer = document.querySelector('nexa-viewer');
+
+// Exportar a diferentes formatos
+await viewer.exportPdf();
+await viewer.exportExcel();
+await viewer.exportWord();
+await viewer.exportCsv();
+
+// Actualizar datos dinámicamente
+viewer.updateData({
+  clientes: [ /* nuevos datos */ ],
+  pedidos: [ /* nuevos datos */ ]
+});
+
+// Obtener campos disponibles del diccionario
+const fields = viewer.getDictionaryFields();
+// [{ alias: 'clientes', fields: [{ name: 'id', type: 'number' }, ...] }]
+
+// Navegación de páginas
+viewer.goToPage(2);
+console.log(viewer.currentPage);  // 2
+console.log(viewer.totalPages);   // 5
+```
+
+### Eventos
+
+```vue
+<nexa-viewer 
+  :definition="report"
+  @data-request="(alias) => fetch(`/api/data/${alias}`).then(r => r.json())"
+/>
+```
+
+## Diccionario Manual
+
+Puedés definir la estructura de datos sin conexión a NexaBase:
+
+```json
+{
+  "dictionary": {
+    "dataSources": [
+      {
+        "alias": "clientes",
+        "label": "Tabla de Clientes",
+        "fields": [
+          { "name": "id", "type": "number", "label": "ID", "primaryKey": true },
+          { "name": "nombre", "type": "string", "label": "Nombre Completo" },
+          { "name": "email", "type": "string", "label": "Email" },
+          { "name": "fecha_registro", "type": "date", "label": "Fecha de Registro" }
+        ]
+      }
+    ],
+    "relationships": [
+      {
+        "from": "pedidos.cliente_id",
+        "to": "clientes.id",
+        "type": "many-to-one"
+      }
+    ]
+  }
+}
+```
+
+## Variables de Sistema
+
+Disponibles en bindings `{{...}}`:
+
+| Variable | Descripción | Ejemplo |
+|----------|-------------|---------|
+| `{{Page}}` | Número de página actual | `1` |
+| `{{TotalPages}}` | Total de páginas | `5` |
+| `{{Now}}` | Fecha y hora actual | `2024-01-15 14:30:00` |
+| `{{Today}}` | Fecha actual | `2024-01-15` |
+| `{{ReportName}}` | Nombre del reporte | `Ventas Mensuales` |
+| `{{RowNumber}}` | Número de fila | `1` |
+
+## Ejemplo Completo
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script src="https://cdn.jsdelivr.net/npm/nexabase-report/dist/nexabase-report.umd.js"></script>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/nexabase-report/dist/style.css">
+</head>
+<body>
+  <h1>Mi Reporte</h1>
+  <nexa-viewer id="viewer" minimal></nexa-viewer>
+
+  <script>
+    NexaReport.registerNexaReport();
+
+    const viewer = document.getElementById('viewer');
+
+    // Cargar definición del reporte
+    fetch('/api/reports/ventas.json')
+      .then(r => r.json())
+      .then(def => { viewer.definition = def; });
+
+    // Cargar datos
+    fetch('/api/data/ventas?desde=2024-01-01')
+      .then(r => r.json())
+      .then(data => { viewer.data = data; });
+  </script>
+</body>
+</html>
+```
+
+## Tipos de Datos Soportados
+
+| Tipo JSON | Tipo en Diccionario | Icono |
+|-----------|---------------------|-------|
+| `string` | `string` | 🏷️ |
+| `number` | `number` | #️⃣ |
+| `boolean` | `boolean` | ☑️ |
+| `string` (formato fecha) | `date` | 📅 |
+| `object` | `object` | 📦 |
+| `array` | `array` | 📋 |
+
+## Tips
+
+1. **Datos grandes**: Usá paginación en tu API y pasá los datos por páginas
+2. **Actualización en tiempo real**: Usá `viewer.updateData()` para refrescar sin recargar
+3. **Validación**: Usá `viewer.getDictionaryFields()` para validar bindings antes de renderizar
+4. **Export**: Los métodos de export funcionan sin conexión a internet