tsvesync 1.0.102 → 1.0.104

package/README.md

@@ -6,8 +6,10 @@ A TypeScript library for interacting with VeSync smart home devices. This librar
 
 - **Enhanced Authentication**: Now supports the new VeSync authentication flow (pyvesync PR #340) with automatic fallback to legacy authentication
 - **Regional API Support**: Automatic detection and routing for US (`smartapi.vesync.com`) and EU (`smartapi.vesync.eu`) endpoints
-- **Improved Error Handling**: Better recovery from API changes and authentication errors
-- **Cross-Region Support**: Handles cross-region authentication errors automatically
+- **International Account Support**: Full support for accounts worldwide including Australia, New Zealand, Japan, and all European countries
+- **Country Code Configuration**: Specify your country code for proper authentication with international accounts
+- **Improved Error Handling**: Better recovery from API changes and authentication errors with helpful guidance
+- **Cross-Region Support**: Automatic handling of cross-region authentication errors
 
 ## Features
 
@@ -176,6 +178,68 @@ await manager.login();
 await manager.getDevices();
 ```
 
+### International Account Support
+
+For accounts created outside the United States, you may need to specify your country code:
+
+```typescript
+import { VeSync } from 'tsvesync';
+
+// For Australian users
+const manager = new VeSync(username, password, 'America/Sydney', {
+    countryCode: 'AU'
+});
+
+// For German users
+const manager = new VeSync(username, password, 'Europe/Berlin', {
+    countryCode: 'DE'
+});
+
+// For UK users
+const manager = new VeSync(username, password, 'Europe/London', {
+    countryCode: 'GB'
+});
+
+await manager.login();
+```
+
+#### Supported Country Codes
+
+The library supports all country codes. Common ones include:
+
+**Americas:**
+- `US` - United States (default)
+- `CA` - Canada
+- `MX` - Mexico
+
+**Europe:** (uses EU endpoint)
+- `GB` - United Kingdom
+- `DE` - Germany
+- `FR` - France
+- `IT` - Italy
+- `ES` - Spain
+- `NL` - Netherlands
+- `SE` - Sweden
+- `NO` - Norway
+- `DK` - Denmark
+- `FI` - Finland
+- `PL` - Poland
+- And all other European countries
+
+**Asia-Pacific:** (uses US endpoint)
+- `AU` - Australia
+- `NZ` - New Zealand
+- `JP` - Japan
+- `SG` - Singapore
+- `CN` - China
+- `KR` - South Korea
+
+**Important Notes:**
+- If you get an authentication error about "country code mismatch" or "cross-region error", you need to set your country code
+- The country code should match the country where your VeSync account was created
+- European countries automatically use the EU endpoint (`smartapi.vesync.eu`)
+- All other countries use the US endpoint (`smartapi.vesync.com`)
+
 ### Working with Devices
 
 ```typescript

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export { VeSyncBulb } from './lib/vesyncBulb';
 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';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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.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; } });
@@ -23,3 +23,9 @@ Object.defineProperty(exports, "VeSyncBaseDevice", { enumerable: true, get: func
 var helpers_1 = require("./lib/helpers");
 Object.defineProperty(exports, "Helpers", { enumerable: true, get: function () { return helpers_1.Helpers; } });
 Object.defineProperty(exports, "setApiBaseUrl", { enumerable: true, get: function () { return helpers_1.setApiBaseUrl; } });
+// Export constants
+var constants_1 = require("./lib/constants");
+Object.defineProperty(exports, "CREDENTIAL_ERROR_CODES", { enumerable: true, get: function () { return constants_1.CREDENTIAL_ERROR_CODES; } });
+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; } });

package/dist/lib/constants.d.ts

@@ -0,0 +1,14 @@
+/**
+ * VeSync API Error Codes
+ */
+export declare const CREDENTIAL_ERROR_CODES: number[];
+export declare const CROSS_REGION_ERROR_CODES: number[];
+export declare const APP_VERSION_ERROR_CODES: number[];
+/**
+ * Check if an error code indicates bad credentials
+ */
+export declare function isCredentialError(code: number): boolean;
+/**
+ * Check if an error code indicates cross-region issue
+ */
+export declare function isCrossRegionError(code: number): boolean;

package/dist/lib/constants.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * VeSync API Error Codes
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APP_VERSION_ERROR_CODES = exports.CROSS_REGION_ERROR_CODES = exports.CREDENTIAL_ERROR_CODES = void 0;
+exports.isCredentialError = isCredentialError;
+exports.isCrossRegionError = isCrossRegionError;
+// Authentication error codes that indicate bad credentials (no point retrying)
+exports.CREDENTIAL_ERROR_CODES = [
+    -11201129, // account or password incorrect
+    -11202129, // the account does not exist
+    -11000129, // illegal argument (empty credentials)
+];
+// Cross-region error codes that require region switching
+exports.CROSS_REGION_ERROR_CODES = [
+    -11260022, // cross region error
+    -11261022, // access region conflict error
+];
+// Other error codes
+exports.APP_VERSION_ERROR_CODES = [
+    -11012022, // app version is too low
+];
+/**
+ * Check if an error code indicates bad credentials
+ */
+function isCredentialError(code) {
+    return exports.CREDENTIAL_ERROR_CODES.includes(code);
+}
+/**
+ * Check if an error code indicates cross-region issue
+ */
+function isCrossRegionError(code) {
+    return exports.CROSS_REGION_ERROR_CODES.includes(code);
+}

package/dist/lib/helpers.d.ts

@@ -26,7 +26,6 @@ export declare const REGION_ENDPOINTS: {
     JP: string;
     EU: string;
 };
-export declare const CROSS_REGION_ERROR_CODES: number[];
 export declare const APP_VERSION_TOO_LOW_ERROR_CODE = -11012022;
 export declare const AUTH_ERROR_CODES: {
     ACCOUNT_PASSWORD_INCORRECT: number;
@@ -34,6 +33,15 @@ export declare const AUTH_ERROR_CODES: {
     CROSS_REGION: number;
     CROSS_REGION_ALT: number;
 };
+/**
+ * Get list of country codes that use the US endpoint
+ * These are tried when we get a cross-region error
+ */
+export declare function getUSEndpointCountryCodes(): string[];
+/**
+ * Get the appropriate API endpoint based on country code
+ */
+export declare function getEndpointForCountryCode(countryCode: string): 'US' | 'EU';
 /**
  * Detect user's home region from email domain or country hints
  */
@@ -159,7 +167,7 @@ export declare class Helpers {
     /**
      * Perform new two-step authentication flow
      */
-    static authNewFlow(manager: VeSync, appId: string, region?: string): Promise<[boolean, string | null, string | null, string | null]>;
+    static authNewFlow(manager: VeSync, appId: string, region?: string, countryCodeOverride?: string): Promise<[boolean, string | null, string | null, string | null]>;
     /**
      * Perform legacy authentication (fallback)
      */

package/dist/lib/helpers.js

@@ -6,12 +6,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Helpers = exports.AUTH_ERROR_CODES = exports.APP_VERSION_TOO_LOW_ERROR_CODE = exports.CROSS_REGION_ERROR_CODES = exports.REGION_ENDPOINTS = exports.CLIENT_VERSION = exports.BYPASS_HEADER_UA = exports.MOBILE_ID = exports.DEFAULT_REGION = exports.DEFAULT_TZ = exports.USER_TYPE = exports.CLIENT_INFO = exports.PHONE_OS = exports.PHONE_BRAND = exports.APP_VERSION = exports.API_TIMEOUT = exports.API_RATE_LIMIT = void 0;
+exports.Helpers = exports.AUTH_ERROR_CODES = exports.APP_VERSION_TOO_LOW_ERROR_CODE = exports.REGION_ENDPOINTS = exports.CLIENT_VERSION = exports.BYPASS_HEADER_UA = exports.MOBILE_ID = exports.DEFAULT_REGION = exports.DEFAULT_TZ = exports.USER_TYPE = exports.CLIENT_INFO = exports.PHONE_OS = exports.PHONE_BRAND = exports.APP_VERSION = exports.API_TIMEOUT = exports.API_RATE_LIMIT = void 0;
 exports.getApiBaseUrl = getApiBaseUrl;
 exports.setApiBaseUrl = setApiBaseUrl;
 exports.getCurrentRegion = getCurrentRegion;
 exports.setCurrentRegion = setCurrentRegion;
 exports.getRegionFromCountryCode = getRegionFromCountryCode;
+exports.getUSEndpointCountryCodes = getUSEndpointCountryCodes;
+exports.getEndpointForCountryCode = getEndpointForCountryCode;
 exports.detectUserRegion = detectUserRegion;
 exports.getCountryCodeFromRegion = getCountryCodeFromRegion;
 exports.generateAppId = generateAppId;
@@ -19,6 +21,7 @@ exports.generateTerminalId = generateTerminalId;
 const axios_1 = __importDefault(require("axios"));
 const crypto_1 = __importDefault(require("crypto"));
 const logger_1 = require("./logger");
+const constants_1 = require("./constants");
 // API configuration - Support regional endpoints
 let _apiBaseUrl = 'https://smartapi.vesync.com';
 let _currentRegion = 'US';
@@ -72,7 +75,7 @@ exports.REGION_ENDPOINTS = {
     'EU': 'https://smartapi.vesync.eu'
 };
 // Cross-region error codes - multiple versions exist
-exports.CROSS_REGION_ERROR_CODES = [-11260022, -11261022];
+// CROSS_REGION_ERROR_CODES moved to constants.ts
 exports.APP_VERSION_TOO_LOW_ERROR_CODE = -11012022;
 // Authentication error codes
 exports.AUTH_ERROR_CODES = {
@@ -81,6 +84,38 @@ exports.AUTH_ERROR_CODES = {
     CROSS_REGION: -11260022,
     CROSS_REGION_ALT: -11261022
 };
+/**
+ * Get list of country codes that use the US endpoint
+ * These are tried when we get a cross-region error
+ */
+function getUSEndpointCountryCodes() {
+    // Countries that use the US endpoint but might need their own country code
+    return ['US', 'AU', 'NZ', 'JP', 'CA', 'MX', 'SG'];
+}
+/**
+ * Get the appropriate API endpoint based on country code
+ */
+function getEndpointForCountryCode(countryCode) {
+    // European country codes that should use the EU endpoint
+    const euCountryCodes = [
+        // Western Europe
+        'GB', 'DE', 'FR', 'IT', 'ES', 'NL', 'BE', 'AT', 'CH', 'IE', 'PT', 'LU',
+        // Nordic countries
+        'SE', 'NO', 'DK', 'FI', 'IS',
+        // Eastern Europe
+        'PL', 'CZ', 'HU', 'RO', 'BG', 'HR', 'SI', 'SK', 'LT', 'LV', 'EE',
+        // Southern Europe
+        'GR', 'CY', 'MT',
+        // Other European
+        'AL', 'BA', 'RS', 'ME', 'MK', 'MD', 'UA', 'BY'
+    ];
+    // Check if country code is in EU list
+    if (euCountryCodes.includes(countryCode)) {
+        return 'EU';
+    }
+    // Everything else uses US endpoint (including AU, NZ, JP, CA, MX, etc.)
+    return 'US';
+}
 /**
  * Detect user's home region from email domain or country hints
  */
@@ -455,7 +490,7 @@ class Helpers {
     /**
      * Perform new two-step authentication flow
      */
-    static async authNewFlow(manager, appId, region = 'US') {
+    static async authNewFlow(manager, appId, region = 'US', countryCodeOverride) {
         try {
             // Generate terminal ID to be used in both steps
             const terminalId = generateTerminalId();
@@ -480,8 +515,14 @@ class Helpers {
             }
             if (authResponse.code !== 0) {
                 logger_1.logger.error('Step 1 error code:', authResponse.code, 'message:', authResponse.msg);
+                // Check if it's a credential error (no point retrying)
+                if ((0, constants_1.isCredentialError)(authResponse.code)) {
+                    logger_1.logger.error('Credential error detected - invalid username or password');
+                    setApiBaseUrl(originalUrl); // Restore original URL
+                    return [false, null, null, 'credential_error'];
+                }
                 // Handle cross-region error (multiple error codes possible)
-                if (exports.CROSS_REGION_ERROR_CODES.includes(authResponse.code)) {
+                if ((0, constants_1.isCrossRegionError)(authResponse.code)) {
                     logger_1.logger.debug('Cross-region error detected:', authResponse.code, 'will try different region');
                     setApiBaseUrl(originalUrl); // Restore original URL
                     return [false, null, null, 'cross_region'];
@@ -497,61 +538,46 @@ class Helpers {
             }
             logger_1.logger.debug('Step 1 successful, got authorization code');
             // Step 2: Login with authorization code
-            // Use the appropriate country code based on the region we're authenticating with
-            const countryCodeForStep2 = region === 'EU' ? 'DE' : 'US';
+            // Use the override if provided, otherwise default to 'US'
+            // Users should specify their actual country code in the configuration
+            const countryCodeForStep2 = countryCodeOverride || 'US';
             const step2Body = this.reqBodyAuthStep2(authorizeCode, bizToken, 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);
+            logger_1.logger.debug('Step 2 response:', {
+                status: loginStatus,
+                code: loginResponse === null || loginResponse === void 0 ? void 0 : loginResponse.code,
+                hasResult: !!(loginResponse === null || loginResponse === void 0 ? void 0 : loginResponse.result),
+                msg: loginResponse === null || loginResponse === void 0 ? void 0 : loginResponse.msg
+            });
             if (!loginResponse || loginStatus !== 200) {
                 logger_1.logger.error('Step 2 failed:', loginResponse);
                 setApiBaseUrl(originalUrl); // Restore original URL on failure
                 return [false, null, null, null];
             }
             if (loginResponse.code !== 0) {
-                // Handle cross-region error with retry (like pyvesync PR #340)
-                if (exports.CROSS_REGION_ERROR_CODES.includes(loginResponse.code)) {
-                    logger_1.logger.debug('Cross-region error detected in Step 2, retrying with region change token...');
-                    const { bizToken: regionChangeToken, countryCode: newCountryCode } = loginResponse.result || {};
-                    if (regionChangeToken && newCountryCode) {
-                        // Retry Step 2 with region change token on the SAME endpoint
-                        // The region change token tells the server to handle the cross-region authentication
-                        const retryBody = {
-                            method: 'loginByAuthorizeCode4Vesync',
-                            authorizeCode: authorizeCode,
-                            acceptLanguage: 'en',
-                            clientInfo: exports.CLIENT_INFO,
-                            clientType: 'vesyncApp',
-                            clientVersion: exports.CLIENT_VERSION,
-                            debugMode: false,
-                            emailSubscriptions: false,
-                            osInfo: exports.PHONE_OS,
-                            terminalId: terminalId,
-                            timeZone: exports.DEFAULT_TZ,
-                            userCountryCode: newCountryCode,
-                            traceId: `APP${appId}${Math.floor(Date.now() / 1000)}`,
-                            bizToken: regionChangeToken,
-                            regionChange: 'last_region'
-                        };
-                        logger_1.logger.debug('Retrying Step 2 with region change token...', {
-                            newCountryCode,
-                            currentEndpoint: getApiBaseUrl()
-                        });
-                        const [retryResponse, retryStatus] = await this.callApi('/user/api/accountManage/v1/loginByAuthorizeCode4Vesync', 'post', retryBody, step1Headers, manager);
-                        if (retryResponse && retryResponse.code === 0) {
-                            const { token, accountID, countryCode } = retryResponse.result || {};
-                            if (token && accountID) {
-                                logger_1.logger.debug('Step 2 retry successful with region change');
-                                setApiBaseUrl(originalUrl); // Restore original URL on success
-                                return [true, token, accountID, countryCode || newCountryCode];
-                            }
-                        }
-                        logger_1.logger.error('Step 2 retry failed:', retryResponse);
-                        setApiBaseUrl(originalUrl); // Restore original URL on failure
-                        return [false, null, null, null];
-                    }
-                    else {
-                        logger_1.logger.error('No region change token in cross-region error response');
-                    }
+                logger_1.logger.debug('Step 2 error, code:', loginResponse.code, 'checking if cross-region...');
+                // Handle cross-region error - for EU accounts, we need to switch regions entirely
+                if (constants_1.CROSS_REGION_ERROR_CODES.includes(loginResponse.code)) {
+                    // Log helpful message about country code mismatch
+                    logger_1.logger.warn('═══════════════════════════════════════════════════════════════');
+                    logger_1.logger.warn('COUNTRY CODE MISMATCH DETECTED');
+                    logger_1.logger.warn(`Your account expects a different country code than '${countryCodeForStep2}'`);
+                    logger_1.logger.warn('This usually means:');
+                    logger_1.logger.warn('  1. You need to set the correct country code in your config');
+                    logger_1.logger.warn('  2. Your account was created in a different country/region');
+                    logger_1.logger.warn('');
+                    logger_1.logger.warn('To fix this:');
+                    logger_1.logger.warn('  - In Homebridge UI: Select your correct country from the dropdown');
+                    logger_1.logger.warn('  - In config.json: Add "countryCode": "YOUR_COUNTRY_CODE"');
+                    logger_1.logger.warn('');
+                    logger_1.logger.warn('Common country codes: US, CA, GB, DE, FR, AU, NZ, JP');
+                    logger_1.logger.warn('═══════════════════════════════════════════════════════════════');
+                    logger_1.logger.debug('Cross-region error detected in Step 2 - will try different endpoint');
+                    // For cross-region errors, we need to retry the entire flow with a different region
+                    // The authorization code from Step 1 is tied to the endpoint it was obtained from
+                    setApiBaseUrl(originalUrl); // Restore original URL
+                    return [false, null, null, 'cross_region_retry'];
                 }
                 logger_1.logger.error('Step 2 error code:', loginResponse.code, 'message:', loginResponse.msg);
                 setApiBaseUrl(originalUrl); // Restore original URL on error
@@ -588,6 +614,11 @@ class Helpers {
             }
             if (response.code && response.code !== 0) {
                 logger_1.logger.error('Legacy login error code:', response.code, 'message:', response.msg);
+                // Check if it's a credential error
+                if ((0, constants_1.isCredentialError)(response.code)) {
+                    logger_1.logger.error('Legacy auth: Credential error detected');
+                    return [false, null, null, 'credential_error'];
+                }
                 return [false, null, null, null];
             }
             const { token, accountID, countryCode } = response.result || {};

package/dist/lib/vesync.d.ts

@@ -27,6 +27,7 @@ export declare class VeSync {
     private _excludeConfig;
     private _appId;
     private _region;
+    private _countryCodeOverride;
     username: string;
     password: string;
     token: string | null;
@@ -61,6 +62,7 @@ export declare class VeSync {
         customLogger?: Logger;
         excludeConfig?: ExcludeConfig;
         region?: string;
+        countryCode?: string;
         debugMode?: boolean;
     }, redact?: boolean, apiUrl?: string, customLogger?: Logger, excludeConfig?: ExcludeConfig);
     /**

package/dist/lib/vesync.js

@@ -141,6 +141,7 @@ class VeSync {
             this._redact = options.redact !== undefined ? options.redact : true;
             this._excludeConfig = options.excludeConfig || null;
             this._region = options.region || 'US';
+            this._countryCodeOverride = options.countryCode || null;
             customLogger = options.customLogger;
             apiUrl = options.apiUrl;
         }
@@ -150,6 +151,7 @@ class VeSync {
             this._redact = redact;
             this._excludeConfig = excludeConfig || null;
             this._region = 'US';
+            this._countryCodeOverride = null;
         }
         this._energyUpdateInterval = DEFAULT_ENERGY_UPDATE_INTERVAL;
         this._energyCheck = true;
@@ -195,6 +197,12 @@ class VeSync {
             (0, helpers_1.setApiBaseUrl)(apiUrl);
         }
         else {
+            // If country code is provided, use it to determine the endpoint
+            if (this._countryCodeOverride) {
+                const endpointRegion = (0, helpers_1.getEndpointForCountryCode)(this._countryCodeOverride);
+                this._region = endpointRegion;
+                logger_1.logger.debug(`Country code ${this._countryCodeOverride} maps to ${endpointRegion} endpoint`);
+            }
             // Set endpoint based on region
             const regionEndpoints = {
                 'US': 'https://smartapi.vesync.com',
@@ -458,32 +466,82 @@ class VeSync {
             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}`);
-                // First, try to detect user's region from email
-                const detectedRegion = (0, helpers_1.getRegionFromCountryCode)((0, helpers_1.getCountryCodeFromRegion)(this._region, this.username));
-                if (detectedRegion !== this._region) {
-                    logger_1.logger.debug(`Adjusting region from ${this._region} to ${detectedRegion} based on email domain`);
-                    this._region = detectedRegion;
-                    (0, helpers_1.setCurrentRegion)(detectedRegion);
-                }
+                // 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);
+                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
+                    }
                     // Check if we need to try a different region
-                    if (countryCode === 'cross_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);
-                        [success, token, accountId, countryCode] = await helpers_1.Helpers.authNewFlow(this, this._appId, 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;
                         }
                     }
                     // If new flow still fails, try legacy authentication as fallback
@@ -493,6 +551,11 @@ class VeSync {
                         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) {

package/package.json

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

package/src/index.ts

@@ -11,4 +11,12 @@ export { VeSyncWallSwitch } from './lib/vesyncSwitchImpl';
 export { VeSyncBaseDevice } from './lib/vesyncBaseDevice';
 
 // Export helper functions
-export { Helpers, setApiBaseUrl } from './lib/helpers'; 
+export { Helpers, setApiBaseUrl } from './lib/helpers';
+
+// Export constants
+export {
+    CREDENTIAL_ERROR_CODES,
+    CROSS_REGION_ERROR_CODES,
+    isCredentialError,
+    isCrossRegionError
+} from './lib/constants'; 

package/src/lib/constants.ts

@@ -0,0 +1,35 @@
+/**
+ * VeSync API Error Codes
+ */
+
+// Authentication error codes that indicate bad credentials (no point retrying)
+export const CREDENTIAL_ERROR_CODES = [
+    -11201129,  // account or password incorrect
+    -11202129,  // the account does not exist
+    -11000129,  // illegal argument (empty credentials)
+];
+
+// Cross-region error codes that require region switching
+export const CROSS_REGION_ERROR_CODES = [
+    -11260022,  // cross region error
+    -11261022,  // access region conflict error
+];
+
+// Other error codes
+export const APP_VERSION_ERROR_CODES = [
+    -11012022,  // app version is too low
+];
+
+/**
+ * Check if an error code indicates bad credentials
+ */
+export function isCredentialError(code: number): boolean {
+    return CREDENTIAL_ERROR_CODES.includes(code);
+}
+
+/**
+ * Check if an error code indicates cross-region issue
+ */
+export function isCrossRegionError(code: number): boolean {
+    return CROSS_REGION_ERROR_CODES.includes(code);
+}

package/src/lib/helpers.ts

@@ -6,6 +6,7 @@ import axios from 'axios';
 import crypto from 'crypto';
 import { VeSync } from './vesync';
 import { logger } from './logger';
+import { isCredentialError, isCrossRegionError, CROSS_REGION_ERROR_CODES } from './constants';
 
 // API configuration - Support regional endpoints
 let _apiBaseUrl = 'https://smartapi.vesync.com';
@@ -72,7 +73,7 @@ export const REGION_ENDPOINTS = {
 };
 
 // Cross-region error codes - multiple versions exist
-export const CROSS_REGION_ERROR_CODES = [-11260022, -11261022];
+// CROSS_REGION_ERROR_CODES moved to constants.ts
 export const APP_VERSION_TOO_LOW_ERROR_CODE = -11012022;
 
 // Authentication error codes
@@ -83,6 +84,42 @@ export const AUTH_ERROR_CODES = {
     CROSS_REGION_ALT: -11261022
 };
 
+/**
+ * Get list of country codes that use the US endpoint
+ * These are tried when we get a cross-region error
+ */
+export function getUSEndpointCountryCodes(): string[] {
+    // Countries that use the US endpoint but might need their own country code
+    return ['US', 'AU', 'NZ', 'JP', 'CA', 'MX', 'SG'];
+}
+
+/**
+ * Get the appropriate API endpoint based on country code
+ */
+export function getEndpointForCountryCode(countryCode: string): 'US' | 'EU' {
+    // European country codes that should use the EU endpoint
+    const euCountryCodes = [
+        // Western Europe
+        'GB', 'DE', 'FR', 'IT', 'ES', 'NL', 'BE', 'AT', 'CH', 'IE', 'PT', 'LU',
+        // Nordic countries
+        'SE', 'NO', 'DK', 'FI', 'IS',
+        // Eastern Europe
+        'PL', 'CZ', 'HU', 'RO', 'BG', 'HR', 'SI', 'SK', 'LT', 'LV', 'EE',
+        // Southern Europe
+        'GR', 'CY', 'MT',
+        // Other European
+        'AL', 'BA', 'RS', 'ME', 'MK', 'MD', 'UA', 'BY'
+    ];
+    
+    // Check if country code is in EU list
+    if (euCountryCodes.includes(countryCode)) {
+        return 'EU';
+    }
+    
+    // Everything else uses US endpoint (including AU, NZ, JP, CA, MX, etc.)
+    return 'US';
+}
+
 /**
  * Detect user's home region from email domain or country hints
  */
@@ -556,7 +593,7 @@ export class Helpers {
     /**
      * Perform new two-step authentication flow
      */
-    static async authNewFlow(manager: VeSync, appId: string, region: string = 'US'): Promise<[boolean, string | null, string | null, string | null]> {
+    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();
@@ -594,8 +631,15 @@ export class Helpers {
             if (authResponse.code !== 0) {
                 logger.error('Step 1 error code:', authResponse.code, 'message:', authResponse.msg);
                 
+                // Check if it's a credential error (no point retrying)
+                if (isCredentialError(authResponse.code)) {
+                    logger.error('Credential error detected - invalid username or password');
+                    setApiBaseUrl(originalUrl); // Restore original URL
+                    return [false, null, null, 'credential_error'];
+                }
+                
                 // Handle cross-region error (multiple error codes possible)
-                if (CROSS_REGION_ERROR_CODES.includes(authResponse.code)) {
+                if (isCrossRegionError(authResponse.code)) {
                     logger.debug('Cross-region error detected:', authResponse.code, 'will try different region');
                     setApiBaseUrl(originalUrl); // Restore original URL
                     return [false, null, null, 'cross_region'];
@@ -616,8 +660,9 @@ export class Helpers {
             logger.debug('Step 1 successful, got authorization code');
 
             // Step 2: Login with authorization code
-            // Use the appropriate country code based on the region we're authenticating with
-            const countryCodeForStep2 = region === 'EU' ? 'DE' : 'US';
+            // Use the override if provided, otherwise default to 'US'
+            // Users should specify their actual country code in the configuration
+            const countryCodeForStep2 = countryCodeOverride || 'US';
             const step2Body = this.reqBodyAuthStep2(authorizeCode, bizToken, appId, terminalId, countryCodeForStep2);
             
             logger.debug('Step 2: Logging in with authorization code...');
@@ -630,6 +675,13 @@ export class Helpers {
                 manager
             );
 
+            logger.debug('Step 2 response:', { 
+                status: loginStatus, 
+                code: loginResponse?.code, 
+                hasResult: !!loginResponse?.result,
+                msg: loginResponse?.msg 
+            });
+
             if (!loginResponse || loginStatus !== 200) {
                 logger.error('Step 2 failed:', loginResponse);
                 setApiBaseUrl(originalUrl); // Restore original URL on failure
@@ -637,61 +689,29 @@ export class Helpers {
             }
 
             if (loginResponse.code !== 0) {
-                // Handle cross-region error with retry (like pyvesync PR #340)
+                logger.debug('Step 2 error, code:', loginResponse.code, 'checking if cross-region...');
+                // Handle cross-region error - for EU accounts, we need to switch regions entirely
                 if (CROSS_REGION_ERROR_CODES.includes(loginResponse.code)) {
-                    logger.debug('Cross-region error detected in Step 2, retrying with region change token...');
+                    // Log helpful message about country code mismatch
+                    logger.warn('═══════════════════════════════════════════════════════════════');
+                    logger.warn('COUNTRY CODE MISMATCH DETECTED');
+                    logger.warn(`Your account expects a different country code than '${countryCodeForStep2}'`);
+                    logger.warn('This usually means:');
+                    logger.warn('  1. You need to set the correct country code in your config');
+                    logger.warn('  2. Your account was created in a different country/region');
+                    logger.warn('');
+                    logger.warn('To fix this:');
+                    logger.warn('  - In Homebridge UI: Select your correct country from the dropdown');
+                    logger.warn('  - In config.json: Add "countryCode": "YOUR_COUNTRY_CODE"');
+                    logger.warn('');
+                    logger.warn('Common country codes: US, CA, GB, DE, FR, AU, NZ, JP');
+                    logger.warn('═══════════════════════════════════════════════════════════════');
                     
-                    const { bizToken: regionChangeToken, countryCode: newCountryCode } = loginResponse.result || {};
-                    
-                    if (regionChangeToken && newCountryCode) {
-                        // Retry Step 2 with region change token on the SAME endpoint
-                        // The region change token tells the server to handle the cross-region authentication
-                        const retryBody = {
-                            method: 'loginByAuthorizeCode4Vesync',
-                            authorizeCode: authorizeCode,
-                            acceptLanguage: 'en',
-                            clientInfo: CLIENT_INFO,
-                            clientType: 'vesyncApp',
-                            clientVersion: CLIENT_VERSION,
-                            debugMode: false,
-                            emailSubscriptions: false,
-                            osInfo: PHONE_OS,
-                            terminalId: terminalId,
-                            timeZone: DEFAULT_TZ,
-                            userCountryCode: newCountryCode,
-                            traceId: `APP${appId}${Math.floor(Date.now() / 1000)}`,
-                            bizToken: regionChangeToken,
-                            regionChange: 'last_region'
-                        };
-                        
-                        logger.debug('Retrying Step 2 with region change token...', {
-                            newCountryCode,
-                            currentEndpoint: getApiBaseUrl()
-                        });
-                        
-                        const [retryResponse, retryStatus] = await this.callApi(
-                            '/user/api/accountManage/v1/loginByAuthorizeCode4Vesync',
-                            'post',
-                            retryBody,
-                            step1Headers,
-                            manager
-                        );
-                        
-                        if (retryResponse && retryResponse.code === 0) {
-                            const { token, accountID, countryCode } = retryResponse.result || {};
-                            if (token && accountID) {
-                                logger.debug('Step 2 retry successful with region change');
-                                setApiBaseUrl(originalUrl); // Restore original URL on success
-                                return [true, token, accountID, countryCode || newCountryCode];
-                            }
-                        }
-                        
-                        logger.error('Step 2 retry failed:', retryResponse);
-                        setApiBaseUrl(originalUrl); // Restore original URL on failure
-                        return [false, null, null, null];
-                    } else {
-                        logger.error('No region change token in cross-region error response');
-                    }
+                    logger.debug('Cross-region error detected in Step 2 - will try different endpoint');
+                    // For cross-region errors, we need to retry the entire flow with a different region
+                    // The authorization code from Step 1 is tied to the endpoint it was obtained from
+                    setApiBaseUrl(originalUrl); // Restore original URL
+                    return [false, null, null, 'cross_region_retry'];
                 }
                 
                 logger.error('Step 2 error code:', loginResponse.code, 'message:', loginResponse.msg);
@@ -744,6 +764,13 @@ export class Helpers {
 
             if (response.code && response.code !== 0) {
                 logger.error('Legacy login error code:', response.code, 'message:', response.msg);
+                
+                // Check if it's a credential error
+                if (isCredentialError(response.code)) {
+                    logger.error('Legacy auth: Credential error detected');
+                    return [false, null, null, 'credential_error'];
+                }
+                
                 return [false, null, null, null];
             }
 

package/src/lib/vesync.ts

@@ -2,7 +2,7 @@
  * VeSync API Device Library
  */
 
-import { Helpers, API_RATE_LIMIT, DEFAULT_TZ, setApiBaseUrl, getApiBaseUrl, generateAppId, getRegionFromCountryCode, setCurrentRegion, getCurrentRegion, REGION_ENDPOINTS, getCountryCodeFromRegion } from './helpers';
+import { Helpers, API_RATE_LIMIT, DEFAULT_TZ, setApiBaseUrl, getApiBaseUrl, generateAppId, getRegionFromCountryCode, setCurrentRegion, getCurrentRegion, REGION_ENDPOINTS, getCountryCodeFromRegion, getEndpointForCountryCode } from './helpers';
 import { VeSyncBaseDevice } from './vesyncBaseDevice';
 import { fanModules } from './vesyncFanImpl';
 import { outletModules } from './vesyncOutletImpl';
@@ -161,6 +161,7 @@ export class VeSync {
     private _excludeConfig: ExcludeConfig | null;
     private _appId: string;
     private _region: string;
+    private _countryCodeOverride: string | null;
 
     username: string;
     password: string;
@@ -202,6 +203,7 @@ export class VeSync {
             customLogger?: Logger;
             excludeConfig?: ExcludeConfig;
             region?: string;
+            countryCode?: string;  // Override country code for Step 2 authentication
             debugMode?: boolean;  // Alias for debug
         } = false,
         redact = true,
@@ -218,6 +220,7 @@ export class VeSync {
             this._redact = options.redact !== undefined ? options.redact : true;
             this._excludeConfig = options.excludeConfig || null;
             this._region = options.region || 'US';
+            this._countryCodeOverride = options.countryCode || null;
             customLogger = options.customLogger;
             apiUrl = options.apiUrl;
         } else {
@@ -226,6 +229,7 @@ export class VeSync {
             this._redact = redact;
             this._excludeConfig = excludeConfig || null;
             this._region = 'US';
+            this._countryCodeOverride = null;
         }
 
         this._energyUpdateInterval = DEFAULT_ENERGY_UPDATE_INTERVAL;
@@ -274,6 +278,13 @@ export class VeSync {
         if (apiUrl) {
             setApiBaseUrl(apiUrl);
         } else {
+            // If country code is provided, use it to determine the endpoint
+            if (this._countryCodeOverride) {
+                const endpointRegion = getEndpointForCountryCode(this._countryCodeOverride);
+                this._region = endpointRegion;
+                logger.debug(`Country code ${this._countryCodeOverride} maps to ${endpointRegion} endpoint`);
+            }
+            
             // Set endpoint based on region
             const regionEndpoints: Record<string, string> = {
                 'US': 'https://smartapi.vesync.com',
@@ -571,20 +582,18 @@ export class VeSync {
             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}`);
 
-                // First, try to detect user's region from email
-                const detectedRegion = getRegionFromCountryCode(getCountryCodeFromRegion(this._region, this.username));
-                if (detectedRegion !== this._region) {
-                    logger.debug(`Adjusting region from ${this._region} to ${detectedRegion} based on email domain`);
-                    this._region = detectedRegion;
-                    setCurrentRegion(detectedRegion);
-                }
+                // 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.authNewFlow(this, this._appId, this._region);
+                let [success, token, accountId, countryCode] = await Helpers.authNewFlow(this, this._appId, this._region, this._countryCodeOverride || undefined);
                 
                 // Track if new flow succeeded
                 if (success) {
@@ -592,15 +601,74 @@ export class VeSync {
                 }
 
                 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
+                    }
+                    
                     // Check if we need to try a different region
-                    if (countryCode === 'cross_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);
-                        [success, token, accountId, countryCode] = await Helpers.authNewFlow(this, this._appId, 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;
                         }
                     }
 
@@ -610,6 +678,10 @@ export class VeSync {
                         [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
                         }
                     }
                 }