tsvesync 1.4.11 → 1.5.1

package/dist/lib/helpers.d.ts

@@ -36,6 +36,14 @@ export declare const AUTH_ERROR_CODES: {
 };
 type CallApiOptions = {
     didRetryAuth?: boolean;
+    /**
+     * Set on requests that are themselves part of the authentication flow.
+     *
+     * Those must never trigger the re-login retry in `callApi`: `VeSync.login()` de-duplicates on an
+     * in-flight promise, so calling it from inside the auth flow makes that promise await itself and it
+     * never settles (a silent hang rather than an error).
+     */
+    skipAuthRetry?: boolean;
 };
 /**
  * Get list of country codes that use the US endpoint

package/dist/lib/helpers.js

@@ -96,6 +96,40 @@ exports.AUTH_ERROR_CODES = {
 function isTokenExpiredMessage(msg) {
     return typeof msg === 'string' && /token\s*(?:has\s*)?expired/i.test(msg);
 }
+/**
+ * Auth material is snapshotted into the request body (`reqBodyAuth`) and headers (`reqHeaders`) at the
+ * moment they are built. A request retried after a re-login therefore still carries the *old* token, so it
+ * fails with the very same token error that triggered the retry. Refresh those fields from the manager
+ * before retrying.
+ *
+ * Only keys that are already present with a non-empty string value are replaced. That leaves auth-flow
+ * payloads — which deliberately send `token: ''` / `accountID: ''` — untouched.
+ */
+function refreshAuthMaterial(data, headers, manager) {
+    const token = manager.token;
+    const accountId = manager.accountId;
+    if (!token || !accountId) {
+        return [data, headers];
+    }
+    const replace = (target, key, value) => {
+        if (typeof target[key] === 'string' && target[key].length > 0) {
+            target[key] = value;
+        }
+    };
+    let nextData = data;
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+        nextData = { ...data };
+        replace(nextData, 'token', token);
+        replace(nextData, 'accountID', accountId);
+        replace(nextData, 'accountId', accountId);
+    }
+    const nextHeaders = { ...headers };
+    replace(nextHeaders, 'tk', token);
+    replace(nextHeaders, 'token', token);
+    replace(nextHeaders, 'accountId', accountId);
+    replace(nextHeaders, 'accountID', accountId);
+    return [nextData, nextHeaders];
+}
 /**
  * Get list of country codes that use the US endpoint
  * These are tried when we get a cross-region error
@@ -467,14 +501,21 @@ class Helpers {
             const responseCode = (_a = response.data) === null || _a === void 0 ? void 0 : _a.code;
             const responseMsg = (_b = response.data) === null || _b === void 0 ? void 0 : _b.msg;
             if (!didRetryAuth &&
+                !options.skipAuthRetry &&
                 response.status === 200 &&
                 ((typeof responseCode === 'number' && (0, constants_1.isTokenError)(responseCode)) ||
                     isTokenExpiredMessage(responseMsg))) {
-                logger_1.logger.debug('Token expired, attempting to re-login...');
+                logger_1.logger.debug('VeSync rejected the session token; re-authenticating before retrying', {
+                    endpoint,
+                    code: responseCode
+                });
                 if (await manager.login()) {
-                    logger_1.logger.debug('Re-login successful, retrying original request...');
-                    return await this.callApi(endpoint, method, data, headers, manager, { ...options, didRetryAuth: true });
+                    // Rebuild the auth fields; the original body/headers still hold the rejected token.
+                    const [retryData, retryHeaders] = refreshAuthMaterial(data, headers, manager);
+                    logger_1.logger.debug('Re-authentication succeeded, retrying request with the refreshed token');
+                    return await this.callApi(endpoint, method, retryData, retryHeaders, manager, { ...options, didRetryAuth: true });
                 }
+                logger_1.logger.debug('Re-authentication failed; returning the original token error to the caller');
             }
             return [response.data, response.status];
         }
@@ -485,18 +526,25 @@ class Helpers {
                 const httpStatus = error.response.status;
                 const msg = responseData === null || responseData === void 0 ? void 0 : responseData.msg;
                 const didRetryAuth = options.didRetryAuth === true;
-                if (!didRetryAuth && (httpStatus === 401 ||
+                if (!didRetryAuth && !options.skipAuthRetry && (httpStatus === 401 ||
                     httpStatus === 419 ||
                     (responseData === null || responseData === void 0 ? void 0 : responseData.code) === 4001004 ||
                     (typeof (responseData === null || responseData === void 0 ? void 0 : responseData.code) === 'number' && (0, constants_1.isTokenError)(responseData.code)) ||
                     isTokenExpiredMessage(msg))) {
-                    logger_1.logger.debug('Token expired, attempting to re-login...');
+                    logger_1.logger.debug('VeSync rejected the session token; re-authenticating before retrying', {
+                        endpoint,
+                        status: httpStatus,
+                        code: responseData === null || responseData === void 0 ? void 0 : responseData.code
+                    });
                     // Re-login
                     if (await manager.login()) {
-                        // Retry the original request
-                        logger_1.logger.debug('Re-login successful, retrying original request...');
-                        return await this.callApi(endpoint, method, data, headers, manager, { ...options, didRetryAuth: true });
+                        // Retry the original request with refreshed auth fields; the original body/headers
+                        // still hold the rejected token.
+                        const [retryData, retryHeaders] = refreshAuthMaterial(data, headers, manager);
+                        logger_1.logger.debug('Re-authentication succeeded, retrying request with the refreshed token');
+                        return await this.callApi(endpoint, method, retryData, retryHeaders, manager, { ...options, didRetryAuth: true });
                     }
+                    logger_1.logger.debug('Re-authentication failed; returning the original token error to the caller');
                 }
                 // Log specific error details for debugging
                 logger_1.logger.error('API call failed with response:', {
@@ -582,7 +630,9 @@ class Helpers {
         var _a, _b, _c;
         try {
             // Generate terminal ID to be used in both steps
-            const terminalId = generateTerminalId();
+            // Reuse the manager's stable terminal id. VeSync binds issued tokens to it (the JWT carries a
+            // `terminalId` claim), and a fresh id on every login makes each login look like a new device.
+            const terminalId = manager.terminalId || generateTerminalId();
             // pyvesync parity:
             // - `userCountryCode` defaults to `DEFAULT_REGION` ("US"), even if we first try the EU base URL.
             // - If the account truly belongs to another region, the Step 2 response includes the correct
@@ -605,7 +655,7 @@ class Helpers {
                 endpoint: manager.apiBaseUrl || getApiBaseUrl(),
                 body: { ...step1Body, password: '[REDACTED]' }
             });
-            const [authResponse, authStatus] = await this.callApi('/globalPlatform/api/accountAuth/v1/authByPWDOrOTM', 'post', step1Body, step1Headers, manager);
+            const [authResponse, authStatus] = await this.callApi('/globalPlatform/api/accountAuth/v1/authByPWDOrOTM', 'post', step1Body, step1Headers, manager, { skipAuthRetry: true });
             if (!authResponse || authStatus !== 200) {
                 logger_1.logger.error('Step 1 failed:', authResponse);
                 manager.apiBaseUrl = originalUrl;
@@ -654,7 +704,7 @@ class Helpers {
             //   to keep the function signature stable/historical.
             const step2Body = this.reqBodyAuthStep2(authorizeCode, null, appId, terminalId, countryCodeForStep2);
             logger_1.logger.debug('Step 2: Logging in with authorization code...');
-            const [loginResponse, loginStatus] = await this.callApi('/user/api/accountManage/v1/loginByAuthorizeCode4Vesync', 'post', step2Body, step1Headers, manager);
+            const [loginResponse, loginStatus] = await this.callApi('/user/api/accountManage/v1/loginByAuthorizeCode4Vesync', 'post', step2Body, step1Headers, manager, { skipAuthRetry: true });
             logger_1.logger.debug('Step 2 response:', {
                 status: loginStatus,
                 code: loginResponse === null || loginResponse === void 0 ? void 0 : loginResponse.code,
@@ -690,7 +740,7 @@ class Helpers {
                     if (regionChangeToken) {
                         const retryCountryCode = serverCountryCode || countryCodeForStep2;
                         const retryBody = this.reqBodyAuthStep2(authorizeCode, regionChangeToken, appId, terminalId, retryCountryCode, 'lastRegion');
-                        const [retryResponse, retryStatus] = await this.callApi('/user/api/accountManage/v1/loginByAuthorizeCode4Vesync', 'post', retryBody, step1Headers, manager);
+                        const [retryResponse, retryStatus] = await this.callApi('/user/api/accountManage/v1/loginByAuthorizeCode4Vesync', 'post', retryBody, step1Headers, manager, { skipAuthRetry: true });
                         if (retryResponse && retryStatus === 200 && retryResponse.code === 0) {
                             const { token, accountID, countryCode } = retryResponse.result || {};
                             if (token && accountID) {
@@ -740,7 +790,7 @@ class Helpers {
                 endpoint: manager.apiBaseUrl || getApiBaseUrl(),
                 body: { ...body, password: '[REDACTED]' }
             });
-            const [response, status] = await this.callApi('/cloud/v1/user/login', 'post', body, {}, manager);
+            const [response, status] = await this.callApi('/cloud/v1/user/login', 'post', body, {}, manager, { skipAuthRetry: true });
             if (!response || status !== 200) {
                 logger_1.logger.error('Legacy login failed:', response);
                 return [false, null, null, null];

package/dist/lib/session.d.ts

@@ -5,6 +5,14 @@ export interface Session {
     region: string;
     apiBaseUrl: string;
     authFlowUsed?: 'legacy' | 'new';
+    /**
+     * Identifies this installation to VeSync. Issued tokens are bound to it (the JWT payload carries a
+     * `terminalId` claim), so it must stay stable across logins and restarts — a fresh id makes every login
+     * look like a brand-new device to VeSync.
+     */
+    terminalId?: string;
+    /** Client app id, kept alongside `terminalId` so the client identity is stable too. */
+    appId?: string;
     issuedAt?: number | null;
     expiresAt?: number | null;
     lastValidatedAt?: number | null;

package/dist/lib/vesync.d.ts

@@ -27,6 +27,7 @@ export declare class VeSync {
     private _inProcess;
     private _excludeConfig;
     private _appId;
+    private _terminalId;
     private _region;
     private _countryCodeOverride;
     private _apiUrlOverride;
@@ -72,6 +73,16 @@ export declare class VeSync {
         sessionStore?: SessionStore;
         onTokenChange?: (session: Session) => void;
     }, redact?: boolean, apiUrl?: string, customLogger?: Logger, excludeConfig?: ExcludeConfig);
+    /**
+     * Adopt a previously persisted client identity without restoring credentials.
+     *
+     * Callers that decide not to reuse a stored token (because it has expired, say) should still keep the
+     * terminal/app id from that session, so the fresh login presents the same client to VeSync.
+     */
+    restoreClientIdentity(identity: {
+        terminalId?: string | null;
+        appId?: string | null;
+    }): void;
     /**
      * Hydrate manager from a previously persisted session
      */
@@ -96,6 +107,11 @@ export declare class VeSync {
      * Get current App ID
      */
     get appId(): string;
+    /**
+     * Terminal id presented to VeSync during authentication. Issued tokens carry it as a JWT claim, so it
+     * is persisted with the session and reused across logins and restarts.
+     */
+    get terminalId(): string;
     /**
      * Get current region
      */
@@ -136,6 +152,13 @@ export declare class VeSync {
      * Login to VeSync server with new authentication flow and backwards compatibility
      */
     login(retryAttempts?: number, initialDelayMs?: number): Promise<boolean>;
+    /**
+     * True when the current token carries an `exp` claim that has already passed.
+     *
+     * Deliberately conservative: a token that cannot be decoded, or that has no `exp`, is treated as
+     * usable and left to the API to accept or reject.
+     */
+    isTokenExpired(skewSeconds?: number): boolean;
     /**
      * Test if update interval has been exceeded
      */

package/dist/lib/vesync.js

@@ -176,6 +176,9 @@ class VeSync {
         this._lastUpdateTs = null;
         this._inProcess = false;
         this._appId = (0, helpers_1.generateAppId)();
+        // Stable per-installation identity. Overwritten by `hydrateSession` when a previous session is
+        // restored, so logins keep presenting the same terminal to VeSync.
+        this._terminalId = (0, helpers_1.generateTerminalId)();
         this.username = username;
         this.password = password;
         this.token = null;
@@ -231,6 +234,20 @@ class VeSync {
         }
         // Debug and redact are already set above in the options handling
     }
+    /**
+     * Adopt a previously persisted client identity without restoring credentials.
+     *
+     * Callers that decide not to reuse a stored token (because it has expired, say) should still keep the
+     * terminal/app id from that session, so the fresh login presents the same client to VeSync.
+     */
+    restoreClientIdentity(identity) {
+        if (typeof (identity === null || identity === void 0 ? void 0 : identity.terminalId) === 'string' && identity.terminalId) {
+            this._terminalId = identity.terminalId;
+        }
+        if (typeof (identity === null || identity === void 0 ? void 0 : identity.appId) === 'string' && identity.appId) {
+            this._appId = identity.appId;
+        }
+    }
     /**
      * Hydrate manager from a previously persisted session
      */
@@ -245,6 +262,13 @@ class VeSync {
             this.accountId = session.accountId;
             this.countryCode = (_a = session.countryCode) !== null && _a !== void 0 ? _a : null;
             this.authFlowUsed = session.authFlowUsed;
+            // Keep the persisted client identity so re-logins present the same terminal to VeSync.
+            if (typeof session.terminalId === 'string' && session.terminalId) {
+                this._terminalId = session.terminalId;
+            }
+            if (typeof session.appId === 'string' && session.appId) {
+                this._appId = session.appId;
+            }
             // pyvesync parity:
             // pyvesync persists `current_region` and derives the API base URL per-request from that region.
             // It does NOT treat a stored base URL as authoritative. For backwards compatibility with older
@@ -303,6 +327,8 @@ class VeSync {
             region: this._region,
             apiBaseUrl: this.apiBaseUrl,
             authFlowUsed: this.authFlowUsed,
+            terminalId: this._terminalId,
+            appId: this._appId,
             issuedAt: (_a = timestamps === null || timestamps === void 0 ? void 0 : timestamps.iat) !== null && _a !== void 0 ? _a : null,
             expiresAt: (_b = timestamps === null || timestamps === void 0 ? void 0 : timestamps.exp) !== null && _b !== void 0 ? _b : null,
             lastValidatedAt: Date.now(),
@@ -350,6 +376,13 @@ class VeSync {
     get appId() {
         return this._appId;
     }
+    /**
+     * Terminal id presented to VeSync during authentication. Issued tokens carry it as a JWT claim, so it
+     * is persisted with the session and reused across logins and restarts.
+     */
+    get terminalId() {
+        return this._terminalId;
+    }
     /**
      * Get current region
      */
@@ -497,6 +530,16 @@ class VeSync {
         this._inProcess = true;
         let success = false;
         try {
+            // A token whose `exp` has already passed can only come back as a token error, so refresh it
+            // up front instead of spending a request to be told so.
+            if (this.isTokenExpired()) {
+                logger_1.logger.debug('Stored VeSync token is past its expiry; authenticating before requesting the device list');
+                if (!await this.login()) {
+                    logger_1.logger.error('VeSync token had expired and re-authentication failed. Check the configured username/password (and country code if your account is not in the US).');
+                    this.enabled = false;
+                    return false;
+                }
+            }
             const fetchDeviceList = async () => {
                 return await helpers_1.Helpers.callApi('/cloud/v1/deviceManaged/devices', 'post', helpers_1.Helpers.reqBody(this, 'devicelist'), helpers_1.Helpers.reqHeaderBypass(), this);
             };
@@ -521,7 +564,9 @@ class VeSync {
                 if (typeof code === 'number' && code !== 0) {
                     if (!didRetryToken && (0, constants_1.isTokenError)(code)) {
                         didRetryToken = true;
-                        logger_1.logger.warn('Device list request returned token error; re-authenticating and retrying (pyvesync parity)', {
+                        // Recoverable: re-authenticate and retry. Logged at debug because the retry below
+                        // normally succeeds; the outcome is reported after the loop.
+                        logger_1.logger.debug('Device list request returned a token error; re-authenticating and retrying', {
                             code,
                             msg: response === null || response === void 0 ? void 0 : response.msg,
                             region: this._region,
@@ -529,6 +574,7 @@ class VeSync {
                         });
                         const reloginOk = await this.login();
                         if (!reloginOk) {
+                            logger_1.logger.error('VeSync rejected the stored session and re-authentication failed. Check the configured username/password (and country code if your account is not in the US).');
                             this.enabled = false;
                             return false;
                         }
@@ -562,6 +608,19 @@ class VeSync {
                 }
                 break;
             }
+            if (didRetryToken) {
+                if (response && status === 200 && response.code === 0) {
+                    logger_1.logger.info('VeSync session had expired; re-authenticated and recovered automatically.');
+                }
+                else {
+                    logger_1.logger.warn('VeSync session had expired and the request still failed after re-authenticating.', {
+                        code: response === null || response === void 0 ? void 0 : response.code,
+                        msg: response === null || response === void 0 ? void 0 : response.msg,
+                        region: this._region,
+                        endpoint: this.apiBaseUrl
+                    });
+                }
+            }
             if (!response) {
                 logger_1.logger.error('No response received from VeSync API');
                 return false;
@@ -792,6 +851,21 @@ class VeSync {
             this._loginPromise = null;
         }
     }
+    /**
+     * True when the current token carries an `exp` claim that has already passed.
+     *
+     * Deliberately conservative: a token that cannot be decoded, or that has no `exp`, is treated as
+     * usable and left to the API to accept or reject.
+     */
+    isTokenExpired(skewSeconds = 60) {
+        var _a;
+        if (!this.token)
+            return false;
+        const exp = (_a = (0, session_1.decodeJwtTimestamps)(this.token)) === null || _a === void 0 ? void 0 : _a.exp;
+        if (!exp)
+            return false;
+        return exp * 1000 <= Date.now() + skewSeconds * 1000;
+    }
     /**
      * Test if update interval has been exceeded
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tsvesync",
-  "version": "1.4.11",
+  "version": "1.5.1",
   "description": "A TypeScript library for interacting with VeSync smart home devices",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,7 +10,8 @@
     "test:everest": "ts-node test/everest-air-parity.test.ts",
     "prepare": "npm run build",
     "version": "git add -A src",
-    "postversion": "git push && git push --tags"
+    "postversion": "git push && git push --tags",
+    "test:token-refresh": "ts-node test/token-refresh-retry.test.ts"
   },
   "keywords": [
     "vesync",

package/src/lib/helpers.ts

@@ -97,8 +97,59 @@ function isTokenExpiredMessage(msg: unknown): boolean {
 
 type CallApiOptions = {
     didRetryAuth?: boolean;
+    /**
+     * Set on requests that are themselves part of the authentication flow.
+     *
+     * Those must never trigger the re-login retry in `callApi`: `VeSync.login()` de-duplicates on an
+     * in-flight promise, so calling it from inside the auth flow makes that promise await itself and it
+     * never settles (a silent hang rather than an error).
+     */
+    skipAuthRetry?: boolean;
 };
 
+/**
+ * Auth material is snapshotted into the request body (`reqBodyAuth`) and headers (`reqHeaders`) at the
+ * moment they are built. A request retried after a re-login therefore still carries the *old* token, so it
+ * fails with the very same token error that triggered the retry. Refresh those fields from the manager
+ * before retrying.
+ *
+ * Only keys that are already present with a non-empty string value are replaced. That leaves auth-flow
+ * payloads — which deliberately send `token: ''` / `accountID: ''` — untouched.
+ */
+function refreshAuthMaterial(
+    data: any,
+    headers: Record<string, string>,
+    manager: VeSync
+): [any, Record<string, string>] {
+    const token = manager.token;
+    const accountId = manager.accountId;
+    if (!token || !accountId) {
+        return [data, headers];
+    }
+
+    const replace = (target: Record<string, any>, key: string, value: string): void => {
+        if (typeof target[key] === 'string' && target[key].length > 0) {
+            target[key] = value;
+        }
+    };
+
+    let nextData = data;
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+        nextData = { ...data };
+        replace(nextData, 'token', token);
+        replace(nextData, 'accountID', accountId);
+        replace(nextData, 'accountId', accountId);
+    }
+
+    const nextHeaders = { ...headers };
+    replace(nextHeaders, 'tk', token);
+    replace(nextHeaders, 'token', token);
+    replace(nextHeaders, 'accountId', accountId);
+    replace(nextHeaders, 'accountID', accountId);
+
+    return [nextData, nextHeaders];
+}
+
 /**
  * Get list of country codes that use the US endpoint
  * These are tried when we get a cross-region error
@@ -564,18 +615,26 @@ export class Helpers {
             const responseMsg = response.data?.msg;
             if (
                 !didRetryAuth &&
+                !options.skipAuthRetry &&
                 response.status === 200 &&
                 (
                     (typeof responseCode === 'number' && isTokenError(responseCode)) ||
                     isTokenExpiredMessage(responseMsg)
                 )
             ) {
-                logger.debug('Token expired, attempting to re-login...');
+                logger.debug('VeSync rejected the session token; re-authenticating before retrying', {
+                    endpoint,
+                    code: responseCode
+                });
 
                 if (await manager.login()) {
-                    logger.debug('Re-login successful, retrying original request...');
-                    return await this.callApi(endpoint, method, data, headers, manager, { ...options, didRetryAuth: true });
+                    // Rebuild the auth fields; the original body/headers still hold the rejected token.
+                    const [retryData, retryHeaders] = refreshAuthMaterial(data, headers, manager);
+                    logger.debug('Re-authentication succeeded, retrying request with the refreshed token');
+                    return await this.callApi(endpoint, method, retryData, retryHeaders, manager, { ...options, didRetryAuth: true });
                 }
+
+                logger.debug('Re-authentication failed; returning the original token error to the caller');
             }
 
             return [response.data, response.status];
@@ -587,21 +646,29 @@ export class Helpers {
                 const httpStatus = error.response.status;
                 const msg: string | undefined = responseData?.msg;
                 const didRetryAuth = options.didRetryAuth === true;
-                if (!didRetryAuth && (
+                if (!didRetryAuth && !options.skipAuthRetry && (
                     httpStatus === 401 ||
                     httpStatus === 419 ||
                     responseData?.code === 4001004 ||
                     (typeof responseData?.code === 'number' && isTokenError(responseData.code)) ||
                     isTokenExpiredMessage(msg)
                 )) {
-                    logger.debug('Token expired, attempting to re-login...');
-                    
+                    logger.debug('VeSync rejected the session token; re-authenticating before retrying', {
+                        endpoint,
+                        status: httpStatus,
+                        code: responseData?.code
+                    });
+
                     // Re-login
                     if (await manager.login()) {
-                        // Retry the original request
-                        logger.debug('Re-login successful, retrying original request...');
-                        return await this.callApi(endpoint, method, data, headers, manager, { ...options, didRetryAuth: true });
+                        // Retry the original request with refreshed auth fields; the original body/headers
+                        // still hold the rejected token.
+                        const [retryData, retryHeaders] = refreshAuthMaterial(data, headers, manager);
+                        logger.debug('Re-authentication succeeded, retrying request with the refreshed token');
+                        return await this.callApi(endpoint, method, retryData, retryHeaders, manager, { ...options, didRetryAuth: true });
                     }
+
+                    logger.debug('Re-authentication failed; returning the original token error to the caller');
                 }
                 
                 // Log specific error details for debugging
@@ -697,7 +764,9 @@ export class Helpers {
     static async authNewFlow(manager: VeSync, appId: string, region: string = 'US', countryCodeOverride?: string): Promise<[boolean, string | null, string | null, string | null]> {
         try {
             // Generate terminal ID to be used in both steps
-            const terminalId = generateTerminalId();
+            // Reuse the manager's stable terminal id. VeSync binds issued tokens to it (the JWT carries a
+            // `terminalId` claim), and a fresh id on every login makes each login look like a new device.
+            const terminalId = manager.terminalId || generateTerminalId();
             // pyvesync parity:
             // - `userCountryCode` defaults to `DEFAULT_REGION` ("US"), even if we first try the EU base URL.
             // - If the account truly belongs to another region, the Step 2 response includes the correct
@@ -729,7 +798,8 @@ export class Helpers {
                 'post',
                 step1Body,
                 step1Headers,
-                manager
+                manager,
+                { skipAuthRetry: true }
             );
 
             if (!authResponse || authStatus !== 200) {
@@ -795,7 +865,8 @@ export class Helpers {
                 'post',
                 step2Body,
                 step1Headers,
-                manager
+                manager,
+                { skipAuthRetry: true }
             );
 
             logger.debug('Step 2 response:', { 
@@ -852,7 +923,8 @@ export class Helpers {
                             'post',
                             retryBody,
                             step1Headers,
-                            manager
+                            manager,
+                            { skipAuthRetry: true }
                         );
 
                         if (retryResponse && retryStatus === 200 && retryResponse.code === 0) {
@@ -919,7 +991,8 @@ export class Helpers {
                 'post',
                 body,
                 {},
-                manager
+                manager,
+                { skipAuthRetry: true }
             );
 
             if (!response || status !== 200) {

package/src/lib/session.ts

@@ -5,6 +5,14 @@ export interface Session {
   region: string;
   apiBaseUrl: string;
   authFlowUsed?: 'legacy' | 'new';
+  /**
+   * Identifies this installation to VeSync. Issued tokens are bound to it (the JWT payload carries a
+   * `terminalId` claim), so it must stay stable across logins and restarts — a fresh id makes every login
+   * look like a brand-new device to VeSync.
+   */
+  terminalId?: string;
+  /** Client app id, kept alongside `terminalId` so the client identity is stable too. */
+  appId?: string;
   issuedAt?: number | null; // epoch seconds
   expiresAt?: number | null; // epoch seconds
   lastValidatedAt?: number | null; // epoch ms

package/src/lib/vesync.ts

@@ -2,7 +2,7 @@
  * VeSync API Device Library
  */
 
-import { Helpers, API_RATE_LIMIT, DEFAULT_TZ, generateAppId, getRegionFromCountryCode, REGION_ENDPOINTS, getEndpointForCountryCode } from './helpers';
+import { Helpers, API_RATE_LIMIT, DEFAULT_TZ, generateAppId, generateTerminalId, getRegionFromCountryCode, REGION_ENDPOINTS, getEndpointForCountryCode } from './helpers';
 import { Session, SessionStore, decodeJwtTimestamps } from './session';
 import { VeSyncBaseDevice } from './vesyncBaseDevice';
 import { fanModules } from './vesyncFanImpl';
@@ -175,6 +175,7 @@ export class VeSync {
     private _inProcess: boolean;
     private _excludeConfig: ExcludeConfig | null;
     private _appId: string;
+    private _terminalId: string;
     private _region: string;
     private _countryCodeOverride: string | null;
     private _apiUrlOverride: string | null;
@@ -261,6 +262,9 @@ export class VeSync {
         this._lastUpdateTs = null;
         this._inProcess = false;
         this._appId = generateAppId();
+        // Stable per-installation identity. Overwritten by `hydrateSession` when a previous session is
+        // restored, so logins keep presenting the same terminal to VeSync.
+        this._terminalId = generateTerminalId();
 
         this.username = username;
         this.password = password;
@@ -322,6 +326,21 @@ export class VeSync {
         // Debug and redact are already set above in the options handling
     }
 
+    /**
+     * Adopt a previously persisted client identity without restoring credentials.
+     *
+     * Callers that decide not to reuse a stored token (because it has expired, say) should still keep the
+     * terminal/app id from that session, so the fresh login presents the same client to VeSync.
+     */
+    restoreClientIdentity(identity: { terminalId?: string | null; appId?: string | null }): void {
+        if (typeof identity?.terminalId === 'string' && identity.terminalId) {
+            this._terminalId = identity.terminalId;
+        }
+        if (typeof identity?.appId === 'string' && identity.appId) {
+            this._appId = identity.appId;
+        }
+    }
+
     /**
      * Hydrate manager from a previously persisted session
      */
@@ -337,6 +356,14 @@ export class VeSync {
             this.countryCode = session.countryCode ?? null;
             this.authFlowUsed = session.authFlowUsed;
 
+            // Keep the persisted client identity so re-logins present the same terminal to VeSync.
+            if (typeof session.terminalId === 'string' && session.terminalId) {
+                this._terminalId = session.terminalId;
+            }
+            if (typeof session.appId === 'string' && session.appId) {
+                this._appId = session.appId;
+            }
+
             // pyvesync parity:
             // pyvesync persists `current_region` and derives the API base URL per-request from that region.
             // It does NOT treat a stored base URL as authoritative. For backwards compatibility with older
@@ -396,6 +423,8 @@ export class VeSync {
             region: this._region,
             apiBaseUrl: this.apiBaseUrl,
             authFlowUsed: this.authFlowUsed,
+            terminalId: this._terminalId,
+            appId: this._appId,
             issuedAt: timestamps?.iat ?? null,
             expiresAt: timestamps?.exp ?? null,
             lastValidatedAt: Date.now(),
@@ -448,6 +477,14 @@ export class VeSync {
         return this._appId;
     }
 
+    /**
+     * Terminal id presented to VeSync during authentication. Issued tokens carry it as a JWT claim, so it
+     * is persisted with the session and reused across logins and restarts.
+     */
+    get terminalId(): string {
+        return this._terminalId;
+    }
+
     /**
      * Get current region
      */
@@ -605,6 +642,17 @@ export class VeSync {
         let success = false;
 
         try {
+            // A token whose `exp` has already passed can only come back as a token error, so refresh it
+            // up front instead of spending a request to be told so.
+            if (this.isTokenExpired()) {
+                logger.debug('Stored VeSync token is past its expiry; authenticating before requesting the device list');
+                if (!await this.login()) {
+                    logger.error('VeSync token had expired and re-authentication failed. Check the configured username/password (and country code if your account is not in the US).');
+                    this.enabled = false;
+                    return false;
+                }
+            }
+
             const fetchDeviceList = async (): Promise<[any, number]> => {
                 return await Helpers.callApi(
                     '/cloud/v1/deviceManaged/devices',
@@ -640,7 +688,9 @@ export class VeSync {
                 if (typeof code === 'number' && code !== 0) {
                     if (!didRetryToken && isTokenError(code)) {
                         didRetryToken = true;
-                        logger.warn('Device list request returned token error; re-authenticating and retrying (pyvesync parity)', {
+                        // Recoverable: re-authenticate and retry. Logged at debug because the retry below
+                        // normally succeeds; the outcome is reported after the loop.
+                        logger.debug('Device list request returned a token error; re-authenticating and retrying', {
                             code,
                             msg: response?.msg,
                             region: this._region,
@@ -648,6 +698,7 @@ export class VeSync {
                         });
                         const reloginOk = await this.login();
                         if (!reloginOk) {
+                            logger.error('VeSync rejected the stored session and re-authentication failed. Check the configured username/password (and country code if your account is not in the US).');
                             this.enabled = false;
                             return false;
                         }
@@ -688,6 +739,19 @@ export class VeSync {
                 break;
             }
 
+            if (didRetryToken) {
+                if (response && status === 200 && response.code === 0) {
+                    logger.info('VeSync session had expired; re-authenticated and recovered automatically.');
+                } else {
+                    logger.warn('VeSync session had expired and the request still failed after re-authenticating.', {
+                        code: response?.code,
+                        msg: response?.msg,
+                        region: this._region,
+                        endpoint: this.apiBaseUrl
+                    });
+                }
+            }
+
             if (!response) {
                 logger.error('No response received from VeSync API');
                 return false;
@@ -950,6 +1014,19 @@ export class VeSync {
         }
     }
 
+    /**
+     * True when the current token carries an `exp` claim that has already passed.
+     *
+     * Deliberately conservative: a token that cannot be decoded, or that has no `exp`, is treated as
+     * usable and left to the API to accept or reject.
+     */
+    isTokenExpired(skewSeconds: number = 60): boolean {
+        if (!this.token) return false;
+        const exp = decodeJwtTimestamps(this.token)?.exp;
+        if (!exp) return false;
+        return exp * 1000 <= Date.now() + skewSeconds * 1000;
+    }
+
     /**
      * Test if update interval has been exceeded
      */