# 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+
