tsvesync 1.1.2 → 1.2.0

package/dist/index.d.ts

@@ -6,3 +6,4 @@ export { VeSyncWallSwitch } from './lib/vesyncSwitchImpl';
 export { VeSyncBaseDevice } from './lib/vesyncBaseDevice';
 export { Helpers, setApiBaseUrl } from './lib/helpers';
 export { CREDENTIAL_ERROR_CODES, CROSS_REGION_ERROR_CODES, isCredentialError, isCrossRegionError } from './lib/constants';
+export { Session, SessionStore, decodeJwtTimestamps } from './lib/session';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isCrossRegionError = exports.isCredentialError = exports.CROSS_REGION_ERROR_CODES = exports.CREDENTIAL_ERROR_CODES = exports.setApiBaseUrl = exports.Helpers = exports.VeSyncBaseDevice = exports.VeSyncWallSwitch = exports.VeSyncBulb = exports.VeSyncOutdoorPlug = exports.VeSyncOutlet15A = exports.VeSyncOutlet10A = exports.VeSyncOutlet7A = exports.VeSyncAirBypass = exports.VeSync = void 0;
+exports.decodeJwtTimestamps = exports.isCrossRegionError = exports.isCredentialError = exports.CROSS_REGION_ERROR_CODES = exports.CREDENTIAL_ERROR_CODES = exports.setApiBaseUrl = exports.Helpers = exports.VeSyncBaseDevice = exports.VeSyncWallSwitch = exports.VeSyncBulb = exports.VeSyncOutdoorPlug = exports.VeSyncOutlet15A = exports.VeSyncOutlet10A = exports.VeSyncOutlet7A = exports.VeSyncAirBypass = exports.VeSync = void 0;
 // Export main VeSync manager class
 var vesync_1 = require("./lib/vesync");
 Object.defineProperty(exports, "VeSync", { enumerable: true, get: function () { return vesync_1.VeSync; } });
@@ -29,3 +29,6 @@ Object.defineProperty(exports, "CREDENTIAL_ERROR_CODES", { enumerable: true, get
 Object.defineProperty(exports, "CROSS_REGION_ERROR_CODES", { enumerable: true, get: function () { return constants_1.CROSS_REGION_ERROR_CODES; } });
 Object.defineProperty(exports, "isCredentialError", { enumerable: true, get: function () { return constants_1.isCredentialError; } });
 Object.defineProperty(exports, "isCrossRegionError", { enumerable: true, get: function () { return constants_1.isCrossRegionError; } });
+// Export session types and utilities
+var session_1 = require("./lib/session");
+Object.defineProperty(exports, "decodeJwtTimestamps", { enumerable: true, get: function () { return session_1.decodeJwtTimestamps; } });

package/dist/lib/helpers.js

@@ -400,8 +400,14 @@ class Helpers {
         catch (error) {
             if (error.response) {
                 const responseData = error.response.data;
-                // Check for token expiration
-                if ((responseData === null || responseData === void 0 ? void 0 : responseData.code) === 4001004 || (responseData === null || responseData === void 0 ? void 0 : responseData.msg) === "token expired") {
+                // Check for token expiration or auth invalidation
+                const httpStatus = error.response.status;
+                const msg = responseData === null || responseData === void 0 ? void 0 : responseData.msg;
+                if ((responseData === null || responseData === void 0 ? void 0 : responseData.code) === 4001004 ||
+                    msg === 'token expired' ||
+                    httpStatus === 401 ||
+                    httpStatus === 419 ||
+                    (typeof msg === 'string' && /token|login/i.test(msg))) {
                     logger_1.logger.debug('Token expired, attempting to re-login...');
                     // Re-login
                     if (await manager.login()) {

package/dist/lib/session.d.ts

@@ -0,0 +1,24 @@
+export interface Session {
+    token: string;
+    accountId: string;
+    countryCode?: string | null;
+    region: string;
+    apiBaseUrl: string;
+    authFlowUsed?: 'legacy' | 'new';
+    issuedAt?: number | null;
+    expiresAt?: number | null;
+    lastValidatedAt?: number | null;
+    libraryVersion?: string;
+}
+export interface SessionStore {
+    load(): Promise<Session | null>;
+    save(session: Session): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Decode a JWT token payload to extract iat/exp without verifying the signature.
+ */
+export declare function decodeJwtTimestamps(token: string): {
+    iat?: number;
+    exp?: number;
+} | null;

package/dist/lib/session.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeJwtTimestamps = decodeJwtTimestamps;
+/**
+ * Decode a JWT token payload to extract iat/exp without verifying the signature.
+ */
+function decodeJwtTimestamps(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return null;
+        const payload = JSON.parse(Buffer.from(parts[1].replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8'));
+        const iat = typeof payload.iat === 'number' ? payload.iat : undefined;
+        const exp = typeof payload.exp === 'number' ? payload.exp : undefined;
+        return { iat, exp };
+    }
+    catch (_a) {
+        return null;
+    }
+}

package/dist/lib/vesync.d.ts

@@ -1,6 +1,7 @@
 /**
  * VeSync API Device Library
  */
+import { Session, SessionStore } from './session';
 import { VeSyncBaseDevice } from './vesyncBaseDevice';
 import { Logger } from './logger';
 /**
@@ -28,6 +29,9 @@ export declare class VeSync {
     private _appId;
     private _region;
     private _countryCodeOverride;
+    private _sessionStore?;
+    private _onTokenChange?;
+    private _loginPromise;
     username: string;
     password: string;
     token: string | null;
@@ -64,7 +68,14 @@ export declare class VeSync {
         region?: string;
         countryCode?: string;
         debugMode?: boolean;
+        sessionStore?: SessionStore;
+        onTokenChange?: (session: Session) => void;
     }, redact?: boolean, apiUrl?: string, customLogger?: Logger, excludeConfig?: ExcludeConfig);
+    /**
+     * Hydrate manager from a previously persisted session
+     */
+    hydrateSession(session: Session): void;
+    private emitTokenChange;
     /**
      * Get/Set debug mode
      */

package/dist/lib/vesync.js

@@ -5,6 +5,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VeSync = void 0;
 const helpers_1 = require("./helpers");
+const session_1 = require("./session");
 const vesyncFanImpl_1 = require("./vesyncFanImpl");
 const vesyncOutletImpl_1 = require("./vesyncOutletImpl");
 const vesyncSwitchImpl_1 = require("./vesyncSwitchImpl");
@@ -132,6 +133,7 @@ class VeSync {
      * @param excludeConfig - Optional device exclusion configuration (used when optionsOrDebug is boolean)
      */
     constructor(username, password, timeZone = helpers_1.DEFAULT_TZ, optionsOrDebug = false, redact = true, apiUrl, customLogger, excludeConfig) {
+        this._loginPromise = null;
         // Handle options object or backward compatible parameters
         let options = {};
         if (typeof optionsOrDebug === 'object' && optionsOrDebug !== null) {
@@ -144,6 +146,8 @@ class VeSync {
             this._countryCodeOverride = options.countryCode || null;
             customLogger = options.customLogger;
             apiUrl = options.apiUrl;
+            this._sessionStore = options.sessionStore;
+            this._onTokenChange = options.onTokenChange;
         }
         else {
             // Using old parameter pattern for backward compatibility
@@ -221,6 +225,51 @@ class VeSync {
         }
         // Debug and redact are already set above in the options handling
     }
+    /**
+     * Hydrate manager from a previously persisted session
+     */
+    hydrateSession(session) {
+        try {
+            if (session.apiBaseUrl) {
+                (0, helpers_1.setApiBaseUrl)(session.apiBaseUrl);
+                this.apiBaseUrl = session.apiBaseUrl;
+            }
+            if (session.region) {
+                this._region = session.region;
+                (0, helpers_1.setCurrentRegion)(session.region);
+            }
+            this.token = session.token;
+            this.accountId = session.accountId;
+            this.countryCode = session.countryCode || null;
+            this.enabled = true;
+        }
+        catch (e) {
+            logger_1.logger.warn('Failed to hydrate session; will require fresh login');
+        }
+    }
+    emitTokenChange() {
+        var _a, _b, _c, _d;
+        if (!this.token || !this.accountId || !this.apiBaseUrl)
+            return;
+        const timestamps = (0, session_1.decodeJwtTimestamps)(this.token);
+        const session = {
+            token: this.token,
+            accountId: this.accountId,
+            countryCode: this.countryCode,
+            region: this._region,
+            apiBaseUrl: this.apiBaseUrl,
+            authFlowUsed: this.authFlowUsed,
+            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(),
+        };
+        // Best-effort persist and callback; errors are non-fatal
+        Promise.resolve((_c = this._sessionStore) === null || _c === void 0 ? void 0 : _c.save(session)).catch(() => { });
+        try {
+            (_d = this._onTokenChange) === null || _d === void 0 ? void 0 : _d.call(this, session);
+        }
+        catch ( /* noop */_e) { /* noop */ }
+    }
     /**
      * Get/Set debug mode
      */
@@ -461,148 +510,159 @@ class VeSync {
      * Login to VeSync server with new authentication flow and backwards compatibility
      */
     async login(retryAttempts = 3, initialDelayMs = 1000) {
-        logger_1.logger.debug('Starting VeSync authentication...', {
-            username: this.username,
-            appId: this._appId,
-            region: this._region
-        });
-        // Track which regions have been attempted to prevent infinite loops
-        const triedRegions = new Set();
-        for (let attempt = 0; attempt < retryAttempts; attempt++) {
-            try {
-                logger_1.logger.debug(`Authentication attempt ${attempt + 1} of ${retryAttempts}`);
-                // Skip email-based region detection for now since we'll handle cross-region errors
-                // The cross-region error handling below will automatically switch to the correct region
-                // Try new authentication flow first with detected region
-                let [success, token, accountId, countryCode] = await helpers_1.Helpers.authNewFlow(this, this._appId, this._region, this._countryCodeOverride || undefined);
-                // Track if new flow succeeded
-                if (success) {
-                    this.authFlowUsed = 'new';
-                }
-                if (!success) {
-                    // Check if it's a credential error (no point retrying)
-                    if (countryCode === 'credential_error') {
-                        logger_1.logger.error('Authentication failed due to invalid credentials');
-                        return false; // Exit immediately, don't retry
+        if (this._loginPromise) {
+            return this._loginPromise;
+        }
+        this._loginPromise = (async () => {
+            logger_1.logger.debug('Starting VeSync authentication...', {
+                username: this.username,
+                appId: this._appId,
+                region: this._region
+            });
+            // Track which regions have been attempted to prevent infinite loops
+            const triedRegions = new Set();
+            for (let attempt = 0; attempt < retryAttempts; attempt++) {
+                try {
+                    logger_1.logger.debug(`Authentication attempt ${attempt + 1} of ${retryAttempts}`);
+                    // Try new authentication flow first with detected region
+                    let [success, token, accountId, countryCode] = await helpers_1.Helpers.authNewFlow(this, this._appId, this._region, this._countryCodeOverride || undefined);
+                    // Track if new flow succeeded
+                    if (success) {
+                        this.authFlowUsed = 'new';
                     }
-                    // Check if we need to try a different region
-                    if (countryCode === 'cross_region' || countryCode === 'cross_region_retry') {
-                        // Mark current region as tried
-                        triedRegions.add(this._region);
-                        logger_1.logger.debug('Cross-region error detected, trying opposite region...');
-                        const alternateRegion = this._region === 'US' ? 'EU' : 'US';
-                        // Check if we've already tried this region to prevent infinite loops
-                        if (triedRegions.has(alternateRegion)) {
-                            logger_1.logger.error('═══════════════════════════════════════════════════════════════');
-                            logger_1.logger.error('AUTHENTICATION FAILED: COUNTRY CODE REQUIRED');
-                            logger_1.logger.error('');
-                            logger_1.logger.error('Both US and EU endpoints rejected your account.');
-                            logger_1.logger.error('This means you MUST specify your country code.');
-                            logger_1.logger.error('');
-                            logger_1.logger.error('SOLUTION:');
-                            logger_1.logger.error('1. In Homebridge UI:');
-                            logger_1.logger.error('   - Go to plugin settings');
-                            logger_1.logger.error('   - Select your country from the "Country Code" dropdown');
-                            logger_1.logger.error('');
-                            logger_1.logger.error('2. In config.json:');
-                            logger_1.logger.error('   Add: "countryCode": "YOUR_COUNTRY_CODE"');
-                            logger_1.logger.error('');
-                            logger_1.logger.error('Common non-US/EU country codes:');
-                            logger_1.logger.error('  🇦🇺 Australia: "AU"');
-                            logger_1.logger.error('  🇳🇿 New Zealand: "NZ"');
-                            logger_1.logger.error('  🇯🇵 Japan: "JP"');
-                            logger_1.logger.error('  🇨🇦 Canada: "CA"');
-                            logger_1.logger.error('  🇸🇬 Singapore: "SG"');
-                            logger_1.logger.error('  🇲🇽 Mexico: "MX"');
-                            logger_1.logger.error('═══════════════════════════════════════════════════════════════');
-                            return false;
-                        }
-                        logger_1.logger.debug(`Switching from ${this._region} to ${alternateRegion} region`);
-                        this._region = alternateRegion;
-                        (0, helpers_1.setCurrentRegion)(alternateRegion);
-                        // Update the API endpoint for the new region
-                        const regionEndpoints = {
-                            'US': 'https://smartapi.vesync.com',
-                            'EU': 'https://smartapi.vesync.eu'
-                        };
-                        if (alternateRegion in regionEndpoints) {
-                            (0, helpers_1.setApiBaseUrl)(regionEndpoints[alternateRegion]);
-                            logger_1.logger.debug(`API endpoint set to ${regionEndpoints[alternateRegion]}`);
+                    if (!success) {
+                        // Check if it's a credential error (no point retrying)
+                        if (countryCode === 'credential_error') {
+                            logger_1.logger.error('Authentication failed due to invalid credentials');
+                            return false; // Exit immediately, don't retry
                         }
-                        // Retry with the alternate region
-                        [success, token, accountId, countryCode] = await helpers_1.Helpers.authNewFlow(this, this._appId, alternateRegion, this._countryCodeOverride || undefined);
-                        if (success) {
-                            this.authFlowUsed = 'new';
-                            logger_1.logger.debug(`Authentication successful with ${alternateRegion} region`);
+                        // Check if we need to try a different region
+                        if (countryCode === 'cross_region' || countryCode === 'cross_region_retry') {
+                            // Mark current region as tried
+                            triedRegions.add(this._region);
+                            logger_1.logger.debug('Cross-region error detected, trying opposite region...');
+                            const alternateRegion = this._region === 'US' ? 'EU' : 'US';
+                            // Check if we've already tried this region to prevent infinite loops
+                            if (triedRegions.has(alternateRegion)) {
+                                logger_1.logger.error('═══════════════════════════════════════════════════════════════');
+                                logger_1.logger.error('AUTHENTICATION FAILED: COUNTRY CODE REQUIRED');
+                                logger_1.logger.error('');
+                                logger_1.logger.error('Both US and EU endpoints rejected your account.');
+                                logger_1.logger.error('This means you MUST specify your country code.');
+                                logger_1.logger.error('');
+                                logger_1.logger.error('SOLUTION:');
+                                logger_1.logger.error('1. In Homebridge UI:');
+                                logger_1.logger.error('   - Go to plugin settings');
+                                logger_1.logger.error('   - Select your country from the "Country Code" dropdown');
+                                logger_1.logger.error('');
+                                logger_1.logger.error('2. In config.json:');
+                                logger_1.logger.error('   Add: "countryCode": "YOUR_COUNTRY_CODE"');
+                                logger_1.logger.error('');
+                                logger_1.logger.error('Common non-US/EU country codes:');
+                                logger_1.logger.error('  🇦🇺 Australia: "AU"');
+                                logger_1.logger.error('  🇳🇿 New Zealand: "NZ"');
+                                logger_1.logger.error('  🇯🇵 Japan: "JP"');
+                                logger_1.logger.error('  🇨🇦 Canada: "CA"');
+                                logger_1.logger.error('  🇸🇬 Singapore: "SG"');
+                                logger_1.logger.error('  🇲🇽 Mexico: "MX"');
+                                logger_1.logger.error('═══════════════════════════════════════════════════════════════');
+                                return false;
+                            }
+                            logger_1.logger.debug(`Switching from ${this._region} to ${alternateRegion} region`);
+                            this._region = alternateRegion;
+                            (0, helpers_1.setCurrentRegion)(alternateRegion);
+                            // Update the API endpoint for the new region
+                            const regionEndpoints = {
+                                'US': 'https://smartapi.vesync.com',
+                                'EU': 'https://smartapi.vesync.eu'
+                            };
+                            if (alternateRegion in regionEndpoints) {
+                                (0, helpers_1.setApiBaseUrl)(regionEndpoints[alternateRegion]);
+                                logger_1.logger.debug(`API endpoint set to ${regionEndpoints[alternateRegion]}`);
+                            }
+                            // Retry with the alternate region
+                            [success, token, accountId, countryCode] = await helpers_1.Helpers.authNewFlow(this, this._appId, alternateRegion, this._countryCodeOverride || undefined);
+                            if (success) {
+                                this.authFlowUsed = 'new';
+                                logger_1.logger.debug(`Authentication successful with ${alternateRegion} region`);
+                            }
+                            else if (countryCode === 'cross_region' || countryCode === 'cross_region_retry') {
+                                // Both regions failed with cross-region error
+                                logger_1.logger.error('Authentication failed: Account rejected by both US and EU regions');
+                                logger_1.logger.error('This may indicate your account was created in a region not yet supported');
+                                logger_1.logger.error('Please contact VeSync support to determine your account region');
+                                // Don't retry further attempts as we've exhausted both regions
+                                return false;
+                            }
                         }
-                        else if (countryCode === 'cross_region' || countryCode === 'cross_region_retry') {
-                            // Both regions failed with cross-region error
-                            logger_1.logger.error('Authentication failed: Account rejected by both US and EU regions');
-                            logger_1.logger.error('This may indicate your account was created in a region not yet supported');
-                            logger_1.logger.error('Please contact VeSync support to determine your account region');
-                            // Don't retry further attempts as we've exhausted both regions
-                            return false;
+                        // If new flow still fails, try legacy authentication as fallback
+                        if (!success) {
+                            logger_1.logger.debug('New authentication flow failed, trying legacy flow...');
+                            [success, token, accountId, countryCode] = await helpers_1.Helpers.authLegacyFlow(this);
+                            if (success) {
+                                this.authFlowUsed = 'legacy';
+                            }
+                            else if (countryCode === 'credential_error') {
+                                // Legacy auth also detected bad credentials
+                                logger_1.logger.error('Both authentication methods report invalid credentials');
+                                return false; // Exit immediately
+                            }
                         }
                     }
-                    // If new flow still fails, try legacy authentication as fallback
-                    if (!success) {
-                        logger_1.logger.debug('New authentication flow failed, trying legacy flow...');
-                        [success, token, accountId, countryCode] = await helpers_1.Helpers.authLegacyFlow(this);
-                        if (success) {
-                            this.authFlowUsed = 'legacy';
-                        }
-                        else if (countryCode === 'credential_error') {
-                            // Legacy auth also detected bad credentials
-                            logger_1.logger.error('Both authentication methods report invalid credentials');
-                            return false; // Exit immediately
+                    if (success && token && accountId) {
+                        this.token = token;
+                        this.accountId = accountId;
+                        this.countryCode = countryCode;
+                        this.enabled = true;
+                        this.apiBaseUrl = (0, helpers_1.getApiBaseUrl)(); // Track the API endpoint being used
+                        // Persist session details for reuse across restarts
+                        this.emitTokenChange();
+                        // DO NOT change the region/endpoint after successful authentication!
+                        // The endpoint that successfully authenticated is the one we must continue using.
+                        // Tokens are endpoint-specific and won't work if we switch endpoints.
+                        // This is especially important for AU/NZ users who may authenticate via EU endpoint
+                        // but have AU/NZ country codes.
+                        // Log a warning if the country code doesn't match the successful region
+                        if (countryCode) {
+                            const expectedRegion = (0, helpers_1.getRegionFromCountryCode)(countryCode);
+                            if (expectedRegion !== this._region) {
+                                logger_1.logger.warn(`Note: Account authenticated with ${this._region} endpoint despite country code ${countryCode} typically using ${expectedRegion}`);
+                                logger_1.logger.warn(`This is normal for accounts created through different regional apps`);
+                            }
                         }
+                        logger_1.logger.debug('Authentication successful!', {
+                            authFlow: this.authFlowUsed,
+                            region: this._region,
+                            countryCode: countryCode,
+                            endpoint: (0, helpers_1.getApiBaseUrl)()
+                        });
+                        return true;
                     }
+                    // If we reach here, authentication failed
+                    const delay = initialDelayMs * Math.pow(2, attempt);
+                    logger_1.logger.debug(`Authentication attempt ${attempt + 1} failed, retrying in ${delay}ms...`);
+                    await new Promise(resolve => setTimeout(resolve, delay));
                 }
-                if (success && token && accountId) {
-                    this.token = token;
-                    this.accountId = accountId;
-                    this.countryCode = countryCode;
-                    this.enabled = true;
-                    this.apiBaseUrl = (0, helpers_1.getApiBaseUrl)(); // Track the API endpoint being used
-                    // DO NOT change the region/endpoint after successful authentication!
-                    // The endpoint that successfully authenticated is the one we must continue using.
-                    // Tokens are endpoint-specific and won't work if we switch endpoints.
-                    // This is especially important for AU/NZ users who may authenticate via EU endpoint
-                    // but have AU/NZ country codes.
-                    // Log a warning if the country code doesn't match the successful region
-                    if (countryCode) {
-                        const expectedRegion = (0, helpers_1.getRegionFromCountryCode)(countryCode);
-                        if (expectedRegion !== this._region) {
-                            logger_1.logger.warn(`Note: Account authenticated with ${this._region} endpoint despite country code ${countryCode} typically using ${expectedRegion}`);
-                            logger_1.logger.warn(`This is normal for accounts created through different regional apps`);
-                        }
+                catch (error) {
+                    logger_1.logger.error(`Authentication attempt ${attempt + 1} error:`, error);
+                    if (attempt === retryAttempts - 1) {
+                        logger_1.logger.error('Authentication failed after all retry attempts');
+                        return false;
                     }
-                    logger_1.logger.debug('Authentication successful!', {
-                        authFlow: this.authFlowUsed,
-                        region: this._region,
-                        countryCode: countryCode,
-                        endpoint: (0, helpers_1.getApiBaseUrl)()
-                    });
-                    return true;
-                }
-                // If we reach here, authentication failed
-                const delay = initialDelayMs * Math.pow(2, attempt);
-                logger_1.logger.debug(`Authentication attempt ${attempt + 1} failed, retrying in ${delay}ms...`);
-                await new Promise(resolve => setTimeout(resolve, delay));
-            }
-            catch (error) {
-                logger_1.logger.error(`Authentication attempt ${attempt + 1} error:`, error);
-                if (attempt === retryAttempts - 1) {
-                    logger_1.logger.error('Authentication failed after all retry attempts');
-                    return false;
+                    const delay = initialDelayMs * Math.pow(2, attempt);
+                    logger_1.logger.debug(`Retrying authentication in ${delay}ms...`);
+                    await new Promise(resolve => setTimeout(resolve, delay));
                 }
-                const delay = initialDelayMs * Math.pow(2, attempt);
-                logger_1.logger.debug(`Retrying authentication in ${delay}ms...`);
-                await new Promise(resolve => setTimeout(resolve, delay));
             }
+            logger_1.logger.error('Unable to authenticate with supplied credentials after all retry attempts');
+            return false;
+        })();
+        try {
+            return await this._loginPromise;
+        }
+        finally {
+            this._loginPromise = null;
         }
-        logger_1.logger.error('Unable to authenticate with supplied credentials after all retry attempts');
-        return false;
     }
     /**
      * Test if update interval has been exceeded

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tsvesync",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "A TypeScript library for interacting with VeSync smart home devices",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -19,4 +19,7 @@ export {
     CROSS_REGION_ERROR_CODES,
     isCredentialError,
     isCrossRegionError
-} from './lib/constants'; 
+} from './lib/constants'; 
+
+// Export session types and utilities
+export { Session, SessionStore, decodeJwtTimestamps } from './lib/session';

package/src/lib/helpers.ts

@@ -491,8 +491,16 @@ export class Helpers {
             if (error.response) {
                 const responseData = error.response.data;
                 
-                // Check for token expiration
-                if (responseData?.code === 4001004 || responseData?.msg === "token expired") {
+                // Check for token expiration or auth invalidation
+                const httpStatus = error.response.status;
+                const msg: string | undefined = responseData?.msg;
+                if (
+                    responseData?.code === 4001004 ||
+                    msg === 'token expired' ||
+                    httpStatus === 401 ||
+                    httpStatus === 419 ||
+                    (typeof msg === 'string' && /token|login/i.test(msg))
+                ) {
                     logger.debug('Token expired, attempting to re-login...');
                     
                     // Re-login
@@ -789,4 +797,4 @@ export class Helpers {
             return [false, null, null, null];
         }
     }
-} 
+} 

package/src/lib/session.ts

@@ -0,0 +1,35 @@
+export interface Session {
+  token: string;
+  accountId: string;
+  countryCode?: string | null;
+  region: string;
+  apiBaseUrl: string;
+  authFlowUsed?: 'legacy' | 'new';
+  issuedAt?: number | null; // epoch seconds
+  expiresAt?: number | null; // epoch seconds
+  lastValidatedAt?: number | null; // epoch ms
+  libraryVersion?: string;
+}
+
+export interface SessionStore {
+  load(): Promise<Session | null>;
+  save(session: Session): Promise<void>;
+  clear(): Promise<void>;
+}
+
+/**
+ * Decode a JWT token payload to extract iat/exp without verifying the signature.
+ */
+export function decodeJwtTimestamps(token: string): { iat?: number; exp?: number } | null {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) return null;
+    const payload = JSON.parse(Buffer.from(parts[1].replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8'));
+    const iat = typeof payload.iat === 'number' ? payload.iat : undefined;
+    const exp = typeof payload.exp === 'number' ? payload.exp : undefined;
+    return { iat, exp };
+  } catch {
+    return null;
+  }
+}
+

package/src/lib/vesync.ts

@@ -3,6 +3,7 @@
  */
 
 import { Helpers, API_RATE_LIMIT, DEFAULT_TZ, setApiBaseUrl, getApiBaseUrl, generateAppId, getRegionFromCountryCode, setCurrentRegion, getCurrentRegion, REGION_ENDPOINTS, getCountryCodeFromRegion, getEndpointForCountryCode } from './helpers';
+import { Session, SessionStore, decodeJwtTimestamps } from './session';
 import { VeSyncBaseDevice } from './vesyncBaseDevice';
 import { fanModules } from './vesyncFanImpl';
 import { outletModules } from './vesyncOutletImpl';
@@ -162,6 +163,9 @@ export class VeSync {
     private _appId: string;
     private _region: string;
     private _countryCodeOverride: string | null;
+    private _sessionStore?: SessionStore;
+    private _onTokenChange?: (session: Session) => void;
+    private _loginPromise: Promise<boolean> | null = null;
 
     username: string;
     password: string;
@@ -205,6 +209,8 @@ export class VeSync {
             region?: string;
             countryCode?: string;  // Override country code for Step 2 authentication
             debugMode?: boolean;  // Alias for debug
+            sessionStore?: SessionStore;
+            onTokenChange?: (session: Session) => void;
         } = false,
         redact = true,
         apiUrl?: string,
@@ -223,6 +229,8 @@ export class VeSync {
             this._countryCodeOverride = options.countryCode || null;
             customLogger = options.customLogger;
             apiUrl = options.apiUrl;
+            this._sessionStore = options.sessionStore;
+            this._onTokenChange = options.onTokenChange;
         } else {
             // Using old parameter pattern for backward compatibility
             this._debug = optionsOrDebug as boolean;
@@ -306,6 +314,47 @@ export class VeSync {
         // Debug and redact are already set above in the options handling
     }
 
+    /**
+     * Hydrate manager from a previously persisted session
+     */
+    hydrateSession(session: Session): void {
+        try {
+            if (session.apiBaseUrl) {
+                setApiBaseUrl(session.apiBaseUrl);
+                this.apiBaseUrl = session.apiBaseUrl;
+            }
+            if (session.region) {
+                this._region = session.region;
+                setCurrentRegion(session.region);
+            }
+            this.token = session.token;
+            this.accountId = session.accountId;
+            this.countryCode = session.countryCode || null;
+            this.enabled = true;
+        } catch (e) {
+            logger.warn('Failed to hydrate session; will require fresh login');
+        }
+    }
+
+    private emitTokenChange(): void {
+        if (!this.token || !this.accountId || !this.apiBaseUrl) return;
+        const timestamps = decodeJwtTimestamps(this.token);
+        const session: Session = {
+            token: this.token,
+            accountId: this.accountId,
+            countryCode: this.countryCode,
+            region: this._region,
+            apiBaseUrl: this.apiBaseUrl,
+            authFlowUsed: this.authFlowUsed,
+            issuedAt: timestamps?.iat ?? null,
+            expiresAt: timestamps?.exp ?? null,
+            lastValidatedAt: Date.now(),
+        };
+        // Best-effort persist and callback; errors are non-fatal
+        Promise.resolve(this._sessionStore?.save(session)).catch(() => {});
+        try { this._onTokenChange?.(session); } catch { /* noop */ }
+    }
+
     /**
      * Get/Set debug mode
      */
@@ -576,168 +625,179 @@ export class VeSync {
      * Login to VeSync server with new authentication flow and backwards compatibility
      */
     async login(retryAttempts: number = 3, initialDelayMs: number = 1000): Promise<boolean> {
-        logger.debug('Starting VeSync authentication...', {
-            username: this.username,
-            appId: this._appId,
-            region: this._region
-        });
-
-        // Track which regions have been attempted to prevent infinite loops
-        const triedRegions = new Set<string>();
-
-        for (let attempt = 0; attempt < retryAttempts; attempt++) {
-            try {
-                logger.debug(`Authentication attempt ${attempt + 1} of ${retryAttempts}`);
+        if (this._loginPromise) {
+            return this._loginPromise;
+        }
+        this._loginPromise = (async () => {
+            logger.debug('Starting VeSync authentication...', {
+                username: this.username,
+                appId: this._appId,
+                region: this._region
+            });
 
-                // Skip email-based region detection for now since we'll handle cross-region errors
-                // The cross-region error handling below will automatically switch to the correct region
+            // Track which regions have been attempted to prevent infinite loops
+            const triedRegions = new Set<string>();
 
-                // Try new authentication flow first with detected region
-                let [success, token, accountId, countryCode] = await Helpers.authNewFlow(this, this._appId, this._region, this._countryCodeOverride || undefined);
-                
-                // Track if new flow succeeded
-                if (success) {
-                    this.authFlowUsed = 'new';
-                }
+            for (let attempt = 0; attempt < retryAttempts; attempt++) {
+                try {
+                    logger.debug(`Authentication attempt ${attempt + 1} of ${retryAttempts}`);
 
-                if (!success) {
-                    // Check if it's a credential error (no point retrying)
-                    if (countryCode === 'credential_error') {
-                        logger.error('Authentication failed due to invalid credentials');
-                        return false;  // Exit immediately, don't retry
-                    }
+                    // Try new authentication flow first with detected region
+                    let [success, token, accountId, countryCode] = await Helpers.authNewFlow(this, this._appId, this._region, this._countryCodeOverride || undefined);
                     
-                    // Check if we need to try a different region
-                    if (countryCode === 'cross_region' || countryCode === 'cross_region_retry') {
-                        // Mark current region as tried
-                        triedRegions.add(this._region);
-                        
-                        logger.debug('Cross-region error detected, trying opposite region...');
-                        const alternateRegion = this._region === 'US' ? 'EU' : 'US';
-                        
-                        // Check if we've already tried this region to prevent infinite loops
-                        if (triedRegions.has(alternateRegion)) {
-                            logger.error('═══════════════════════════════════════════════════════════════');
-                            logger.error('AUTHENTICATION FAILED: COUNTRY CODE REQUIRED');
-                            logger.error('');
-                            logger.error('Both US and EU endpoints rejected your account.');
-                            logger.error('This means you MUST specify your country code.');
-                            logger.error('');
-                            logger.error('SOLUTION:');
-                            logger.error('1. In Homebridge UI:');
-                            logger.error('   - Go to plugin settings');
-                            logger.error('   - Select your country from the "Country Code" dropdown');
-                            logger.error('');
-                            logger.error('2. In config.json:');
-                            logger.error('   Add: "countryCode": "YOUR_COUNTRY_CODE"');
-                            logger.error('');
-                            logger.error('Common non-US/EU country codes:');
-                            logger.error('  🇦🇺 Australia: "AU"');
-                            logger.error('  🇳🇿 New Zealand: "NZ"');
-                            logger.error('  🇯🇵 Japan: "JP"');
-                            logger.error('  🇨🇦 Canada: "CA"');
-                            logger.error('  🇸🇬 Singapore: "SG"');
-                            logger.error('  🇲🇽 Mexico: "MX"');
-                            logger.error('═══════════════════════════════════════════════════════════════');
-                            return false;
+                    // Track if new flow succeeded
+                    if (success) {
+                        this.authFlowUsed = 'new';
+                    }
+
+                    if (!success) {
+                        // Check if it's a credential error (no point retrying)
+                        if (countryCode === 'credential_error') {
+                            logger.error('Authentication failed due to invalid credentials');
+                            return false;  // Exit immediately, don't retry
                         }
                         
-                        logger.debug(`Switching from ${this._region} to ${alternateRegion} region`);
-                        
-                        this._region = alternateRegion;
-                        setCurrentRegion(alternateRegion);
-                        
-                        // Update the API endpoint for the new region
-                        const regionEndpoints: Record<string, string> = {
-                            'US': 'https://smartapi.vesync.com',
-                            'EU': 'https://smartapi.vesync.eu'
-                        };
-                        if (alternateRegion in regionEndpoints) {
-                            setApiBaseUrl(regionEndpoints[alternateRegion]);
-                            logger.debug(`API endpoint set to ${regionEndpoints[alternateRegion]}`);
+                        // Check if we need to try a different region
+                        if (countryCode === 'cross_region' || countryCode === 'cross_region_retry') {
+                            // Mark current region as tried
+                            triedRegions.add(this._region);
+                            
+                            logger.debug('Cross-region error detected, trying opposite region...');
+                            const alternateRegion = this._region === 'US' ? 'EU' : 'US';
+                            
+                            // Check if we've already tried this region to prevent infinite loops
+                            if (triedRegions.has(alternateRegion)) {
+                                logger.error('═══════════════════════════════════════════════════════════════');
+                                logger.error('AUTHENTICATION FAILED: COUNTRY CODE REQUIRED');
+                                logger.error('');
+                                logger.error('Both US and EU endpoints rejected your account.');
+                                logger.error('This means you MUST specify your country code.');
+                                logger.error('');
+                                logger.error('SOLUTION:');
+                                logger.error('1. In Homebridge UI:');
+                                logger.error('   - Go to plugin settings');
+                                logger.error('   - Select your country from the "Country Code" dropdown');
+                                logger.error('');
+                                logger.error('2. In config.json:');
+                                logger.error('   Add: "countryCode": "YOUR_COUNTRY_CODE"');
+                                logger.error('');
+                                logger.error('Common non-US/EU country codes:');
+                                logger.error('  🇦🇺 Australia: "AU"');
+                                logger.error('  🇳🇿 New Zealand: "NZ"');
+                                logger.error('  🇯🇵 Japan: "JP"');
+                                logger.error('  🇨🇦 Canada: "CA"');
+                                logger.error('  🇸🇬 Singapore: "SG"');
+                                logger.error('  🇲🇽 Mexico: "MX"');
+                                logger.error('═══════════════════════════════════════════════════════════════');
+                                return false;
+                            }
+                            
+                            logger.debug(`Switching from ${this._region} to ${alternateRegion} region`);
+                            
+                            this._region = alternateRegion;
+                            setCurrentRegion(alternateRegion);
+                            
+                            // Update the API endpoint for the new region
+                            const regionEndpoints: Record<string, string> = {
+                                'US': 'https://smartapi.vesync.com',
+                                'EU': 'https://smartapi.vesync.eu'
+                            };
+                            if (alternateRegion in regionEndpoints) {
+                                setApiBaseUrl(regionEndpoints[alternateRegion]);
+                                logger.debug(`API endpoint set to ${regionEndpoints[alternateRegion]}`);
+                            }
+                            
+                            // Retry with the alternate region
+                            [success, token, accountId, countryCode] = await Helpers.authNewFlow(this, this._appId, alternateRegion, this._countryCodeOverride || undefined);
+                            if (success) {
+                                this.authFlowUsed = 'new';
+                                logger.debug(`Authentication successful with ${alternateRegion} region`);
+                            } else if (countryCode === 'cross_region' || countryCode === 'cross_region_retry') {
+                                // Both regions failed with cross-region error
+                                logger.error('Authentication failed: Account rejected by both US and EU regions');
+                                logger.error('This may indicate your account was created in a region not yet supported');
+                                logger.error('Please contact VeSync support to determine your account region');
+                                // Don't retry further attempts as we've exhausted both regions
+                                return false;
+                            }
                         }
-                        
-                        // Retry with the alternate region
-                        [success, token, accountId, countryCode] = await Helpers.authNewFlow(this, this._appId, alternateRegion, this._countryCodeOverride || undefined);
-                        if (success) {
-                            this.authFlowUsed = 'new';
-                            logger.debug(`Authentication successful with ${alternateRegion} region`);
-                        } else if (countryCode === 'cross_region' || countryCode === 'cross_region_retry') {
-                            // Both regions failed with cross-region error
-                            logger.error('Authentication failed: Account rejected by both US and EU regions');
-                            logger.error('This may indicate your account was created in a region not yet supported');
-                            logger.error('Please contact VeSync support to determine your account region');
-                            // Don't retry further attempts as we've exhausted both regions
-                            return false;
+
+                        // If new flow still fails, try legacy authentication as fallback
+                        if (!success) {
+                            logger.debug('New authentication flow failed, trying legacy flow...');
+                            [success, token, accountId, countryCode] = await Helpers.authLegacyFlow(this);
+                            if (success) {
+                                this.authFlowUsed = 'legacy';
+                            } else if (countryCode === 'credential_error') {
+                                // Legacy auth also detected bad credentials
+                                logger.error('Both authentication methods report invalid credentials');
+                                return false;  // Exit immediately
+                            }
                         }
                     }
 
-                    // If new flow still fails, try legacy authentication as fallback
-                    if (!success) {
-                        logger.debug('New authentication flow failed, trying legacy flow...');
-                        [success, token, accountId, countryCode] = await Helpers.authLegacyFlow(this);
-                        if (success) {
-                            this.authFlowUsed = 'legacy';
-                        } else if (countryCode === 'credential_error') {
-                            // Legacy auth also detected bad credentials
-                            logger.error('Both authentication methods report invalid credentials');
-                            return false;  // Exit immediately
+                    if (success && token && accountId) {
+                        this.token = token;
+                        this.accountId = accountId;
+                        this.countryCode = countryCode;
+                        this.enabled = true;
+                        this.apiBaseUrl = getApiBaseUrl();  // Track the API endpoint being used
+
+                        // Persist session details for reuse across restarts
+                        this.emitTokenChange();
+
+                        // DO NOT change the region/endpoint after successful authentication!
+                        // The endpoint that successfully authenticated is the one we must continue using.
+                        // Tokens are endpoint-specific and won't work if we switch endpoints.
+                        // This is especially important for AU/NZ users who may authenticate via EU endpoint
+                        // but have AU/NZ country codes.
+                        
+                        // Log a warning if the country code doesn't match the successful region
+                        if (countryCode) {
+                            const expectedRegion = getRegionFromCountryCode(countryCode);
+                            if (expectedRegion !== this._region) {
+                                logger.warn(`Note: Account authenticated with ${this._region} endpoint despite country code ${countryCode} typically using ${expectedRegion}`);
+                                logger.warn(`This is normal for accounts created through different regional apps`);
+                            }
                         }
+
+                        logger.debug('Authentication successful!', {
+                            authFlow: this.authFlowUsed,
+                            region: this._region,
+                            countryCode: countryCode,
+                            endpoint: getApiBaseUrl()
+                        });
+                        return true;
                     }
-                }
 
-                if (success && token && accountId) {
-                    this.token = token;
-                    this.accountId = accountId;
-                    this.countryCode = countryCode;
-                    this.enabled = true;
-                    this.apiBaseUrl = getApiBaseUrl();  // Track the API endpoint being used
-
-                    // DO NOT change the region/endpoint after successful authentication!
-                    // The endpoint that successfully authenticated is the one we must continue using.
-                    // Tokens are endpoint-specific and won't work if we switch endpoints.
-                    // This is especially important for AU/NZ users who may authenticate via EU endpoint
-                    // but have AU/NZ country codes.
+                    // If we reach here, authentication failed
+                    const delay = initialDelayMs * Math.pow(2, attempt);
+                    logger.debug(`Authentication attempt ${attempt + 1} failed, retrying in ${delay}ms...`);
+                    await new Promise(resolve => setTimeout(resolve, delay));
+
+                } catch (error) {
+                    logger.error(`Authentication attempt ${attempt + 1} error:`, error);
                     
-                    // Log a warning if the country code doesn't match the successful region
-                    if (countryCode) {
-                        const expectedRegion = getRegionFromCountryCode(countryCode);
-                        if (expectedRegion !== this._region) {
-                            logger.warn(`Note: Account authenticated with ${this._region} endpoint despite country code ${countryCode} typically using ${expectedRegion}`);
-                            logger.warn(`This is normal for accounts created through different regional apps`);
-                        }
+                    if (attempt === retryAttempts - 1) {
+                        logger.error('Authentication failed after all retry attempts');
+                        return false;
                     }
 
-                    logger.debug('Authentication successful!', {
-                        authFlow: this.authFlowUsed,
-                        region: this._region,
-                        countryCode: countryCode,
-                        endpoint: getApiBaseUrl()
-                    });
-                    return true;
+                    const delay = initialDelayMs * Math.pow(2, attempt);
+                    logger.debug(`Retrying authentication in ${delay}ms...`);
+                    await new Promise(resolve => setTimeout(resolve, delay));
                 }
+            }
 
-                // If we reach here, authentication failed
-                const delay = initialDelayMs * Math.pow(2, attempt);
-                logger.debug(`Authentication attempt ${attempt + 1} failed, retrying in ${delay}ms...`);
-                await new Promise(resolve => setTimeout(resolve, delay));
-
-            } catch (error) {
-                logger.error(`Authentication attempt ${attempt + 1} error:`, error);
-                
-                if (attempt === retryAttempts - 1) {
-                    logger.error('Authentication failed after all retry attempts');
-                    return false;
-                }
+            logger.error('Unable to authenticate with supplied credentials after all retry attempts');
+            return false;
+        })();
 
-                const delay = initialDelayMs * Math.pow(2, attempt);
-                logger.debug(`Retrying authentication in ${delay}ms...`);
-                await new Promise(resolve => setTimeout(resolve, delay));
-            }
+        try {
+            return await this._loginPromise;
+        } finally {
+            this._loginPromise = null;
         }
-
-        logger.error('Unable to authenticate with supplied credentials after all retry attempts');
-        return false;
     }
 
     /**
@@ -858,4 +918,4 @@ export class VeSync {
     ): Promise<[any, number]> {
         return await Helpers.callApi(endpoint, method, data, headers, this);
     }
-} 
+}