@arela/uploader 1.0.24 → 1.1.1

package/docs/SMART_WATCH_DATABASE_CHANGES.md

@@ -0,0 +1,502 @@
+# Smart Watch Database Service Changes
+
+## 📋 Resumen de Cambios
+
+Se han agregado **13 nuevos métodos** al `DatabaseService.js` para soportar la cola inteligente de procesamiento (Smart Watch Queue).
+
+### ✅ Métodos Agregados
+
+#### 1. `insertFileToUploader(filePath, options)`
+Inserta un archivo con estado inicial PENDING o READY_TO_UPLOAD.
+
+**Parámetros:**
+- `filePath` (string): Ruta completa del archivo
+- `options` (object):
+  - `processingStatus` (string): 'PENDING' o 'READY_TO_UPLOAD' (default: 'PENDING')
+  - `dependsOnPath` (string): Ruta del directorio padre
+  - `documentType` (string): Tipo de documento
+  - `size` (number): Tamaño del archivo en bytes
+  - `fileExtension` (string): Extensión del archivo
+
+**Ejemplo:**
+```javascript
+const file = await databaseService.insertFileToUploader('/path/to/file.pdf', {
+  processingStatus: 'PENDING',
+  dependsOnPath: '../../Documents/2023',
+  size: 1024,
+  fileExtension: 'pdf'
+});
+```
+
+#### 2. `getPendingFilesInDirectory(dirPath)`
+Obtiene archivos que esperan por un pedimento simplificado.
+
+**Parámetros:**
+- `dirPath` (string): Ruta del directorio
+
+**Retorna:** Array de archivos con status PENDING
+
+**Ejemplo:**
+```javascript
+const pendingFiles = await databaseService.getPendingFilesInDirectory(
+  '../../Documents/2023'
+);
+console.log(`${pendingFiles.length} files waiting for pedimento`);
+```
+
+#### 3. `getFilesWithStatus(statuses, limit)`
+Obtiene archivos con ciertos status.
+
+**Parámetros:**
+- `statuses` (array): Array de status a buscar
+- `limit` (number): Máximo de resultados (default: 10)
+
+**Ejemplo:**
+```javascript
+const ready = await databaseService.getFilesWithStatus(
+  ['READY_TO_UPLOAD', 'PROCESSING'],
+  10
+);
+```
+
+#### 4. `updateFileStatus(filePath, updates)`
+Actualiza el estado y otros campos de un archivo.
+
+**Parámetros:**
+- `filePath` (string): Ruta original del archivo
+- `updates` (object): Campos a actualizar
+
+**Ejemplo:**
+```javascript
+await databaseService.updateFileStatus(filePath, {
+  processing_status: 'UPLOADED',
+  upload_attempts: 1
+});
+```
+
+#### 5. `markPedimentoDetected(dirPath, pedimentoPath)`
+Marca un pedimento como detectado y actualiza archivos pendientes automáticamente.
+
+**Parámetros:**
+- `dirPath` (string): Ruta del directorio
+- `pedimentoPath` (string): Ruta del archivo pedimento
+
+**Comportamiento Automático:**
+- Marca el pedimento como READY_TO_UPLOAD
+- Obtiene todos los PENDING en `dirPath`
+- Actualiza todos los PENDING a READY_TO_UPLOAD
+- Registra el timestamp de detección
+
+**Ejemplo:**
+```javascript
+await databaseService.markPedimentoDetected(
+  '../../Documents/2023',
+  '../../Documents/2023/3429-07-23021611-Simplif.pdf'
+);
+// Automáticamente marca todos los PENDING como READY_TO_UPLOAD
+```
+
+#### 6. `getExpiredWaitingFiles(maxWaitTimeSeconds)`
+Obtiene archivos que esperan demasiado sin pedimento (archivos huérfanos).
+
+**Parámetros:**
+- `maxWaitTimeSeconds` (number): Tiempo máximo de espera en segundos
+
+**Ejemplo:**
+```javascript
+const expired = await databaseService.getExpiredWaitingFiles(300); // 5 minutos
+if (expired.length > 0) {
+  console.log(`Found ${expired.length} orphaned files`);
+}
+```
+
+#### 7. `getProcessingStats()`
+Obtiene estadísticas generales de la cola.
+
+**Retorna:** Object con conteos por status
+
+**Ejemplo:**
+```javascript
+const stats = await databaseService.getProcessingStats();
+console.log(`
+  Pending: ${stats.pending}
+  Ready: ${stats.readyToUpload}
+  Processing: ${stats.processing}
+  Uploaded: ${stats.uploaded}
+  Failed: ${stats.failed}
+  Total: ${stats.total}
+`);
+```
+
+#### 8. `getFailedFilesForRetry(maxAttempts)`
+Obtiene archivos fallidos listos para reintentar.
+
+**Parámetros:**
+- `maxAttempts` (number): Máximo número de intentos permitidos (default: 3)
+
+**Ejemplo:**
+```javascript
+const toRetry = await databaseService.getFailedFilesForRetry(3);
+console.log(`${toRetry.length} files ready for retry`);
+```
+
+#### 9. `retryFile(filePath)`
+Reinicia un archivo fallido individual.
+
+**Parámetros:**
+- `filePath` (string): Ruta del archivo
+
+**Comportamiento:**
+- Cambia status a READY_TO_UPLOAD
+- Reinicia upload_attempts a 0
+- Limpia last_error
+
+**Ejemplo:**
+```javascript
+const retried = await databaseService.retryFile('../../Documents/2023/file.pdf');
+console.log(`File retried: ${retried.filename}`);
+```
+
+#### 10. `retryFailedFiles(limit, maxAttempts)`
+Reinicia múltiples archivos fallidos de forma eficiente.
+
+**Parámetros:**
+- `limit` (number): Cantidad máxima a reintentar (default: 10)
+- `maxAttempts` (number): Máximo número de intentos (default: 3)
+
+**Retorna:** Object con `{ retried, skipped, files }`
+
+**Ejemplo:**
+```javascript
+const result = await databaseService.retryFailedFiles(10, 3);
+console.log(`✅ Retried: ${result.retried}, ❌ Skipped: ${result.skipped}`);
+```
+
+#### 11. `getOverallProgress()`
+Obtiene progreso general con estimación de tiempo.
+
+**Retorna:** Object con:
+- `totalFiles`: Total de archivos
+- `processedFiles`: Archivos subidos exitosamente
+- `failedFiles`: Archivos con error
+- `pendingFiles`: Archivos pendientes/procesando
+- `percentComplete`: Porcentaje completado
+- `estimatedTimeRemaining`: ETA estimada
+- `avgProcessingTimeMs`: Tiempo promedio de procesamiento
+
+**Ejemplo:**
+```javascript
+const progress = await databaseService.getOverallProgress();
+console.log(`Progress: ${progress.percentComplete}%`);
+console.log(`ETA: ${progress.estimatedTimeRemaining}`);
+console.log(`Success rate: ${
+  (progress.processedFiles / progress.totalFiles * 100).toFixed(2)
+}%`);
+```
+
+#### 12. `getFileDetails(filePath)`
+Obtiene detalles completos de un archivo.
+
+**Parámetros:**
+- `filePath` (string): Ruta del archivo
+
+**Retorna:** Object con todos los campos + información adicional
+
+**Ejemplo:**
+```javascript
+const details = await databaseService.getFileDetails(filePath);
+console.log(`
+  Filename: ${details.filename}
+  Status: ${details.processing_status}
+  Time in queue: ${details.timeInQueue}
+  Attempts: ${details.attempts}
+  Has error: ${details.hasError}
+`);
+```
+
+#### 13. `searchFiles(filters)`
+Busca archivos por múltiples criterios.
+
+**Parámetros:**
+- `filters` (object):
+  - `status` (string): Status a buscar
+  - `rfc` (string): RFC del remitente
+  - `year` (number): Año
+  - `dirPath` (string): Ruta del directorio
+  - `numPedimento` (string): Número de pedimento (búsqueda parcial)
+  - `limit` (number): Máximo de resultados (default: 50)
+
+**Ejemplo:**
+```javascript
+const results = await databaseService.searchFiles({
+  status: 'FAILED',
+  rfc: 'AUM9207011CA',
+  year: 2023,
+  limit: 50
+});
+```
+
+## 🔄 Flujo de Procesamiento
+
+### Escenario Típico
+
+```javascript
+// 1. Archivo nuevo detectado en el directorio
+const file = await databaseService.insertFileToUploader(
+  filePath,
+  { 
+    processingStatus: 'PENDING',
+    dependsOnPath: dirPath 
+  }
+);
+console.log(`✅ Archivo registrado: ${file.filename}`);
+
+// 2. Esperando pedimento simplificado
+const pending = await databaseService.getPendingFilesInDirectory(dirPath);
+console.log(`⏳ Esperando: ${pending.length} archivos`);
+
+// 3. Se detecta pedimento simplificado
+await databaseService.markPedimentoDetected(dirPath, pedimentoPath);
+// ↓ Automáticamente marca PENDING → READY_TO_UPLOAD
+
+// 4. Obtener archivos listos para procesar
+const ready = await databaseService.getFilesWithStatus(['READY_TO_UPLOAD'], 10);
+console.log(`✅ Listos: ${ready.length} archivos`);
+
+// 5. Actualizar a PROCESSING
+await databaseService.updateFileStatus(filePath, {
+  processing_status: 'PROCESSING'
+});
+
+// 6. Actualizar a UPLOADED (éxito)
+await databaseService.updateFileStatus(filePath, {
+  processing_status: 'UPLOADED',
+  upload_attempts: 1
+});
+console.log(`✅ Subido: ${filePath}`);
+
+// 7. Si hay error → FAILED
+await databaseService.updateFileStatus(filePath, {
+  processing_status: 'FAILED',
+  last_error: 'Timeout uploading to server',
+  upload_attempts: 1
+});
+
+// 8. Reintentar más tarde
+const retried = await databaseService.retryFile(filePath);
+console.log(`🔄 Reintentando: ${filePath}`);
+```
+
+## 📊 Estados de Archivo
+
+```
+┌─────────┐
+│ PENDING │  ← Archivo nuevo, esperando pedimento simplificado
+└────┬────┘
+     │
+     │ [Pedimento detectado → markPedimentoDetected()]
+     ↓
+┌──────────────────┐
+│ READY_TO_UPLOAD  │  ← Listo para procesar
+└────┬─────────────┘
+     │
+     │ [Comienza procesamiento → updateFileStatus('PROCESSING')]
+     ↓
+┌────────────┐
+│ PROCESSING │  ← Siendo procesado
+└────┬───────┘
+     │
+     ├─→ [Éxito]  ┌──────────┐
+     │            │ UPLOADED │  ✅ Completado
+     │            └──────────┘
+     │
+     └─→ [Error]  ┌────────┐
+                  │ FAILED │  ❌ Con error
+                  └───┬────┘
+                      │
+                      │ [Reintentar → retryFile()]
+                      ↓
+                  READY_TO_UPLOAD (reinicio del ciclo)
+```
+
+## 🛡️ Manejo de Errores
+
+Todos los métodos incluyen:
+- **Retry lógico** con exponential backoff (hasta 30 segundos)
+- **Error logging** detallado con contexto
+- **Transacciones seguras** (no hay datos parciales)
+- **Validaciones** de parámetros
+- **Recuperación automática** en caso de timeout
+
+## 📈 Casos de Uso
+
+### Monitoreo en Tiempo Real
+```javascript
+setInterval(async () => {
+  const stats = await databaseService.getProcessingStats();
+  const progress = await databaseService.getOverallProgress();
+
+  console.log(`📊 Stats:`);
+  console.log(`  Progreso: ${progress.percentComplete}%`);
+  console.log(`  ETA: ${progress.estimatedTimeRemaining}`);
+  console.log(`  Pendientes: ${progress.pendingFiles}`);
+  console.log(`  Fallidos: ${progress.failedFiles}`);
+}, 5000); // Cada 5 segundos
+```
+
+### Limpieza de Archivos Huérfanos (Orfanage Cleanup)
+```javascript
+// Ejecutar cada 30 minutos
+setInterval(async () => {
+  const expired = await databaseService.getExpiredWaitingFiles(1800); // 30 minutos
+  
+  if (expired.length > 0) {
+    console.log(`🗑️ Limpiando ${expired.length} archivos huérfanos...`);
+    
+    for (const file of expired) {
+      await databaseService.updateFileStatus(file.original_path, {
+        processing_status: 'FAILED',
+        last_error: 'Expired waiting for pedimento (30 minutes)'
+      });
+    }
+  }
+}, 1800000); // 30 minutos
+```
+
+### Reintentos Automáticos
+```javascript
+// Ejecutar cada 10 minutos
+setInterval(async () => {
+  const result = await databaseService.retryFailedFiles(10, 3);
+  
+  if (result.retried > 0) {
+    console.log(`🔄 Retrying ${result.retried} files...`);
+  }
+}, 600000); // 10 minutos
+```
+
+### Búsqueda Avanzada
+```javascript
+// Buscar todos los archivos fallidos de un RFC en 2023
+const files = await databaseService.searchFiles({
+  rfc: 'AUM9207011CA',
+  year: 2023,
+  status: 'FAILED'
+});
+
+console.log(`Found ${files.length} failed files for RFC ${rfc}`);
+files.forEach(f => {
+  console.log(`- ${f.filename}: ${f.last_error}`);
+});
+```
+
+### Dashboard con Estadísticas
+```javascript
+async function getDashboardData() {
+  const [stats, progress, failedFiles] = await Promise.all([
+    databaseService.getProcessingStats(),
+    databaseService.getOverallProgress(),
+    databaseService.getFailedFilesForRetry()
+  ]);
+
+  return {
+    stats,
+    progress,
+    failedCount: failedFiles.length,
+    successRate: (
+      progress.processedFiles / progress.totalFiles * 100
+    ).toFixed(2) + '%'
+  };
+}
+```
+
+## 🔗 Integración con SmartWatchService
+
+El DatabaseService se usa desde SmartWatchService:
+
+```javascript
+// En SmartWatchService.js
+class SmartWatchService {
+  async handleNewFile(filePath) {
+    const isPedimento = await this.#isPedimentoSimplificado(filePath);
+    const parentDir = path.dirname(filePath);
+
+    if (isPedimento) {
+      // Insertar pedimento y marcar dependientes como READY
+      await this.databaseService.markPedimentoDetected(parentDir, filePath);
+      logger.info(`✅ Pedimento detected, ${pending.length} files ready`);
+    } else {
+      // Insertar archivo como PENDING
+      await this.databaseService.insertFileToUploader(filePath, {
+        processingStatus: 'PENDING',
+        dependsOnPath: parentDir,
+        size: fs.statSync(filePath).size,
+        fileExtension: path.extname(filePath).slice(1)
+      });
+      logger.info(`⏳ File registered as PENDING`);
+    }
+  }
+
+  async processReadyFiles() {
+    const ready = await this.databaseService.getFilesWithStatus(
+      ['READY_TO_UPLOAD'],
+      10
+    );
+
+    for (const file of ready) {
+      try {
+        await this.databaseService.updateFileStatus(file.original_path, {
+          processing_status: 'PROCESSING'
+        });
+
+        const result = await this.uploadService.upload(file);
+
+        await this.databaseService.updateFileStatus(file.original_path, {
+          processing_status: 'UPLOADED',
+          upload_attempts: (file.upload_attempts || 0) + 1
+        });
+      } catch (error) {
+        await this.databaseService.updateFileStatus(file.original_path, {
+          processing_status: 'FAILED',
+          last_error: error.message,
+          upload_attempts: (file.upload_attempts || 0) + 1
+        });
+      }
+    }
+  }
+}
+```
+
+## 📚 Tablas y Campos Soportados
+
+### Tabla: `uploader`
+
+**Campos utilizados por Smart Watch:**
+- `original_path` (varchar): Ruta completa del archivo
+- `filename` (varchar): Nombre del archivo
+- `file_extension` (varchar): Extensión (.pdf, .xml, etc.)
+- `size` (bigint): Tamaño en bytes
+- `document_type` (varchar): Tipo de documento
+- `processing_status` (varchar): PENDING | READY_TO_UPLOAD | PROCESSING | UPLOADED | FAILED
+- `depends_on_path` (varchar): Referencia al directorio del pedimento
+- `pedimento_detected_at` (timestamp): Cuándo se detectó el pedimento
+- `upload_attempts` (integer): Número de intentos
+- `last_error` (text): Último mensaje de error
+- `created_at` (timestamp): Fecha de creación
+- `updated_at` (timestamp): Última actualización
+- `status` (varchar): Legacy field (pendiente, en_progreso, completado, fallido)
+
+## ✅ Validación
+
+- Todos los métodos pasan validación de sintaxis Node.js
+- Incluyen error handling robusto con retry logic
+- Compatible con Supabase JS client (v1.x y v2.x)
+- Logs detallados para debugging
+- No hay breaking changes en métodos existentes
+
+## 🚀 Próximos Pasos
+
+1. **Integración con SmartWatchService** - Usar estos métodos en el watch service
+2. **Estadísticas en API** - Exponer endpoints REST para las estadísticas
+3. **Dashboard** - Crear UI para monitoreo en tiempo real
+4. **Alertas** - Notificaciones cuando hay archivos expirados o con errores

package/docs/TESTING_WATCH_MODE.md

@@ -0,0 +1,212 @@
+# 🧪 Testing Manual: Watch Mode - Fase 2
+
+## Preparación del Entorno
+
+```bash
+# Crear directorio de prueba
+mkdir -p /tmp/watch-test
+cd /tmp/watch-test
+
+# Crear archivo inicial
+echo "Test document" > test-document.txt
+```
+
+## Test 1: Watch Mode Básico (Strategy: batch)
+
+```bash
+# Terminal 1: Iniciar watch mode
+cd /Users/jjfigueroa/gitRepos/arela-uploader
+node src/index.js watch --directories /tmp/watch-test --strategy batch --debounce 500 --verbose
+
+# Terminal 2: Crear archivos de prueba
+cd /tmp/watch-test
+
+# Crear un archivo nuevo
+echo "New file content" > new-file.txt
+
+# Esperar a ver el evento procesado en Terminal 1
+
+# Crear otro archivo
+echo "Another file" > another-file.txt
+
+# Modificar archivo existente
+echo "Modified content" >> new-file.txt
+
+# Esperar a ver eventos en Terminal 1
+```
+
+## Test 2: Strategy Individual
+
+```bash
+# Terminal 1: Iniciar con strategy individual
+cd /Users/jjfigueroa/gitRepos/arela-uploader
+node src/index.js watch --directories /tmp/watch-test --strategy individual --debounce 500 --verbose
+
+# Terminal 2: Crear archivo
+cd /tmp/watch-test
+echo "Single file test" > single-test.txt
+
+# Esperar a ver que SOLO este archivo se procesa
+```
+
+## Test 3: Strategy Full-Structure
+
+```bash
+# Crear estructura de directorios
+mkdir -p /tmp/watch-test/documents/folder1
+mkdir -p /tmp/watch-test/documents/folder2
+
+echo "File 1" > /tmp/watch-test/documents/folder1/file1.txt
+echo "File 2" > /tmp/watch-test/documents/folder2/file2.txt
+
+# Terminal 1: Iniciar con strategy full-structure
+cd /Users/jjfigueroa/gitRepos/arela-uploader
+node src/index.js watch --directories /tmp/watch-test/documents --strategy full-structure --debounce 1000 --verbose
+
+# Terminal 2: Crear un nuevo archivo en subfolder
+cd /tmp/watch-test/documents/folder1
+echo "New test file" > test-new.txt
+
+# Esperar a ver que TODA la estructura se procesa
+```
+
+## Test 4: Multiple Directories
+
+```bash
+# Crear más directorio de prueba
+mkdir -p /tmp/watch-test2
+echo "Test" > /tmp/watch-test2/test.txt
+
+# Terminal 1: Watch múltiples directorios
+cd /Users/jjfigueroa/gitRepos/arela-uploader
+node src/index.js watch --directories /tmp/watch-test,/tmp/watch-test2 --strategy batch --verbose
+
+# Terminal 2: Crear archivos en ambas carpetas
+echo "File in test1" > /tmp/watch-test/file1.txt
+echo "File in test2" > /tmp/watch-test2/file2.txt
+
+# Esperar a ver eventos de ambos directorios
+```
+
+## Test 5: Dry-Run Mode
+
+```bash
+# Terminal 1: Iniciar en modo dry-run
+cd /Users/jjfigueroa/gitRepos/arela-uploader
+node src/index.js watch --directories /tmp/watch-test --strategy batch --dry-run --verbose
+
+# Terminal 2: Crear archivo
+cd /tmp/watch-test
+echo "Dry run test" > dry-test.txt
+
+# Esperar a ver "[DRY RUN]" en los logs - no debe hacer upload real
+```
+
+## Test 6: Debouncing (Verificar que agrupa eventos)
+
+```bash
+# Terminal 1: Iniciar watch con debounce de 2 segundos
+cd /Users/jjfigueroa/gitRepos/arela-uploader
+node src/index.js watch --directories /tmp/watch-test --strategy batch --debounce 2000 --verbose
+
+# Terminal 2: Crear múltiples archivos rápidamente
+cd /tmp/watch-test
+for i in {1..5}; do
+  echo "File $i" > test-$i.txt
+  sleep 0.2  # 200ms entre archivos
+done
+
+# Esperar 2 segundos
+# Debería ver un ÚNICO evento que agrupa los 5 archivos
+```
+
+## Test 7: Graceful Shutdown
+
+```bash
+# Terminal 1: Iniciar watch mode
+cd /Users/jjfigueroa/gitRepos/arela-uploader
+node src/index.js watch --directories /tmp/watch-test --verbose
+
+# Terminal 2: Crear archivo mientras está corriendo
+cd /tmp/watch-test
+echo "Test" > test.txt
+
+# Terminal 1: Presionar Ctrl+C
+
+# Esperar a ver:
+# - "🛑 Received SIGINT, shutting down gracefully..."
+# - "🔴 Stopping WatchService..."
+# - "✅ WatchService stopped"
+# - Resumen final con estadísticas
+```
+
+## Test 8: Ignorar Patrones
+
+```bash
+# Terminal 1: Iniciar watch ignorando archivos .tmp
+cd /Users/jjfigueroa/gitRepos/arela-uploader
+node src/index.js watch --directories /tmp/watch-test --ignore "*.tmp,*.bak" --verbose
+
+# Terminal 2: Crear archivos para ignorar
+cd /tmp/watch-test
+echo "Should be ignored" > file.tmp
+echo "Also ignored" > file.bak
+echo "Should be captured" > file.txt
+
+# Esperar: solo file.txt debe generar evento
+```
+
+## Puntos a Verificar en los Tests
+
+### Logs Esperados:
+- ✅ "🟢 WATCH MODE STARTED"
+- ✅ "📁 Watching X director(y/ies):"
+- ✅ "⚡ Processing event:"
+- ✅ "📤 [STRATEGY] Upload triggered by:"
+- ✅ "✅ Files queued for upload"
+- ✅ "📊 Stats:"
+
+### Eventos Esperados:
+- `add` - Cuando se crea un archivo nuevo
+- `change` - Cuando se modifica un archivo
+- `unlink` - Cuando se elimina un archivo (debería ignorarse)
+
+### Debouncing:
+- Múltiples cambios rápidos = 1 evento procesado
+- Esperar = nuevo evento procesado
+
+### Graceful Shutdown:
+- Ctrl+C debería cerrar cleanly
+- Ver resumen final con estadísticas
+- Sin errores no capturados
+
+## Comandos Útiles para Limpieza
+
+```bash
+# Limpiar directorio de prueba
+rm -rf /tmp/watch-test
+rm -rf /tmp/watch-test2
+
+# Ver archivos siendo creados en tiempo real
+ls -la /tmp/watch-test
+
+# Monitorear cambios de archivos en otra terminal
+fswatch /tmp/watch-test  # Requiere 'brew install fswatch' en macOS
+```
+
+## Comandos para Desarrollar
+
+```bash
+# Ejecutar linter
+npm run format
+
+# Ver logs en detalle
+node src/index.js watch --directories /tmp/watch-test --verbose --clear-log
+
+# Ver solo directorios siendo observados
+node src/index.js watch --directories /tmp/watch-test --verbose | grep "📁"
+```
+
+---
+
+**Nota**: Los tests pueden ejecutarse en serie o en paralelo según sea necesario. Cada test es independiente pero usa los mismos directorios (/tmp/watch-test) que pueden necesitar cleanup entre tests.