@arela/uploader 1.0.24 → 1.1.1

package/docs/WATCHER_SETUP_GUIDE.md

@@ -0,0 +1,614 @@
+# 🚀 Guía Paso a Paso: Integrar Watcher con arela-api
+
+## 📌 Objetivo Final
+Permitir que el frontend monitoree el estado del watcher en tiempo real a través de endpoints REST en la arela-api.
+
+---
+
+## ✅ Pasos de Implementación
+
+### **Paso 1: Preparar arela-uploader para exportar WatchService**
+
+#### 1.1 Crear archivo de exportaciones
+
+Crear: `src/services/index.js`
+
+```javascript
+// Exportar todos los servicios disponibles públicamente
+export { default as watchService } from './WatchService.js';
+export { default as databaseService } from './DatabaseService.js';
+export { default as autoProcessingService } from './AutoProcessingService.js';
+export { default as logger } from './LoggingService.js';
+```
+
+#### 1.2 Actualizar package.json de arela-uploader
+
+Agregar campo `exports`:
+
+```json
+{
+  "name": "arela-uploader",
+  "version": "1.0.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./services": "./src/services/index.js",
+    "./commands": "./src/commands/index.js"
+  },
+  "main": "./src/index.js"
+}
+```
+
+✅ **Resultado:** Otros módulos pueden hacer:
+```javascript
+import { watchService } from 'arela-uploader/services';
+```
+
+---
+
+### **Paso 2: Preparar arela-api para usar WatchService**
+
+#### 2.1 Instalar dependencia de arela-uploader
+
+En el directorio `arela-api`:
+
+```bash
+# Opción A: Instalar desde ruta local
+npm install ../arela-uploader
+
+# Opción B: Si está publicado en npm
+npm install arela-uploader
+```
+
+#### 2.2 Crear carpeta de rutas si no existe
+
+```bash
+mkdir -p src/routes
+```
+
+#### 2.3 Crear archivo de rutas del watcher
+
+Crear: `arela-api/src/routes/watcher.routes.js`
+
+**Copiar contenido completo del archivo en `WATCHER_API_IMPLEMENTATION.md`**
+
+```javascript
+import express from 'express';
+import logger from '../services/LoggingService.js';
+
+const router = express.Router();
+
+export function initWatcherRoutes(app, watchService) {
+  // ... copiar todos los endpoints de WATCHER_API_IMPLEMENTATION.md ...
+}
+
+export default router;
+```
+
+#### 2.4 Integrar rutas en app.js
+
+En `arela-api/src/app.js`:
+
+```javascript
+import express from 'express';
+import { initWatcherRoutes } from './routes/watcher.routes.js';
+import { watchService } from 'arela-uploader/services'; // ✨ Nuevo
+
+const app = express();
+
+// Middleware
+app.use(express.json());
+app.use(express.urlencoded({ extended: true }));
+
+// ... otras rutas ...
+
+// ✨ Inicializar rutas del watcher
+initWatcherRoutes(app, watchService);
+
+// Error handling
+app.use((err, req, res, next) => {
+  console.error(err);
+  res.status(500).json({
+    error: 'Internal server error',
+    message: err.message,
+  });
+});
+
+export default app;
+```
+
+---
+
+### **Paso 3: Agregar Autenticación (Opcional pero Recomendado)**
+
+#### 3.1 Crear middleware de autenticación
+
+Crear: `arela-api/src/middleware/auth.js`
+
+```javascript
+import jwt from 'jsonwebtoken';
+
+export const verifyAuth = (req, res, next) => {
+  try {
+    const token = req.headers.authorization?.split(' ')[1];
+    
+    if (!token) {
+      return res.status(401).json({ error: 'No token provided' });
+    }
+
+    const decoded = jwt.verify(token, process.env.JWT_SECRET);
+    req.user = decoded;
+    next();
+  } catch (error) {
+    res.status(401).json({ error: 'Invalid token' });
+  }
+};
+
+export const requireRole = (role) => (req, res, next) => {
+  if (req.user?.role !== role && req.user?.role !== 'admin') {
+    return res.status(403).json({ error: 'Insufficient permissions' });
+  }
+  next();
+};
+```
+
+#### 3.2 Actualizar rutas para protegerlas
+
+En `watcher.routes.js`, agregar autenticación:
+
+```javascript
+import { verifyAuth, requireRole } from '../middleware/auth.js';
+
+export function initWatcherRoutes(app, watchService) {
+  // Endpoints de lectura (cualquier usuario autenticado)
+  router.get('/status', verifyAuth, (req, res) => {
+    // ... implementación ...
+  });
+
+  router.get('/queue-stats', verifyAuth, async (req, res) => {
+    // ... implementación ...
+  });
+
+  router.get('/directories', verifyAuth, (req, res) => {
+    // ... implementación ...
+  });
+
+  // Endpoints de control (solo admin)
+  router.post('/start', verifyAuth, requireRole('admin'), async (req, res) => {
+    // ... implementación ...
+  });
+
+  router.post('/stop', verifyAuth, requireRole('admin'), async (req, res) => {
+    // ... implementación ...
+  });
+
+  // ... resto de rutas ...
+}
+```
+
+---
+
+### **Paso 4: Actualizar Frontend para Consumir Endpoints**
+
+#### 4.1 Crear hook de React para monitorear watcher
+
+Crear: `frontend/src/hooks/useWatcherMonitor.js`
+
+```javascript
+import { useState, useEffect, useCallback } from 'react';
+
+export const useWatcherMonitor = (pollInterval = 5000) => {
+  const [status, setStatus] = useState(null);
+  const [queue, setQueue] = useState(null);
+  const [directories, setDirectories] = useState([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+
+  // Refrescar datos
+  const refresh = useCallback(async () => {
+    try {
+      setLoading(true);
+      setError(null);
+
+      const token = localStorage.getItem('token'); // O de donde lo tengas
+      const headers = {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${token}`,
+      };
+
+      const [statusRes, queueRes, dirRes] = await Promise.all([
+        fetch('/api/watcher/status', { headers }),
+        fetch('/api/watcher/queue-stats', { headers }),
+        fetch('/api/watcher/directories', { headers }),
+      ]);
+
+      if (!statusRes.ok || !queueRes.ok || !dirRes.ok) {
+        throw new Error('Failed to fetch watcher data');
+      }
+
+      setStatus(await statusRes.json());
+      setQueue(await queueRes.json());
+      setDirectories(await dirRes.json());
+    } catch (err) {
+      setError(err.message);
+      console.error('Error fetching watcher data:', err);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  // Poll automático
+  useEffect(() => {
+    refresh(); // Fetch inicial
+    const interval = setInterval(refresh, pollInterval);
+    return () => clearInterval(interval);
+  }, [pollInterval, refresh]);
+
+  // Acciones
+  const startWatcher = useCallback(
+    async (directories) => {
+      const token = localStorage.getItem('token');
+      const res = await fetch('/api/watcher/start', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${token}`,
+        },
+        body: JSON.stringify({ directories, autoProcessing: true }),
+      });
+      if (!res.ok) throw new Error('Failed to start watcher');
+      await refresh();
+      return res.json();
+    },
+    [refresh]
+  );
+
+  const stopWatcher = useCallback(async () => {
+    const token = localStorage.getItem('token');
+    const res = await fetch('/api/watcher/stop', {
+      method: 'POST',
+      headers: { 'Authorization': `Bearer ${token}` },
+    });
+    if (!res.ok) throw new Error('Failed to stop watcher');
+    await refresh();
+    return res.json();
+  }, [refresh]);
+
+  return {
+    status,
+    queue,
+    directories,
+    loading,
+    error,
+    refresh,
+    startWatcher,
+    stopWatcher,
+  };
+};
+```
+
+#### 4.2 Usar el hook en un componente
+
+```javascript
+// WatcherDashboard.jsx
+import React from 'react';
+import { useWatcherMonitor } from './hooks/useWatcherMonitor';
+
+export const WatcherDashboard = () => {
+  const { status, queue, directories, loading, error, startWatcher, stopWatcher } =
+    useWatcherMonitor(5000); // Refrescar cada 5 segundos
+
+  if (loading && !status) return <div>Loading...</div>;
+  if (error) return <div className="error">Error: {error}</div>;
+
+  return (
+    <div className="watcher-dashboard">
+      <h1>🔍 File Watcher Monitor</h1>
+
+      {/* Status Section */}
+      <section className="status-card">
+        <h2>Estado</h2>
+        <div className="status-grid">
+          <div>
+            <span>Estado:</span>
+            <strong>{status?.isRunning ? '✅ Activo' : '❌ Detenido'}</strong>
+          </div>
+          <div>
+            <span>Directorios monitoreados:</span>
+            <strong>{status?.watchedDirectories}</strong>
+          </div>
+          <div>
+            <span>Auto-procesamiento:</span>
+            <strong>
+              {status?.autoProcessingEnabled ? '✅ Activo' : '❌ Inactivo'}
+            </strong>
+          </div>
+        </div>
+      </section>
+
+      {/* Queue Statistics Section */}
+      <section className="queue-stats-card">
+        <h2>Cola de Procesamiento</h2>
+        <div className="progress-bar">
+          <div
+            className="progress-fill"
+            style={{
+              width: `${queue?.progress?.percentComplete || 0}%`,
+            }}
+          />
+        </div>
+        <p>{queue?.progress?.percentComplete?.toFixed(1)}% completado</p>
+
+        <div className="queue-grid">
+          <div className="queue-item">
+            <span>Pendientes</span>
+            <strong>{queue?.queue?.pending || 0}</strong>
+          </div>
+          <div className="queue-item">
+            <span>Listos</span>
+            <strong>{queue?.queue?.readyToUpload || 0}</strong>
+          </div>
+          <div className="queue-item">
+            <span>Procesando</span>
+            <strong>{queue?.queue?.processing || 0}</strong>
+          </div>
+          <div className="queue-item">
+            <span>Subidos</span>
+            <strong>{queue?.queue?.uploaded || 0}</strong>
+          </div>
+        </div>
+      </section>
+
+      {/* Directories Section */}
+      <section className="directories-card">
+        <h2>Directorios Monitoreados</h2>
+        <ul>
+          {directories?.directories?.map((dir) => (
+            <li key={dir.path}>
+              <span>{dir.isReady ? '✅' : '⏳'}</span>
+              <span>{dir.path}</span>
+              <small>{dir.folderStructure}</small>
+            </li>
+          ))}
+        </ul>
+      </section>
+
+      {/* Control Buttons */}
+      <section className="controls">
+        <button
+          onClick={() => startWatcher(['/path/to/watch'])}
+          disabled={status?.isRunning}
+        >
+          Iniciar Watcher
+        </button>
+        <button onClick={stopWatcher} disabled={!status?.isRunning}>
+          Detener Watcher
+        </button>
+      </section>
+    </div>
+  );
+};
+```
+
+---
+
+### **Paso 5: Documentar API con Swagger (Opcional)**
+
+#### 5.1 Instalar dependencias
+
+```bash
+cd arela-api
+npm install swagger-ui-express swagger-jsdoc
+```
+
+#### 5.2 Crear especificación de Swagger
+
+Crear: `arela-api/src/swagger/watcher.swagger.js`
+
+```javascript
+export const watcherSwaggerDef = {
+  paths: {
+    '/api/watcher/status': {
+      get: {
+        summary: 'Get watcher status',
+        tags: ['Watcher'],
+        responses: {
+          200: {
+            description: 'Current watcher status',
+            schema: {
+              type: 'object',
+              properties: {
+                isRunning: { type: 'boolean' },
+                autoProcessingEnabled: { type: 'boolean' },
+                watchedDirectories: { type: 'number' },
+                stats: { type: 'object' },
+              },
+            },
+          },
+          500: {
+            description: 'Error getting status',
+          },
+        },
+      },
+    },
+    '/api/watcher/start': {
+      post: {
+        summary: 'Start the watcher',
+        tags: ['Watcher'],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                properties: {
+                  directories: {
+                    type: 'array',
+                    items: { type: 'string' },
+                  },
+                  autoProcessing: { type: 'boolean' },
+                  folderStructure: { type: 'string' },
+                },
+                required: ['directories'],
+              },
+            },
+          },
+        },
+        responses: {
+          200: { description: 'Watcher started successfully' },
+          400: { description: 'Invalid request' },
+          500: { description: 'Error starting watcher' },
+        },
+      },
+    },
+    // ... agregar más endpoints ...
+  },
+};
+```
+
+#### 5.3 Integrar en app.js
+
+```javascript
+import swaggerUi from 'swagger-ui-express';
+import swaggerJsdoc from 'swagger-jsdoc';
+import { watcherSwaggerDef } from './swagger/watcher.swagger.js';
+
+const swaggerSpec = swaggerJsdoc({
+  definition: {
+    openapi: '3.0.0',
+    info: {
+      title: 'Arela API',
+      version: '1.0.0',
+    },
+    servers: [
+      { url: 'http://localhost:3000', description: 'Development' },
+    ],
+    ...watcherSwaggerDef,
+  },
+  apis: [],
+});
+
+app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
+```
+
+**Acceder en:** `http://localhost:3000/api-docs`
+
+---
+
+### **Paso 6: Testing**
+
+#### 6.1 Crear tests de integración
+
+Crear: `arela-api/test/watcher.test.js`
+
+```javascript
+import request from 'supertest';
+import app from '../src/app.js';
+
+describe('Watcher API Routes', () => {
+  it('GET /api/watcher/status should return watcher status', async () => {
+    const response = await request(app)
+      .get('/api/watcher/status')
+      .set('Authorization', `Bearer ${validToken}`);
+
+    expect(response.status).toBe(200);
+    expect(response.body).toHaveProperty('isRunning');
+    expect(response.body).toHaveProperty('stats');
+  });
+
+  it('GET /api/watcher/queue-stats should return queue statistics', async () => {
+    const response = await request(app)
+      .get('/api/watcher/queue-stats')
+      .set('Authorization', `Bearer ${validToken}`);
+
+    expect(response.status).toBe(200);
+    expect(response.body).toHaveProperty('queue');
+    expect(response.body).toHaveProperty('progress');
+  });
+
+  it('POST /api/watcher/start should start watcher with directories', async () => {
+    const response = await request(app)
+      .post('/api/watcher/start')
+      .set('Authorization', `Bearer ${validToken}`)
+      .send({
+        directories: ['/test/dir'],
+        autoProcessing: true,
+      });
+
+    expect(response.status).toBe(200);
+    expect(response.body.success).toBe(true);
+  });
+});
+```
+
+#### 6.2 Ejecutar tests
+
+```bash
+npm test -- test/watcher.test.js
+```
+
+---
+
+## 📋 Checklist Final
+
+- [ ] Crear `src/services/index.js` en arela-uploader
+- [ ] Actualizar `package.json` de arela-uploader con `exports`
+- [ ] Instalar arela-uploader en arela-api
+- [ ] Crear `src/routes/watcher.routes.js` en arela-api
+- [ ] Integrar rutas en `app.js`
+- [ ] Crear middleware de autenticación (opcional)
+- [ ] Proteger rutas con autenticación
+- [ ] Crear hook `useWatcherMonitor` en frontend
+- [ ] Crear componente `WatcherDashboard` en frontend
+- [ ] Agregar Swagger (opcional)
+- [ ] Crear tests de integración
+- [ ] Documentar endpoints
+- [ ] Validar que funciona end-to-end
+
+---
+
+## 🧪 Testing End-to-End
+
+### 1. Iniciar arela-api
+```bash
+cd arela-api
+npm start
+```
+
+### 2. Probar endpoints con curl
+
+```bash
+# Get status
+curl http://localhost:3000/api/watcher/status \
+  -H "Authorization: Bearer YOUR_TOKEN"
+
+# Get queue stats
+curl http://localhost:3000/api/watcher/queue-stats \
+  -H "Authorization: Bearer YOUR_TOKEN"
+
+# Start watcher
+curl -X POST http://localhost:3000/api/watcher/start \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -d '{
+    "directories": ["/path/to/watch"],
+    "autoProcessing": true
+  }'
+
+# Stop watcher
+curl -X POST http://localhost:3000/api/watcher/stop \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+### 3. Verificar en frontend
+- Abrir DevTools (F12)
+- Ir a Network tab
+- Verificar que se hacen llamadas a `/api/watcher/*`
+- Ver respuestas JSON en Preview
+
+---
+
+## 🎉 ¡Listo!
+
+El frontend ahora puede monitorear el watcher en tiempo real a través de la API REST.
+