@homebridge-plugins/homebridge-resideo 3.0.3-beta.8 → 3.1.0

package/.github/ISSUE_TEMPLATE/config.yml

@@ -1,4 +1,4 @@
-blank_issues_enabled: true
+blank_issues_enabled: false
 contact_links:
   - name: Homebridge Discord Channel for Resideo
     url: https://discord.gg/8fpZA4S

package/.github/copilot-instructions.md

@@ -1,204 +1,260 @@
 # Homebridge Resideo Plugin
 
-The Homebridge Resideo plugin is a TypeScript-based Homebridge plugin that integrates Resideo/Honeywell Home devices (thermostats, leak sensors, room sensors, valves) with Apple HomeKit. The plugin communicates with Resideo APIs using OAuth2 authentication and includes a web-based configuration UI.
-
-Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
-
-## Branching and Release Strategy
-
-### Beta Branch Targeting
-**IMPORTANT**: All pull requests must be directed at a branch that starts with "beta-" first, never directly to the main/latest branch.
-
-#### Branch Creation Rules
-- If no appropriate beta branch exists, create one based on the semantic versioning type:
-  - **patch** (bug fixes): Create `beta-X.Y.Z+1` (e.g., `beta-3.0.3` from current `3.0.2`)
-  - **minor** (new features): Create `beta-X.Y+1.0` (e.g., `beta-3.1.0` from current `3.0.2`) 
-  - **major** (breaking changes): Create `beta-X+1.0.0` (e.g., `beta-4.0.0` from current `3.0.2`)
-
-#### Required Labels
-Before assigning any issue to Copilot, the following labels **must** be set to determine the change type:
-- `patch` - for bug fixes and small improvements (no API changes)
-- `minor` - for new features (backward compatible API additions)
-- `major` - for breaking changes (incompatible API changes)
-
-#### Workflow
-1. Check issue has required semantic versioning label (`patch`, `minor`, or `major`)
-2. Identify or create appropriate beta branch based on the label
-3. Target all work to the beta branch, not main/latest
-4. Beta branches will be merged to main/latest after testing and validation
-
-#### Examples
-- Current version: `3.0.2`
-- Existing beta branch: `beta-3.0.3` (for patch releases)
-- For a **bug fix** with `patch` label: Use existing `beta-3.0.3` or create `beta-3.0.4`
-- For a **new feature** with `minor` label: Create `beta-3.1.0`  
-- For a **breaking change** with `major` label: Create `beta-4.0.0`
-
-#### Creating Beta Branches
-If no appropriate beta branch exists, create one using:
-```bash
-git checkout latest  # Start from latest stable
-git checkout -b beta-X.Y.Z  # Create new beta branch
-git push -u origin beta-X.Y.Z  # Push to remote
-```
+Always reference these instructions first and fall back to search only when the repo contents do not answer the question.
 
-#### Issue Assignment Requirements
-**Before assigning any issue to Copilot:**
-1. Verify the issue has one of the required semantic versioning labels (`patch`, `minor`, `major`)
-2. If missing, add the appropriate label based on the change type
-3. Confirm the target beta branch exists or needs to be created
-4. Only then assign the issue to Copilot for implementation
+This is a Homebridge platform plugin for Resideo and Honeywell Home devices. The plugin is written in TypeScript, talks to the Resideo cloud API over OAuth, and exposes supported devices to HomeKit through Homebridge.
 
-## Working Effectively
+Current focus: keep the HAP integration stable, keep the Homebridge UI account-linking flow working, and preserve existing thermostat, room sensor, leak sensor, and shutoff valve behavior.
 
-### Environment Setup
-- Ensure Node.js 20+ or 22+ is installed (current requirement from package.json engines field)
-- Use npm 10+ for package management
+## Device Support
 
-### Bootstrap and Build Process
-- `npm install` -- installs all dependencies. Takes ~30 seconds. Some deprecation warnings are expected and safe to ignore.
-- `npm run build` -- full build process. Takes ~5 seconds. NEVER CANCEL. Set timeout to 60+ seconds.
-  - Runs `npm run clean && tsc && npm run plugin-ui`
-  - Cleans dist directory, compiles TypeScript, copies UI files
-- `npm run clean` -- removes dist directory. Takes <1 second.
+### Currently Supported Devices
+- Thermostats with HomeKit exposure through the main accessory flow
+- T9 and T10 room sensors exposed as separate accessories when enabled
+- T9 and T10 room-priority virtual thermostat accessories when configured
+- Leak detectors
+- Shutoff valves
 
-### Testing and Validation
-- `npm test` -- runs linting only (not unit tests). Takes ~3 seconds.
-- `npm run lint` -- runs ESLint on TypeScript files. Takes ~3 seconds.
-- `npm run lint:fix` -- auto-fixes ESLint issues where possible.
-- `npx vitest run` -- runs actual unit tests. Takes ~1 second. **NOTE**: Some tests currently fail due to pre-existing mocking issues in platform.test.ts and a rounding issue in utils.test.ts. These failures are unrelated to code changes and should be ignored.
+### Device Classes Seen In Code
+- `Thermostat`
+- `LeakDetector`
+- `ShutoffValve`
 
-### Documentation Generation
-- `npm run docs` -- generates TypeDoc documentation. Takes ~6 seconds. Creates ./docs directory.
-- `npm run lint-docs` -- validates documentation for errors.
+### Important Notes
+- This repository is currently HAP-only. There is no Matter platform implementation in this codebase.
+- Room sensors are discovered from thermostat group data, not as top-level standalone devices.
+- Unsupported devices are logged from `src/platform.ts` and should be added through the platform discovery switch plus a dedicated device class.
 
-### Development Workflow
-- `npm run watch` -- development mode with nodemon for auto-rebuilding during development.
-- Build output is in `dist/` directory and mirrors `src/` structure.
-- The main plugin entry point is `dist/index.js` which exports the platform registration function.
-- **Always work on beta branches**: PRs should target beta branches, never main/latest directly.
-- **Use semantic versioning**: Ensure the target beta branch matches the change type (patch/minor/major).
+## Homebridge and API Integration
 
-## Validation Scenarios
+### Platform Model
+- The plugin registers a single dynamic platform through `ResideoPlatform` in `src/platform.ts`.
+- `src/index.ts` only registers the platform and contains no business logic.
+- Device discovery happens after `didFinishLaunching`, once an access token is refreshed.
 
-After making changes to the codebase, always perform these validation steps:
+### OAuth Flow
+- The Homebridge UI custom server in `src/homebridge-ui/server.ts` starts a temporary local HTTP server on port `8585`.
+- The UI redirects the user to the Resideo authorize endpoint, receives the authorization code, and exchanges it for tokens.
+- The platform refreshes the access token at runtime and writes back a new refresh token into Homebridge `config.json` when it changes.
 
-### Build Validation
-- Run `npm run build` to ensure TypeScript compilation succeeds.
-- Verify that `dist/index.js` exists and can be loaded with: `node -e "const plugin = require('./dist/index.js'); console.log('Plugin loaded:', typeof plugin.default === 'function');"`
+### Authoritative References
+- Resideo developer setup in `README.md`
+- OAuth and API endpoints in `src/settings.ts`
+- Homebridge schema and UI behavior in `config.schema.json` and `src/homebridge-ui/server.ts`
 
-### Code Quality Validation  
-- ALWAYS run `npm run lint` before committing changes or the CI will fail.
-- Run `npm run lint:fix` to automatically fix style issues.
-- Optionally run `npx vitest run` but ignore pre-existing test failures in platform.test.ts and utils.test.ts.
+## Changelog Format Requirements
 
-### Manual Testing Scenarios
-Since this is a Homebridge plugin that requires real Resideo devices and API credentials:
-- **Cannot fully test device functionality** without valid Resideo developer account and actual devices.
-- **Cannot test OAuth flow** without proper Resideo API credentials.
-- **Can test**: Plugin loading, configuration schema validation, and basic TypeScript compilation.
-- **Plugin Architecture Validation**: The built plugin should export a default function that accepts an API parameter for Homebridge platform registration.
+When generating a changelog entry for this repository, always use the homebridge-resideo compare URLs, not another plugin's URLs.
 
-## Codebase Navigation
+Use this release header format:
 
-### Key Directories and Files
+```md
+## [X.Y.Z](https://github.com/homebridge-plugins/homebridge-resideo/compare/vX.Y.(Z-1)...vX.Y.Z) (YYYY-MM-DD)
 ```
-/src/
-├── index.ts                 # Main plugin entry point - registers platform with Homebridge  
-├── platform.ts             # ResideoPlatform class - core plugin logic, API communication
-├── settings.ts              # Configuration interfaces, constants, and type definitions
-├── utils.ts                 # Utility functions (temperature conversion, etc.)
-├── devices/                 # Device-specific implementations
-│   ├── device.ts           # Base device class with common functionality
-│   ├── thermostats.ts      # Thermostat device implementation
-│   ├── leaksensors.ts      # Leak sensor device implementation  
-│   ├── roomsensors.ts      # Room sensor device implementation
-│   ├── roomsensorthermostats.ts # Room sensor thermostat combo
-│   └── valve.ts            # Valve device implementation
-└── homebridge-ui/          # Web UI for plugin configuration
-    ├── server.ts           # UI server for OAuth setup
-    └── public/index.html   # UI frontend
+
+Use standard sections as needed, such as `### Bug Fixes`, `### Enhancements`, or `### Documentation`.
+
+End each release entry with:
+
+```md
+**Full Changelog**: https://github.com/homebridge-plugins/homebridge-resideo/compare/vX.Y.(Z-1)...vX.Y.Z
 ```
 
-### Configuration and Build Files
-- `package.json` -- dependencies, scripts, and plugin metadata
-- `tsconfig.json` -- TypeScript compilation settings
-- `eslint.config.js` -- ESLint configuration using @antfu/eslint-config
-- `config.schema.json` -- Homebridge configuration UI schema
-- `.github/workflows/build.yml` -- CI/CD pipeline
-
-### Key Code Patterns
-- **Platform Registration**: `src/index.ts` exports default function that calls `api.registerPlatform()`
-- **Device Discovery**: `platform.ts` contains `discoverlocations()` and device creation methods
-- **API Communication**: Uses axios with interceptors for OAuth2 authentication to Resideo APIs
-- **Device Classes**: All inherit from base `device.ts` class with common logging and status methods
-- **Configuration**: TypeScript interfaces in `settings.ts` define all config structure
-
-## Common Tasks
-
-### Beta Branch Workflow
-1. **Check for Semantic Labels**: Verify issue has `patch`, `minor`, or `major` label
-2. **Identify Target Branch**: Find or create appropriate beta branch (e.g., `beta-3.0.3`, `beta-3.1.0`, `beta-4.0.0`)
-3. **Create Feature Branch**: Create your feature branch from the target beta branch
-4. **Submit PR**: Target your PR to the beta branch, not main/latest
-5. **Merge to Main**: Beta branches are later merged to main/latest by maintainers
-
-### Adding New Device Types
-1. Create new device class in `src/devices/` extending base Device class
-2. Add device-specific interfaces to `settings.ts` 
-3. Update `platform.ts` device discovery logic
-4. Add device creation method in platform.ts
-5. Update configuration schema in `config.schema.json`
-
-### Modifying API Communication
-- API endpoints and authentication logic are in `platform.ts`
-- OAuth2 configuration and token management handled in platform constructor
-- Resideo API URLs defined as constants in `settings.ts`
-
-### Configuration Changes
-- Update interfaces in `settings.ts` for new config options
-- Modify `config.schema.json` for UI schema changes
-- Update platform config validation in `platform.ts` `verifyConfig()` method
-
-### Debugging and Logging
-- All device classes inherit logging methods from base Device class
-- Platform logging controlled by config options
-- Use `this.debugLog()`, `this.infoLog()`, `this.warnLog()`, `this.errorLog()` in device classes
-- Platform-level logging available via platform instance methods
-
-## Troubleshooting
-
-### Build Issues
-- **TypeScript errors**: Check `tsconfig.json` settings and ensure all imports use `.js` extensions for ES modules
-- **Missing dist files**: Run `npm run clean && npm run build` to regenerate
-- **Plugin UI missing**: Ensure `npm run plugin-ui` completes successfully
-
-### Test Failures
-- **Platform tests failing**: Known issue with axios mocking in platform.test.ts - ignore these failures
-- **Utils test failures**: Known rounding issue in temperature conversion - ignore this failure  
-- **New test failures**: Only address test failures directly related to your changes
-
-### Runtime Issues
-- **Plugin not loading**: Verify `dist/index.js` exists and exports default function
-- **API authentication**: Check that OAuth2 credentials are properly configured
-- **Device discovery**: Ensure Resideo API endpoints in `settings.ts` are correct
-
-### Common npm Commands Reference
-```bash
-npm install              # Install dependencies (~30 seconds)
-npm run build           # Full build (~5 seconds, timeout 60+ seconds)
-npm run clean           # Clean dist directory (<1 second)  
-npm test                # Run linting (~3 seconds)
-npm run lint            # ESLint only (~3 seconds)
-npm run lint:fix        # Auto-fix ESLint issues
-npm run docs            # Generate documentation (~6 seconds)
-npx vitest run          # Run unit tests (~1 second, has known failures)
-npm run watch           # Development mode with auto-rebuild
+If the previous version is not known, inspect `CHANGELOG.md` before drafting the entry.
+
+## Working Effectively
+
+### Bootstrap and Build
+- Install dependencies: `npm install`
+- Build the project: `npm run build`
+- Clean build artifacts: `npm run clean`
+- Copy the Homebridge UI file into `dist`: `npm run plugin-ui`
+- Full publish pipeline: `npm run prepublishOnly`
+
+### Testing and Quality Assurance
+- Lint code: `npm run lint`
+- Fix lint issues: `npm run lint:fix`
+- Package `test` currently aliases lint: `npm run test` runs `npm run lint`
+- Vitest is installed and test files exist under `src/`, but there is no dedicated `package.json` script for them right now
+- Generate docs: `npm run docs`
+- Validate docs: `npm run lint-docs`
+
+### Development Workflow
+- Development mode: `npm run watch`
+- `npm run watch` builds, copies the UI file, links the plugin locally, and starts `nodemon`
+- The Homebridge UI is backed by a single static file at `src/homebridge-ui/public/index.html`
+- Always run `npm run build` after source changes
+- Always run `npm run lint` before finishing a code change
+
+## Validation
+
+After making code changes, validate with:
+1. `npm run build`
+2. `npm run lint`
+3. `npm run test`
+
+If you changed generated-doc comments or documentation-sensitive types, also run:
+4. `npm run docs`
+5. `npm run lint-docs`
+
+If you changed the UI login flow, also validate the Homebridge UI account-linking path.
+
+## Important Directories and Files
+
+### Source Code Structure
+- `src/index.ts` - Homebridge entry point
+- `src/platform.ts` - Main platform, OAuth refresh, discovery, accessory registration, retry and logging behavior
+- `src/settings.ts` - Plugin constants, config types, API URLs, and device-related TypeScript interfaces
+- `src/utils.ts` - Utility helpers such as temperature conversion
+- `src/devices/thermostats.ts` - Thermostat accessory implementation
+- `src/devices/roomsensors.ts` - Room sensor accessory implementation
+- `src/devices/roomsensorthermostats.ts` - Virtual thermostat accessory for room-priority flows
+- `src/devices/leaksensors.ts` - Leak sensor accessory implementation
+- `src/devices/valve.ts` - Shutoff valve accessory implementation
+- `src/homebridge-ui/server.ts` - Custom Homebridge UI backend server for OAuth login
+- `src/homebridge-ui/public/index.html` - Custom Homebridge UI frontend
+
+### Tests
+- `src/index.test.ts`
+- `src/platform.test.ts`
+- `src/settings.test.ts`
+- `src/utils.test.ts`
+
+### Configuration and Build
+- `package.json`
+- `config.schema.json`
+- `eslint.config.js`
+- `tsconfig.json`
+- `typedoc.json`
+- `nodemon.json`
+- `.github/copilot-instructions.md`
+
+### Generated Output
+- `dist/`
+- `docs/`
+
+## Dependencies and Requirements
+
+### Runtime Requirements
+- Node.js `^20 || ^22`
+- Homebridge `^1.9.0 || ^2.0.0 || ^2.0.0-beta.26 || ^2.0.0-alpha.37`
+
+### Key Runtime Dependencies
+- `axios` for Resideo API requests
+- `rxjs` for reactive flows used by device code
+- `@homebridge/plugin-ui-utils` for the Homebridge settings UI server
+
+### Key Development Dependencies
+- `typescript`
+- `eslint`
+- `@antfu/eslint-config`
+- `typedoc`
+- `vitest`
+- `nodemon`
+
+## Common Development Tasks
+
+### Adding New Device Support
+1. Add the device class handling in the discovery switch in `src/platform.ts`.
+2. Create a new implementation under `src/devices/` following the existing accessory classes.
+3. Update `config.schema.json` if the new device requires user-configurable options.
+4. Add or update TypeScript types in `src/settings.ts`.
+5. Make sure cached accessories use a stable UUID pattern.
+6. Validate with `npm run build`, `npm run lint`, and `npm run test`.
+
+### Changing Thermostat or Sensor Behavior
+1. Start in `src/platform.ts` to find the controlling discovery and refresh path.
+2. Move into the owning class in `src/devices/thermostats.ts`, `src/devices/roomsensors.ts`, or `src/devices/roomsensorthermostats.ts`.
+3. Keep room sensor logic aligned with the thermostat group APIs used by `getCurrentSensorData()`.
+4. Preserve per-device config overrides from `options.devices`.
+
+### Changing the OAuth or UI Flow
+1. Update the frontend in `src/homebridge-ui/public/index.html`.
+2. Update the backend server in `src/homebridge-ui/server.ts`.
+3. Keep the callback path and port handling aligned with the README and schema.
+4. Rebuild so the UI file is copied to `dist`.
+
+## Common Issues and Solutions
+
+### Build Failures
+- Verify dependencies are installed with `npm install`.
+- Rebuild from clean state with `npm run clean && npm run build`.
+- Remember this project is ESM and local imports use `.js` extensions.
+
+### Test Confusion
+- `npm run test` is not a separate unit-test command in this repo; it currently runs lint.
+- If you need to execute Vitest directly, use the local toolchain already present in the repo rather than inventing a new workflow.
+
+### OAuth and Login Failures
+- Re-check the Resideo developer app callback URL and credentials.
+- Confirm the temporary local server can bind to port `8585`.
+- If token refresh fails, inspect the stored credentials in Homebridge config and the refresh-token update path in `src/platform.ts`.
+
+### Device Discovery Gaps
+- Discovery is location-based through the Resideo API.
+- Room sensors depend on thermostat groups and will not appear unless the thermostat and group data support them.
+- Unsupported `deviceClass` values require new platform handling and a dedicated accessory implementation.
+
+Never describe this repository as a Lutron plugin, never mention Matter support as if it exists today, and never reference files such as `Platform.Matter.ts`, `WallDimmer.ts`, `PicoRemote.ts`, or other artifacts that are not present in this workspace.
+
+## Matter and HomeKit Integration
+
+### Matter Implementation
+The plugin implements dual-mode device registration:
+- **HAP mode** (HomeKit Accessory Protocol): Base implementation via `LutronCasetaLeap` class
+- **Matter mode**: Extended via `LutronCasetaLeapMatterPlatform` class that overrides `processDevice()`
+
+When Homebridge's Matter API is available, `LutronCasetaLeapMatterPlatform.processDevice()` registers accessories with both HAP and Matter simultaneously. If Matter API is not available, the plugin transparently falls back to HAP-only mode.
+
+### Matter Device Type Mapping
+All Matter device types use `api.matter.deviceTypes.*` objects from the homebridge-matter API:
+
+| Device Type | HAP Service | Matter DeviceType | Matter Clusters |
+|---|---|---|---|
+| WallDimmer | Lightbulb | `DimmableLight` | onOff, levelControl |
+| WallSwitch | Switch | `OnOffLight` | onOff |
+| SerenaTiltOnlyWoodBlind | WindowCovering | `WindowCovering` | windowCovering |
+| RPSOccupancySensor | OccupancySensor | `OccupancySensor` | occupancySensing |
+| Pico Remotes | StatelessProgrammableSwitch | `GenericSwitch` | switch |
+
+### Authoritative Matter References
+
+1. https://matter-js.github.io/docs/index.html
+2. https://github.com/homebridge-plugins/homebridge-matter: Official Homebridge Matter plugin repository with extensive documentation and examples
+  - For all Matter cluster, attribute, and device type specifications, use the official homebridge-matter wiki:
+    - [Introduction](https://github.com/homebridge-plugins/homebridge-matter/wiki/Introduction)
+    - [Core Concepts](https://github.com/homebridge-plugins/homebridge-matter/wiki/Core-Concepts)
+    - [Getting Started](https://github.com/homebridge-plugins/homebridge-matter/wiki/Getting-Started)
+    - [State Management](https://github.com/homebridge-plugins/homebridge-matter/wiki/State-Management)
+    - [Monitoring External Changes](https://github.com/homebridge-plugins/homebridge-matter/wiki/Monitoring-External-Changes)
+    - [Best Practices](https://github.com/homebridge-plugins/homebridge-matter/wiki/Best-Practices)
+    - [Advanced Patterns](https://github.com/homebridge-plugins/homebridge-matter/wiki/Advanced-Patterns)
+    - [API Reference](https://github.com/homebridge-plugins/homebridge-matter/wiki/API-Reference)
+    - [Matter Types](https://github.com/homebridge-plugins/homebridge-matter/wiki/Matter-Types)
+    - [Value Conversions](https://github.com/homebridge-plugins/homebridge-matter/wiki/Value-Conversions)
+
+  - **Device References:**
+    - [Lighting Devices (§4)](https://github.com/homebridge-plugins/homebridge-matter/wiki/Section-4-Lighting) — DimmableLight, OnOffLight
+    - [Switches (§6)](https://github.com/homebridge-plugins/homebridge-matter/wiki/Section-6-Switches) — OnOffSwitch
+    - [Sensors (§7)](https://github.com/homebridge-plugins/homebridge-matter/wiki/Section-7-Sensors) — OccupancySensor
+    - [Closure Devices (§8)](https://github.com/homebridge-plugins/homebridge-matter/wiki/Section-8-Closure) — WindowCovering
+
+## Changelog Format Requirements
+
+When generating a changelog release entry, always use this exact structure:
+
+1. Release header with compare URL using `compare/tag/vX.Y.Z`:
+
+```md
+## [X.Y.Z](https://github.com/homebridge-plugins/homebridge-updater/compare/tag/vX.Y.Z) (YYYY-MM-DD)
+```
+
+2. Standard sections as needed (`### Bug Fixes`, `### Enhancements`, `### Documentation`, etc.).
+
+3. End each release entry with a full changelog comparison URL to the previous version:
+
+```md
+**Full Changelog**: https://github.com/homebridge-plugins/homebridge-updater/compare/vX.Y.(Z-1)...vX.Y.Z
 ```
 
-## Critical Reminders
-- **NEVER CANCEL** any build commands - let them complete fully
-- **ALWAYS** run `npm run lint` before pushing changes to avoid CI failures
-- **DO NOT** attempt to fix pre-existing test failures unrelated to your changes
-- **VALIDATE** that your changes can be built and the plugin can be loaded
-- Use `.js` extensions in TypeScript imports for ES module compatibility
+Do not omit either URL line when creating a new release entry.

package/.github/labeler.yml

@@ -20,9 +20,9 @@ dependencies:
     - any-glob-to-any-file: 'package.json'
     - any-glob-to-any-file: 'package-lock.json'
 
-# Add 'beta' label to any PR that is opened against a beta branch (beta-X.Y.Z format)
+# Add 'beta' label to any PR that is opened against the `beta` branch
 beta:
-- base-branch: 'beta-*'
+- base-branch: 'beta*'
 
 # Add 'alpha' label to any PR that is opened against the `alpha` branch
 alpha:
@@ -35,15 +35,4 @@ latest:
 # Add 'workflow' to any changes within 'workflow' folder or any subfolders
 workflow:
 - changed-files:
-  - any-glob-to-any-file: .github/**
-
-# Semantic versioning labels for automated release management
-# These labels should be manually applied before assigning issues to Copilot
-patch:
-- any: []  # Manual assignment only
-
-minor:
-- any: []  # Manual assignment only
-
-major:
-- any: []  # Manual assignment only
+  - any-glob-to-any-file: .github/**