homebridge-nuheat2 1.2.4 → 1.2.6

package/CHANGELOG.md

@@ -1,97 +1,121 @@
-# Changelog
-
-All notable changes to this project should be documented in this file
-
+# Changelog
+
+All notable changes to this project should be documented in this file
+
 ## [Unreleased]
 
-## [1.2.4] - 2026-04-11
+## [1.2.6] - 2026-04-11
 
 ### Added
 
-- Swagger-aligned internal model helpers for account, thermostat, schedule, group, and energy responses
-- Optional per-thermostat schedule switches that can resume schedule mode from HomeKit
-- Account, schedule, and energy log API helpers for future UI and automation features
-
-### Changed
-
-- Delay platform startup until Homebridge finishes restoring cached accessories
-- Allow overriding Nuheat OAuth client settings through config or environment variables
-- Improve SignalR reconnection handling and token refresh behavior
-- Add regression tests and modernize package metadata for current Homebridge releases
-- Publish the maintained fork under the npm package identity `homebridge-nuheat2`
-- Simplify thermostat operating-mode handling to match the documented Nuheat Swagger model
-- Refresh thermostats when Nuheat sends schedule notifications
-
-### Fixed
-
-- Correct manual-mode thermostat mapping so HomeKit no longer snaps back to off
-- Fix thermostat online-state handling so status updates no longer rely on an assignment bug
-- Pin transitive websocket and cookie dependencies away from known vulnerable versions
-
-## [1.2.3] - 2024-11-04
-
-### Fixed
-
-- Bug when using away mode switches
-- Variable handling in some debug logging
-
-## [1.2.2] - 2023-06-13
-
-### Fixed
-
-- variable typo
-
-## [1.2.1] - 2023-06-01
-
-### Fixed
-
-- hold length bug
-
-## [1.2.0] - 2023-05-26
+- Add an `enableNotifications` config option so SignalR can be disabled during troubleshooting
 
 ### Changed
 
-- client secret for api auth
+- Skip group setup and refresh calls unless away-mode groups are actually configured
+- Improve Nuheat API error logging with request method, endpoint, status code, and response snippets
 
-### Fixed
-
-- async updates from the api to reduce cookie creation
-
-## [1.1.4] - 2023-05-12
-
-### Changed
-
-- error handling when unable to get access token, as to not crash homebridge
-
-## [1.1.3] - 2023-04-17
-
-### Fixed
-
-- typo in away mode
-
-## [1.1.2] - 2022-12-24
-
-### Fixed
-
-- some unhandled api auth error
+## [1.2.5] - 2026-04-11
 
 ### Changed
 
-- some debug logging code
-
-## [1.1.1] - 2022-11-17
+- Refactor platform accessory setup paths to reduce repeated lookups and simplify accessory updates
+- Consolidate shared Homebridge test stubs into reusable helpers
+- Restrict the test script to `*.test.js` files for cleaner local and CI output
 
 ### Fixed
 
-- changed the 'homebridge-nuheat' name to be lower case so HOOBS handles properly
-
-## [1.1.0] - 2022-11-15
+- Improve SignalR notification tracing readability
+- Correct setpoint debug log spacing in thermostat updates
 
-### Added
-
-- Added `homebridge-ui` support with auto detection
-- Added Away Mode switches for groups
-
-### Changed
-
-- Changed the underlying API to use nuheats new api system
+## [1.2.4] - 2026-04-11
+
+### Added
+
+- Swagger-aligned internal model helpers for account, thermostat, schedule, group, and energy responses
+- Optional per-thermostat schedule switches that can resume schedule mode from HomeKit
+- Account, schedule, and energy log API helpers for future UI and automation features
+
+### Changed
+
+- Delay platform startup until Homebridge finishes restoring cached accessories
+- Allow overriding Nuheat OAuth client settings through config or environment variables
+- Improve SignalR reconnection handling and token refresh behavior
+- Add regression tests and modernize package metadata for current Homebridge releases
+- Publish the maintained fork under the npm package identity `homebridge-nuheat2`
+- Simplify thermostat operating-mode handling to match the documented Nuheat Swagger model
+- Refresh thermostats when Nuheat sends schedule notifications
+
+### Fixed
+
+- Correct manual-mode thermostat mapping so HomeKit no longer snaps back to off
+- Fix thermostat online-state handling so status updates no longer rely on an assignment bug
+- Pin transitive websocket and cookie dependencies away from known vulnerable versions
+
+## [1.2.3] - 2024-11-04
+
+### Fixed
+
+- Bug when using away mode switches
+- Variable handling in some debug logging
+
+## [1.2.2] - 2023-06-13
+
+### Fixed
+
+- variable typo
+
+## [1.2.1] - 2023-06-01
+
+### Fixed
+
+- hold length bug
+
+## [1.2.0] - 2023-05-26
+
+### Changed
+
+- client secret for api auth
+
+### Fixed
+
+- async updates from the api to reduce cookie creation
+
+## [1.1.4] - 2023-05-12
+
+### Changed
+
+- error handling when unable to get access token, as to not crash homebridge
+
+## [1.1.3] - 2023-04-17
+
+### Fixed
+
+- typo in away mode
+
+## [1.1.2] - 2022-12-24
+
+### Fixed
+
+- some unhandled api auth error
+
+### Changed
+
+- some debug logging code
+
+## [1.1.1] - 2022-11-17
+
+### Fixed
+
+- changed the 'homebridge-nuheat' name to be lower case so HOOBS handles properly
+
+## [1.1.0] - 2022-11-15
+
+### Added
+
+- Added `homebridge-ui` support with auto detection
+- Added Away Mode switches for groups
+
+### Changed
+
+- Changed the underlying API to use nuheats new api system

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joshua Appleman
+
+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

@@ -1,127 +1,129 @@
-# homebridge-nuheat2
-
-[![npm version](https://img.shields.io/npm/v/homebridge-nuheat2.svg)](https://www.npmjs.com/package/homebridge-nuheat2)
-[![npm downloads](https://img.shields.io/npm/dm/homebridge-nuheat2.svg)](https://www.npmjs.com/package/homebridge-nuheat2)
-
+# homebridge-nuheat2
+
+[![npm version](https://img.shields.io/npm/v/homebridge-nuheat2.svg)](https://www.npmjs.com/package/homebridge-nuheat2)
+[![npm downloads](https://img.shields.io/npm/dm/homebridge-nuheat2.svg)](https://www.npmjs.com/package/homebridge-nuheat2)
+
 Homebridge platform plugin for Nuheat Signature floor-heating thermostats.
 
 This fork focuses on modernizing the plugin for current Homebridge releases, improving runtime stability, and preparing for Homebridge 2.0 while keeping the existing `NuHeat` platform configuration intact.
 
-## Highlights
-
-- Automatically discovers thermostats on the authenticated Nuheat account
-- Optionally creates HomeKit switches for Nuheat group away mode
-- Supports permanent, scheduled, and timed holds
-- Uses Nuheat's OAuth-based API instead of legacy site scraping
-- Includes compatibility improvements for Homebridge 1.8+ and 2.0 betas
-- Can optionally expose a schedule switch for each thermostat
-- Allows advanced OAuth overrides for long-term API stability
-
-## Compatibility
-
-- Homebridge: `^1.8.0 || ^2.0.0-beta.0`
-- Node.js: `^18.20.4 || ^20.18.0 || ^22 || ^24`
-
-For current Homebridge 2.0 betas, use Node 22 or 24.
-
-## Installation
-
-Install Homebridge first:
-
-```bash
-npm install -g homebridge
-```
-
-Then install the plugin:
-
-```bash
-npm install -g homebridge-nuheat2
-```
-
-The published package name for this maintained fork is `homebridge-nuheat2`. The Homebridge platform name in config remains `NuHeat`.
-
-## Configuration
-
-Most users should configure the plugin through Homebridge Config UI X, but the equivalent JSON looks like this:
-
-```json
-{
-  "platform": "NuHeat",
-  "name": "NuHeat",
-  "email": "email@address.com",
-  "password": "password123",
-  "devices": [{ "serialNumber": "1111111" }, { "serialNumber": "2222222" }],
-  "autoPopulateAwayModeSwitches": true,
-  "exposeScheduleSwitches": false,
-  "holdLength": 1440,
-  "refresh": 60
-}
-```
-
-### Options
-
-- `platform`: Must be `NuHeat`
-- `name`: Display name used in Homebridge logs
-- `email`: MyNuheat account email address
-- `Email`: Legacy alias still accepted for backward compatibility, but `email` is the preferred documented field
-- `password`: MyNuheat account password
-- `devices`: Optional list of thermostats to expose. If omitted or empty, every thermostat on the account will be discovered automatically
-- `serialNumber`: Thermostat serial number from MyNuheat
-- `autoPopulateAwayModeSwitches`: Automatically expose away-mode switches for all groups on the account
-- `exposeScheduleSwitches`: Optionally expose a switch per thermostat that reflects whether the thermostat is following its schedule and can be turned on to resume the schedule
-- `groups`: Optional allow-list of groups to expose as away-mode switches. This only affects group/away-mode accessories
-- `groupName`: Group name as shown in MyNuheat
-- `holdLength`: Hold duration in minutes
-- `refresh`: Poll interval in seconds, default `60`
-- `debug`: Enables verbose logging
-- `clientId`: Optional advanced override for the Nuheat OAuth client ID. This is recommended once you have official Nuheat API credentials
-- `clientSecret`: Optional advanced override for the Nuheat OAuth client secret
-- `redirectUri`: Optional advanced override for the Nuheat OAuth redirect URI, default `http://localhost`
-
-### Hold Length Behavior
-
-- `0`: hold until the next scheduled event
-- `1-1439`: timed hold for the configured number of minutes
-- `1440`: permanent hold
-
-### Device Discovery
-
-If `devices` is omitted or empty, the plugin will automatically expose every thermostat on the authenticated account.
-
-If `groups` is omitted and `autoPopulateAwayModeSwitches` is enabled, the plugin will automatically expose away-mode switches for all groups on the account.
-
-If `exposeScheduleSwitches` is enabled, the plugin will also create one switch per thermostat that turns on when the thermostat is following its Nuheat schedule and can be used to resume that schedule from HomeKit.
-
-## Nuheat API Access
-
-Nuheat's public OpenAPI documentation indicates that third-party developers should request their own API credentials:
-
-- [Nuheat OpenAPI docs](https://api.mynuheat.com/)
-- [Nuheat API access request page](https://www.nuheat.com/openapi)
-
-This fork still supports the legacy built-in OAuth client settings as a fallback, but using your own `clientId` and `clientSecret` is the recommended long-term path once Nuheat issues them for your integration.
-
-## What's New In This Fork
-
-- Fixed the manual-mode thermostat issue where HomeKit could immediately snap back to `Off`
-- Hardened online-state parsing and general accessory refresh behavior
-- Delayed platform startup until Homebridge finishes restoring cached accessories
-- Improved SignalR reconnect handling
-- Added regression tests for the key thermostat behavior fixes
-- Updated package metadata and dependency overrides for a cleaner modern release
-- Published under the maintainer-owned package identity `homebridge-nuheat2`
-- Added Swagger-aligned account, schedule, and energy API helpers for future enhancements
-
-## Development
-
-Run the test suite with:
-
-```bash
-npm test
-```
-
-## Roadmap
-
-- Validate the plugin against an official Nuheat API client registration
-- Verify group and away-mode behavior against current live API responses
-- Revisit whether SignalR notifications can reduce polling further in real-world deployments
+This project builds on the original [`senorshaun/homebridge-nuheat`](https://github.com/senorshaun/homebridge-nuheat) plugin and retains attribution for Shaun's original work.
+
+## Highlights
+
+- Automatically discovers thermostats on the authenticated Nuheat account
+- Optionally creates HomeKit switches for Nuheat group away mode
+- Supports permanent, scheduled, and timed holds
+- Uses Nuheat's OAuth-based API instead of legacy site scraping
+- Includes compatibility improvements for Homebridge 1.8+ and 2.0 betas
+- Can optionally expose a schedule switch for each thermostat
+- Allows advanced OAuth overrides for long-term API stability
+
+## Compatibility
+
+- Homebridge: `^1.8.0 || ^2.0.0-beta.0`
+- Node.js: `^18.20.4 || ^20.18.0 || ^22 || ^24`
+
+For current Homebridge 2.0 betas, use Node 22 or 24.
+
+## Installation
+
+Install Homebridge first:
+
+```bash
+npm install -g homebridge
+```
+
+Then install the plugin:
+
+```bash
+npm install -g homebridge-nuheat2
+```
+
+The published package name for this maintained fork is `homebridge-nuheat2`. The Homebridge platform name in config remains `NuHeat`.
+
+## Configuration
+
+Most users should configure the plugin through Homebridge Config UI X, but the equivalent JSON looks like this:
+
+```json
+{
+  "platform": "NuHeat",
+  "name": "NuHeat",
+  "email": "email@address.com",
+  "password": "password123",
+  "devices": [{ "serialNumber": "1111111" }, { "serialNumber": "2222222" }],
+  "autoPopulateAwayModeSwitches": true,
+  "exposeScheduleSwitches": false,
+  "holdLength": 1440,
+  "refresh": 60
+}
+```
+
+### Options
+
+- `platform`: Must be `NuHeat`
+- `name`: Display name used in Homebridge logs
+- `email`: MyNuheat account email address
+- `Email`: Legacy alias still accepted for backward compatibility, but `email` is the preferred documented field
+- `password`: MyNuheat account password
+- `devices`: Optional list of thermostats to expose. If omitted or empty, every thermostat on the account will be discovered automatically
+- `serialNumber`: Thermostat serial number from MyNuheat
+- `autoPopulateAwayModeSwitches`: Automatically expose away-mode switches for all groups on the account
+- `exposeScheduleSwitches`: Optionally expose a switch per thermostat that reflects whether the thermostat is following its schedule and can be turned on to resume the schedule
+- `groups`: Optional allow-list of groups to expose as away-mode switches. This only affects group/away-mode accessories
+- `groupName`: Group name as shown in MyNuheat
+- `holdLength`: Hold duration in minutes
+- `refresh`: Poll interval in seconds, default `60`
+- `debug`: Enables verbose logging
+- `clientId`: Optional advanced override for the Nuheat OAuth client ID. This is recommended once you have official Nuheat API credentials
+- `clientSecret`: Optional advanced override for the Nuheat OAuth client secret
+- `redirectUri`: Optional advanced override for the Nuheat OAuth redirect URI, default `http://localhost`
+
+### Hold Length Behavior
+
+- `0`: hold until the next scheduled event
+- `1-1439`: timed hold for the configured number of minutes
+- `1440`: permanent hold
+
+### Device Discovery
+
+If `devices` is omitted or empty, the plugin will automatically expose every thermostat on the authenticated account.
+
+If `groups` is omitted and `autoPopulateAwayModeSwitches` is enabled, the plugin will automatically expose away-mode switches for all groups on the account.
+
+If `exposeScheduleSwitches` is enabled, the plugin will also create one switch per thermostat that turns on when the thermostat is following its Nuheat schedule and can be used to resume that schedule from HomeKit.
+
+## Nuheat API Access
+
+Nuheat's public OpenAPI documentation indicates that third-party developers should request their own API credentials:
+
+- [Nuheat OpenAPI docs](https://api.mynuheat.com/)
+- [Nuheat API access request page](https://www.nuheat.com/openapi)
+
+This fork still supports the legacy built-in OAuth client settings as a fallback, but using your own `clientId` and `clientSecret` is the recommended long-term path once Nuheat issues them for your integration.
+
+## What's New In This Fork
+
+- Fixed the manual-mode thermostat issue where HomeKit could immediately snap back to `Off`
+- Hardened online-state parsing and general accessory refresh behavior
+- Delayed platform startup until Homebridge finishes restoring cached accessories
+- Improved SignalR reconnect handling
+- Added regression tests for the key thermostat behavior fixes
+- Updated package metadata and dependency overrides for a cleaner modern release
+- Published under the maintainer-owned package identity `homebridge-nuheat2`
+- Added Swagger-aligned account, schedule, and energy API helpers for future enhancements
+
+## Development
+
+Run the test suite with:
+
+```bash
+npm test
+```
+
+## Future Work
+
+- Validate the plugin against the official Nuheat API credentials requested for this integration.
+- Verify group and away-mode behavior against current live API responses.
+- Evaluate whether SignalR notifications can reduce polling further in real-world deployments.