homebridge-tsvesync/CHANGELOG.md

Homebridge plugin for VeSync devices including Levoit air purifiers, humidifiers, and Etekcity smart outlets

# Changelog

## 1.4.9 (2026-03-30)

### Fixed
- **💧 Dual 200S Mode, Mist, and Humidity Control**: Corrected HomeKit target-state mapping for Dual 200S / LUH-D301S humidifiers, constrained mist control to the two supported levels, and switches to manual mode before applying mist-speed changes so Home commands match actual device behavior.
- **🎯 Humidity Slider Stability**: Prevented target-humidity snap-back by keeping the commanded humidity in memory, updating the humidity field the getter actually reads, and syncing `Active` immediately when humidity changes power the unit on.
- **🕒 Stale Mode Override Expiry**: Expires the temporary commanded-mode override after 30 seconds so HomeKit stays stable during eventual consistency without masking later mode changes from the VeSync app.

### Changed
- **🧱 Build Scope**: Excluded test files from the production TypeScript build to avoid type-check failures caused by local/Homebridge test-only type differences.

### Tests
- **🧪 Dual 200S Regression Coverage**: Expanded humidifier write-consistency coverage around target humidity and stale-response behavior so the plugin-side Dual 200S fixes stay locked in.

### Dependencies
- **📦 tsvesync**: Updated to 1.4.9 for the Dual 200S humidifier bypass write-method fix.

## 1.4.8 (2026-03-27)

### Fixed
- **💧 Dual 200S Write Consistency**: Humidifier writes now follow the same optimistic HomeKit update pattern as the air purifier accessory, so successful power and auto-mode commands no longer log false "did not change to desired state/mode" warnings or bounce the Home app back to stale values while VeSync catches up.

### Tests
- **🧪 Humidifier Regression Coverage**: Added targeted stale-refresh tests for Dual 200S power and auto-mode writes to lock in the eventual-consistency behavior reported in issue #31.

### Dependencies
- **📦 tsvesync**: Updated to 1.4.8 for version sync (no functional changes).

## 1.4.7 (2026-02-02)

### Fixed
- **🧽 Preserve HomeKit Automations When Devices Go Offline**: Stops unregistering accessories when a device temporarily disappears from the VeSync device list (e.g., powered off/unplugged for filter cleaning), preventing HomeKit name resets and broken automations. Accessories remain cached and should recover automatically when the device comes back online.

### Dependencies
- **📦 tsvesync**: Updated to 1.4.7 for version sync (no functional changes).

## 1.4.6 (2026-01-25)

### Fixed
- **🔑 Token Expiration Recovery (-11001022)**: Pulls in tsvesync's improved token-expiration handling so the plugin automatically re-authenticates and retries when VeSync returns `code: -11001022` ("the token has expired"), even when the HTTP status is 200.

### Dependencies
- **📦 tsvesync**: Updated to 1.4.6 for token-expiration recovery (`-11001022`) and HTTP 200 token-expired response handling.

## 1.4.5 (2026-01-19)

### Fixed
- **🧩 Node 24 Compatibility**: Relaxed `engines.node` to allow installation on Node 24.x.

### Dependencies
- **📦 tsvesync**: Updated to 1.4.5 for version sync (no functional changes).

## 1.4.4 (2026-01-19)

### Fixed
- **🪵 Log Spam (Core 400S + other AirPurifiers)**: Prevented the air purifier accessory from being re-created on every polling cycle, which was repeatedly re-running service setup and spamming "Configured for AUTO and MANUAL modes..." logs.
- **📊 Quota Management Toggle**: `quotaManagement.enabled=false` now actually disables quota tracking/logging (including the periodic "Daily quota status..." message).

### Changed
- **🔁 Discovery Efficiency**: Avoid redundant startup `client.update()` calls (discovery already refreshes the device list), reducing unnecessary API traffic.
- **🧾 Logging**: Downgraded the auto/manual configuration line to `debug` since it does not reflect a state change.

## 1.4.3 (2025-12-21)

### Fixed
- **🌍 Cross-Region Session + Device Discovery Reliability**: Picks up the tsvesync 1.4.3 pyvesync-parity improvements so non-US/EU accounts can reuse persisted sessions and still discover devices reliably (fixes issue #25).

### Dependencies
- **📦 tsvesync**: Updated to 1.4.3 for region/session/device-list parity fixes.

## 1.4.2 (2025-12-09)

### Fixed
- **Critical Session File Corruption Fix**: Resolved race condition causing session.json corruption from concurrent writes
  - Implemented write mutex in FileSessionStore to serialize concurrent save operations
  - Fixed race condition when both tsvesync library and homebridge plugin attempted simultaneous session saves
  - Session saves now use read-merge-write pattern to preserve all fields (especially 'username') across library-triggered saves
  - Prevents "Extra data: line X column Y" JSON parse errors that caused repeated login failures
  - Eliminated API quota exhaustion from constant re-authentication due to corrupted sessions
- **Enhanced Session Error Logging**: Changed session save errors from debug to error level for better visibility
  - Critical session persistence failures now properly visible in logs
  - Improved troubleshooting capability for session-related authentication issues
- **Removed Duplicate Session Save**: Eliminated redundant save in onTokenChange callback
  - Prevents duplicate writes that contributed to race condition
  - Library already saves session after token refresh, plugin no longer needs duplicate save
  - Reduces filesystem I/O and potential for concurrent write conflicts

### Technical Details
- **Write Mutex Implementation**: Added saveInProgress promise to serialize concurrent save operations
- **Read-Merge-Write Pattern**: Session save now reads existing data, merges with new data, preserves all fields
- **Preserved Fields**: Username and other platform-specific fields now survive library-triggered session saves
- **Race Condition Context**: Race occurred when:
  - tsvesync library saved session after token refresh (vesync.ts:354)
  - Platform's onTokenChange callback saved again with username field (platform.ts:378)
  - Both writes happened simultaneously causing JSON corruption in containerized environments

### Impact
- **Containerized Deployments**: Fixes critical bug affecting Docker/Kubernetes deployments where session corruption was common
- **Authentication Reliability**: Eliminates repeated login failures from corrupted session files
- **API Quota Management**: Prevents quota exhaustion from constant re-authentication attempts
- **Startup Reliability**: Ensures consistent session recovery across Homebridge restarts

## 1.4.1 (2025-12-09)

### Fixed
- **🌡️ Core 300S/400S/600S Air Quality Sensors**: Resolved missing air quality sensors for LAP variant devices in HomeKit
  - Core 400S (LAP-C401S variants) now properly display air quality sensor with PM2.5 readings
  - Core 300S (LAP-C301S/C302S variants) air quality sensors now appear in HomeKit
  - Core 600S (LAP-C601S variants) air quality monitoring now fully functional
  - Fixes issue where devices with air quality hardware were not exposing air quality characteristics
- **🔧 Multi-Firmware Air Quality Support**: Enhanced air quality data parsing for compatibility across firmware versions
  - Supports both snake_case and PascalCase API field naming conventions
  - Handles varying API response formats from different device firmware versions
  - Improves reliability of air quality readings across all Core series devices

### Enhanced
- **🎯 Regional Variant Auto-Detection**: Improved device type matching for international market variants
  - Automatically maps LAP regional codes (e.g., LAP-C401S-WUSR, LAP-C401S-WJP) to correct base configurations
  - Future-proof support for new regional variants without plugin updates
  - Enhanced device classification with fallback matching for unknown variant codes

### Dependencies
- **📦 tsvesync**: Updated to 1.4.1 for air quality sensor fixes and enhanced device type matching

## 1.4.0 (2025-10-26)

### Added
- **🧪 Everest Regression Coverage**: Extended the Everest Air accessory tests to exercise auto-sentinel state updates and turbo failure paths, locking in the new tsvesync behaviors.

### Changed
- **🎚️ Slider Semantics**: The air purifier accessory now treats the first notch as Sleep, middle notches as discrete manual speeds, and the top notch as Turbo while automatically shifting HomeKit’s target state to Auto whenever the purifier reports the sentinel fan speed.
- **📉 Error Resilience**: Turbo failures surface through our logging pipeline without spoofing the UI, and auto state updates keep Rotation Speed at 0% so automations see the correct behavior.

### Dependencies
- **📦 tsvesync**: Bumped to 1.4.0 for the expanded Everest/Vital mode metadata and bypassV2 parity fixes.

## 1.3.13 (2025-10-23)

### Fixed
- **🌫️ HomeKit AQ Automations**: Air Quality accessories now prioritize pyvesync's categorical levels and fall back to PM2.5 thresholds, keeping the Home app's “drops below Inferior” trigger selectable instead of collapsing to Poor.

### Changed
- **📊 Sensor Mapping**: Clamp PM2.5 heuristics to HomeKit’s four-level scale and reuse tsvesync’s normalized metadata so characteristic values stay identical across the plugin and library.

### Tests
- **🧪 Air Quality Regression Suite**: Added dedicated sensor tests covering normalized levels, vendor fallbacks, and PM2.5 heuristics to guard against future mapping regressions.

### Dependencies
- **📦 tsvesync**: Updated to 1.3.13 for the shared normalization helper and purifier metadata alignment.

## 1.3.12 (2025-10-22)

### Fixed
- **🔌 ESWD16 Toggle Flow**: HomeKit On/Off events now call the dimmer’s `turnOn/turnOff` API before restoring brightness, preventing stalls when the slider was previously set to 0%.
- **💾 Brightness Memory**: Restores the last dimmer level after a power-on and keeps HomeKit’s slider aligned with the wall switch.

### Tests
- **🧪 Dimmer Coverage**: Added assertions ensuring the plugin invokes both `turnOn/turnOff` and `setBrightness`, protecting the new toggle flow from regressions.

### Dependencies
- **📦 tsvesync**: Updated to 1.3.12 for the trace ID parity and ESWD16 state alignment.

## 1.3.11 (2025-10-22)

### Fixed
- **🔌 ESWD16 Main Tile**: Switched the plugin to the updated tsvesync bypass calls so the primary Dining Lights tile now toggles the load and updates brightness reliably.
- **🎯 Accurate Capabilities**: Hides the indicator colour service for ESWD16 models, removing the phantom colour picker HomeKit was showing for this white-only dimmer.

### Dependencies
- **📦 tsvesync**: Updated to 1.3.11 to pick up the new ESWD16 bypass-v1 implementation and state normalization.

## 1.3.10 (2025-10-21)

### Fixed
- **💡 ESL Bulb Control**: HomeKit now routes ESL100/ESL100CW/ESL100MC actions through the corrected tsvesync endpoints, restoring on/off, dimming, and color control for these bulbs.
- **🎨 Accurate Color & Temperature Updates**: Hue/Saturation commands convert via the shared HSV→RGB helpers and color-temperature sliders translate between mireds and VeSync percentages, eliminating the no-op adjustments users reported.

### Changed
- **🧩 Capability Detection**: Light accessories consume the new tsvesync bulb helpers, keeping feature detection and state reads aligned with pyvesync and reducing duplicated logic inside the plugin.

### Dependencies
- **📦 tsvesync**: Updated to 1.3.10 for the ESL bulb API parity, color helpers, and normalized bypass responses.

## 1.3.9 (2025-10-05)

### Fixed
- **🗻 EverestAir Toggle Reliability**: HomeKit power commands now relay the updated tsvesync `powerSwitch` payloads so EverestAir purifiers actually turn on/off instead of silently ignoring requests.
- **🎚️ Manual Fan Control**: Fan speed updates forward the new manual speed payloads, preventing EverestAir and Vital purifiers from snapping back to auto at max speed after HomeKit adjustments.

### Dependencies
- **📦 tsvesync**: Updated to 1.3.9 for the synchronized bypassV2 API fixes and auto-state normalization.

## 1.3.8 (2025-09-19)

### Fixed
- **🔌 HomeKit Toggle Reliability**: ESWD16 dimmer switches now translate HomeKit On/Off into brightness updates, restoring the wall switch behavior that regressed in 1.3.7.
- **🌈 Indicator Ring Activation**: Hue/Saturation changes automatically wake the locator ring before applying new colors, so the Home app color picker works every time.
- **🔁 State Refresh**: Brightness changes persist the latest level and refresh the cloud snapshot, keeping HomeKit and VeSync in sync after manual toggles.

### Dependencies
- **📦 tsvesync**: Updated to 1.3.8 for matching ESWD16 API fixes and the exported `VeSyncDimmerSwitch` helper.

## 1.3.7 (2025-09-19)

### Dependencies
- **📦 tsvesync**: Updated to 1.3.7 to keep the plugin and library version numbers matched.

## 1.3.6 (2025-09-19)

### Dependencies
- **📦 tsvesync**: Updated to 1.3.5 to keep the plugin aligned with the latest library release.

## 1.3.5 (2025-09-19)

### Fixed
- **🚨 ESWD16 Initialization Regression**: Restore dimmer detection during accessory setup so HomeKit now shows the brightness slider and indicator service without crashing on launch.
- **🛠️ Safe Capability Fallbacks**: Ensure cached ESWD16 accessories derive capabilities before the base constructor runs, preventing `hasBrightness` errors during rediscovery and background polls.

### Packaging
- **📦 Built Distribution**: Regenerated compiled `dist/` output and verified release bundle to include the new dimmer logic.

## 1.3.4 (2025-09-18)

### Added
- **🕹️ ESWD16 Dimming in HomeKit**: ESWD16 dimmer switches now register as HomeKit `Lightbulb` accessories with native On/Off and Brightness control.
- **🌈 Indicator Ring Control**: Introduced a dedicated "Indicator" light service for the ESWD16 locator ring, including Hue/Saturation control powered by automatic HSV→RGB conversion.

### Improved
- **🔄 State Synchronization**: On/Off and brightness updates now refresh ESWD16 cloud state immediately, keeping HomeKit characteristics accurate even when VeSync lags.
- **🛡️ Polling Guardrails**: Background discovery is now serialized and paired with UUID-stable Air Quality accessories, preventing duplicate registrations and overlapping sync loops.

### Dependencies
- **📦 tsvesync**: Upgraded to 1.3.4 to stay aligned with the latest ESWD16 API surfaces.

## 1.3.3 (2025-01-05)

### Fixed
- **⏰ Extended Timeout Chain Fix**: Enhanced proactive token refresh system to handle very long-duration tokens
  - **🔧 Timeout Chaining**: Implemented timeout chaining for refresh delays exceeding Node.js setTimeout maximum (~24.8 days)
  - **🛡️ Robust Scheduling**: Prevents timer overflow errors with automatic timer chaining for extended token lifetimes
  - **⚡ Seamless Operation**: Long-duration token refresh scheduling now works reliably without timing limitations
  - **🎯 Precision Handling**: Maintains accurate refresh timing even for tokens with extended lifetimes
  - **📊 Enhanced Logging**: Improved logging for chained timer operations and extended refresh scheduling

- **🔄 Session Hydration Compatibility**: Enhanced session recovery with backward compatibility
  - **🛡️ Fallback Support**: Added backward-compatible session hydration for older tsvesync versions
  - **⚡ Direct Field Setting**: Automatic fallback to direct field setting when hydrateSession method unavailable
  - **🔧 Improved Reliability**: Enhanced session recovery across different tsvesync library versions
  - **📊 Better Error Handling**: Graceful handling of version compatibility during session restoration

### Enhanced
- **🎯 Timer Management**: Advanced timer management system for extended timeout scenarios
  - **🔧 MAX_DELAY Handling**: Proper handling of Node.js setTimeout maximum delay limitations (2,147,483,647 ms)
  - **⚡ Chain Calculation**: Intelligent timer chaining with accurate remaining time calculations
  - **🛡️ Error Prevention**: Prevents timer overflow errors and ensures reliable long-duration scheduling
  - **📈 Performance**: Optimized timer chaining with minimal overhead for standard use cases

### Technical Details
- **🏗️ Timeout Architecture**: Enhanced proactive refresh system with timeout chaining support
- **📊 Timer Chain Logic**: Automatic detection and handling of timeouts exceeding Node.js limitations
- **🔧 Compatibility Layer**: Backward-compatible session hydration for various tsvesync versions
- **⚡ Precision Timing**: Maintains accurate refresh timing regardless of token lifetime duration

### Dependencies
- **📦 tsvesync**: Updated to 1.3.3 for enhanced cross-project version synchronization

### Summary of All Enhancements from v1.2.0 onwards

#### Session Management & Authentication System (v1.2.0-1.3.3)
- **💾 Complete Session Persistence**: Sessions survive across Homebridge restarts with enhanced validation
- **⏰ Advanced Proactive Token Refresh**: Intelligent refresh scheduling with extended timeout support (v1.3.0-1.3.3)
- **🔐 Enhanced Security**: Username validation and account isolation for multi-user environments
- **📊 JWT Token Mastery**: Complete lifecycle management with normalized timestamp handling
- **🛡️ Secure Storage**: Protected session storage with comprehensive validation and recovery
- **🚀 Performance Optimization**: Reduced authentication overhead with intelligent session reuse
- **🔄 Cross-Region Support**: Enhanced compatibility with different VeSync regional endpoints
- **🎯 Extended Timeout Handling**: Reliable scheduling for very long-duration token refresh scenarios (NEW in 1.3.3)

#### Speed Control & HomeKit Integration (v1.2.0-1.3.1)
- **🎛️ Advanced Speed Control**: Dynamic support for 3-4+ speed air purifiers with model-specific logic
- **🌙 Intelligent Sleep Mode**: Sleep mode integration as first notch on HomeKit slider
- **🎯 Precision Mapping**: Accurate percentage-to-speed conversions for different device capabilities
- **📱 Enhanced UX**: Improved slider positions, speed transitions, and HomeKit responsiveness
- **🔄 Smart Notch System**: Automatic adjustment based on device capabilities and speed ranges

Full changelog: https://github.com/mickgiles/homebridge-tsvesync/blob/main/CHANGELOG.md

## 1.3.2 (2025-01-05)

### Enhanced
- **🔐 Advanced Session Management**: Comprehensive improvements to session persistence and authentication reliability
  - **👤 Enhanced Username Validation**: Session reuse now validates username to prevent cross-account authentication conflicts
  - **🔒 Improved Account Isolation**: Persisted sessions are properly isolated and validated against configured accounts
  - **💾 Optimized Session Persistence**: Best-effort session saving immediately after successful authentication
  - **📝 Detailed Session Logging**: Comprehensive debug logging for session save/load operations with expiration tracking
  - **🛡️ Robust Error Handling**: Enhanced error messages and recovery flows for session hydration failures

- **🔧 JWT Timestamp Precision Handling**: Enhanced token timestamp processing for consistent authentication
  - **📊 Timestamp Normalization**: Automatic detection and conversion of millisecond timestamps to seconds
  - **⚡ Improved Token Validation**: Ensures accurate token expiration calculations across different token formats
  - **🔄 Cross-Region Compatibility**: Better handling of JWT tokens from different VeSync regional endpoints
  - **🛡️ Edge Case Prevention**: Fixes authentication issues with tokens using inconsistent timestamp precision

### Fixed
- **🎛️ Session Hydration Reliability**: Improved session recovery and validation processes
  - **🔍 Better Error Detection**: Enhanced detection of invalid or corrupted session data
  - **📈 Startup Performance**: Optimized authentication flow to reduce unnecessary login attempts
  - **⚡ Token Lifecycle Management**: Better coordination with tsvesync library's token refresh mechanisms
  - **🛡️ Authentication Stability**: Reduced authentication interruptions during long-running sessions

### Technical Details
- **🏗️ Session Architecture**: Enhanced session store with improved persistence and validation logic
- **📊 Token Management**: Advanced JWT token handling with normalized timestamp precision
- **🔧 Error Handling**: Comprehensive error recovery flows with detailed logging and debugging
- **⚡ Performance**: Optimized session operations for better startup performance and reliability

### Dependencies
- **📦 tsvesync**: Updated to 1.3.2 for enhanced JWT timestamp handling and session management improvements

### Summary of All Enhancements from v1.2.0 onwards

#### Session Management & Authentication System (v1.2.0-1.3.2)
- **💾 Complete Session Persistence**: Sessions survive across Homebridge restarts with enhanced validation
- **⏰ Advanced Proactive Token Refresh**: Intelligent refresh scheduling prevents JWT expiration (v1.3.0)
- **🔐 Enhanced Security**: Username validation and account isolation for multi-user environments
- **📊 JWT Token Mastery**: Complete lifecycle management with normalized timestamp handling
- **🛡️ Secure Storage**: Protected session storage with comprehensive validation and recovery
- **🚀 Performance Optimization**: Reduced authentication overhead with intelligent session reuse
- **🔄 Cross-Region Support**: Enhanced compatibility with different VeSync regional endpoints

#### Speed Control & HomeKit Integration (v1.2.0-1.3.1)
- **🎛️ Advanced Speed Control**: Dynamic support for 3-4+ speed air purifiers with model-specific logic
- **🌙 Intelligent Sleep Mode**: Sleep mode integration as first notch on HomeKit slider
- **🎯 Precision Mapping**: Accurate percentage-to-speed conversions for different device capabilities
- **📱 Enhanced UX**: Improved slider positions, speed transitions, and HomeKit responsiveness
- **🔄 Smart Notch System**: Automatic adjustment based on device capabilities and speed ranges

Full changelog: https://github.com/mickgiles/homebridge-tsvesync/blob/main/CHANGELOG.md

## 1.3.1 (2025-09-04)

### Fixed
- **🔐 Enhanced Session Management**: Improved session persistence and authentication flow
  - **👤 Username Validation**: Session reuse now validates username to prevent cross-account conflicts
  - **🔒 Account Isolation**: Persisted sessions are ignored if they belong to a different configured account
  - **⚡ Optimized Login Flow**: Authentication only occurs when necessary, relying on persisted tokens and library re-login
  - **🛡️ Session Security**: Enhanced session storage with username tracking for better account management

- **🎛️ Core 200S Speed Control Improvements**: Enhanced air purifier speed control for Core 200S devices
  - **🎯 Model-Specific Logic**: Core 200S now uses dedicated speed calculation method with proper 25% steps
  - **📊 Accurate Mapping**: Improved speed-to-percentage conversion for devices with 3 manual speeds
  - **🌙 Sleep Mode Integration**: Better sleep mode handling with model-specific speed ranges
  - **🔄 Precise Notch Calculation**: Enhanced notch-to-speed mapping for more accurate HomeKit control

### Enhanced
- **📝 Improved Logging**: Better debugging information for mode changes and device operations
  - **🔍 Mode Change Tracking**: Enhanced logging for manual, auto, and sleep mode transitions
  - **🎛️ Speed Control Logging**: More detailed logging for speed changes and slider operations
  - **📱 HomeKit Integration**: Better visibility into device state changes and characteristic updates

### Changed
- **🔄 Authentication Strategy**: Optimized authentication flow to reduce unnecessary login attempts
  - **💾 Token Persistence**: Improved reliance on persisted tokens with library-managed re-authentication
  - **⚡ Startup Performance**: Faster platform initialization by avoiding redundant login checks
  - **🎯 Smart Re-login**: Authentication only triggered when API returns 401/419 status codes

### Technical Details
- **🏗️ Session Architecture**: Enhanced session store with username tracking and validation
- **🎛️ Speed Control Algorithm**: Model-specific speed calculation methods for different device types
- **🔧 Authentication Flow**: Streamlined login logic with better token lifecycle management
- **📊 Core 200S Support**: Dedicated isCore200S() method for model-specific functionality

### Dependencies
- **📦 tsvesync**: Updated to 1.3.1 for enhanced token expiration detection and authentication improvements

## 1.3.0 (2025-09-04)

### Added
- **⏰ Enhanced Proactive Token Refresh**: Advanced JWT token refresh system with intelligent scheduling
  - **🎯 Smart Scheduling Policy**: Dynamic refresh timing based on token lifetime:
    - >7 days remaining: refresh 5 days before expiry
    - 1-7 days remaining: refresh 12 hours before expiry
    - 1-24 hours remaining: refresh 1 hour before expiry
    - <1 hour remaining: rely on 401-triggered re-login to prevent thrashing
  - **📊 Accurate Lifetime Tracking**: Uses actual token issuance time (iat) for precise calculations
  - **🛡️ Duplicate Prevention**: Guards against multiple timers for same token expiration
  - **🔄 State Management**: Concurrent refresh protection with in-progress tracking
  - **🧹 Clean Shutdown**: Proper timer cleanup on platform shutdown
  - **⚡ Background Operation**: Seamless token refresh without service interruption

- **🔧 Advanced Session Management**: Enhanced integration with tsvesync v1.3.0
  - **🔔 Token Change Integration**: Full utilization of tsvesync's onTokenChange callback system
  - **📈 Reliability**: Eliminates VeSync connectivity interruptions from expired tokens
  - **🎯 Optimal Timing**: Intelligent buffer calculation prevents both premature and late refreshes
  - **⏰ Safety Floor**: Never schedules refresh less than 30 minutes from current time

### Enhanced
- **🔐 Session Persistence**: Improved session management with proactive refresh integration
  - **💾 Complete Session Recovery**: Sessions survive across Homebridge restarts with enhanced refresh
  - **📊 JWT Integration**: Advanced token lifecycle management with expiration tracking
  - **🛡️ Secure Storage**: Protected session storage in tsvesync subdirectory
  - **🚀 Faster Startup**: Reduced authentication overhead via intelligent session reuse
  - **🔄 Seamless Recovery**: Automatic fallback when persisted sessions are invalid

### Changed
- **📚 Dependency Update**: Updated tsvesync dependency to 1.3.0 for enhanced session management
- **📝 Documentation**: Comprehensive release notes including all enhancements from 1.2.0 onwards
- **⚡ Performance**: Optimized token refresh logic for better performance and reliability

### Technical Details
- **🔧 Advanced Token Lifecycle**: Proactive refresh ensures tokens never expire during operation
- **🎯 Progressive Buffer Strategy**: Smart refresh timing based on token lifetime for optimal reliability
- **📈 Enhanced Error Handling**: Comprehensive try/finally blocks for robust operation
- **🔄 State Coordination**: Prevents concurrent refresh operations with proper synchronization
- **🛡️ Authentication Stability**: Eliminates authentication interruptions during long-running sessions

### Summary of All Features from v1.2.0 onwards

#### Session Management & Authentication (v1.2.0-1.3.0)
- **💾 Complete Session Persistence**: Sessions survive across Homebridge restarts
- **⏰ Enhanced Proactive Token Refresh**: Advanced refresh before JWT expiration (NEW in 1.3.0)
- **🔐 Automatic Recovery**: Seamless fallback when persisted sessions are invalid
- **📊 JWT Integration**: Full token lifecycle management with expiration tracking
- **🛡️ Secure Storage**: Protected session storage in tsvesync subdirectory
- **🚀 Faster Startup**: Reduced authentication overhead via session reuse

#### Speed Control & HomeKit Integration (v1.2.0)
- **🎛️ Advanced Speed Control**: Dynamic support for 3-4+ speed air purifiers
- **🌙 Sleep Mode Integration**: Sleep mode as first notch on HomeKit slider
- **🎯 Precision Mapping**: Accurate percentage-to-speed conversions
- **📱 Enhanced UX**: Improved slider positions and speed transitions
- **🔄 Smart Notch System**: Automatic adjustment based on device capabilities

Full changelog: https://github.com/mickgiles/homebridge-tsvesync/blob/main/CHANGELOG.md

## 1.2.2 (2025-09-04)

### Added
- **⏰ Proactive Token Refresh**: Intelligent JWT token refresh before expiration
  - **🔄 Smart Scheduling**: Automatically schedules token refresh before JWT expiry
  - **📊 Accurate Lifetime Tracking**: Uses actual token issuance time (iat) for precise calculations
  - **🎯 Dynamic Buffer Calculation**: Refresh buffer is earlier of 5 days or 10% of token lifetime
  - **🔔 Token Change Integration**: Leverages tsvesync's onTokenChange callback system
  - **🧹 Clean Shutdown**: Properly clears refresh timer on platform shutdown
  - **🛡️ Uninterrupted Service**: Prevents authentication failures during long-running sessions

### Changed
- **📚 Dependency Update**: Updated tsvesync dependency to 1.2.2
- **📝 Documentation**: Comprehensive release notes including all changes from 1.2.0 onwards

### Technical Details
- **🔧 Token Lifecycle**: Proactive refresh ensures tokens never expire during operation
- **📈 Reliability**: Eliminates VeSync connectivity interruptions from expired tokens
- **🎯 Buffer Strategy**: Minimum 1 day, maximum 5 days refresh buffer for optimal timing
- **⚡ Background Operation**: Token refresh happens seamlessly without service interruption

### Summary of All Features from v1.2.0 onwards

#### Session Management & Authentication (v1.2.0-1.2.2)
- **💾 Complete Session Persistence**: Sessions survive across Homebridge restarts
- **⏰ Proactive Token Refresh**: Automatic refresh before JWT expiration (NEW in 1.2.2)
- **🔐 Automatic Recovery**: Seamless fallback when persisted sessions are invalid
- **📊 JWT Integration**: Full token lifecycle management with expiration tracking
- **🛡️ Secure Storage**: Protected session storage in tsvesync subdirectory
- **🚀 Faster Startup**: Reduced authentication overhead via session reuse

#### Speed Control & HomeKit Integration (v1.2.0)
- **🎛️ Advanced Speed Control**: Dynamic support for 3-4+ speed air purifiers
- **🌙 Sleep Mode Integration**: Sleep mode as first notch on HomeKit slider
- **🎯 Precision Mapping**: Accurate percentage-to-speed conversions
- **📱 Enhanced UX**: Improved slider positions and speed transitions
- **🔄 Smart Notch System**: Automatic adjustment based on device capabilities

Full changelog: https://github.com/mickgiles/homebridge-tsvesync/blob/main/CHANGELOG.md

## 1.2.1 (2025-09-04)

### Changed
- **📦 Re-release**: Version 1.2.1 re-release with comprehensive release notes from 1.2.0
- **📝 Documentation**: Enhanced release documentation and changelog formatting
- **🔄 Version Alignment**: Synchronized version numbers across tsvesync and homebridge-tsvesync
- **📚 Dependency Update**: Updated tsvesync dependency to 1.2.1

## 1.2.0 (2025-09-04)

### Added
- **💾 Session Persistence**: Comprehensive session management for improved reliability
  - **🔐 Automatic Session Recovery**: VeSync sessions now persist across Homebridge restarts
  - **📊 Token Lifecycle Management**: JWT token expiration tracking and automatic refresh
  - **🛡️ Secure Storage**: Sessions stored with appropriate file permissions in tsvesync subdirectory
  - **🚀 Faster Startup**: Reduced authentication overhead on Homebridge startup via session reuse
  - **🔄 Seamless Recovery**: Automatic fallback to fresh login when persisted sessions are invalid

- **🎛️ Advanced Speed Control**: Enhanced speed control for air purifiers with 4+ manual speeds
  - **🌟 Multi-Speed Support**: Dynamic step calculation for devices with 4+ manual speed levels
  - **🎯 Precision Mapping**: Better percentage-to-speed conversion for devices with varying speed counts
  - **🔄 Smart Notch System**: Automatic adjustment of speed notches based on device capabilities
  - **📱 Improved HomeKit UX**: More accurate slider positions and speed transitions

### Enhanced
- **🔧 API Integration**: Enhanced tsvesync library integration with session management
  - **📦 Library Update**: Updated to tsvesync 1.2.0 with session persistence capabilities
  - **🔗 Session Callbacks**: Integration with tsvesync session store for automatic persistence
  - **⚡ Performance**: Reduced API calls through intelligent session reuse
  - **🛡️ Reliability**: Better handling of authentication failures with automatic recovery

- **🌙 Sleep Mode Control**: Refined sleep mode speed control logic
  - **🎛️ Dynamic Step Calculation**: Speed steps now adjust based on maximum device speeds (20% vs 25%)
  - **🎯 Better Speed Mapping**: More accurate conversion between HomeKit percentages and device speeds
  - **🔄 Consistent Behavior**: Unified speed control logic across all sleep-capable devices
  - **📱 UI Responsiveness**: Improved HomeKit characteristic updates during sleep mode transitions

### Fixed
- **🔧 Speed Control Accuracy**: Enhanced speed control precision for various device configurations
  - **📊 Speed Calculation**: Fixed percentage calculation for devices with 4+ manual speeds
  - **🎛️ Notch Mapping**: Improved notch-to-speed conversion with proper boundary checking
  - **🔄 State Synchronization**: Better synchronization between device state and HomeKit display
  - **🛡️ Edge Case Handling**: Enhanced handling of speed edge cases and boundary conditions

### Technical Details
- **🏗️ Session Architecture**: Complete integration with tsvesync 1.2.0 session management system
- **🔧 FileSessionStore**: Dedicated session storage in ~/.homebridge/tsvesync/session.json
- **📊 JWT Integration**: Automatic JWT token expiration tracking and session validation
- **🎛️ Speed Algorithm**: Enhanced speed calculation algorithms for multi-speed device support
- **🔄 Promise Coordination**: Better coordination with tsvesync library's promise-based login system

### Migration Notes
- **🚀 Automatic Enhancement**: Session persistence activates automatically after Homebridge restart
- **📁 New Storage**: Session files stored in new tsvesync subdirectory under Homebridge storage path
- **🔄 Backward Compatible**: All existing functionality preserved with enhanced capabilities
- **✅ No Configuration**: No configuration changes required - enhancements work automatically
- **🔧 Dependency Update**: tsvesync library automatically updated to version 1.2.0

## 1.1.2 (2025-09-03)

### Enhanced
- **🌙 Advanced Sleep Mode Speed Control**: Significantly improved HomeKit sleep mode integration
  - **🎯 Sleep as First Notch**: Sleep mode now appears as the first position (25%) on HomeKit speed slider for supported devices
  - **🎛️ Better Speed Mapping**: Enhanced speed control with 25%/50%/75%/100% positions for intuitive user control
  - **🔄 Smart Mode Transitions**: Automatic manual mode switching when adjusting speeds from sleep mode
  - **📱 Immediate UI Feedback**: Instant HomeKit characteristic updates for responsive user experience
  - **🛡️ Error Recovery**: Comprehensive error handling with state reversion on API failures

- **⚡ Performance Optimizations**: Streamlined speed control logic for better performance
  - **🔧 Consolidated Code**: Refactored speed conversion methods for improved maintainability
  - **📊 Efficient Calculations**: Optimized percentage-to-speed and speed-to-percentage conversions
  - **🎯 Reduced Complexity**: Simplified conditional logic while maintaining full functionality
  - **💾 Memory Efficiency**: Better resource utilization with consolidated helper methods

### Fixed
- **🌪️ Enhanced Speed Restoration**: Improved device speed handling across all air purifier models
  - **🎛️ Sleep Mode Detection**: Better detection and handling of sleep mode state transitions
  - **🔄 Mode Synchronization**: Improved synchronization between device mode and HomeKit display
  - **📱 Slider Accuracy**: More accurate speed slider positions for devices with sleep mode support
  - **🛡️ State Consistency**: Enhanced state management to prevent speed control conflicts

### Technical Details
- **🏗️ Refactored Architecture**: Consolidated speed calculation methods for better code organization
- **🎯 Feature Detection**: Enhanced hasFeature('sleep_mode') integration for dynamic behavior
- **🔧 Method Optimization**: Streamlined percentageToSpeed() and speedToPercentage() methods
- **📊 Improved Mapping**: Better notch-based speed mapping with rounding for discrete positions
- **🛡️ Enhanced Validation**: Improved input validation and boundary checking for speed values

### Affected Devices
- **Sleep Mode Devices**: Air purifiers with sleep mode support now have enhanced speed control
- **All Air Purifiers**: Benefit from optimized speed conversion logic and better performance
- **Core/Vital/LAP Series**: Improved HomeKit integration with consistent speed control behavior

### Migration Notes
- **🚀 Automatic Enhancement**: Speed control improvements activate automatically after Homebridge restart
- **📱 HomeKit Changes**: Supported devices will show sleep mode as first notch on speed slider
- **🔄 Backward Compatible**: All existing functionality preserved with enhanced capabilities
- **✅ No Configuration**: No configuration changes required - enhancements work automatically

### Dependencies
- **📦 tsvesync**: Updated to 1.1.2 for synchronized release versioning

## 1.1.1 (2025-08-30)

### Improved
- **⚡ Enhanced On/Off Responsiveness**: Significantly improved HomeKit control responsiveness
  - **🎯 Instant UI Feedback**: HomeKit characteristics now update immediately when on/off commands are issued
  - **⏳ Background Processing**: API calls are processed in the background while users see immediate state changes
  - **🛡️ Error Recovery**: Failed API calls now properly revert HomeKit state to maintain consistency
  - **📱 Better UX**: Users experience near-instantaneous response when toggling devices on/off in the Home app

- **🔧 Enhanced Speed Restoration**: Improved device speed handling when turning devices back on
  - **🌪️ Air131 Support**: Air131 devices now properly restore their previous speed setting when turned on
  - **⚡ All Device Types**: Enhanced speed restoration logic for all air purifier models
  - **🎛️ Speed Preservation**: Device speed settings are maintained and restored correctly after power cycling

### Fixed
- **🧪 Test Environment Compatibility**: Fixed setPrimaryService() calls in testing environments
  - **✅ Test Safety**: Added proper function existence check before calling setPrimaryService()
  - **🔧 Development**: Ensures compatibility across different testing and development environments
  - **🛡️ Defensive Coding**: Prevents errors when service methods are not available

### Technical Details
- **📦 Immediate State Updates**: Uses updateCharacteristic() for instant HomeKit feedback
- **🔄 Error Handling**: Comprehensive error recovery with state reversion on API failures
- **⚡ Performance**: Optimized to reduce perceived latency while maintaining API rate limits
- **🎯 Device State**: Enhanced device state persistence for consistent behavior across restarts

### Affected Devices
- **All Air Purifiers**: Improved on/off responsiveness and speed restoration
- **Air131 Models**: Enhanced speed restoration logic with immediate characteristic updates
- **Core Series**: Better HomeKit interaction consistency with instant feedback

## 1.1.0 (2025-08-29)

### Added
- **🆕 Separated Air Quality Sensors**: Air quality sensors now appear as independent HomeKit accessories
  - **📦 New AirQualitySensorAccessory Class**: Dedicated accessory for air quality monitoring with PM2.5 and PM10 support
  - **🎯 Core300S, Core400S, Core600S**: Air quality sensors appear as separate tiles in HomeKit for better organization
  - **📊 EPA AQI Standards**: Air quality levels calculated using official EPA Air Quality Index thresholds
  - **🔧 Smart Detection**: Automatic PM2.5 and PM10 characteristic setup based on device capabilities
  - **🌟 Better UX**: Air purifier controls and air quality readings are now clearly separated in HomeKit

### Fixed
- **🎯 Core Series Filter Life Detection**: Enhanced filter life detection for all Core series air purifiers
  - **✅ Core300S Filter Support**: Core300S devices now properly display filter life percentage in HomeKit
  - **🔧 Pattern Matching**: Improved device type detection to catch variants like "300S", "200S", "400S", "600S"
  - **🛡️ Defensive Logic**: Robust filter detection ensures all Core series devices get filter characteristics
  - **📱 HomeKit Integration**: Filter maintenance notifications now work correctly for all Core series models

- **🚨 Critical Air Quality Bug Fix**: Resolved phantom air quality services on devices without sensors
  - **⚡ hasFeature() Fix**: Fixed API proxy wrapping causing hasFeature() to return Promise instead of boolean
  - **🎯 Core200S Specific**: Core200S and LAP-C201S/C202S no longer show phantom air quality services
  - **🔧 Bypass Logic**: Moved bypass check before async wrapper to prevent Promise wrapping of sync methods
  - **✅ Accurate Detection**: Only devices with actual air quality sensors now show AQ characteristics

### Improved
- **🔇 Reduced Log Verbosity**: Changed excessive info logging to debug level for cleaner operation
  - **📊 Debug Level**: Feature detection, device type analysis, and configuration details moved to debug
  - **⚡ Performance**: Reduced log noise during normal operation while maintaining troubleshooting capability
  - **🎯 Focused Logging**: Important warnings and errors remain visible, routine operations moved to debug

- **🏗️ Enhanced HomeKit Service Architecture**: Proper service hierarchy for better HomeKit display
  - **🎯 Primary Service**: AirPurifier service marked as primary to show controls instead of info page
  - **🔗 Linked Services**: Air quality sensors properly linked to maintain service relationships
  - **📱 HomeKit UX**: All air purifiers now show control interface when tapped in Home app

### Technical Details
- **🔧 API Proxy Enhancement**: Improved rate limiting with proper bypass handling for sync methods
- **📦 Device Factory**: Enhanced device classification and feature detection logic
- **🎛️ Service Management**: Comprehensive service setup with primary/secondary hierarchy
- **🔍 Enhanced Logging**: Detailed debugging information available when needed

### Affected Devices
- **Core Series**: Core200S, Core300S, Core400S, Core600S - improved filter detection and service setup
- **LAP Series**: LAP-C201S, LAP-C202S, LAP-C301S, LAP-C401S, LAP-C601S - fixed phantom AQ services
- **All Air Purifiers**: Better HomeKit service hierarchy and consistent behavior across models

### Migration Notes
- **🚀 Automatic Upgrade**: Changes take effect after Homebridge restart, no configuration needed
- **📱 HomeKit Changes**: Air quality sensors will appear as separate accessories for supported devices
- **🔄 Backward Compatible**: All existing functionality preserved with enhanced capabilities
- **✅ Verification**: Check that Core series devices show filter life and separated AQ sensors work correctly

### Dependencies
- **📦 tsvesync**: Updated to 1.1.0 for synchronized release versioning

## 1.0.123 (2025-08-29)

### Fixed
- **🎯 Core300S HomeKit Controls Display**: Fixed Core300S showing info page instead of control settings in HomeKit
  - **✅ Primary Service**: AirPurifier service now marked as primary service to ensure control display instead of info page
  - **🔗 Service Hierarchy**: AirQualitySensor service properly linked as secondary service to primary AirPurifier service
  - **🔧 Technical Implementation**: Uses setPrimaryService(true) for AirPurifier and addLinkedService() for AirQualitySensor
  - **📱 HomeKit Impact**: Core300S devices now properly display controls (fan speed, mode, etc.) when tapped in Home app
  - **🛡️ Universal Fix**: Primary service configuration applied to all air purifiers for consistent HomeKit behavior

### Improved
- **🔍 Enhanced Service Configuration Logging**: Added comprehensive logging for service hierarchy setup debugging
  - **📊 Primary Service Tracking**: All primary service assignments now logged with device name context for troubleshooting
  - **🎯 Linked Service Detection**: Service linking operations logged with clear success confirmation messages  
  - **⚠️ Clear Notifications**: Service configuration now clearly logged for all air purifiers with hierarchy details
  - **🔧 Configuration Verification**: Detailed logging confirms proper service setup and linking for debugging purposes

### Technical Details
- **🏗️ HomeKit Service Architecture**: Proper primary/secondary service hierarchy implementation following HomeKit best practices
- **🔄 Service Priority**: AirPurifier service always set as primary to ensure control interface is displayed first
- **⚖️ Linked Services**: AirQualitySensor and other secondary services properly linked to maintain service relationships
- **📝 Code Enhancement**: Added clear comments explaining the critical nature of primary service configuration

### Affected Devices
- **Core300S** (primary fix target) - now shows controls instead of info page when tapped in HomeKit
- **All Air Purifiers** - benefit from consistent primary service configuration and proper service hierarchy
- **Multi-Service Devices** - proper service linking ensures all services remain accessible with correct display priority

### Migration Notes
- **🚀 Automatic Fix**: Service hierarchy changes will take effect automatically after Homebridge restart
- **📱 HomeKit Changes**: Core300S and other air purifiers should now show control interface when tapped in Home app
- **🔄 No Configuration**: Changes are automatic - no configuration updates required
- **✅ Verification**: Check air purifier devices in Home app to confirm control interface is displayed instead of info page

### Dependencies
- **📦 tsvesync**: Updated from 1.0.122 to 1.0.123 for synchronized release versioning

## 1.0.122 (2025-08-29)

### Fixed
- **🎯 Core300S HomeKit Tile Missing Features**: Fixed Core300S filter characteristics and mode settings not appearing in HomeKit tile
  - **✅ Filter Characteristics**: Filter characteristics now always registered for all air purifiers (matching reference implementation)
  - **🔧 Mode Switch**: Core300S auto/manual mode switcher now appears in HomeKit by using proper unified approach
  - **🛡️ Universal Setup**: Changed from conditional filter setup to always-register approach for all air purifiers
  - **📱 HomeKit Impact**: Core300S devices now properly display filter life percentage and auto/manual mode toggle in Home app
  - **🔧 Technical Fix**: Uses getCharacteristic() approach that auto-adds characteristics (like proven reference plugins)

### Improved
- **🔍 Enhanced Logging**: Added comprehensive device feature detection logging for troubleshooting
  - **📊 Feature Detection**: All hasFeature() calls now logged with device type context for debugging
  - **🎯 Device Classification**: Enhanced logging for auto mode support detection and characteristic setup
  - **⚠️ Clear Notifications**: Core300S auto mode enablement now clearly logged with success confirmation
  - **🔧 Characteristic Tracking**: Detailed logging confirms filter characteristics are registered for all air purifiers

### Technical Details
- **🏗️ Reference-Based Implementation**: Aligned implementation with proven working homebridge-levoit-air-purifier approach
- **🔄 Always-Register Pattern**: Filter characteristics now registered for ALL air purifiers without conditional logic
- **⚖️ Unified Logic**: Core300S now gets both auto and manual mode support explicitly enabled
- **📝 Simplified Code**: Removed complex conditional handling in favor of proven always-register approach

### Affected Devices
- **Core300S** (primary fix target) - filter and mode characteristics now reliably appear in HomeKit tile
- **All Air Purifiers** - benefit from unified filter characteristic setup approach
- **Core200S** - continues to work with enhanced logging and consistent setup

### Migration Notes
- **🚀 Automatic Fix**: Filter and mode characteristics will appear automatically after Homebridge restart
- **📱 HomeKit Changes**: Core300S tiles should now show filter life percentage and auto/manual mode toggle
- **🔄 No Configuration**: Changes are automatic - no configuration updates required
- **✅ Verification**: Check Core300S devices in Home app to confirm filter and mode controls are visible

### Dependencies
- **📦 tsvesync**: Updated from 1.0.121 to 1.0.122 for synchronized release versioning

## 1.0.121 (2025-08-29)

### Fixed
- **🔧 Simplified HomeKit Characteristic Setup**: Completely overhauled characteristic configuration based on working reference plugin analysis
  - **✅ Filter Characteristics**: Now using getCharacteristic() directly which auto-adds characteristics if missing (like reference plugin)
  - **🎯 Removed Complex Logic**: Eliminated special remove/re-add logic for Core200S and Core300S rotation speed handling
  - **🛡️ Unified Approach**: All devices now use the same simplified characteristic setup approach
  - **📱 HomeKit Impact**: Core300S filter and mode display issues resolved through simplified implementation
  - **🔧 Technical Enhancement**: Based on analysis of proven working homebridge-levoit-air-purifier plugin

### Improved  
- **🔍 Characteristic Configuration**: Streamlined approach eliminates duplicate and complex characteristic handling
  - **📊 Direct getCharacteristic**: Uses getCharacteristic() calls that auto-add characteristics (matching reference plugin)
  - **🎯 Consistent Setup**: Removed device-specific characteristic removal/addition logic
  - **⚠️ Simplified Code**: Eliminated complex conditional handling for different device models
  - **🔧 Proven Approach**: Aligns implementation with workin