padavan 1.0.1 → 2.0.0

package/README.md

@@ -1,98 +1,125 @@
-Router management with Padavan firmware
+# padavan
 
+[[RU]](./docs/ru/README.md) | [EN]
 
-## Install
+A Node.js library for managing routers running **Padavan** firmware.
 
-``` shell
-npm install padavan
-```
+It interacts with the router via its **Web Interface (HTTP)**, providing
+programmatic access to configuration, diagnostics, and firmware management
+functions.
 
+## Migration
 
-## Usage
-
-```javascript
-import Padavan from 'padavan';
-const client = new Padavan({
-    repo, branch, token, // GITHUB
-    host, username, password // Router
-});
-```
+Upgrading from v1? Check the [Migration Guide](../../docs/MIGRATION.md) for
+details on breaking changes (move from SSH to HTTP, new constructor) and removed
+features.
 
+## Installation
 
-## API
-
-### Get current status
-```javascript
-await client.getStatus();
-// { lavg, uptime, ram, swap, cpu, wifi2, wifi5 }
+```bash
+npm install padavan
 ```
 
-### Get traffic history
-```javascript
-await client.getHistory();
-// { daily_history, monthly_history }
-```
+## Usage
 
-### Get logs
 ```javascript
-await client.getLog();
-```
+import Padavan from 'padavan';
 
-### Get device list
-```javascript
-await client.getDevices();
-// [{ hostname, ip, mac, rssi }]
-```
+const client = new Padavan({
+    credentials: {
+        host: '192.168.1.1',
+        username: 'admin',
+        password: 'password'
+    },
+    logLevel: 'error'
+});
 
-### Get parameters
-```javascript
-await client.getParams(); // Object with all parameters
-await client.getParams('firmver_sub'); // Only { firmver_sub }
-await client.getParams([ 'firmver_sub', 'ip6_service' ]); // { firmver_sub, ip6_service }
+// Get system status
+const status = await client.getStatus();
+console.log(`Uptime: ${status.uptime}`);
 ```
 
-### Set parameters
-```javascript
-await client.setParams({
-	sid_list: 'IP6Connection;',
-	ip6_service: '6in4'
-}); // Enable ipv6
-await client.setParams({
-	ip6_service: ''
-}); // Disable ipv6
-```
+## Configuration
 
-### Start SpeedTest on the device
-```javascript
-await client.startSpeedTest();
-// { networkDownloadSpeedMbps, networkUploadSpeedMbps }
-```
+The constructor accepts a config object with the following properties:
 
-### Start firmware build in the repository
-```javascript
-await client.startBuild();
-```
+| Property | Description |
+| --- | --- |
+| `credentials` | Object containing connection details. |
+| `logLevel` | Logging level: `'none'`, `'error'`, `'info'`, `'debug'`. |
 
-### Get the firmware changelog
-```javascript
-await client.getChangelog();
-await client.getChangelog(from_id, to_id);
-// { from_id, to_id, data: [] }
-```
+### Credentials Object
 
-### Start firmware upgrade
-```javascript
-await client.startUpgrade();
-```
+| Property | Description |
+| --- | --- |
+| `host` | Router IP address or hostname. |
+| `username` | Web interface username. |
+| `password` | Web interface password. |
+| `repo` | GitHub `owner/repo` for firmware updates. |
+| `branch` | GitHub branch (e.g., `main`). |
+| `token` | GitHub PAT for accessing Actions/Artifacts. |
 
-### Reboot
-```javascript
-await client.startReboot();
-```
+## API
 
-### Find repositories with firmware for the device
-```javascript
-await client.find();
-await client.find(productid);
-// [{ repo, branch, active, created_at, name }]
-```
+### System & Diagnostics
+
+- **`getStatus()`**
+  Returns CPU load, RAM usage, uptime, and basic Wi-Fi status.
+- **`getLog()`**
+  Fetches the complete system log.
+- **`exec(command)`**
+  Executes a system command via the web console emulator (`SystemCmd`).
+  *Returns:* Command output (stdout + stderr).
+- **`startReboot()`**
+  Reboots the router via HTTP command.
+
+### Network & Clients
+
+- **`getDevices()`**
+  Returns a list of connected clients from the ARP table and Wi-Fi driver.
+  *Properties:* `mac`, `ip`, `hostname`, `type` (eth, wifi, 2.4GHz, 5GHz),
+  `rssi`.
+- **`getHistory()`**
+  Returns traffic statistics.
+  *Structure:* `{ daily: [...], monthly: [...] }`.
+
+### Wi-Fi Tools
+
+- **`startScan(band)`**
+  Performs a Site Survey (scan).
+  *Band:* `'2.4'` or `'5'`.
+- **`getBestChannel(band)`**
+  **Wi-Fi Doctor**: Scans the environment, calculates interference scores, and
+  recommends the optimal channel for your router.
+
+### NVRAM & Settings
+
+- **`getParams(keys?, page?)`**
+  Returns NVRAM variables.
+  *Arguments:*
+  - `keys`: Specific key string or array of keys. If omitted, returns all.
+  - `page`: If provided, parses input fields from a specific ASP page HTML instead
+    of using `nvram show`.
+- **`setParams(params, options?)`**
+  Sets NVRAM variables.
+  *Options:* `action_mode` (e.g., `' Apply '`), `sid_list` (Service IDs to
+  restart), `group_id`, `current_page`.
+
+### Firmware Management
+
+Requires GitHub credentials (`repo`, `branch`, `token`).
+
+- **`findFirmware(model?)`**
+  Searches for firmware artifacts in the configured repository network (looks
+  into forks).
+- **`getChangelog()`**
+  Compares the current router version with the latest artifact and returns a list
+  of commits.
+- **`startBuild()`**
+  Triggers a GitHub Actions workflow to build new firmware.
+- **`startUpgrade()`**
+  Downloads the latest artifact, uploads it to the router, and flashes it.
+
+## CLI
+
+This package includes a CLI tool. See [CLI Documentation](docs/en-US/CLI.md).

package/bin/cli.js

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import Padavan from '../src/index.js';
+import { formatBytes, formatUptime } from '../src/utils/formatting.js';
+import { DEFAULT_HTTP_CONFIG, DEFAULT_FIRMWARE_REPO, ACTION_MODE, SERVICE_ID, GROUP_ID } from '../src/constants.js';
+/** @import { ActionMode, ServiceId, GroupId } from '../src/constants.js' */
+/** @import { ArgumentsCamelCase } from 'yargs' */
+/** @import { Device, WifiNetwork, ChannelAnalysis } from '../src/index.js' */
+
+/**
+ * @typedef {Object} CommonArgs
+ * @property {string} host
+ * @property {number} port
+ * @property {string} user
+ * @property {string} password
+ * @property {boolean} verbose
+ * @property {boolean} json
+ */
+
+/**
+ * @typedef {Object} FirmwareArgs
+ * @property {string} action
+ * @property {string} [repo]
+ * @property {string} [branch]
+ * @property {string} [token]
+ * @property {string} [model]
+ */
+
+const logInfo = (/** @type {string} */ msg) => console.error(msg);
+
+/**
+ * @param {CommonArgs} argv
+ * @param {any} data
+ * @param {(item: any) => any} [tableTransform]
+ */
+const printOutput = (argv, data, tableTransform = null) => {
+	if (argv.json)
+		return console.log(JSON.stringify(data, null, 2));
+	let output = data;
+	if (tableTransform)
+		output = Array.isArray(data) ? data.map(tableTransform) : tableTransform(data);
+	if (Array.isArray(output))
+		return output.length ? console.table(output) : logInfo('No results found.');
+	if (output && typeof output === 'object')
+		return Object.keys(output).length ? console.table(output) : logInfo('No results found.');
+	console.log(output);
+};
+
+const getClient = (/** @type {ArgumentsCamelCase<CommonArgs & Partial<FirmwareArgs>>} */ argv) => {
+	const logLevel = argv.verbose ? 'debug' : 'none';
+	return new Padavan({ credentials: argv, logLevel });
+};
+
+const args = hideBin(process.argv);
+const cli = yargs(args)
+	.env('PADAVAN')
+	.option('host', { type: 'string', describe: 'Router IP', default: DEFAULT_HTTP_CONFIG.host })
+	.option('port', { type: 'number', describe: 'Port', default: DEFAULT_HTTP_CONFIG.port })
+	.option('user', { type: 'string', describe: 'Username', default: DEFAULT_HTTP_CONFIG.username })
+	.option('password', { type: 'string', describe: 'Password', default: DEFAULT_HTTP_CONFIG.password })
+	.option('json', { type: 'boolean', describe: 'Output result as JSON', default: false })
+	.option('verbose', { type: 'boolean', describe: 'Show debug logs' });
+
+// --- STATUS & INFO ---
+
+cli.command('status', 'Get system status', {}, async (/** @type {ArgumentsCamelCase<CommonArgs>} */ argv) => {
+	const client = getClient(argv);
+	const status = await client.getStatus();
+	printOutput(argv, status, (s) => ({
+		'Uptime': formatUptime(s.uptime),
+		'Load Avg': s.lavg,
+		'RAM Free': formatBytes(s.ram.free * 1024),
+		'RAM Used': formatBytes(s.ram.used * 1024),
+		'RAM Total': formatBytes(s.ram.total * 1024)
+	}));
+});
+
+cli.command('devices', 'List connected devices', {}, async (/** @type {ArgumentsCamelCase<CommonArgs>} */ argv) => {
+	const client = getClient(argv);
+	const devices = await client.getDevices();
+	printOutput(argv, devices, (/** @type {Device} */ d) => ({
+		MAC: d.mac,
+		IP: d.ip,
+		HostName: d.hostname,
+		Type: d.type,
+		RSSI: d.rssi ? d.rssi + '%' : null
+	}));
+});
+
+cli.command('log', 'Get system log', {}, async (/** @type {ArgumentsCamelCase<CommonArgs>} */ argv) => {
+	const client = getClient(argv);
+	const log = await client.getLog();
+	console.log(log);
+});
+
+cli.command('traffic', 'Get traffic history', {}, async (/** @type {ArgumentsCamelCase<CommonArgs>} */ argv) => {
+	const client = getClient(argv);
+	const history = await client.getHistory();
+	if (argv.json) {
+		printOutput(argv, history);
+		return;
+	}
+	const trafficTable = (/** @type {any} */ item) => ({
+		Date: item.dateStr,
+		Download: formatBytes(item.download * 1024),
+		Upload: formatBytes(item.upload * 1024),
+		Total: formatBytes((item.download + item.upload) * 1024)
+	});
+	logInfo('Daily History (Last 10):');
+	console.table(history.daily.slice().reverse().slice(0, 10).map(trafficTable));
+	logInfo('Monthly History (Last 10):');
+	console.table(history.monthly.slice().reverse().slice(0, 10).map(trafficTable));
+});
+
+// --- WIFI DOCTOR ---
+
+cli.command('scan [band]', 'Scan Wi-Fi networks', (yargs) => {
+	return yargs.positional('band', { type: 'string', choices: ['2.4', '5'], default: '2.4' });
+}, async (/** @type {ArgumentsCamelCase<CommonArgs & {band: '2.4'|'5'}>} */ argv) => {
+	const client = getClient(argv);
+	logInfo(`Scanning ${argv.band}GHz networks...`);
+	const networks = await client.startScan(argv.band);
+	printOutput(argv, networks, (/** @type {WifiNetwork} */ n) => ({
+		SSID: n.ssid,
+		Channel: n.channel,
+		Quality: n.quality + '%',
+		BSSID: n.bssid
+	}));
+});
+
+cli.command('doctor [band]', 'Analyze Wi-Fi environment and recommend channel', (yargs) => {
+	return yargs.positional('band', { type: 'string', choices: ['2.4', '5'], default: '2.4' });
+}, async (/** @type {ArgumentsCamelCase<CommonArgs & {band: '2.4'|'5'}>} */ argv) => {
+	const client = getClient(argv);
+	logInfo(`Scanning and analyzing ${argv.band}GHz spectrum...`);
+	const result = await client.getBestChannel(argv.band);
+	printOutput(argv, result, (/** @type {ChannelAnalysis} */ r) => ({
+		'Current': r.currentChannel,
+		'Best': r.bestChannel,
+		'Optimal?': r.isCurrentOptimal ? 'Yes' : 'No',
+		'Reason': r.reason
+	}));
+});
+
+// --- PARAMS (NVRAM) ---
+
+cli.command('params [keys..]', 'Get parameters (NVRAM or Page inputs)', (yargs) => {
+	return yargs
+		.option('page', { type: 'string', describe: 'Target ASP page to parse inputs from' });
+}, async (/** @type {ArgumentsCamelCase<CommonArgs & {keys?: string[], page?: string}>} */ argv) => {
+	const client = getClient(argv);
+	const params = await client.getParams(argv.keys, argv.page);
+	printOutput(argv, params);
+});
+
+cli.command('set <pairs..>', 'Set parameters (key=value)', (yargs) => {
+	return yargs
+		.option('page', { type: 'string', describe: 'Current page (for auto-SID detection)' })
+		.option('sid', { type: 'array', describe: 'Service ID list', choices: SERVICE_ID })
+		.option('group', { type: 'string', describe: 'Group ID (required for Add/Del actions)', choices: GROUP_ID })
+		.option('script', { type: 'string', describe: 'Action script' })
+		.option('action', {
+			type: 'string',
+			describe: 'Action mode',
+			default: 'Apply',
+			coerce: (arg) => {
+				const clean = arg.trim();
+				const match = ACTION_MODE.map(m => m.trim()).find(m => m.toLowerCase() === clean.toLowerCase());
+				return match || arg;
+			},
+			choices: ACTION_MODE.map(m => m.trim())
+		})
+		.example('$0 set rt_ssid=MyWifi --page "Advanced_WAdvanced_Content.asp"', 'Apply settings via Web UI')
+		.example('$0 set "rt_ACLList=AA:BB:CC:DD:EE:FF" --action Add --group rt_ACLList', 'Add MAC to filter');
+}, async (/** @type {ArgumentsCamelCase<CommonArgs & {pairs: string[], sid?: string|ServiceId[], page?: string, action?: ActionMode, group?: GroupId, script?: string}>} */ argv) => {
+	const client = getClient(argv);
+	const /** @type {Record<string, string>} */ params = {};
+	argv.pairs.forEach(p => {
+		const [k, ...v] = p.split('=');
+		if (k)
+			params[k] = v.join('=');
+	});
+	const action_mode = ACTION_MODE.find(m => m.trim() === argv.action) || argv.action;
+	await client.setParams(params, {
+		action_mode,
+		action_script: argv.script,
+		sid_list: argv.sid,
+		group_id: argv.group,
+		current_page: argv.page
+	});
+	logInfo('Settings applied successfully.');
+});
+
+// --- FIRMWARE ---
+
+cli.command('firmware <action>', 'Manage firmware', (yargs) => {
+	return yargs
+		.positional('action', { choices: ['changelog', 'build', 'upgrade', 'search'] })
+		.option('repo', { type: 'string', describe: 'GitHub Owner/Repo', default: DEFAULT_FIRMWARE_REPO })
+		.option('branch', { type: 'string', describe: 'Branch name' })
+		.option('token', { type: 'string', describe: 'GitHub Token' })
+		.option('model', { type: 'string', describe: 'Model filter for search' });
+}, async (/** @type {ArgumentsCamelCase<CommonArgs & FirmwareArgs>} */ argv) => {
+	if (argv.action !== 'search' && !argv.repo)
+		throw new Error(`--repo is required for ${argv.action}`);
+
+	const client = getClient(argv);
+	switch (argv.action) {
+		case 'search': {
+			logInfo(`Searching firmware (Source: ${argv.repo}, Model: ${argv.model || 'Auto'})...`);
+			const results = await client.findFirmware(argv.model);
+			printOutput(argv, results, (r) => ({
+				'Date': new Date(r.created_at).toLocaleDateString(),
+				'Repo': r.repo,
+				'Branch': r.branch,
+				'Firmware': r.name,
+				'Size': formatBytes(r.size)
+			}));
+			break;
+		}
+		case 'build': {
+			logInfo(`Triggering build in ${argv.repo}...`);
+			await client.startBuild();
+			logInfo('Build started! Check GitHub Actions tab.');
+			break;
+		}
+		case 'changelog': {
+			logInfo('Fetching changelog...');
+			const log = await client.getChangelog();
+			logInfo(`\nChanges from ${log.from} to ${log.to}:`);
+			if (log.messages.length === 0)
+				logInfo('No changes (versions are identical).');
+			else
+				log.messages.forEach(msg => console.log(`- ${msg}`));
+			break;
+		}
+		case 'upgrade': {
+			logInfo('WARNING: This will download the latest artifact and flash your router.');
+			logInfo('Do not turn off power!');
+			await client.startUpgrade();
+			logInfo('Upgrade process started. Router is rebooting...');
+			break;
+		}
+	}
+});
+
+// --- SYSTEM ---
+
+cli.command('reboot', 'Reboot the router', {}, async (/** @type {ArgumentsCamelCase<CommonArgs>} */ argv) => {
+	const client = getClient(argv);
+	logInfo('Sending reboot command...');
+	await client.startReboot();
+	logInfo('Reboot command sent.');
+});
+
+cli.fail((msg, err, yargs) => {
+	if (err)
+		console.error(err.message);
+	else if (msg && !(args.length === 1 && args[0] === 'firmware'))
+		console.error(msg);
+	else
+		yargs.showHelp();
+	process.exit(1);
+});
+
+cli
+	.demandCommand(1, '')
+	.recommendCommands()
+	.help().alias('h', 'help')
+	.version().alias('v', 'version')
+	.parse();

package/package.json

@@ -1,28 +1,45 @@
 {
 	"name": "padavan",
-	"version": "1.0.1",
-	"description": "Router management with Padavan firmware",
-	"main": "main.mjs",
+	"version": "2.0.0",
+	"private": false,
+	"type": "module",
+	"description": "The core library for interacting with routers running Padavan firmware. Provides a programmatic API for local control via HTTP.",
+	"exports": {
+		".": "./src/index.js",
+		"./*": "./src/*"
+	},
+	"bin": {
+		"padavan": "./bin/cli.js"
+	},
+	"scripts": {
+		"test": "tsc -p ./jsconfig.json"
+	},
 	"files": [
-		"services/",
-		"main.mjs"
+		"./bin/",
+		"./src/*.js"
 	],
+	"dependencies": {
+		"jszip": "^3.10.1",
+		"yargs": "^18.0.0"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"license": "MIT",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/alex2844/node-padavan.git"
+		"url": "git+https://github.com/alex2844/node-padavan.git",
+		"directory": "packages/node"
 	},
 	"keywords": [
+		"router",
+		"padavan",
 		"nodejs",
 		"iot",
-		"smart home",
-		"router",
-		"padavan"
-	],
-	"author": "Alex Smith",
-	"license": "MIT",
-	"dependencies": {
-		"ini": "^4.1.3",
-		"jszip": "^3.10.1",
-		"ssh2": "^1.15.0"
-	}
-}
+		"smarthome",
+		"home-automation",
+		"javascript",
+		"library",
+		"api"
+	]
+}

package/src/constants.js

@@ -0,0 +1,98 @@
+/** Идентификатор библиотеки для debuglog. */
+export const LIB_ID = 'padavan';
+
+/**
+ * Уровни логирования.
+ * @enum {number}
+ */
+export const LOG_LEVELS = /** @type {const} */ ({
+	none: 0,
+	error: 1,
+	warn: 2,
+	info: 3,
+	debug: 4
+});
+
+/** Уровень логирования по умолчанию. */
+export const DEFAULT_LOG_LEVEL = 'none';
+
+/** Репозиторий с прошивками по умолчанию. */
+export const DEFAULT_FIRMWARE_REPO = 'alex2844/node-padavan';
+
+/** Конфигурация HTTP клиента по умолчанию. */
+export const DEFAULT_HTTP_CONFIG = {
+	host: '192.168.1.1',
+	port: 80,
+	username: 'admin',
+	password: 'admin'
+};
+
+/** Время жизни кэша NVRAM в миллисекундах. */
+export const NVRAM_CACHE_TTL = 3_000;
+
+/**
+ * Режимы действия для apply.cgi.
+ * Обратите внимание: большинство команд требуют пробелы по краям.
+ * @typedef {(typeof ACTION_MODE)[number]} ActionMode
+ */
+export const ACTION_MODE = /** @type {const} */ ([
+	' Apply ', ' Restart ', ' Reboot ', ' Shutdown ',
+	' Add ', ' Del ', ' ClearLog ', ' SystemCmd ',
+	' CommitFlash ', ' RestoreNVRAM ', ' RestoreStorage ', ' FreeMemory ',
+	' NTPSyncNow ', ' CreateCertHTTPS ', ' CheckCertHTTPS ',
+	' CreateCertOVPNS ', ' ExportConfOVPNC ', ' ExportWGConf ',
+	' wg_action ', 'Update'
+]);
+
+/**
+ * Идентификаторы сервисов (Service ID).
+ * Используются для уведомления демонов (rc) о необходимости перечитать конфиги.
+ * @typedef {(typeof SERVICE_ID)[number]} ServiceId
+ */
+export const SERVICE_ID = /** @type {const} */ ([
+	'General', 'LANHostConfig', 'IPConnection', 'PPPConnection', 'FirewallConfig', 'RouterConfig',
+	'WLANConfig11a', 'WLANConfig11b', 'WLANAuthentication11a', 'WLANAuthentication11b',
+	'Storage', 'IP6Connection', 'Layer3Forwarding'
+]);
+
+/**
+ * Идентификаторы групп для списков (NVRAM Lists).
+ * Ообязателен, если action_mode=' Add ' или ' Del '.
+ * @typedef {(typeof GROUP_ID)[number]} GroupId
+ */
+export const GROUP_ID = /** @type {const} */ ([
+	'ManualDHCPList', 'VSList', 'GWStatic', 'UrlList', 'MFList',
+	'ACLList', 'rt_ACLList', 'RBRList', 'rt_RBRList',
+	'LWFilterList', 'VPNSACLList'
+]);
+
+/** Системные команды роутера. */
+export const COMMANDS = {
+	NVRAM_SHOW: 'nvram showall'
+};
+
+/** Список используемых страниц веб-интерфейса. */
+export const PAGES = {
+	/** Основной список клиентов (ARP + Wireless) */
+	CLIENTS: 'device-map/clients.asp',
+	/** Логи драйвера 2.4GHz */
+	WIFI_2G: 'Main_WStatus2g_Content.asp',
+	/** Логи драйвера 5GHz */
+	WIFI_5G: 'Main_WStatus_Content.asp',
+	/** Инициация сканирования 2.4GHz */
+	SCAN_2G: 'wds_aplist_2g.asp',
+	/** Инициация сканирования 5GHz */
+	SCAN_5G: 'wds_aplist.asp',
+	/** Текущий статус системы (JSON-like) */
+	STATUS: 'system_status_data.asp',
+	/** История трафика */
+	TRAFFIC: 'Main_TrafficMonitor_daily.asp',
+	/** Результат выполнения системной команды */
+	CONSOLE_RESPONSE: 'console_response.asp',
+	/** Системный журнал */
+	SYSLOG: 'Main_LogStatus_Content.asp',
+	/** Страница обновления прошивки (POST) */
+	UPGRADE: 'upgrade.cgi',
+	/** Основная точка входа для применения настроек (POST) */
+	APPLY: 'apply.cgi'
+};