npm package: @gnpdev/rpa-tools
Description: Libreria para logs y screenshot de bots
Author: Sergio Antonio Trujillo del Valle
Latest version: 1.1.3

# @gnpdev/rpa-tools

Herramientas de automatización para bots RPA: logging estructurado con **Pino**, almacenamiento en **MinIO** con optimización de imágenes (WebP) y monitoreo de flags en base de datos para capturas de pantalla en tiempo real con **Playwright**.

## Requisitos

- **Node.js** v18+
- **pnpm** (recomendado)
- Instancia de **MinIO** activa.
- Base de datos **PostgreSQL**.

## Instalación

```bash
pnpm add @gnpdev/rpa-tools
```

## Configuración Centralizada (Best Practice)

Crea un archivo en tu proyecto (ej. `src/lib/rpa.js`) para inicializar y exportar las herramientas. Esto asegura que uses la misma instancia en toda la aplicación.

```javascript
// src/lib/rpa.js
import { createRpaTools } from '@gnpdev/rpa-tools';
import { Pool } from 'pg';
import * as dotenv from 'dotenv';
dotenv.config();

// 1. Configura tu pool de base de datos (usualmente ya lo tienes)
const pool = new Pool({
  connectionString: process.env.DATABASE_URL
});

// 2. Inicializa las herramientas
export const rpa = await createRpaTools({
  botId: process.env.RPA_BOT_ID,
  db: pool,
  minio: {
    endPoint: process.env.MINIO_ENDPOINT,
    port: parseInt(process.env.MINIO_PORT || '9000'),
    useSSL: process.env.MINIO_USE_SSL === 'true',
    accessKey: process.env.MINIO_ACCESS_KEY,
    secretKey: process.env.MINIO_SECRET_KEY,
    bucket: 'rpa-screenshots'
  },
  log: {
    level: process.env.NODE_ENV === 'development' ? 'debug' : 'info',
    pretty: process.env.NODE_ENV !== 'production',
  }
})

// 3. Exporta las herramientas
export const { logger, state, step } = rpa;
```

## Uso en la Aplicación

### 1. Gestión de Pasos y Estado
La librería mantiene el rastro del paso actual del bot. Cada vez que llamas a `step()`, se actualiza el estado interno y se genera un log automático.

```javascript
import { step, state } from './lib/rpa.js';

step('Inicio de Sesión');
console.log(state.currentStep); // 'Inicio de Sesión'

step('Extracción de Datos');
// Genera log: info { "step": "Extracción de Datos" } "Nuevo paso"
```

### 2. Logging Estructurado
Usa el logger preconfigurado que ya incluye el `botId` en cada entrada.

```javascript
import { logger } from './lib/rpa.js';

logger.info('Procesando orden');
```

### 3. Gestión de Credenciales y Estado de Aplicaciones
Recupera de forma segura el `usuario`, `password` e `idUsuario` de una aplicación específica vinculada al bot. También permite actualizar el estado y observaciones (útil para fallos de login).

```javascript
import { rpa, logger } from './lib/rpa.js';

logger.info('Obtener credenciales');
const credentials = await rpa.getCredentials('Portal CRM');

if (credentials) {
  const { usuario, password, idUsuario } = credentials;
  // usar en el login de la web
}

// En caso de fallo de login o error en la aplicación
await rpa.updateAppStatus('Portal CRM', false, 'Credenciales inválidas o bloqueo de cuenta');
```

### 4. Verificar Estado del Bot (Kill Switch)
...
```javascript
import { rpa, logger } from './lib/rpa.js';

const active = await rpa.isActive();
...
```

### 5. Capturas de Pantalla
Existen tres formas de realizar capturas de pantalla:

#### A. Captura Manual Estructurada
Captura la página actual y la guarda con una estructura de carpetas: `capturas/id_bot/fecha/nombre.webp`.

```javascript
import { rpa } from './lib/rpa.js';

// Captura la página actual con el nombre 'dashboard_principal'
const key = await rpa.capturePage(page, 'dashboard_principal');
```

#### B. Monitoreo en Tiempo Real (Debug)
Activa el watcher pasando la instancia de `page`. El bot detectará cambios en la tabla de la DB para tomar screenshots automáticamente.

```javascript
import { chromium } from 'playwright';
import { rpa } from './lib/rpa.js';

const browser = await chromium.launch();
const page = await browser.newPage();

rpa.watchDebugFlag(page);
```

#### C. Captura Automática de Errores (Screenshot + Trace)
...
Captura el estado completo del bot cuando ocurre una excepción. **`captureError` detecta automáticamente el paso actual** definido con `step()`.

> **Nota:** El soporte de `tracing` (archivos .zip de depuración) es exclusivo de **Playwright**. En **Puppeteer** se capturará el error y el screenshot, pero el `traceKey` será nulo.

```javascript
import { chromium } from 'playwright';
import { rpa, logger, step } from './lib/rpa.js';

const browser = await chromium.launch({ headless: true });
const context = await browser.newContext();
const page    = await context.newPage();

// ── Activar tracing ANTES de que empiece la sesión ──────────────────────
await context.tracing.start({ screenshots: true, snapshots: true });

browser.on('disconnected', () => rpa.destroy());

try {
  step('Navegación');
  await page.goto('https://example.com');
  
  step('Login');
  await login(page);

  step('Procesar Datos');
  await page.click('#boton-inexistente');

} catch (err) {
  // Captura automática de evidencia (usa el paso 'Procesar Datos' automáticamente)
  const { errorId } = await rpa.captureError({ page, context, err });

  logger.error({ errorId }, 'Fallo crítico capturado');
  rpa.destroy();
  throw err;
}
```

## Variables de Entorno Sugeridas

```env
MINIO_ENDPOINT=localhost
MINIO_PORT=9000
MINIO_USE_SSL=false
MINIO_ACCESS_KEY=admin
MINIO_SECRET_KEY=password
MINIO_BUCKET=rpa-screenshots
DATABASE_URL=postgres://user:pass@localhost:5432/db
```