Fix HTTP 422 error handling and improve status code messaging (#163)

Author: Copilot

.copilot/instructions.md

@@ -0,0 +1,261 @@
+# Copilot Instructions for Homebridge August Plugin
+
+## Repository Overview
+
+This is a Homebridge plugin that provides HomeKit integration for August and Yale smart locks. The plugin is written in TypeScript with ES modules and follows Homebridge platform patterns.
+
+**Branch Strategy**: This repository uses a beta-first development workflow where all changes must target beta branches before being merged to main. Version bumps are determined by issue labels (patch/minor/major) that must be set before assigning work to Copilot.
+
+## Architecture
+
+- **Plugin Type**: Homebridge dynamic platform plugin
+- **Language**: TypeScript with ES modules (ES2022)
+- **Runtime**: Node.js 20+ or 22+
+- **Build System**: TypeScript compiler (tsc) with bundler module resolution
+- **Testing**: Vitest with coverage support
+- **Linting**: ESLint with Antfu config and custom rules
+- **Documentation**: TypeDoc with modern theme
+- **External API**: august-yale package for August/Yale API communication
+
+## Key Files and Directories
+
+- `src/` - TypeScript source code
+  - `index.ts` - Plugin entry point that registers the platform
+  - `platform.ts` - Main platform class (AugustPlatform)
+  - `settings.ts` - Configuration interfaces and constants
+  - `devices/` - Device-specific implementations
+    - `lock.ts` - Lock mechanism implementation
+    - `device.ts` - Base device class
+  - `homebridge-ui/` - Custom UI for Homebridge Config UI X
+  - `*.test.ts` - Test files (Vitest)
+- `dist/` - Compiled JavaScript output (generated, excluded from git)
+- `config.schema.json` - Homebridge configuration schema with custom UI
+- `package.json` - Dependencies and npm scripts
+- `tsconfig.json` - TypeScript configuration (ES2022, bundler resolution)
+- `eslint.config.js` - ESLint configuration with Antfu base and custom rules
+
+## Development Workflow
+
+### Branch Strategy and PR Workflow
+
+**IMPORTANT**: All pull requests must target a beta branch first, never directly to the main branch.
+
+#### Beta Branch Requirements
+- All PRs must be directed to a branch that starts with "beta-" 
+- Beta branches should be named `beta-X.Y.Z` based on the expected version bump
+- If no appropriate beta branch exists, create one based on the next possible version:
+  - **patch** releases (bug fixes): `beta-X.Y.Z+1` (e.g., current 3.0.2 → beta-3.0.3)
+  - **minor** releases (new features): `beta-X.Y+1.0` (e.g., current 3.0.2 → beta-3.1.0) 
+  - **major** releases (breaking changes): `beta-X+1.0.0` (e.g., current 3.0.2 → beta-4.0.0)
+
+#### Required Labels
+Before assigning any issue to Copilot, the following labels **must** be set to determine the version bump:
+- `patch` - for bug fixes and minor improvements
+- `minor` - for new features and enhancements  
+- `major` - for breaking changes
+
+#### Workflow Steps
+1. Ensure proper label (patch/minor/major) is set on the issue
+2. Identify or create appropriate beta branch based on the label
+3. Target all development work and PRs to the beta branch
+4. Once beta testing is complete, merge beta branch to main for release
+
+### Building
+```bash
+npm run build         # Full build: clean + compile + copy UI files
+npm run clean         # Remove dist directory
+npm run watch         # Build + link + watch with nodemon
+```
+
+### Testing
+```bash
+npm test              # Run Vitest tests once
+npm run test:watch    # Run tests in watch mode
+npm run test-coverage # Run tests with coverage report
+```
+
+### Linting
+```bash
+npm run lint          # Check for ESLint issues
+npm run lint:fix      # Auto-fix ESLint issues
+```
+
+### Documentation
+```bash
+npm run docs          # Generate TypeDoc documentation
+npm run docs:lint     # Validate documentation (treat warnings as errors)
+npm run docs:theme    # Generate docs with default-modern theme
+```
+
+### Development Setup
+```bash
+npm run watch         # Start development with hot reload
+npm run plugin-ui     # Copy UI files to dist
+```
+
+## Coding Standards
+
+1. **TypeScript**: 
+   - ES2022 target with bundler module resolution
+   - Strict mode enabled (except noImplicitAny: false)
+   - Use ES modules with `.js` file extensions in imports
+   - Generate declaration files and source maps
+
+2. **ESLint**: 
+   - Antfu ESLint config as base
+   - Custom rules for import ordering (perfectionist)
+   - JSDoc alignment enforcement
+   - Multi-line curly braces only
+   - Consistent quote props
+   - Test-specific rules (no-only-tests)
+
+3. **Code Style**:
+   - Use 1TBS brace style with single line allowed
+   - Sort imports by type (builtin, external, internal, relative)
+   - Sort named imports and exports
+   - Use proper JSDoc formatting and alignment
+
+4. **Homebridge Patterns**:
+   - Implement DynamicPlatformPlugin interface
+   - Use proper platform registration in index.ts
+   - Follow accessory lifecycle management
+   - Implement proper logging with Homebridge logger
+   - Use PlatformAccessory for device management
+
+5. **Error Handling**: 
+   - Proper try-catch blocks for async operations
+   - Meaningful error messages with context
+   - Graceful degradation for API failures
+
+## Homebridge Specifics
+
+- **Platform Type**: Dynamic platform plugin (not accessory plugin)
+- **Platform Name**: "August" (defined in settings.ts)
+- **Plugin Name**: "homebridge-august" (must match package.json name)
+- **Configuration Schema**: Uses config.schema.json with custom UI
+- **Custom UI**: Located in src/homebridge-ui/ with custom configuration interface
+- **Platform Class**: AugustPlatform extends DynamicPlatformPlugin
+- **Device Management**: Uses PlatformAccessory for caching and state management
+- **HAP Services**: Implement LockMechanism service for smart locks
+- **Authentication**: Handle August API authentication with validation codes
+- **Rate Limiting**: Implement proper refresh/update/push rates for API calls
+
+## August/Yale Integration
+
+- **API Package**: Uses `august-yale` npm package for API communication
+- **Authentication Flow**:
+  1. User provides augustId (email/phone) and password
+  2. System sends validation code to user
+  3. User enters validation code to complete authentication
+  4. API credentials are stored and used for subsequent requests
+- **Device Types**: Support multiple lock types (August Smart Lock, Yale Assure Lock variants)
+- **State Synchronization**: Keep HomeKit state in sync with August/Yale API
+- **Polling**: Implement configurable refresh rates for device state updates
+- **Configuration**: Use credentials interface for API authentication settings
+
+## When Making Changes
+
+**CRITICAL**: Before starting any work, ensure the issue has the appropriate label (patch/minor/major) and target the correct beta branch.
+
+0. **Branch Targeting**:
+   - Never target PRs directly to main branch
+   - Always target a beta branch (beta-X.Y.Z format)
+   - Create beta branch if none exists for the expected version
+   - Use issue labels to determine version bump:
+     - `patch`: Bug fixes → beta-X.Y.Z+1
+     - `minor`: New features → beta-X.Y+1.0  
+     - `major`: Breaking changes → beta-X+1.0.0
+
+1. **Dependencies**: 
+   - Only add well-maintained dependencies
+   - Keep runtime dependencies minimal
+   - Update package.json and package-lock.json properly
+   - Consider bundle size impact
+
+2. **Breaking Changes**: 
+   - Follow semantic versioning
+   - Update CHANGELOG.md appropriately
+   - Consider migration paths for users
+   - Test with multiple Homebridge versions
+   - **Must** use `major` label and target appropriate beta-X+1.0.0 branch
+
+3. **Configuration**: 
+   - Update config.schema.json for new options
+   - Maintain backward compatibility
+   - Add proper validation and defaults
+   - Update TypeScript interfaces in settings.ts
+
+4. **Documentation**: 
+   - Update README.md for user-facing changes
+   - Add TSDoc comments for new APIs
+   - Update TypeDoc comments for generated docs
+   - Consider updating examples
+
+5. **Testing**: 
+   - Add Vitest tests for new features
+   - Mock external dependencies (August API)
+   - Test error scenarios and edge cases
+   - Maintain test coverage
+
+6. **Compatibility**: 
+   - Support Node.js 20+ and 22+
+   - Support Homebridge 1.9.0+ and 2.0.0+
+   - Test with Config UI X integration
+   - Verify ES module compatibility
+
+## Common Patterns
+
+- **RxJS**: Use reactive programming patterns where appropriate
+- **Async/Await**: Prefer async/await over Promise chains
+- **ES Modules**: Use ES module syntax with `.js` extensions in imports
+- **Interface Design**: Define clear TypeScript interfaces in settings.ts
+- **Error Handling**: Implement comprehensive error handling with meaningful messages
+- **Logging**: Use this.log with appropriate log levels (info, warn, error, debug)
+- **Device Lifecycle**: Implement proper setup/cleanup in platform methods
+- **Configuration Validation**: Validate user configuration and provide helpful error messages
+- **API Rate Limiting**: Respect August API rate limits with configurable intervals
+- **State Management**: Maintain device state consistency between API and HomeKit
+
+## Important Constants and Settings
+
+- **PLATFORM_NAME**: "August" (used in Homebridge registration)
+- **PLUGIN_NAME**: "homebridge-august" (must match package.json)
+- **Plugin Type**: "platform" (not accessory)
+- **Custom UI**: Enabled with path "./dist/homebridge-ui"
+- **Configuration**: Uses credentials and options interfaces
+- **Device Types**: Support for various August and Yale lock models
+
+## Testing Guidelines
+
+- **Framework**: Use Vitest for testing with TypeScript support
+- **Test Files**: Name test files with `.test.ts` extension in src/
+- **Coverage**: Aim for good test coverage, use `npm run test-coverage`
+- **Mocking**: Mock external dependencies, especially:
+  - August/Yale API calls
+  - Homebridge API interactions
+  - File system operations
+- **Test Categories**:
+  - Unit tests for individual functions and classes
+  - Integration tests for platform initialization
+  - Configuration validation tests
+  - Error handling tests
+- **Test Data**: Use realistic test data that matches August API responses
+- **Async Testing**: Properly test async operations and promises
+- **CI/CD**: Ensure tests run in continuous integration pipeline
+
+## Files to Avoid Modifying
+
+- `dist/` directory (generated by TypeScript compilation)
+- `node_modules/` directory (managed by npm)
+- `docs/` directory (generated by TypeDoc)
+- `.git/` directory and git metadata
+- Files listed in `.gitignore`
+- `package-lock.json` (only modify through npm commands)
+
+## Security Considerations
+
+- **Credentials**: Never log or expose user credentials
+- **API Keys**: Handle August API credentials securely
+- **Validation**: Validate all user inputs
+- **Error Messages**: Don't expose sensitive information in error messages
+- **Storage**: Store credentials securely using Homebridge storage mechanisms

src/devices/device.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { deviceBase } from './device.js'
+
+describe('deviceBase statusCode', () => {
+  // Test the statusCode method directly by mocking only what we need
+  const createMockDevice = () => {
+    // Create a minimal mock that satisfies TypeScript
+    const mockDevice = {
+      debugLog: vi.fn().mockImplementation(async () => {}),
+      debugErrorLog: vi.fn().mockImplementation(async () => {}),
+    }
+    // Bind the statusCode method to our mock device
+    const boundStatusCode = deviceBase.prototype.statusCode.bind(mockDevice)
+    return { ...mockDevice, statusCode: boundStatusCode }
+  }
+
+  it('should handle 422 status code with appropriate message', async () => {
+    const device = createMockDevice()
+    const error = { message: 'PUT failed with: 422' }
+
+    await device.statusCode('pushChanges', error)
+
+    expect(device.debugLog).toHaveBeenCalledWith(
+      'Unprocessable Entity - The request was well-formed but could not be processed. This may indicate the lock is in an invalid state or the operation is not allowed at this time, statusCode: PUT failed with: 422',
+    )
+    expect(device.debugErrorLog).not.toHaveBeenCalled()
+  })
+
+  it('should handle unknown status codes', async () => {
+    const device = createMockDevice()
+    const error = { message: 'PUT failed with: 500' }
+
+    await device.statusCode('pushChanges', error)
+
+    expect(device.debugLog).toHaveBeenCalledWith(
+      'Unknown statusCode: PUT failed with: 500, Submit Bugs Here: https://tinyurl.com/AugustYaleBug',
+    )
+    expect(device.debugErrorLog).toHaveBeenCalledWith('failed pushChanges, Error: [object Object]')
+  })
+
+  it('should handle 200 status code successfully', async () => {
+    const device = createMockDevice()
+    const error = { message: '200 OK' }
+
+    await device.statusCode('pushChanges', error)
+
+    expect(device.debugLog).toHaveBeenCalledWith('Request successful, statusCode: 200 OK')
+    expect(device.debugErrorLog).not.toHaveBeenCalled()
+  })
+
+  it('should handle 429 status code for rate limiting', async () => {
+    const device = createMockDevice()
+    const error = { message: 'PUT failed with: 429' }
+
+    await device.statusCode('pushChanges', error)
+
+    expect(device.debugLog).toHaveBeenCalledWith(
+      'Too Many Requests, exceeded the number of requests allowed for a given time window, statusCode: PUT failed with: 429',
+    )
+    expect(device.debugErrorLog).not.toHaveBeenCalled()
+  })
+
+  it('should extract status code from different message formats', async () => {
+    const device = createMockDevice()
+
+    // Test extraction from "422"
+    const error1 = { message: '422' }
+    await device.statusCode('test', error1)
+    expect(device.debugLog).toHaveBeenCalledWith(
+      'Unprocessable Entity - The request was well-formed but could not be processed. This may indicate the lock is in an invalid state or the operation is not allowed at this time, statusCode: 422',
+    )
+
+    // Reset mock
+    device.debugLog.mockClear()
+    device.debugErrorLog.mockClear()
+
+    // Test extraction from "API call failed: 422"
+    const error2 = { message: 'API call failed: 422' }
+    await device.statusCode('test', error2)
+    expect(device.debugLog).toHaveBeenCalledWith(
+      'Unprocessable Entity - The request was well-formed but could not be processed. This may indicate the lock is in an invalid state or the operation is not allowed at this time, statusCode: API call failed: 422',
+    )
+  })
+})

src/devices/device.ts

@@ -157,16 +157,22 @@ export abstract class deviceBase {
 
   async statusCode(action: string, error: { message: string }): Promise<void> {
     const statusCodeString = error.message // Convert statusCode to a string
+
+    // Extract numeric status code from error message (e.g., "PUT failed with: 422" -> "422")
+    const statusCodeMatch = statusCodeString.match(/\b(\d{3})\b/)
+    const statusCode = statusCodeMatch ? statusCodeMatch[1] : statusCodeString.slice(0, 3)
+
     const logMap = {
       100: `Command successfully sent, statusCode: ${statusCodeString}`,
       200: `Request successful, statusCode: ${statusCodeString}`,
       400: `Bad Request, statusCode: ${statusCodeString}`,
+      422: `Unprocessable Entity - The request was well-formed but could not be processed. This may indicate the lock is in an invalid state or the operation is not allowed at this time, statusCode: ${statusCodeString}`,
       429: `Too Many Requests, exceeded the number of requests allowed for a given time window, statusCode: ${statusCodeString}`,
     }
-    const logMessage = logMap[statusCodeString.slice(0, 3)]
+    const logMessage = logMap[statusCode]
       ?? `Unknown statusCode: ${statusCodeString}, Submit Bugs Here: https://tinyurl.com/AugustYaleBug`
     await this.debugLog(logMessage)
-    if (!logMap[statusCodeString.slice(0, 3)]) {
+    if (!logMap[statusCode]) {
       await this.debugErrorLog(`failed ${action}, Error: ${error}`)
     }
   }