homebridge-nuheat2 1.2.5 → 1.2.7

package/CHANGELOG.md

@@ -1,9 +1,34 @@
-# 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.7] - 2026-04-15
+
+### Added
+
+- TypeScript build and typecheck scaffolding for incremental migration
+- TypeScript tests for the Swagger-normalization helpers, schedule switch, and thermostat behavior
+- GitHub Actions workflows for CI validation and automated npm publishing
+
+### Changed
+
+- Move the platform entrypoint, API client, accessory classes, logger, settings, models, and test helpers to TypeScript source under `src/`
+- Keep the published CommonJS runtime layout stable by compiling TypeScript back into `index.js`, `lib/`, and `test/`
+- Switch package repository metadata to the canonical GitHub URL for npm trusted publishing and provenance
+
+## [1.2.6] - 2026-04-11
+
+### Added
+
+- Add an `enableNotifications` config option so SignalR can be disabled during troubleshooting
+
+### Changed
+
+- 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
+
 ## [1.2.5] - 2026-04-11
 
 ### Changed
@@ -18,93 +43,93 @@ All notable changes to this project should be documented in this file
 - Correct setpoint debug log spacing in thermostat updates
 
 ## [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
+
+### 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/README.md

@@ -1,129 +1,163 @@
-# 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.
 
 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.
+
+## 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
+
+The TypeScript migration is now underway for the core runtime. The source of truth for the platform, API client, accessories, internal models, and tests lives under `src/`, and `npm run build` compiles that back into the existing CommonJS layout used by Homebridge (`index.js`, `lib/`, and `test/`).
+
+This keeps the published plugin layout stable while we migrate incrementally instead of doing a risky one-shot rewrite.
+
+Common development commands:
+
+```bash
+npm run build
+npm run typecheck
+```
+
+Run the test suite with:
+
+```bash
+npm test
+```
+
+## Release Automation
+
+GitHub Actions now handles two jobs for this repository:
+
+- `.github/workflows/ci.yml` runs `npm ci`, `npm run typecheck`, and `npm test` on pushes and pull requests across Node 20, 22, and 24
+- `.github/workflows/publish.yml` runs on pushes to `master` when `package.json` changes, re-runs the checks on Node 24, and publishes to npm only when the `package.json` version is not already on the registry
+
+The publish workflow also maps prerelease versions to npm dist-tags automatically. For example, `1.2.7-beta.1` publishes with the `beta` tag, while stable versions publish to `latest`.
+
+### Recommended npm Setup
+
+Use npm trusted publishing rather than a long-lived automation token.
+
+1. Open the `homebridge-nuheat2` package settings on npm.
+2. Add a trusted publisher for GitHub Actions.
+3. Configure:
+   - Organization or user: `applemanj`
+   - Repository: `homebridge-nuheat2`
+   - Workflow filename: `publish.yml`
+4. Keep the workflow on GitHub-hosted runners.
+
+After that, bump the version in `package.json`, push to `master`, and GitHub Actions will publish the new version automatically once the checks pass.
+
+## 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.