rosinterface 1.3.0 → 1.3.2

package/dist/core/SocketClient.js

@@ -38,29 +38,48 @@ const net = __importStar(require("net"));
 const tls = __importStar(require("tls"));
 const events_1 = require("events");
 const buffer_1 = require("buffer");
-const RosProtocol_1 = require("./RosProtocol");
+const RosProtocol_1 = require("./RosProtocol"); // Asegúrate de tener este archivo
+/**
+ * Low-level TCP/TLS Client.
+ * Responsibilities:
+ * 1. Transport Layer: Decides between 'net' (Plain) and 'tls' (Secure).
+ * 2. Event Handling: Manages socket errors, closures, and timeouts.
+ * 3. Framing: Buffers incoming raw bytes and splits them into valid MikroTik words.
+ */
 class SocketClient extends events_1.EventEmitter {
     constructor(options) {
         super();
+        // Union type to support both standard and secure sockets
         this.socket = null;
+        // State tracking
         this.connected = false;
+        // Buffer accumulator for handling TCP packet fragmentation
         this.receiveBuffer = buffer_1.Buffer.alloc(0);
         this.options = {
             timeout: 10,
-            rejectUnauthorized: false,
+            rejectUnauthorized: false, // For development usually
             keepAlive: true,
             useTLS: false,
             ...options
         };
     }
+    /**
+     * Establishes the connection to the router.
+     * Supports both Plain TCP and TLS based on configuration.
+     * @returns Promise that resolves when the connection is fully established.
+     */
     connect() {
         return new Promise((resolve, reject) => {
             if (this.connected)
                 return resolve();
+            // 1. Clean up any previous socket instance
             this.cleanup();
+            // 2. Calculate timeout in milliseconds
             const timeoutMs = (this.options.timeout || 10) * 1000;
+            // 3. LOGIC DECISION: TLS vs PLAIN TCP
             try {
                 if (this.options.useTLS) {
+                    // --- SECURE MODE (TLS) ---
                     const tlsOptions = {
                         host: this.options.host,
                         port: this.options.port,
@@ -70,6 +89,7 @@ class SocketClient extends events_1.EventEmitter {
                     this.socket = tls.connect(tlsOptions);
                 }
                 else {
+                    // --- PLAIN MODE (TCP) ---
                     this.socket = new net.Socket();
                     this.socket.setTimeout(timeoutMs);
                     this.socket.connect(this.options.port, this.options.host);
@@ -78,24 +98,30 @@ class SocketClient extends events_1.EventEmitter {
             catch (err) {
                 return reject(err);
             }
+            // 4. Handle Connection Timeout (Handshake phase)
             this.socket.once('timeout', () => {
                 const err = new Error(`Connection timed out after ${this.options.timeout} seconds`);
                 this.destroy();
                 reject(err);
             });
+            // 5. Optimization: Disable Nagle's Algorithm (Lower latency for small packets)
             this.socket.setNoDelay(true);
+            // 6. Keep-Alive
             if (this.options.keepAlive && this.socket instanceof net.Socket) {
                 this.socket.setKeepAlive(true, 10000);
             }
+            // --- EVENT BINDING ---
             const connectEvent = this.options.useTLS ? 'secureConnect' : 'connect';
             this.socket.once(connectEvent, () => {
                 this.connected = true;
+                // Clear initial timeout so we don't disconnect during operation
                 if (this.socket)
                     this.socket.setTimeout(0);
-                this.emit('connect');
+                this.emit('connect'); // Notify MikrotikClient
                 resolve();
             });
             this.socket.on('error', (err) => {
+                // If error happens during connection phase, reject the promise
                 if (!this.connected) {
                     reject(err);
                 }
@@ -107,7 +133,9 @@ class SocketClient extends events_1.EventEmitter {
                 this.connected = false;
                 this.emit('close', hadError);
             });
+            // DATA RECEIVING LOOP
             this.socket.on('data', (chunk) => {
+                // Defensive programming
                 const bufferChunk = buffer_1.Buffer.isBuffer(chunk)
                     ? chunk
                     : buffer_1.Buffer.from(chunk, 'utf8');
@@ -115,18 +143,29 @@ class SocketClient extends events_1.EventEmitter {
             });
         });
     }
+    /**
+     * Writes raw bytes to the socket stream.
+     */
     write(data) {
         if (!this.connected || !this.socket) {
             throw new Error('Socket is not connected. Call connect() first.');
         }
+        // Uncomment to see OUTGOING raw bytes
+        // console.log('>>> OUT [Buffer]:', data);
         this.socket.write(data);
     }
+    /**
+     * Gracefully closes the connection.
+     */
     close() {
         if (this.socket && !this.socket.destroyed) {
             this.socket.end();
             this.connected = false;
         }
     }
+    /**
+     * Forcefully destroys the connection.
+     */
     destroy() {
         if (this.socket && !this.socket.destroyed) {
             this.socket.destroy();
@@ -141,15 +180,24 @@ class SocketClient extends events_1.EventEmitter {
         }
         this.receiveBuffer = buffer_1.Buffer.alloc(0);
     }
+    /**
+     * CORE LOGIC: TCP Framing.
+     * Extracts valid MikroTik "Words" from the TCP stream.
+     */
     handleDataChunk(chunk) {
+        // Append new data
         this.receiveBuffer = buffer_1.Buffer.concat([this.receiveBuffer, chunk]);
+        // Loop to process as many words as possible
         while (this.receiveBuffer.length > 0) {
+            // Decode length using RosProtocol utility
             const lengthInfo = RosProtocol_1.RosProtocol.decodeLength(this.receiveBuffer);
+            // If we don't have enough bytes for the length header, wait for next packet
             if (!lengthInfo) {
                 break;
             }
             const { length, byteLength } = lengthInfo;
             const totalPacketSize = byteLength + length;
+            // If we have the header but not the full body, wait.
             if (this.receiveBuffer.length < totalPacketSize) {
                 break;
             }

package/dist/core/SocketClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"SocketClient.js","sourceRoot":"","sources":["../../src/core/SocketClient.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,yCAA2B;AAC3B,yCAA2B;AAC3B,mCAAsC;AACtC,mCAAgC;AAChC,+CAA4C;AA2B5C,MAAa,YAAa,SAAQ,qBAAY;IAW1C,YAAY,OAA4B;QACpC,KAAK,EAAE,CAAC;QAVJ,WAAM,GAAsC,IAAI,CAAC;QAIlD,cAAS,GAAY,KAAK,CAAC;QAG1B,kBAAa,GAAW,eAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAI5C,IAAI,CAAC,OAAO,GAAG;YACX,OAAO,EAAE,EAAE;YACX,kBAAkB,EAAE,KAAK;YACzB,SAAS,EAAE,IAAI;YACf,MAAM,EAAE,KAAK;YACb,GAAG,OAAO;SACb,CAAC;IACN,CAAC;IAOM,OAAO;QACV,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACnC,IAAI,IAAI,CAAC,SAAS;gBAAE,OAAO,OAAO,EAAE,CAAC;YAGrC,IAAI,CAAC,OAAO,EAAE,CAAC;YAGf,MAAM,SAAS,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;YAGtD,IAAI,CAAC;gBACD,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;oBAEtB,MAAM,UAAU,GAA0B;wBACtC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI;wBACvB,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI;wBACvB,kBAAkB,EAAE,IAAI,CAAC,OAAO,CAAC,kBAAkB;wBACnD,OAAO,EAAE,SAAS;qBACrB,CAAC;oBACF,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;gBAC1C,CAAC;qBAAM,CAAC;oBAEJ,IAAI,CAAC,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;oBAC/B,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;oBAClC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAC9D,CAAC;YACL,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACX,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,CAAC;YAGD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE;gBAC7B,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,8BAA8B,IAAI,CAAC,OAAO,CAAC,OAAO,UAAU,CAAC,CAAC;gBACpF,IAAI,CAAC,OAAO,EAAE,CAAC;gBACf,MAAM,CAAC,GAAG,CAAC,CAAC;YAChB,CAAC,CAAC,CAAC;YAGH,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YAG7B,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,CAAC;gBAC9D,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAC1C,CAAC;YAID,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC;YAEvE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,GAAG,EAAE;gBAChC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;gBAEtB,IAAI,IAAI,CAAC,MAAM;oBAAE,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;gBAE3C,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBACrB,OAAO,EAAE,CAAC;YACd,CAAC,CAAC,CAAC;YAEH,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;gBAE5B,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;oBAClB,MAAM,CAAC,GAAG,CAAC,CAAC;gBAChB,CAAC;qBAAM,CAAC;oBACJ,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;gBAC5B,CAAC;YACL,CAAC,CAAC,CAAC;YAEH,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,EAAE;gBACjC,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;gBACvB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YACjC,CAAC,CAAC,CAAC;YAGH,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAsB,EAAE,EAAE;gBAE9C,MAAM,WAAW,GAAG,eAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;oBACtC,CAAC,CAAC,KAAK;oBACP,CAAC,CAAC,eAAM,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;gBAEjC,IAAI,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;YACtC,CAAC,CAAC,CAAC;QACP,CAAC,CAAC,CAAC;IACP,CAAC;IAKM,KAAK,CAAC,IAAY;QACrB,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACtE,CAAC;QAKD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAKM,KAAK;QACR,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YACxC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;YAClB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QAC3B,CAAC;IACL,CAAC;IAKM,OAAO;QACV,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YACxC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACtB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QAC3B,CAAC;IACL,CAAC;IAEO,OAAO;QACX,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACd,IAAI,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC;YACjC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACvB,CAAC;QACD,IAAI,CAAC,aAAa,GAAG,eAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC;IAMO,eAAe,CAAC,KAAa;QAEjC,IAAI,CAAC,aAAa,GAAG,eAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC,CAAC;QAGhE,OAAO,IAAI,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAGnC,MAAM,UAAU,GAAG,yBAAW,CAAC,YAAY,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;YAGhE,IAAI,CAAC,UAAU,EAAE,CAAC;gBACd,MAAM;YACV,CAAC;YAED,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,UAAU,CAAC;YAC1C,MAAM,eAAe,GAAG,UAAU,GAAG,MAAM,CAAC;YAG5C,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;gBAC9C,MAAM;YACV,CAAC;YAED,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC;YAEtE,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;YAE/D,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAEtC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC5B,CAAC;IACL,CAAC;CACJ;AA/LD,oCA+LC"}
+{"version":3,"file":"SocketClient.js","sourceRoot":"","sources":["../../src/core/SocketClient.ts"],"names":[],"mappings":"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"}

package/dist/features/FileManager.d.ts

@@ -1,4 +1,7 @@
 import { MikrotikClient } from '../client/MikrotikClient';
+/**
+ * Represents a file object from RouterOS /file/print
+ */
 export interface IFileEntry {
     '.id': string;
     name: string;
@@ -7,16 +10,63 @@ export interface IFileEntry {
     'creation-time': string;
     contents?: string;
 }
+/**
+ * **FileManager**
+ * * Advanced abstraction layer for file operations on RouterOS.
+ * Features:
+ * - Text File I/O (Read/Write scripts/logs).
+ * - System Backup & Restore management.
+ * - RSC Script Execution (Import).
+ * - Directory listing and cleaning.
+ */
 export declare class FileManager {
     private client;
     constructor(client: MikrotikClient);
+    /**
+     * Lists files on the router, optionally filtering by name.
+     * @param filterName Optional substring to filter files (e.g., ".backup")
+     */
     list(filterName?: string): Promise<IFileEntry[]>;
+    /**
+     * Checks if a file exists on the router.
+     */
     exists(fileName: string): Promise<boolean>;
+    /**
+     * Deletes a file or multiple files.
+     * @param fileName Name of the file (or array of names).
+     */
     delete(fileName: string | string[]): Promise<void>;
+    /**
+     * Writes text content to a file.
+     * Handles creation if it doesn't exist.
+     * * WARNING: RouterOS API has a limit for property values (~4MB in v7, less in v6).
+     * Do not use this for binary files (.npk) or massive logs.
+     */
     writeText(fileName: string, content: string): Promise<void>;
+    /**
+     * Reads text content from a file.
+     * @returns string content, or throws error if file is binary/too large.
+     */
     readText(fileName: string): Promise<string>;
+    /**
+     * Creates a System Backup (.backup) file.
+     * @param name Backup name (without extension).
+     * @param password Optional encryption password.
+     */
     createSystemBackup(name: string, password?: string): Promise<string>;
+    /**
+     * Restores a System Backup.
+     * DANGER: This will reboot the router.
+     */
     restoreSystemBackup(name: string, password?: string): Promise<void>;
+    /**
+     * Exports configuration to an RSC script file.
+     * @param name File name (e.g., "daily_export")
+     */
     createExport(name: string): Promise<string>;
+    /**
+     * Uploads a script (.rsc) and immediately executes it.
+     * Great for provisioning or mass updates.
+     */
     runScript(content: string, scriptName?: string): Promise<void>;
 }

package/dist/features/FileManager.js

@@ -1,10 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileManager = void 0;
+/**
+ * **FileManager**
+ * * Advanced abstraction layer for file operations on RouterOS.
+ * Features:
+ * - Text File I/O (Read/Write scripts/logs).
+ * - System Backup & Restore management.
+ * - RSC Script Execution (Import).
+ * - Directory listing and cleaning.
+ */
 class FileManager {
     constructor(client) {
         this.client = client;
     }
+    // ==========================================
+    // CORE FILE OPERATIONS
+    // ==========================================
+    /**
+     * Lists files on the router, optionally filtering by name.
+     * @param filterName Optional substring to filter files (e.g., ".backup")
+     */
     async list(filterName) {
         const cmd = this.client.command('/file');
         const result = await cmd.print();
@@ -14,14 +30,23 @@ class FileManager {
         }
         return files;
     }
+    /**
+     * Checks if a file exists on the router.
+     */
     async exists(fileName) {
         const file = await this.client.command('/file')
             .where('name', fileName)
             .first();
         return !!file;
     }
+    /**
+     * Deletes a file or multiple files.
+     * @param fileName Name of the file (or array of names).
+     */
     async delete(fileName) {
         const targets = Array.isArray(fileName) ? fileName : [fileName];
+        // We need IDs to remove safely, or use 'remove [find where name=X]' logic
+        // But the API supports removing by ID mostly.
         for (const name of targets) {
             const file = await this.client.command('/file').where('name', name).first();
             if (file) {
@@ -30,37 +55,62 @@ class FileManager {
             }
         }
     }
+    // ==========================================
+    // TEXT I/O (Scripts, Configs, Hotspot)
+    // ==========================================
+    /**
+     * Writes text content to a file.
+     * Handles creation if it doesn't exist.
+     * * WARNING: RouterOS API has a limit for property values (~4MB in v7, less in v6).
+     * Do not use this for binary files (.npk) or massive logs.
+     */
     async writeText(fileName, content) {
-        if (content.length > 1024 * 1024) {
+        if (content.length > 1024 * 1024) { // 1MB Guard
             console.warn(`[FileManager] Warning: Uploading ${content.length} bytes via API is risky.`);
         }
         const exists = await this.exists(fileName);
         if (!exists) {
+            // Trick: 'print file=name' creates an empty file
             await this.client.write('/file/print', {
                 file: fileName,
-                where: 'false'
-            }).catch(() => { });
+                where: 'false' // Suppress output
+            }).catch(() => { }); // Ignore "interrupted" or empty return errors
+            // Wait a tiny bit for FS sync
             await new Promise(r => setTimeout(r, 200));
         }
+        // Update content
         await this.client.write('/file/set', {
-            'numbers': fileName,
+            'numbers': fileName, // API allows name in numbers for some versions, but IDs are safer.
             'contents': content
         });
         console.log(`[FileManager] Saved: ${fileName}`);
     }
+    /**
+     * Reads text content from a file.
+     * @returns string content, or throws error if file is binary/too large.
+     */
     async readText(fileName) {
         const file = await this.client.command('/file').where('name', fileName).first();
         if (!file)
             throw new Error(`File '${fileName}' not found.`);
+        // RouterOS logic: If 'contents' is missing, the file is too big or binary.
         if (file.contents === undefined) {
             const size = Number(file.size);
-            if (size > 4096) {
+            if (size > 4096) { // Heuristic: API often hides contents > 4KB (v6) or 64KB (v7)
                 throw new Error(`File '${fileName}' is too large (${size} bytes) or binary to read via API. Use SFTP.`);
             }
-            return '';
+            return ''; // Empty file
         }
         return file.contents;
     }
+    // ==========================================
+    // SYSTEM & AUTOMATION
+    // ==========================================
+    /**
+     * Creates a System Backup (.backup) file.
+     * @param name Backup name (without extension).
+     * @param password Optional encryption password.
+     */
     async createSystemBackup(name, password) {
         const fullName = `${name}.backup`;
         const params = { name: name };
@@ -70,6 +120,10 @@ class FileManager {
         await this.client.write('/system/backup/save', params);
         return fullName;
     }
+    /**
+     * Restores a System Backup.
+     * DANGER: This will reboot the router.
+     */
     async restoreSystemBackup(name, password) {
         console.warn(`[FileManager] RESTORING BACKUP ${name}. ROUTER WILL REBOOT.`);
         const params = { name: name };
@@ -77,15 +131,26 @@ class FileManager {
             params.password = password;
         await this.client.write('/system/backup/load', params);
     }
+    /**
+     * Exports configuration to an RSC script file.
+     * @param name File name (e.g., "daily_export")
+     */
     async createExport(name) {
         const fullName = name.endsWith('.rsc') ? name : `${name}.rsc`;
         console.log(`[FileManager] Exporting config to ${fullName}...`);
+        // /export file=name
         await this.client.write('/export', { file: name });
         return fullName;
     }
+    /**
+     * Uploads a script (.rsc) and immediately executes it.
+     * Great for provisioning or mass updates.
+     */
     async runScript(content, scriptName = 'temp_worker.rsc') {
         try {
+            // Upload
             await this.writeText(scriptName, content);
+            // Execute (/import)
             console.log(`[FileManager] Executing script: ${scriptName}...`);
             await this.client.write('/import', { 'file-name': scriptName });
             console.log(`[FileManager] Script executed successfully.`);
@@ -95,6 +160,7 @@ class FileManager {
             throw error;
         }
         finally {
+            // Cleanup (Optional: remove script after run)
             await this.delete(scriptName);
         }
     }

package/dist/features/FileManager.js.map

@@ -1 +1 @@
-{"version":3,"file":"FileManager.js","sourceRoot":"","sources":["../../src/features/FileManager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"FileManager.js","sourceRoot":"","sources":["../../src/features/FileManager.ts"],"names":[],"mappings":"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"}

package/dist/features/LiveCollection.d.ts

@@ -1,18 +1,69 @@
 import { MikrotikClient } from "../client/MikrotikClient";
 import { SnapshotSubscription, SnapshotDiff } from "../client/SnapshotSubscription";
+/**
+ * Flexible callback definition.
+ * Can receive a standard Array OR a Diff object depending on configuration.
+ */
 export type SnapshotCallback<T> = (data: T[] | SnapshotDiff<T>) => void;
+/**
+ * LiveCollection
+ * ==========================================
+ * Manages a real-time synchronized collection of items from the router.
+ *
+ * Instead of firing simple callbacks, it manages 'SnapshotSubscription' instances.
+ * This allows each subscriber to have their own Throttle settings and Diff modes.
+ *
+ * @template T The type of the items in the collection.
+ */
 export declare class LiveCollection<T extends Record<string, any>> {
     private client;
     private path;
     private query;
+    /** Internal storage mapped by item ID (e.g., "*1A") */
     private localCache;
+    /** The active low-level subscription object returned by the Client/Socket */
     private subscription;
+    /**
+     * CHANGED: List of active "Smart Subscriptions" instead of simple functions.
+     * This allows us to call .processUpdate() on each one.
+     */
     private subscriptions;
+    /** Flag to prevent double initialization */
     private isInitializing;
+    /**
+     * Creates an instance of LiveCollection.
+     * @param client The main MikrotikClient instance.
+     * @param path The menu path to listen to (e.g., '/ppp/active').
+     * @param query Optional filter object (e.g. { name: 'admin' }).
+     */
     constructor(client: MikrotikClient, path: string, query?: Record<string, string | number | boolean>);
+    /**
+     * Subscribes to real-time updates.
+     *
+     * v1.2.0 Change:
+     * Returns a `SnapshotSubscription` object instead of a cleanup function.
+     * This enables chaining methods like `.onDiff()`, `.throttle()`, and `.join()`.
+     *
+     * @param callback Function to execute when data changes.
+     * @returns The Subscription object for chaining configuration.
+     */
     onSnapshot(callback: SnapshotCallback<T>): SnapshotSubscription<T>;
+    /**
+     * Internal method to establish the connection via the client.
+     */
     private startListening;
+    /**
+     * Processes incoming raw packets from RouterOS.
+     * Handles creation, updates, and deletion based on packet flags.
+     * @param packet Raw data from the router.
+     */
     private processPacket;
+    /**
+     * Broadcasts the current array of items to all smart subscriptions.
+     */
     private emit;
+    /**
+     * Stops the low-level connection to the router.
+     */
     private stopListening;
 }

package/dist/features/LiveCollection.js

@@ -2,28 +2,67 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LiveCollection = void 0;
 const SnapshotSubscription_1 = require("../client/SnapshotSubscription");
+/**
+ * LiveCollection
+ * ==========================================
+ * Manages a real-time synchronized collection of items from the router.
+ *
+ * Instead of firing simple callbacks, it manages 'SnapshotSubscription' instances.
+ * This allows each subscriber to have their own Throttle settings and Diff modes.
+ *
+ * @template T The type of the items in the collection.
+ */
 class LiveCollection {
+    /**
+     * Creates an instance of LiveCollection.
+     * @param client The main MikrotikClient instance.
+     * @param path The menu path to listen to (e.g., '/ppp/active').
+     * @param query Optional filter object (e.g. { name: 'admin' }).
+     */
     constructor(client, path, query = {}) {
         this.client = client;
         this.path = path;
         this.query = query;
+        /** Internal storage mapped by item ID (e.g., "*1A") */
         this.localCache = new Map();
+        /** The active low-level subscription object returned by the Client/Socket */
         this.subscription = null;
+        /**
+         * CHANGED: List of active "Smart Subscriptions" instead of simple functions.
+         * This allows us to call .processUpdate() on each one.
+         */
         this.subscriptions = [];
+        /** Flag to prevent double initialization */
         this.isInitializing = false;
     }
+    /**
+     * Subscribes to real-time updates.
+     *
+     * v1.2.0 Change:
+     * Returns a `SnapshotSubscription` object instead of a cleanup function.
+     * This enables chaining methods like `.onDiff()`, `.throttle()`, and `.join()`.
+     *
+     * @param callback Function to execute when data changes.
+     * @returns The Subscription object for chaining configuration.
+     */
     onSnapshot(callback) {
+        // Define the cleanup logic for this specific subscriber
         const unsubscribeLogic = () => {
             this.subscriptions = this.subscriptions.filter(s => s !== sub);
+            // If no one is listening anymore, stop the router connection to save bandwidth
             if (this.subscriptions.length === 0) {
                 this.stopListening();
             }
         };
+        // Create the Smart Subscription
         const sub = new SnapshotSubscription_1.SnapshotSubscription(this.client, callback, unsubscribeLogic);
         this.subscriptions.push(sub);
+        // Send immediate data if we already have cache (Hot Observable behavior)
         if (this.localCache.size > 0) {
+            // We use processUpdate so logic like Join or Diff runs even on the first data
             sub.processUpdate(Array.from(this.localCache.values()));
         }
+        // Start Router connection if this is the first listener
         if (!this.subscription && !this.isInitializing) {
             this.startListening().catch(err => {
                 console.error("RosInterface: Error starting live listener", err);
@@ -31,13 +70,20 @@ class LiveCollection {
         }
         return sub;
     }
+    /**
+     * Internal method to establish the connection via the client.
+     */
     async startListening() {
         if (this.isInitializing)
             return;
         this.isInitializing = true;
         try {
+            // Initialize Command
             const cmd = this.client.command(this.path);
+            // Optimization: Request specific fields to reduce CPU load on Router.
+            // CRITICAL: We MUST include '.dead' to detect deletions.
             cmd.where('.proplist', '.id,.dead,name,comment,disabled,profile,service,user,password,address,uptime,mac-address,caller-id,bytes-in,bytes-out,radius');
+            // Apply Filters from Query
             if (this.query) {
                 Object.keys(this.query).forEach(key => {
                     const value = this.query[key];
@@ -46,6 +92,7 @@ class LiveCollection {
                     }
                 });
             }
+            // Start Streaming
             this.subscription = cmd.listen((packet) => {
                 this.processPacket(packet);
             });
@@ -55,31 +102,53 @@ class LiveCollection {
             this.isInitializing = false;
         }
     }
+    /**
+     * Processes incoming raw packets from RouterOS.
+     * Handles creation, updates, and deletion based on packet flags.
+     * @param packet Raw data from the router.
+     */
     processPacket(packet) {
+        // RouterOS raw packets use '.id', but sometimes it might be parsed as 'id'
         const rawId = packet['.id'] || packet['id'];
+        // Ignore status packets (!done, !fatal)
         if (!rawId)
             return;
+        // HANDLE DELETION
         if (packet['.dead'] === true || packet['dead'] === true) {
             this.localCache.delete(rawId);
         }
+        // HANDLE UPDATE / INSERT
         else {
             const existing = this.localCache.get(rawId) || {};
+            // Normalize keys: Remove leading dots
             const cleanPacket = {};
             for (const key of Object.keys(packet)) {
                 const cleanKey = key.startsWith('.') ? key.substring(1) : key;
                 cleanPacket[cleanKey] = packet[key];
             }
+            // Merge with existing data to support partial updates
             const updated = { ...existing, ...cleanPacket };
             this.localCache.set(rawId, updated);
         }
+        // BROADCAST TO SMART SUBSCRIPTIONS
+        // Instead of sending the array directly, we let the Subscription object
+        // decide IF and WHEN to send it (Throttle) and HOW (Diff/Join).
         this.emit();
     }
+    /**
+     * Broadcasts the current array of items to all smart subscriptions.
+     */
     emit() {
         const fullList = Array.from(this.localCache.values());
+        // We delegate the logic to each subscription.
+        // One user might want Diffs, another might want the full list throttled.
         this.subscriptions.forEach(sub => {
             sub.processUpdate(fullList);
         });
     }
+    /**
+     * Stops the low-level connection to the router.
+     */
     stopListening() {
         if (this.subscription) {
             try {