nwinread 1.1.0 → 1.2.0

package/doc/USAGE.md

@@ -0,0 +1,527 @@
+# nwinread - Native Windows Event Log Reader
+
+Lector nativo de Event Log de Windows para Node.js con soporte para lectura síncrona (polling) y asíncrona (suscripciones).
+
+## ✨ Novedades v1.1.1
+
+- **API Coherente**: Modos de lectura consistentes entre sync y async
+- **Nuevos Métodos**: `subscribeFromBeginning()`, `subscribeFromEnd()`, `subscribeFromWatermark()`  
+- **Improved EventEmitter**: Soporte para modos en `createEventEmitter()`
+- **Compatibilidad 100%**: Código existente sigue funcionando sin cambios
+
+Ver [COHERENCIA_APIS.md](COHERENCIA_APIS.md) para detalles completos.
+
+## Instalación y Compilación
+
+```bash
+# Instalar dependencias
+npm install
+
+# Compilar módulos nativos
+npm run rebuild
+```
+
+## Uso Básico
+
+### API Síncrona (Polling)
+
+```javascript
+const eventLog = require('nwinread');
+
+// Leer eventos más recientes
+const result = eventLog.readEvents(
+    "System",                       // Canal
+    eventLog.START_MODE.END,        // Desde el final
+    0,                              // Watermark
+    100,                            // Máximo eventos
+    [1074, 1076]                    // Solo shutdown/restart
+);
+
+console.log(`Eventos: ${result.records.length}`);
+console.log(`Último ID: ${result.lastRecordId}`);
+
+result.records.forEach(event => {
+    console.log(`ID: ${event.recordId}, XML: ${event.xml}`);
+});
+```
+
+### API Asíncrona (Suscripciones)
+
+```javascript
+const eventLog = require('nwinread');
+
+// Crear suscripción con callbacks
+const subscription = eventLog.subscribe(
+    "System",           // Canal
+    0,                  // Watermark (0 = solo futuros)
+    (event) => {        // Callback de eventos
+        console.log(`Evento: ${event.recordId}`);
+        console.log(`XML: ${event.xml}`);
+    },
+    (error) => {        // Callback de errores
+        console.error(`Error: ${error.message}`);
+    },
+    [6005, 6006]        // Solo eventos de inicio/fin de sesión
+);
+
+// Gestionar la suscripción
+console.log(`ID: ${subscription.id}`);
+console.log(`Último Record ID: ${subscription.getLastRecordId()}`);
+
+// Cancelar cuando termine
+subscription.unsubscribe();
+```
+
+### API EventEmitter (Conveniente)
+
+```javascript
+const eventLog = require('nwinread');
+
+// Crear EventEmitter
+const emitter = eventLog.createEventEmitter('Application', {
+    watermark: 0,
+    eventIds: [1000, 1001, 1002]
+});
+
+// Escuchar eventos
+emitter.on('event', (event) => {
+    console.log(`App Event: ${event.recordId}`);
+});
+
+emitter.on('error', (error) => {
+    console.error(`Error: ${error.message}`);
+});
+
+// Limpiar
+emitter.unsubscribe();
+```
+
+## API Coherente (Modos Síncronos/Asíncronos)
+
+New! APIs que mantienen coherencia entre operaciones síncronas y asíncronas:
+
+### Métodos Helper Específicos
+
+```javascript
+const eventLog = require('nwinread');
+
+// 1. Procesar TODOS los eventos (equivale a mode=BEGINNING)
+const allEvents = eventLog.subscribeFromBeginning("System",
+    (event) => console.log(`Historical: ${event.recordId}`),
+    (error) => console.error(error.message)
+);
+
+// 2. Solo eventos FUTUROS (equivale a mode=END) 
+const futureEvents = eventLog.subscribeFromEnd("Security",
+    (event) => console.log(`New: ${event.recordId}`),  
+    (error) => console.error(error.message)
+);
+
+// 3. Desde un PUNTO ESPECÍFICO (equivale a mode=WATERMARK)
+const fromPoint = eventLog.subscribeFromWatermark("Application", 50000,
+    (event) => console.log(`From 50k: ${event.recordId}`),
+    (error) => console.error(error.message) 
+);
+```
+
+### subscribe() con Opciones de Modo
+
+```javascript
+// Nuevo formato con modo explícito
+const subscription = eventLog.subscribe("System", {
+    mode: eventLog.START_MODE.BEGINNING,  // BEGINNING, END, o WATERMARK
+    watermark: 12345,                     // Para WATERMARK mode
+    eventIds: [1074, 6005]               // Filtros opcionales
+}, onEvent, onError);
+
+// Formato anterior sigue funcionando (compatibilidad total)
+const legacy = eventLog.subscribe("System", 0, onEvent, onError, [1074]);
+```
+
+### EventEmitter con Modos
+
+```javascript
+// EventEmitter que procesa todos los eventos históricos
+const historicalEmitter = eventLog.createEventEmitter('Application', {
+    mode: eventLog.START_MODE.BEGINNING,
+    eventIds: [1000, 1001]
+});
+
+// EventEmitter solo para eventos futuros con filtros 
+const futureEmitter = eventLog.createEventEmitter('Security', {
+    mode: eventLog.START_MODE.END,
+    eventIds: [4624, 4625, 4634]  // Login/logout events
+});
+```
+
+## API Referencia
+
+### `readEvents(channel, mode, watermark, maxEvents, eventIds)`
+
+Lectura síncrona de eventos del Event Log.
+
+- **channel** `string` - Canal del Event Log ("System", "Application", "Security", etc.)
+- **mode** `number` - Modo de lectura (START_MODE.BEGINNING, END, WATERMARK)
+- **watermark** `number` - Record ID de inicio para modo WATERMARK
+- **maxEvents** `number` - Número máximo de eventos a retornar (1-10000)
+- **eventIds** `Array<number>` - Array opcional de Event IDs para filtrar
+
+**Retorna:** `Object`
+```javascript
+{
+  records: [
+    { recordId: number, xml: string },
+    ...
+  ],
+  lastRecordId: number
+}
+```
+
+### `subscribe(channel, watermark, onEvent, onError, eventIds)`
+
+Crear suscripción asíncrona a eventos en tiempo real.
+
+- **channel** `string` - Canal del Event Log
+- **watermark** `number` - Record ID de inicio (ver [Configuración de Offset](#configuración-de-offset))
+- **onEvent** `Function` - Callback `(event) => {}` llamado por cada evento
+- **onError** `Function` - Callback `(error) => {}` llamado en errores
+- **eventIds** `Array<number>` - Array opcional de Event IDs para filtrar
+
+**Retorna:** `EventLogSubscription`
+
+### `createEventEmitter(channel, options)`
+
+Crear EventEmitter para suscripción conveniente.
+
+- **channel** `string` - Canal del Event Log
+- **options** `Object` - Opciones de configuración
+  - **watermark** `number` - Record ID de inicio (default: 0)
+  - **eventIds** `Array<number>` - Event IDs para filtrar (default: null)
+
+**Retorna:** `EventEmitter` que emite eventos 'event' y 'error'
+
+### Clase `EventLogSubscription`
+
+#### Métodos
+
+- **`getLastRecordId()`** - Obtiene el último Record ID procesado
+- **`unsubscribe()`** - Cancela la suscripción
+- **`isActive()`** - Verifica si la suscripción está activa
+
+#### Propiedades  
+
+- **`id`** - ID único de la suscripción
+- **`channel`** - Canal al que está suscrito
+- **`watermark`** - Watermark inicial
+
+## Constantes
+
+### `START_MODE`
+
+```javascript
+{
+  BEGINNING: 0,  // Leer desde el inicio del log
+  END: 1,        // Leer desde el final del log  
+  WATERMARK: 2   // Leer desde un Record ID específico
+}
+```
+
+## Canales Comunes
+
+- **"System"** - Eventos del sistema (inicio, apagado, errores hardware)
+- **"Application"** - Eventos de aplicaciones
+- **"Security"** - Eventos de seguridad y auditoría
+- **"Setup"** - Eventos de instalación
+- **"Microsoft-Windows-*"** - Canales específicos de Windows
+
+## Event IDs Comunes
+
+### Sistema
+- **1074** - Shutdown del sistema
+- **1076** - Motivo de último shutdown
+- **6005** - Inicio del Event Log Service
+- **6006** - Parada del Event Log Service  
+- **6008** - Shutdown inesperado anterior
+
+### Seguridad
+- **4624** - Logon exitoso
+- **4625** - Logon fallido
+- **4634** - Logoff de cuenta
+
+## Ejemplos Avanzados
+
+### Monitoreo de Seguridad
+
+```javascript
+const eventLog = require('nwinread');
+
+const securityMonitor = eventLog.createEventEmitter('Security', {
+    eventIds: [4624, 4625, 4634] // Logon/Logoff events
+});
+
+securityMonitor.on('event', (event) => {
+    // Parsear XML del evento para obtener detalles
+    const xml = event.xml;
+    
+    if (xml.includes('4625')) {
+        console.log('⚠️  Intento de login fallido detectado');
+    } else if (xml.includes('4624')) {
+        console.log('✅ Login exitoso');
+    }
+});
+```
+
+### Sistema de Alarmas
+
+```javascript
+const eventLog = require('nwinread');
+
+class SystemAlerts {
+    constructor() {
+        this.subscription = eventLog.subscribe(
+            "System",
+            0,
+            this.handleEvent.bind(this),
+            this.handleError.bind(this),
+            [1074, 1076, 6008] // Shutdown y errores
+        );
+    }
+
+    handleEvent(event) {
+        const xml = event.xml;
+        
+        if (xml.includes('1074')) {
+            this.sendAlert('Sistema apagándose', event);
+        } else if (xml.includes('6008')) {
+            this.sendAlert('Shutdown inesperado detectado', event);
+        }
+    }
+
+    handleError(error) {
+        console.error(`Sistema de alertas error: ${error.message}`);
+    }
+
+    sendAlert(message, event) {
+        console.log(`🚨 ALERTA: ${message}`);
+        console.log(`    Record ID: ${event.recordId}`);
+        console.log(`    Timestamp: ${new Date().toISOString()}`);
+    }
+
+    stop() {
+        return this.subscription.unsubscribe();
+    }
+}
+
+const alerts = new SystemAlerts();
+```
+
+## Manejo de Errores
+
+### Errores Comunes
+
+- **Access Denied** - Permisos insuficientes para leer el canal
+- **Channel Not Found** - El canal especificado no existe
+- **Invalid Arguments** - Parámetros incorrectos
+
+### Códigos de Error Windows
+
+Los errores retornan objetos con:
+```javascript
+{
+  message: "Descripción del error",
+  code: 123  // Código de error de Windows
+}
+```
+
+## Rendimiento y Best Practices
+
+### Para API Síncrona
+- Use para consultas puntuales o análisis histórico
+- Limite maxEvents para evitar uso excesivo de memoria
+- Use filtros eventIds para mejorar rendimiento
+
+### Para API Asíncrona
+- Ideal para monitoreo en tiempo real
+- Menor uso de CPU que polling
+- Maneje adecuadamente cleanup en cierre de aplicación
+- Use filtros para reducir ruido
+
+### Cleanup Apropiado
+
+```javascript
+// Manejar señales de terminación
+process.on('SIGINT', cleanup);
+process.on('SIGTERM', cleanup);
+
+function cleanup() {
+    if (subscription && subscription.isActive()) {
+        subscription.unsubscribe();
+    }
+    process.exit(0);
+}
+```
+
+## Configuración de Offset
+
+El parámetro `watermark` (offset de inicio) permite controlar desde qué punto iniciar la lectura de eventos. Es especialmente útil para recuperación tras interrupciones o análisis histórico selectivo.
+
+### Valores de Watermark
+
+| Valor | Comportamiento | Caso de Uso |
+|-------|---------------|-------------|
+| `0` | Solo eventos futuros | Monitoreo en tiempo real |
+| `N > 0` | Desde Record ID específico | Recuperación desde punto conocido |
+| `-1` | Todos los eventos disponibles | Análisis histórico completo |
+
+### Ejemplos de Uso
+
+#### 1. Monitoreo en Tiempo Real
+```javascript
+// Solo eventos que ocurran después de la suscripción
+const subscription = eventLog.subscribe(
+    "System", 
+    0,  // Solo eventos futuros
+    onEvent, 
+    onError
+);
+```
+
+#### 2. Recuperación desde Punto Específico  
+```javascript
+// Continuar desde un Record ID conocido
+const subscription = eventLog.subscribe(
+    "Application",
+    5000,  // Desde Record ID 5000 en adelante
+    onEvent,
+    onError
+);
+```
+
+#### 3. Análisis Histórico Completo
+```javascript
+// Procesar todos los eventos disponibles
+const subscription = eventLog.subscribe(
+    "Security",
+    -1,  // Todos los eventos del log
+    onEvent, 
+    onError
+);
+```
+
+#### 4. Offset Dinámico por Fecha
+```javascript
+function getOffsetByDate(channel, targetDate) {
+    const events = eventLog.read(channel, "recent", 0, 100);
+    let closestRecordId = 0;
+    let closestDiff = Infinity;
+    
+    for (const event of events) {
+        const eventTime = new Date(event.timestamp);
+        const timeDiff = Math.abs(eventTime.getTime() - targetDate.getTime());
+        
+        if (timeDiff < closestDiff) {
+            closestDiff = timeDiff;
+            closestRecordId = event.recordId;
+        }
+    }
+    
+    return closestRecordId;
+}
+
+// Suscribirse desde hace 1 hora
+const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000);
+const offset = getOffsetByDate("System", oneHourAgo);
+
+const subscription = eventLog.subscribe("System", offset, onEvent, onError);
+```
+
+#### 5. Estado de Suscripción con Offset
+```javascript
+const subscription = eventLog.subscribe("Application", 1000, onEvent, onError);
+
+console.log(`Iniciado desde Record ID: ${subscription.getStartWatermark()}`);
+console.log(`Canal: ${subscription.channel}`);
+console.log(`Activa: ${subscription.isActive()}`);
+```
+
+### EventEmitter con Offset
+
+```javascript
+const emitter = eventLog.createEventEmitter('System', {
+    watermark: 2500,  // Desde Record ID 2500
+    eventIds: [1074, 6008]  // Con filtro de eventos
+});
+
+emitter.on('event', (event) => {
+    console.log(`Record: ${event.recordId}, desde offset 2500`);
+});
+```
+
+### Mejores Prácticas para Offsets
+
+1. **Persistir último Record ID**: Guarde el último Record ID procesado para recuperación
+2. **Validar disponibilidad**: Los logs rotan, verifique que el offset sigue disponible  
+3. **Fallback a 0**: Si el offset específico falla, use 0 como fallback
+4. **Monitorear gaps**: Detecte saltos en Record IDs que indican rotación de logs
+
+```javascript
+class PersistentEventReader {
+    constructor(channel, stateFile = './last-record-id.txt') {
+        this.channel = channel;
+        this.stateFile = stateFile;
+        this.lastRecordId = this.loadState();
+    }
+    
+    start() {
+        this.subscription = eventLog.subscribe(
+            this.channel,
+            this.lastRecordId,
+            (event) => {
+                this.handleEvent(event);
+                this.saveState(event.recordId);
+            },
+            this.handleError.bind(this)
+        );
+    }
+    
+    handleEvent(event) {
+        console.log(`Procesando Record ID: ${event.recordId}`);
+        // Procesar evento...
+    }
+    
+    loadState() {
+        try {
+            const fs = require('fs');
+            const content = fs.readFileSync(this.stateFile, 'utf8');
+            return parseInt(content.trim()) + 1; // Siguiente al último procesado
+        } catch {
+            return 0; // Primera ejecución, solo eventos futuros
+        }
+    }
+    
+    saveState(recordId) {
+        const fs = require('fs');
+        fs.writeFileSync(this.stateFile, recordId.toString());
+    }
+}
+```
+
+## Requisitos del Sistema
+
+- Windows Vista o superior  
+- Permisos de lectura al Event Log
+- Node.js 14+ con N-API support
+- Visual Studio Build Tools para compilación
+
+## Troubleshooting
+
+### Error: "Module not found"
+```bash
+npm run rebuild
+```
+
+### Error: "Access denied"  
+Ejecutar con permisos elevados o verificar permisos de usuario.
+
+### Error de compilación
+Verificar que Visual Studio Build Tools esté instalado.