padavan 2.1.0 → 2.2.0

package/README.md

@@ -70,6 +70,10 @@ The constructor accepts a config object with the following properties:
 - **`exec(command)`**
   Executes a system command via the web console emulator (`SystemCmd`).
   *Returns:* Command output (stdout + stderr).
+- **`sendAction(action, payload?)`**
+  Sends a low-level action to `apply.cgi`.
+  *Arguments:* `action` (string, e.g., `' Reboot '`), `payload` (data object).
+  *Returns:* Server response (command output or status).
 - **`startReboot()`**
   Reboots the router via HTTP command.
 

package/bin/cli.js

@@ -4,8 +4,8 @@ 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 { DEFAULT_HTTP_CONFIG, DEFAULT_FIRMWARE_REPO, SYSTEM_ACTION, CONFIG_ACTION, SERVICE_ID, GROUP_ID, WIFI_BANDS } from '../src/constants.js';
+/** @import { SystemAction, ConfigAction, ServiceId, GroupId, WifiBand } from '../src/constants.js' */
 /** @import { ArgumentsCamelCase } from 'yargs' */
 /** @import { Device, WifiNetwork, ChannelAnalysis } from '../src/index.js' */
 
@@ -28,6 +28,8 @@ import { DEFAULT_HTTP_CONFIG, DEFAULT_FIRMWARE_REPO, ACTION_MODE, SERVICE_ID, GR
  * @property {string} [model]
  */
 
+const SYSTEM_ACTION_VALUES = Object.values(SYSTEM_ACTION);
+const CONFIG_ACTION_VALUES = Object.values(CONFIG_ACTION);
 const logInfo = (/** @type {string} */ msg) => console.error(msg);
 
 /**
@@ -117,8 +119,8 @@ cli.command('traffic', 'Get traffic history', {}, async (/** @type {ArgumentsCam
 // --- 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) => {
+	return yargs.positional('band', { type: 'string', choices: WIFI_BANDS, default: WIFI_BANDS[0] });
+}, async (/** @type {ArgumentsCamelCase<CommonArgs & {band: WifiBand}>} */ argv) => {
 	const client = getClient(argv);
 	logInfo(`Scanning ${argv.band}GHz networks...`);
 	const networks = await client.startScan(argv.band);
@@ -131,8 +133,8 @@ cli.command('scan [band]', 'Scan Wi-Fi networks', (yargs) => {
 });
 
 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) => {
+	return yargs.positional('band', { type: 'string', choices: WIFI_BANDS, default: WIFI_BANDS[0] });
+}, async (/** @type {ArgumentsCamelCase<CommonArgs & {band: WifiBand}>} */ argv) => {
 	const client = getClient(argv);
 	logInfo(`Scanning and analyzing ${argv.band}GHz spectrum...`);
 	const result = await client.getBestChannel(argv.band);
@@ -164,17 +166,17 @@ cli.command('set <pairs..>', 'Set parameters (key=value)', (yargs) => {
 		.option('action', {
 			type: 'string',
 			describe: 'Action mode',
-			default: 'Apply',
+			default: CONFIG_ACTION.APPLY.trim(),
+			choices: CONFIG_ACTION_VALUES.map(m => m.trim()),
 			coerce: (arg) => {
-				const clean = arg.trim();
-				const match = ACTION_MODE.map(m => m.trim()).find(m => m.toLowerCase() === clean.toLowerCase());
+				const clean = arg.trim().toLowerCase();
+				const match = CONFIG_ACTION_VALUES.map(m => m.trim()).find(m => m.toLowerCase() === clean);
 				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) => {
+}, async (/** @type {ArgumentsCamelCase<CommonArgs & {pairs: string[], sid?: string|ServiceId[], page?: string, action?: ConfigAction, group?: GroupId, script?: string}>} */ argv) => {
 	const client = getClient(argv);
 	const /** @type {Record<string, string>} */ params = {};
 	argv.pairs.forEach(p => {
@@ -182,7 +184,7 @@ cli.command('set <pairs..>', 'Set parameters (key=value)', (yargs) => {
 		if (k)
 			params[k] = v.join('=');
 	});
-	const action_mode = ACTION_MODE.find(m => m.trim() === argv.action) || argv.action;
+	const action_mode = CONFIG_ACTION_VALUES.find(m => m.trim() === argv.action) || argv.action;
 	await client.setParams(params, {
 		action_mode,
 		action_script: argv.script,
@@ -193,6 +195,40 @@ cli.command('set <pairs..>', 'Set parameters (key=value)', (yargs) => {
 	logInfo('Settings applied successfully.');
 });
 
+cli.command('call <action> [payload...]', 'Call a system action', (yargs) => {
+	return yargs
+		.positional('action', {
+			describe: 'System action to execute',
+			choices: SYSTEM_ACTION_VALUES.map(v => v.trim()),
+			coerce: (arg) => {
+				const clean = arg.trim().toLowerCase();
+				const match = SYSTEM_ACTION_VALUES.map(m => m.trim()).find(v => v.toLowerCase() === clean);
+				return match;
+			}
+		})
+		.example('$0 call SystemCmd ls -la /tmp', 'Execute a shell command')
+		.example('$0 call wg_action action=genkey', 'Pass payload for wg_action');
+}, async (/** @type {ArgumentsCamelCase<CommonArgs & {action: SystemAction, payload?: string[]}>} */ argv) => {
+	const client = getClient(argv);
+	const action = SYSTEM_ACTION_VALUES.find(m => m.trim() === argv.action) || argv.action;
+	const payload = {};
+	if (argv.payload && argv.payload.length > 0) {
+		if (action === SYSTEM_ACTION.SYSTEM_CMD)
+			payload.SystemCmd = argv.payload.join(' ');
+		else
+			argv.payload.forEach(p => {
+				const [key, ...valParts] = p.split('=');
+				if (key)
+					payload[key] = valParts.join('=');
+			});
+	}
+	logInfo(`Executing action: ${action.trim()}`);
+	if (Object.keys(payload).length > 0)
+		logInfo(`With payload: ${JSON.stringify(payload)}`);
+	const result = await client.sendAction(action, payload);
+	printOutput(argv, result);
+});
+
 // --- FIRMWARE ---
 
 cli.command('firmware <action>', 'Manage firmware', (yargs) => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "padavan",
-	"version": "2.1.0",
+	"version": "2.2.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.",

package/src/constants.js

@@ -32,17 +32,57 @@ export const NVRAM_CACHE_TTL = 3_000;
 
 /**
  * Режимы действия для apply.cgi.
- * Обратите внимание: большинство команд требуют пробелы по краям.
- * @typedef {(typeof ACTION_MODE)[number]} ActionMode
+ * @typedef {(typeof SYSTEM_ACTION)[keyof typeof SYSTEM_ACTION]} SystemAction
  */
-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'
-]);
+export const SYSTEM_ACTION = /** @type {const} */ ({
+	/** Полная перезагрузка роутера */
+	REBOOT: ' Reboot ',
+	/** Выключение роутера */
+	SHUTDOWN: ' Shutdown ',
+	/** Очистить системный лог */
+	CLEAR_LOG: ' ClearLog ',
+	/** Выполнить системную команду */
+	SYSTEM_CMD: ' SystemCmd ',
+	/** Сохранить NVRAM во флеш-память */
+	COMMIT_FLASH: ' CommitFlash ',
+	/** Сброс настроек к заводским */
+	RESTORE_NVRAM: ' RestoreNVRAM ',
+	/** Восстановить /etc/storage из сжатого файла */
+	RESTORE_STORAGE: ' RestoreStorage ',
+	/** Сбросить кэши памяти */
+	FREE_MEMORY: ' FreeMemory ',
+	/** Принудительная синхронизация времени */
+	NTP_SYNC_NOW: ' NTPSyncNow ',
+	/** Генерировать сертификат для HTTPS */
+	CREATE_CERT_HTTPS: ' CreateCertHTTPS ',
+	/** Проверка наличия SSL сертификата */
+	CHECK_CERT_HTTPS: ' CheckCertHTTPS ',
+	/** Генерировать ключи/сертификаты для OpenVPN сервера */
+	CREATE_CERT_OVPNS: ' CreateCertOVPNS ',
+	/** Экспорт конфига OpenVPN клиента */
+	EXPORT_CONF_OVPNC: ' ExportConfOVPNC ',
+	/** Экспорт конфига WireGuard */
+	EXPORT_WG_CONF: ' ExportWGConf ',
+	/** Действия WireGuard (требует доп. параметр action: genkey, pubkey, genpsk). */
+	WG_ACTION: ' wg_action '
+});
+
+/**
+ * Режимы действия для start_apply.htm.
+ * @typedef {(typeof CONFIG_ACTION)[keyof typeof CONFIG_ACTION]} ConfigAction
+ */
+export const CONFIG_ACTION = /** @type {const} */ ({
+	/** Применить настройки (без перезагрузки всего роутера, если возможно) */
+	APPLY: ' Apply ',
+	/** Применить настройки с явным перезапуском связанных сервисов */
+	RESTART: ' Restart ',
+	/** Добавить запись в список (используется с group_id) */
+	ADD: ' Add ',
+	/** Удалить запись из списка (используется с group_id) */
+	DEL: ' Del ',
+	/** Используется в связке с action_script (например, для обновления DDNS или статуса принтера) */
+	UPDATE: 'Update'
+});
 
 /**
  * Идентификаторы сервисов (Service ID).
@@ -66,6 +106,12 @@ export const GROUP_ID = /** @type {const} */ ([
 	'LWFilterList', 'VPNSACLList'
 ]);
 
+/**
+ * Диапазоны Wi-Fi.
+ * @typedef {(typeof WIFI_BANDS)[number]} WifiBand
+ */
+export const WIFI_BANDS = /** @type {const} */ (['2.4', '5']);
+
 /** Системные команды роутера. */
 export const COMMANDS = {
 	NVRAM_SHOW: 'nvram showall'
@@ -93,6 +139,8 @@ export const PAGES = {
 	SYSLOG: 'Main_LogStatus_Content.asp',
 	/** Страница обновления прошивки (POST) */
 	UPGRADE: 'upgrade.cgi',
-	/** Основная точка входа для применения настроек (POST) */
-	APPLY: 'apply.cgi'
+	/** Обработчик мгновенных действий (Reboot, Shell, AJAX) без редиректа */
+	APPLY: 'apply.cgi',
+	/** Обработчик применения настроек с сохранением NVRAM и перезапуском сервисов */
+	START_APPLY: 'start_apply.htm'
 };

package/src/index.js

@@ -7,8 +7,8 @@ import {
 	parsePageInputs, parseNvramOutput, parseLooseJson, normalizeTrafficHistory,
 	extractJsVariable, extractTextareaValue, extractMacsFromTextarea, extractCurrentChannel
 } from './utils/parsers.js';
-import { LOG_LEVELS, DEFAULT_LOG_LEVEL, LIB_ID, NVRAM_CACHE_TTL, PAGES, COMMANDS } from './constants.js';
-/** @import { ActionMode, ServiceId, GroupId } from './constants.js' */
+import { LOG_LEVELS, DEFAULT_LOG_LEVEL, LIB_ID, NVRAM_CACHE_TTL, SYSTEM_ACTION, PAGES, COMMANDS } from './constants.js';
+/** @import { SystemAction, ConfigAction, ServiceId, GroupId, WifiBand } from './constants.js' */
 /** @import { Config as HttpConfig } from './transport/http.js' */
 /** @import { Config as GithubConfig } from './transport/github.js' */
 /** @typedef {HttpConfig & GithubConfig} Credentials */
@@ -52,7 +52,7 @@ import { LOG_LEVELS, DEFAULT_LOG_LEVEL, LIB_ID, NVRAM_CACHE_TTL, PAGES, COMMANDS
  * @property {string} [next_page] Страница перенаправления.
  * @property {string|ServiceId[]} [sid_list] Строка или массив сервисов для перезапуска.
  * @property {GroupId} [group_id] ID группы.
- * @property {ActionMode} [action_mode=' Apply '] Режим действия.
+ * @property {ConfigAction} [action_mode=' Apply '] Режим действия.
  * @property {string} [action_script] Имя скрипта.
  */
 
@@ -150,24 +150,7 @@ export default class Padavan {
 	 * @returns {Promise<string>} Вывод команды (stdout + stderr).
 	 */
 	async exec(command) {
-		const result = this.#commandQueue.then(async () => {
-			this.log('debug', `Executing command: ${command}`);
-			if (!this.#http)
-				throw new Error('HTTP client not initialized');
-			try {
-				await this.#http.post(PAGES.APPLY, {
-					action_mode: ' SystemCmd ',
-					SystemCmd: command
-				});
-				const response = await this.#http.get(PAGES.CONSOLE_RESPONSE);
-				return response.trim();
-			} catch (e) {
-				this.log('error', `Command execution failed: ${command}`, e);
-				throw e;
-			}
-		});
-		this.#commandQueue = result.catch(() => {});
-		return result;
+		return this.sendAction(SYSTEM_ACTION.SYSTEM_CMD, { SystemCmd: command });
 	};
 
 	/**
@@ -224,19 +207,25 @@ export default class Padavan {
 		const kvPairs = Object.entries(params);
 		if (kvPairs.length === 0)
 			return;
+
 		const page = options.current_page || options.next_page;
+		let sid_list = options.sid_list;
+		let group_id = options.group_id || '';
 
-		let sidList = options.sid_list;
-		if (Array.isArray(sidList))
-			sidList = sidList.join(';') + ';';
-		else if (!sidList && page) {
+		if (Array.isArray(sid_list))
+			sid_list = sid_list.join(';') + ';';
+		else if (!sid_list && page) {
 			this.log('debug', `sid_list not provided, searching on ${page}...`);
 			try {
 				const html = await this.#http.get(page);
 				const pageInputs = parsePageInputs(html);
 				if (pageInputs['sid_list']) {
-					sidList = pageInputs['sid_list'];
-					this.log('debug', `Found sid_list: ${sidList}`);
+					sid_list = pageInputs['sid_list'];
+					this.log('debug', `Found sid_list: ${sid_list}`);
+					if (!group_id && pageInputs['group_id']) {
+						group_id = pageInputs['group_id'];
+						this.log('debug', `Auto-detected group_id: ${group_id}`);
+					}
 				} else
 					this.log('warn', `Could not find sid_list on ${page}`);
 			} catch (e) {
@@ -248,18 +237,18 @@ export default class Padavan {
 		this.#nvramPromise = null;
 		this.#nvramTimestamp = 0;
 
-		if (sidList) {
+		if (sid_list) {
 			const data = {
+				sid_list, group_id,
 				action_mode: options.action_mode || ' Apply ',
 				action_script: options.action_script || '',
-				sid_list: sidList,
-				group_id: options.group_id || '',
 				current_page: page || 'index.asp',
 				next_page: options.next_page || page || 'index.asp',
 				...params
 			};
+			this.log('debug', `POST ${PAGES.START_APPLY} payload:`, data);
 			try {
-				await this.#http.post(PAGES.APPLY, data);
+				await this.#http.post(PAGES.START_APPLY, data);
 				return true;
 			} catch (e) {
 				this.log('debug', 'setParams (UI) finished', e.message);
@@ -278,6 +267,34 @@ export default class Padavan {
 		return true;
 	};
 
+	/**
+	 * Отправляет системную команду на apply.cgi и возвращает результат.
+	 * @param {SystemAction} action Режим действия.
+	 * @param {Object} [payload] Дополнительные данные.
+	 * @returns {Promise<string>} Тело ответа от сервера.
+	 */
+	async sendAction(action, payload = {}) {
+		const result = this.#commandQueue.then(async () => {
+			this.log('info', `Sending system action: ${action}`);
+			try {
+				const result = await this.#http.post(PAGES.APPLY, {
+					action_mode: action,
+					...payload
+				});
+				if (action === SYSTEM_ACTION.SYSTEM_CMD) {
+					const response = await this.#http.get(PAGES.CONSOLE_RESPONSE);
+					return response.trim();
+				}
+				return result;
+			} catch (e) {
+				this.log('error', `Sending system action failed: ${action}`, e);
+				throw e;
+			}
+		});
+		this.#commandQueue = result.catch(() => {});
+		return result;
+	};
+
 	/**
 	 * Получает текущий статус системы (CPU, RAM, Uptime, LoadAvg).
 	 * @returns {Promise<Object>}
@@ -376,7 +393,7 @@ export default class Padavan {
 	/**
 	 * Сканирование эфира.
 	 * ВНИМАНИЕ: Если вы подключены по Wi-Fi к сканируемому диапазону, соединение разорвется.
-	 * @param {'2.4'|'5'} [band='2.4'] Частотный диапазон.
+	 * @param {WifiBand} [band='2.4'] Частотный диапазон.
 	 * @returns {Promise<WifiNetwork[]>} Список найденных сетей, отсортированный по уровню сигнала.
 	 */
 	async startScan(band = '2.4') {
@@ -409,7 +426,7 @@ export default class Padavan {
 
 	/**
 	 * Анализирует эфир и предлагает лучший канал с учетом совместимости и региона.
-	 * @param {'2.4'|'5'} [band='2.4'] Частотный диапазон.
+	 * @param {WifiBand} [band='2.4'] Частотный диапазон.
 	 * @param {WifiNetwork[]} [scanResults] Опционально: результаты сканирования.
 	 * @returns {Promise<ChannelAnalysis>} Результат анализа.
 	 */
@@ -561,7 +578,7 @@ export default class Padavan {
 		this.log('warn', 'Rebooting router via HTTP...');
 		try {
 			await this.#http.post(PAGES.APPLY, {
-				action_mode: ' Reboot '
+				action_mode: SYSTEM_ACTION.REBOOT
 			});
 		} catch (e) {
 			this.log('debug', 'Reboot request sent (network error expected)', e.message);