homebridge-navilink 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.0.3](https://github.com/tbaur/homebridge-navilink/compare/v1.0.2...v1.0.3) (2026-09-20)
+
+
+### Bug Fixes
+
+* fail fast REST sign-in during a sustained cloud outage ([#20](https://github.com/tbaur/homebridge-navilink/issues/20)) ([41f0a39](https://github.com/tbaur/homebridge-navilink/commit/41f0a3963d9333850144d243945b83b6d6ac725c))
+
 ## [1.0.2](https://github.com/tbaur/homebridge-navilink/compare/v1.0.1...v1.0.2) (2026-09-20)
 
 

package/README.md

@@ -1,11 +1,11 @@
 # homebridge-navilink
 
-[![Tests](https://github.com/tbaur/homebridge-navilink/actions/workflows/test.yml/badge.svg)](https://github.com/tbaur/homebridge-navilink/actions/workflows/test.yml)
-[![npm version](https://img.shields.io/npm/v/homebridge-navilink?style=flat-square)](https://www.npmjs.com/package/homebridge-navilink)
-[![npm downloads](https://img.shields.io/npm/dt/homebridge-navilink?label=downloads&style=flat-square)](https://www.npmjs.com/package/homebridge-navilink)
-[![Node.js](https://img.shields.io/badge/node-22%20%7C%7C%2024%20%7C%7C%2026-green)](https://nodejs.org)
-[![Homebridge](https://img.shields.io/badge/homebridge-2.x-purple)](https://homebridge.io)
-[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+![Tests](https://github.com/tbaur/homebridge-navilink/actions/workflows/test.yml/badge.svg)
+![npm version](https://img.shields.io/npm/v/homebridge-navilink?style=flat-square)
+![npm downloads](https://img.shields.io/npm/dt/homebridge-navilink?label=downloads&style=flat-square)
+![Node.js](https://img.shields.io/badge/node-22%20%7C%7C%2024%20%7C%7C%2026-green)
+![Homebridge](https://img.shields.io/badge/homebridge-2.x-purple)
+![License](https://img.shields.io/badge/license-Apache--2.0-blue)
 
 **Navien combi boilers and water heaters in Apple HomeKit.** Hot water and space-heating thermostats, recirculation, faults and temperature probes, with changes arriving as they happen rather than on a polling loop. Verified against an NCB-240E (firmware 4352).
 
@@ -13,6 +13,8 @@ Scheduling, weekly programmes and commissioning stay in the NaviLink app, which
 
 ## Features
 
+
+
 ### Per appliance
 
 - **Hot water thermostat:** the domestic hot water setpoint, reading the actual outlet temperature
@@ -22,6 +24,8 @@ Scheduling, weekly programmes and commissioning stay in the NaviLink app, which
 - **Fault sensor:** a contact sensor that opens and logs on an error code, so HomeKit can notify you
 - **Temperature sensors:** hot water in and out, heating flow and return, and the optional outdoor probe
 
+
+
 ### Reliability
 
 - **Push, not polling.** The gateway sends changes as they happen, so a setpoint changed at the wall controller or in the NaviLink app reaches HomeKit in about a second. The poll is only a backstop
@@ -30,6 +34,9 @@ Scheduling, weekly programmes and commissioning stay in the NaviLink app, which
 - **A connected socket is not a live appliance.** Readings carry the time they were taken, and a stale one becomes No Response instead
 - **State:** No Response until the appliance has actually been read, and not a value it cannot confirm
 - **Never loses your rooms:** a broken config disables the platform without unregistering anything
+- **A REST circuit breaker** fails fast during a sustained cloud outage. The log is `Circuit breaker CLOSED -> OPEN`, then `HALF_OPEN` and `CLOSED` when it recovers. Firmware reads do not trip it
+
+
 
 ### Quality
 
@@ -42,6 +49,8 @@ Every accessory, field and log line is documented in [Detailed documentation](do
 
 ## Quick Start
 
+
+
 ### 1. Install
 
 **Homebridge UI** (recommended): Plugins → Search `homebridge-navilink` → Install
@@ -50,6 +59,8 @@ Every accessory, field and log line is documented in [Detailed documentation](do
 npm install -g homebridge-navilink
 ```
 
+
+
 ### 2. Prepare your appliance
 
 Your NaviLink gateway must be connected and showing as online in the NaviLink app. Nothing needs enabling: the plugin uses the same service the app does. If the app cannot see the appliance, neither can this.
@@ -94,12 +105,15 @@ Accessories appear in the Home app after restart, showing No Response for the fe
 
 Any Navien appliance that the NaviLink app controls. The cloud interface is the same for all of them; what differs is which capabilities an appliance reports.
 
+
 | Verified against  | Notes                                             |
 | ----------------- | ------------------------------------------------- |
 | **NCB-240E (NG)** | Combi: hot water and space heating, firmware 4352 |
 
+
 Other families are decoded from the same table the NaviLink app uses and are expected to work, but nobody has confirmed them here:
 
+
 | Family             | Expected                                                                       |
 | ------------------ | ------------------------------------------------------------------------------ |
 | **NPE, NPE2, NPN** | Tankless water heaters. Hot water only; the heating thermostat disables itself |
@@ -108,12 +122,14 @@ Other families are decoded from the same table the NaviLink app uses and are exp
 | **NFB, NFC**       | Boilers with hot water and space heating                                       |
 | **NVW**            | Water heater with a tank                                                       |
 
+
 If yours is not listed, it will most likely work. Please open an issue with the output of `node scripts/capture-fixture.js --redact` either way, so the table can say so with confidence.
 
 ## Configuration Options
 
 Only one `NaviLink` platform block is supported. It can hold as many appliances as the account owns.
 
+
 | Option                        | Required to run | Description                                                                     |
 | ----------------------------- | --------------- | ------------------------------------------------------------------------------- |
 | `name`                        | ✓               | Plugin instance name shown in Homebridge logs                                   |
@@ -127,15 +143,17 @@ Only one `NaviLink` platform block is supported. It can hold as many appliances
 | `options.structuredLogs`      |                 | With diagnostics, also emit a JSON line (default false)                         |
 | `options.accessoryPrefix`     |                 | Prefix for every HomeKit name. Blank uses each appliance's name                 |
 
+
 Each entry in `devices[]` takes `id` and `name`, plus an optional `channel` and one flag per accessory: `dhw`, `heating`, `power`, `recirculation`, `fault`, `temperatureSensors` and `outdoorSensor`. The [detailed documentation](docs/README-DETAILED.md#devices-entries) describes each one.
 
 ## Not Working?
 
 1. **"NaviLink rejected the email address or password."** Sign in to the NaviLink app with the same credentials. The plugin has stopped trying on purpose, so fix the password and restart Homebridge
 2. **Everything shows No Response.** Check the log for `platform disabled`, which means the configuration could not be read
-3. **The heating thermostat says it has no loop.** Your appliance reports no space-heating circuit. Turn the accessory off in the settings
-4. **A recirculation switch that is not offered.** No pump is fitted, or it is not commissioned. Check the NaviLink app
+3. **The heating thermostat says it has no loop.** Your appliance reports no space-heating circuit
+4. **A recirculation switch that is not offered.** No pump is fitted, or it is not commissioned
 5. **`rate limited`.** The cloud rate-limits control. The plugin pauses and retries on the next press
+6. **`Circuit breaker CLOSED -> OPEN`.** Sign-in is paused; tiles stay No Response until the cloud recovers
 
 The [full troubleshooting list](docs/README-DETAILED.md#troubleshooting) covers more, including what Off on the hot water tile does once you allow power-off.
 
@@ -151,6 +169,8 @@ This plugin needs your NaviLink password, stores it in the Homebridge configurat
 - A NaviLink account with at least one gateway online
 - A working internet connection
 
+
+
 ## More Info
 
 - [Detailed documentation](docs/README-DETAILED.md)
@@ -160,6 +180,8 @@ This plugin needs your NaviLink password, stores it in the Homebridge configurat
 - [Report Issues](https://github.com/tbaur/homebridge-navilink/issues)
 - [Changelog](CHANGELOG.md)
 
+
+
 ## License
 
 Copyright 2026 tbaur

package/dist/api/circuit-breaker.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Circuit breaker for REST resilience.
+ *
+ * Prevents hammering the NaviLink REST cloud when it is down: after a
+ * threshold of service-health failures the breaker opens, later calls fail
+ * fast until a cooldown elapses, then a single half-open probe decides
+ * whether to close again or stay open.
+ *
+ * MQTT is a separate transport and is not gated here. A dead broker is the
+ * session reconnect loop and the `mqttDown` diagnostic, not this breaker.
+ */
+/** Circuit breaker states. */
+export declare enum CircuitState {
+    /** Normal operation — requests flow through. */
+    CLOSED = "CLOSED",
+    /** Circuit tripped — requests fail immediately. */
+    OPEN = "OPEN",
+    /** Testing whether the service recovered. */
+    HALF_OPEN = "HALF_OPEN"
+}
+/** Circuit breaker configuration. */
+export interface CircuitBreakerConfig {
+    /** Number of failures within the window before opening the circuit. */
+    failureThreshold: number;
+    /** Time in ms before trying half-open after opening. */
+    resetTimeout: number;
+    /** Max concurrent probe requests allowed in half-open state. */
+    halfOpenMax: number;
+    /** Sliding window (ms) for counting failures. */
+    failureWindow?: number;
+    /**
+     * Invoked whenever the circuit transitions between states. Used for
+     * observability so operators can see when the breaker opens or recovers.
+     */
+    onStateChange?: (from: CircuitState, to: CircuitState) => void;
+}
+/**
+ * Default circuit breaker configuration.
+ *
+ * `halfOpenMax` is 1 on purpose: establish is sequential (sign-in, then
+ * list), and a single probe keeps recovery deterministic, matching the
+ * sibling plugins.
+ */
+export declare const DEFAULT_CIRCUIT_BREAKER_CONFIG: CircuitBreakerConfig;
+/** Circuit breaker status snapshot. */
+export interface CircuitBreakerStatus {
+    state: CircuitState;
+    failures: number;
+    successes: number;
+    lastFailureTime: number | null;
+    halfOpenRequests: number;
+    isOpen: boolean;
+    remainingResetTime: number | null;
+}
+/**
+ * Circuit breaker for REST resilience.
+ * Prevents hammering NaviLink REST when it is returning sustained failures.
+ */
+export declare class CircuitBreaker {
+    private readonly failureThreshold;
+    private readonly resetTimeout;
+    private readonly halfOpenMax;
+    private readonly failureWindow;
+    private readonly onStateChange?;
+    private _state;
+    private failures;
+    private successes;
+    private lastFailureTime;
+    private halfOpenRequests;
+    private failureTimestamps;
+    constructor(config?: Partial<CircuitBreakerConfig>);
+    /** Current circuit state. */
+    get state(): CircuitState;
+    /** True when the circuit is open (requests should fail fast). */
+    get isOpen(): boolean;
+    /**
+     * Transition to a new state, notifying observers only on an actual change.
+     */
+    private transitionTo;
+    /** Drop failure timestamps that fall outside the sliding window. */
+    private cleanupFailures;
+    /** Whether the circuit currently allows a request through. */
+    canRequest(): boolean;
+    /** Record a successful request. */
+    recordSuccess(): void;
+    /** Record a failed request that reflects service health. */
+    recordFailure(): void;
+    /** Track a half-open probe request against the concurrency cap. */
+    trackHalfOpenRequest(): void;
+    /** Reset the circuit breaker to closed state. */
+    reset(): void;
+    /** Current circuit breaker status. */
+    getStatus(): CircuitBreakerStatus;
+    /**
+     * Execute a function with circuit breaker protection.
+     *
+     * @param isFailure Optional predicate controlling which thrown errors count
+     *   as service-health failures while CLOSED. Defaults to treating every
+     *   rejection as a failure. REST uses a narrower predicate (connection and
+     *   protocol errors). While HALF_OPEN, every terminal rejection still
+     *   re-opens the breaker so the probe slot cannot wedge.
+     */
+    execute<T>(fn: () => Promise<T>, isFailure?: (error: unknown) => boolean): Promise<T>;
+    /** Create a wrapped version of a function with circuit breaker protection. */
+    wrap<T extends unknown[], R>(fn: (...args: T) => Promise<R>, isFailure?: (error: unknown) => boolean): (...args: T) => Promise<R>;
+}

package/dist/api/circuit-breaker.js

@@ -0,0 +1,221 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview Circuit breaker for REST resilience.
+ *
+ * Prevents hammering the NaviLink REST cloud when it is down: after a
+ * threshold of service-health failures the breaker opens, later calls fail
+ * fast until a cooldown elapses, then a single half-open probe decides
+ * whether to close again or stay open.
+ *
+ * MQTT is a separate transport and is not gated here. A dead broker is the
+ * session reconnect loop and the `mqttDown` diagnostic, not this breaker.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreaker = exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = exports.CircuitState = void 0;
+const errors_1 = require("../utils/errors");
+/** Circuit breaker states. */
+var CircuitState;
+(function (CircuitState) {
+    /** Normal operation — requests flow through. */
+    CircuitState["CLOSED"] = "CLOSED";
+    /** Circuit tripped — requests fail immediately. */
+    CircuitState["OPEN"] = "OPEN";
+    /** Testing whether the service recovered. */
+    CircuitState["HALF_OPEN"] = "HALF_OPEN";
+})(CircuitState || (exports.CircuitState = CircuitState = {}));
+/**
+ * Default circuit breaker configuration.
+ *
+ * `halfOpenMax` is 1 on purpose: establish is sequential (sign-in, then
+ * list), and a single probe keeps recovery deterministic, matching the
+ * sibling plugins.
+ */
+exports.DEFAULT_CIRCUIT_BREAKER_CONFIG = {
+    failureThreshold: 5,
+    resetTimeout: 30_000,
+    halfOpenMax: 1,
+    failureWindow: 60_000,
+};
+/**
+ * Circuit breaker for REST resilience.
+ * Prevents hammering NaviLink REST when it is returning sustained failures.
+ */
+class CircuitBreaker {
+    failureThreshold;
+    resetTimeout;
+    halfOpenMax;
+    failureWindow;
+    onStateChange;
+    _state = CircuitState.CLOSED;
+    failures = 0;
+    successes = 0;
+    lastFailureTime = null;
+    halfOpenRequests = 0;
+    failureTimestamps = [];
+    constructor(config = {}) {
+        const merged = { ...exports.DEFAULT_CIRCUIT_BREAKER_CONFIG, ...config };
+        this.failureThreshold = merged.failureThreshold;
+        this.resetTimeout = merged.resetTimeout;
+        // At least one probe must be allowed. With a cap of 0, canRequest() would
+        // promote OPEN -> HALF_OPEN and then refuse every probe (0 < 0), wedging the
+        // breaker shut permanently with no path back to CLOSED.
+        this.halfOpenMax = Math.max(1, merged.halfOpenMax);
+        this.failureWindow = merged.failureWindow ?? 60_000;
+        this.onStateChange = merged.onStateChange;
+    }
+    /** Current circuit state. */
+    get state() {
+        return this._state;
+    }
+    /** True when the circuit is open (requests should fail fast). */
+    get isOpen() {
+        return this._state === CircuitState.OPEN;
+    }
+    /**
+     * Transition to a new state, notifying observers only on an actual change.
+     */
+    transitionTo(next) {
+        if (this._state === next) {
+            return;
+        }
+        const previous = this._state;
+        this._state = next;
+        this.onStateChange?.(previous, next);
+    }
+    /** Drop failure timestamps that fall outside the sliding window. */
+    cleanupFailures() {
+        const cutoff = Date.now() - this.failureWindow;
+        this.failureTimestamps = this.failureTimestamps.filter((stamp) => stamp > cutoff);
+        this.failures = this.failureTimestamps.length;
+    }
+    /** Whether the circuit currently allows a request through. */
+    canRequest() {
+        if (this._state === CircuitState.CLOSED) {
+            return true;
+        }
+        if (this._state === CircuitState.OPEN) {
+            if (this.lastFailureTime && (Date.now() - this.lastFailureTime) >= this.resetTimeout) {
+                this.halfOpenRequests = 0;
+                this.successes = 0;
+                this.transitionTo(CircuitState.HALF_OPEN);
+                return true;
+            }
+            return false;
+        }
+        if (this._state === CircuitState.HALF_OPEN) {
+            return this.halfOpenRequests < this.halfOpenMax;
+        }
+        return false;
+    }
+    /** Record a successful request. */
+    recordSuccess() {
+        if (this._state === CircuitState.HALF_OPEN) {
+            this.successes += 1;
+            if (this.successes >= this.halfOpenMax) {
+                this.reset();
+            }
+        }
+        else if (this._state === CircuitState.OPEN) {
+            // A request that was already in flight when the breaker re-opened still
+            // proves the service is reachable — close immediately rather than waiting
+            // out the full cooldown.
+            this.reset();
+        }
+        else if (this._state === CircuitState.CLOSED) {
+            this.cleanupFailures();
+        }
+    }
+    /** Record a failed request that reflects service health. */
+    recordFailure() {
+        // Already open: ignore late failures from overlapping half-open probes so
+        // they cannot keep pushing lastFailureTime forward and extend the cooldown.
+        if (this._state === CircuitState.OPEN) {
+            return;
+        }
+        const now = Date.now();
+        this.lastFailureTime = now;
+        this.failureTimestamps.push(now);
+        if (this._state === CircuitState.HALF_OPEN) {
+            this.halfOpenRequests = 0;
+            this.successes = 0;
+            this.transitionTo(CircuitState.OPEN);
+        }
+        else if (this._state === CircuitState.CLOSED) {
+            this.cleanupFailures();
+            if (this.failures >= this.failureThreshold) {
+                this.transitionTo(CircuitState.OPEN);
+            }
+        }
+    }
+    /** Track a half-open probe request against the concurrency cap. */
+    trackHalfOpenRequest() {
+        if (this._state === CircuitState.HALF_OPEN) {
+            this.halfOpenRequests += 1;
+        }
+    }
+    /** Reset the circuit breaker to closed state. */
+    reset() {
+        this.failures = 0;
+        this.successes = 0;
+        this.lastFailureTime = null;
+        this.halfOpenRequests = 0;
+        this.failureTimestamps = [];
+        this.transitionTo(CircuitState.CLOSED);
+    }
+    /** Current circuit breaker status. */
+    getStatus() {
+        const now = Date.now();
+        let remainingResetTime = null;
+        if (this._state === CircuitState.OPEN && this.lastFailureTime) {
+            remainingResetTime = Math.max(0, this.resetTimeout - (now - this.lastFailureTime));
+        }
+        return {
+            state: this._state,
+            failures: this.failures,
+            successes: this.successes,
+            lastFailureTime: this.lastFailureTime,
+            halfOpenRequests: this.halfOpenRequests,
+            isOpen: this.isOpen,
+            remainingResetTime,
+        };
+    }
+    /**
+     * Execute a function with circuit breaker protection.
+     *
+     * @param isFailure Optional predicate controlling which thrown errors count
+     *   as service-health failures while CLOSED. Defaults to treating every
+     *   rejection as a failure. REST uses a narrower predicate (connection and
+     *   protocol errors). While HALF_OPEN, every terminal rejection still
+     *   re-opens the breaker so the probe slot cannot wedge.
+     */
+    async execute(fn, isFailure = () => true) {
+        if (!this.canRequest()) {
+            const status = this.getStatus();
+            throw new errors_1.CircuitBreakerError(status.remainingResetTime ?? this.resetTimeout);
+        }
+        if (this._state === CircuitState.HALF_OPEN) {
+            this.trackHalfOpenRequest();
+        }
+        try {
+            const result = await fn();
+            this.recordSuccess();
+            return result;
+        }
+        catch (error) {
+            if (this._state === CircuitState.HALF_OPEN || isFailure(error)) {
+                this.recordFailure();
+            }
+            throw error;
+        }
+    }
+    /** Create a wrapped version of a function with circuit breaker protection. */
+    wrap(fn, isFailure) {
+        return (...args) => this.execute(() => fn(...args), isFailure);
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;

package/dist/api/index.d.ts

@@ -7,6 +7,7 @@
  * @fileoverview API barrel.
  */
 export * from './channel';
+export * from './circuit-breaker';
 export * from './http';
 export * from './identity';
 export * from './mqtt';

package/dist/api/index.js

@@ -23,6 +23,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./channel"), exports);
+__exportStar(require("./circuit-breaker"), exports);
 __exportStar(require("./http"), exports);
 __exportStar(require("./identity"), exports);
 __exportStar(require("./mqtt"), exports);

package/dist/api/rest.d.ts

@@ -25,6 +25,7 @@
  * is logged, and the fields the plugin does not need are never read out of it.
  */
 import type { PluginLogger } from '../types';
+import { type CircuitBreakerStatus } from './circuit-breaker';
 import { type JsonPost } from './http';
 import type { IotCredentials } from './sigv4';
 /** A signed-in session. */
@@ -67,6 +68,8 @@ export interface NaviLinkRestOptions {
         durationMs: number;
         ok: boolean;
     }) => void;
+    /** Fired when the breaker transitions into OPEN, so diagnostics can count a trip. */
+    onCircuitOpen?: () => void;
 }
 /** Talks to the NaviLink REST service. */
 export declare class NaviLinkRest {
@@ -75,7 +78,11 @@ export declare class NaviLinkRest {
     private readonly now;
     private readonly signal;
     private readonly metrics;
+    private readonly onCircuitOpen;
+    private readonly circuitBreaker;
     constructor(options: NaviLinkRestOptions);
+    /** Live breaker status for diagnostics. Never reads the network. */
+    getCircuitBreakerStatus(): CircuitBreakerStatus;
     /**
      * Exchange an email and password for a session.
      *
@@ -112,6 +119,21 @@ export declare class NaviLinkRest {
         additionalValue: string;
     }): Promise<string | undefined>;
     private call;
+    /**
+     * Run one REST logical attempt behind the circuit breaker.
+     *
+     * Pre-flight OPEN rejections do not count as API samples: nothing was sent.
+     * Connection and protocol errors trip the breaker; a rejected password does
+     * not. HALF_OPEN treats every terminal rejection as a failed probe so the
+     * slot cannot wedge.
+     */
+    private guarded;
+    /**
+     * Surface circuit-breaker transitions so operators can see when NaviLink
+     * REST is being treated as unavailable and when it recovers. OPEN is warn;
+     * HALF_OPEN (probe) and CLOSED (recovery) are info.
+     */
+    private logCircuitTransition;
     private readBody;
     /**
      * Turn a failed sign-in into the right kind of error.

package/dist/api/rest.js

@@ -29,6 +29,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NaviLinkRest = void 0;
 const settings_1 = require("../settings");
 const errors_1 = require("../utils/errors");
+const circuit_breaker_1 = require("./circuit-breaker");
 const http_1 = require("./http");
 /**
  * How long a session lasts when the cloud's answer is not believable.
@@ -55,12 +56,24 @@ class NaviLinkRest {
     now;
     signal;
     metrics;
+    onCircuitOpen;
+    circuitBreaker;
     constructor(options) {
         this.log = options.log;
         this.post = options.post ?? http_1.postJson;
         this.now = options.now ?? Date.now;
         this.signal = options.signal;
         this.metrics = options.metrics;
+        this.onCircuitOpen = options.onCircuitOpen;
+        this.circuitBreaker = new circuit_breaker_1.CircuitBreaker({
+            onStateChange: (from, to) => {
+                this.logCircuitTransition(from, to);
+            },
+        });
+    }
+    /** Live breaker status for diagnostics. Never reads the network. */
+    getCircuitBreakerStatus() {
+        return this.circuitBreaker.getStatus();
     }
     /**
      * Exchange an email and password for a session.
@@ -76,43 +89,45 @@ class NaviLinkRest {
             // COMMON_BAD_REQUEST, which looks like a credential problem.
             throw new TypeError('sign-in needs an email and a password as two strings');
         }
-        const response = await this.call('/user/sign-in', { userId: email, password });
-        const body = this.readBody(response.body, 'sign-in');
-        const data = asRecord(body.data);
-        const token = asRecord(data?.token);
-        const accessToken = asNonEmptyString(token?.accessToken);
-        if (accessToken === undefined || token === undefined || data === undefined) {
-            // Deliberately not keyed on the status code. **This API answers a
-            // rejected password with HTTP 200** and an error in the body, so a
-            // status check alone classifies a wrong password as a transient
-            // protocol fault, and then retries it every few seconds until the
-            // account is locked. The presence of a token is the only reliable
-            // discriminator, so that is what decides success here.
-            throw this.signInFailure(response.status, body);
-        }
-        const accessKeyId = asNonEmptyString(token.accessKeyId);
-        const secretKey = asNonEmptyString(token.secretKey);
-        const sessionToken = asNonEmptyString(token.sessionToken);
-        if (accessKeyId === undefined || secretKey === undefined || sessionToken === undefined) {
-            throw new errors_1.ProtocolError('the sign-in response carried no AWS IoT credentials, so live status is not available');
-        }
-        const userSeq = readUserSeq(data);
-        if (userSeq === undefined) {
-            throw new errors_1.ProtocolError('the sign-in response carried no account identifier');
-        }
-        return {
-            userSeq,
-            accessToken,
-            refreshToken: asNonEmptyString(token.refreshToken),
-            credentials: {
-                accessKeyId,
-                secretKey,
-                sessionToken,
-                endpoint: settings_1.IOT_ENDPOINT,
-                region: settings_1.IOT_REGION,
-            },
-            expiresAt: this.now() + this.sessionLifetimeMs(token),
-        };
+        return this.guarded(async () => {
+            const response = await this.call('/user/sign-in', { userId: email, password });
+            const body = this.readBody(response.body, 'sign-in');
+            const data = asRecord(body.data);
+            const token = asRecord(data?.token);
+            const accessToken = asNonEmptyString(token?.accessToken);
+            if (accessToken === undefined || token === undefined || data === undefined) {
+                // Deliberately not keyed on the status code. **This API answers a
+                // rejected password with HTTP 200** and an error in the body, so a
+                // status check alone classifies a wrong password as a transient
+                // protocol fault, and then retries it every few seconds until the
+                // account is locked. The presence of a token is the only reliable
+                // discriminator, so that is what decides success here.
+                throw this.signInFailure(response.status, body);
+            }
+            const accessKeyId = asNonEmptyString(token.accessKeyId);
+            const secretKey = asNonEmptyString(token.secretKey);
+            const sessionToken = asNonEmptyString(token.sessionToken);
+            if (accessKeyId === undefined || secretKey === undefined || sessionToken === undefined) {
+                throw new errors_1.ProtocolError('the sign-in response carried no AWS IoT credentials, so live status is not available');
+            }
+            const userSeq = readUserSeq(data);
+            if (userSeq === undefined) {
+                throw new errors_1.ProtocolError('the sign-in response carried no account identifier');
+            }
+            return {
+                userSeq,
+                accessToken,
+                refreshToken: asNonEmptyString(token.refreshToken),
+                credentials: {
+                    accessKeyId,
+                    secretKey,
+                    sessionToken,
+                    endpoint: settings_1.IOT_ENDPOINT,
+                    region: settings_1.IOT_REGION,
+                },
+                expiresAt: this.now() + this.sessionLifetimeMs(token),
+            };
+        });
     }
     /**
      * List the gateways on the account.
@@ -135,31 +150,33 @@ class NaviLinkRest {
     }
     /** One page of the device list, already parsed. */
     async listDevicePage(input, offset) {
-        const response = await this.call('/device/list', { offset, count: DEVICE_LIST_PAGE_SIZE, userId: input.email }, input.accessToken);
-        const body = this.readBody(response.body, 'device list');
-        if (response.status === 401 || response.status === 403) {
-            throw new errors_1.AuthenticationError('the cloud rejected the session token when listing devices');
-        }
-        if (response.status !== 200) {
-            throw new errors_1.ProtocolError(`the device list failed: ${describeApiFailure(response.status, body)}`);
-        }
-        // Two shapes have been seen: a bare array, and an object wrapping one.
-        // Both are accepted rather than one being declared correct, because there
-        // is no specification to be right about.
-        const data = body.data;
-        const raw = Array.isArray(data)
-            ? data
-            : (asRecord(data)?.deviceList ?? asRecord(data)?.devices);
-        if (!Array.isArray(raw)) {
-            throw new errors_1.ProtocolError('the device list response did not contain a list of devices');
-        }
-        return {
-            entries: raw.flatMap((entry) => {
-                const device = this.readListedDevice(entry);
-                return device === undefined ? [] : [device];
-            }),
-            isFull: raw.length >= DEVICE_LIST_PAGE_SIZE,
-        };
+        return this.guarded(async () => {
+            const response = await this.call('/device/list', { offset, count: DEVICE_LIST_PAGE_SIZE, userId: input.email }, input.accessToken);
+            const body = this.readBody(response.body, 'device list');
+            if (response.status === 401 || response.status === 403) {
+                throw new errors_1.AuthenticationError('the cloud rejected the session token when listing devices');
+            }
+            if (response.status !== 200) {
+                throw new errors_1.ProtocolError(`the device list failed: ${describeApiFailure(response.status, body)}`);
+            }
+            // Two shapes have been seen: a bare array, and an object wrapping one.
+            // Both are accepted rather than one being declared correct, because there
+            // is no specification to be right about.
+            const data = body.data;
+            const raw = Array.isArray(data)
+                ? data
+                : (asRecord(data)?.deviceList ?? asRecord(data)?.devices);
+            if (!Array.isArray(raw)) {
+                throw new errors_1.ProtocolError('the device list response did not contain a list of devices');
+            }
+            return {
+                entries: raw.flatMap((entry) => {
+                    const device = this.readListedDevice(entry);
+                    return device === undefined ? [] : [device];
+                }),
+                isFull: raw.length >= DEVICE_LIST_PAGE_SIZE,
+            };
+        });
     }
     /**
      * Read a single device's detail.
@@ -170,6 +187,8 @@ class NaviLinkRest {
      * read, so they cannot reach a log, an accessory context or a capture.
      */
     async readFirmware(input) {
+        // Not behind the breaker. Firmware is optional, the session swallows
+        // failures, and a flaky device/info must not trip OPEN after MQTT is live.
         const response = await this.call('/device/info', {
             macAddress: input.macAddress,
             additionalValue: input.additionalValue,
@@ -209,6 +228,49 @@ class NaviLinkRest {
             throw error;
         }
     }
+    /**
+     * Run one REST logical attempt behind the circuit breaker.
+     *
+     * Pre-flight OPEN rejections do not count as API samples: nothing was sent.
+     * Connection and protocol errors trip the breaker; a rejected password does
+     * not. HALF_OPEN treats every terminal rejection as a failed probe so the
+     * slot cannot wedge.
+     */
+    async guarded(work) {
+        if (!this.circuitBreaker.canRequest()) {
+            const status = this.circuitBreaker.getStatus();
+            throw new errors_1.CircuitBreakerError(status.remainingResetTime ?? circuit_breaker_1.DEFAULT_CIRCUIT_BREAKER_CONFIG.resetTimeout);
+        }
+        if (this.circuitBreaker.state === circuit_breaker_1.CircuitState.HALF_OPEN) {
+            this.circuitBreaker.trackHalfOpenRequest();
+        }
+        try {
+            const result = await work();
+            this.circuitBreaker.recordSuccess();
+            return result;
+        }
+        catch (error) {
+            if (this.circuitBreaker.state === circuit_breaker_1.CircuitState.HALF_OPEN || isCircuitBreakerFailure(error)) {
+                this.circuitBreaker.recordFailure();
+            }
+            throw error;
+        }
+    }
+    /**
+     * Surface circuit-breaker transitions so operators can see when NaviLink
+     * REST is being treated as unavailable and when it recovers. OPEN is warn;
+     * HALF_OPEN (probe) and CLOSED (recovery) are info.
+     */
+    logCircuitTransition(from, to) {
+        const message = `Circuit breaker ${from} -> ${to}`;
+        if (to === circuit_breaker_1.CircuitState.OPEN) {
+            this.log.warn(message);
+            this.onCircuitOpen?.();
+        }
+        else {
+            this.log.info(message);
+        }
+    }
     readBody(text, what) {
         const parsed = (0, http_1.parseJsonBody)(text);
         const record = asRecord(parsed);
@@ -289,6 +351,14 @@ class NaviLinkRest {
     }
 }
 exports.NaviLinkRest = NaviLinkRest;
+/**
+ * Errors that should count against the circuit breaker: the cloud could not
+ * be reached, or it answered with something we cannot parse. A rejected
+ * password is the user's problem, not service health.
+ */
+function isCircuitBreakerFailure(error) {
+    return error instanceof errors_1.ConnectionError || error instanceof errors_1.ProtocolError;
+}
 /** Describe an API failure without quoting a body that may hold a token. */
 function describeApiFailure(status, body) {
     const message = asNonEmptyString(body.msg);

package/dist/diagnostics/collector.d.ts

@@ -13,8 +13,9 @@
  *   - `rollup()`         — `{ health, reasons[] }`
  *
  * NaviLink variant of the sibling collectors: REST sign-in plus an MQTT
- * session, no circuit breaker. It only reads in-memory state via `readers`;
- * it never touches the network.
+ * session. The REST circuit breaker is included so sustained cloud outages
+ * surface as `circuitBreakerOpen` in the health rollup. It only reads
+ * in-memory state via `readers`; it never touches the network.
  */
 import type { DeviceGauges, DiagnosticsSnapshot, MqttTransportState, NaviLinkPlatformConfig, SessionMetrics } from '../types';
 /**
@@ -28,6 +29,9 @@ export interface DiagnosticsReaders {
     tokenExpiresInSec: () => number | null;
     tokenLastRefreshAt: () => number | null;
     pollingCadenceSec: () => number;
+    circuitBreaker: () => {
+        state: string;
+    };
 }
 interface CollectorOptions {
     pluginVersion: string;
@@ -53,6 +57,8 @@ export declare class DiagnosticsCollector implements SessionMetrics {
     private mqttReconnects;
     private commands;
     private pushes;
+    private breakerTrips;
+    private lastTripAt;
     private lastPollDurationMs;
     private readonly latencies;
     private readonly recentOutcomes;
@@ -64,12 +70,15 @@ export declare class DiagnosticsCollector implements SessionMetrics {
     command(): void;
     sessionRefresh(): void;
     push(): void;
+    /** Record a circuit-breaker trip (transition into the open state). */
+    breakerTrip(): void;
     /** Nearest-rank percentile (0..100) over the recent-latency window. */
     percentile(p: number): number;
     /**
      * Classify current health. Degraded when the MQTT session has been down
-     * longer than the grace window, credentials were rejected, or recent REST
-     * calls are failing at a high rate.
+     * longer than the grace window, credentials were rejected, the REST
+     * circuit breaker is open or probing, or recent REST calls are failing
+     * at a high rate.
      */
     rollup(readers: DiagnosticsReaders): HealthRollup;
     buildHeartbeat(readers: DiagnosticsReaders): DiagnosticsSnapshot;

package/dist/diagnostics/collector.js

@@ -14,8 +14,9 @@
  *   - `rollup()`         — `{ health, reasons[] }`
  *
  * NaviLink variant of the sibling collectors: REST sign-in plus an MQTT
- * session, no circuit breaker. It only reads in-memory state via `readers`;
- * it never touches the network.
+ * session. The REST circuit breaker is included so sustained cloud outages
+ * surface as `circuitBreakerOpen` in the health rollup. It only reads
+ * in-memory state via `readers`; it never touches the network.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DiagnosticsCollector = void 0;
@@ -42,6 +43,8 @@ class DiagnosticsCollector {
     mqttReconnects = 0;
     commands = 0;
     pushes = 0;
+    breakerTrips = 0;
+    lastTripAt = null;
     lastPollDurationMs = null;
     latencies = [];
     recentOutcomes = [];
@@ -88,6 +91,11 @@ class DiagnosticsCollector {
     push() {
         this.pushes += 1;
     }
+    /** Record a circuit-breaker trip (transition into the open state). */
+    breakerTrip() {
+        this.breakerTrips += 1;
+        this.lastTripAt = this.now();
+    }
     /** Nearest-rank percentile (0..100) over the recent-latency window. */
     percentile(p) {
         if (this.latencies.length === 0) {
@@ -101,8 +109,9 @@ class DiagnosticsCollector {
     }
     /**
      * Classify current health. Degraded when the MQTT session has been down
-     * longer than the grace window, credentials were rejected, or recent REST
-     * calls are failing at a high rate.
+     * longer than the grace window, credentials were rejected, the REST
+     * circuit breaker is open or probing, or recent REST calls are failing
+     * at a high rate.
      */
     rollup(readers) {
         const reasons = [];
@@ -120,6 +129,10 @@ class DiagnosticsCollector {
                 reasons.push('mqttDown');
             }
         }
+        const breakerState = readers.circuitBreaker().state;
+        if (breakerState === 'OPEN' || breakerState === 'HALF_OPEN') {
+            reasons.push('circuitBreakerOpen');
+        }
         const total = this.recentOutcomes.length;
         if (total >= API_ERROR_MIN_SAMPLES) {
             const errors = this.recentOutcomes.filter((ok) => !ok).length;
@@ -143,6 +156,7 @@ class DiagnosticsCollector {
             reconnects: current.mqttReconnects - this.marker.mqttReconnects,
             commands: current.commands - this.marker.commands,
             pushes: current.pushes - this.marker.pushes,
+            trips: current.breakerTrips - this.marker.breakerTrips,
         }, readers);
         this.marker = current;
         return report;
@@ -157,6 +171,7 @@ class DiagnosticsCollector {
             reconnects: this.mqttReconnects,
             commands: this.commands,
             pushes: this.pushes,
+            trips: this.breakerTrips,
         }, readers);
         report.config = { ...this.configEcho };
         return report;
@@ -174,6 +189,7 @@ class DiagnosticsCollector {
             mqttReconnects: this.mqttReconnects,
             commands: this.commands,
             pushes: this.pushes,
+            breakerTrips: this.breakerTrips,
         };
     }
     buildReport(msg, counters, readers) {
@@ -210,6 +226,11 @@ class DiagnosticsCollector {
                 commands: counters.commands,
                 pushes: counters.pushes,
             },
+            circuitBreaker: {
+                state: readers.circuitBreaker().state,
+                lastTripAt: this.lastTripAt,
+                trips: counters.trips,
+            },
         };
     }
 }

package/dist/diagnostics/format.d.ts

@@ -17,8 +17,10 @@ export declare function formatReasons(reasons: string[]): string;
  * Concise summary matching the sibling plugins:
  * `Health: healthy | devices 1/1 | mqtt live | api p50 12ms p95 40ms (req 3, err 0)`.
  *
- * The heartbeat uses the short `mqtt` token. Standalone lifecycle lines keep
- * `Publish-subscribe (mqtt)` so a lone `up` / `recovered` still names the channel.
+ * A non-CLOSED REST breaker inserts `breaker OPEN` (or `HALF_OPEN`) after
+ * devices, matching the sibling plugins. The heartbeat uses the short `mqtt`
+ * token. Standalone lifecycle lines keep `Publish-subscribe (mqtt)` so a
+ * lone `up` / `recovered` still names the channel.
  */
 export declare function formatDiagnosticLine(report: DiagnosticsSnapshot): string;
 /** State-only line for a healthy/degraded flip. The heartbeat already has the body. */

package/dist/diagnostics/format.js

@@ -54,17 +54,22 @@ function formatReasons(reasons) {
  * Concise summary matching the sibling plugins:
  * `Health: healthy | devices 1/1 | mqtt live | api p50 12ms p95 40ms (req 3, err 0)`.
  *
- * The heartbeat uses the short `mqtt` token. Standalone lifecycle lines keep
- * `Publish-subscribe (mqtt)` so a lone `up` / `recovered` still names the channel.
+ * A non-CLOSED REST breaker inserts `breaker OPEN` (or `HALF_OPEN`) after
+ * devices, matching the sibling plugins. The heartbeat uses the short `mqtt`
+ * token. Standalone lifecycle lines keep `Publish-subscribe (mqtt)` so a
+ * lone `up` / `recovered` still names the channel.
  */
 function formatDiagnosticLine(report) {
-    const { lifecycle, devices, transport, api } = report;
-    return [
+    const { lifecycle, devices, circuitBreaker, transport, api } = report;
+    const parts = [
         `${diagnosticLabel(report.msg)}: ${lifecycle.health}${formatReasons(lifecycle.reasons)}`,
         `devices ${devices.online}/${devices.total}`,
-        `mqtt ${formatMqttTransportState(transport.mqttState)}`,
-        `api p50 ${api.p50Ms}ms p95 ${api.p95Ms}ms (req ${api.requests}, err ${api.errors})`,
-    ].join(' | ');
+    ];
+    if (circuitBreaker.state !== 'CLOSED') {
+        parts.push(`breaker ${circuitBreaker.state}`);
+    }
+    parts.push(`mqtt ${formatMqttTransportState(transport.mqttState)}`, `api p50 ${api.p50Ms}ms p95 ${api.p95Ms}ms (req ${api.requests}, err ${api.errors})`);
+    return parts.join(' | ');
 }
 /** State-only line for a healthy/degraded flip. The heartbeat already has the body. */
 function formatHealthTransitionLine(report) {

package/dist/platform.js

@@ -130,6 +130,7 @@ class NaviLinkPlatform {
             devices,
             statusIntervalSec: this.options.statusIntervalSec,
             metrics: this.diagnostics,
+            onCircuitOpen: () => this.diagnostics.breakerTrip(),
         });
         session.onObservation((deviceId, observation, reason) => {
             this.distribute(deviceId, observation, reason);
@@ -506,6 +507,9 @@ class NaviLinkPlatform {
             },
             tokenLastRefreshAt: () => health?.lastRefreshAt ?? null,
             pollingCadenceSec: () => this.options.statusIntervalSec,
+            circuitBreaker: () => ({
+                state: this.session?.circuitBreakerState() ?? 'CLOSED',
+            }),
         };
     }
     emitDiagnostic(level, report, options = {}) {

package/dist/session.d.ts

@@ -72,6 +72,8 @@ export interface NaviLinkSessionOptions {
     now?: () => number;
     random?: () => number;
     metrics?: SessionMetrics;
+    /** Fired when REST trips OPEN, so diagnostics can count a trip. */
+    onCircuitOpen?: () => void;
 }
 /** Owns the plugin's entire relationship with the NaviLink cloud. */
 export declare class NaviLinkSession {
@@ -122,6 +124,8 @@ export declare class NaviLinkSession {
     onStale(listener: StaleListener): void;
     /** In-memory gauges for diagnostics. Never reads the network. */
     health(): SessionHealth;
+    /** REST circuit-breaker state for diagnostics. Never reads the network. */
+    circuitBreakerState(): string;
     /**
      * The current state of a device, or undefined when there is none to trust.
      *
@@ -159,6 +163,8 @@ export declare class NaviLinkSession {
      * readable and there is exactly one place that decides whether to try again.
      */
     private runForever;
+    /** Sleep the reconnect delay, abortable on shutdown. */
+    private waitToReconnect;
     /** Sign in, list devices, connect MQTT, subscribe, and ask for state. */
     private establish;
     /** Match the account's gateways against what the user configured. */

package/dist/session.js

@@ -93,6 +93,7 @@ class NaviLinkSession {
         this.rest = options.rest ?? new rest_1.NaviLinkRest({
             log: options.log,
             signal: this.abort.signal,
+            ...(options.onCircuitOpen === undefined ? {} : { onCircuitOpen: options.onCircuitOpen }),
             ...(options.metrics === undefined
                 ? {}
                 : { metrics: (sample) => options.metrics?.apiRequest(sample.durationMs, sample.ok) }),
@@ -129,6 +130,10 @@ class NaviLinkSession {
                 .map((device) => device.id),
         };
     }
+    /** REST circuit-breaker state for diagnostics. Never reads the network. */
+    circuitBreakerState() {
+        return this.rest.getCircuitBreakerStatus().state;
+    }
     /**
      * The current state of a device, or undefined when there is none to trust.
      *
@@ -258,8 +263,13 @@ class NaviLinkSession {
                     this.stopPermanently(error);
                     return;
                 }
-                attempt += 1;
                 this.notifyUnreachable(error);
+                if (error instanceof utils_1.CircuitBreakerError) {
+                    // The OPEN line already named the outage. Fail-fast until cooldown.
+                    await this.waitToReconnect(Math.max(error.retryAfterMs, 1_000));
+                    continue;
+                }
+                attempt += 1;
                 this.log.warn(`session failed: ${(0, utils_1.describeError)(error)}`);
             }
             if (!this.running) {
@@ -272,12 +282,19 @@ class NaviLinkSession {
                 maxMs: settings_1.RECONNECT_BACKOFF_MAX_MS,
                 ...(this.options.random === undefined ? {} : { random: this.options.random }),
             });
-            this.log.info(`reconnect in ${Math.round(delay / 1_000)}s`);
-            const backoff = (0, utils_1.interruptibleSleep)(delay);
-            this.backoffSleep = backoff;
-            await backoff.promise;
-            this.backoffSleep = undefined;
+            await this.waitToReconnect(delay);
+        }
+    }
+    /** Sleep the reconnect delay, abortable on shutdown. */
+    async waitToReconnect(delayMs) {
+        if (!this.running) {
+            return;
         }
+        this.log.info(`reconnect in ${Math.round(delayMs / 1_000)}s`);
+        const backoff = (0, utils_1.interruptibleSleep)(delayMs);
+        this.backoffSleep = backoff;
+        await backoff.promise;
+        this.backoffSleep = undefined;
     }
     /** Sign in, list devices, connect MQTT, subscribe, and ask for state. */
     async establish() {

package/dist/types/index.d.ts

@@ -307,6 +307,11 @@ export interface DiagnosticsSnapshot {
         commands: number;
         pushes: number;
     };
+    circuitBreaker: {
+        state: string;
+        lastTripAt: number | null;
+        trips: number;
+    };
     /** Redacted config echo, present only on boot/shutdown snapshots. */
     config?: Record<string, unknown>;
 }

package/dist/utils/errors.d.ts

@@ -75,3 +75,18 @@ export declare class ControlRejectedError extends Error {
         cause?: unknown;
     });
 }
+/**
+ * The REST circuit breaker is open, so this call was not sent.
+ *
+ * Callers should wait {@link retryAfterMs} before trying again. The session
+ * treats this as a transient outage, not a rejected password.
+ */
+export declare class CircuitBreakerError extends Error {
+    readonly code = "CIRCUIT_OPEN";
+    readonly isRetryable = true;
+    readonly resetTime: Date;
+    constructor(resetTimeMs: number, options?: {
+        cause?: Error;
+    });
+    get retryAfterMs(): number;
+}

package/dist/utils/errors.js

@@ -19,7 +19,7 @@
  * error message or it does not reach it at all.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ControlRejectedError = exports.ConnectionError = exports.ProtocolError = exports.AuthenticationError = void 0;
+exports.CircuitBreakerError = exports.ControlRejectedError = exports.ConnectionError = exports.ProtocolError = exports.AuthenticationError = void 0;
 exports.describeError = describeError;
 const redact_1 = require("./redact");
 /** Longest description produced, so a hostile endpoint cannot flood the log. */
@@ -124,3 +124,24 @@ class ControlRejectedError extends Error {
     }
 }
 exports.ControlRejectedError = ControlRejectedError;
+/**
+ * The REST circuit breaker is open, so this call was not sent.
+ *
+ * Callers should wait {@link retryAfterMs} before trying again. The session
+ * treats this as a transient outage, not a rejected password.
+ */
+class CircuitBreakerError extends Error {
+    code = 'CIRCUIT_OPEN';
+    isRetryable = true;
+    resetTime;
+    constructor(resetTimeMs, options) {
+        const resetTime = new Date(Date.now() + resetTimeMs);
+        super(`Circuit breaker is open. Service unavailable until ${resetTime.toISOString()}`, options);
+        this.name = 'CircuitBreakerError';
+        this.resetTime = resetTime;
+    }
+    get retryAfterMs() {
+        return Math.max(0, this.resetTime.getTime() - Date.now());
+    }
+}
+exports.CircuitBreakerError = CircuitBreakerError;

package/docs/FEATURES.md

@@ -28,6 +28,7 @@ A checklist of what is built. The plugin aims to cover everything about a Navien
 - ✅ **Never loses your rooms:** a broken config disables the platform without unregistering anything (`platform disabled; cached accessories kept`)
 - ✅ Control rate-limited per gateway. When the cloud answers `failCode 2`, the log is `rate limited` and the plugin pauses
 - ✅ Exponential backoff with jitter on reconnect, to a capped ceiling. A real drop says so once, then `reconnect in Ns`
+- ✅ REST circuit breaker for sustained cloud outages: fail-fast while open; a single half-open probe after cooldown. Transitions log as `Circuit breaker CLOSED -> OPEN` (warn) and `HALF_OPEN` / `CLOSED` (info). Firmware reads do not trip it.
 - ✅ Accessory identity is `{gateway MAC}:{channel}:{kind}`, never the address or the name, so nothing about your network or your naming can orphan a tile
 - ✅ Cached accessories adopted by identity, never replaced, so rooms, scenes and automations survive
 - ✅ An unusable configuration disables the platform and keeps every accessory registered. Nothing is deleted
@@ -35,7 +36,7 @@ A checklist of what is built. The plugin aims to cover everything about a Navien
 - ✅ Read-only mode: every accessory reports state, and no control command is ever sent (`readOnly; write ignored`)
 - ✅ Power-off guard, on by default, because a combi's power state governs central heating as well as hot water (`power-off disabled (allowPowerOff is off)`)
 - ✅ Accessory name prefix (`options.accessoryPrefix`): one editable stem for every HomeKit tile, without changing accessory identity
-- ✅ Opt-in diagnostics (`options.diagnosticsInterval`, default 0 / off): a periodic heartbeat (`Health: healthy | devices n/n | mqtt live | api p50/p95 (req, err)`), with optional structured JSON (`options.structuredLogs`)
+- ✅ Opt-in diagnostics (`options.diagnosticsInterval`, default 0 / off): a periodic heartbeat (`Health: healthy | devices n/n | mqtt live | api p50/p95 (req, err)`), with `breaker OPEN` / `breaker HALF_OPEN` only when the REST circuit is not closed, and optional structured JSON (`options.structuredLogs`)
 - ✅ Secrets redacted from every log line by shape, not by field name, so an unfamiliar response cannot leak a token
 - ✅ HomeKit serial numbers are opaque generated values, never the gateway MAC
 - ✅ Bounded I/O: separate connect and total timeouts, a capped response size, and a capped MQTT packet size

package/docs/PROTOCOL.md

@@ -30,6 +30,8 @@ A rejected password is **not** a 401. It is a 200 with the failure in the body.
 
 `src/api/rest.ts` maps `USER_NOT_FOUND` and `INVALID_USER_PASSWORD` to a fatal error that stops the session for good. Anything else stays retryable, because guessing that an unfamiliar error is a bad credential would stop the plugin recovering from something temporary.
 
+Retryable is not the same as hammering. Sign-in and the device list sit behind a circuit breaker: five connection or protocol failures in a minute open it (`Circuit breaker CLOSED -> OPEN`), later calls fail fast until a cooldown, then a single probe. A rejected password does not trip it. Firmware (`device/info`) is not behind it either: that read is optional, the session swallows failures, and a flaky info endpoint must not open the breaker after MQTT is already live.
+
 ### There is no usable token refresh
 
 The sign-in response carries a `refreshToken`, and `/auth/refresh` exists on the v2.1 path. Neither helps: the AWS IoT credentials are what the MQTT connection actually needs, and no refresh path has been found that reissues them.

package/docs/README-DETAILED.md

@@ -108,6 +108,8 @@ An appliance with no probe reports `0`. The plugin treats that as absent, not as
 
 **Backoff has jitter.** Reconnects use exponential backoff with full jitter to a capped ceiling, so a regional outage does not produce a synchronised stampede when it ends. A real drop logs the close, then `reconnect in Ns`, then `Publish-subscribe (mqtt) recovered` when the session is up again.
 
+**REST outages fail fast.** After five connection or protocol failures in a minute, the REST circuit breaker opens (`Circuit breaker CLOSED -> OPEN` at warn). Sign-in is not sent again until a cooldown, then a single probe: `HALF_OPEN` and `CLOSED` at info if the cloud answers. A rejected password does not trip it, and a firmware read does not either. MQTT stays on the session reconnect loop.
+
 ## Full configuration reference
 
 ### Platform options
@@ -234,6 +236,17 @@ Publish-subscribe (mqtt) recovered
 
 A continuing outage repeats at most hourly, at debug in between.
 
+A REST cloud outage, as opposed to a broker drop:
+
+```
+Circuit breaker CLOSED -> OPEN
+reconnect in 30s
+Circuit breaker OPEN -> HALF_OPEN
+Circuit breaker HALF_OPEN -> CLOSED
+```
+
+The OPEN line is the warn. While the breaker is open, sign-in is not sent. Diagnostics, if on, add `breaker OPEN` to the heartbeat until the probe succeeds.
+
 A credential refresh is not an outage. The plugin closes the socket itself a few minutes before the AWS credentials expire, signs in again, and the tiles stay current. That is debug only. `family=`, firmware and `Publish-subscribe (mqtt) up` do not repeat at info.
 
 ### Diagnostics (optional)
@@ -246,13 +259,19 @@ It pairs with `options.structuredLogs: true`, which adds a JSON line next to the
 Health: healthy | devices 1/1 | mqtt live | api p50 80ms p95 120ms (req 3, err 0)
 ```
 
+When the REST breaker is not closed, it appears on that line:
+
+```
+Health: degraded [circuitBreakerOpen] | devices 1/1 | breaker OPEN | mqtt connecting | api p50 80ms p95 120ms (req 3, err 5)
+```
+
 | `msg` | Level | When |
 | --- | --- | --- |
 | `diagnostics.start` / `diagnostics.stop` | info | Boot and shutdown, with a redacted config echo |
 | `health` | info | Every `diagnosticsInterval` seconds |
 | `health.degraded` / `health.recovered` | warn / info | When the rollup flips |
 
-Health is `degraded` when the MQTT session has been down for more than a minute, the account was rejected, or recent REST calls are failing at a high rate. Counters on a `health` line are per-interval deltas; the start/stop snapshots are session totals. Credentials, appliance names and the accessory prefix are never in the JSON (the prefix is a boolean: set or not).
+Health is `degraded` when the MQTT session has been down for more than a minute, the account was rejected, the REST circuit breaker is open or probing (`circuitBreakerOpen`), or recent REST calls are failing at a high rate. A non-CLOSED breaker also appears on the human line as `breaker OPEN` or `breaker HALF_OPEN`. Counters on a `health` line are per-interval deltas; the start/stop snapshots are session totals. Credentials, appliance names and the accessory prefix are never in the JSON (the prefix is a boolean: set or not).
 
 ## Apple Shortcuts
 
@@ -288,7 +307,7 @@ The plugin has stopped trying on purpose, so the account is not locked out. Sign
 The account does not exist. Check for a typo, and note that the plugin trims surrounding whitespace but cannot fix a wrong address.
 
 **3. Everything shows No Response and stays that way.**
-Look for `platform disabled` in the log. That means the configuration could not be read; the error above it says which part.
+Look for `platform disabled` in the log. That means the configuration could not be read; the error above it says which part. `Circuit breaker CLOSED -> OPEN` is a cloud outage, not a config error; see 13.
 
 **4. Accessories exist but never get a reading.**
 Check the gateway shows as connected in the NaviLink app. The plugin cannot see anything the app cannot.
@@ -317,7 +336,10 @@ Expected. The appliance clamps to the range your installer set, and a Fahrenheit
 **12. A tile lost its room after an update.**
 Should not happen; identity is stable by design. If `id` was edited by hand, that will do it. Otherwise please open an issue, because it is a bug.
 
-**13. It all stops when the internet does.**
+**13. `Circuit breaker CLOSED -> OPEN`**
+NaviLink REST is being treated as down. Sign-in is paused until the cooldown; tiles stay No Response. When the cloud answers again the log is `HALF_OPEN` then `CLOSED`. A firmware line that never arrives is not this: firmware is optional and does not trip the breaker.
+
+**14. It all stops when the internet does.**
 There is no local interface on a NaviLink gateway. Nothing can be done about this from here.
 
 ## Security

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-navilink",
   "displayName": "Homebridge NaviLink",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Homebridge plugin for Navien combi boilers and water heaters through the North American NaviLink cloud: hot water and space-heating thermostats, power, recirculation, fault and temperature accessories. Verified on an NCB-240E (firmware 4352)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",