rosinterface 1.2.1 → 1.3.1

package/README.md

@@ -1,4 +1,4 @@
-# RosInterface v1.2
+# RosInterface v1.3
 
 > **High-Performance RouterOS Automation A modern TypeScript and JavasScript Library for MikroTik interactions.**  
 > Built with Reactive Streaming (onSnapshot), Circuit Breakers for fault tolerance, and an Offline Queue system.
@@ -16,8 +16,12 @@
 
 ## English Documentation
 
-**RosInterface** is designed for **ISPs and mission-critical environments**.  
-It focuses on **connection stability**, **router hardware protection**, and **efficient data access**, even under unstable network conditions.
+**RosInterface** is a high-performance Node.js library designed for ISPs and mission-critical network environments.
+It goes beyond simple API wrappers by introducing a unique Hybrid Engine that seamlessly unifies the transactional safety of REST (HTTPS) with the real-time speed of Sockets (TCP).
+This architecture allows for robust management of mixed environments (RouterOS v6 & v7) without code changes.
+
+Built with stability and hardware protection at its core, **RosInterface** ensures efficient data access even under unstable network conditions, preventing CPU spikes and connection floods.
+
 
 ---
 
@@ -62,6 +66,19 @@ It focuses on **connection stability**, **router hardware protection**, and **ef
 - **Intelligent Throttling**  
   Control the flow of real-time data with "Leading + Trailing Edge" strategies.
 
+- **Intelligent Hybrid Engine:**
+
+  - Combines the security of the **REST (HTTPS)** protocol for CRUD commands with the speed of **Sockets (TCP)** for data streaming.
+  - *RouterOS v7:* Uses HTTPS + Sockets (Background).
+  - *RouterOS v6:* Uses pure Sockets (Legacy Mode).
+
+- **Swarm Mode:**
+Manages fleets of **50+ routers** from a single instance.
+  - Supports **Broadcast** (all nodes) and **Multicast** (selected groups).
+  - Fault Tolerance: If one router fails, the rest of the swarm continues operating.
+  - Protocol Agnosticism: Mixes modern and legacy routers in the same control group.
+
+  
 ---
 
 
@@ -74,10 +91,47 @@ It focuses on **connection stability**, **router hardware protection**, and **ef
 Create a `.env` file in the root directory of your project:
 
 ```text
-MIKROTIK_HOST=ROUTER_IP
-MIKROTIK_USER=admin
-MIKROTIK_PASSWORD=your_password
-MIKROTIK_PORT=8729
+Basic Credentials
+These are the standard login credentials.
+
+MIKROTIK_HOST: Your router's IP address (e.g., 192.168.1.1).
+
+MIKROTIK_USER: Username with write permissions (e.g., admin).
+
+MIKROTIK_PASSWORD: User password.
+
+The Brain (Main Protocol)
+Here you decide how commands (Create, Edit, Delete) will be sent.
+
+MIKROTIK_PROTOCOL
+
+rest: (Recommended for RouterOS v7+). Uses HTTPS. It is more secure and handles errors better.
+
+socket: (For RouterOS v6). Uses a raw TCP connection. Use it only if your router is old and does not support REST.
+
+MIKROTIK_PORT
+
+This is the port for the protocol chosen above.
+
+If you use rest: Enter 443 (the router's www-ssl port).
+
+If you're using a socket: Enter 8728 (the API port).
+
+SSL Security
+MIKROTIK_INSECURE
+
+true: (Almost always necessary on local networks). Tells the library: "Trust the router's certificate even if it's self-signed." Uses the secure dispatcher internally.
+
+false: Only use this if you've purchased a real domain (e.g., router.example.com) and installed a valid certificate on the Mikrotik.
+
+The "Listen" (Hybrid Engine)
+This is the main variable for real-time events (onSnapshot) while using REST.
+
+MIKROTIK_PORT_APISSL (or socketPort in the code)
+
+If you leave it empty: Hybrid mode is disabled. You can only send commands, but you won't be able to listen for live changes.
+
+If you enter 8728: You activate Hybrid Mode. The library will use REST to send commands and will open a hidden channel on 8728 to listen for onSnapshot.
 ```
 
 > ⚠️ **Security Notice**  
@@ -95,6 +149,21 @@ MIKROTIK_PORT=8729
 > Use it **in moderation; excessive use of onSnapshot can negatively affect the performance of your devices**.
 
 
+> ⚠️ **Basic Configurations on Your Equipment**
+> 
+> Before running these codes, ensure your RouterOS configuration matches:
+> > **Ports (Hybrid Mode):**
+>>
+> > REST (Commands): Requires the www-ssl service enabled on the router (Default port 443).
+>>
+> > Socket (Streaming): Requires the api service (Default 8728) or api-ssl (Default 8729).
+> >
+>> **Certificates (Self-Signed):**
+> >
+> > By setting `rejectUnauthorized: false` in the MikrotikClient options, the library uses the Undici Dispatcher (Agent with Scope).
+> >
+> **This means that traffic remains encrypted (HTTPS), but the library will accept the router's self-generated certificate without failure. This does not compromise the security of other external connections (such as Stripe/AWS) in your Node.js application.**
+
 ---
 
 
@@ -363,14 +432,125 @@ async function createSecureUser() {
 ```
 
 
+#### 11. Hybrid Engine (REST + Sockets) & Idempotency
+
+```ts
+import { MikrotikClient } from 'rosinterface';
+
+const delay = (ms: number) => new Promise(res => setTimeout(res, ms));
+
+async function runHybridTest() {
+    console.log("Starting Hybrid Engine Test");
+
+    const client = new MikrotikClient({
+        host: '10.0.0.1',
+        user: 'admin',
+        password: 'password',
+        // HYBRID CONFIGURATION:
+        protocol: 'rest',       // Primary Brain: HTTPS (Port 443)
+        port: 443,
+        socketPort: 8728,       // Secondary Ear: TCP (Port 8728 for Streams)
+        rejectUnauthorized: false // Accept Self-Signed Certs (Safe Dispatcher)
+    });
+
+    try {
+        await client.connect();
+        console.log("Hybrid Connection Established (HTTPS + TCP)");
+
+        // LIVE MONITORING (Via Socket 8728)
+        console.log("Listening for changes...");
+        client.collection('/ppp/secret')
+            .onSnapshot(data => {
+                if ('added' in data) console.log('Live Stream [New]:', data.added.map(x => x.name));
+                if ('removed' in data) console.log('Live Stream [Deleted]:', data.removed.map(x => x.name));
+            })
+            .onDiff();
+
+        await delay(1000);
+
+        // IDEMPOTENCY (Via REST 443)
+        // Attempt to create the same user twice. The second time should NOT fail.
+        const userPayload = { name: 'hybrid_user', password: '123', service: 'pppoe' };
+
+        console.log("Creating User...");
+        await client.command('/ppp/secret').idempotent().add(userPayload);
+
+        console.log("Creating User Again (Idempotency Check)...");
+        // This will strictly recover the existing ID without throwing an error
+        const result = await client.command('/ppp/secret').idempotent().add(userPayload);
+        console.log("Idempotency Result:", result); // Should return the existing object
+
+        await delay(2000);
+
+        // Cleanup
+        await client.command('/ppp/secret').remove(result['.id']);
+        console.log("Cleanup done.");
+
+    } catch (e) {
+        console.error("Error:", e);
+    } finally {
+        // Graceful shutdown prevents "Socket Closed" errors
+        client.close();
+    }
+}
+
+runHybridTest();
+```
+
+#### 12. Swarm Mode (Mass Management)
+
+```ts
+import { MikrotikSwarm } from 'rosinterface';
+
+async function runSwarmTest() {
+    const swarm = new MikrotikSwarm();
+
+    // Node A: Modern Router (v7) -> Uses REST
+    swarm.addNode('CORE_ROUTER', {
+        host: '192.168.1.1',
+        user: 'admin',
+        password: 'secure',
+        protocol: 'rest',
+        port: 443
+    });
+
+    // Node B: Legacy Router (v6) -> Uses Sockets
+    swarm.addNode('TOWER_A', {
+        host: '10.20.30.50',
+        user: 'admin',
+        password: 'old',
+        protocol: 'socket',
+        port: 8728
+    });
+
+    console.log("Connecting Swarm...");
+    await swarm.connectAll();
+
+    // BROADCAST: Send command to ALL routers in parallel
+    console.log("Broadcasting Firewall Rule...");
+    const results = await swarm.broadcast('/ip/dns/set', {
+        'allow-remote-requests': 'yes'
+    });
+
+    results.forEach(res => {
+        console.log(`[${res.nodeId}] Success: ${res.success}`);
+    });
+
+    swarm.closeAll();
+}
 
+runSwarmTest();
+```
 
 ---
 
 ## Documentación en Español
 
-**RosInterface** está diseñado para **ISPs y entornos críticos**.  
-Su objetivo es garantizar **estabilidad de conexión**, **protección del hardware MikroTik** y **consultas eficientes**, incluso con enlaces inestables.
+**RosInterface** es una biblioteca Node.js de alto rendimiento diseñada para proveedores de servicios de internet (ISP) y entornos de red críticos.
+Va más allá de los simples envoltorios de API al introducir un motor híbrido único que unifica a la perfección la seguridad transaccional de REST (HTTPS) con la velocidad en tiempo real de los sockets (TCP).
+Esta arquitectura permite una gestión robusta de entornos mixtos (RouterOS v6 y v7) sin necesidad de modificar el código.
+
+Construida con la estabilidad y la protección del hardware como base, **RosInterface** garantiza un acceso eficiente a los datos incluso en condiciones de red inestables, evitando picos de CPU y sobrecargas de conexión.
 
 ---
 
@@ -415,6 +595,20 @@ Su objetivo es garantizar **estabilidad de conexión**, **protección del hardwa
 
   Controle el flujo de datos en tiempo real con estrategias de vanguardia y vanguardia.
 
+- **Motor Híbrido Inteligente:**
+
+  Combina la seguridad del protocolo **REST (HTTPS)** para comandos CRUD con la velocidad de **Sockets (TCP)** para streaming de datos.
+    - *RouterOS v7:* Usa HTTPS + Sockets (Background).
+    - *RouterOS v6:* Usa Sockets puro (Legacy Mode).
+
+- **Modo Enjambre (Swarm):**
+
+  Administra flotas de **50+ routers** desde una sola instancia.
+    - Soporte para **Broadcast** (todos los nodos) y **Multicast** (grupos selectos).
+    - Tolerancia a fallos: Si un router no responde, el resto del enjambre sigue operando.
+    - Agnosticismo de Protocolo: Mezcla routers modernos y antiguos en el mismo grupo de control.
+
+
 ---
 
 ### ✨ Consideraciones Importantes
@@ -424,10 +618,49 @@ Su objetivo es garantizar **estabilidad de conexión**, **protección del hardwa
 Crea un archivo `.env` en el directorio raíz de tu proyecto:
 
 ```text
-MIKROTIK_HOST=IP_DEL_ROUTER
-MIKROTIK_USER=admin
-MIKROTIK_PASSWORD=tu_contraseña
-MIKROTIK_PORT=8729
+Credenciales Básicas
+Son los datos de acceso estándar.
+
+MIKROTIK_HOST: La IP de tu router (ej. 192.168.1.1).
+
+MIKROTIK_USER: Usuario con permisos de escritura (ej. admin).
+
+MIKROTIK_PASSWORD: Contraseña del usuario.
+
+El Cerebro (Protocolo Principal)
+Aquí decides cómo se enviarán los comandos (Crear, Editar, Borrar).
+
+MIKROTIK_PROTOCOL
+
+rest: (Recomendado para RouterOS v7+). Usa HTTPS. Es más seguro y maneja mejor los errores.
+
+socket: (Para RouterOS v6). Usa conexión TCP cruda. Úsalo solo si tu router es viejo y no soporta REST.
+
+MIKROTIK_PORT
+
+Es el puerto del protocolo elegido arriba.
+
+Si usas rest: Pon 443 (el puerto www-ssl del router).
+
+Si usas socket: Pon 8728 (el puerto api).
+
+Seguridad SSL
+MIKROTIK_INSECURE
+
+true: (Casi siempre necesario en redes locales). Le dice a la librería: "Confía en el certificado del router aunque sea autofirmado". Usa el Dispatcher seguro internamente.
+
+false: Solo úsalo si has comprado un dominio real (ej. router.ejemplo.com) y le instalaste un certificado válido al Mikrotik.
+
+
+El "Oído" (Motor Híbrido)
+Esta es la variable principal para tener eventos en tiempo real (onSnapshot) mientras usas REST.
+
+MIKROTIK_PORT_APISSL (o socketPort en el código)
+
+Si lo dejas vacío: El modo híbrido se apaga. Solo podrás enviar comandos, pero no escuchar cambios en vivo.
+
+Si pones 8728: Activas el Modo Híbrido. La librería usará REST para mandar órdenes y abrirá un canal oculto en el 8728 para escuchar el onSnapshot.
+
 ```
 
 > ⚠️ **Aviso de Seguridad**  
@@ -444,6 +677,22 @@ MIKROTIK_PORT=8729
 > Úsala **con moderación, el abuso de onSnapshot puede afectar el rendimiento de tus equipos**.
 
 
+> ⚠️ **Configuraciones básicas en tus equipos**  
+> Antes de ejecutar estos códigos, asegúrese de que la configuración de RouterOS coincida:
+> > **Puertos (Modo Híbrido):**
+> >
+> > REST (Comandos): Requiere el servicio www-ssl habilitado en el router (Puerto predeterminado 443).
+> >
+> > Socket (Streaming): Requiere el servicio api (Predeterminado 8728) o api-ssl (Predeterminado 8729).
+> >
+>> **Certificados (Autofirmados):**
+> >
+> >Al configurar `rejectUnauthorized: false` en las opciones de MikrotikClient, la biblioteca utiliza el Despachador Undici (Agente con Ámbito).
+> >
+> **Esto implica que el tráfico sigue estando cifrado (HTTPS), pero la biblioteca aceptará el certificado autogenerado del router sin fallar. Esto no compromete la seguridad de otras conexiones externas (como Stripe/AWS) en su aplicación Node.js.**
+
+
+
 
 ---
 
@@ -677,7 +926,7 @@ client.command('/log').print().then(result => {
 > > npm run codegen -- -p /ppp/secret -n ISecret
 >
 > OPCIÓN B: Configuración Manual (Pruebas Rápidas / CI)
-> PPasa los detalles de conexión directamente mediante banderas. Usa comillas dobles para contraseñas con caracteres especiales.
+> Pasa los detalles de conexión directamente mediante banderas. Usa comillas dobles para contraseñas con caracteres especiales.
 > >npm run codegen -- -p /ppp/secret -n ISecret --host ROUTER_IP --user admin --pass "secret123" --port 8728
 
 
@@ -712,6 +961,124 @@ async function createSecureUser() {
 ```
 
 
+
+#### 11. Hybrid Engine (REST + Sockets) & Idempotency
+
+```ts
+import { MikrotikClient } from 'rosinterface';
+
+const delay = (ms: number) => new Promise(res => setTimeout(res, ms));
+
+async function ejecutarTestHibrido() {
+    console.log("Iniciando Motor Híbrido");
+
+    const client = new MikrotikClient({
+        host: '192.168.1.1',
+        user: 'IVMEX',
+        password: 'password',
+        // CONFIGURACIÓN HÍBRIDA:
+        protocol: 'rest',       // Cerebro Principal: HTTPS (Puerto 443)
+        port: 443,
+        socketPort: 8728,       // Oído Secundario: TCP (Puerto 8728 para Streams)
+        rejectUnauthorized: false // Aceptar Certs Autofirmados (Usa Dispatcher Seguro)
+    });
+
+    try {
+        await client.connect();
+        console.log("Conexión Híbrida Establecida (HTTPS + TCP)");
+
+        // A. MONITOREO EN VIVO (Vía Socket 8728)
+        console.log("Escuchando cambios...");
+        client.collection('/ppp/secret')
+            .onSnapshot(data => {
+                if ('added' in data) console.log('Stream [Nuevo]:', data.added.map(x => x.name));
+                if ('removed' in data) console.log('Stream [Eliminado]:', data.removed.map(x => x.name));
+            })
+            .onDiff();
+
+        await delay(1000);
+
+        // B. IDEMPOTENCIA (Vía REST 443)
+        // Intentamos crear el mismo usuario dos veces. La segunda NO debe fallar.
+        const datosUsuario = { name: 'usuario_hibrido', password: '123', service: 'pppoe' };
+
+        console.log("Creando Usuario...");
+        await client.command('/ppp/secret').idempotent().add(datosUsuario);
+
+        console.log("Creando Usuario Nuevamente (Prueba Idempotencia)...");
+        // Esto recuperará el ID existente sin lanzar error
+        const resultado = await client.command('/ppp/secret').idempotent().add(datosUsuario);
+        console.log("Resultado Idempotencia:", resultado); // Debe devolver el objeto existente
+
+        await delay(2000);
+
+        // Limpieza
+        await client.command('/ppp/secret').remove(resultado['.id']);
+        console.log("Limpieza completada.");
+
+    } catch (e) {
+        console.error("Error:", e);
+    } finally {
+        // Cierre elegante evita errores de "Socket Closed"
+        client.close();
+    }
+}
+
+ejecutarTestHibrido();
+```
+
+
+
+#### 12. Swarm Mode (Mass Management)
+
+```ts
+import { MikrotikSwarm } from 'rosinterface';
+
+async function ejecutarTestEnjambre() {
+    const enjambre = new MikrotikSwarm();
+
+    // Nodo A: Router Moderno (v7) -> Usa REST
+    enjambre.addNode('ROUTER_CENTRAL', {
+        host: '192.168.1.1',
+        user: 'admin',
+        password: 'segura',
+        protocol: 'rest',
+        port: 443
+    });
+
+    // Nodo B: Router Antiguo (v6) -> Usa Sockets
+    enjambre.addNode('TORRE_NORTE', {
+        host: '10.20.30.50',
+        user: 'admin',
+        password: 'vieja',
+        protocol: 'socket',
+        port: 8728
+    });
+
+    console.log("Conectando Enjambre...");
+    await enjambre.connectAll();
+
+    // BROADCAST: Enviar comando a TODOS los routers en paralelo
+    console.log("Difundiendo configuración DNS...");
+    const resultados = await enjambre.broadcast('/ip/dns/set', {
+        'allow-remote-requests': 'yes',
+        'servers': '8.8.8.8,1.1.1.1'
+    });
+
+    resultados.forEach(res => {
+        if (res.success) {
+            console.log(`[${res.nodeId}] Éxito`);
+        } else {
+            console.log(`[${res.nodeId}] Falló: ${res.error}`);
+        }
+    });
+
+    enjambre.closeAll();
+}
+
+ejecutarTestEnjambre();
+```
+
 ---
 
 ## Author's Note / Nota del Autor

package/dist/cli/{generate.js → Generate.js}

@@ -44,25 +44,37 @@ const path = __importStar(require("path"));
 const chalk_1 = __importDefault(require("chalk"));
 const ora_1 = __importDefault(require("ora"));
 const dotenv_1 = __importDefault(require("dotenv"));
+// Load .env (if available)
 dotenv_1.default.config();
 const program = new commander_1.Command();
 program
     .name('ros-codegen')
     .description('Generates TypeScript interfaces from your live MikroTik router')
     .version('1.2.0')
+    // Mandatory Generation Params
     .requiredOption('-p, --path <menu>', 'MikroTik Menu Path (e.g. /ppp/secret)')
     .requiredOption('-n, --name <interface>', 'Name of the output Interface (e.g. PPPSecret)')
     .option('-o, --output <dir>', 'Output directory', './src/generated')
+    // Optional Connection Params (Overrides .env if provided)
     .option('--host <host>', 'Router Host/IP')
     .option('--user <user>', 'Router Username')
     .option('--pass <password>', 'Router Password')
     .option('--port <port>', 'Router API Port')
     .option('--tls', 'Use TLS (SSL) connection', false)
     .action(async (options) => {
+    // ==========================================
+    // 1. CREDENTIALS RESOLUTION STRATEGY
+    // Priority: CLI Flag > Environment Variable
+    // ==========================================
     const host = options.host || process.env.MIKROTIK_HOST;
     const user = options.user || process.env.MIKROTIK_USER;
     const password = options.pass || process.env.MIKROTIK_PASS;
+    // TLS Logic: Flag OR Env Var string 'true'
     const useTLS = options.tls || process.env.MIKROTIK_USE_TLS === 'true';
+    // Port Logic:
+    // 1. CLI Flag
+    // 2. Env Var
+    // 3. Default based on TLS (8729 vs 8728)
     let port;
     if (options.port) {
         port = parseInt(options.port, 10);
@@ -73,6 +85,7 @@ program
     else {
         port = useTLS ? 8729 : 8728;
     }
+    // Pre-flight Validation
     if (!host || !user || !password) {
         console.error(chalk_1.default.red('Error: Missing credentials.'));
         console.error(chalk_1.default.yellow('You must provide credentials via .env file OR CLI flags.'));
@@ -83,23 +96,27 @@ Usage Example:
         process.exit(1);
     }
     const spinner = (0, ora_1.default)(`Connecting to ${host}:${port}...`).start();
+    // Initialize Client
     const client = new MikrotikClient_1.MikrotikClient({
         host: host,
         user: user,
         password: password,
         port: port,
         useTLS: useTLS,
-        allowInsecureConfig: true
+        allowInsecureConfig: true // Suppress warnings for CLI tool since hardcoding is expected here
     });
     try {
         await client.connect();
         spinner.text = `Fetching schema from ${options.path}...`;
+        // Fetch Real Data (The "Truth")
         const data = await client.write(`${options.path}/print`);
         if (data.length === 0) {
             spinner.warn(chalk_1.default.yellow(' Warning: No data found in this menu. Generated interface will be empty or generic.'));
         }
+        // Infer Schema
         spinner.text = 'Inferring Types & Generating Code...';
         const tsCode = SchemaInferrer_1.SchemaInferrer.generateInterface(options.name, data);
+        // Add File Header
         const fileContent = `
 /**
  * AUTO-GENERATED FILE - DO NOT EDIT MANUALLY
@@ -110,11 +127,13 @@ Usage Example:
 
 ${tsCode}
 `;
+        // Write to File
         const outputDir = path.resolve(options.output);
         await fs.ensureDir(outputDir);
         const filePath = path.join(outputDir, `${options.name}.ts`);
         await fs.writeFile(filePath, fileContent);
         spinner.succeed(chalk_1.default.green(`Successfully generated ${options.name}.ts in ${options.output}`));
+        // Show Preview
         console.log(chalk_1.default.gray('\nPreview:'));
         console.log(chalk_1.default.cyan(tsCode.split('\n').slice(0, 15).join('\n') + '\n...'));
     }
@@ -136,4 +155,4 @@ ${tsCode}
     }
 });
 program.parse(process.argv);
-//# sourceMappingURL=generate.js.map
+//# sourceMappingURL=Generate.js.map

package/dist/cli/Generate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Generate.js","sourceRoot":"","sources":["../../src/cli/Generate.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,yCAAoC;AACpC,6DAA0D;AAC1D,qDAAkD;AAClD,6CAA+B;AAC/B,2CAA6B;AAC7B,kDAA0B;AAC1B,8CAAsB;AACtB,oDAA4B;AAE5B,2BAA2B;AAC3B,gBAAM,CAAC,MAAM,EAAE,CAAC;AAEhB,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;AAE9B,OAAO;KACF,IAAI,CAAC,aAAa,CAAC;KACnB,WAAW,CAAC,gEAAgE,CAAC;KAC7E,OAAO,CAAC,OAAO,CAAC;IACjB,8BAA8B;KAC7B,cAAc,CAAC,mBAAmB,EAAE,uCAAuC,CAAC;KAC5E,cAAc,CAAC,wBAAwB,EAAE,+CAA+C,CAAC;KACzF,MAAM,CAAC,oBAAoB,EAAE,kBAAkB,EAAE,iBAAiB,CAAC;IAEpE,0DAA0D;KACzD,MAAM,CAAC,eAAe,EAAE,gBAAgB,CAAC;KACzC,MAAM,CAAC,eAAe,EAAE,iBAAiB,CAAC;KAC1C,MAAM,CAAC,mBAAmB,EAAE,iBAAiB,CAAC;KAC9C,MAAM,CAAC,eAAe,EAAE,iBAAiB,CAAC;KAC1C,MAAM,CAAC,OAAO,EAAE,0BAA0B,EAAE,KAAK,CAAC;KAElD,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;IACtB,6CAA6C;IAC7C,qCAAqC;IACrC,4CAA4C;IAC5C,6CAA6C;IAE7C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;IACvD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;IACvD,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;IAE3D,2CAA2C;IAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,KAAK,MAAM,CAAC;IAEtE,cAAc;IACd,cAAc;IACd,aAAa;IACb,yCAAyC;IACzC,IAAI,IAAY,CAAC;IACjB,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACf,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACtC,CAAC;SAAM,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;QACnC,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;IACnD,CAAC;SAAM,CAAC;QACJ,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAChC,CAAC;IAED,wBAAwB;IACxB,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC9B,OAAO,CAAC,KAAK,CAAC,eAAK,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC,CAAC;QACxD,OAAO,CAAC,KAAK,CAAC,eAAK,CAAC,MAAM,CAAC,0DAA0D,CAAC,CAAC,CAAC;QACxF,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,IAAI,CAAC;;;aAGtB,CAAC,CAAC,CAAC;QACJ,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IAED,MAAM,OAAO,GAAG,IAAA,aAAG,EAAC,iBAAiB,IAAI,IAAI,IAAI,KAAK,CAAC,CAAC,KAAK,EAAE,CAAC;IAEhE,oBAAoB;IACpB,MAAM,MAAM,GAAG,IAAI,+BAAc,CAAC;QAC9B,IAAI,EAAE,IAAI;QACV,IAAI,EAAE,IAAI;QACV,QAAQ,EAAE,QAAQ;QAClB,IAAI,EAAE,IAAI;QACV,MAAM,EAAE,MAAM;QACd,mBAAmB,EAAE,IAAI,CAAC,mEAAmE;KAChG,CAAC,CAAC;IAEH,IAAI,CAAC;QACD,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;QAEvB,OAAO,CAAC,IAAI,GAAG,wBAAwB,OAAO,CAAC,IAAI,KAAK,CAAC;QAEzD,gCAAgC;QAChC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,QAAQ,CAAC,CAAC;QAEzD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpB,OAAO,CAAC,IAAI,CAAC,eAAK,CAAC,MAAM,CAAC,qFAAqF,CAAC,CAAC,CAAC;QACtH,CAAC;QAED,eAAe;QACf,OAAO,CAAC,IAAI,GAAG,sCAAsC,CAAC;QACtD,MAAM,MAAM,GAAG,+BAAc,CAAC,iBAAiB,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAEpE,kBAAkB;QAClB,MAAM,WAAW,GAAG;;;;aAInB,OAAO,CAAC,IAAI;WACd,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;;;EAGjC,MAAM;CACP,CAAC;QAEU,gBAAgB;QAChB,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC/C,MAAM,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC;QAE5D,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;QAE1C,OAAO,CAAC,OAAO,CAAC,eAAK,CAAC,KAAK,CAAC,0BAA0B,OAAO,CAAC,IAAI,UAAU,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAE/F,eAAe;QACf,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;QACtC,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAElF,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QAClB,OAAO,CAAC,IAAI,CAAC,eAAK,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC,CAAC;QAE7C,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YAChC,OAAO,CAAC,KAAK,CAAC,eAAK,CAAC,GAAG,CAAC,wBAAwB,IAAI,IAAI,IAAI,kBAAkB,CAAC,CAAC,CAAC;QACrF,CAAC;aAAM,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1D,OAAO,CAAC,KAAK,CAAC,eAAK,CAAC,GAAG,CAAC,kCAAkC,IAAI,mBAAmB,CAAC,CAAC,CAAC;QACxF,CAAC;aAAM,CAAC;YACJ,OAAO,CAAC,KAAK,CAAC,eAAK,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAC5C,CAAC;IACL,CAAC;YAAS,CAAC;QACP,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;AACL,CAAC,CAAC,CAAC;AAEP,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/cli/SchemaInferrer.d.ts

@@ -1,4 +1,13 @@
+/**
+ * Analyzes raw MikroTik data and infers TypeScript types.
+ */
 export declare class SchemaInferrer {
+    /**
+     * Main entry point: Generates the Interface string from raw data items.
+     */
     static generateInterface(interfaceName: string, dataSample: Record<string, any>[]): string;
+    /**
+     * Heuristic Engine to determine the best TypeScript type.
+     */
     private static inferType;
 }

package/dist/cli/SchemaInferrer.js

@@ -1,9 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SchemaInferrer = void 0;
+/**
+ * Analyzes raw MikroTik data and infers TypeScript types.
+ */
 class SchemaInferrer {
+    /**
+     * Main entry point: Generates the Interface string from raw data items.
+     */
     static generateInterface(interfaceName, dataSample) {
         const fieldStats = {};
+        // Collect all possible values for each field across the sample
         dataSample.forEach(item => {
             Object.keys(item).forEach(key => {
                 if (!fieldStats[key])
@@ -11,30 +18,42 @@ class SchemaInferrer {
                 fieldStats[key].add(String(item[key]));
             });
         });
+        // Build the Interface lines
         const lines = [];
         lines.push(`export interface ${interfaceName} {`);
         Object.keys(fieldStats).sort().forEach(key => {
             const values = Array.from(fieldStats[key]);
             const type = this.inferType(key, values);
+            // MikroTik fields are mostly optional as they depend on configuration
             const isOptional = true;
-            const propName = key.includes('-') ? `'${key}'` : key;
+            const propName = key.includes('-') ? `'${key}'` : key; // Quote kebab-case
             lines.push(`    /** Sample values: ${values.slice(0, 3).join(', ')}... */`);
             lines.push(`    ${propName}${isOptional ? '?' : ''}: ${type};`);
         });
         lines.push(`}`);
         return lines.join('\n');
     }
+    /**
+     * Heuristic Engine to determine the best TypeScript type.
+     */
     static inferType(key, values) {
+        // Boolean Detection (true/false/yes/no)
         const isBoolean = values.every(v => ['true', 'false', 'yes', 'no'].includes(v.toLowerCase()));
         if (isBoolean)
-            return 'boolean | string';
+            return 'boolean | string'; // string fallback for safety
+        // Number Detection
+        // Checks if all values look like numbers (ignoring empty strings)
         const isNumber = values.every(v => v === '' || !isNaN(Number(v)));
         if (isNumber && values.length > 0)
             return 'number | string';
+        // Enum / Union Type Detection
+        // If we see very few unique values (e.g. 'running' | 'stopped'), create a Union.
+        // Limit: Max 10 unique values to consider it an Enum.
         if (values.length > 0 && values.length < 10 && !isNumber) {
             const union = values.map(v => `'${v}'`).join(' | ');
-            return `${union} | string`;
+            return `${union} | string`; // Append string to allow future values
         }
+        // Default
         return 'string';
     }
 }

package/dist/cli/SchemaInferrer.js.map

@@ -1 +1 @@
-{"version":3,"file":"SchemaInferrer.js","sourceRoot":"","sources":["../../src/cli/SchemaInferrer.ts"],"names":[],"mappings":";;;AAGA,MAAa,cAAc;IAKhB,MAAM,CAAC,iBAAiB,CAAC,aAAqB,EAAE,UAAiC;QACpF,MAAM,UAAU,GAAgC,EAAE,CAAC;QAGnD,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE;YACtB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;gBAC5B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;oBAAE,UAAU,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,EAAE,CAAC;gBAClD,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC3C,CAAC,CAAC,CAAC;QACP,CAAC,CAAC,CAAC;QAGH,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC,oBAAoB,aAAa,IAAI,CAAC,CAAC;QAElD,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;YACzC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;YAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAGzC,MAAM,UAAU,GAAG,IAAI,CAAC;YACxB,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;YAEtD,KAAK,CAAC,IAAI,CAAC,0BAA0B,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC5E,KAAK,CAAC,IAAI,CAAC,OAAO,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,GAAG,CAAC,CAAC;QACpE,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAKO,MAAM,CAAC,SAAS,CAAC,GAAW,EAAE,MAAgB;QAElD,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;QAC9F,IAAI,SAAS;YAAE,OAAO,kBAAkB,CAAC;QAIzC,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAClE,IAAI,QAAQ,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,iBAAiB,CAAC;QAK5D,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACvD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpD,OAAO,GAAG,KAAK,WAAW,CAAC;QAC/B,CAAC;QAGD,OAAO,QAAQ,CAAC;IACpB,CAAC;CACJ;AA5DD,wCA4DC"}
+{"version":3,"file":"SchemaInferrer.js","sourceRoot":"","sources":["../../src/cli/SchemaInferrer.ts"],"names":[],"mappings":"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"}