rosinterface 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,252 @@
+# RosInterface 
+
+> **Enterprise-Grade MikroTik RouterOS API Client for Node.js**  
+> High-performance, **Offline-First** and **Type-Safe** framework for modern network automation.
+
+[![npm version](https://img.shields.io/npm/v/rosinterface.svg?style=flat-square)](https://www.npmjs.com/package/rosinterface)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
+---
+
+## 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.
+
+---
+
+### ✨ Key Features
+
+- **🛡️ Hardware Protection**  
+  Built-in **Rate Limiter** with intelligent backoff to prevent RouterOS CPU saturation.
+
+- **🔌 Offline-First Architecture**  
+  Commands marked with `.persistent()` are automatically queued if the router is offline and synchronized once connectivity is restored.
+
+- **🧠 Smart Caching**  
+  Read operations are cached for **5 seconds (TTL)** to reduce redundant API calls and router load.
+
+- **🔍 Source-Side Filtering**  
+  Use `.findBy()` and `.findOne()` to filter data **directly on the router**, minimizing bandwidth and latency.
+
+- **🌊 Fluent API**  
+  Chainable, expressive syntax for clean and maintainable automation code.
+
+---
+
+
+---
+
+### ✨ Important Considerations
+
+#### 📄 Environment Variables (.env)
+
+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
+```
+
+> ⚠️ **Security Notice**  
+> The `allowInsecureConfig` flag is a **critical** security measure in RosInterface.  
+> Prevents accidental exposure of credentials or use of unencrypted protocols in production.
+>
+> Use **only in controlled, local or test environments**.
+
+---
+
+
+### 🛠 Usage Examples
+
+#### 1️⃣ Basic Connection
+
+```ts
+import { MikrotikClient } from 'rosinterface';
+
+const client = new MikrotikClient({
+    host: 'IP_DEL_ROUTER',
+    user: 'admin',
+    password: 'password',
+    useTLS: false, // ⚠️ Test only
+    rateLimit: 50,
+    allowInsecureConfig: true // ⚠️ Never in production or release
+});
+
+await client.connect();
+```
+---
+
+---
+
+#### 2️⃣ Recommended connection (Production/Release)
+
+```ts
+import { MikrotikClient } from 'rosinterface';
+import 'dotenv/config';
+
+const client = new MikrotikClient({
+  host: process.env.MIKROTIK_HOST,
+  user: process.env.MIKROTIK_USER,
+  password: process.env.MIKROTIK_PASSWORD,
+  port: Number(process.env.MIKROTIK_PORT) || 8729,
+  useTLS: true,
+  rateLimit: 50
+});
+
+await client.connect();
+```
+
+---
+
+
+
+#### 2️⃣ Optimized Read (select + findOne)
+
+```ts
+const user = await client.command('/ppp/secret')
+  .select(['name', 'profile', 'last-logged-out'])
+  .findOne({ name: 'john_doe' });
+
+console.log(`User: ${user?.name}, Profile: ${user?.profile}`);
+```
+
+---
+
+#### 3️⃣ Resilience with Persistence (Offline-Safe)
+
+```ts
+const result = await client.command('/ppp/secret')
+  .persistent()
+  .add({
+    name: 'new_user',
+    password: 'securePassword123',
+    profile: 'default'
+  });
+
+if (result === 'QUEUED_OFFLINE') {
+  console.log('Router unreachable. Task stored and will sync automatically.');
+}
+```
+
+---
+
+## 📕 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.
+
+---
+
+### ✨ Características Principales
+
+- **🛡️ Protección del Hardware**  
+  Limitador de tasa integrado con retroceso inteligente para evitar saturación de CPU.
+
+- **🔌 Arquitectura Offline-First**  
+  Los comandos con `.persistent()` se guardan en cola si el router no está disponible y se ejecutan automáticamente al reconectar.
+
+- **🧠 Caché Inteligente**  
+  Consultas con TTL de **5 segundos**, reduciendo llamadas innecesarias.
+
+- **🔍 Filtrado en Origen**  
+  `.findBy()` y `.findOne()` filtran directamente en RouterOS sin descargar tablas completas.
+
+- **🌊 API Fluida**  
+  Sintaxis encadenable y clara.
+
+---
+
+### ✨ Consideraciones Importantes
+
+#### 📄 Variables de Entorno (.env)
+
+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
+```
+
+> ⚠️ **Aviso de Seguridad**  
+> La bandera `allowInsecureConfig` es una medida de seguridad **crítica** en RosInterface.  
+> Previene la exposición accidental de credenciales o el uso de protocolos no cifrados en producción.
+>
+> Úsala **solo en entornos controlados, locales o de prueba**.
+
+---
+
+### 🛠 Ejemplos de Uso
+
+#### 1️⃣ Conexión rápida (solo pruebas)
+
+```ts
+import { MikrotikClient } from 'rosinterface';
+
+const client = new MikrotikClient({
+  host: 'IP_DEL_ROUTER',
+  user: 'admin',
+  password: 'password',
+  useTLS: false, // ⚠️ Solo pruebas
+  rateLimit: 50,
+  allowInsecureConfig: true // ⚠️ Nunca en producción
+});
+
+await client.connect();
+```
+
+---
+
+#### 2️⃣ Conexión Recomendada (Producción)
+
+```ts
+import { MikrotikClient } from 'rosinterface';
+import 'dotenv/config';
+
+const client = new MikrotikClient({
+  host: process.env.MIKROTIK_HOST,
+  user: process.env.MIKROTIK_USER,
+  password: process.env.MIKROTIK_PASSWORD,
+  port: Number(process.env.MIKROTIK_PORT) || 8729,
+  useTLS: true,
+  rateLimit: 50
+});
+
+await client.connect();
+```
+
+---
+
+#### 3️⃣ Lectura Optimizada
+
+```ts
+const user = await client.command('/ppp/secret')
+  .select(['name', 'profile', 'last-logged-out'])
+  .findOne({ name: 'john_doe' });
+
+console.log(`User: ${user?.name}, Profile: ${user?.profile}`);
+```
+
+---
+
+#### 4️⃣ Persistencia Offline
+
+```ts
+const result = await client.command('/ppp/secret')
+  .persistent()
+  .add({
+    name: 'new_user',
+    password: 'securePassword123',
+    profile: 'default'
+  });
+
+if (result === 'QUEUED_OFFLINE') {
+  console.log('Router unreachable. Task stored and will sync automatically.');
+}
+```
+
+---

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "rosinterface",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "High-performance, Offline-First Mikrotik RouterOS API Client for Enterprise.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "author": "IVMEX",
+  "author": "McBlockier",
   "license": "MIT",
   "keywords": [
     "mikrotik",
@@ -39,4 +39,4 @@
   "engines": {
     "node": ">=14.0.0"
   }
-}
+}