Fix August API ETIMEDOUT errors after 24 hours with session refresh and retry logic (#166)

This PR addresses persistent ETIMEDOUT connection failures that occur
after approximately 24 hours of plugin operation. The issue manifests
as:

```
[August] [DEBUG] Lock: DoorName failed (refreshStatus) lockDetails, Error: {"errno":-110,"code":"ETIMEDOUT","syscall":"read"}
[August] Lock: DoorName pushChanges: read ETIMEDOUT
```

## Root Cause
The August API invalidates sessions after extended periods, but the
plugin continued using stale connections without attempting to
re-establish them when timeouts occurred.

## Solution
Implemented a minimal timeout detection and session refresh mechanism:

1. **Timeout Detection**: Added `isTimeoutError()` method to
specifically identify ETIMEDOUT errors in network operations
2. **Session Refresh**: Added `refreshAugustSession()` method that calls
`augustConfig.end()` to clear stale tokens, forcing re-authentication on
the next API call
3. **Retry Logic**: Enhanced `refreshStatus()` and `pushChanges()`
methods to automatically retry operations once after session refresh
when timeouts are detected

## Technical Details
The fix leverages the existing `august-yale` library's session
management:
- Uses `augustConfig.end()` to clear stale tokens
- Allows automatic re-authentication on subsequent API calls
- Implements single retry to avoid infinite loops
- Preserves all existing error logging and debugging

## Testing
- ✅ Build passes without compilation errors
- ✅ All existing tests continue to pass
- ✅ Linting requirements satisfied
- ✅ No breaking changes to existing functionality

The solution is minimal and surgical, adding only 64 lines of code
focused specifically on timeout handling without modifying any existing
behavior.

Fixes #126.

<!-- START COPILOT CODING AGENT TIPS -->
---

💬 Share your feedback on Copilot coding agent for the chance to win a
$200 gift card! Click
[here](https://survey3.medallia.com/?EAHeSx-AP01bZqG0Ld9QLQ) to start
the survey.

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: donavanbecker <[email protected]>
Co-authored-by: Donavan Becker <[email protected]>

Author: Copilot

src/devices/device.ts

@@ -177,6 +177,13 @@ export abstract class deviceBase {
     }
   }
 
+  /**
+   * Check if error is a network timeout that requires session refresh
+   */
+  isTimeoutError(error: { message: string }): boolean {
+    return Boolean(error.message && error.message.includes('ETIMEDOUT'))
+  }
+
   /**
    * Logging for Device
    */

src/devices/lock.ts

@@ -314,6 +314,27 @@ export class LockMechanism extends deviceBase {
       } catch (e: any) {
         await this.statusCode('(refreshStatus) lockDetails', e)
         await this.errorLog(`(refreshStatus) lockDetails: ${e.message ?? e}`)
+
+        // Check if this is a timeout error and retry once after session refresh
+        if (this.isTimeoutError(e)) {
+          try {
+            await this.debugLog('Timeout detected, refreshing August session and retrying...')
+            await this.platform.refreshAugustSession()
+
+            // Retry the operation once
+            if (this.platform.augustConfig && this.platform.augustConfig.details) {
+              const lockDetails: any = await this.platform.augustConfig.details(this.device.lockId)
+              await this.debugSuccessLog(`(refreshStatus retry) lockDetails: ${JSON.stringify(lockDetails)}`)
+              // Update HomeKit
+              this.lockDetails = lockDetails
+              this.lockStatus = lockDetails.LockStatus
+              await this.parseStatus()
+              await this.updateHomeKitCharacteristics()
+            }
+          } catch (retryError: any) {
+            await this.errorLog(`(refreshStatus retry) failed: ${retryError.message ?? retryError}`)
+          }
+        }
       }
     } else {
       await this.debugLog(`(refreshStatus) deviceRefreshRate: ${this.deviceRefreshRate}`)
@@ -358,6 +379,27 @@ export class LockMechanism extends deviceBase {
     } catch (e: any) {
       await this.statusCode('pushChanges', e)
       await this.debugLog(`pushChanges: ${e.message ?? e}`)
+
+      // Check if this is a timeout error and retry once after session refresh
+      if (this.isTimeoutError(e)) {
+        try {
+          await this.debugLog('Timeout detected in pushChanges, refreshing August session and retrying...')
+          await this.platform.refreshAugustSession()
+
+          // Retry the operation once
+          if (this.LockMechanism && this.LockMechanism.LockTargetState !== this.LockMechanism.LockCurrentState) {
+            if (this.LockMechanism.LockTargetState === this.hap.Characteristic.LockTargetState.UNSECURED) {
+              await this.platform.augustConfig.unlock(this.device.lockId)
+            } else {
+              await this.platform.augustConfig.lock(this.device.lockId)
+            }
+            await this.successLog(`Retry: Sending request to August API: ${this.LockMechanism.LockTargetState === 1 ? 'Locked' : 'Unlocked'}`)
+            await this.updateHomeKitCharacteristics()
+          }
+        } catch (retryError: any) {
+          await this.errorLog(`(pushChanges retry) failed: ${retryError.message ?? retryError}`)
+        }
+      }
     }
   }
 

src/platform.ts

@@ -198,6 +198,21 @@ export class AugustPlatform implements DynamicPlatformPlugin {
     }
   }
 
+  /**
+   * Refresh August session by clearing current token
+   */
+  async refreshAugustSession(): Promise<void> {
+    try {
+      if (this.augustConfig) {
+        await this.debugLog('Refreshing August session due to timeout error')
+        this.augustConfig.end() // Clear the current token to force re-authentication
+        await this.debugLog('August session refreshed successfully')
+      }
+    } catch (e: any) {
+      await this.errorLog(`Failed to refresh August session: ${e.message ?? e}`)
+    }
+  }
+
   async pluginConfig() {
     const currentConfig = JSON.parse(readFileSync(this.api.user.configPath(), 'utf8'))
     // check the platforms section is an array before we do array things on it