mysa-js-sdk 3.0.0 → 3.1.0

package/dist/index.d.ts

@@ -39,6 +39,20 @@ declare class UnknownDeviceError extends Error {
      */
     constructor(deviceId: string);
 }
+/** Error thrown when a requested fan speed is not supported by the target device. */
+declare class UnsupportedFanSpeedError extends Error {
+    readonly deviceId: string;
+    readonly fanSpeed: string;
+    readonly supportedFanSpeeds: string[];
+    /**
+     * Creates a new UnsupportedFanSpeedError instance.
+     *
+     * @param deviceId - The id of the device the command was aimed at.
+     * @param fanSpeed - The requested fan speed that the device does not support.
+     * @param supportedFanSpeeds - The fan speeds the device does support.
+     */
+    constructor(deviceId: string, fanSpeed: string, supportedFanSpeeds: string[]);
+}
 /** Error thrown when an MQTT publish ultimately fails after retry attempts. */
 declare class MqttPublishError extends Error {
     attempts: number;
@@ -120,6 +134,8 @@ interface Status {
     current?: number;
     /** Optional heating element duty cycle, as a fraction between 0.0 and 1.0 */
     dutyCycle?: number;
+    /** Optional floor-probe temperature reading, reported only by in-floor heating thermostats (INF-V1-0) */
+    floorTemperature?: number;
 }
 
 /** Interface for logging operations at different severity levels */
@@ -215,6 +231,12 @@ interface SupportedCaps {
     version: string;
     /** Array of supported remote control key codes */
     keys: number[];
+    /**
+     * Optional device-specific fan-speed `fn` values, ordered by canonical fan speed (`[auto, low, medium, high, max]`).
+     * E.g. `[1, 2, 4, 6]` for CodeNum=1117 devices means auto=1, low=2, medium=4, high=6. When absent, a legacy universal
+     * mapping is assumed.
+     */
+    fanSpeeds?: number[];
 }
 /**
  * Device operating mode information.
@@ -568,12 +590,29 @@ interface DeviceV2Status extends MsgPayload<OutMessageType.DEVICE_V2_STATUS> {
     body: {
         /** Ambient temperature reading from the device sensor */
         ambTemp: number;
-        /** Current duty cycle of the heating element, as a fraction between 0.0 and 1.0 */
-        dtyCycle: number;
+        /**
+         * Current duty cycle of the heating element, as a fraction between 0.0 and 1.0. Reported by baseboard V2 devices;
+         * absent on in-floor heating thermostats (INF-V1-0), which report {@link heatStat} instead.
+         */
+        dtyCycle?: number;
         /** Relative humidity percentage reading from the device sensor */
         hum: number;
         /** Current temperature setpoint setting */
         stpt: number;
+        /**
+         * Binary heating-relay state (0 = off, 1 = energized) reported by in-floor heating thermostats (INF-V1-0) in place
+         * of {@link dtyCycle}. Absent on baseboard V2 devices.
+         */
+        heatStat?: number;
+        /** Floor-probe temperature reading (°C) from in-floor heating thermostats. Absent on baseboard V2 devices. */
+        flrSnsrTemp?: number;
+        /**
+         * Which sensor the in-floor thermostat regulates against (3 = floor probe, 5 = ambient air). Absent on baseboard V2
+         * devices.
+         */
+        trackedSnsr?: number;
+        /** Line voltage (V) reported by in-floor heating thermostats. Absent on baseboard V2 devices. */
+        lineVtg?: number;
     };
 }
 
@@ -805,8 +844,21 @@ declare class MysaApiClient {
     private _mqttInterrupts;
     /** Whether a forced MQTT reset is currently in progress (guards against re-entrancy). */
     private _mqttResetInProgress;
+    /** Monotonic id of the current MQTT connection; used to ignore events from discarded connections. */
+    private _mqttGeneration;
+    /** Consecutive forced resets without an intervening stable period; drives reset backoff. */
+    private _mqttConsecutiveResets;
+    /** Timestamp (ms) of the most recent successful MQTT (re)connect, for interrupt dwell-time diagnostics. */
+    private _mqttLastConnectionSuccessAt?;
+    /** Timer that clears the consecutive-reset counter once a connection stays healthy. */
+    private _mqttStabilityTimer?;
     /** The device IDs that are currently being updated in real-time, mapped to their respective timeouts. */
     private _realtimeDeviceIds;
+    /**
+     * Raw topic filters registered via {@link startRawTopicCapture}, mapped to their message handlers. Re-subscribed on
+     * every reconnect so a debug capture survives connection resets.
+     */
+    private _rawTopicCaptures;
     /** The cached devices object, if any. */
     private _cachedDevices?;
     /**
@@ -945,6 +997,7 @@ declare class MysaApiClient {
      *   unchanged).
      * @throws {@link UnauthenticatedError} When the client cannot authenticate with its credentials.
      * @throws {@link UnknownDeviceError} When the device id does not match any device on the account.
+     * @throws {@link UnsupportedFanSpeedError} When the requested fan speed is not supported by the device.
      * @throws {@link Error} When MQTT connection or command sending fails.
      */
     setDeviceState(deviceId: string, setPoint?: number, mode?: MysaDeviceMode, fanSpeed?: MysaFanSpeedMode): Promise<void>;
@@ -980,6 +1033,28 @@ declare class MysaApiClient {
      * @throws {@link Error} When MQTT unsubscription fails.
      */
     stopRealtimeUpdates(deviceId: string): Promise<void>;
+    /**
+     * Subscribes to raw MQTT topic filters and relays every message verbatim.
+     *
+     * Unlike {@link startRealtimeUpdates}, this performs no parsing, emits no typed events and sends no "start publishing"
+     * request to the device — it simply forwards the full message topic and the decoded UTF-8 payload of everything that
+     * arrives on the given filters. It exists to reverse-engineer device families the SDK does not model yet, most
+     * notably the AWS IoT Device Shadow protocol used by the central-HVAC ST-V1 thermostats, where both the topic (which
+     * shadow, and `accepted`/`rejected`/`delta`/`documents`) and the raw JSON body carry the information a new
+     * implementation needs.
+     *
+     * The capture is passive: the device only publishes to its shadow topics when something drives a change (the Mysa
+     * mobile app, a schedule, or the device itself), so exercise the thermostat while a capture is running.
+     *
+     * Registered filters are re-subscribed automatically after a reconnect.
+     *
+     * @param topicFilters - MQTT topic filters to subscribe to. Wildcards (`+`, `#`) are allowed, subject to the AWS IoT
+     *   policy attached to the account's Cognito identity — a filter the policy forbids resolves with a non-zero
+     *   `error_code`, which is logged rather than thrown so the remaining filters still subscribe.
+     * @param handler - Invoked with the full message topic and the decoded UTF-8 payload for every message received.
+     * @throws {@link Error} When the MQTT connection cannot be established.
+     */
+    startRawTopicCapture(topicFilters: string[], handler: (topic: string, payload: string) => void): Promise<void>;
     /**
      * Ensures a valid, non-expired session is available.
      *
@@ -1053,6 +1128,36 @@ declare class MysaApiClient {
      * @throws {@link Error} When connection establishment fails.
      */
     private _createMqttConnection;
+    /**
+     * Re-subscribes every device currently receiving real-time updates on the given connection.
+     *
+     * Safe to call on every (re)connect: aws-crt replaces the per-topic callback on a duplicate subscribe, so this never
+     * registers a message handler more than once.
+     *
+     * @param connection - The connection to (re-)establish subscriptions on.
+     */
+    private _resubscribeAll;
+    /**
+     * Arms (or re-arms) the stability timer. When a connection stays interrupt-free for {@link MqttStabilityWindow}, the
+     * consecutive-reset backoff counter is cleared so a future isolated storm still gets a fast first reset.
+     *
+     * @param generation - The connection generation that armed the timer; the callback is a no-op if the connection has
+     *   since been replaced.
+     */
+    private _armMqttStabilityTimer;
+    /** Clears the stability timer, if armed. */
+    private _clearMqttStabilityTimer;
+    /**
+     * Forcefully tears down the current MQTT connection and rebuilds it with a fresh client id and fresh credentials,
+     * escaping interrupt storms that a plain native reconnect cannot.
+     *
+     * Repeatable and self-contained: only one reset runs at a time, consecutive resets without an intervening stable
+     * period back off exponentially (up to {@link MqttResetMaxDelay}), and it never rejects — so it is safe to invoke
+     * fire-and-forget from an event handler.
+     *
+     * @param reason - Human-readable reason for the reset, used in logs.
+     */
+    private _resetMqttConnection;
     /**
      * Processes incoming MQTT messages and emits appropriate events.
      *
@@ -1175,4 +1280,4 @@ type MsgTypeInPayload = CheckDeviceSettings | StartPublishingDeviceStatus;
  */
 type InPayload = MsgTypeInPayload | MsgInPayload;
 
-export { type BrandInfo, type ChangeDeviceState, type CheckDeviceSettings, type DeviceAcStatus, type DeviceBase, type DeviceLog, type DevicePostBoot, type DeviceSetpointChange, type DeviceState, type DeviceStateChange, type DeviceStates, type DeviceStatesObj, type DeviceV1Status, type DeviceV2Status, type Devices, type DevicesObj, type FirmwareDevice, type Firmwares, type HomeBase, type Homes, InMessageType, type InPayload, type Logger, type ModeObj, MqttPublishError, type MqttPublishOptions, type MsgBasePayload, type MsgInPayload, type MsgOutPayload, type MsgPayload, type MsgTypeBasePayload, type MsgTypeInPayload, type MsgTypeOutPayload, type MsgTypePayload, MysaApiClient, type MysaApiClientEventTypes, type MysaApiClientOptions, MysaApiError, type MysaCredentials, type MysaDeviceMode, type MysaFanSpeedMode, OutMessageType, type OutPayload, type SetPointChange, type StartPublishingDeviceStatus, type StateChange, type Status, type SupportedCaps, type TimestampedValue, UnauthenticatedError, UnknownDeviceError, VoidLogger };
+export { type BrandInfo, type ChangeDeviceState, type CheckDeviceSettings, type DeviceAcStatus, type DeviceBase, type DeviceLog, type DevicePostBoot, type DeviceSetpointChange, type DeviceState, type DeviceStateChange, type DeviceStates, type DeviceStatesObj, type DeviceV1Status, type DeviceV2Status, type Devices, type DevicesObj, type FirmwareDevice, type Firmwares, type HomeBase, type Homes, InMessageType, type InPayload, type Logger, type ModeObj, MqttPublishError, type MqttPublishOptions, type MsgBasePayload, type MsgInPayload, type MsgOutPayload, type MsgPayload, type MsgTypeBasePayload, type MsgTypeInPayload, type MsgTypeOutPayload, type MsgTypePayload, MysaApiClient, type MysaApiClientEventTypes, type MysaApiClientOptions, MysaApiError, type MysaCredentials, type MysaDeviceMode, type MysaFanSpeedMode, OutMessageType, type OutPayload, type SetPointChange, type StartPublishingDeviceStatus, type StateChange, type Status, type SupportedCaps, type TimestampedValue, UnauthenticatedError, UnknownDeviceError, UnsupportedFanSpeedError, VoidLogger };

package/dist/index.js

@@ -76,6 +76,27 @@ var UnknownDeviceError = class extends Error {
   }
   deviceId;
 };
+var UnsupportedFanSpeedError = class extends Error {
+  /**
+   * Creates a new UnsupportedFanSpeedError instance.
+   *
+   * @param deviceId - The id of the device the command was aimed at.
+   * @param fanSpeed - The requested fan speed that the device does not support.
+   * @param supportedFanSpeeds - The fan speeds the device does support.
+   */
+  constructor(deviceId, fanSpeed, supportedFanSpeeds) {
+    super(
+      `Device '${deviceId}' does not support the '${fanSpeed}' fan speed. Supported fan speeds: ${supportedFanSpeeds.join(", ") || "(none)"}.`
+    );
+    this.deviceId = deviceId;
+    this.fanSpeed = fanSpeed;
+    this.supportedFanSpeeds = supportedFanSpeeds;
+    this.name = "UnsupportedFanSpeedError";
+  }
+  deviceId;
+  fanSpeed;
+  supportedFanSpeeds;
+};
 var MqttPublishError = class extends Error {
   /**
    * Creates a new MqttPublishError instance.
@@ -232,6 +253,43 @@ var MqttEndpoint = "a3q27gia9qg3zy-ats.iot.us-east-1.amazonaws.com";
 var MysaApiBaseUrl = "https://app-prod.mysa.cloud";
 var RealtimeKeepAliveInterval = dayjs.duration(5, "minutes");
 var PublishAckTimeout = dayjs.duration(30, "seconds");
+var MqttInterruptWindow = dayjs.duration(30, "seconds");
+var MqttInterruptThreshold = 3;
+var MqttResetBaseDelay = dayjs.duration(1, "second");
+var MqttResetMaxDelay = dayjs.duration(30, "seconds");
+var MqttStabilityWindow = dayjs.duration(60, "seconds");
+var CanonicalFanSpeedOrder = ["auto", "low", "medium", "high", "max"];
+var LegacyFanSpeedSendMap = { auto: 1, low: 3, medium: 5, high: 7, max: 8 };
+var FanSpeedReceiveMap = {
+  1: "auto",
+  2: "low",
+  // CodeNum=1117 canonical low
+  3: "low",
+  // legacy
+  4: "medium",
+  // CodeNum=1117 canonical medium
+  5: "medium",
+  // legacy
+  6: "high",
+  // CodeNum=1117 canonical high
+  7: "high",
+  // legacy
+  8: "max"
+};
+function buildFanSpeedSendMap(device) {
+  var _a;
+  const fanSpeeds = (_a = device.SupportedCaps) == null ? void 0 : _a.fanSpeeds;
+  if (!fanSpeeds || fanSpeeds.length === 0) {
+    return LegacyFanSpeedSendMap;
+  }
+  const map = {};
+  CanonicalFanSpeedOrder.forEach((name, index) => {
+    if (index < fanSpeeds.length) {
+      map[name] = fanSpeeds[index];
+    }
+  });
+  return map;
+}
 var MysaApiClient = class {
   /** The credentials of the Mysa account this client authenticates as. */
   _credentials;
@@ -255,8 +313,21 @@ var MysaApiClient = class {
   _mqttInterrupts = [];
   /** Whether a forced MQTT reset is currently in progress (guards against re-entrancy). */
   _mqttResetInProgress = false;
+  /** Monotonic id of the current MQTT connection; used to ignore events from discarded connections. */
+  _mqttGeneration = 0;
+  /** Consecutive forced resets without an intervening stable period; drives reset backoff. */
+  _mqttConsecutiveResets = 0;
+  /** Timestamp (ms) of the most recent successful MQTT (re)connect, for interrupt dwell-time diagnostics. */
+  _mqttLastConnectionSuccessAt;
+  /** Timer that clears the consecutive-reset counter once a connection stays healthy. */
+  _mqttStabilityTimer;
   /** The device IDs that are currently being updated in real-time, mapped to their respective timeouts. */
   _realtimeDeviceIds = /* @__PURE__ */ new Map();
+  /**
+   * Raw topic filters registered via {@link startRawTopicCapture}, mapped to their message handlers. Re-subscribed on
+   * every reconnect so a debug capture survives connection resets.
+   */
+  _rawTopicCaptures = /* @__PURE__ */ new Map();
   /** The cached devices object, if any. */
   _cachedDevices;
   /**
@@ -310,6 +381,7 @@ var MysaApiClient = class {
     this._cognitoUserSession = void 0;
     this._mqttClientId = void 0;
     this._mqttInterrupts = [];
+    this._mqttConsecutiveResets = 0;
     const { username, password } = this._credentials;
     return new Promise((resolve, reject) => {
       const user = new CognitoUser({
@@ -501,6 +573,7 @@ var MysaApiClient = class {
    *   unchanged).
    * @throws {@link UnauthenticatedError} When the client cannot authenticate with its credentials.
    * @throws {@link UnknownDeviceError} When the device id does not match any device on the account.
+   * @throws {@link UnsupportedFanSpeedError} When the requested fan speed is not supported by the device.
    * @throws {@link Error} When MQTT connection or command sending fails.
    */
   async setDeviceState(deviceId, setPoint, mode, fanSpeed) {
@@ -518,7 +591,10 @@ var MysaApiClient = class {
     const now = dayjs();
     this._logger.debug(`Sending request to set device state for '${deviceId}'...`);
     const modeMap = { off: 1, auto: 2, heat: 3, cool: 4, fan_only: 5, dry: 6 };
-    const fanSpeedMap = { auto: 1, low: 3, medium: 5, high: 7, max: 8 };
+    const fanSpeedMap = buildFanSpeedSendMap(device);
+    if (fanSpeed !== void 0 && fanSpeedMap[fanSpeed] === void 0) {
+      throw new UnsupportedFanSpeedError(deviceId, fanSpeed, Object.keys(fanSpeedMap));
+    }
     const payload = serializeMqttPayload({
       msg: 44 /* CHANGE_DEVICE_STATE */,
       id: now.valueOf(),
@@ -535,7 +611,7 @@ var MysaApiClient = class {
       resp: 2,
       body: {
         ver: 1,
-        type: device.Model.startsWith("BB-V1") || device.Model.startsWith("v1") ? 1 : device.Model.startsWith("AC-V1") ? 2 : device.Model.startsWith("BB-V2") ? device.Model.endsWith("-L") ? 5 : 4 : 0,
+        type: device.Model.startsWith("BB-V1") || device.Model.startsWith("v1") ? 1 : device.Model.startsWith("AC-V1") ? 2 : device.Model.startsWith("INF-V1") ? 3 : device.Model.startsWith("BB-V2") ? device.Model.endsWith("-L") ? 5 : 4 : 0,
         cmd: [
           {
             tm: -1,
@@ -639,6 +715,46 @@ var MysaApiClient = class {
     clearInterval(timer);
     this._realtimeDeviceIds.delete(deviceId);
   }
+  /**
+   * Subscribes to raw MQTT topic filters and relays every message verbatim.
+   *
+   * Unlike {@link startRealtimeUpdates}, this performs no parsing, emits no typed events and sends no "start publishing"
+   * request to the device — it simply forwards the full message topic and the decoded UTF-8 payload of everything that
+   * arrives on the given filters. It exists to reverse-engineer device families the SDK does not model yet, most
+   * notably the AWS IoT Device Shadow protocol used by the central-HVAC ST-V1 thermostats, where both the topic (which
+   * shadow, and `accepted`/`rejected`/`delta`/`documents`) and the raw JSON body carry the information a new
+   * implementation needs.
+   *
+   * The capture is passive: the device only publishes to its shadow topics when something drives a change (the Mysa
+   * mobile app, a schedule, or the device itself), so exercise the thermostat while a capture is running.
+   *
+   * Registered filters are re-subscribed automatically after a reconnect.
+   *
+   * @param topicFilters - MQTT topic filters to subscribe to. Wildcards (`+`, `#`) are allowed, subject to the AWS IoT
+   *   policy attached to the account's Cognito identity — a filter the policy forbids resolves with a non-zero
+   *   `error_code`, which is logged rather than thrown so the remaining filters still subscribe.
+   * @param handler - Invoked with the full message topic and the decoded UTF-8 payload for every message received.
+   * @throws {@link Error} When the MQTT connection cannot be established.
+   */
+  async startRawTopicCapture(topicFilters, handler) {
+    this._logger.info(`Starting raw topic capture for ${topicFilters.length} filter(s)`);
+    const connection = await this._getMqttConnection();
+    const decoder = new TextDecoder("utf-8");
+    for (const filter of topicFilters) {
+      this._rawTopicCaptures.set(filter, handler);
+      this._logger.debug(`Subscribing to raw topic filter '${filter}'...`);
+      try {
+        const result = await connection.subscribe(filter, mqtt.QoS.AtLeastOnce, (topic, payload) => {
+          handler(topic, decoder.decode(payload));
+        });
+        this._logger.debug(
+          `Raw subscribe to '${filter}' granted (topic='${result.topic}', qos=${result.qos}, error_code=${result.error_code ?? 0})`
+        );
+      } catch (error) {
+        this._logger.warn(`Failed to subscribe to raw topic filter '${filter}'`, error);
+      }
+    }
+  }
   /**
    * Ensures a valid, non-expired session is available.
    *
@@ -840,7 +956,7 @@ var MysaApiClient = class {
       const usernameHash = hash("sha1", username);
       this._mqttClientId = `mysa-js-sdk-${usernameHash}-${process.pid}-${getRandomClientId()}`;
     }
-    const builder = iot.AwsIotMqttConnectionConfigBuilder.new_with_websockets().with_credentials(AwsRegion, credentials.accessKeyId, credentials.secretAccessKey, credentials.sessionToken).with_endpoint(MqttEndpoint).with_client_id(this._mqttClientId).with_clean_session(false).with_keep_alive_seconds(30).with_ping_timeout_ms(3e3).with_protocol_operation_timeout_ms(6e4).with_reconnect_min_sec(1).with_reconnect_max_sec(30);
+    const builder = iot.AwsIotMqttConnectionConfigBuilder.new_with_websockets().with_credentials(AwsRegion, credentials.accessKeyId, credentials.secretAccessKey, credentials.sessionToken).with_endpoint(MqttEndpoint).with_client_id(this._mqttClientId).with_clean_session(true).with_keep_alive_seconds(30).with_ping_timeout_ms(3e3).with_protocol_operation_timeout_ms(6e4).with_reconnect_min_sec(3).with_reconnect_max_sec(30);
     const config = builder.build();
     config.websocket_handshake_transform = async (request, done) => {
       try {
@@ -883,89 +999,174 @@ var MysaApiClient = class {
     };
     const client = new mqtt.MqttClient();
     const connection = client.new_connection(config);
-    connection.on("connect", () => {
-      this._logger.debug(`MQTT connect (clientId=${this._mqttClientId})`);
+    const generation = ++this._mqttGeneration;
+    connection.on("connect", (sessionPresent) => {
+      if (generation !== this._mqttGeneration) return;
+      this._logger.debug(`MQTT connect (clientId=${this._mqttClientId}, sessionPresent=${sessionPresent})`);
     });
-    connection.on("connection_success", () => {
-      this._logger.debug(`MQTT connection_success (clientId=${this._mqttClientId})`);
+    connection.on("connection_success", (result) => {
+      if (generation !== this._mqttGeneration) return;
+      this._mqttLastConnectionSuccessAt = Date.now();
+      this._logger.debug(
+        `MQTT connection_success (clientId=${this._mqttClientId}, sessionPresent=${result == null ? void 0 : result.session_present}, reasonCode=${result == null ? void 0 : result.reason_code})`
+      );
+      this._armMqttStabilityTimer(generation);
     });
     connection.on("connection_failure", (e) => {
+      if (generation !== this._mqttGeneration) return;
       this._logger.error(`MQTT connection_failure (clientId=${this._mqttClientId})`, e);
     });
-    connection.on("interrupt", async (e) => {
+    connection.on("interrupt", (e) => {
       var _a2;
-      this._logger.warn(`MQTT interrupt (clientId=${this._mqttClientId})`, e);
+      if (generation !== this._mqttGeneration) return;
+      const dwellMs = this._mqttLastConnectionSuccessAt !== void 0 ? Date.now() - this._mqttLastConnectionSuccessAt : void 0;
+      this._logger.warn(
+        `MQTT interrupt (clientId=${this._mqttClientId}, dwellMs=${dwellMs ?? "n/a"}, generation=${generation})`,
+        e
+      );
+      this._clearMqttStabilityTimer();
       const now = Date.now();
-      this._mqttInterrupts = this._mqttInterrupts.filter((t) => now - t < 6e4);
+      this._mqttInterrupts = this._mqttInterrupts.filter((t) => now - t < MqttInterruptWindow.asMilliseconds());
       this._mqttInterrupts.push(now);
       const areCredentialsExpired = !(((_a2 = this._mqttCredentialsExpiration) == null ? void 0 : _a2.isAfter(dayjs())) ?? false);
-      if ((this._mqttInterrupts.length > 5 || areCredentialsExpired) && !this._mqttResetInProgress) {
-        this._mqttResetInProgress = true;
-        if (this._mqttInterrupts.length > 5) {
-          this._logger.warn(
-            `High interrupt rate (${this._mqttInterrupts.length}/60s). Possible clientId collision. Regenerating clientId and resetting connection...`
-          );
-        } else {
-          this._logger.warn(`Credentials expired. Regenerating clientId and resetting connection...`);
-        }
-        this._mqttClientId = void 0;
-        this._mqttCredentialsExpiration = void 0;
-        this._mqttInterrupts = [];
-        this._mqttConnectionPromise = void 0;
-        try {
-          connection.removeAllListeners();
-          await connection.disconnect();
-          try {
-            this._logger.debug("Old MQTT connection disconnected; establishing new connection...");
-            const newConnection = await this._getMqttConnection();
-            for (const deviceId of Array.from(this._realtimeDeviceIds.keys())) {
-              const topic = `/v1/dev/${deviceId}/out`;
-              this._logger.debug(`Re-subscribing to ${topic}`);
-              await newConnection.subscribe(topic, mqtt.QoS.AtLeastOnce, (_topic, payload) => {
-                this._processMqttMessage(payload);
-              });
-            }
-            this._logger.info("MQTT connection rebuilt successfully after interrupt storm or credentials expiration");
-          } catch (err) {
-            this._logger.error("Failed to re-subscribe after interrupt storm or credentials expiration", err);
-          }
-        } catch (error) {
-          this._logger.error("Error during MQTT reset", error);
-        } finally {
-          this._mqttResetInProgress = false;
-        }
+      const isStorm = this._mqttInterrupts.length >= MqttInterruptThreshold;
+      if (isStorm || areCredentialsExpired) {
+        const reason = isStorm ? `High interrupt rate (${this._mqttInterrupts.length} in ${MqttInterruptWindow.asSeconds()}s)` : "Credentials expired";
+        void this._resetMqttConnection(reason);
       }
     });
     connection.on("resume", async (returnCode, sessionPresent) => {
+      if (generation !== this._mqttGeneration) return;
       this._logger.info(
         `MQTT resume returnCode=${returnCode} sessionPresent=${sessionPresent} clientId=${this._mqttClientId}`
       );
       if (!sessionPresent) {
-        this._logger.info("No session present, re-subscribing each device");
         try {
-          for (const deviceId of Array.from(this._realtimeDeviceIds.keys())) {
-            const topic = `/v1/dev/${deviceId}/out`;
-            this._logger.debug(`Re-subscribing to ${topic}`);
-            await connection.subscribe(topic, mqtt.QoS.AtLeastOnce, (_topic, payload) => {
-              this._processMqttMessage(payload);
-            });
-          }
+          await this._resubscribeAll(connection);
         } catch (err) {
           this._logger.error("Failed to re-subscribe after resume", err);
         }
       }
     });
     connection.on("error", (e) => {
+      if (generation !== this._mqttGeneration) return;
       this._logger.error(`MQTT error (clientId=${this._mqttClientId})`, e);
     });
     connection.on("closed", () => {
+      if (generation !== this._mqttGeneration) return;
       this._logger.info("MQTT connection closed");
+      this._clearMqttStabilityTimer();
       this._mqttConnectionPromise = void 0;
       this._mqttCredentialsExpiration = void 0;
     });
     await connection.connect();
     return connection;
   }
+  /**
+   * Re-subscribes every device currently receiving real-time updates on the given connection.
+   *
+   * Safe to call on every (re)connect: aws-crt replaces the per-topic callback on a duplicate subscribe, so this never
+   * registers a message handler more than once.
+   *
+   * @param connection - The connection to (re-)establish subscriptions on.
+   */
+  async _resubscribeAll(connection) {
+    for (const deviceId of Array.from(this._realtimeDeviceIds.keys())) {
+      const topic = `/v1/dev/${deviceId}/out`;
+      this._logger.debug(`Re-subscribing to ${topic}`);
+      await connection.subscribe(topic, mqtt.QoS.AtLeastOnce, (_topic, payload) => {
+        this._processMqttMessage(payload);
+      });
+    }
+    const decoder = new TextDecoder("utf-8");
+    for (const [filter, handler] of Array.from(this._rawTopicCaptures.entries())) {
+      this._logger.debug(`Re-subscribing to raw topic filter '${filter}'`);
+      try {
+        await connection.subscribe(filter, mqtt.QoS.AtLeastOnce, (topic, payload) => {
+          handler(topic, decoder.decode(payload));
+        });
+      } catch (error) {
+        this._logger.warn(`Failed to re-subscribe to raw topic filter '${filter}'`, error);
+      }
+    }
+  }
+  /**
+   * Arms (or re-arms) the stability timer. When a connection stays interrupt-free for {@link MqttStabilityWindow}, the
+   * consecutive-reset backoff counter is cleared so a future isolated storm still gets a fast first reset.
+   *
+   * @param generation - The connection generation that armed the timer; the callback is a no-op if the connection has
+   *   since been replaced.
+   */
+  _armMqttStabilityTimer(generation) {
+    var _a, _b;
+    this._clearMqttStabilityTimer();
+    this._mqttStabilityTimer = setTimeout(() => {
+      if (generation !== this._mqttGeneration) return;
+      if (this._mqttConsecutiveResets > 0) {
+        this._logger.debug("MQTT connection stable; clearing consecutive-reset counter");
+        this._mqttConsecutiveResets = 0;
+      }
+    }, MqttStabilityWindow.asMilliseconds());
+    (_b = (_a = this._mqttStabilityTimer).unref) == null ? void 0 : _b.call(_a);
+  }
+  /** Clears the stability timer, if armed. */
+  _clearMqttStabilityTimer() {
+    if (this._mqttStabilityTimer) {
+      clearTimeout(this._mqttStabilityTimer);
+      this._mqttStabilityTimer = void 0;
+    }
+  }
+  /**
+   * Forcefully tears down the current MQTT connection and rebuilds it with a fresh client id and fresh credentials,
+   * escaping interrupt storms that a plain native reconnect cannot.
+   *
+   * Repeatable and self-contained: only one reset runs at a time, consecutive resets without an intervening stable
+   * period back off exponentially (up to {@link MqttResetMaxDelay}), and it never rejects — so it is safe to invoke
+   * fire-and-forget from an event handler.
+   *
+   * @param reason - Human-readable reason for the reset, used in logs.
+   */
+  async _resetMqttConnection(reason) {
+    if (this._mqttResetInProgress) {
+      return;
+    }
+    this._mqttResetInProgress = true;
+    const connectionToClose = this._mqttConnectionPromise;
+    try {
+      this._mqttConsecutiveResets++;
+      const delayMs = Math.min(
+        MqttResetBaseDelay.asMilliseconds() * Math.pow(2, this._mqttConsecutiveResets - 1),
+        MqttResetMaxDelay.asMilliseconds()
+      );
+      this._logger.warn(
+        `${reason}. Forcing MQTT reset #${this._mqttConsecutiveResets} (new clientId, fresh credentials) after ${Math.round(delayMs)}ms...`
+      );
+      this._mqttClientId = void 0;
+      this._mqttCredentialsExpiration = void 0;
+      this._mqttInterrupts = [];
+      this._clearMqttStabilityTimer();
+      this._mqttConnectionPromise = void 0;
+      if (connectionToClose) {
+        try {
+          const connection = await connectionToClose;
+          connection.removeAllListeners();
+          await connection.disconnect();
+        } catch (err) {
+          this._logger.debug("Error tearing down old MQTT connection during reset (ignored)", err);
+        }
+      }
+      if (delayMs > 0) {
+        await new Promise((r) => setTimeout(r, delayMs));
+      }
+      const newConnection = await this._getMqttConnection();
+      await this._resubscribeAll(newConnection);
+      this._logger.info(`MQTT connection rebuilt successfully after reset #${this._mqttConsecutiveResets} (${reason})`);
+    } catch (err) {
+      this._logger.error("Failed to rebuild MQTT connection after reset", err);
+    } finally {
+      this._mqttResetInProgress = false;
+    }
+  }
   /**
    * Processes incoming MQTT messages and emits appropriate events.
    *
@@ -1001,7 +1202,6 @@ var MysaApiClient = class {
       } else if (isMsgOutPayload(parsedPayload)) {
         switch (parsedPayload.msg) {
           case 30 /* DEVICE_AC_STATUS */:
-          case 40 /* DEVICE_V2_STATUS */:
             this.emitter.emit("statusChanged", {
               deviceId: parsedPayload.src.ref,
               temperature: parsedPayload.body.ambTemp,
@@ -1010,6 +1210,16 @@ var MysaApiClient = class {
               dutyCycle: parsedPayload.body.dtyCycle
             });
             break;
+          case 40 /* DEVICE_V2_STATUS */:
+            this.emitter.emit("statusChanged", {
+              deviceId: parsedPayload.src.ref,
+              temperature: parsedPayload.body.ambTemp,
+              humidity: parsedPayload.body.hum,
+              setPoint: parsedPayload.body.stpt,
+              dutyCycle: parsedPayload.body.dtyCycle ?? parsedPayload.body.heatStat,
+              floorTemperature: parsedPayload.body.flrSnsrTemp
+            });
+            break;
           case 44 /* DEVICE_STATE_CHANGE */: {
             const modeMap = {
               1: "off",
@@ -1019,18 +1229,11 @@ var MysaApiClient = class {
               5: "fan_only",
               6: "dry"
             };
-            const fanSpeedMap = {
-              1: "auto",
-              3: "low",
-              5: "medium",
-              7: "high",
-              8: "max"
-            };
             this.emitter.emit("stateChanged", {
               deviceId: parsedPayload.src.ref,
               mode: parsedPayload.body.state.md ? modeMap[parsedPayload.body.state.md] : void 0,
               setPoint: parsedPayload.body.state.sp,
-              fanSpeed: parsedPayload.body.state.fn !== void 0 ? fanSpeedMap[parsedPayload.body.state.fn] : void 0
+              fanSpeed: parsedPayload.body.state.fn !== void 0 ? FanSpeedReceiveMap[parsedPayload.body.state.fn] : void 0
             });
             break;
           }
@@ -1049,6 +1252,7 @@ export {
   OutMessageType,
   UnauthenticatedError,
   UnknownDeviceError,
+  UnsupportedFanSpeedError,
   VoidLogger
 };
 //# sourceMappingURL=index.js.map