homebridge-mynest 2.1.1 → 2.1.2

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project are documented here. From the first release onward, [release-please](https://github.com/googleapis/release-please) owns this file — do not hand-edit version headings after `0.1.0` ships.
 
+## [2.1.2](https://github.com/tbaur/homebridge-mynest/compare/v2.1.1...v2.1.2) (2026-10-26)
+
+
+### Bug Fixes
+
+* page auth-failed when Nest rejects the token ([#72](https://github.com/tbaur/homebridge-mynest/issues/72)) ([d69bf69](https://github.com/tbaur/homebridge-mynest/commit/d69bf69e1e67e4f75e8a5148edcbd2c933499ee4))
+
 ## [2.1.1](https://github.com/tbaur/homebridge-mynest/compare/v2.1.0...v2.1.1) (2026-10-26)
 
 

package/dist/api/session.d.ts

@@ -33,7 +33,7 @@ export declare function authenticatedHeaders(session: NestSession): Record<strin
 /**
  * Exchange the configured access token for a usable session.
  *
- * @throws {AuthenticationError} When Nest rejects the token.
+ * @throws {AuthenticationError} When Nest rejects the token (HTTP 400 or 401).
  * @throws {SessionShapeError} When the response is accepted but omits a field
  *   the plugin needs, or names a transport host off Nest infrastructure. Either
  *   means Nest changed the contract; a new token would not help.

package/dist/api/session.js

@@ -48,26 +48,42 @@ function authenticatedHeaders(session) {
         'Content-Type': 'application/json',
     };
 }
+/**
+ * Fetch `GET /session`, reporting HTTP 400 or 401 as a rejected token.
+ *
+ * @throws {AuthenticationError} On HTTP 400 or 401.
+ */
+async function requestSession(options) {
+    try {
+        return await (0, http_1.requestJson)(options.endpoints.sessionUrl, {
+            method: 'GET',
+            headers: sessionHeaders(options.accessToken),
+            timeoutMs: settings_1.SESSION_TIMEOUT_MS,
+            fetchImpl: options.fetchImpl,
+            signal: options.signal,
+        });
+    }
+    catch (error) {
+        if (!(0, errors_1.isSessionTokenRejection)(error) || error instanceof errors_1.AuthenticationError) {
+            throw error;
+        }
+        throw new errors_1.AuthenticationError(error.message, { cause: error, status: error.httpStatus });
+    }
+}
 /**
  * Exchange the configured access token for a usable session.
  *
- * @throws {AuthenticationError} When Nest rejects the token.
+ * @throws {AuthenticationError} When Nest rejects the token (HTTP 400 or 401).
  * @throws {SessionShapeError} When the response is accepted but omits a field
  *   the plugin needs, or names a transport host off Nest infrastructure. Either
  *   means Nest changed the contract; a new token would not help.
  */
 async function openSession(options) {
-    const { accessToken, endpoints, log } = options;
+    const { accessToken, log } = options;
     if (log.debugEnabled) {
         log.debug(`Opening a Nest session with the configured token ${(0, sanitizers_1.previewSecret)(accessToken)}`);
     }
-    const body = await (0, http_1.requestJson)(endpoints.sessionUrl, {
-        method: 'GET',
-        headers: sessionHeaders(accessToken),
-        timeoutMs: settings_1.SESSION_TIMEOUT_MS,
-        fetchImpl: options.fetchImpl,
-        signal: options.signal,
-    });
+    const body = await requestSession(options);
     const token = typeof body.access_token === 'string' ? body.access_token : undefined;
     // Only a scalar. `String()` accepts anything, so an object would become
     // `'[object Object]'` — truthy, so it passes the missing-field check below and

package/dist/errors/index.d.ts

@@ -28,7 +28,8 @@ export declare class ConfigurationError extends NestError {
     readonly isRetryable = false;
 }
 /**
- * Nest rejected the access token (HTTP 401).
+ * Nest rejected the access token: HTTP 401 anywhere, or HTTP 400 from the
+ * session endpoint (see {@link isSessionTokenRejection}).
  *
  * Not retryable: the token is copied by hand from a browser session and only a
  * new one will help. Retrying a rejected token is also how an account attracts
@@ -37,11 +38,24 @@ export declare class ConfigurationError extends NestError {
 export declare class AuthenticationError extends NestError {
     readonly code = "AUTH_ERROR";
     readonly isRetryable = false;
-    readonly httpStatus = 401;
+    readonly httpStatus: number;
     constructor(message?: string, options?: {
         cause?: Error;
+        status?: number;
     });
 }
+/**
+ * Whether a failed session open proves the configured token is unusable.
+ *
+ * The session endpoint takes nothing but the token, and Nest answers a
+ * missing or bad one with 400 (`invalid_request`) or 401. Every other failure
+ * retries, because a 403 or an unfamiliar code can be an edge block that
+ * clears on its own. Retrying never hides an outage: the alarm feed goes stale
+ * and alarm-feed-stale pages whatever the cause.
+ */
+export declare function isSessionTokenRejection(error: unknown): error is NestError & {
+    httpStatus: number;
+};
 /**
  * Nest answered HTTP 403 Forbidden.
  *

package/dist/errors/index.js

@@ -9,6 +9,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CircuitBreakerError = exports.ObserveStreamError = exports.ApiParseError = exports.ApiResponseError = exports.RateLimitError = exports.TimeoutError = exports.NetworkError = exports.SessionShapeError = exports.ForbiddenError = exports.AuthenticationError = exports.ConfigurationError = exports.NestError = void 0;
+exports.isSessionTokenRejection = isSessionTokenRejection;
 exports.isFatalTransportError = isFatalTransportError;
 exports.isCircuitBreakerFailure = isCircuitBreakerFailure;
 exports.parseRetryAfterMs = parseRetryAfterMs;
@@ -42,7 +43,8 @@ class ConfigurationError extends NestError {
 }
 exports.ConfigurationError = ConfigurationError;
 /**
- * Nest rejected the access token (HTTP 401).
+ * Nest rejected the access token: HTTP 401 anywhere, or HTTP 400 from the
+ * session endpoint (see {@link isSessionTokenRejection}).
  *
  * Not retryable: the token is copied by hand from a browser session and only a
  * new one will help. Retrying a rejected token is also how an account attracts
@@ -51,12 +53,25 @@ exports.ConfigurationError = ConfigurationError;
 class AuthenticationError extends NestError {
     code = 'AUTH_ERROR';
     isRetryable = false;
-    httpStatus = 401;
+    httpStatus;
     constructor(message = 'Nest rejected the configured access token. Sign in at https://home.nest.com, open https://home.nest.com/session, and copy a fresh "access_token".', options) {
-        super(message, options);
+        super(message, options?.cause ? { cause: options.cause } : undefined);
+        this.httpStatus = options?.status ?? 401;
     }
 }
 exports.AuthenticationError = AuthenticationError;
+/**
+ * Whether a failed session open proves the configured token is unusable.
+ *
+ * The session endpoint takes nothing but the token, and Nest answers a
+ * missing or bad one with 400 (`invalid_request`) or 401. Every other failure
+ * retries, because a 403 or an unfamiliar code can be an edge block that
+ * clears on its own. Retrying never hides an outage: the alarm feed goes stale
+ * and alarm-feed-stale pages whatever the cause.
+ */
+function isSessionTokenRejection(error) {
+    return error instanceof NestError && (error.httpStatus === 400 || error.httpStatus === 401);
+}
 /**
  * Nest answered HTTP 403 Forbidden.
  *

package/dist/nest-signals.d.ts

@@ -47,10 +47,12 @@ export declare class NestSignals {
     #private;
     constructor(writer: SignalWriter, graceMs?: number);
     /**
-     * Start the alarm feed grace.
+     * Write auth-failed and alarm-feed-stale clear, and start the alarm feed grace.
      *
-     * Does not write. Call once, before the first request, so a feed that is
-     * already down at launch still pages.
+     * Call once, before the first request. The write lists this plugin in
+     * homebridge-pagerduty even if Nest never answers, and the grace timer pages
+     * for a feed that is already down at launch. Smoke and CO wait for a fresh
+     * feed, so a restart cannot clear a real alarm.
      */
     start(): void;
     /** Nest accepted the token. Clears auth-failed. */

package/dist/nest-signals.js

@@ -58,16 +58,20 @@ class NestSignals {
         this.#graceMs = graceMs;
     }
     /**
-     * Start the alarm feed grace.
+     * Write auth-failed and alarm-feed-stale clear, and start the alarm feed grace.
      *
-     * Does not write. Call once, before the first request, so a feed that is
-     * already down at launch still pages.
+     * Call once, before the first request. The write lists this plugin in
+     * homebridge-pagerduty even if Nest never answers, and the grace timer pages
+     * for a feed that is already down at launch. Smoke and CO wait for a fresh
+     * feed, so a restart cannot clear a real alarm.
      */
     start() {
-        if (this.#isClosed || this.#hasStarted) {
+        if (this.#isClosed || this.#hasStarted || this.#hasStopped) {
             return;
         }
         this.#hasStarted = true;
+        this.#writeAuthFailedClear();
+        this.#writeFeedStale(false);
         this.#armStaleTimer();
     }
     /** Nest accepted the token. Clears auth-failed. */
@@ -75,11 +79,7 @@ class NestSignals {
         if (this.#isClosed || this.#hasStopped) {
             return;
         }
-        this.#writer.write(exports.SIGNAL_AUTH_FAILED, {
-            active: false,
-            severity: 'error',
-            summary: exports.TOKEN_REJECTED_SUMMARY,
-        });
+        this.#writeAuthFailedClear();
     }
     /** Record the Protects HomeKit is showing and whether their alarm feed is fresh. */
     update(protects, isFeedAvailable) {
@@ -132,6 +132,13 @@ class NestSignals {
         this.#clearStaleTimer();
         this.#writer.close();
     }
+    #writeAuthFailedClear() {
+        this.#writer.write(exports.SIGNAL_AUTH_FAILED, {
+            active: false,
+            severity: 'error',
+            summary: exports.TOKEN_REJECTED_SUMMARY,
+        });
+    }
     #writeFeedStale(active) {
         this.#writer.write(exports.SIGNAL_ALARM_FEED_STALE, {
             active,

package/dist/platform.js

@@ -66,7 +66,32 @@ const UPDATE_COALESCE_MS = 250;
  * only remaining signal that HomeKit's values are frozen.
  */
 const FATAL_REMINDER_MS = 60 * 60_000;
-const TOKEN_REJECTED_MESSAGE = 'Nest token rejected. Get a new token from https://home.nest.com/session and restart Homebridge.';
+function tokenRejectedMessage(status) {
+    return `Nest rejected the token (HTTP ${status}). Get a new token from https://home.nest.com/session and restart Homebridge.`;
+}
+/** A few words for the startup retry line; the full error goes to debug. */
+function describeStartupFailure(error) {
+    if (error instanceof errors_1.CircuitBreakerError) {
+        return 'paused after repeated failures';
+    }
+    if (error instanceof errors_1.TimeoutError) {
+        return 'timed out';
+    }
+    if (error instanceof errors_1.NetworkError) {
+        return 'network error';
+    }
+    if (error instanceof errors_1.ApiParseError) {
+        return 'unexpected response';
+    }
+    if (error instanceof errors_1.NestError && error.httpStatus !== undefined) {
+        return `HTTP ${error.httpStatus}`;
+    }
+    return (0, sanitizers_1.sanitizeError)(error);
+}
+function formatDelay(ms) {
+    const seconds = Math.round(ms / 1000);
+    return seconds < 120 ? `${seconds}s` : `${Math.round(seconds / 60)} min`;
+}
 function stopReasonFor(error) {
     if (error instanceof errors_1.SessionShapeError) {
         return 'session';
@@ -203,6 +228,9 @@ class MyNestPlatform {
             for (const warning of warnings) {
                 this.#log.warn(warning);
             }
+            if (resolved.allowThermostatControl) {
+                this.#log.info('Thermostat control enabled');
+            }
         }
         catch (error) {
             // Homebridge keeps running other platforms, so this must not throw. The
@@ -252,9 +280,6 @@ class MyNestPlatform {
         this.#holdUnpublishedProtectAlarms();
         this.#signals?.start();
         this.#startedAt = Date.now();
-        if (this.#config.allowThermostatControl) {
-            this.#log.info('Thermostat control enabled');
-        }
         const diagnostics = this.#diagnostics;
         const transport = new transport_1.NestTransport({
             accessToken: this.#config.accessToken,
@@ -302,8 +327,8 @@ class MyNestPlatform {
             if (this.#isShuttingDown) {
                 return;
             }
-            this.#log.warn(`Nest unreachable at startup (${(0, sanitizers_1.sanitizeError)(error)}), retrying`);
-            this.#scheduleStartRetry();
+            this.#log.debug(`Startup failed: ${(0, sanitizers_1.sanitizeError)(error)}`);
+            this.#scheduleStartRetry(describeStartupFailure(error));
             return;
         }
         this.#startRetryAttempt = 0;
@@ -320,7 +345,7 @@ class MyNestPlatform {
      * the plugin permanently idle — and cache-restored Protect tiles keep whatever
      * smoke/CO value Homebridge persisted, with no handler to mark them faulted.
      */
-    #scheduleStartRetry() {
+    #scheduleStartRetry(reason) {
         if (this.#isShuttingDown || this.#hasFatal || this.#startRetryTimer) {
             return;
         }
@@ -329,6 +354,7 @@ class MyNestPlatform {
         this.#holdUnpublishedProtectAlarms();
         this.#startRetryAttempt++;
         const delayMs = (0, retry_1.computeBackoffMs)(this.#startRetryAttempt);
+        this.#log.warn(`Could not connect to Nest (${reason}), retrying in ${formatDelay(delayMs)}`);
         this.#startRetryTimer = setTimeout(() => {
             this.#startRetryTimer = null;
             if (this.#isShuttingDown || this.#hasFatal) {
@@ -393,7 +419,11 @@ class MyNestPlatform {
         }
         this.#hasFatal = true;
         const isSessionShape = error instanceof errors_1.SessionShapeError;
-        this.#log.error(error instanceof errors_1.AuthenticationError ? TOKEN_REJECTED_MESSAGE : error.message);
+        const message = error instanceof errors_1.AuthenticationError
+            ? tokenRejectedMessage(error.httpStatus)
+            : error.message;
+        this.#log.error(message);
+        this.#log.debug(`Stopped by: ${(0, sanitizers_1.sanitizeError)(error)}`);
         this.#signals?.noteStopped(stopReasonFor(error));
         // Mark Protect smoke/CO inactive/faulted while handlers can still refresh.
         // `#stop` sets `#isShuttingDown` and drops `#scheduleUpdate`, so the
@@ -417,7 +447,7 @@ class MyNestPlatform {
         // the single error line above scrolls out of the log within hours.
         const reminder = isSessionShape
             ? 'Still stopped: unsupported Nest session format. Readings are frozen.'
-            : `Still stopped: ${TOKEN_REJECTED_MESSAGE}`;
+            : `Still stopped: ${message}`;
         this.#fatalReminderTimer = setInterval(() => {
             this.#log.error(reminder);
         }, FATAL_REMINDER_MS);

package/docs/PROTOCOL.md

@@ -29,7 +29,7 @@ HomeKit accessories are unregistered only when Nest has confirmed a device is go
 | Observe never connected this session | Do not unregister (REST-only view cannot prove thermostats are gone) |
 | Cached accessory not named by Nest since the restart | Two settled Observe snapshots that both omit it before prune |
 | Device absent from the Observe ∪ REST inventory after the above | Unregister from HomeKit |
-| Expired or revoked access token (HTTP 401, or a session this plugin cannot use) | Stop updates; **keep** accessories. HTTP 403 does not stop the plugin, including when both transports exhaust their budget. Each transport probes again after the cooldown. Nest Account auth is a manually pasted session token, so unregistering would bounce rooms and automations until the user pastes a fresh token and restarts |
+| Expired, revoked or missing access token (HTTP 401 anywhere, HTTP 400 from `/session`, or a session this plugin cannot use) | Stop updates; **keep** accessories. Any other failure, including HTTP 403 from either host, retries and does not stop the plugin, including when both transports exhaust their budget. Each transport probes again after the cooldown. Nest Account auth is a manually pasted session token, so unregistering would bounce rooms and automations until the user pastes a fresh token and restarts |
 
 Unusable plugin config at startup (missing/invalid token shape, etc.) **keeps** the cached accessories, for the same reason an expired token does. A typo, a half-edited `config.json`, or a truncated token would otherwise destroy every room assignment, scene membership, and automation target in the Home app — and fixing the config does not bring them back, because HomeKit treats the re-registered accessories as new devices. A config error cannot warrant a more destructive response than a revoked token. The plugin logs why and publishes nothing until it is restarted with a usable config.
 

package/docs/README-DETAILED.md

@@ -131,10 +131,10 @@ Each condition below then opens a PagerDuty alert while it is present, and resol
 | --- | --- | --- |
 | `smoke` | critical | Any Protect reports a smoke warning or emergency |
 | `co` | critical | Any Protect reports a carbon monoxide warning or emergency |
-| `alarm-feed-stale` | error | The Protect alarm feed has been unavailable for 5 minutes, so HomeKit may not show a smoke or CO alarm |
-| `auth-failed` | error | The plugin stopped because Nest rejected the token, the token in the config is missing or invalid, or Nest changed its session format |
+| `alarm-feed-stale` | error | The Protect alarm feed has been unavailable for 5 minutes, whatever the cause, so HomeKit may not show a smoke or CO alarm |
+| `auth-failed` | error | The plugin stopped because Nest rejected the token (HTTP 400 or 401), the token in the config is missing or invalid, or Nest changed its session format |
 
-Each signal covers the whole house. The summary does not name the Protect, so check the Nest app for which one is alarming. While the alarm feed is stale, `smoke` and `co` keep their last value. They do not clear until fresh readings arrive. While `auth-failed` is active, `alarm-feed-stale` stays off, so a stopped plugin sends one page.
+Each signal covers the whole house. The summary does not name the Protect, so check the Nest app for which one is alarming. While the alarm feed is stale, `smoke` and `co` keep their last value. They do not clear until fresh readings arrive. While `auth-failed` is active, `alarm-feed-stale` stays off, so a stopped plugin sends one page. Any other failure, such as HTTP 403, an unfamiliar error code or a network outage, keeps retrying and pages `alarm-feed-stale` if it lasts 5 minutes. The plugin writes `auth-failed` and `alarm-feed-stale` at startup, so homebridge-pagerduty lists it even if Nest never answers.
 
 ## Troubleshooting
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-mynest",
   "displayName": "Homebridge My Nest",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "Homebridge plugin for Nest thermostats (with Eco Mode), Nest Protect, and Nest Temperature Sensors using a Nest Account access token",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",