homebridge-tsvesync 1.0.67 → 1.0.70

package/.clinerules

@@ -0,0 +1,145 @@
+# Cline Rules for homebridge-tsvesync
+
+## Project Patterns
+
+### Code Organization
+- TypeScript files use `.ts` extension
+- Test files are placed in `__tests__` directory with `.test.ts` extension
+- Device-specific accessories are in `accessories/` directory with `.accessory.ts` suffix
+- Type definitions are in `types/` directory
+- Utility functions are in `utils/` directory
+
+### Naming Conventions
+- Classes use PascalCase (e.g., `BaseAccessory`, `HumidifierAccessory`)
+- Interfaces use PascalCase with descriptive names (e.g., `DeviceCapabilities`)
+- Methods and variables use camelCase
+- Constants use UPPER_SNAKE_CASE for truly constant values
+- File names use kebab-case for general files, but camelCase for class files
+
+### Code Style
+- Use 2-space indentation
+- Prefer single quotes for strings
+- Use semicolons at the end of statements
+- Use explicit type annotations for function parameters and return types
+- Use async/await for asynchronous operations
+- Prefer interfaces over type aliases for object types
+- Use optional chaining and nullish coalescing when appropriate
+
+### Error Handling
+- Use try/catch blocks for API operations
+- Log errors with appropriate context
+- Implement retry mechanisms with exponential backoff
+- Provide meaningful error messages for debugging
+- Handle specific error types differently (network errors, auth errors, etc.)
+
+### Logging
+- Use the plugin's logger instance, not console.log
+- Include device context in log messages
+- Use appropriate log levels (debug, info, warn, error)
+- Redact sensitive information in logs
+- Include operation context in log messages
+
+### File Editing Practices
+- Always commit working code before making significant changes
+- Make small, incremental changes rather than large rewrites
+- Initialize all properties in constructors with default values
+- Be cautious when modifying interface definitions
+- Validate type casting with explicit checks
+- Use version control for recovery if files become corrupted
+- See memory-bank/file-editing-guidelines.md for detailed guidelines
+
+## Implementation Patterns
+
+### Device Handling
+- All device accessories extend `BaseAccessory`
+- Device-specific logic is implemented in subclasses
+- Common functionality is in the base class
+- Use composition of interfaces for device capabilities
+- Map device states to HomeKit characteristics
+
+### API Communication
+- Use the tsvesync library for API calls
+- Implement rate limiting for API requests
+- Handle authentication token refresh
+- Use exponential backoff for failed requests
+- Cache device states to reduce API calls
+
+### State Management
+- Update device states periodically based on configuration
+- Persist device state in accessory context
+- Update HomeKit characteristics when device state changes
+- Handle state synchronization between HomeKit and VeSync
+
+### Testing
+- Use Jest for unit tests
+- Mock external dependencies
+- Test error handling paths
+- Use descriptive test names
+- Group related tests in describe blocks
+
+## Development Workflow
+
+### Building
+- Run `npm run build` to compile TypeScript to JavaScript
+- Output goes to `dist/` directory
+- Clean build directory before compilation
+
+### Testing
+- Run `npm test` to execute all tests
+- Run `npm run test:watch` for development
+- Run `npm run test:coverage` to check test coverage
+
+### Debugging
+- Enable debug mode in plugin configuration
+- Check Homebridge logs for detailed information
+- Use VS Code debugger with appropriate launch configuration
+- Test with real devices when possible
+
+### Deployment
+- Update version in package.json
+- Update CHANGELOG.md with version changes
+- Run tests before publishing
+- Use `npm publish` to publish to npm registry
+
+## User Support Patterns
+
+### Configuration Help
+- Guide users through config.json setup
+- Provide examples for different device types
+- Explain exclusion options clearly
+- Document all configuration parameters
+
+### Troubleshooting
+- Ask for debug logs when helping users
+- Check for common configuration issues first
+- Verify device compatibility
+- Check for network/connectivity issues
+- Verify VeSync account credentials
+
+### Feature Requests
+- Evaluate feasibility based on API capabilities
+- Consider HomeKit limitations
+- Prioritize based on user impact
+- Document in GitHub issues
+
+## Project-Specific Notes
+
+### VeSync API Quirks
+- Different device models have inconsistent API implementations
+- Some devices require specific mode settings before other operations
+- API rate limiting can be unpredictable
+- Authentication tokens expire after 1 hour
+- Some device features are not exposed via the API
+
+### HomeKit Limitations
+- Limited set of predefined accessory types
+- Restricted characteristic value ranges
+- No custom characteristics without using HAP-NodeJS directly
+- Limited support for complex device features
+
+### Common Issues
+- Rate limiting during device discovery with many devices
+- State synchronization delays during high activity
+- Token refresh failures during network interruptions
+- Mapping complex device modes to HomeKit characteristics
+- File corruption during complex edits (see file-editing-guidelines.md)

package/CHANGELOG.md

@@ -1,37 +1,59 @@
-# Change Log
+# Changelog
+
+## 1.0.68 (2025-02-28)
+
+### Added
+- API quota management system to prevent exceeding VeSync's daily request limits
+- Configurable quota buffer percentage and priority methods in config.schema.json
+- Automatic device count detection for quota calculation
+- Graceful degradation when quota limits are reached
+- High-priority methods that will still work even when quota is exceeded
+
+### Changed
+- Improved error handling for API quota errors
+- Limited device state sync retries to 3 attempts to avoid excessive API calls
+- Enhanced logging for quota-related issues
+- Updated config schema with new quota management options
 
-# 1.0.33 (2025-01-04)
 ### Fixed
-- Fixed issue where devices were not being refreshed and polling too frequently
+- Fixed issue with API quota errors causing plugin instability
+- Improved handling of null responses from API calls due to quota limits
+
+## 1.0.67 (2025-01-15)
+
+### Added
+- Support for OasisMist1000S humidifier
+
+### Changed
+- Improved error handling for API rate limiting
+- Enhanced token refresh mechanism
 
-# 1.0.31 (2025-01-04)
 ### Fixed
-- Fixed issue where login token was not being refreshed
+- Fixed issue with fan speed control on certain models
+- Improved logging for troubleshooting
+
+## 1.0.66 (2024-12-10)
+
+### Added
+- Support for Superior6000S humidifier
+
+### Changed
+- Improved device exclusion logic
+- Enhanced error recovery for network failures
+- Updated tsvesync dependency to v1.0.64
 
-# 1.0.27 (2025-01-02)
 ### Fixed
-- Fixed invalid speed setting issues for air purifiers, fans, and humidifiers
-  - Speed 0 now properly turns off the device instead of attempting to set an invalid speed
-  - Air purifiers and fans now correctly map HomeKit's 0-100% to device speeds 1-5
-  - Humidifiers now correctly map HomeKit's 0-100% to device speeds 1-9
+- Fixed connection stability issues
+
+## 1.0.65 (2024-11-05)
 
 ### Added
-- Added informative logging for all device control actions
-  - Power state changes
-  - Speed/level adjustments
-  - Mode changes
-  - Child lock toggles
-  - Swing mode changes
-  - Rotation direction changes
-  - Target humidity adjustments
-- Added support for ESO15-TB dual outdoor outlets
-  - Power state control for both outlets
-  - Energy monitoring capabilities
-  - Power consumption tracking
-  - Voltage monitoring
-- Added support for ESWL01, ESWL03, and ESWD16 wall switches
+- Support for EverestAir air purifier
 
 ### Changed
-- Improved error handling for device control operations
-- Enhanced speed control mapping for better user experience
-- Updated humidifier mist level terminology in logs for clarity 
+- Improved handling of device reconnection
+- Enhanced logging for API communication
+- Optimized polling frequency
+
+### Fixed
+- Fixed issues with characteristic updates

package/config.schema.json

@@ -2,7 +2,7 @@
   "pluginAlias": "TSVESyncPlatform",
   "pluginType": "platform",
   "singular": true,
-  "headerDisplay": "Homebridge plugin for VeSync devices including Levoit air purifiers, humidifiers, and Etekcity smart outlets.",
+  "headerDisplay": "Homebridge plugin for VeSync devices including Levoit air purifiers humidifiers and Etekcity smart outlets.",
   "footerDisplay": "For help please visit the [GitHub repository](https://github.com/mickgiles/homebridge-tsvesync).",
   "schema": {
     "type": "object",
@@ -10,229 +10,170 @@
       "name": {
         "title": "Name",
         "type": "string",
-        "required": true,
-        "default": "TSVESync"
+        "default": "TSVESync",
+        "required": true
       },
       "username": {
-        "title": "Email",
+        "title": "VeSync Username",
         "type": "string",
         "required": true,
         "description": "Your VeSync account email address"
       },
       "password": {
-        "title": "Password",
+        "title": "VeSync Password",
         "type": "string",
         "required": true,
-        "description": "Your VeSync account password",
-        "typeahead": {
-          "source": []
-        }
+        "description": "Your VeSync account password"
       },
       "updateInterval": {
         "title": "Update Interval",
         "type": "integer",
-        "minimum": 60,
-        "maximum": 900,
-        "default": 300,
-        "required": false,
-        "description": "How often to update device states (in seconds). Default is 300 seconds (5 minutes). Minimum is 60 seconds to avoid API rate limits."
+        "default": 30,
+        "minimum": 10,
+        "maximum": 600,
+        "description": "How often to update device status (in seconds)"
       },
       "debug": {
-        "title": "Debug Logging",
+        "title": "Debug Mode",
         "type": "boolean",
-        "required": false,
         "default": false,
-        "description": "Enable debug logging for troubleshooting"
+        "description": "Enable debug logging"
+      },
+      "apiUrl": {
+        "title": "API URL",
+        "type": "string",
+        "description": "Custom VeSync API URL (advanced users only)"
       },
       "exclude": {
-        "title": "Device Exclusions",
+        "title": "Exclude Devices",
         "type": "object",
-        "required": false,
-        "description": "Configure which devices to exclude from HomeKit",
         "properties": {
           "type": {
-            "title": "Exclude Device Types",
+            "title": "Exclude by Type",
             "type": "array",
             "items": {
-              "title": "Device Type",
               "type": "string",
-              "enum": ["fan", "outlet", "switch", "bulb", "purifier", "humidifier"]
+              "enum": [
+                "fan",
+                "outlet",
+                "switch",
+                "bulb",
+                "humidifier",
+                "purifier"
+              ]
             },
             "uniqueItems": true,
-            "description": "Select device types to exclude from HomeKit",
-            "default": []
+            "description": "Exclude devices by type"
           },
           "model": {
-            "title": "Exclude Device Models",
+            "title": "Exclude by Model",
             "type": "array",
             "items": {
-              "title": "Device Model",
-              "type": "string",
-              "placeholder": "Core300S"
+              "type": "string"
             },
             "uniqueItems": true,
-            "description": "Enter device models to exclude (e.g., Core300S, LV600S, ESL100)",
-            "default": []
+            "description": "Exclude devices by model (e.g., 'Core300S', 'LV600S')"
           },
           "name": {
             "title": "Exclude by Name",
             "type": "array",
             "items": {
-              "title": "Device Name",
-              "type": "string",
-              "placeholder": "Living Room Light"
+              "type": "string"
             },
             "uniqueItems": true,
-            "description": "Enter exact device names to exclude (case-sensitive)",
-            "default": []
+            "description": "Exclude devices by exact name match"
           },
           "namePattern": {
             "title": "Exclude by Name Pattern",
             "type": "array",
             "items": {
-              "title": "Pattern",
-              "type": "string",
-              "placeholder": "Bedroom.*"
+              "type": "string"
             },
             "uniqueItems": true,
-            "description": "Enter regex patterns to match device names for exclusion (e.g., 'Bedroom.*' to exclude all bedroom devices)",
-            "default": []
+            "description": "Exclude devices by name pattern (regex)"
           },
           "id": {
-            "title": "Exclude by Device ID",
+            "title": "Exclude by ID",
             "type": "array",
             "items": {
-              "title": "Device ID",
-              "type": "string",
-              "placeholder": "cid123456"
+              "type": "string"
             },
             "uniqueItems": true,
-            "description": "Enter device IDs (cid/uuid) to exclude",
-            "default": []
+            "description": "Exclude devices by ID (cid/uuid)"
           }
         }
       },
       "retry": {
-        "title": "API Retry Configuration",
+        "title": "Retry Configuration",
         "type": "object",
-        "required": false,
-        "description": "Configure retry behavior for API calls",
         "properties": {
           "maxRetries": {
             "title": "Maximum Retries",
             "type": "integer",
+            "default": 3,
             "minimum": 1,
             "maximum": 10,
-            "default": 3,
-            "description": "Maximum number of retry attempts for failed API calls"
+            "description": "Maximum number of retry attempts for failed operations"
           },
           "initialDelay": {
-            "title": "Initial Retry Delay",
+            "title": "Initial Delay",
             "type": "integer",
-            "minimum": 1000,
-            "maximum": 10000,
             "default": 2000,
-            "description": "Initial delay between retries in milliseconds"
+            "minimum": 500,
+            "maximum": 10000,
+            "description": "Initial delay before first retry (in milliseconds)"
           },
           "maxDelay": {
-            "title": "Maximum Retry Delay",
+            "title": "Maximum Delay",
             "type": "integer",
-            "minimum": 5000,
-            "maximum": 30000,
             "default": 10000,
-            "description": "Maximum delay between retries in milliseconds"
+            "minimum": 1000,
+            "maximum": 60000,
+            "description": "Maximum delay between retries (in milliseconds)"
           }
         }
-      }
-    }
-  },
-  "layout": [
-    "name",
-    "username",
-    "password",
-    "updateInterval",
-    "debug",
-    {
-      "key": "exclude",
-      "type": "section",
-      "title": "Device Exclusions",
-      "expandable": true,
-      "expanded": false,
-      "orderable": false,
-      "items": [
-        {
-          "key": "exclude.type",
-          "type": "array",
-          "title": "Device Types to Exclude",
-          "buttonText": "Add Device Type",
-          "items": [
-            {
-              "key": "exclude.type[]",
-              "type": "select"
-            }
-          ]
-        },
-        {
-          "key": "exclude.model",
-          "type": "array",
-          "title": "Device Models to Exclude",
-          "buttonText": "Add Device Model",
-          "items": [
-            {
-              "key": "exclude.model[]",
-              "type": "string"
-            }
-          ]
-        },
-        {
-          "key": "exclude.name",
-          "type": "array",
-          "title": "Device Names to Exclude",
-          "buttonText": "Add Device Name",
-          "items": [
-            {
-              "key": "exclude.name[]",
-              "type": "string"
-            }
-          ]
-        },
-        {
-          "key": "exclude.namePattern",
-          "type": "array",
-          "title": "Name Patterns to Exclude",
-          "buttonText": "Add Name Pattern",
-          "items": [
-            {
-              "key": "exclude.namePattern[]",
-              "type": "string"
-            }
-          ]
-        },
-        {
-          "key": "exclude.id",
-          "type": "array",
-          "title": "Device IDs to Exclude",
-          "buttonText": "Add Device ID",
-          "items": [
-            {
-              "key": "exclude.id[]",
+      },
+      "quotaManagement": {
+        "title": "API Quota Management",
+        "type": "object",
+        "properties": {
+          "enabled": {
+            "title": "Enable Quota Management",
+            "type": "boolean",
+            "default": true,
+            "description": "Enable API quota management to prevent exceeding VeSync's daily limits"
+          },
+          "bufferPercentage": {
+            "title": "Buffer Percentage",
+            "type": "integer",
+            "default": 95,
+            "minimum": 50,
+            "maximum": 100,
+            "description": "Percentage of the calculated quota to use (lower values provide more safety margin)"
+          },
+          "priorityMethods": {
+            "title": "Priority Methods",
+            "type": "array",
+            "items": {
               "type": "string"
-            }
-          ]
+            },
+            "default": [
+              "turnOn", 
+              "turnOff", 
+              "setMode", 
+              "setTargetHumidity", 
+              "setBrightness",
+              "setColorTemperature",
+              "setColor",
+              "changeFanSpeed",
+              "setOscillation",
+              "setChildLock"
+            ],
+            "uniqueItems": true,
+            "description": "API methods that will be allowed even when quota is exceeded"
+          }
         }
-      ]
-    },
-    {
-      "key": "retry",
-      "type": "section",
-      "title": "API Retry Settings",
-      "expandable": true,
-      "expanded": false,
-      "items": [
-        "retry.maxRetries",
-        "retry.initialDelay",
-        "retry.maxDelay"
-      ]
+      }
     }
-  ]
-} 
+  }
+}

package/dist/accessories/air-purifier.accessory.d.ts

@@ -5,6 +5,7 @@ import { DeviceCapabilities, VeSyncAirPurifier } from '../types/device.types';
 export declare class AirPurifierAccessory extends BaseAccessory {
     private readonly capabilities;
     protected readonly device: VeSyncAirPurifier;
+    private isLVSeries;
     constructor(platform: TSVESyncPlatform, accessory: PlatformAccessory, device: VeSyncAirPurifier);
     /**
      * Set up the air purifier service
@@ -18,6 +19,14 @@ export declare class AirPurifierAccessory extends BaseAccessory {
      * Update device states based on the latest details
      */
     protected updateDeviceSpecificStates(details: any): Promise<void>;
+    /**
+     * Get target state (AUTO = 0, MANUAL = 1)
+     */
+    private getTargetState;
+    /**
+     * Set target state (AUTO = 0, MANUAL = 1)
+     */
+    private setTargetState;
     /**
      * Handle set rotation speed
      */

package/dist/accessories/air-purifier.accessory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"air-purifier.accessory.d.ts","sourceRoot":"","sources":["../../src/accessories/air-purifier.accessory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE9E,qBAAa,oBAAqB,SAAQ,aAAa;IACrD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;gBAG3C,QAAQ,EAAE,gBAAgB,EAC1B,SAAS,EAAE,iBAAiB,EAC5B,MAAM,EAAE,iBAAiB;IAO3B;;OAEG;IACH,SAAS,CAAC,YAAY,IAAI,IAAI;IA0B9B;;OAEG;IACH,SAAS,CAAC,qBAAqB,IAAI,kBAAkB;IAcrD;;OAEG;cACa,0BAA0B,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BvE;;OAEG;YACW,sBAAsB;YA0BtB,SAAS;YAIT,SAAS;YAiBT,gBAAgB;CAgB/B"}
+{"version":3,"file":"air-purifier.accessory.d.ts","sourceRoot":"","sources":["../../src/accessories/air-purifier.accessory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AA0B9E,qBAAa,oBAAqB,SAAQ,aAAa;IACrD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IAC7C,OAAO,CAAC,UAAU,CAAU;gBAG1B,QAAQ,EAAE,gBAAgB,EAC1B,SAAS,EAAE,iBAAiB,EAC5B,MAAM,EAAE,iBAAiB;IAe3B;;OAEG;IACH,SAAS,CAAC,YAAY,IAAI,IAAI;IAiC9B;;OAEG;IACH,SAAS,CAAC,qBAAqB,IAAI,kBAAkB;IAcrD;;OAEG;cACa,0BAA0B,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAoDvE;;OAEG;YACW,cAAc;IAK5B;;OAEG;YACW,cAAc;IAmC5B;;OAEG;YACW,sBAAsB;YAyEtB,SAAS;YAIT,SAAS;YAmBT,gBAAgB;CA6B/B"}