@gnpdev/rpa-tools 1.0.0

package/README.md

@@ -0,0 +1,93 @@
+# @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
+const { createRpaTools } = require('@gnpdev/rpa-tools');
+const { Pool } = require('pg');
+
+// 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
+async function initRpa() {
+  const rpa = await createRpaTools({
+    botId: 'BOT-VENTAS-01',
+    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 === 'development'
+    }
+  });
+  return rpa;
+}
+
+module.exports = initRpa;
+```
+
+## Uso en la Aplicación
+
+### 1. Logging Estructurado
+Usa el logger preconfigurado que ya incluye el `botId` en cada entrada.
+
+```javascript
+const rpa = await initRpa();
+rpa.logger.info({ orderId: '123' }, 'Procesando orden');
+```
+
+### 2. Capturas de Pantalla bajo demanda (Playwright)
+Activa el watcher pasando la instancia de `page`. El bot detectará cambios en la tabla de la DB para tomar screenshots automáticamente.
+
+```javascript
+const { chromium } = require('playwright');
+const rpa = await initRpa();
+
+const browser = await chromium.launch();
+const page = await browser.newPage();
+
+// Inicia el monitoreo (polling cada 3s por defecto)
+rpa.watchDebugFlag(page);
+
+// Al terminar el proceso del bot
+// rpa.destroy(); 
+```
+
+## 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
+```

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@gnpdev/rpa-tools",
+  "version": "1.0.0",
+  "description": "Libreria para logs y screenshot de bots",
+  "author": "Sergio Antonio Trujillo del Valle",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "rpa",
+    "playwright",
+    "minio",
+    "pino",
+    "screenshots"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "minio": "^8.0.7",
+    "pino": "^10.3.1",
+    "sharp": "^0.34.5"
+  },
+  "devDependencies": {
+    "pino-pretty": "^13.1.3"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,75 @@
+import type { Pool }   from 'pg';
+import type { Logger }  from 'pino';
+import type { Page }    from 'playwright';
+
+// ── Opciones de MinIO ────────────────────────────────────────────────────────
+export interface MinioConfig {
+  endPoint:   string;
+  port?:      number;
+  useSSL?:    boolean;
+  accessKey:  string | any;
+  secretKey:  string | any;
+  bucket?:    string | any;
+}
+
+// ── Opciones de screenshot ───────────────────────────────────────────────────
+export interface ScreenshotConfig {
+  /** Formato final del archivo en MinIO. Default: 'webp' */
+  format?:         'webp' | 'jpeg';
+  /** Calidad de compresión final (sharp). Default: 70 */
+  quality?:        number;
+  /** Calidad de captura en Playwright. Default: 90 */
+  captureQuality?: number;
+}
+
+// ── Opciones de Pino ─────────────────────────────────────────────────────────
+export interface LogConfig {
+  level?:       'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent' | any;
+  /** Activar pino-pretty (solo dev). Default: false */
+  pretty?:      boolean;
+  pinoOptions?: Record<string, unknown>;
+}
+
+// ── Opciones principales de createRpaTools ───────────────────────────────────
+export interface RpaToolsOptions {
+  /** ID único del bot. Default: process.env.RPA_BOT_ID */
+  botId?:      string;
+  /** Pool de pg ya conectado */
+  db:          Pool;
+  /** Config de MinIO. Si se omite, lee de variables de entorno MINIO_* */
+  minio?:      MinioConfig;
+  /** Opciones del logger Pino */
+  log?:        LogConfig;
+  /** Opciones de captura y compresión de screenshots */
+  screenshot?: ScreenshotConfig;
+}
+
+// ── Objeto retornado por createRpaTools ──────────────────────────────────────
+export interface RpaTools {
+  /** Instancia de Pino lista para usar en el bot */
+  logger: Logger;
+
+  /**
+   * Inicia el polling que activa/desactiva screenshots
+   * según bot_debug_config en la BD.
+   * @param page      - Objeto Page de Playwright
+   * @param pollMs    - Intervalo de polling en ms. Default: 3000
+   */
+  watchDebugFlag: (page: Page, pollMs?: number) => void;
+
+  /** Detiene todos los intervalos. Llamar siempre al cerrar el bot. */
+  destroy: () => void;
+}
+
+// ── Export principal ─────────────────────────────────────────────────────────
+/**
+ * Inicializa la librería rpa-tools.
+ * Crea el cliente MinIO, verifica el bucket y retorna
+ * el logger y el watcher listos para usar.
+ *
+ * @example
+ * const rpa = await createRpaTools({ botId: 'bot-001', db: pool });
+ * rpa.watchDebugFlag(page);
+ * rpa.logger.info('Bot iniciado');
+ */
+export function createRpaTools(options: RpaToolsOptions): Promise<RpaTools>;

package/src/index.js

@@ -0,0 +1,86 @@
+'use strict';
+const { createLogger }                       = require('./logger');
+const { createMinioClient, ensureBucket }    = require('./storage');
+const { ScreenshotWatcher }                  = require('./watcher');
+
+/**
+ * Factory principal de la librería.
+ *
+ * @param {object} opts
+ * @param {string}  opts.botId          - identificador único del bot
+ * @param {import('pg').Pool} opts.db   - pool de pg ya conectado
+ * @param {object}  opts.minio          - config de MinIO (ver abajo)
+ * @param {string}  opts.minio.endPoint
+ * @param {number}  [opts.minio.port=9000]
+ * @param {boolean} [opts.minio.useSSL=false]
+ * @param {string}  opts.minio.accessKey
+ * @param {string}  opts.minio.secretKey
+ * @param {string}  [opts.minio.bucket='rpa-screenshots']
+ * @param {object}  [opts.log]          - opciones de Pino
+ * @param {string}  [opts.log.level='info']
+ * @param {boolean} [opts.log.pretty=false]
+ *
+ * @returns {{ logger, watchDebugFlag, destroy }}
+ */
+async function createRpaTools(opts = {}) {
+  const {
+    botId = process.env.RPA_BOT_ID,
+    log:  logCfg = {},
+    db,
+    minio: minioCfg,
+  } = opts;
+
+  // Leer minio desde env si no se pasó config
+  const minio = minioCfg ?? {
+    endPoint:  process.env.MINIO_ENDPOINT,
+    port:      Number(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:    process.env.MINIO_BUCKET ?? 'rpa-screenshots',
+  };
+
+  // db se sigue pasando desde afuera (el pool ya existe en el bot)
+  // pero puedes leer la URL para validar
+  if (!db) throw new Error('[rpa-tools] db (pg.Pool) es requerido');
+
+  // Validar que las env vars críticas existan
+  const missing = ['endPoint', 'accessKey', 'secretKey']
+    .filter(k => !minio[k]);
+
+  if (missing.length) {
+    throw new Error(`[rpa-tools] Faltan vars de entorno: ${missing.map(k => `MINIO_${k.toUpperCase()}`).join(', ')}`);
+  }
+
+
+
+  if (!botId)    throw new Error('[rpa-tools] botId es requerido');
+  if (!db)       throw new Error('[rpa-tools] db (pg.Pool) es requerido');
+  if (!minioCfg) throw new Error('[rpa-tools] minio config es requerida');
+
+  const logger      = createLogger(botId, logCfg);
+  const minioClient = createMinioClient(minioCfg);
+  const bucket      = minioCfg.bucket ?? 'rpa-screenshots';
+
+  await ensureBucket(minioClient, bucket);
+  logger.info({ bucket }, 'MinIO listo');
+
+  const watcher = new ScreenshotWatcher({ botId, pool: db, minioClient, bucket, logger });
+
+  return {
+    /** Instancia de Pino lista para usar en tu bot */
+    logger,
+
+    /**
+     * Arranca el polling. Llama una vez, pasando el objeto `page` de Playwright.
+     * @param {import('playwright').Page} page
+     * @param {number} [pollMs=3000]
+     */
+    watchDebugFlag: (page, pollMs) => watcher.watch(page, pollMs),
+
+    /** Limpia intervalos al finalizar el bot */
+    destroy: () => watcher.destroy(),
+  };
+}
+
+module.exports = { createRpaTools };

package/src/logger.js

@@ -0,0 +1,26 @@
+'use strict';
+const pino = require('pino');
+
+/**
+ * Crea una instancia de Pino ya configurada con el botId como campo base.
+ * @param {string} botId
+ * @param {object} opts
+ * @param {'trace'|'debug'|'info'|'warn'|'error'} [opts.level='info']
+ * @param {boolean} [opts.pretty=false]  - activar pino-pretty (solo en dev)
+ * @param {object} [opts.pinoOptions]    - opciones adicionales de Pino
+ */
+function createLogger(botId, opts = {}) {
+  const { level = 'info', pretty = false, pinoOptions = {} } = opts;
+
+  return pino({
+    level,
+    base: { botId },
+    timestamp: pino.stdTimeFunctions.isoTime,
+    transport: pretty
+      ? { target: 'pino-pretty', options: { colorize: true } }
+      : undefined,
+    ...pinoOptions,
+  });
+}
+
+module.exports = { createLogger };

package/src/storage.js

@@ -0,0 +1,83 @@
+'use strict';
+const Minio = require('minio');
+const sharp = require('sharp');
+
+/**
+ * Crea y retorna el cliente de MinIO.
+ * @param {object} cfg
+ * @param {string}  cfg.endPoint
+ * @param {number}  [cfg.port=9000]
+ * @param {boolean} [cfg.useSSL=false]
+ * @param {string}  cfg.accessKey
+ * @param {string}  cfg.secretKey
+ */
+function createMinioClient(cfg) {
+  return new Minio.Client({
+    endPoint:  cfg.endPoint,
+    port:      cfg.port     ?? 9000,
+    useSSL:    cfg.useSSL   ?? false,
+    accessKey: cfg.accessKey,
+    secretKey: cfg.secretKey,
+  });
+}
+
+/**
+ * Garantiza que el bucket exista; lo crea si no.
+ * @param {import('minio').Client} client
+ * @param {string} bucket
+ * @param {string} [region='us-east-1']
+ */
+async function ensureBucket(client, bucket, region = 'us-east-1') {
+  const exists = await client.bucketExists(bucket);
+  if (!exists) await client.makeBucket(bucket, region);
+}
+
+/**
+ * Convierte un buffer de imagen a WebP usando sharp.
+ * @param {Buffer} buffer  - buffer fuente (jpeg/png)
+ * @param {number} [quality=70]
+ * @returns {Promise<Buffer>}
+ */
+async function toWebp(buffer, quality = 70) {
+  return sharp(buffer)
+    .webp({ quality })
+    .toBuffer();
+}
+
+/**
+ * Sube un screenshot a MinIO.
+ * Si format='webp' convierte el buffer antes de subir.
+ * Ruta generada: {botId}/{YYYY-MM-DD}/{ISO-timestamp}.{ext}
+ *
+ * @param {import('minio').Client} client
+ * @param {string} bucket
+ * @param {string} botId
+ * @param {Buffer} buffer       - buffer raw de Playwright (jpeg)
+ * @param {object} [opts]
+ * @param {'webp'|'jpeg'}  [opts.format='webp']
+ * @param {number}         [opts.quality=70]      - calidad 1-100
+ * @returns {Promise<string>}   - object key en MinIO
+ */
+async function uploadScreenshot(client, bucket, botId, buffer, opts = {}) {
+  const { format = 'webp', quality = 70 } = opts;
+
+  const finalBuffer = format === 'webp'
+    ? await toWebp(buffer, quality)
+    : buffer;
+
+  const contentType = format === 'webp' ? 'image/webp' : 'image/jpeg';
+  const ext         = format === 'webp' ? 'webp' : 'jpg';
+
+  const now  = new Date();
+  const date = now.toISOString().slice(0, 10);           // 2025-06-01
+  const ts   = now.toISOString().replace(/[:.]/g, '-');  // 2025-06-01T12-30-00-000Z
+  const key  = `${botId}.${ext}`;
+
+  await client.putObject(bucket, key, finalBuffer, finalBuffer.length, {
+    'Content-Type': contentType,
+  });
+
+  return key;
+}
+
+module.exports = { createMinioClient, ensureBucket, uploadScreenshot };

package/src/watcher.js

@@ -0,0 +1,137 @@
+'use strict';
+const { uploadScreenshot } = require('./storage');
+
+class ScreenshotWatcher {
+  /**
+   * @param {object} p
+   * @param {string}                p.botId
+   * @param {import('pg').Pool}     p.pool
+   * @param {import('minio').Client} p.minioClient
+   * @param {string}                p.bucket
+   * @param {import('pino').Logger} p.logger
+   * @param {object}                [p.screenshot]
+   * @param {'webp'|'jpeg'}         [p.screenshot.format='webp']
+   * @param {number}                [p.screenshot.quality=70]   - calidad conversión 1-100
+   * @param {number}                [p.screenshot.captureQuality=90] - calidad captura Playwright
+   */
+  constructor({ botId, pool, minioClient, bucket, logger, screenshot = {} }) {
+    this.botId       = botId;
+    this.pool        = pool;
+    this.minioClient = minioClient;
+    this.bucket      = bucket;
+    this.logger      = logger;
+
+    this.screenshotOpts = {
+      format:         screenshot.format         ?? 'webp',
+      quality:        screenshot.quality        ?? 70,
+      captureQuality: screenshot.captureQuality ?? 90,
+    };
+
+    this._watchTimer = null;
+    this._shotTimer  = null;
+  }
+
+  /**
+   * Inicia el polling que activa/desactiva screenshots según bot_debug_config.
+   * Llama una sola vez al arrancar el bot.
+   *
+   * @param {import('playwright').Page} page
+   * @param {number} [pollMs=3000] - cada cuántos ms revisar la BD
+   */
+  watch(page, pollMs = 3000) {
+    if (this._watchTimer) {
+      this.logger.warn('ScreenshotWatcher ya está corriendo, ignorando llamada duplicada');
+      return;
+    }
+
+    this.logger.info({ pollMs }, 'Iniciando polling de debug config');
+
+    this._watchTimer = setInterval(async () => {
+      try {
+        const { rows } = await this.pool.query(
+          `SELECT screenshots, interval_sec
+             FROM bots.tb_bots
+            WHERE bot_id = $1`,
+          [this.botId]
+        );
+
+        const cfg = rows[0];
+        // console.log('DEBUG CONFIG', cfg); // <-- loguear config para debug
+
+        if (!cfg) {
+          this.logger.debug('Sin config en bot_debug_config para este bot');
+          return;
+        }
+
+        if (cfg.screenshots && !this._shotTimer) {
+          this.logger.info({ intervalSec: cfg.interval_sec }, 'Screenshots activados');
+          this._startScreenshots(page, cfg.interval_sec * 1000);
+          return;
+        }
+
+        if (!cfg.screenshots && this._shotTimer) {
+          this.logger.info('Screenshots desactivados');
+          this._stopScreenshots();
+        }
+      } catch (err) {
+        this.logger.error({ err }, 'Error leyendo bot_debug_config');
+      }
+    }, pollMs);
+  }
+
+  /**
+   * @private
+   */
+  _startScreenshots(page, intervalMs) {
+    this._shotTimer = setInterval(async () => {
+      const t0 = Date.now();
+
+      try {
+        // Playwright captura en jpeg (más rápido), sharp convierte a WebP después
+        const rawBuffer = await page.screenshot({
+          type:     'jpeg',
+          quality:  this.screenshotOpts.captureQuality,
+          fullPage: false,
+        });
+
+        const key = await uploadScreenshot(
+          this.minioClient,
+          this.bucket,
+          this.botId,
+          rawBuffer,
+          {
+            format:  this.screenshotOpts.format,
+            quality: this.screenshotOpts.quality,
+          }
+        );
+
+        this.logger.debug(
+          { key, ms: Date.now() - t0 },
+          'Screenshot subido'
+        );
+      } catch (err) {
+        this.logger.error({ err }, 'Error capturando o subiendo screenshot');
+      }
+    }, intervalMs);
+  }
+
+  /**
+   * @private
+   */
+  _stopScreenshots() {
+    clearInterval(this._shotTimer);
+    this._shotTimer = null;
+  }
+
+  /**
+   * Detiene todos los intervalos. Llamar siempre al cerrar el bot.
+   */
+  destroy() {
+    this._stopScreenshots();
+    clearInterval(this._watchTimer);
+    this._watchTimer = null;
+    this.logger.info('ScreenshotWatcher destruido');
+  }
+}
+
+module.exports = { ScreenshotWatcher };