homebridge-melcloud-control 4.10.0-beta.0 → 4.10.0

package/CHANGELOG.md

@@ -28,7 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Changes
 
-- added web socket for real time data refresh with MELCloud Home
+- added web socket for real time data update with MELCloud Home
 - cleanup
 
 # [4.9.1] - (15.04.2026)

package/index.js

@@ -90,7 +90,7 @@ class MelCloudPlatform {
 										if (logLevel.warn) log.warn(`Unknown account type: ${account.type}.`);
 										return;
 								}
-								melCloudClass.on('success', (msg) => logLevel.success && log.success(`${name}, ${msg}`))
+								melCloudClass.on('success', (msg) => log.success(`${name}, ${msg}`))
 									.on('info', (msg) => log.info(`${name}, ${msg}`))
 									.on('debug', (msg) => log.info(`${name}, debug: ${msg}`))
 									.on('warn', (msg) => log.warn(`${name}, ${msg}`))
@@ -188,8 +188,8 @@ class MelCloudPlatform {
 											continue;
 									}
 
-									deviceClass.on('devInfo', (info) => logLevel.devInfo && log.info(info))
-										.on('success', (msg) => logLevel.success && log.success(`${name}, ${deviceTypeString}, ${deviceName}, ${msg}`))
+									deviceClass.on('devInfo', (info) => log.info(info))
+										.on('success', (msg) => log.success(`${name}, ${deviceTypeString}, ${deviceName}, ${msg}`))
 										.on('info', (msg) => log.info(`${name}, ${deviceTypeString}, ${deviceName}, ${msg}`))
 										.on('debug', (msg) => log.info(`${name}, ${deviceTypeString}, ${deviceName}, debug: ${msg}`))
 										.on('warn', (msg) => log.warn(`${name}, ${deviceTypeString}, ${deviceName}, ${msg}`))

package/package.json

@@ -1,7 +1,7 @@
 {
   "displayName": "MELCloud Control",
   "name": "homebridge-melcloud-control",
-  "version": "4.10.0-beta.0",
+  "version": "4.10.0",
   "description": "Homebridge plugin to control Mitsubishi Air Conditioner, Heat Pump and Energy Recovery Ventilation.",
   "license": "MIT",
   "author": "grzegorz914",

package/src/melcloud.js

@@ -10,6 +10,7 @@ class MelCloud extends EventEmitter {
         this.user = account.user;
         this.passwd = account.passwd;
         this.language = account.language;
+        this.logSuccess = account.log?.success;
         this.logWarn = account.log?.warn;
         this.logError = account.log?.error;
         this.logDebug = account.log?.debug;
@@ -26,7 +27,7 @@ class MelCloud extends EventEmitter {
                     await this.checkDevicesList();
                 }))
                 .on('state', (state) => {
-                    this.emit(state ? 'success' : 'warn', `Impulse generator ${state ? 'started' : 'stopped'}`);
+                    if (this.logSuccess) this.emit(state ? 'success' : 'warn', `Impulse generator ${state ? 'started' : 'stopped'}`);
                 });
         }
     }

package/src/melcloudata.js

@@ -6,7 +6,6 @@ class MelCloudAta extends EventEmitter {
     constructor(account, device, defaultTempsFile, melCloudClass) {
         super();
         this.accountTypeMelcloud = account.type === 'melcloud';
-        this.logSuccess = account.log?.success;
         this.logWarn = account.log?.warn;
         this.logError = account.log?.error;
         this.logDebug = account.log?.debug;

package/src/melcloudatw.js

@@ -6,7 +6,6 @@ class MelCloudAtw extends EventEmitter {
     constructor(account, device, defaultTempsFile, melCloudClass) {
         super();
         this.accountTypeMelCloud = account.type === 'melcloud';
-        this.logSuccess = account.log?.success;
         this.logWarn = account.log?.warn;
         this.logError = account.log?.error;
         this.logDebug = account.log?.debug;
@@ -242,7 +241,7 @@ class MelCloudAtw extends EventEmitter {
                         case 'schedule':
                             payload = { enabled: payload.enabled };
                             method = 'PUT';
-                            path = ApiUrls.Home.Put.ScheduleEnableDisable.replace('deviceid', deviceData.DeviceID);
+                            path = ApiUrls.Home.Put.ScheduleEnabled.replace('deviceid', deviceData.DeviceID);
                             deviceData.ScheduleEnabled = payload.enabled;
                             break;
                         case 'scene':

package/src/melclouderv.js

@@ -6,7 +6,6 @@ class MelCloudErv extends EventEmitter {
     constructor(account, device, defaultTempsFile, melCloudClass) {
         super();
         this.accountTypeMelCloud = account.type === 'melcloud';
-        this.logSuccess = account.log?.success;
         this.logWarn = account.log?.warn;
         this.logError = account.log?.error;
         this.logDebug = account.log?.debug;
@@ -245,7 +244,7 @@ class MelCloudErv extends EventEmitter {
                         case 'schedule':
                             payload = { enabled: payload.enabled };
                             method = 'PUT';
-                            path = ApiUrls.Home.Put.ScheduleEnableDisable.replace('deviceid', deviceData.DeviceID);
+                            path = ApiUrls.Home.Put.ScheduleEnabled.replace('deviceid', deviceData.DeviceID);
                             deviceData.ScheduleEnabled = payload.enabled;
                             break;
                         case 'scene':

package/src/melcloudhome.js

@@ -31,15 +31,15 @@ class MelCloudHome extends EventEmitter {
         this.pacer = new RequestPacer();
 
         // Axios clients
-        this.authClient = null; // cookie-jar client używany tylko podczas auth flow
-        this.client = null; // API client używany do requestów po zalogowaniu
+        this.authClient = null; // cookie-jar client used only during the auth flow
+        this.client = null; // API client used for all post-login requests
 
         // Token state
         this.accessToken = null;
         this.refreshToken = null;
-        this.tokenExpiry = 0; // Unix timestamp (sekundy)
+        this.tokenExpiry = 0; // Unix timestamp (seconds)
 
-        // Flaga zapobiegająca wielokrotnemu dodaniu interceptorów
+        // Flag preventing duplicate interceptor registration on re-login
         this.interceptorsAttached = false;
 
         // WebSocket state
@@ -48,8 +48,8 @@ class MelCloudHome extends EventEmitter {
         this.connecting = false;
         this.heartbeat = null;
         this.reconnectTimer = null;
-        this.reconnectDelay = 5_000;  // ms, rośnie wykładniczo do reconnectDelayMax
-        this.reconnectDelayMax = 300_000; // 5 minut
+        this.reconnectDelay = 5_000;   // ms, grows exponentially up to reconnectDelayMax
+        this.reconnectDelayMax = 300_000; // 5 minutes
 
         if (pluginStart) {
             this.impulseGenerator = new ImpulseGenerator()
@@ -64,17 +64,19 @@ class MelCloudHome extends EventEmitter {
 
     // ── WebSocket ─────────────────────────────────────────────────────────────
 
+    // Resets all WebSocket state and clears the heartbeat interval.
     cleanupSocket() {
         if (this.heartbeat) {
             clearInterval(this.heartbeat);
             this.heartbeat = null;
         }
+        this.socket = null;
         this.socketConnected = false;
         this.connecting = false;
-        this.socket = null;
     }
 
-    // Łączy się z WebSocket. Wywoływane po udanym connect() lub po reconnect.
+    // Opens a WebSocket connection using the user ID from /api/user/context as the hash.
+    // Called automatically after a successful login and on every reconnect attempt.
     async connectSocket() {
         if (this.connecting || this.socketConnected) return;
         this.connecting = true;
@@ -82,9 +84,10 @@ class MelCloudHome extends EventEmitter {
         let hash;
         try {
             const resp = await this.client.get(ApiUrls.Home.Get.Context);
-            hash = resp.data.id ?? null;
+            hash = resp.data?.id ?? null;
+            if (!hash) throw new Error('id field missing in context response');
         } catch (err) {
-            if (this.logError) this.emit('error', `connectSocket: cannot get WS hash: ${err.message}`);
+            if (this.logError) this.emit('error', `WebSocket: cannot get hash: ${err.message}`);
             this.connecting = false;
             this.scheduleReconnect();
             return;
@@ -97,68 +100,74 @@ class MelCloudHome extends EventEmitter {
             'Cache-Control': 'no-cache',
         };
 
-        if (this.logDebug) this.emit('debug', `Connecting WebSocket: ${url.slice(0, 60)}...`);
+        if (this.logDebug) this.emit('debug', `WebSocket connecting: ${url.slice(0, 60)}...`);
 
         try {
             const ws = new WebSocket(url, { headers });
             this.socket = ws;
 
             ws.on('error', (error) => {
-                if (this.logError) this.emit('error', `Web socket error: ${error.message}`);
-                try { ws.close(); } catch { /* ignoruj */ }
-            })
-                .on('close', () => {
-                    if (this.logDebug) this.emit('debug', 'Web socket closed');
-                    this.cleanupSocket();
-                    this.scheduleReconnect();
-                })
-                .on('open', () => {
-                    this.socketConnected = true;
-                    this.connecting = false;
-                    this.reconnectDelay = 5_000; // reset backoff po udanym połączeniu
-                    if (this.reconnectTimer) {
-                        clearTimeout(this.reconnectTimer);
-                        this.reconnectTimer = null;
+                if (this.logError) this.emit('error', `WebSocket error: ${error.message}`);
+                try { ws.close(); } catch { /* ignore if already closed */ }
+            });
+
+            ws.on('close', () => {
+                if (this.logDebug) this.emit('debug', 'WebSocket closed');
+                this.cleanupSocket();
+                this.scheduleReconnect();
+            });
+
+            ws.on('open', () => {
+                this.socketConnected = true;
+                this.connecting = false;
+                this.reconnectDelay = 5_000; // reset backoff on successful connection
+                if (this.reconnectTimer) {
+                    clearTimeout(this.reconnectTimer);
+                    this.reconnectTimer = null;
+                }
+                if (this.logSuccess) this.emit('success', 'WebSocket connected');
+
+                // Send a ping every 30 s to keep the connection alive
+                this.heartbeat = setInterval(() => {
+                    if (ws.readyState === WebSocket.OPEN) {
+                        if (this.logDebug) this.emit('debug', 'WebSocket heartbeat sent');
+                        ws.ping();
                     }
-                    if (this.logSuccess) this.emit('success', 'Web Socket Connected');
-
-                    // Heartbeat co 30s
-                    this.heartbeat = setInterval(() => {
-                        if (ws.readyState === WebSocket.OPEN) {
-                            if (this.logDebug) this.emit('debug', 'Web socket send heartbeat');
-                            ws.ping();
-                        }
-                    }, 30_000);
-                })
-                .on('pong', () => {
-                    if (this.logDebug) this.emit('debug', 'Web socket received heartbeat');
-                })
-                .on('message', (message) => {
-                    try {
-                        const parsedMessage = JSON.parse(message);
-                        if (this.logDebug) this.emit('debug', `Web socket incoming message: ${JSON.stringify(parsedMessage, null, 2)}`);
+                }, 30_000);
+            });
 
-                        // Format: array, pierwszy element ma Data.id
-                        const messageData = parsedMessage?.[0]?.Data;
-                        if (!messageData || parsedMessage.message === 'Forbidden') return;
+            ws.on('pong', () => {
+                if (this.logDebug) this.emit('debug', 'WebSocket heartbeat received');
+            });
+
+            ws.on('message', (message) => {
+                try {
+                    const parsed = JSON.parse(message);
+                    const messageData = parsed?.[0]?.Data;
+
+                    if (this.logDebug) this.emit('debug', `WebSocket message: ${JSON.stringify(parsed, null, 2)}`);
+
+                    // Ignore empty payloads and server-side auth errors
+                    if (!messageData || parsed.message === 'Forbidden') return;
+
+                    this.emit(messageData.id, 'ws', parsed[0]);
+                } catch (err) {
+                    if (this.logError) this.emit('error', `WebSocket message parse error: ${err.message}`);
+                }
+            });
 
-                        this.emit(messageData.id, 'ws', parsedMessage[0]);
-                    } catch (err) {
-                        if (this.logError) this.emit('error', `Web socket message parse error: ${err.message}`);
-                    }
-                });
         } catch (error) {
-            if (this.logError) this.emit('error', `Web socket connection failed: ${error.message}`);
+            if (this.logError) this.emit('error', `WebSocket connection failed: ${error.message}`);
             this.cleanupSocket();
             this.scheduleReconnect();
         }
     }
 
-    // Wykładniczy backoff: 5s → 10s → 20s → ... → max 5 minut
+    // Schedules a reconnect attempt using exponential backoff (5 s → 10 s → … → 5 min).
     scheduleReconnect() {
-        if (this.reconnectTimer) return; // już zaplanowany
+        if (this.reconnectTimer) return; // already scheduled
 
-        if (this.logDebug) this.emit('debug', `Web socket reconnecting in ${this.reconnectDelay / 1000}s...`);
+        if (this.logDebug) this.emit('debug', `WebSocket reconnecting in ${this.reconnectDelay / 1000} s...`);
 
         this.reconnectTimer = setTimeout(async () => {
             this.reconnectTimer = null;
@@ -170,6 +179,7 @@ class MelCloudHome extends EventEmitter {
 
     // ── Utils ─────────────────────────────────────────────────────────────────
 
+    // Recursively capitalizes the first letter of every object key.
     capitalizeKeysDeep(obj) {
         if (Array.isArray(obj)) return obj.map(item => this.capitalizeKeysDeep(item));
         if (obj && typeof obj === 'object') {
@@ -185,6 +195,7 @@ class MelCloudHome extends EventEmitter {
 
     // ── Token state ───────────────────────────────────────────────────────────
 
+    // Returns true when the access token is absent or expires within 60 seconds.
     isTokenExpired() {
         if (!this.accessToken) return true;
         return Date.now() / 1000 >= this.tokenExpiry - 60;
@@ -192,11 +203,12 @@ class MelCloudHome extends EventEmitter {
 
     // ── Axios clients ─────────────────────────────────────────────────────────
 
+    // Returns (creating if needed) the cookie-jar client used during the OAuth flow.
     ensureAuthClient() {
         if (this.authClient) return this.authClient;
 
         const jar = new CookieJar();
-        const instance = wrapper(
+        this.authClient = wrapper(
             axios.create({
                 jar,
                 timeout: 30_000,
@@ -205,14 +217,14 @@ class MelCloudHome extends EventEmitter {
                     'User-Agent': ApiUrls.Home.UserAgent,
                 },
                 maxRedirects: 5,
-                validateStatus: () => true,
+                validateStatus: () => true, // handle all status codes manually
             })
         );
 
-        this.authClient = instance;
-        return instance;
+        return this.authClient;
     }
 
+    // Returns (creating if needed) the API client used for all post-login requests.
     ensureClient() {
         if (this.client) return this.client;
 
@@ -228,7 +240,7 @@ class MelCloudHome extends EventEmitter {
         return this.client;
     }
 
-    // ── Pacer helper ──────────────────────────────────────────────────────────
+    // ── Pacer ─────────────────────────────────────────────────────────────────
 
     pace(fn) {
         return this.pacer.run(fn);
@@ -244,6 +256,7 @@ class MelCloudHome extends EventEmitter {
 
     // ── CSRF token ────────────────────────────────────────────────────────────
 
+    // Extracts the _csrf token value from the Cognito login page HTML.
     extractCsrfToken(html) {
         return (
             /<input[^>]+name="_csrf"[^>]+value="([^"]+)"/.exec(html)?.[1] ??
@@ -253,8 +266,9 @@ class MelCloudHome extends EventEmitter {
         );
     }
 
-    // ── Follow callback redirect ──────────────────────────────────────────────
+    // ── OAuth helpers ─────────────────────────────────────────────────────────
 
+    // Follows the /connect/authorize/callback redirect chain and returns the auth code.
     async followCallbackForCode(client, callbackQs) {
         const qs = callbackQs.replace(/&amp;/g, '&');
         const callbackUrl = `${ApiUrls.Home.AuthBase}/connect/authorize/callback?${qs}`;
@@ -272,10 +286,9 @@ class MelCloudHome extends EventEmitter {
             if (m) return m[1];
         }
 
-        if (!location || location === '/')
-            throw new Error('Callback returned empty or root redirect');
+        if (!location || location === '/') throw new Error('Callback returned empty or root redirect');
 
-        // Jeden dodatkowy hop
+        // One additional hop if needed
         const redirectUrl = location.startsWith('http')
             ? location
             : `${ApiUrls.Home.AuthBase}${location}`;
@@ -293,8 +306,7 @@ class MelCloudHome extends EventEmitter {
         return m[1];
     }
 
-    // ── Token exchange ────────────────────────────────────────────────────────
-
+    // Exchanges an authorization code for access and refresh tokens.
     async exchangeCodeForTokens(client, authCode, codeVerifier) {
         if (this.logDebug) this.emit('debug', 'Step 6: Token exchange');
 
@@ -325,11 +337,11 @@ class MelCloudHome extends EventEmitter {
 
     // ── Token refresh ─────────────────────────────────────────────────────────
 
+    // Uses the stored refresh token to obtain a new access token.
     async refreshAccessToken() {
         if (!this.refreshToken) throw new Error('No refresh token available');
 
         const client = this.ensureAuthClient();
-
         const resp = await this.pace(() =>
             client.post(
                 `${ApiUrls.Home.AuthBase}/connect/token`,
@@ -354,57 +366,66 @@ class MelCloudHome extends EventEmitter {
         return true;
     }
 
-    // ── Auto-refresh: refresh token lub pełne logowanie od nowa ──────────────
-
+    // Attempts a token refresh; falls back to a full re-login if the refresh token is
+    // missing or rejected. A single shared Promise prevents concurrent refresh races.
     async refreshOrRelogin() {
-        if (this.refreshToken) {
-            try {
-                await this.refreshAccessToken();
-                if (this.logDebug) this.emit('debug', 'Token refreshed successfully');
-                return;
-            } catch (err) {
-                if (this.logDebug) this.emit('debug', `Refresh token rejected (${err.message}), falling back to full re-login`);
+        if (this.refreshPromise) return this.refreshPromise;
+
+        this.refreshPromise = (async () => {
+            if (this.refreshToken) {
+                try {
+                    await this.refreshAccessToken();
+                    if (this.logDebug) this.emit('debug', 'Token refreshed successfully');
+                    return;
+                } catch (err) {
+                    if (this.logDebug) this.emit('debug', `Refresh token rejected (${err.message}), falling back to full re-login`);
+                }
             }
-        }
 
-        if (this.logDebug) this.emit('debug', 'Performing full re-login');
-        await this.connect();
+            if (this.logDebug) this.emit('debug', 'Performing full re-login');
+            await this.connect();
+        })().finally(() => {
+            this.refreshPromise = null;
+        });
+
+        return this.refreshPromise;
     }
 
-    // ── Interceptory do automatycznego odświeżania tokena ─────────────────────
+    // ── Token interceptors ────────────────────────────────────────────────────
 
+    // Attaches request and response interceptors to the API client.
+    // Safe to call multiple times — interceptors are registered only once.
     attachTokenInterceptors() {
         if (this.interceptorsAttached) return;
         this.interceptorsAttached = true;
 
         const apiClient = this.ensureClient();
 
-        // Request interceptor — dokłada aktualny token przed każdym requestem.
-        // Jeśli token wygasł, odświeża go najpierw.
+        // Inject a fresh Authorization header before every request.
+        // If the token is expired, refresh it first.
         apiClient.interceptors.request.use(async (config) => {
             if (this.isTokenExpired()) {
-                if (this.logDebug) this.emit('debug', 'Token expired or missing — refreshing before request');
+                if (this.logDebug) this.emit('debug', 'Token expired — refreshing before request');
                 await this.refreshOrRelogin();
             }
             config.headers['Authorization'] = `Bearer ${this.accessToken}`;
             return config;
         });
 
-        // Response interceptor — obsługuje 401 który może przyjść mimo świeżego tokena
-        // (np. token odwołany po stronie serwera). Ponawia request dokładnie raz.
+        // On 401, refresh the token and retry the original request exactly once.
         apiClient.interceptors.response.use(
             response => response,
             async (error) => {
-                const originalRequest = error.config;
+                const original = error.config;
 
-                if (error.response?.status === 401 && !originalRequest._retried) {
-                    originalRequest._retried = true;
-                    if (this.logDebug) this.emit('debug', 'Got 401 — refreshing token and retrying request');
+                if (error.response?.status === 401 && !original.retried) {
+                    original.retried = true;
+                    if (this.logDebug) this.emit('debug', 'Got 401 — refreshing token and retrying');
 
                     try {
                         await this.refreshOrRelogin();
-                        originalRequest.headers['Authorization'] = `Bearer ${this.accessToken}`;
-                        return apiClient(originalRequest);
+                        original.headers['Authorization'] = `Bearer ${this.accessToken}`;
+                        return apiClient(original);
                     } catch (refreshError) {
                         this.emit('error', `Token refresh failed: ${refreshError.message}`);
                         return Promise.reject(refreshError);
@@ -416,19 +437,19 @@ class MelCloudHome extends EventEmitter {
         );
     }
 
-    // ── Buduje connectInfo po udanym token exchange ───────────────────────────
+    // ── Post-login setup ──────────────────────────────────────────────────────
 
+    // Finalises the connect flow: sets up the API client, attaches interceptors,
+    // emits the 'client' event and opens the WebSocket connection.
     async buildConnectInfo(connectInfo, exchangeRes) {
         if (exchangeRes) {
-            // ensureClient() tworzy client jeśli nie istnieje.
-            // attachTokenInterceptors() dodaje interceptory tylko przy pierwszym wywołaniu.
             this.ensureClient();
             this.attachTokenInterceptors();
 
             if (this.pluginStart) {
                 this.emit('client', this.client);
                 await this.connectSocket().catch(err => {
-                    if (this.logError) this.emit('error', `Initial WebSocket connect failed: ${err.message}`);
+                    if (this.logError) this.emit('error', `WebSocket initial connect failed: ${err.message}`);
                 });
             }
         }
@@ -441,17 +462,23 @@ class MelCloudHome extends EventEmitter {
 
     // ── Connect ───────────────────────────────────────────────────────────────
 
+    // Full OAuth 2.0 PKCE login flow:
+    //   Step 1 — Pushed Authorization Request (PAR)
+    //   Step 2 — Authorize redirect → Cognito login page (or fast-path if session exists)
+    //   Step 3 — POST credentials to Cognito (maxRedirects: 0 to intercept form_post)
+    //   Step 4 — POST Cognito callback params to IdentityServer /signin-oidc-meu
+    //   Step 5 — Follow redirect chain until the auth code is found
+    //   Step 6 — Exchange auth code for access + refresh tokens
     async connect() {
         if (this.logDebug) this.emit('debug', 'Connecting to MELCloud Home');
 
         try {
             const connectInfo = { State: false, Status: '', Account: {}, UseFahrenheit: false };
-
             const client = this.ensureAuthClient();
             const { verifier: codeVerifier, challenge: codeChallenge } = this.generatePkce();
             const state = crypto.randomBytes(16).toString('base64url');
 
-            // ── Step 1: PAR ──────────────────────────────────────────────────
+            // ── Step 1: PAR ───────────────────────────────────────────────────
             if (this.logDebug) this.emit('debug', 'Step 1: PAR request');
 
             const parResp = await this.pace(() =>
@@ -498,18 +525,16 @@ class MelCloudHome extends EventEmitter {
 
             const finalUrl = authResp.request?.res?.responseUrl ?? authorizeUrl;
             const parsed = new URL(finalUrl);
-            const body = typeof authResp.data === 'string'
-                ? authResp.data
-                : JSON.stringify(authResp.data);
+            const body = typeof authResp.data === 'string' ? authResp.data : JSON.stringify(authResp.data);
 
             if (parsed.hostname?.endsWith(ApiUrls.Home.CognitoDomainSuffix) && parsed.pathname.includes('/login')) {
-                // Happy path: strona logowania Cognito
+                // Happy path: landed on the Cognito login page
                 csrfToken = this.extractCsrfToken(body);
                 if (!csrfToken) throw new Error('Failed to extract CSRF token from Cognito login page');
                 cognitoLoginUrl = finalUrl;
                 if (this.logDebug) this.emit('debug', 'Cognito login page OK');
             } else {
-                // Fast path: istniejąca sesja — kod dostępny od razu
+                // Fast path: existing IdentityServer session — auth code available immediately
                 const codeMatch = /code=([^&"' ]+)/.exec(finalUrl) || /code=([^&"' ]+)/.exec(body);
                 if (codeMatch) {
                     authCode = codeMatch[1];
@@ -525,20 +550,21 @@ class MelCloudHome extends EventEmitter {
                 }
             }
 
-            // Fast-path: pomiń etap logowania
+            // Skip credential submission when we already have a code
             if (authCode) {
                 if (this.logDebug) this.emit('debug', 'Re-login with existing session (skipping credentials)');
                 const exchangeRes = await this.exchangeCodeForTokens(client, authCode, codeVerifier);
                 return await this.buildConnectInfo(connectInfo, exchangeRes);
             }
 
-            // ── Step 3: Wyślij dane logowania do Cognito ──────────────────────
+            // ── Step 3: Submit credentials to Cognito ─────────────────────────
+            // maxRedirects: 0 — Cognito uses response_mode=form_post, so after a
+            // successful login it POSTs back to IdentityServer (/signin-oidc-meu).
+            // We intercept the 302 before axios follows it to avoid a 500 from Kestrel.
             if (this.logDebug) this.emit('debug', 'Step 3: Submit credentials to Cognito');
 
             const cognitoHostname = new URL(cognitoLoginUrl).hostname;
 
-            // maxRedirects: 0 — Cognito używa response_mode=form_post.
-            // Przechwytujemy 302 zanim axios podąży za nim do IdentityServera (→ 500).
             const credResp = await this.pace(() =>
                 client.post(
                     cognitoLoginUrl,
@@ -565,13 +591,14 @@ class MelCloudHome extends EventEmitter {
                 this.emit('debug', `Step 3 response location: ${credResp.headers?.location ?? '(none)'}`);
             }
 
-            // status 200 = zostaliśmy na stronie Cognito → złe hasło
+            // HTTP 200 means Cognito returned the login page again → wrong password
             if (credResp.status === 200) throw new Error('Authentication failed: Invalid username or password');
             if (credResp.status >= 500) throw new Error(`Cognito server error: HTTP ${credResp.status}`);
 
-            // ── Step 4: POST do signin-oidc-meu (emulacja form_post z Cognito) ──
-            // Cognito normalnie robi POST z code+state w body do IdentityServera.
-            // My dostaliśmy 302 z tymi parametrami w query — wysyłamy je jako POST body.
+            // ── Step 4: POST Cognito callback params to IdentityServer ─────────
+            // Cognito normally POSTs code+state to /signin-oidc-meu (form_post).
+            // We received a 302 with those params in the query string, so we replay
+            // them as a POST body — exactly as Cognito would have done.
             if (this.logDebug) this.emit('debug', 'Step 4: Follow Cognito → IdentityServer redirect');
 
             const cognitoRedirectLocation = credResp.headers?.location ?? '';
@@ -600,9 +627,9 @@ class MelCloudHome extends EventEmitter {
                 this.emit('debug', `Step 4 signin location: ${signinResp.headers?.location ?? '(none)'}`);
             }
 
-            // ── Step 5: Podążaj za łańcuchem redirectów aż do auth code ──────────
-            // IdentityServer przekierowuje przez kilka etapów:
-            // /ExternalLogin/Callback → /connect/authorize/callback → melcloudhome://
+            // ── Step 5: Follow redirect chain until the auth code is found ────
+            // IdentityServer redirects through several hops:
+            //   /ExternalLogin/Callback → /connect/authorize/callback → melcloudhome://
             if (this.logDebug) this.emit('debug', 'Step 5: Following redirect chain to auth code');
 
             let currentResp = signinResp;
@@ -615,13 +642,13 @@ class MelCloudHome extends EventEmitter {
 
                 if (this.logDebug) this.emit('debug', `Step 5 hop ${hop}: status=${hopStatus} location=${hopLocation || '(none)'}`);
 
-                // A: melcloudhome:// z code=
+                // A: custom scheme redirect carrying the auth code
                 if (hopLocation.startsWith('melcloudhome://')) {
                     const m = /code=([^&"' ]+)/.exec(hopLocation);
                     if (m) { authCode = m[1]; break; }
                 }
 
-                // B: /connect/authorize/callback w location lub body
+                // B: IdentityServer authorize callback — delegate to helper
                 const cbMatch = /\/connect\/authorize\/callback\?([^"' ]+)/.exec(hopLocation)
                     || /\/connect\/authorize\/callback\?([^"' ]+)/.exec(hopBody);
                 if (cbMatch) {
@@ -630,15 +657,15 @@ class MelCloudHome extends EventEmitter {
                     break;
                 }
 
-                // C: code= bezpośrednio w location
+                // C: auth code directly in the Location header
                 const codeInLocation = /code=([^&"' ]+)/.exec(hopLocation);
                 if (codeInLocation) { authCode = codeInLocation[1]; break; }
 
-                // D: code= w body
+                // D: auth code in the response body
                 const codeInBody = /code=([^&"' ]+)/.exec(hopBody);
                 if (codeInBody) { authCode = codeInBody[1]; break; }
 
-                // Zwykły redirect — podążaj dalej
+                // Standard redirect — follow the next hop
                 if ((hopStatus === 301 || hopStatus === 302 || hopStatus === 303) && hopLocation) {
                     const nextUrl = hopLocation.startsWith('http')
                         ? hopLocation
@@ -660,7 +687,7 @@ class MelCloudHome extends EventEmitter {
 
             if (this.logDebug) this.emit('debug', `Got auth code: ${authCode.slice(0, 20)}...`);
 
-            // ── Step 6: Wymień kod na tokeny ──────────────────────────────────
+            // ── Step 6: Exchange auth code for tokens ─────────────────────────
             const exchangeRes = await this.exchangeCodeForTokens(client, authCode, codeVerifier);
             return await this.buildConnectInfo(connectInfo, exchangeRes);
 
@@ -669,23 +696,23 @@ class MelCloudHome extends EventEmitter {
         }
     }
 
-    // ── Scenes & Devices ──────────────────────────────────────────────────────
+    // ── Scenes ────────────────────────────────────────────────────────────────
 
     async checkScenesList() {
         try {
             if (this.logDebug) this.emit('debug', 'Scanning for scenes');
 
             const resp = await this.client.get(ApiUrls.Home.Get.Scenes);
-            const scenesList = resp.data;
+            if (this.logDebug) this.emit('debug', `Scenes: ${JSON.stringify(resp.data, null, 2)}`);
 
-            if (this.logDebug) this.emit('debug', `Scenes: ${JSON.stringify(scenesList, null, 2)}`);
-
-            return this.capitalizeKeysDeep(scenesList);
+            return this.capitalizeKeysDeep(resp.data);
         } catch (error) {
             throw new Error(`Check scenes list error: ${error.message}`);
         }
     }
 
+    // ── Devices ───────────────────────────────────────────────────────────────
+
     async checkDevicesList() {
         try {
             const result = { State: false, Status: null, Buildings: {}, Devices: [], Scenes: [] };
@@ -693,11 +720,11 @@ class MelCloudHome extends EventEmitter {
 
             const resp = await this.client.get(ApiUrls.Home.Get.Context);
             const userContext = resp.data;
-            //if (this.logDebug) this.emit('debug', `User Context: ${JSON.stringify(userContext, null, 2)}`);
 
-            const buildings = userContext.buildings ?? [];
-            const guestBuildings = userContext.guestBuildings ?? [];
-            const buildingsList = [...buildings, ...guestBuildings];
+            const buildingsList = [
+                ...(userContext.buildings ?? []),
+                ...(userContext.guestBuildings ?? []),
+            ];
 
             if (this.logDebug) this.emit('debug', `Buildings: ${JSON.stringify(buildingsList, null, 2)}`);
 
@@ -706,6 +733,7 @@ class MelCloudHome extends EventEmitter {
                 return result;
             }
 
+            // Shallow capitalize — used for flat objects (Capabilities, FrostProtection, etc.)
             const capitalizeKeys = obj => Object.fromEntries(
                 Object.entries(obj).map(([k, v]) => [k.charAt(0).toUpperCase() + k.slice(1), v])
             );
@@ -729,7 +757,9 @@ class MelCloudHome extends EventEmitter {
                 if (device.FrostProtection) device.FrostProtection = capitalizeKeys(device.FrostProtection);
                 if (device.OverheatProtection) device.OverheatProtection = capitalizeKeys(device.OverheatProtection);
                 if (device.HolidayMode) device.HolidayMode = capitalizeKeys(device.HolidayMode);
-                if (Array.isArray(device.Schedule)) device.Schedule = device.Schedule.map(s => this.capitalizeKeysDeep(s));
+                if (Array.isArray(device.Schedule)) {
+                    device.Schedule = device.Schedule.map(s => this.capitalizeKeysDeep(s));
+                }
 
                 const { Settings, Capabilities, Id, GivenDisplayName, ...rest } = device;
 
@@ -754,13 +784,12 @@ class MelCloudHome extends EventEmitter {
                 return result;
             }
 
-            // Sceny
             let scenes = [];
             try {
                 scenes = await this.checkScenesList();
                 if (this.logDebug) this.emit('debug', `Found ${scenes.length} scenes`);
             } catch (error) {
-                if (this.logError) this.emit('error', `Get scenes error: ${error}`);
+                if (this.logError) this.emit('error', `Get scenes error: ${error.message}`);
             }
 
             result.State = true;