mysa-js-sdk 3.0.0 → 3.1.1

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # mysa-js-sdk
 
+## 3.1.1
+
+### Patch Changes
+
+- [#121](https://github.com/bourquep/mysa2mqtt/pull/121) [`8fab111`](https://github.com/bourquep/mysa2mqtt/commit/8fab111568255ea6130123be8dd3fcf5cbb08b5b) Thanks [@souvik101990](https://github.com/souvik101990)! - Derive AC fan modes from `SupportedCaps` and preserve state on fan-mode changes (CodeNum=1117).
+
+  AC-V1-X thermostats (Mysa for Mini-Split) report their supported fan speeds through `SupportedCaps.fanSpeeds` and use canonical `fn` values (`[1, 2, 4, 6]`) that differ from the legacy universal mapping. `mysa2mqtt` now:
+
+  - recognizes the canonical `fn=2/4/6` values on the receive path so the current fan speed is reported instead of dropped;
+  - derives the advertised `fan_modes` from the device's actual `SupportedCaps` instead of a hardcoded list (devices without fan-speed support advertise only `auto`), deduplicating modes that map from both legacy and canonical raw values;
+  - rejects fan-mode commands the device doesn't support instead of silently reapplying the current state; and
+  - preserves the current target temperature and climate mode when changing fan mode, and keeps the current fan mode when a state update omits the fan speed.
+
+  `mysa-js-sdk` adds an optional per-mode `fanSpeeds` field to `SupportedCaps.modes` (the top-level `fanSpeeds` field was already present).
+
+- [#217](https://github.com/bourquep/mysa2mqtt/pull/217) [`0da4a1d`](https://github.com/bourquep/mysa2mqtt/commit/0da4a1d4e95dddf9638ec00747895008a10f7ba8) Thanks [@bourquep](https://github.com/bourquep)! - Updated dependencies to latest versions
+
+- [#220](https://github.com/bourquep/mysa2mqtt/pull/220) [`f0dc8c1`](https://github.com/bourquep/mysa2mqtt/commit/f0dc8c1c812e469cde891b513a812e717d584aff) Thanks [@dependabot](https://github.com/apps/dependabot)! - chore(deps): Bump @aws-sdk/client-iot from 3.1090.0 to 3.1094.0
+
+- [#219](https://github.com/bourquep/mysa2mqtt/pull/219) [`6bd3f92`](https://github.com/bourquep/mysa2mqtt/commit/6bd3f920dc85697c2d9665b31e25b36767884ecd) Thanks [@dependabot](https://github.com/apps/dependabot)! - chore(deps): Bump @aws-sdk/credential-providers from 3.1090.0 to 3.1094.0
+
+## 3.1.0
+
+### Minor Changes
+
+- [#211](https://github.com/bourquep/mysa2mqtt/pull/211) [`5dc3270`](https://github.com/bourquep/mysa2mqtt/commit/5dc32709beee8fa7caf487f422c0ed97ebc7c4a2) Thanks [@bourquep](https://github.com/bourquep)! - Support Mysa in-floor heating thermostats (INF-V1-0) ([#94](https://github.com/bourquep/mysa2mqtt/issues/94)).
+
+  - Parse the in-floor-specific status fields — floor-probe temperature (`flrSnsrTemp`), binary heating-relay state (`heatStat`), tracked sensor (`trackedSnsr`) and line voltage (`lineVtg`) — which share the V2 status message type (`msg: 40`). `heatStat` maps onto the emitted `dutyCycle`, and the floor-probe reading is surfaced as a new `Status.floorTemperature`.
+  - Send the correct control command `type` (3) for in-floor thermostats so setpoint and mode changes take effect instead of being silently ignored.
+
+- [#212](https://github.com/bourquep/mysa2mqtt/pull/212) [`a1000a7`](https://github.com/bourquep/mysa2mqtt/commit/a1000a7475c4487931edddab678ace6558a1d0e7) Thanks [@bourquep](https://github.com/bourquep)! - Add a `mysa2mqtt-capture` tool (and the underlying `MysaApiClient.startRawTopicCapture()` SDK method) to record the raw AWS IoT Device Shadow traffic of unsupported thermostats, most notably the central-HVAC ST-V1.
+
+  Unlike the real-time path, `startRawTopicCapture()` subscribes to arbitrary MQTT topic filters and relays every message verbatim (full topic + decoded payload) with no parsing, re-subscribing across reconnects. The `mysa2mqtt-capture` command uses it to dump a device's REST metadata and passively record every shadow message to a file, providing the raw material needed to implement support for a new device family. Run `npm run capture -w mysa2mqtt -- --help` for usage.
+
+### Patch Changes
+
+- [#205](https://github.com/bourquep/mysa2mqtt/pull/205) [`b5bf8f9`](https://github.com/bourquep/mysa2mqtt/commit/b5bf8f922c90a2342466e9ea1ba7e398ff0cd5d6) Thanks [@bourquep](https://github.com/bourquep)! - Fix fan-speed `fn` mapping for AC-V1-X (CodeNum=1117) devices ([#179](https://github.com/bourquep/mysa2mqtt/issues/179)).
+
+  - Derive the send-side `fn` values from the device's reported `SupportedCaps.fanSpeeds` (positionally mapped to the canonical `[auto, low, medium, high, max]` order) instead of a hardcoded universal map. Devices that don't report `fanSpeeds` keep the previous behaviour.
+  - Recognise the CodeNum=1117 canonical receive values (`fn` 2/4/6 → low/medium/high) so the current fan speed is surfaced instead of coming back `undefined`.
+  - Add the `fanSpeeds` field to the `SupportedCaps` type so consumers no longer need to cast to access it.
+  - Throw a new `UnsupportedFanSpeedError` when a requested fan speed is not supported by the target device (e.g. `max` on a device that only exposes auto/low/medium/high), instead of silently publishing a no-op command.
+
+- [#202](https://github.com/bourquep/mysa2mqtt/pull/202) [`49d3017`](https://github.com/bourquep/mysa2mqtt/commit/49d3017fd301c1b79560d1a6403927a7c15de3be) Thanks [@bourquep](https://github.com/bourquep)! - Harden the MQTT connection against `AWS_ERROR_MQTT_UNEXPECTED_HANGUP` interrupt storms ([#178](https://github.com/bourquep/mysa2mqtt/issues/178)).
+
+  - Switch to clean MQTT sessions so the broker no longer redelivers a backlog of queued QoS1 messages on reconnect (the source of the ~1000x message bursts and exponential Home Assistant database growth) and so forced resets no longer leave orphaned broker sessions.
+  - Make the forced connection reset repeatable with exponential backoff instead of one-shot, so a persistent storm keeps recovering (fresh client id + fresh credentials) rather than giving up.
+  - Tag each connection with a generation and ignore events from discarded connections, and ensure the reset never rejects — preventing the in-flight publish crash (`AWS_ERROR_MQTT_CONNECTION_DESTROYED`) that terminated the process.
+  - Add interrupt dwell-time and session diagnostics to help pin down the server-side hangup trigger.
+
 ## 3.0.0
 
 ### Major Changes

package/README.md

@@ -203,8 +203,7 @@ copyright notice and license text in any copy of the software or substantial por
 
 ## Support
 
-For bug reports and feature requests, please use the [GitHub Issues](https://github.com/bourquep/mysa2mqtt/issues)
-page.
+For bug reports and feature requests, please use the [GitHub Issues](https://github.com/bourquep/mysa2mqtt/issues) page.
 
 For general questions and discussions, join our [Discussion Forum](https://github.com/bourquep/mysa2mqtt/discussions).
 
@@ -216,6 +215,6 @@ protocol which is being used by this library.
 
 ## Contributors ✨
 
-This project follows the [all-contributors](https://github.com/all-contributors/all-contributors)
-specification. See the [contributor list](https://github.com/bourquep/mysa2mqtt#contributors-) in the
-repository README. Contributions of any kind welcome!
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. See the
+[contributor list](https://github.com/bourquep/mysa2mqtt#contributors-) in the repository README. Contributions of any
+kind welcome!

package/dist/index.cjs

@@ -60,6 +60,7 @@ __export(index_exports, {
   OutMessageType: () => OutMessageType,
   UnauthenticatedError: () => UnauthenticatedError,
   UnknownDeviceError: () => UnknownDeviceError,
+  UnsupportedFanSpeedError: () => UnsupportedFanSpeedError,
   VoidLogger: () => VoidLogger
 });
 module.exports = __toCommonJS(index_exports);
@@ -118,6 +119,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.
@@ -274,6 +296,43 @@ var MqttEndpoint = "a3q27gia9qg3zy-ats.iot.us-east-1.amazonaws.com";
 var MysaApiBaseUrl = "https://app-prod.mysa.cloud";
 var RealtimeKeepAliveInterval = import_dayjs.default.duration(5, "minutes");
 var PublishAckTimeout = import_dayjs.default.duration(30, "seconds");
+var MqttInterruptWindow = import_dayjs.default.duration(30, "seconds");
+var MqttInterruptThreshold = 3;
+var MqttResetBaseDelay = import_dayjs.default.duration(1, "second");
+var MqttResetMaxDelay = import_dayjs.default.duration(30, "seconds");
+var MqttStabilityWindow = import_dayjs.default.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;
@@ -297,8 +356,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;
   /**
@@ -352,6 +424,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 import_amazon_cognito_identity_js.CognitoUser({
@@ -543,6 +616,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) {
@@ -560,7 +634,10 @@ var MysaApiClient = class {
     const now = (0, import_dayjs.default)();
     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(),
@@ -577,7 +654,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,
@@ -681,6 +758,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, import_aws_iot_device_sdk_v2.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.
    *
@@ -882,7 +999,7 @@ var MysaApiClient = class {
       const usernameHash = (0, import_crypto.hash)("sha1", username);
       this._mqttClientId = `mysa-js-sdk-${usernameHash}-${process.pid}-${getRandomClientId()}`;
     }
-    const builder = import_aws_iot_device_sdk_v2.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 = import_aws_iot_device_sdk_v2.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 {
@@ -925,89 +1042,174 @@ var MysaApiClient = class {
     };
     const client = new import_aws_iot_device_sdk_v2.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((0, import_dayjs.default)())) ?? 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, import_aws_iot_device_sdk_v2.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, import_aws_iot_device_sdk_v2.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, import_aws_iot_device_sdk_v2.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, import_aws_iot_device_sdk_v2.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.
    *
@@ -1043,7 +1245,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,
@@ -1052,6 +1253,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",
@@ -1061,18 +1272,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;
           }
@@ -1092,6 +1296,7 @@ var MysaApiClient = class {
   OutMessageType,
   UnauthenticatedError,
   UnknownDeviceError,
+  UnsupportedFanSpeedError,
   VoidLogger
 });
 //# sourceMappingURL=index.cjs.map