@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

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.

// 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.

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.

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).

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)

...

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.

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.

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.

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

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