flaks-node-hon 1.0.0

package/src/caching/appliance-cache.js

@@ -0,0 +1,71 @@
+const fs = require("node:fs/promises");
+const path = require("node:path");
+const { findApplianceIdentifierMatches } = require("../appliance-identity");
+
+const CACHE_VERSION = 1;
+
+class ApplianceCache {
+  constructor(filePath) {
+    this.filePath = path.resolve(filePath || "./.hon-appliance-cache.json");
+  }
+
+  async read() {
+    try {
+      const text = await fs.readFile(this.filePath, "utf8");
+      const data = JSON.parse(text);
+      if (data.version !== CACHE_VERSION || !Array.isArray(data.appliances)) {
+        return emptyCache();
+      }
+      return data;
+    } catch (error) {
+      const fileError = /** @type {NodeJS.ErrnoException} */ (error);
+      if (fileError && fileError.code === "ENOENT") {
+        return emptyCache();
+      }
+      throw error;
+    }
+  }
+
+  async find(id) {
+    const matches = await this.findAll(id);
+    return matches[0] || null;
+  }
+
+  async findAll(id) {
+    const cache = await this.read();
+    return findApplianceIdentifierMatches(cache.appliances, id).map((match) => match.item);
+  }
+
+  async upsert(record) {
+    let cache;
+    try {
+      cache = await this.read();
+    } catch {
+      cache = emptyCache();
+    }
+    const next = cache.appliances.filter((item) => !recordMatches(item, record.uniqueId) && !recordMatches(item, record.macAddress));
+    next.push(record);
+    await this.write({ version: CACHE_VERSION, appliances: next });
+  }
+
+  async write(data) {
+    await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+    const tmp = `${this.filePath}.${process.pid}.tmp`;
+    await fs.writeFile(tmp, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+    await fs.rename(tmp, this.filePath);
+  }
+}
+
+function emptyCache() {
+  return { version: CACHE_VERSION, appliances: [] };
+}
+
+/**
+ * @param {{ macAddress?: string, uniqueId?: string, nickName?: string } | null | undefined} record
+ * @param {string} id
+ */
+function recordMatches(record, id) {
+  return findApplianceIdentifierMatches(record ? [record] : [], id).length > 0;
+}
+
+module.exports = { ApplianceCache, CACHE_VERSION, recordMatches };

package/src/caching/session-store.js

@@ -0,0 +1,47 @@
+const fs = require("node:fs/promises");
+const path = require("node:path");
+
+class SessionStore {
+  constructor(filePath) {
+    this.filePath = filePath ? path.resolve(filePath) : "";
+  }
+
+  async read() {
+    if (!this.filePath) {
+      return null;
+    }
+    try {
+      const text = await fs.readFile(this.filePath, "utf8");
+      return JSON.parse(text);
+    } catch (error) {
+      const fileError = /** @type {NodeJS.ErrnoException} */ (error);
+      if (fileError && fileError.code === "ENOENT") {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  async write(data) {
+    if (!this.filePath) {
+      return;
+    }
+    await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+    const tmp = `${this.filePath}.${process.pid}.tmp`;
+    await fs.writeFile(tmp, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+    await fs.rename(tmp, this.filePath);
+  }
+}
+
+function isExpired(expiresAt, warningMs = 0) {
+  if (!expiresAt) {
+    return true;
+  }
+  const timestamp = Date.parse(expiresAt);
+  if (!Number.isFinite(timestamp)) {
+    return true;
+  }
+  return Date.now() + warningMs >= timestamp;
+}
+
+module.exports = { SessionStore, isExpired };

package/src/client.js

@@ -0,0 +1,253 @@
+const path = require("node:path");
+const { HonDevice } = require("./device");
+const { SessionStore } = require("./caching/session-store");
+const { HonAuth } = require("./auth");
+const { HonAPI } = require("./api");
+const { HonAppliance, isAirConditioner } = require("./appliance");
+const { HonAirConditioner } = require("./ac");
+const { ApplianceNotFoundError } = require("./errors");
+const { DebugLogger } = require("./lib/logger");
+const { ApplianceCache } = require("./caching/appliance-cache");
+const { findApplianceIdentifierMatches } = require("./appliance-identity");
+
+class HonClient {
+  /**
+   * @param {Partial<import("../types/global").ProjectConfig> & { fetch?: typeof fetch, logger?: any }} [config]
+   */
+  constructor(config = {}) {
+    this.config = config;
+    this.fetch = config.fetch || globalThis.fetch;
+    this.logger =
+      config.logger || new DebugLogger({ enabled: Boolean(config.debug) });
+    this.device = new HonDevice(config.mobileId);
+    const sessionFile = config.sessionFile
+      ? path.resolve(config.sessionFile)
+      : "";
+
+    /** @type {SessionStore | null} */
+    this.sessionStore = sessionFile ? new SessionStore(sessionFile) : null;
+    this.applianceCache = new ApplianceCache(config.applianceCacheFile || "./cache/.hon-appliance-cache.json");
+    this.forceApplianceCacheRefresh = Boolean(config.forceApplianceCacheRefresh);
+    this.auth = new HonAuth({
+      email: config.email,
+      password: config.password,
+      device: this.device,
+      fetchImpl: this.fetch,
+      sessionStore: this.sessionStore,
+      debug: Boolean(config.debug),
+      logger: this.logger,
+    });
+    this.api = new HonAPI(this.auth, this.device, this.fetch, this.logger);
+    this.appliances = [];
+  }
+
+  async create() {
+    const operation = this.logger.start("Creating hOn client...");
+    try {
+      await this.login();
+      // await this.setup();
+      operation.success("hOn client ready");
+    } catch (error) {
+      operation.failure("hOn client setup failed");
+      throw error;
+    }
+    return this;
+  }
+
+  async login() {
+    const operation = this.logger.start("Trying to login...");
+    try {
+      await this.auth.initialize();
+      operation.success("Login success");
+    } catch (error) {
+      operation.failure("Login failed");
+      throw error;
+    }
+    return this;
+  }
+
+  async refresh() {
+    const operation = this.logger.start("Refreshing login...");
+    try {
+      const result = await this.auth.refresh();
+      operation.success(result ? "Refresh success" : "Refresh skipped");
+      return result;
+    } catch (error) {
+      operation.failure("Refresh failed");
+      throw error;
+    }
+  }
+
+  async setupOne(id) {
+    const appliances = await this.api.loadAppliances();
+    const airConditioners = appliances
+      .map((applianceData) => new HonAppliance(this.api, applianceData))
+      .filter(isAirConditioner);
+    const matches = findApplianceIdentifierMatches(airConditioners, id);
+    if (matches.length > 1) {
+      throw new ApplianceNotFoundError(`AC_ID matches multiple air conditioners: ${id}`, {
+        id,
+        matches: matches.map(({ item }) => item.toCacheRecord())
+      });
+    }
+    if (matches.length === 1) {
+      return this.#createApplianceSetup(matches[0].item);
+    }
+  }
+
+  async getAirConditionerByIdCached(id) {
+    if (!id) {
+      throw new ApplianceNotFoundError("AC_ID is required", { available: [] });
+    }
+    if (!this.forceApplianceCacheRefresh) {
+      const operation = this.logger.start(`Loading AC from cache: "${id}"...`);
+      try {
+        const records = await this.applianceCache.findAll(id);
+        if (records.length > 1) {
+          throw new ApplianceNotFoundError(`AC_ID matches multiple cached air conditioners: ${id}`, {
+            id,
+            matches: records.map((record) => ({
+              macAddress: record.macAddress,
+              uniqueId: record.uniqueId,
+              nickName: record.nickName
+            }))
+          });
+        }
+        if (records.length === 1) {
+          const record = records[0];
+          const appliance = HonAppliance.fromCacheRecord(this.api, record);
+          operation.success(`Loaded AC from cache: "${id}"`);
+          return new HonAirConditioner(appliance, this.logger);
+        }
+        operation.failure(`AC cache miss: "${id}"`);
+      } catch (error) {
+        operation.failure(`AC cache failed: "${id}"`);
+        if (error instanceof ApplianceNotFoundError) {
+          throw error;
+        }
+      }
+    }
+
+    const refresh = this.logger.start(`Refreshing AC cache: "${id}"...`);
+    const appliance = await this.setupOne(id);
+    if (!appliance) {
+      refresh.failure(`AC cache refresh failed: "${id}"`);
+      throw new ApplianceNotFoundError(`No air conditioner found for AC_ID: ${id}`, { id, available: [] });
+    }
+    await this.applianceCache.upsert(appliance.toCacheRecord());
+    refresh.success(`AC cache refreshed: "${id}"`);
+    return new HonAirConditioner(appliance, this.logger);
+  }
+
+  async setup() {
+    const operation = this.logger.start("Loading appliances...");
+
+    try {
+      const appliances = await this.api.loadAppliances();
+      for (const applianceData of appliances) {
+        const zones = Number(applianceData.zone || 0);
+        if (zones > 1) {
+          for (let zone = 1; zone <= zones; zone += 1) {
+            await this.createAppliance({ ...applianceData }, zone);
+          }
+        }
+        await this.createAppliance(applianceData);
+      }
+      operation.success(`Loaded ${this.appliances.length} appliance(s)`);
+    } catch (error) {
+      operation.failure("Loading appliances failed");
+      throw error;
+    }
+  }
+
+  /**
+   * @param {HonAppliance} appliance
+   */
+  async #createApplianceSetup(appliance) {
+    const label = appliance.nickName || appliance.macAddress;
+    if (!this.appliances) this.appliances = [];
+    const operation = this.logger.start(`Loading appliance: "${label}"...`);
+
+    try {
+      const promises = [
+        appliance.loadCommands(),
+        appliance.loadAttributes(),
+        appliance.loadStatistics(),
+      ];
+      await Promise.all(promises);
+
+      this.appliances.push(appliance);
+      operation.success(`Loaded appliance: "${label}"`);
+
+      return appliance;
+    } catch (error) {
+      operation.failure(`Loading appliance failed: "${label}"`);
+      throw error;
+    }
+  }
+
+  async createAppliance(applianceData, zone = 0) {
+    const appliance = new HonAppliance(this.api, applianceData, zone);
+    if (!appliance.macAddress) {
+      return;
+    }
+
+    return this.#createApplianceSetup(appliance);
+  }
+
+  async getAppliances() {
+    if (!this.appliances.length) {
+      await this.setup();
+    }
+    return this.appliances;
+  }
+
+  async getAirConditioners() {
+    const appliances = await this.getAppliances();
+    return appliances
+      .filter(isAirConditioner)
+      .map((appliance) => new HonAirConditioner(appliance, this.logger));
+  }
+
+  async getAirConditionerByIdFast(id) {
+    const appliance = await this.setupOne(id);
+    if (!appliance) return;
+
+    return new HonAirConditioner(appliance, this.logger);
+  }
+
+  async getAirConditionerById(id) {
+    const airConditioners = await this.getAirConditioners();
+    if (!id) {
+      throw new ApplianceNotFoundError("AC_ID is required", {
+        available: airConditioners.map((ac) => ac.identifiers),
+      });
+    }
+    const matches = findApplianceIdentifierMatches(airConditioners, id);
+    if (matches.length === 1) {
+      return matches[0].item;
+    }
+    if (matches.length > 1) {
+      throw new ApplianceNotFoundError(
+        `AC_ID matches multiple air conditioners`,
+        {
+          id,
+          matches: matches.map(({ item }) => item.identifiers),
+        },
+      );
+    }
+    throw new ApplianceNotFoundError(
+      `No air conditioner found for AC_ID: ${id}`,
+      {
+        id,
+        available: airConditioners.map((ac) => ac.identifiers),
+      },
+    );
+  }
+
+  async close() {
+    return undefined;
+  }
+}
+
+module.exports = { HonClient };

package/src/command.js

@@ -0,0 +1,314 @@
+const { HonApiError } = require("./errors");
+const { HonParameterFixed, HonParameterProgram, createParameter } = require("./parameters");
+
+class HonCommand {
+  /**
+   * @param {string} name
+   * @param {Record<string, any>} attributes
+   * @param {any} appliance
+   * @param {any} [categories]
+   * @param {string} [categoryName]
+   */
+  constructor(name, attributes, appliance, categories = null, categoryName = "") {
+    this.name = name;
+    this.appliance = appliance;
+    this.categories = categories || null;
+    this.categoryName = categoryName;
+    this.parameters = {};
+    this.data = {};
+    const copy = { ...attributes };
+    delete copy.description;
+    delete copy.protocolType;
+    this.loadParameters(copy);
+  }
+
+  loadParameters(attributes) {
+    for (const [group, items] of Object.entries(attributes)) {
+      if (!items || typeof items !== "object" || Array.isArray(items)) {
+        this.data[group] = items;
+        continue;
+      }
+      for (const [name, data] of Object.entries(items)) {
+        this.createParameter(data, name, group);
+      }
+    }
+  }
+
+  createParameter(data, name, group) {
+    if (name === "zoneMap" && this.appliance.zone) {
+      data.default = this.appliance.zone;
+    }
+    if (data.category === "rule") {
+      return;
+    }
+    const parameter = createParameter(name, data, group);
+    if (!parameter) {
+      this.data[name] = data;
+      return;
+    }
+    this.parameters[name] = parameter;
+    if (this.categoryName) {
+      const key = this.categoryName.includes("PROGRAM") ? "program" : "category";
+      this.parameters[key] = new HonParameterProgram(key, this, "custom");
+    }
+  }
+
+  get settings() {
+    return this.parameters;
+  }
+
+  get parameterGroups() {
+    const result = {};
+    for (const [name, parameter] of Object.entries(this.parameters)) {
+      if (!result[parameter.group]) {
+        result[parameter.group] = {};
+      }
+      result[parameter.group][name] = parameter.internValue;
+    }
+    return result;
+  }
+
+  get mandatoryParameterGroups() {
+    const result = {};
+    for (const [name, parameter] of Object.entries(this.parameters)) {
+      if (!parameter.mandatory) {
+        continue;
+      }
+      if (!result[parameter.group]) {
+        result[parameter.group] = {};
+      }
+      result[parameter.group][name] = parameter.internValue;
+    }
+    return result;
+  }
+
+  get parameterValue() {
+    return Object.fromEntries(Object.entries(this.parameters).map(([name, parameter]) => [name, parameter.value]));
+  }
+
+  get category() {
+    return this.categoryName;
+  }
+
+  set category(category) {
+    if (this.categories && this.categories[category]) {
+      this.appliance.commands[this.name] = this.categories[category];
+    }
+  }
+
+  get settingKeys() {
+    const result = new Set();
+    for (const command of Object.values(this.categories || { _: this })) {
+      for (const key of Object.keys(command.parameters)) {
+        result.add(key);
+      }
+    }
+    return [...result];
+  }
+
+  get availableSettings() {
+    const result = {};
+    for (const command of Object.values(this.categories || { _: this })) {
+      for (const [name, parameter] of Object.entries(command.parameters)) {
+        if (!result[name] || parameter.values.length > result[name].values.length) {
+          result[name] = parameter;
+        }
+      }
+    }
+    return result;
+  }
+
+  async send(onlyMandatory = false) {
+    const groupedParams = onlyMandatory ? this.mandatoryParameterGroups : this.parameterGroups;
+    return this.sendParameters(groupedParams.parameters || {});
+  }
+
+  async sendSpecific(paramNames) {
+    const params = {};
+    for (const [key, parameter] of Object.entries(this.parameters)) {
+      if (paramNames.includes(key) || parameter.mandatory) {
+        params[key] = parameter.value;
+      }
+    }
+    return this.sendParameters(params);
+  }
+
+  async sendParameters(params) {
+    const ancillaryParams = { ...(this.parameterGroups.ancillaryParameters || {}) };
+    delete ancillaryParams.programRules;
+    if (params.prStr) {
+      params.prStr = this.categoryName.toUpperCase();
+    }
+    this.appliance.syncCommandToParams(this.name);
+    const result = await this.appliance.api.sendCommand(this.appliance, this.name, params, ancillaryParams, this.categoryName);
+    if (!result) {
+      throw new HonApiError("Can't send command", { command: this.name, params });
+    }
+    return result;
+  }
+
+  reset() {
+    for (const parameter of Object.values(this.parameters)) {
+      parameter.reset();
+    }
+  }
+}
+
+function isCommand(data) {
+  return Boolean(data && typeof data === "object" && data.description !== undefined && data.protocolType !== undefined);
+}
+
+function cleanName(category) {
+  if (category.includes("PROGRAM")) {
+    return category.split(".").pop().toLowerCase();
+  }
+  return category;
+}
+
+class HonCommandLoader {
+  constructor(api, appliance) {
+    this.api = api;
+    this.appliance = appliance;
+    this.apiCommands = {};
+    this.favourites = [];
+    this.commandHistory = [];
+    this.commands = {};
+    this.applianceData = {};
+    this.additionalData = {};
+    this.rawCommands = {};
+  }
+
+  async loadCommands() {
+    const [commands, favourites, history] = await Promise.all([
+      this.api.loadCommands(this.appliance),
+      this.api.loadFavourites(this.appliance),
+      this.api.loadCommandHistory(this.appliance)
+    ]);
+    this.apiCommands = { ...(commands || {}) };
+    this.rawCommands = { ...(commands || {}) };
+    this.favourites = favourites || [];
+    this.commandHistory = history || [];
+    this.applianceData = this.apiCommands.applianceModel || {};
+    delete this.apiCommands.applianceModel;
+    this.getCommands();
+    this.addFavourites();
+    this.recoverLastCommandStates();
+  }
+
+  loadFromCache(cacheData) {
+    this.apiCommands = { ...(cacheData.commands || {}) };
+    this.rawCommands = { ...(cacheData.commands || {}) };
+    this.favourites = [];
+    this.commandHistory = [];
+    this.applianceData = cacheData.applianceModel || {};
+    this.additionalData = cacheData.additionalData || {};
+    this.getCommands();
+  }
+
+  getCommands() {
+    const commands = [];
+    for (const [name, data] of Object.entries(this.apiCommands)) {
+      const command = this.parseCommand(data, name);
+      if (command) {
+        commands.push(command);
+      }
+    }
+    this.commands = Object.fromEntries(commands.map((command) => [command.name, command]));
+  }
+
+  /**
+   * @param {any} data
+   * @param {string} commandName
+   * @param {any} [categories]
+   * @param {string} [categoryName]
+   */
+  parseCommand(data, commandName, categories = null, categoryName = "") {
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+      this.additionalData[commandName] = data;
+      return null;
+    }
+    if (isCommand(data)) {
+      return new HonCommand(commandName, data, this.appliance, categories, categoryName);
+    }
+    return this.parseCategories(data, commandName);
+  }
+
+  parseCategories(data, commandName) {
+    const categories = {};
+    for (const [category, value] of Object.entries(data)) {
+      const command = this.parseCommand(value, commandName, categories, category);
+      if (command) {
+        categories[cleanName(category)] = command;
+      }
+    }
+    if (!Object.keys(categories).length) {
+      return null;
+    }
+    return categories.setParameters || Object.values(categories)[0];
+  }
+
+  recoverLastCommandStates() {
+    for (const [name, baseCommand] of Object.entries(this.commands)) {
+      const last = this.commandHistory.find((item) => item?.command?.commandName === name);
+      if (!last) {
+        continue;
+      }
+      const parameters = { ...(last.command.parameters || {}) };
+      let command = baseCommand;
+      const program = parameters.program;
+      const category = parameters.category;
+      delete parameters.program;
+      delete parameters.category;
+      if (program && command.categories) {
+        command.category = cleanName(program);
+        command = this.commands[name];
+      } else if (category && command.categories) {
+        command.category = category;
+        command = this.commands[name];
+      }
+      for (const [key, value] of Object.entries(parameters)) {
+        if (command.settings[key]) {
+          try {
+            command.settings[key].value = value;
+          } catch {
+            // keep discovered default
+          }
+        }
+      }
+    }
+  }
+
+  addFavourites() {
+    for (const favourite of this.favourites) {
+      const commandName = favourite?.command?.commandName || "";
+      const programName = cleanName(favourite?.command?.programName || "");
+      const base = this.commands[commandName]?.categories?.[programName];
+      if (!base) {
+        continue;
+      }
+      const clone = Object.create(Object.getPrototypeOf(base));
+      Object.assign(clone, base, { parameters: { ...base.parameters } });
+      for (const value of Object.values(favourite.command || {})) {
+        if (!value || typeof value === "string") {
+          continue;
+        }
+        for (const [key, paramValue] of Object.entries(value)) {
+          if (clone.parameters[key]) {
+            try {
+              clone.parameters[key].value = paramValue;
+            } catch {
+              // keep default
+            }
+          }
+        }
+      }
+      clone.parameters.favourite = new HonParameterFixed("favourite", { fixedValue: "1" }, "custom");
+      if (clone.parameters.program && typeof clone.parameters.program.setValue === "function") {
+        clone.parameters.program.setValue(favourite.favouriteName);
+      }
+      this.commands[commandName].categories[favourite.favouriteName] = clone;
+    }
+  }
+}
+
+module.exports = { HonCommand, HonCommandLoader, isCommand, cleanName };