Refactor platform internals, improve robustness and device lifecycle

- Centralize Govee API URLs and headers in govee-api.ts, removing
  duplication across HTTP client and UI server
- Replace node-rsa/pem dependencies with openssl execSync for PFX
  extraction, reducing native module footprint
- Add createDebouncedGuard utility and replace manual debounce pattern
  across light, heater2, fan-light, and humidifier device handlers
- Add destroy() lifecycle method to GoveeDeviceBase; implement in
  cooler, heater, and valve devices to clean up timers on shutdown
- Move module-level global state (devicesInHB, awsDevices, etc.) to
  platform instance properties
- Replace global process error handlers for BLE with Noble error event
- Add retry limits to HTTP login/getDevices to prevent infinite retries
- Add external update debounce guards to outlet, purifier, tap, tv,
  and valve devices
- Add debug logging config option, lower HTTP refresh minimum to 30s
- Fix settings.ts plugin name, add LAN message validation, safe JSON
  parsing for deviceSettings
- Improve AWS sync with re-entrancy guard
- Harden UI server with Array.isArray checks for device responses

Author: mp-consulting

config.schema.json

@@ -39,11 +39,17 @@
         "default": false,
         "description": "If enabled, device state changes will not be logged."
       },
+      "debug": {
+        "title": "Debug Logging",
+        "type": "boolean",
+        "default": false,
+        "description": "If enabled, verbose debug logging will be output to the Homebridge log."
+      },
       "httpRefreshTime": {
         "title": "HTTP Refresh Time (seconds)",
         "type": "integer",
-        "minimum": 60,
-        "default": 60,
+        "minimum": 30,
+        "default": 30,
         "description": "How often to poll the Govee API for device updates."
       },
       "awsDisable": {
@@ -673,7 +679,8 @@
       "items": [
         "ignoreMatter",
         "disableDeviceLogging",
-        "colourSafeMode"
+        "colourSafeMode",
+        "debug"
       ]
     },
     {

homebridge-ui/server.js

@@ -51,11 +51,11 @@ class GoveeUiServer extends HomebridgePluginUiServer {
       const devices = await goveeGetDevices(loginResult.token, loginResult.clientId);
 
       return {
-        devices: devices.map(device => ({
+        devices: Array.isArray(devices) ? devices.map(device => ({
           deviceId: device.device,
           deviceName: device.deviceName,
           model: device.sku,
-        })),
+        })) : [],
       };
     } catch (err) {
       const message = err.response?.data?.message || err.message || 'Discovery failed';
@@ -100,8 +100,8 @@ class GoveeUiServer extends HomebridgePluginUiServer {
         return { devices: [] };
       }
 
-      const devices = JSON.parse(storedData);
-      return { devices: devices || [] };
+      const devices = typeof storedData === 'string' ? JSON.parse(storedData) : storedData;
+      return { devices: Array.isArray(devices) ? devices : [] };
     } catch (err) {
       console.error('Failed to get cached devices:', err);
       return { devices: [] };

nodemon.json

@@ -4,9 +4,9 @@
   ],
   "ext": "ts",
   "ignore": [],
-  "exec": "tsc && npx homebridge -U ./test/hbConfig -D -P .",
+  "exec": "tsc && npx homebridge-config-ui-x run -U ./test/hbConfig -D",
   "signal": "SIGTERM",
   "env": {
     "NODE_OPTIONS": "--trace-warnings"
   }
-}
+}

package.json

@@ -53,9 +53,7 @@
     "axios": "^1.13.2",
     "fakegato-history": "^0.6.7",
     "node-persist": "^4.0.4",
-    "node-rsa": "^1.1.1",
-    "p-queue": "^9.0.1",
-    "pem": "^1.14.8"
+    "p-queue": "^9.0.1"
   },
   "optionalDependencies": {
     "@stoprocent/bluetooth-hci-socket": "^2.2.3",
@@ -66,8 +64,6 @@
     "@types/aws-iot-device-sdk": "^2.2.8",
     "@types/node": "^24.10.1",
     "@types/node-persist": "^3.1.8",
-    "@types/node-rsa": "^1.1.4",
-    "@types/pem": "^1.14.4",
     "eslint": "^9.39.1",
     "homebridge": "^2.0.0-beta.55",
     "homebridge-config-ui-x": "^4.6.7",

src/connection/ble.ts

@@ -9,24 +9,6 @@ import { isValidPeripheral } from '../utils/validation.js';
 
 process.env.NOBLE_REPORT_ALL_HCI_EVENTS = '1';
 
-process.on('uncaughtException', (err) => {
-  if (err.message && err.message.includes('BLEManager')) {
-    console.error('[BLE] native ble crash detected:', err.message);
-    console.error('[BLE] this is a known issue with Noble on some macos systems, ble functionality may be limited.');
-  } else {
-    throw err;
-  }
-});
-
-process.on('unhandledRejection', (reason) => {
-  if (reason && reason.toString().includes('BLEManager')) {
-    console.error('[BLE] unhandled ble rejection:', reason);
-    console.error('[BLE] this is a known issue with Noble on some macos systems, ble functionality may be limited.');
-  } else {
-    throw reason;
-  }
-});
-
 const H5075_UUID = 'ec88';
 const H5101_UUID = '0001';
 const CONTROL_CHARACTERISTIC_UUID = '000102030405060708090a0b0c0d1910';
@@ -157,6 +139,18 @@ export default class BLEClient {
       this.btClient.on('scanStop', this.eventHandlers.scanStop);
       this.btClient.on('warning', this.eventHandlers.warning);
       this.btClient.on('discover', this.eventHandlers.discover);
+
+      // Handle Noble-specific errors without installing global process handlers
+      this.btClient.on('error', (err: Error) => {
+        if (this.isShuttingDown) {
+          return;
+        }
+        if (err.message && err.message.includes('BLEManager')) {
+          this.log.warn('[BLE] native ble error detected: %s. BLE functionality may be limited.', err.message);
+        } else {
+          this.log.warn('[BLE] adapter error: %s.', err.message);
+        }
+      });
     } catch (err) {
       this.log.warn('[BLE] failed to setup event listeners:', (err as Error).message);
     }

src/connection/http.ts

@@ -1,10 +1,9 @@
-import { Buffer } from 'node:buffer';
-
 import axios, { type AxiosError } from 'axios';
 
 import type { GoveeHTTPDeviceInfo, GoveeLogging, GoveePluginConfig, HTTPLoginResult } from '../types.js';
 import platformConsts from '../utils/constants.js';
 import { parseError, sleep } from '../utils/functions.js';
+import { GOVEE_API_URLS, goveeHeaders } from '../utils/govee-api.js';
 import platformLang from '../utils/lang-en.js';
 
 interface HTTPPlatformRef {
@@ -21,16 +20,16 @@ interface HTTPPlatformRef {
   };
 }
 
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 30000;
+
 export default class HTTPClient {
   private log: GoveeLogging;
   private password: string;
   private token?: string;
   private tokenTTR?: string;
   private username: string;
-  private appVersion: string;
-  private userAgent: string;
   private clientId: string;
-  private base64Tried = false;
 
   constructor(platform: HTTPPlatformRef) {
     this.log = platform.log;
@@ -39,14 +38,15 @@ export default class HTTPClient {
     this.tokenTTR = platform.accountTokenTTR;
     this.username = platform.config.username || '';
 
-    this.appVersion = '5.6.01';
-    this.userAgent = `GoveeHome/${this.appVersion} (com.ihoment.GoVeeSensor; build:2; iOS 16.5.0) Alamofire/5.6.4`;
-
     let clientSuffix = platform.api.hap.uuid.generate(this.username).replace(/-/g, '');
     clientSuffix = clientSuffix.substring(0, clientSuffix.length - 2);
     this.clientId = `hb${clientSuffix}`;
   }
 
+  private headers(token?: string): Record<string, string | number> {
+    return goveeHeaders(token || this.token!, this.clientId);
+  }
+
   /**
    * Set the token from cached credentials
    */
@@ -57,12 +57,12 @@ export default class HTTPClient {
     }
   }
 
-  async login(): Promise<HTTPLoginResult> {
+  async login(retryCount = 0): Promise<HTTPLoginResult> {
     try {
       this.log.debug('[HTTP] Attempting login for user: %s', this.username);
 
       const res = await axios({
-        url: 'https://app2.govee.com/account/rest/account/v1/login',
+        url: GOVEE_API_URLS.login,
         method: 'post',
         data: {
           email: this.username,
@@ -81,26 +81,13 @@ export default class HTTPClient {
 
       if (!res.data.client || !res.data.client.token) {
         this.log.debug('[HTTP] Login response missing client/token. Message: %s', res.data.message || 'none');
-        if (res.data.message && res.data.message.replace(/\s+/g, '') === 'Incorrectpassword') {
-          if (this.base64Tried) {
-            throw new Error(res.data.message || platformLang.noToken);
-          } else {
-            this.log.debug('[HTTP] Trying base64 decoded password');
-            this.base64Tried = true;
-            this.password = Buffer.from(this.password, 'base64')
-              .toString('utf8')
-              .replace(/\r\n|\n|\r/g, '')
-              .trim();
-            return await this.login();
-          }
-        }
         throw new Error(res.data.message || platformLang.noToken);
       }
 
       this.log.debug('[HTTP] Primary login successful, fetching TTR token...');
 
       const ttrRes = await axios({
-        url: 'https://community-api.govee.com/os/v1/login',
+        url: GOVEE_API_URLS.loginTTR,
         method: 'post',
         data: {
           email: this.username,
@@ -117,17 +104,9 @@ export default class HTTPClient {
       this.log.debug('[HTTP] Fetching IoT credentials...');
 
       const iotRes = await axios({
-        url: 'https://app2.govee.com/app/v1/account/iot/key',
+        url: GOVEE_API_URLS.iotKey,
         method: 'get',
-        headers: {
-          'Authorization': `Bearer ${this.token}`,
-          'appVersion': this.appVersion,
-          'clientId': this.clientId,
-          'clientType': 1,
-          'iotVersion': 0,
-          'timestamp': Date.now(),
-          'User-Agent': this.userAgent,
-        },
+        headers: this.headers(),
       });
 
       this.log.debug('[HTTP] IoT credentials received. Endpoint: %s', iotRes.data.data.endpoint);
@@ -145,9 +124,13 @@ export default class HTTPClient {
     } catch (err) {
       const axiosErr = err as AxiosError;
       if (axiosErr.code && platformConsts.httpRetryCodes.includes(axiosErr.code)) {
-        this.log.warn('[HTTP] %s [login() - %s].', platformLang.httpRetry, axiosErr.code);
-        await sleep(30000);
-        return this.login();
+        if (retryCount >= MAX_RETRIES) {
+          this.log.warn('[HTTP] login() failed after %d retries [%s].', MAX_RETRIES, axiosErr.code);
+          throw err;
+        }
+        this.log.warn('[HTTP] %s [login() - %s] (attempt %d/%d).', platformLang.httpRetry, axiosErr.code, retryCount + 1, MAX_RETRIES);
+        await sleep(RETRY_DELAY_MS);
+        return this.login(retryCount + 1);
       }
       throw err;
     }
@@ -156,24 +139,16 @@ export default class HTTPClient {
   async logout(): Promise<void> {
     try {
       await axios({
-        url: 'https://app2.govee.com/account/rest/account/v1/logout',
+        url: GOVEE_API_URLS.logout,
         method: 'post',
-        headers: {
-          'Authorization': `Bearer ${this.token}`,
-          'appVersion': this.appVersion,
-          'clientId': this.clientId,
-          'clientType': 1,
-          'iotVersion': 0,
-          'timestamp': Date.now(),
-          'User-Agent': this.userAgent,
-        },
+        headers: this.headers(),
       });
     } catch (err) {
       this.log.warn('[HTTP] %s %s.', platformLang.logoutFail, parseError(err as Error));
     }
   }
 
-  async getDevices(isSync = true): Promise<GoveeHTTPDeviceInfo[]> {
+  async getDevices(isSync = true, retryCount = 0): Promise<GoveeHTTPDeviceInfo[]> {
     try {
       if (!this.token) {
         this.log.debug('[HTTP] getDevices called but no token exists');
@@ -183,17 +158,9 @@ export default class HTTPClient {
       this.log.debug('[HTTP] Fetching device list...');
 
       const res = await axios({
-        url: 'https://app2.govee.com/device/rest/devices/v1/list',
+        url: GOVEE_API_URLS.devices,
         method: 'post',
-        headers: {
-          'Authorization': `Bearer ${this.token}`,
-          'appVersion': this.appVersion,
-          'clientId': this.clientId,
-          'clientType': 1,
-          'iotVersion': 0,
-          'timestamp': Date.now(),
-          'User-Agent': this.userAgent,
-        },
+        headers: this.headers(),
         timeout: 30000,
       });
 
@@ -217,54 +184,27 @@ export default class HTTPClient {
     } catch (err) {
       const axiosErr = err as AxiosError;
       if (!isSync && axiosErr.code && platformConsts.httpRetryCodes.includes(axiosErr.code)) {
-        this.log.warn('[HTTP] %s [getDevices() - %s].', platformLang.httpRetry, axiosErr.code);
-        await sleep(30000);
-        return this.getDevices();
+        if (retryCount >= MAX_RETRIES) {
+          this.log.warn('[HTTP] getDevices() failed after %d retries [%s].', MAX_RETRIES, axiosErr.code);
+          throw err;
+        }
+        this.log.warn('[HTTP] %s [getDevices() - %s] (attempt %d/%d).', platformLang.httpRetry, axiosErr.code, retryCount + 1, MAX_RETRIES);
+        await sleep(RETRY_DELAY_MS);
+        return this.getDevices(isSync, retryCount + 1);
       }
       throw err;
     }
   }
 
-  async getTapToRuns(): Promise<unknown[]> {
-    const res = await axios({
-      url: 'https://app2.govee.com/bff-app/v1/exec-plat/home',
-      method: 'get',
-      headers: {
-        'Authorization': `Bearer ${this.tokenTTR}`,
-        'appVersion': this.appVersion,
-        'clientId': this.clientId,
-        'clientType': 1,
-        'iotVersion': 0,
-        'timestamp': Date.now(),
-        'User-Agent': this.userAgent,
-      },
-      timeout: 10000,
-    });
-
-    if (!res?.data?.data?.components) {
-      throw new Error('not a valid response');
-    }
-
-    return res.data.data.components;
-  }
-
   async getLeakDeviceWarning(deviceId: string, deviceSku: string): Promise<unknown[]> {
     if (!this.token) {
       throw new Error(platformLang.noTokenExists);
     }
 
     const res = await axios({
-      url: 'https://app2.govee.com/leak/rest/device/v1/warnMessage',
+      url: GOVEE_API_URLS.leakWarning,
       method: 'post',
-      headers: {
-        'Authorization': `Bearer ${this.token}`,
-        'appVersion': this.appVersion,
-        'clientId': this.clientId,
-        'clientType': 1,
-        'iotVersion': 0,
-        'timestamp': Date.now(),
-        'User-Agent': this.userAgent,
-      },
+      headers: this.headers(),
       data: {
         device: deviceId.replaceAll(':', ''),
         limit: 50,