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

package/README.md

@@ -13,42 +13,85 @@
 <p align="center">
   <a href="https://github.com/ZeliardM/homebridge-ttlock-accesscode/blob/latest/LICENSE"><img src="https://img.shields.io/npm/l/homebridge-ttlock-accesscode?color=yellow" alt="mit license"></a>
   <a href="https://www.npmjs.com/package/homebridge-ttlock-accesscode/v/latest"><img src="https://img.shields.io/npm/v/homebridge-ttlock-accesscode/latest?label=npm%40latest&color=blue" alt="latest npm version"></a>
+  <a href="https://www.npmjs.com/package/homebridge-ttlock-accesscode/v/beta"><img src="https://img.shields.io/npm/v/homebridge-ttlock-accesscode/beta?label=npm%40beta&color=red" alt="beta npm version"></a>
   <a href="https://www.npmjs.com/package/homebridge-ttlock-accesscode/v/latest"><img src="https://img.shields.io/npm/dt/homebridge-ttlock-accesscode?color=brightgreen" alt="npm downloads total"></a>
-  <a href="https://www.paypal.me/ZeliardM/USD/"><img src="https://img.shields.io/badge/donate-paypal-orange" alt="donate"></a>
-  <a href="https://github.com/sponsors/ZeliardM"><img src="https://img.shields.io/badge/donate-github-orange" alt="donate"></a>
+  <a href="https://www.paypal.me/ZeliardM/USD/"><img src="https://img.shields.io/badge/donate-paypal-orange" alt="donate paypal"></a>
+  <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>>;