flaks-node-hon 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flaks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# hOn Node.js AC Controls
+
+A CommonJS Node.js module for hOn authentication and air conditioner controls.
+
+## Advantages
+
+- Speed: cached AC preset runs take about 1 second.
+- CLI: easy to set up and use.
+- Module: easy to reuse in other projects.
+
+## About This Project
+
+This project is a **Node.js port** of [Andre0512/pyhOn](https://github.com/Andre0512/pyhOn), which was originally developed by Andre0512 under the MIT License.
+
+All credit for the original implementation goes to Andre0512. This version reimplements the library in Node.js and may differ in API and functionality to better suit the JavaScript ecosystem.
+
+## Install From NPM
+
+After this package is published, install it globally:
+
+```bash
+npm install -g node-hon
+```
+
+Then create a working config in the installed package folder or run from a checkout that has `config.js`, presets, and cache files available.
+
+## Global CLI Setup From This Repo
+
+1. Clone or download this repository.
+
+2. Install dependencies:
+
+```bash
+npm install
+```
+
+3. Create your local config:
+
+```bash
+cp config_example.js config.js
+```
+
+4. Edit `config.js` and set your hOn account values.
+
+5. Install this checkout as a global npm command:
+
+```bash
+npm install -g .
+```
+
+6. Confirm the CLI is available:
+
+```bash
+node-hon list
+```
+
+## CLI Usage
+
+List available air conditioners:
+
+```bash
+node-hon list
+```
+
+Apply a preset by MAC address:
+
+```bash
+node-hon apply xx-xx-xx-xx-xx-xx preset_fan
+```
+
+Apply a preset by AC name:
+
+```bash
+node-hon apply Bedroom preset_fan
+```
+
+Turn an AC off:
+
+```bash
+node-hon apply bedroom off
+```
+
+Generate a preset interactively from live hOn capabilities:
+
+```bash
+node-hon generate-preset
+```
+
+Purge cached session and appliance command data:
+
+```bash
+node-hon purge-cache
+```
+
+The AC identifier can be a MAC address, unique ID, or nickname. Nickname lookup is case-insensitive, so `Bedroom` and `bedroom` can both match the same AC.
+
+Generated and bundled presets live in `presets/`. Preset names are passed without `.json`, for example `preset_fan` loads `presets/preset_fan.json`.
+
+Runtime cache files live under `cache/` by default, including session and appliance command cache data. Run `node-hon purge-cache`, or set `forceApplianceCacheRefresh: true` in `config.js`, when the appliance command model changes or a preset cannot find a parameter that exists in the app.
+
+## Development CLI
+
+You can also run the CLI scripts directly from the repository:
+
+```bash
+node cli/show_my_ac_devices.js
+node cli/ac_generate_preset.js
+```
+
+`ac_generate_preset.js` loads the latest AC capabilities from the hOn API. You can set `AC_ID` or `PRESET_NAME` to preselect the air conditioner or output preset name.
+
+## Tests
+
+```bash
+npm test
+```
+
+## Publishing
+
+Before publishing, make sure you are logged in:
+
+```bash
+npm login
+npm whoami
+```
+
+Verify the package:
+
+```bash
+npm test
+npm run typecheck
+npm pack --dry-run
+```
+
+Publish:
+
+```bash
+npm publish --access public
+```
+
+### License
+
+This project is released under the MIT License.  
+The original Python library is also MIT-licensed. See the `LICENSE` file for details and attribution.

package/bin/node-hon.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("node:path");
+
+const packageRoot = path.resolve(__dirname, "..");
+
+function usage() {
+  return [
+    "Usage:",
+    "  node-hon apply <mac|name> <preset_name|off>",
+    "  node-hon config",
+    "  node-hon list",
+    "  node-hon generate-preset",
+    "  node-hon purge-cache"
+  ].join("\n");
+}
+
+async function run(argv = process.argv.slice(2), options = {}) {
+  const stderr = options.stderr || process.stderr;
+  const commands = options.commands || defaultCommands();
+  const baseDir = options.baseDir || packageRoot;
+  const [command, ...args] = argv;
+
+  if (command === "apply") {
+    const [acId, presetName, ...rest] = args;
+    if (!acId || !presetName || rest.length) {
+      stderr.write(`${usage()}\n`);
+      return 1;
+    }
+    await commands.apply({ acId, presetName, baseDir });
+    return 0;
+  }
+
+  if (command === "generate-preset") {
+    if (args.length) {
+      stderr.write(`${usage()}\n`);
+      return 1;
+    }
+    await commands.generatePreset({ baseDir });
+    return 0;
+  }
+
+  if (command === "config") {
+    if (args.length) {
+      stderr.write(`${usage()}\n`);
+      return 1;
+    }
+    await commands.config({ baseDir });
+    return 0;
+  }
+
+  if (command === "list") {
+    if (args.length) {
+      stderr.write(`${usage()}\n`);
+      return 1;
+    }
+    await commands.list({ baseDir });
+    return 0;
+  }
+
+  if (command === "purge-cache") {
+    if (args.length) {
+      stderr.write(`${usage()}\n`);
+      return 1;
+    }
+    await commands.purgeCache({ baseDir });
+    return 0;
+  }
+
+  stderr.write(`${usage()}\n`);
+  return 1;
+}
+
+function defaultCommands() {
+  return {
+    apply: require("../cli/ac_apply_preset").main,
+    config: require("../cli/config").main,
+    list: require("../cli/show_my_ac_devices").main,
+    generatePreset: require("../cli/ac_generate_preset").main,
+    purgeCache: require("../cli/purge_cache").main
+  };
+}
+
+if (require.main === module) {
+  run().then((code) => {
+    process.exitCode = code;
+  }).catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { run, usage };

package/cli/ac_apply_preset.js

@@ -0,0 +1,36 @@
+const path = require("node:path");
+const getAcClient = require("../src/lib-cli/_get-ac-client");
+const { formatAc } = require("../src/lib-cli/_format");
+const { handleCliError } = require("../src/lib-cli/_run");
+
+async function main(options = {}) {
+  const baseDir = options.baseDir || path.resolve(__dirname, "..");
+  const loadAcClient = options.getAcClient || getAcClient;
+  const { ac, client } = await loadAcClient({ ...options, baseDir });
+
+  try {
+    const presetName = options.presetName || process.env.PRESET_NAME || "preset_fan";
+    if (presetName === "off") {
+      await ac.powerOff();
+      console.log(`Powered off ${formatAc(ac)}`);
+      return;
+    }
+    const presetFile = path.resolve(
+      baseDir,
+      "presets",
+      `${presetName}.json`,
+    );
+
+    const preset = require(presetFile);
+    await ac.applyPreset(preset, presetName);
+    console.log(`Applied ${presetName} to ${formatAc(ac)}`);
+  } finally {
+    await client.close();
+  }
+}
+
+if (require.main === module) {
+  main().catch(handleCliError);
+}
+
+module.exports = { main };

package/cli/ac_generate_preset.js

@@ -0,0 +1,80 @@
+const fs = require("node:fs/promises");
+const path = require("node:path");
+const getClient = require("../src/lib-cli/_get-client");
+const { createAsk, promptChoice } = require("../src/lib-cli/_prompt");
+const { formatAc, printSkipped } = require("../src/lib-cli/_format");
+const { handleCliError } = require("../src/lib-cli/_run");
+const { selectAirConditioner } = require("../src/lib-cli/_select-ac");
+const {
+  buildPreset,
+  defaultValueForField,
+  getFieldDescriptors,
+  getModeOptions,
+  selectPresetCommand
+} = require("../src/preset-generator");
+
+async function main(options = {}) {
+  const baseDir = options.baseDir || path.resolve(__dirname, "..");
+  const client = await getClient({ ...options, baseDir });
+  const ask = options.ask || createAsk();
+  try {
+    const airConditioners = await client.getAirConditioners();
+    if (!airConditioners.length) {
+      console.log("No air conditioners found.");
+      return;
+    }
+    const selectedAc = await selectAirConditioner(ask, airConditioners, options.acId);
+    const selectedCommand = selectPresetCommand(selectedAc.capabilities());
+    const generatorMode = await promptChoice(ask, "Generator mode", ["basic", "advanced"], "basic");
+    const modeOptions = getModeOptions(selectedCommand.command);
+    const presetMode = modeOptions.length ? await promptChoice(ask, "Preset mode", modeOptions, modeOptions[0]) : "";
+    const { fields, skipped } = getFieldDescriptors(selectedCommand.command, generatorMode);
+    const values = {};
+    for (const field of fields) {
+      values[field.name] = await promptField(ask, field);
+    }
+    const preset = buildPreset(selectedCommand.command, values, presetMode);
+    const presetName = await promptPresetName(ask, options.presetName);
+    const outputFile = path.resolve(baseDir, "presets", `${presetName}.json`);
+    await fs.mkdir(path.dirname(outputFile), { recursive: true });
+    await fs.writeFile(outputFile, `${JSON.stringify(preset, null, 2)}\n`);
+    console.log(`Generated ${path.relative(process.cwd(), outputFile)} for ${formatAc(selectedAc)}`);
+    console.log(`Selected command: ${selectedCommand.name}${presetMode ? ` (${presetMode})` : ""}`);
+    printSkipped(skipped);
+  } finally {
+    if (ask.close) {
+      ask.close();
+    }
+    await client.close();
+  }
+}
+
+async function promptPresetName(ask, presetName = "") {
+  const fallback = presetName || process.env.PRESET_NAME || "preset_custom";
+  for (;;) {
+    const answer = (await ask.question(`Preset filename [${fallback}]: `)).trim() || fallback;
+    const safe = answer.replace(/\.json$/i, "");
+    if (/^[a-zA-Z0-9_.-]+$/.test(safe)) {
+      return safe;
+    }
+    console.log("Use only letters, numbers, dot, underscore, and dash.");
+  }
+}
+
+async function promptField(ask, field) {
+  const fallback = defaultValueForField(field);
+  for (;;) {
+    const suffix = field.values.length ? ` (${field.values.join(", ")})` : "";
+    const answer = (await ask.question(`${field.name}${suffix} [${fallback}]: `)).trim() || fallback;
+    if (field.values.includes(String(answer))) {
+      return String(answer);
+    }
+    console.log(`Allowed values: ${field.values.join(", ")}`);
+  }
+}
+
+if (require.main === module) {
+  main().catch(handleCliError);
+}
+
+module.exports = { main };

package/cli/ac_turn_off.js

@@ -0,0 +1,20 @@
+const getAcClient = require("../src/lib-cli/_get-ac-client");
+const { formatAc } = require("../src/lib-cli/_format");
+const { handleCliError } = require("../src/lib-cli/_run");
+
+async function main(options = {}) {
+  const { ac, client } = await getAcClient(options);
+
+  try {
+    await ac.powerOff();
+    console.log(`Turned off ${formatAc(ac)}`);
+  } finally {
+    await client.close();
+  }
+}
+
+if (require.main === module) {
+  main().catch(handleCliError);
+}
+
+module.exports = { main };

package/cli/ac_turn_on.js

@@ -0,0 +1,21 @@
+const getAcClient = require("../src/lib-cli/_get-ac-client");
+const { formatAc } = require("../src/lib-cli/_format");
+const { handleCliError } = require("../src/lib-cli/_run");
+
+async function main(options = {}) {
+  const { ac, client } = await getAcClient(options);
+
+  try {
+    await ac.powerOn();
+
+    console.log(`Turned on ${formatAc(ac)}`);
+  } finally {
+    await client.close();
+  }
+}
+
+if (require.main === module) {
+  main().catch(handleCliError);
+}
+
+module.exports = { main };

package/cli/config.js

@@ -0,0 +1,84 @@
+const fs = require("node:fs/promises");
+const path = require("node:path");
+const { stdout: output } = require("node:process");
+const { askBoolean, askText, createAsk } = require("../src/lib-cli/_prompt");
+const { handleCliError } = require("../src/lib-cli/_run");
+
+async function main(options = {}) {
+  const baseDir = options.baseDir || path.resolve(__dirname, "..");
+  const configPath = options.configPath || path.resolve(baseDir, "config.js");
+  const examplePath = path.resolve(baseDir, "config_example.js");
+  const current = await loadConfigOrDefaults(configPath, examplePath);
+  const ask = options.ask || createAsk();
+
+  try {
+    const config = {
+      email: await askText(ask, "hOn email", current.email),
+      password: await askText(ask, "hOn password", "", current.password),
+      mobileId: await askText(ask, "Mobile ID", current.mobileId || "pyhOn-node"),
+      sessionFile: await askText(ask, "Session file", current.sessionFile || "./cache/.hon-session.json"),
+      applianceCacheFile: await askText(ask, "Appliance cache file", current.applianceCacheFile || "./cache/.hon-appliance-cache.json"),
+      forceApplianceCacheRefresh: await askBoolean(ask, "Force appliance cache refresh", Boolean(current.forceApplianceCacheRefresh)),
+      debug: await askBoolean(ask, "Debug logging", Boolean(current.debug))
+    };
+    await fs.writeFile(configPath, buildConfigText(config), "utf8");
+    output.write(`Saved ${configPath}\n`);
+  } finally {
+    if (ask.close) {
+      ask.close();
+    }
+  }
+}
+
+async function loadConfigOrDefaults(configPath, examplePath) {
+  if (await exists(configPath)) {
+    return requireFresh(configPath);
+  }
+  if (await exists(examplePath)) {
+    return requireFresh(examplePath);
+  }
+  return {
+    email: "user@example.com",
+    password: "password",
+    mobileId: "pyhOn-node",
+    sessionFile: "./cache/.hon-session.json",
+    applianceCacheFile: "./cache/.hon-appliance-cache.json",
+    forceApplianceCacheRefresh: false,
+    debug: false
+  };
+}
+
+function requireFresh(filePath) {
+  const resolved = require.resolve(path.resolve(filePath));
+  delete require.cache[resolved];
+  return require(resolved);
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function buildConfigText(config) {
+  return `/** @type {import("./types/global").ProjectConfig} */
+module.exports = {
+  email: ${JSON.stringify(config.email)},
+  password: ${JSON.stringify(config.password)},
+  mobileId: ${JSON.stringify(config.mobileId)},
+  sessionFile: ${JSON.stringify(config.sessionFile)},
+  applianceCacheFile: ${JSON.stringify(config.applianceCacheFile)},
+  forceApplianceCacheRefresh: ${Boolean(config.forceApplianceCacheRefresh)},
+  debug: ${Boolean(config.debug)}
+};
+`;
+}
+
+if (require.main === module) {
+  main().catch(handleCliError);
+}
+
+module.exports = { buildConfigText, main };

package/cli/purge_cache.js

@@ -0,0 +1,16 @@
+const fs = require("node:fs/promises");
+const path = require("node:path");
+const { handleCliError } = require("../src/lib-cli/_run");
+
+async function main(options = {}) {
+  const baseDir = options.baseDir || path.resolve(__dirname, "..");
+  const cacheDir = options.cacheDir || path.resolve(baseDir, "cache");
+  await fs.rm(cacheDir, { recursive: true, force: true });
+  console.log(`Purged cache: ${cacheDir}`);
+}
+
+if (require.main === module) {
+  main().catch(handleCliError);
+}
+
+module.exports = { main };

package/cli/show_my_ac_capabilities.js

@@ -0,0 +1,36 @@
+const fs = require("node:fs");
+const getClient = require("../src/lib-cli/_get-client");
+
+async function main(options = {}) {
+  const client = await getClient(options);
+
+  try {
+    const airConditioners = await client.getAirConditioners();
+    if (!airConditioners.length) {
+      console.log("No air conditioners found.");
+      return;
+    }
+
+    const filename = "./hon-devices-capabilities.json";
+    const mapping = {};
+    for (const ac of airConditioners) {
+      const naming = `${ac.nickName}_${ac.macAddress}`;
+      console.log(naming);
+
+      mapping[naming] = ac.capabilities();
+    }
+
+    fs.writeFileSync(filename, JSON.stringify(mapping, null, 2));
+  } finally {
+    await client.close();
+  }
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+  });
+}
+
+module.exports = { main };

package/cli/show_my_ac_devices.js

@@ -0,0 +1,19 @@
+const getClient = require("../src/lib-cli/_get-client");
+const { printAcList } = require("../src/lib-cli/_format");
+const { handleCliError } = require("../src/lib-cli/_run");
+
+async function main(options = {}) {
+  const client = await getClient(options);
+  try {
+    const airConditioners = await client.getAirConditioners();
+    printAcList(airConditioners);
+  } finally {
+    await client.close();
+  }
+}
+
+if (require.main === module) {
+  main().catch(handleCliError);
+}
+
+module.exports = { main };

package/config_example.js

@@ -0,0 +1,10 @@
+/** @type {import("./types/global").ProjectConfig} */
+module.exports = {
+  email: "user@example.com",
+  password: "password",
+  mobileId: "pyhOn-node",
+  sessionFile: "./cache/.hon-session.json",
+  applianceCacheFile: "./cache/.hon-appliance-cache.json",
+  forceApplianceCacheRefresh: false,
+  debug: false
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "flaks-node-hon",
+  "version": "1.0.0",
+  "description": "CommonJS Node.js client for hOn auth and air conditioner controls",
+  "main": "src/index.js",
+  "bin": {
+    "node-hon": "bin/node-hon.js"
+  },
+  "files": [
+    "bin/",
+    "cli/",
+    "src/",
+    "presets/",
+    "types/",
+    "config_example.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "commonjs",
+  "author": "Flaks",
+  "engines": {
+    "node": ">=23"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\"",
+    "typecheck": "tsc --noEmit --project jsconfig.json",
+    "prepublishOnly": "npm test && npm run typecheck"
+  },
+  "keywords": [
+    "hon",
+    "haier",
+    "candy",
+    "hoover",
+    "air-conditioner"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3"
+  }
+}

package/presets/preset_auto.json

@@ -0,0 +1,7 @@
+{
+  "mode": "iot_uv_and_auto",
+  "tempSel": "24",
+  "windSpeed": "3",
+  "windDirectionVertical": "2",
+  "windDirectionHorizontal": "6"
+}

package/presets/preset_cool.json

@@ -0,0 +1,8 @@
+{
+  "mode": "iot_uv_and_cool",
+  "tempSel": "24",
+  "windSpeed": "2",
+  "windDirectionVertical": "2",
+  "windDirectionHorizontal": "0",
+  "healthMode": "1"
+}

package/presets/preset_dry.json

@@ -0,0 +1,6 @@
+{
+  "mode": "iot_uv_and_dry",
+  "tempSel": "24",
+  "windSpeed": "2",
+  "windDirectionVertical": "5"
+}

package/presets/preset_fan.json

@@ -0,0 +1,8 @@
+{
+  "mode": "iot_uv_and_fan",
+  "tempSel": "24",
+  "windSpeed": "2",
+  "windDirectionVertical": "2",
+  "windDirectionHorizontal": "0",
+  "healthMode": "1"
+}