@gnpdev/rpa-tools 1.1.3 → 1.3.0

package/README.md

@@ -5,14 +5,14 @@ Herramientas de automatización para bots RPA: logging estructurado con **Pino**
 ## Requisitos
 
 - **Node.js** v18+
-- **pnpm** (recomendado)
+- **npm** o **pnpm**
 - Instancia de **MinIO** activa.
 - Base de datos **PostgreSQL**.
 
 ## Instalación
 
 ```bash
-pnpm add @gnpdev/rpa-tools
+npm install @gnpdev/rpa-tools
 ```
 
 ## Configuración Centralizada (Best Practice)
@@ -91,6 +91,10 @@ if (credentials) {
   // usar en el login de la web
 }
 
+// Si pueden existir múltiples registros con el mismo nombre:
+const allCredentials = await rpa.getCredentialsAll('Portal CRM');
+// allCredentials → Array de { nombre, usuario, password, idUsuario, status }
+
 // 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');
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gnpdev/rpa-tools",
-  "version": "1.1.3",
+  "version": "1.3.0",
   "description": "Libreria para logs y screenshot de bots",
   "author": "Sergio Antonio Trujillo del Valle",
   "main": "src/index.js",
@@ -18,21 +18,24 @@
   "license": "MIT",
   "dependencies": {
     "minio": "^8.0.7",
+    "pg": "^8.11.0",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
-    "sharp": "^0.34.5",
-    "pg": "^8.11.0",
-    "@types/pg": "^8.20.0"
+    "sharp": "^0.34.5"
   },
   "devDependencies": {
     "@commitlint/cli": "^20.5.0",
     "@commitlint/config-conventional": "^20.5.0",
     "@release-it/conventional-changelog": "^10.0.6",
+    "@types/pg": "^8.20.0",
+    "@types/node": "^25.9.1",
     "husky": "^9.1.7",
-    "release-it": "^19.2.4"
+    "release-it": "^19.2.4",
+    "typescript": "^6.0.3"
   },
   "scripts": {
     "prepare": "husky",
+    "typecheck": "tsc --noEmit",
     "release": "release-it"
   }
 }

package/src/capture.js

@@ -1,31 +1,39 @@
 'use strict';
 const sharp = require('sharp');
+const os = require('os');
 
 /**
- * Gestor de capturas de pantalla de la página actual.
+ * Gestor de capturas de pantalla — modo histórico y modo live frame.
+ *
+ * Proporciona:
+ *  - capture()       → captura única con key timestampeda (histórica)
+ *  - captureLive()   → sobrescribe siempre la misma key (live frame)
+ *  - setOffline()    → sube placeholder negro a la key live (agente inactivo)
  */
 class PageCapturer {
   /**
    * @param {object} params
-   * @param {string} params.botId - UUID del bot
+   * @param {string} params.botId - UUID o identificador de la app/bot
    * @param {import('minio').Client} params.minioClient - Cliente MinIO
    * @param {string} params.bucket - Bucket de MinIO
    * @param {import('pino').Logger} [params.logger] - Instancia de Logger
+   * @param {object} [params.redis] - Cliente Redis opcional (ioredis)
    */
-  constructor({ botId, minioClient, bucket, logger }) {
+  constructor({ botId, minioClient, bucket, logger, redis }) {
     this.botId = botId;
     this.minioClient = minioClient;
     this.bucket = bucket;
     this.logger = logger;
+    this.redis = redis;
   }
 
   /**
-   * Captura la página actual y la sube a MinIO con una ruta estructurada.
-   * Estructura: capturas/{botId}/{YYYY-MM-DD}/{nombre}.webp
-   * 
+   * Captura única — sube a MinIO con key timestampeda.
+   * Ruta: capturas/{botId}/{YYYY-MM-DD}/{nombre}.webp
+   *
    * @param {any} page - Instancia de Page (Playwright o Puppeteer)
    * @param {string} nombre - Nombre del elemento/captura
-   * @returns {Promise<string|null>} - Key de la captura en MinIO
+   * @returns {Promise<string|null>}
    */
   async capture(page, nombre) {
     try {
@@ -59,6 +67,168 @@ class PageCapturer {
       return null;
     }
   }
+
+  /**
+   * Live Frame — Captura y SOBRESCRIBE la misma key en MinIO.
+   *
+   * Ruta fija: live/{appId}/{instancia}/{usuario}/live.webp
+   *
+   * Una sola imagen por agente que se actualiza periódicamente
+   * sin acumular archivos. Headers anti-cache + Redis timestamp.
+   *
+   * @param {any} page - Instancia de Page (Playwright o Puppeteer)
+   * @param {object} [opts]
+   * @param {string} [opts.usuario='unknown'] - Identificador del usuario/agente
+   * @param {string} [opts.instancia] - Hostname/pod (default: HOSTNAME)
+   * @param {object} [opts.metadata] - Metadatos adicionales para Redis
+   * @param {boolean} [opts.fullPage=false] - Capturar página completa
+   * @returns {Promise<{key: string, updatedAt: string}|null>}
+   */
+  async captureLive(page, opts = {}) {
+    const usuario = opts.usuario || 'unknown';
+    const instancia = opts.instancia || process.env.HOSTNAME || os.hostname();
+    const metadata = opts.metadata || {};
+    const fullPage = opts.fullPage || false;
+
+    try {
+      const now = new Date();
+      const key = `live/${this.botId}/${instancia}/${usuario}/live.webp`;
+
+      const buffer = await page.screenshot({
+        type: 'jpeg',
+        quality: 80,
+        fullPage,
+      });
+
+      const finalBuffer = await sharp(buffer)
+        .webp({ quality: 70 })
+        .toBuffer();
+
+      // Sobrescribe la misma key con headers anti-cache
+      await this.minioClient.putObject(this.bucket, key, finalBuffer, finalBuffer.length, {
+        'Content-Type': 'image/webp',
+        'Cache-Control': 'no-cache, no-store, must-revalidate',
+        'Pragma': 'no-cache',
+        'Expires': '0',
+      });
+
+      const timestamp = now.toISOString();
+
+      // Actualizar metadata en Redis
+      if (this.redis) {
+        await this.redis.set(`agent:${usuario}:screenshot_updated_at`, timestamp);
+        await this.redis.set(`agent:${usuario}:screenshot_key`, key);
+        await this.redis.set(`agent:${usuario}:status`, 'active');
+        await this.redis.set(`agent:${usuario}:instancia`, instancia);
+        await this.redis.set(`agent:${usuario}:app_id`, this.botId);
+        if (Object.keys(metadata).length > 0) {
+          await this.redis.set(`agent:${usuario}:metadata`, JSON.stringify(metadata));
+        }
+      }
+
+      if (this.logger) {
+        this.logger.info({ key, usuario, instancia }, 'Live screenshot updated');
+      }
+
+      return { key, updatedAt: timestamp };
+    } catch (err) {
+      if (this.logger) {
+        this.logger.error({ err, usuario }, 'Error capturing live screenshot');
+      }
+      return null;
+    }
+  }
+
+  /**
+   * Sustituye la imagen live por un placeholder negro/offline.
+   *
+   * Se llama cuando el bot se pausa, desactiva, o termina su ejecución.
+   * Sobrescribe la misma key live/{appId}/{instancia}/{usuario}/live.webp
+   * para que el frontend refleje automáticamente el estado inactivo.
+   *
+   * @param {object} [opts]
+   * @param {string} [opts.usuario='unknown'] - Identificador del usuario/agente
+   * @param {string} [opts.instancia] - Hostname/pod (default: HOSTNAME)
+   * @returns {Promise<string|null>}
+   */
+  async setOffline(opts = {}) {
+    const usuario = opts.usuario || 'unknown';
+    const instancia = opts.instancia || process.env.HOSTNAME || os.hostname();
+
+    try {
+      const key = `live/${this.botId}/${instancia}/${usuario}/live.webp`;
+
+      // Generar placeholder offline vía SVG (sharp lo rasteriza)
+      let finalBuffer;
+
+      try {
+        const svg = `<svg width="1280" height="900" xmlns="http://www.w3.org/2000/svg">
+          <rect width="1280" height="900" fill="#0a0a0a"/>
+          <style>
+            .t { fill:#333; font-family:sans-serif; font-size:48px; font-weight:bold; text-anchor:middle; }
+            .s { fill:#222; font-family:monospace; font-size:20px; text-anchor:middle; }
+          </style>
+          <text x="640" y="420" class="t">AGENTE INACTIVO</text>
+          <text x="640" y="480" class="s">${usuario}</text>
+          <text x="640" y="520" class="s">${this.botId}</text>
+        </svg>`;
+
+        finalBuffer = await sharp(Buffer.from(svg))
+          .webp({ quality: 50 })
+          .toBuffer();
+      } catch {
+        // Fallback: pixel negro 1x1 si SVG falla
+        finalBuffer = await sharp({
+          create: {
+            width: 1,
+            height: 1,
+            channels: 3,
+            background: { r: 0, g: 0, b: 0 },
+          },
+        }).webp().toBuffer();
+      }
+
+      // Sobrescribe la misma key live con headers anti-cache
+      await this.minioClient.putObject(this.bucket, key, finalBuffer, finalBuffer.length, {
+        'Content-Type': 'image/webp',
+        'Cache-Control': 'no-cache, no-store, must-revalidate',
+        'Pragma': 'no-cache',
+        'Expires': '0',
+      });
+
+      const timestamp = new Date().toISOString();
+
+      // Actualizar Redis
+      if (this.redis) {
+        await this.redis.set(`agent:${usuario}:status`, 'paused');
+        await this.redis.set(`agent:${usuario}:screenshot_updated_at`, timestamp);
+      }
+
+      if (this.logger) {
+        this.logger.info({ key, usuario }, 'Offline placeholder set');
+      }
+
+      return key;
+    } catch (err) {
+      if (this.logger) {
+        this.logger.error({ err, usuario }, 'Error setting offline placeholder');
+      }
+      return null;
+    }
+  }
+
+  /**
+   * Libera recursos (Redis, etc.) — llamar al cerrar el bot.
+   */
+  async destroy() {
+    if (this.redis && typeof this.redis.quit === 'function') {
+      try {
+        await this.redis.quit();
+      } catch {
+        // ignore
+      }
+    }
+  }
 }
 
 module.exports = { PageCapturer };

package/src/credentials.js

@@ -31,6 +31,22 @@ class CredentialManager {
     return rows.length > 0 ? rows[0] : null;
   }
 
+  /**
+   * Obtiene todas las credenciales que coincidan con el nombre y bot ID.
+   * @param {string} nombre - Nombre de la aplicación
+   * @returns {Promise<Array<{nombre: string, usuario: string, password: string, idUsuario: string, status: boolean}>>}
+   */
+  async getAppCredentialsAll(nombre) {
+    const { rows } = await this.pool.query(
+      `SELECT nombre, usuario, password, "idUsuario", status
+         FROM bots.tb_aplicaciones_bots
+        WHERE nombre = $1 AND bot_id = $2`,
+      [nombre, this.botId]
+    );
+
+    return rows;
+  }
+
   /**
    * Actualiza el estado y las observaciones de una aplicación.
    * @param {string} nombre - Nombre de la aplicación
@@ -48,6 +64,7 @@ class CredentialManager {
       );
       return true;
     } catch (err) {
+      console.error(`[Credentials] Error actualizando estado de "${nombre}":`, err.message);
       return false;
     }
   }

package/src/errorCapture.js

@@ -117,6 +117,9 @@ async function captureError({ page, context, err, botId, pool, minioClient, buck
   }
 
   // ── 3. Registro en bots.tb_error_bots ───────────────────────────────────
+  let pageUrl = null;
+  try { pageUrl = page.url(); } catch { /* page already closed */ }
+
   try {
     const { rows } = await pool.query(
       `INSERT INTO bots.tb_error_bots
@@ -127,7 +130,7 @@ async function captureError({ page, context, err, botId, pool, minioClient, buck
         botId,
         step                 ?? null,
         err.message,
-        page.url()           ?? null,
+        pageUrl,
         result.screenshotKey ?? null,
         result.traceKey      ?? null,
       ]
@@ -143,7 +146,7 @@ async function captureError({ page, context, err, botId, pool, minioClient, buck
   logger.error({
     ...stepInfo,
     err,
-    url:            page.url(),
+    url:            pageUrl,
     screenshotKey:  result.screenshotKey,
     traceKey:       result.traceKey,
     errorId:        result.errorId,

package/src/index.d.ts

@@ -1,7 +1,5 @@
 import type { Pool }   from 'pg';
 import type { Logger }  from 'pino';
-import type { Page }    from 'playwright';
-
 export type { Logger };
 
 // ── Opciones de MinIO ────────────────────────────────────────────────────────
@@ -9,11 +7,10 @@ export interface MinioConfig {
   endPoint:   string;
   port?:      number;
   useSSL?:    boolean;
-  accessKey:  string | any;
-  secretKey:  string | any;
-  bucket?:    string | any;
+  accessKey:  string;
+  secretKey:  string;
+  bucket?:    string;
 }
-
 // ── Opciones de screenshot ───────────────────────────────────────────────────
 export interface ScreenshotConfig {
   /** Formato final del archivo en MinIO. Default: 'webp' */
@@ -23,15 +20,28 @@ export interface ScreenshotConfig {
   /** Calidad de captura en Playwright. Default: 90 */
   captureQuality?: number;
 }
-
+// ── Opciones de captura live ─────────────────────────────────────────────────
+export interface CaptureLiveOptions {
+  /** Identificador del usuario/agente */
+  usuario?:   string;
+  /** Hostname/pod (default: HOSTNAME) */
+  instancia?: string;
+  /** Metadatos adicionales para Redis */
+  metadata?:  Record<string, unknown>;
+  /** Capturar página completa */
+  fullPage?:  boolean;
+}
+export interface CaptureLiveResult {
+  key:       string;
+  updatedAt: string;
+}
 // ── Opciones de Pino ─────────────────────────────────────────────────────────
 export interface LogConfig {
-  level?:       'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent' | any;
+  level?:       'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
   /** 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 */
@@ -44,24 +54,22 @@ export interface RpaToolsOptions {
   log?:        LogConfig;
   /** Opciones de captura y compresión de screenshots */
   screenshot?: ScreenshotConfig;
+  /** Cliente Redis opcional (ioredis). Requerido para captureLive/setOffline */
+  redis?:      any;
 }
-
 // ── Objeto retornado por createRpaTools ──────────────────────────────────────
 export interface RpaTools {
   /** Instancia de Pino lista para usar en el bot */
   logger: Logger;
-
   /** Estado compartido del bot */
   state: {
     currentStep: string;
   };
-
   /**
    * Cambia el paso actual, actualiza el estado y emite un log info.
    * @param name - Nombre del nuevo paso
    */
   step: (name: string) => void;
-
   /**
    * Inicia el polling que activa/desactiva screenshots
    * según bot_debug_config en la BD.
@@ -69,13 +77,16 @@ export interface RpaTools {
    * @param pollMs    - Intervalo de polling en ms. Default: 3000
    */
   watchDebugFlag: (page: any, pollMs?: number) => void;
-
   /**
-   * Recupera credenciales de una aplicación desde la base de datos.
+   * Recupera las credenciales de una aplicación desde la base de datos.
    * @param nombre - Nombre de la aplicación (ej. 'Portal CRM')
    */
   getCredentials: (nombre: string) => Promise<{ nombre: string; usuario: string; password: string; idUsuario: string; status: boolean } | null>;
-
+  /**
+   * Recupera TODAS las credenciales que coincidan con el nombre.
+   * @param nombre - Nombre de la aplicación (ej. 'Portal CRM')
+   */
+  getCredentialsAll: (nombre: string) => Promise<Array<{ nombre: string; usuario: string; password: string; idUsuario: string; status: boolean }>>;
   /**
    * Actualiza el estado y las observaciones de una aplicación.
    * @param nombre - Nombre de la aplicación (ej. 'Portal CRM')
@@ -83,20 +94,34 @@ export interface RpaTools {
    * @param observations - Observaciones/Errores
    */
   updateAppStatus: (nombre: string, status: boolean, observations: string) => Promise<boolean>;
-
   /**
    * Consulta si el bot está activo en la base de datos (columna 'estado').
    * @returns {Promise<boolean>}
    */
   isActive: () => Promise<boolean>;
-
   /**
-   * Captura el estado de la página actual y lo sube a MinIO.
+   * Captura única — sube a MinIO con key timestampeda.
    * @param page - Instancia de Page (Playwright o Puppeteer)
    * @param nombre - Nombre del elemento/captura
    */
   capturePage: (page: any, nombre: string) => Promise<string | null>;
-
+  /**
+   * Live Frame — Captura y sobrescribe la misma key en MinIO.
+   * Una imagen por (appId, instancia, usuario). Headers anti-cache.
+   *
+   * Requiere redis configurado en createRpaTools().
+   *
+   * @param page - Instancia de Page
+   * @param opts - Opciones de captura (usuario, instancia, metadata)
+   */
+  captureLive: (page: any, opts?: CaptureLiveOptions) => Promise<CaptureLiveResult | null>;
+  /**
+   * Sustituye la imagen live por un placeholder negro/offline.
+   * Se llama cuando el bot se pausa, desactiva, o termina.
+   *
+   * @param opts - Opciones (usuario, instancia)
+   */
+  setOffline: (opts?: { usuario?: string; instancia?: string }) => Promise<string | null>;
   /**
    * Captura screenshot, trace y registra error en base de datos.
    */
@@ -106,11 +131,9 @@ export interface RpaTools {
     err: Error;
     step?: string;
   }) => Promise<{ errorId: number | null; screenshotKey: string | null; traceKey: string | null }>;
-
   /** Detiene todos los intervalos. Llamar siempre al cerrar el bot. */
   destroy: () => void;
 }
-
 // ── Export principal ─────────────────────────────────────────────────────────
 /**
  * Inicializa la librería rpa-tools.

package/src/index.js

@@ -10,12 +10,14 @@ const { PageCapturer }                      = require('./capture');
  * Factory principal de la librería.
  *
  * @param {object} opts
- * @param {string}  opts.botId          - identificador único del bot
+ * @param {string}  opts.botId          - identificador único del bot/app
  * @param {import('pg').Pool} opts.db   - pool de pg ya conectado
  * @param {object}  opts.minio          - config de MinIO
  * @param {object}  [opts.log]          - opciones de Pino
+ * @param {object}  [opts.screenshot]   - opciones de captura (formato, calidad)
+ * @param {object}  [opts.redis]        - cliente Redis opcional (ioredis)
  *
- * @returns {{ logger, state, step, watchDebugFlag, getCredentials, updateAppStatus, isActive, capturePage, captureError, destroy }}
+ * @returns {Promise<{ logger, state, step, watchDebugFlag, getCredentials, getCredentialsAll, updateAppStatus, isActive, capturePage, captureLive, setOffline, captureError, destroy }>}
  */
 async function createRpaTools(opts = {}) {
   const {
@@ -23,6 +25,8 @@ async function createRpaTools(opts = {}) {
     log:  logCfg = {},
     db,
     minio: minioCfg,
+    screenshot: screenshotCfg,
+    redis: redisClient,
   } = opts;
 
   const minio = minioCfg ?? {
@@ -44,9 +48,9 @@ async function createRpaTools(opts = {}) {
   await ensureBucket(minioClient, bucket);
   logger.info({ bucket }, 'MinIO listo');
 
-  const watcher     = new ScreenshotWatcher({ botId, pool: db, minioClient, bucket, logger });
+  const watcher     = new ScreenshotWatcher({ botId, pool: db, minioClient, bucket, logger, screenshot: screenshotCfg });
   const credentials = new CredentialManager({ botId, pool: db });
-  const capturer    = new PageCapturer({ botId, minioClient, bucket, logger });
+  const capturer    = new PageCapturer({ botId, minioClient, bucket, logger, redis: redisClient });
 
   const state = { currentStep: 'Inicio' };
 
@@ -55,7 +59,7 @@ async function createRpaTools(opts = {}) {
     state,
     step: (name) => {
       state.currentStep = name;
-      logger.info(name + ' - Nuevo paso');
+      logger.info({ step: name }, 'Nuevo paso');
     },
     /**
      * Inicia el polling que activa/desactiva screenshots según bot_debug_config.
@@ -64,6 +68,7 @@ async function createRpaTools(opts = {}) {
      */
     watchDebugFlag: (page, pollMs) => watcher.watch(page, pollMs),
     getCredentials: (nombre) => credentials.getAppCredentials(nombre),
+    getCredentialsAll: (nombre) => credentials.getAppCredentialsAll(nombre),
     updateAppStatus: (nombre, status, observations) => credentials.updateAppStatus(nombre, status, observations),
     /**
      * Consulta si el bot está activo en la base de datos (columna 'estado').
@@ -82,14 +87,34 @@ async function createRpaTools(opts = {}) {
       }
     },
     /**
-     * Captura el estado de la página actual y lo sube a MinIO.
+     * Captura única — sube a MinIO con key timestampeda.
      * @param {any} page - Instancia de Page
      * @param {string} nombre - Nombre del elemento/captura
      */
     capturePage: (page, nombre) => capturer.capture(page, nombre),
     /**
-     * Captura screenshot y registra error en base de datos. 
-     * Soporta Playwright (con tracing opcional) y Puppeteer.
+     * Live Frame — Captura y sobrescribe la misma key en MinIO.
+     * Una imagen por (appId, instancia, usuario). Headers anti-cache.
+     *
+     * @param {any} page - Instancia de Page (Playwright o Puppeteer)
+     * @param {object} [opts]
+     * @param {string} [opts.usuario] - Identificador del usuario/agente
+     * @param {string} [opts.instancia] - Hostname/pod
+     * @param {object} [opts.metadata] - Metadatos para Redis
+     * @param {boolean} [opts.fullPage] - Capturar página completa
+     * @returns {Promise<{key: string, updatedAt: string}|null>}
+     */
+    captureLive: (page, opts) => capturer.captureLive(page, opts),
+    /**
+     * Sustituye la imagen live por un placeholder offline.
+     * @param {object} [opts]
+     * @param {string} [opts.usuario] - Identificador del usuario/agente
+     * @param {string} [opts.instancia] - Hostname/pod
+     * @returns {Promise<string|null>}
+     */
+    setOffline: (opts) => capturer.setOffline(opts),
+    /**
+     * Captura screenshot y registra error en base de datos.
      */
     captureError: ({ page, context, err, step }) => captureError({
       page,
@@ -102,7 +127,10 @@ async function createRpaTools(opts = {}) {
       bucket,
       logger
     }),
-    destroy: () => watcher.destroy(),
+    destroy: () => {
+      watcher.destroy();
+      capturer.destroy().catch(() => {});
+    },
   };
 }
 

package/src/storage.js

@@ -1,6 +1,15 @@
 'use strict';
 const Minio = require('minio');
 const sharp = require('sharp');
+const os = require('os');
+
+/**
+ * Retorna el identificador de la instancia actual (pod en K8s).
+ * En Kubernetes se usa process.env.HOSTNAME (nombre del pod).
+ */
+function getInstanceId() {
+  return process.env.HOSTNAME || os.hostname();
+}
 
 /**
  * Crea y retorna el cliente de MinIO.
@@ -49,6 +58,10 @@ async function toWebp(buffer, quality = 70) {
  * Si format='webp' convierte el buffer antes de subir.
  * Ruta generada: {botId}/{YYYY-MM-DD}/{ISO-timestamp}.{ext}
  *
+ * En BD guarda un arreglo JSONB en url_screenshot con la estructura:
+ *   [{ instancia: string, url: string, timestamp: string }]
+ * Cada instancia (pod) actualiza su propia entrada.
+ *
  * @param {import('minio').Client} client
  * @param {string} bucket
  * @param {string} botId
@@ -58,10 +71,11 @@ async function toWebp(buffer, quality = 70) {
  * @param {number}         [opts.quality=70]      - calidad 1-100
  * @param {object}         [opts.pool]            - Pool de base de datos
  * @param {object}         [opts.logger]          - Instancia de logger
+ * @param {string}         [opts.instancia]       - ID de instancia (default: HOSTNAME)
  * @returns {Promise<string>}   - object key en MinIO
  */
 async function uploadScreenshot(client, bucket, botId, buffer, opts = {}) {
-  const { format = 'webp', quality = 70, pool, logger } = opts;
+  const { format = 'webp', quality = 70, pool, logger, instancia = getInstanceId() } = opts;
 
   const finalBuffer = format === 'webp'
     ? await toWebp(buffer, quality)
@@ -69,29 +83,55 @@ async function uploadScreenshot(client, bucket, botId, buffer, opts = {}) {
 
   const contentType = format === 'webp' ? 'image/webp' : 'image/jpeg';
   const ext         = format === 'webp' ? 'webp' : 'jpg';
-  const key  = `${botId}.${ext}`;
+  const now  = new Date();
+  const date = now.toISOString().slice(0, 10);
+  const ts   = now.toISOString().replace(/[:.]/g, '-');
+  const key  = `capturas/${botId}/${date}/${ts}.${ext}`;
 
   await client.putObject(bucket, key, finalBuffer, finalBuffer.length, {
     'Content-Type': contentType,
   });
 
-  // ── 3. Registro en base de datos ─────────────────────────────────────────
+  // ── 3. Registro en base de datos (arreglo JSONB por instancia) ──────────
   if (pool) {
+    const pgClient = await pool.connect();
     try {
-      await pool.query(
+      await pgClient.query('BEGIN');
+
+      const { rows } = await pgClient.query(
+        `SELECT url_screenshot FROM bots.tb_bots WHERE id = $1::uuid FOR UPDATE`,
+        [botId]
+      );
+
+      const actual = (rows[0]?.url_screenshot || []);
+      const idx = actual.findIndex(e => e.instancia === instancia);
+
+      const entry = { instancia, url: key, timestamp: now.toISOString() };
+
+      if (idx >= 0) {
+        actual[idx] = entry;
+      } else {
+        actual.push(entry);
+      }
+
+      await pgClient.query(
         `UPDATE bots.tb_bots
-         SET url_screenshot = $1,
-             updated_at = NOW()
-         WHERE id = $2::uuid`,
-        [key, botId]
+            SET url_screenshot = $1::jsonb,
+                updated_at = NOW()
+          WHERE id = $2::uuid`,
+        [JSON.stringify(actual), botId]
       );
-      
+
+      await pgClient.query('COMMIT');
     } catch (err) {
+      await pgClient.query('ROLLBACK').catch(() => {});
       if (logger) {
-        logger.error({ err, botId, key }, 'No se pudo actualizar url_screenshot en BD');
+        logger.error({ err, botId, key, instancia }, 'No se pudo actualizar url_screenshot en BD');
       } else {
         console.error(`[Storage] Error BD (${botId}):`, err.message);
       }
+    } finally {
+      pgClient.release();
     }
   }