homebridge-ttlock-accesscode 2.0.0-beta.7 → 2.0.0

package/README.md

@@ -19,37 +19,79 @@
   <a href="https://github.com/sponsors/ZeliardM"><img src="https://img.shields.io/badge/donate-github-orange" alt="donate github"></a>
 </p>
 
-<div align="center">
+This is a [Homebridge](https://github.com/homebridge/homebridge) plug-in based for integrating TTLock smart locks with the TTLock Cloud API.
 
->## PLEASE READ!!!
->HomeKey Support is not physically possible with TTLock Readers, but Access Code Features are working in HomeKit.
+This plug-in lets you control TTLock locks in the Apple Home app with lock/unlock status, control, and access code management if supported.
 
-</div>
+## Requirements
+- Homebridge Supported Versions: 1.8.0 and 2.0.0-beta.0 or later.
+- Node.js Supported Versions: 20, 22, and 24.
+- TTLock Smart Lock.
+- TTLock Gateway for non-Wi-Fi locks.
+- Remote Unlock enabled in the TTLock mobile app.
+- TTLock Open API account with an approved OAUTH2.0 App.
 
-This is a [Homebridge](https://github.com/homebridge/homebridge) plug-in based for integrating TTLock smart locks with the TTLock Cloud API.
+## Current Supported and Tested Devices
+- I have tested this plug-in with a G2 Gateway setup and TTLock lock access code features in Apple Home. More lock models and gateway setups are expected to work, but may vary by TTLock firmware and account setup.
 
 ## Features
-
 - Get the status of your TTLock devices.
 - Lock and unlock your TTLock devices.
-- Manage passcodes for your TTLock devices.
-
-## Requirements
-
-1. TTLock Smart Lock
-2. A Gateway (If your lock does not have built-in Wi-Fi, I purchased a TTLock G2 Gateway off Amazon.)
-3. Remote Unlock must be enabled through the TTLock App locally within bluetooth or Wi-Fi rnage of your lock.
-4. You must create a TTLock Open API Account. This is not the username and password that will be used in the setting in the plug-in, this is for creating an OAUTH2.0 App with the TTLock Cloud API for the plug-in to get access to your TTLock Devices.
-
-## Setup
-
-1. Create an account in the [TTLock Cloud API](https://euopen.ttlock.com/register). 
-2. Create your OAUTH2.0 App, give it a name, icon, select the 'App' option, and a short description.</br>
-*This may take a few days to be approved by their Development Team.*
-3. Once approved, you will need the *client_id* and *client_secret* from the app.
-4. Setup the TTLock Mobile App, create an account in the Mobile App, setup and install your lock(s).</br>
-*If your Lock is not Wi-Fi Capable, make sure you setup your Gateway as well and have it close enough to your Lock for the Gateway to pick up the Lock in the Mobile App.*
-5. Once you have your Mobile App Username and Password, and the client_id and client_secret, you can setup the plug-in in Homebridge.
-
-## IMPORTANT
-I have only tested this with a G2 Gateway.
+- Manage passcodes for your TTLock devices in Apple Home.
+- Automatic API usage protection with adaptive polling.
+- Periodic discovery and offline recovery handling.
+
+## Installation
+- Install from the Homebridge UI or with npm.
+- After installing, configure your TTLock credentials and API App values, then restart Homebridge.
+
+```bash
+npm install -g homebridge-ttlock-accesscode
+```
+
+## Configuration Notes
+- Create an account in the [TTLock Cloud API](https://euopen.ttlock.com/register)
+- Create your OAUTH2.0 App, approval may take a few days.
+- Use your TTLock mobile app username/password and OAUTH2.0 App client_id and client_secret in the plugin settings.
+- For non-Wi-Fi locks, make sure your gateway is online and near the lock.
+- The default settings are tuned for TTLock's monthly API limits.
+- Polling is automatically slowed when monthly allowance gets lower.
+
+## Access Code Notes
+- Access code support is exposed through the Apple Home App.
+- Existing passcodes are loaded from TTLock and mapped into the Apple Home App.
+- Add/Delete/List/Read flows are handled through the Apple Home App.
+
+## Example Configuration
+```json
+{
+  "bridge": {
+    "name": "Homebridge",
+    "username": "11:22:33:AA:BB:CC",
+    "port": 12345,
+    "pin": "001-02-003"
+  },
+  "description": "This is an example configuration file.",
+  "platforms": [
+    {
+      "platform": "TTLockAccessCode",
+      "name": "TTLockAccessCode",
+      "clientId": "YourClientID",
+      "clientSecret": "YourClientSecret",
+      "username": "YourUsername",
+      "password": "YourPassword",
+      "totalApiCallsPerMonth": 30000,
+      "pollingInterval": 300,
+      "discoveryPollingInterval": 12,
+      "offlineInterval": 7,
+      "waitTimeUpdate": 100
+    }
+  ],
+  "accessories": []
+}
+```
+
+## Known Limitations
+- Apple HomeKey is not supported by TTLock readers.
+- Gateway-dependent locks will return gateway-offline conditions if the gateway is unavailable.
+- TTLock Cloud API limits and behavior can change without notice.

package/config.schema.json

@@ -2,6 +2,7 @@
   "pluginAlias": "TTLockAccessCode",
   "pluginType": "platform",
   "singular": true,
+  "strictValidation": true,
   "headerDisplay": "TTLock Access Code Plugin.<p>Follow the [README](https://github.com/ZeliardM/homebridge-ttlock-accesscode/blob/latest/README.md) for configuration instructions and then click \"Save\" to get started.</p>",
   "footerDisplay": "",
   "schema": {
@@ -50,20 +51,20 @@
         "title": "Total API Calls Per Month",
         "type": "integer",
         "description": "Total number of TTLock API calls allowed per month (used to automatically adjust polling).",
-        "default": 100000,
-        "minimum": 100000
+        "default": 30000,
+        "minimum": 30000
       },
       "pollingInterval": {
         "title": "Polling Interval (seconds)",
         "type": "integer",
         "description": "How often to check device status in the background (seconds)",
-        "default": 90
+        "default": 300
       },
       "discoveryPollingInterval": {
         "title": "Discovery Polling Interval (hours)",
         "type": "integer",
         "description": "How often to discover new devices in the background (hours)",
-        "default": 6
+        "default": 12
       },
       "offlineInterval": {
         "title": "Offline Interval (days)",

package/dist/api/ttlockApi.d.ts

@@ -1,6 +1,28 @@
 import type { Logging } from 'homebridge';
 import { UsageTracker } from './usageTracker.js';
 import { FeatureInfo, Passcode, SysInfo, TTLockDevice } from '../devices/deviceTypes.js';
+export declare enum TTLockApiErrorCategory {
+    AuthExpired = "AuthExpired",
+    AuthInvalid = "AuthInvalid",
+    BudgetExhausted = "BudgetExhausted",
+    ClientInvalidRequest = "ClientInvalidRequest",
+    InvalidResponse = "InvalidResponse",
+    NetworkTransient = "NetworkTransient",
+    RateLimited = "RateLimited",
+    ServerTransient = "ServerTransient",
+    Unknown = "Unknown"
+}
+export declare class TTLockApiError extends Error {
+    readonly category: TTLockApiErrorCategory;
+    readonly retryable: boolean;
+    readonly endpoint?: string | undefined;
+    readonly statusCode?: number | undefined;
+    readonly errcode?: number | undefined;
+    readonly cause?: unknown | undefined;
+    wasLogged: boolean;
+    constructor(message: string, category: TTLockApiErrorCategory, retryable: boolean, endpoint?: string | undefined, statusCode?: number | undefined, errcode?: number | undefined, cause?: unknown | undefined);
+    get authRelated(): boolean;
+}
 export declare class TTLockApi {
     private log;
     private clientId;
@@ -10,12 +32,26 @@ export declare class TTLockApi {
     refreshToken: string | null;
     private tokenMutex;
     private usageTracker;
+    private authUsername;
+    private authPassword;
+    private readonly requestTimeoutMs;
+    private readonly maxRetries;
     constructor(log: Logging, clientId: string, clientSecret: string, usageTracker?: UsageTracker);
     private encryptPassword;
     authenticate(username: string, password: string): Promise<void>;
-    private refreshTokenIfNeeded;
+    private authenticateWithPassword;
+    private refreshTokenIfNeededLocked;
+    private recoverAuthentication;
     private makeAuthenticatedRequest;
-    private handleError;
+    private logApiError;
+    private isGatewayOfflineError;
+    private normalizeApiResponseError;
+    private normalizeError;
+    private looksAuthError;
+    private looksRateLimitError;
+    private getRetryDelayMs;
+    private sleep;
+    private isObject;
     getDevices(): Promise<TTLockDevice[]>;
     getDeviceDetails(lockId: string): Promise<Partial<SysInfo>>;
     getSysInfo(lockId: string): Promise<Partial<SysInfo>>;

package/dist/api/ttlockApi.js

@@ -1,10 +1,38 @@
 import axios from 'axios';
 import crypto from 'crypto';
 import { SimpleMutex } from '../utils.js';
-class RequestFailed extends Error {
-    constructor(message) {
+export var TTLockApiErrorCategory;
+(function (TTLockApiErrorCategory) {
+    TTLockApiErrorCategory["AuthExpired"] = "AuthExpired";
+    TTLockApiErrorCategory["AuthInvalid"] = "AuthInvalid";
+    TTLockApiErrorCategory["BudgetExhausted"] = "BudgetExhausted";
+    TTLockApiErrorCategory["ClientInvalidRequest"] = "ClientInvalidRequest";
+    TTLockApiErrorCategory["InvalidResponse"] = "InvalidResponse";
+    TTLockApiErrorCategory["NetworkTransient"] = "NetworkTransient";
+    TTLockApiErrorCategory["RateLimited"] = "RateLimited";
+    TTLockApiErrorCategory["ServerTransient"] = "ServerTransient";
+    TTLockApiErrorCategory["Unknown"] = "Unknown";
+})(TTLockApiErrorCategory || (TTLockApiErrorCategory = {}));
+export class TTLockApiError extends Error {
+    category;
+    retryable;
+    endpoint;
+    statusCode;
+    errcode;
+    cause;
+    wasLogged = false;
+    constructor(message, category, retryable, endpoint, statusCode, errcode, cause) {
         super(message);
-        this.name = 'RequestFailed';
+        this.category = category;
+        this.retryable = retryable;
+        this.endpoint = endpoint;
+        this.statusCode = statusCode;
+        this.errcode = errcode;
+        this.cause = cause;
+        this.name = 'TTLockApiError';
+    }
+    get authRelated() {
+        return this.category === TTLockApiErrorCategory.AuthExpired || this.category === TTLockApiErrorCategory.AuthInvalid;
     }
 }
 export class TTLockApi {
@@ -16,6 +44,10 @@ export class TTLockApi {
     refreshToken = null;
     tokenMutex = new SimpleMutex();
     usageTracker;
+    authUsername = null;
+    authPassword = null;
+    requestTimeoutMs = 15000;
+    maxRetries = 3;
     constructor(log, clientId, clientSecret, usageTracker) {
         this.log = log;
         this.clientId = clientId;
@@ -25,6 +57,7 @@ export class TTLockApi {
             headers: {
                 'Content-Type': 'application/x-www-form-urlencoded',
             },
+            timeout: this.requestTimeoutMs,
         });
         this.log.debug('TTLockApi initialized');
         this.usageTracker = usageTracker;
@@ -33,51 +66,52 @@ export class TTLockApi {
         return crypto.createHash('md5').update(password).digest('hex');
     }
     async authenticate(username, password) {
+        this.authUsername = username;
+        this.authPassword = password;
+        await this.authenticateWithPassword(username, password);
+    }
+    async authenticateWithPassword(username, password) {
         this.log.debug('Authenticating with TTLock API...');
         try {
             const encryptedPassword = this.encryptPassword(password);
             if (this.usageTracker) {
                 const ok = await this.usageTracker.tryReserve(1, 'authenticate');
                 if (!ok) {
-                    throw new Error('API usage budget exhausted (authenticate)');
+                    throw new TTLockApiError('API usage budget exhausted (authenticate)', TTLockApiErrorCategory.BudgetExhausted, false, 'oauth2/token');
                 }
             }
-            const response = await Promise.race([
-                this.apiClient.post('oauth2/token', new URLSearchParams({
-                    client_id: this.clientId,
-                    client_secret: this.clientSecret,
-                    grant_type: 'password',
-                    username,
-                    password: encryptedPassword,
-                }).toString()),
-                new Promise((_, reject) => setTimeout(() => reject(new Error('TTLock API authentication timed out')), 15000)),
-            ]);
+            const response = await this.apiClient.post('oauth2/token', new URLSearchParams({
+                client_id: this.clientId,
+                client_secret: this.clientSecret,
+                grant_type: 'password',
+                username,
+                password: encryptedPassword,
+            }).toString());
             if (response.data.access_token && response.data.refresh_token) {
                 this.accessToken = response.data.access_token;
                 this.refreshToken = response.data.refresh_token;
                 this.log.info('Authenticated with TTLock API');
             }
             else {
-                this.log.error('Authentication response did not contain tokens:', response.data);
-                throw new Error('Authentication failed: No tokens received');
+                throw new TTLockApiError(`Authentication failed: invalid token response (${JSON.stringify(response.data)})`, TTLockApiErrorCategory.AuthInvalid, false, 'oauth2/token', undefined, response.data.errcode);
             }
         }
         catch (error) {
-            this.handleError('Failed to authenticate with TTLock API', error);
-            throw error;
+            const normalized = this.normalizeError(error, 'oauth2/token');
+            this.logApiError('Failed to authenticate with TTLock API', normalized);
+            throw normalized;
         }
     }
-    async refreshTokenIfNeeded() {
+    async refreshTokenIfNeededLocked() {
         if (!this.refreshToken) {
-            throw new Error('No refresh token available. Please call authenticate() first.');
+            throw new TTLockApiError('No refresh token available. Full re-authentication required.', TTLockApiErrorCategory.AuthInvalid, false, 'oauth2/token');
         }
-        const release = await this.tokenMutex.acquire();
         try {
             this.log.debug('Refreshing access token...');
             if (this.usageTracker) {
                 const ok = await this.usageTracker.tryReserve(1, 'refreshToken');
                 if (!ok) {
-                    throw new Error('API usage budget exhausted (refreshToken)');
+                    throw new TTLockApiError('API usage budget exhausted (refreshToken)', TTLockApiErrorCategory.BudgetExhausted, false, 'oauth2/token');
                 }
             }
             const response = await this.apiClient.post('oauth2/token', new URLSearchParams({
@@ -92,32 +126,68 @@ export class TTLockApi {
                 this.log.debug('Access token refreshed');
             }
             else {
-                throw new Error('Failed to refresh token: Invalid response');
+                throw new TTLockApiError(`Failed to refresh token: invalid response (${JSON.stringify(response.data)})`, TTLockApiErrorCategory.AuthInvalid, false, 'oauth2/token', undefined, response.data.errcode);
             }
         }
         catch (error) {
-            this.handleError('Failed to refresh access token', error);
-            throw error;
+            throw this.normalizeError(error, 'oauth2/token');
+        }
+    }
+    async recoverAuthentication(failedToken, endpoint) {
+        const release = await this.tokenMutex.acquire();
+        try {
+            if (this.accessToken && this.accessToken !== failedToken) {
+                this.log.debug(`Token already refreshed by a concurrent request for endpoint ${endpoint}`);
+                return;
+            }
+            try {
+                await this.refreshTokenIfNeededLocked();
+                this.log.debug(`Recovered authentication via refresh token for endpoint ${endpoint}`);
+                return;
+            }
+            catch (refreshError) {
+                const normalizedRefreshError = this.normalizeError(refreshError, endpoint);
+                this.log.warn(`Refresh token flow failed for endpoint ${endpoint}: ${normalizedRefreshError.message}`);
+            }
+            if (!this.authUsername || !this.authPassword) {
+                throw new TTLockApiError('No stored credentials available for full re-authentication', TTLockApiErrorCategory.AuthInvalid, false, endpoint);
+            }
+            await this.authenticateWithPassword(this.authUsername, this.authPassword);
+            this.log.info(`Recovered authentication via full credential re-login for endpoint ${endpoint}`);
         }
         finally {
             release();
         }
     }
     async makeAuthenticatedRequest(endpoint, method = 'GET', data) {
-        const maxRetries = 3;
+        const fullEndpoint = `v3/${endpoint}`;
+        let authRecoveryAttempted = false;
+        let lastError;
+        if (!this.accessToken && this.authUsername && this.authPassword) {
+            await this.authenticateWithPassword(this.authUsername, this.authPassword);
+        }
         if (!this.accessToken) {
-            throw new Error('Not authenticated. Please call authenticate() first.');
+            throw new TTLockApiError('Not authenticated and credentials are unavailable', TTLockApiErrorCategory.AuthInvalid, false, endpoint);
         }
-        const requestData = {
-            ...data,
-            clientId: this.clientId,
-            accessToken: this.accessToken,
-            date: Date.now(),
-        };
-        const fullEndpoint = `v3/${endpoint}`;
-        let lastError = new Error('Unknown request error');
-        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        if (this.usageTracker) {
+            const consumedReserved = await this.usageTracker.consumePendingReservation(1);
+            if (!consumedReserved) {
+                const ok = await this.usageTracker.tryReserve(1, `request:${endpoint}`);
+                if (!ok) {
+                    throw new TTLockApiError(`API usage budget exhausted (${endpoint})`, TTLockApiErrorCategory.BudgetExhausted, false, endpoint);
+                }
+            }
+        }
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            let attemptedToken = this.accessToken;
             try {
+                attemptedToken = this.accessToken;
+                const requestData = {
+                    ...data,
+                    clientId: this.clientId,
+                    accessToken: this.accessToken,
+                    date: Date.now(),
+                };
                 const response = await this.apiClient.request({
                     url: fullEndpoint,
                     method,
@@ -132,82 +202,133 @@ export class TTLockApi {
                         }, {})).toString()
                         : undefined,
                 });
-                if ('errcode' in response.data && response.data.errcode !== 0) {
-                    throw new RequestFailed(`API returned error: ${response.data.errmsg || 'Unknown error'}`);
+                if (this.isObject(response.data) && 'errcode' in response.data && response.data.errcode !== 0) {
+                    const payload = response.data;
+                    throw this.normalizeApiResponseError(payload, endpoint);
                 }
                 return response.data;
             }
             catch (error) {
-                lastError = error;
-                if (error instanceof RequestFailed) {
-                    const errorMsg = error.message;
-                    this.log.debug(`Attempt ${attempt + 1} failed: ${errorMsg}`);
-                    if (attempt < maxRetries) {
-                        const delay = Math.pow(2, attempt) * 1000;
-                        this.log.debug(`Retrying in ${delay / 1000} seconds...`);
-                        await new Promise(resolve => setTimeout(resolve, delay));
-                        continue;
-                    }
-                    break;
+                const normalized = this.normalizeError(error, endpoint);
+                lastError = normalized;
+                if (normalized.authRelated && !authRecoveryAttempted) {
+                    authRecoveryAttempted = true;
+                    this.log.warn(`Auth failure for ${endpoint}; attempting internal re-authentication`);
+                    await this.recoverAuthentication(attemptedToken, endpoint);
+                    continue;
                 }
-                if (axios.isAxiosError(error)) {
-                    if (error.response) {
-                        if (error.response.status === 401) {
-                            this.log.debug('Access token expired, refreshing token...');
-                            try {
-                                await this.refreshTokenIfNeeded();
-                                continue;
-                            }
-                            catch (error) {
-                                lastError = error;
-                                break;
-                            }
-                        }
-                        const rf = new RequestFailed(`Request failed: status=${error.response.status}, body=${JSON.stringify(error.response.data)}`);
-                        this.log.error(rf.message);
-                        if (error.response.status >= 500 && attempt < maxRetries) {
-                            const delay = Math.pow(2, attempt) * 1000;
-                            this.log.debug(`Server error, retrying in ${delay / 1000} seconds...`);
-                            await new Promise(resolve => setTimeout(resolve, delay));
-                            lastError = rf;
-                            continue;
-                        }
-                        lastError = rf;
-                        break;
-                    }
-                    this.log.debug(`Network error on attempt ${attempt + 1}: ${error.message}`);
-                    if (attempt < maxRetries) {
-                        const delay = Math.pow(2, attempt) * 1000;
-                        await new Promise(resolve => setTimeout(resolve, delay));
-                        continue;
-                    }
-                    break;
+                const isLastAttempt = attempt >= this.maxRetries;
+                if (!isLastAttempt && normalized.retryable) {
+                    const delay = this.getRetryDelayMs(attempt);
+                    this.log.warn(`Retryable TTLock API error on ${endpoint}; category=${normalized.category}; ` +
+                        `attempt=${attempt + 1}/${this.maxRetries + 1}; retrying in ${delay}ms`);
+                    await this.sleep(delay);
+                    continue;
                 }
-                this.handleError('Request failed', error);
-                break;
+                if (!this.isGatewayOfflineError(normalized)) {
+                    this.logApiError(`Request failed for ${endpoint}`, normalized);
+                }
+                throw normalized;
             }
         }
-        if (lastError instanceof Error) {
+        if (lastError) {
             throw lastError;
         }
-        throw new Error('Max retries reached');
+        throw new TTLockApiError('Max retries reached', TTLockApiErrorCategory.Unknown, false, endpoint);
+    }
+    logApiError(message, error) {
+        if (error.wasLogged) {
+            return;
+        }
+        error.wasLogged = true;
+        if (this.isGatewayOfflineError(error)) {
+            this.log.warn(`${message}: gateway offline (endpoint=${error.endpoint ?? 'unknown'} errcode=${error.errcode ?? 'n/a'}). ` +
+                'Will retry on next poll/discovery cycle.');
+            return;
+        }
+        this.log.error(`${message}: category=${error.category} retryable=${error.retryable} endpoint=${error.endpoint ?? 'unknown'} ` +
+            `status=${error.statusCode ?? 'n/a'} errcode=${error.errcode ?? 'n/a'} message=${error.message}`);
+    }
+    isGatewayOfflineError(error) {
+        return error.errcode === -3002 || /gateway is offline/i.test(error.message);
+    }
+    normalizeApiResponseError(payload, endpoint) {
+        const errcode = payload.errcode;
+        const errmsg = payload.errmsg ?? 'Unknown API error';
+        if (this.looksAuthError(undefined, errcode, errmsg)) {
+            return new TTLockApiError(`TTLock authentication error: ${errmsg}`, TTLockApiErrorCategory.AuthExpired, false, endpoint, undefined, errcode);
+        }
+        if (this.looksRateLimitError(undefined, errcode, errmsg)) {
+            return new TTLockApiError(`TTLock rate limit error: ${errmsg}`, TTLockApiErrorCategory.RateLimited, true, endpoint, undefined, errcode);
+        }
+        return new TTLockApiError(`TTLock API returned errcode=${errcode ?? 'n/a'} errmsg=${errmsg}`, TTLockApiErrorCategory.ClientInvalidRequest, false, endpoint, undefined, errcode);
     }
-    handleError(message, error) {
+    normalizeError(error, endpoint) {
+        if (error instanceof TTLockApiError) {
+            return error;
+        }
         if (axios.isAxiosError(error)) {
-            this.log.error(`${message}: ${error.response?.data || error.message}`);
+            const status = error.response?.status;
+            const responseData = error.response?.data;
+            const errcode = this.isObject(responseData) ? responseData.errcode : undefined;
+            const errmsg = this.isObject(responseData) ? responseData.errmsg : undefined;
+            if (this.looksAuthError(status, errcode, errmsg)) {
+                return new TTLockApiError(`Authentication failed for ${endpoint ?? 'request'}: ${errmsg ?? error.message}`, TTLockApiErrorCategory.AuthExpired, false, endpoint, status, errcode, error);
+            }
+            if (this.looksRateLimitError(status, errcode, errmsg)) {
+                return new TTLockApiError(`Rate limited on ${endpoint ?? 'request'}: ${errmsg ?? error.message}`, TTLockApiErrorCategory.RateLimited, true, endpoint, status, errcode, error);
+            }
+            if (!error.response || error.code === 'ECONNABORTED') {
+                return new TTLockApiError(`Network error on ${endpoint ?? 'request'}: ${error.message}`, TTLockApiErrorCategory.NetworkTransient, true, endpoint, status, errcode, error);
+            }
+            if (status !== undefined && status >= 500) {
+                return new TTLockApiError(`Server error on ${endpoint ?? 'request'}: status=${status}`, TTLockApiErrorCategory.ServerTransient, true, endpoint, status, errcode, error);
+            }
+            if (status !== undefined && status >= 400) {
+                return new TTLockApiError(`Client error on ${endpoint ?? 'request'}: status=${status}`, TTLockApiErrorCategory.ClientInvalidRequest, false, endpoint, status, errcode, error);
+            }
+            return new TTLockApiError(`Unknown axios error on ${endpoint ?? 'request'}: ${error.message}`, TTLockApiErrorCategory.Unknown, false, endpoint, status, errcode, error);
+        }
+        if (error instanceof Error) {
+            const isTimeout = /timed out|timeout/i.test(error.message);
+            return new TTLockApiError(error.message, isTimeout ? TTLockApiErrorCategory.NetworkTransient : TTLockApiErrorCategory.Unknown, isTimeout, endpoint, undefined, undefined, error);
         }
-        else if (error instanceof Error) {
-            this.log.error(`${message}: ${error.message}`);
+        return new TTLockApiError(`Unknown error: ${JSON.stringify(error)}`, TTLockApiErrorCategory.Unknown, false, endpoint, undefined, undefined, error);
+    }
+    looksAuthError(status, errcode, message) {
+        if (status === 401 || status === 403) {
+            return true;
         }
-        else {
-            this.log.error(`${message}: ${JSON.stringify(error)}`);
+        if (typeof errcode === 'number' && [10002, 10003, 10004, 10005, 10006].includes(errcode)) {
+            return true;
         }
+        return /token|auth|expired|invalid_grant|credential|login/i.test(message ?? '');
+    }
+    looksRateLimitError(status, errcode, message) {
+        if (status === 429) {
+            return true;
+        }
+        if (typeof errcode === 'number' && [10018, 10019, 10020].includes(errcode)) {
+            return true;
+        }
+        return /too many|rate.?limit|frequency|limit/i.test(message ?? '');
+    }
+    getRetryDelayMs(attempt) {
+        const baseDelay = Math.min(8000, Math.pow(2, attempt) * 1000);
+        const jitter = Math.floor(Math.random() * 250);
+        return baseDelay + jitter;
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    isObject(value) {
+        return typeof value === 'object' && value !== null;
     }
     async getDevices() {
         const response = await this.makeAuthenticatedRequest('lock/list', 'GET', { pageNo: 1, pageSize: 1000 });
         if (!response.list || !Array.isArray(response.list)) {
             this.log.error('Invalid response format: expected list of locks');
-            throw new Error('Invalid response format: expected list of locks');
+            throw new TTLockApiError('Invalid response format: expected list of locks', TTLockApiErrorCategory.InvalidResponse, false, 'lock/list');
         }
         const lockList = [];
         for (const lock of response.list) {
@@ -227,7 +348,8 @@ export class TTLockApi {
                 lockList.push(ttlockDevice);
             }
             catch (error) {
-                this.handleError(`Failed to fetch details for lock ${lock.lockId}`, error);
+                const normalized = this.normalizeError(error, 'lock/detail|lock/queryOpenState');
+                this.logApiError(`Failed to fetch details for lock ${lock.lockId}`, normalized);
                 continue;
             }
         }
@@ -237,6 +359,9 @@ export class TTLockApi {
         const sysInfo = {};
         const detailResponse = await this.makeAuthenticatedRequest('lock/detail', 'GET', { lockId });
         const stateResponse = await this.makeAuthenticatedRequest('lock/queryOpenState', 'GET', { lockId });
+        if (!detailResponse.firmwareRevision || !detailResponse.hardwareRevision || !detailResponse.modelNum) {
+            throw new TTLockApiError(`Invalid lock/detail response for lockId=${lockId}`, TTLockApiErrorCategory.InvalidResponse, false, 'lock/detail');
+        }
         sysInfo.fw_ver = detailResponse.firmwareRevision.split('.').slice(0, 3).join('.');
         sysInfo.hw_ver = detailResponse.hardwareRevision;
         sysInfo.model = detailResponse.modelNum;
@@ -266,7 +391,8 @@ export class TTLockApi {
             return featureInfo;
         }
         catch (error) {
-            this.handleError('Failed to parse featureValue', error);
+            const normalized = this.normalizeError(error, 'feature/parse');
+            this.logApiError('Failed to parse featureValue', normalized);
             featureInfo.passcode = false;
             return featureInfo;
         }
@@ -286,12 +412,12 @@ export class TTLockApi {
         const response = await this.makeAuthenticatedRequest('lock/listKeyboardPwd', 'GET', { lockId, pageNo: 1, pageSize: 1000, orderBy: 0 });
         if (!response.list || !Array.isArray(response.list)) {
             this.log.error('Invalid response format: expected list of passcodes');
-            throw new Error('Invalid response format: expected list of passcodes');
+            throw new TTLockApiError('Invalid response format: expected list of passcodes', TTLockApiErrorCategory.InvalidResponse, false, 'lock/listKeyboardPwd');
         }
         this.log.debug(`Found ${response.list.length} passcodes for lock: ${lockId}`);
         return response.list.map((item, index) => ({
             passcode_id: item.keyboardPwdId.toString(),
-            index: (index).toString(),
+            index: index.toString(),
             lock_id: item.lockId.toString(),
             passcode: item.keyboardPwd,
         }));