mysa-js-sdk 2.1.2 → 3.1.0

package/dist/index.cjs

@@ -59,20 +59,32 @@ __export(index_exports, {
   MysaApiError: () => MysaApiError,
   OutMessageType: () => OutMessageType,
   UnauthenticatedError: () => UnauthenticatedError,
+  UnknownDeviceError: () => UnknownDeviceError,
+  UnsupportedFanSpeedError: () => UnsupportedFanSpeedError,
   VoidLogger: () => VoidLogger
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/api/Errors.ts
 var UnauthenticatedError = class extends Error {
+  /**
+   * The underlying failure that prevented authentication.
+   *
+   * Callers need it to tell a credential rejection apart from a transport or service failure, since both surface as
+   * this error. Declared explicitly rather than passed to `super` so the SDK keeps compiling against its current lib,
+   * which predates the two-argument `Error` constructor.
+   */
+  cause;
   /**
    * Creates a new UnauthenticatedError instance.
    *
    * @param message - The error message
+   * @param cause - The underlying failure that prevented authentication, if any.
    */
-  constructor(message) {
+  constructor(message, cause) {
     super(message);
     this.name = "UnauthenticatedError";
+    this.cause = cause;
   }
 };
 var MysaApiError = class extends Error {
@@ -94,6 +106,40 @@ var MysaApiError = class extends Error {
     this.statusText = apiResponse.statusText;
   }
 };
+var UnknownDeviceError = class extends Error {
+  /**
+   * Creates a new UnknownDeviceError instance.
+   *
+   * @param deviceId - The device id that could not be resolved
+   */
+  constructor(deviceId) {
+    super(`Unknown device id '${deviceId}': no such device on this account.`);
+    this.deviceId = deviceId;
+    this.name = "UnknownDeviceError";
+  }
+  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.
@@ -191,8 +237,9 @@ function parseMqttPayload(payload) {
     const jsonString = decoder.decode(payload);
     return JSON.parse(jsonString);
   } catch (error) {
-    console.error("Error parsing MQTT payload:", error);
-    throw new Error("Failed to parse MQTT payload");
+    const parseError = new Error("Failed to parse MQTT payload");
+    parseError.cause = error;
+    throw parseError;
   }
 }
 function serializeMqttPayload(payload) {
@@ -249,11 +296,52 @@ 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;
   /** The current session object, if any. */
   _cognitoUserSession;
   /** The current user object, if any. */
   _cognitoUser;
+  /** The in-flight session acquisition, if any, so that concurrent callers share a single refresh or login. */
+  _freshSessionPromise;
   /** The logger instance used by the client. */
   _logger;
   /** The fetcher function used by the client. */
@@ -268,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;
   /**
@@ -278,89 +379,63 @@ var MysaApiClient = class {
    * @see {@link MysaApiClientEventTypes} for the possible events and their payloads.
    */
   emitter = new EventEmitter();
-  /**
-   * Gets the persistable session object.
-   *
-   * @returns The current persistable session object, if any.
-   */
-  get session() {
-    if (!this._cognitoUserSession || !this._cognitoUser) {
-      return void 0;
-    }
-    return {
-      username: this._cognitoUser.getUsername(),
-      idToken: this._cognitoUserSession.getIdToken().getJwtToken(),
-      accessToken: this._cognitoUserSession.getAccessToken().getJwtToken(),
-      refreshToken: this._cognitoUserSession.getRefreshToken().getToken()
-    };
-  }
-  /**
-   * Returns whether the client currently has an active session.
-   *
-   * @returns True if the client has an active session, false otherwise.
-   */
-  get isAuthenticated() {
-    return !!this.session;
-  }
   /**
    * Constructs a new instance of the MysaApiClient.
    *
-   * @param session - The persistable session object, if any.
+   * @param credentials - The credentials of the Mysa account to authenticate as.
    * @param options - The options for the client.
    */
-  constructor(session, options) {
+  constructor(credentials, options) {
+    this._credentials = credentials;
     this._logger = (options == null ? void 0 : options.logger) || new VoidLogger();
     this._fetcher = (options == null ? void 0 : options.fetcher) || fetch;
-    if (session) {
-      this._cognitoUser = new import_amazon_cognito_identity_js.CognitoUser({
-        Username: session.username,
-        Pool: new import_amazon_cognito_identity_js.CognitoUserPool({ UserPoolId: CognitoUserPoolId, ClientId: CognitoClientId })
-      });
-      this._cognitoUserSession = new import_amazon_cognito_identity_js.CognitoUserSession({
-        IdToken: new import_amazon_cognito_identity_js.CognitoIdToken({ IdToken: session.idToken }),
-        AccessToken: new import_amazon_cognito_identity_js.CognitoAccessToken({ AccessToken: session.accessToken }),
-        RefreshToken: new import_amazon_cognito_identity_js.CognitoRefreshToken({ RefreshToken: session.refreshToken })
-      });
-    }
   }
   /**
-   * Logs in the user with the given email address and password.
+   * Ensures the client has a usable session, logging in with the credentials it was constructed with if needed.
    *
-   * This method authenticates the user with Mysa's Cognito user pool and establishes a session that can be used for
-   * subsequent API calls. Upon successful login, a 'sessionChanged' event is emitted.
+   * Calling this method is optional: the client authenticates on demand before its first API call, and re-authenticates
+   * on its own whenever its session can no longer be refreshed. Call it explicitly at startup to fail fast on invalid
+   * credentials instead of on the first API call. It is a no-op when the current session is still usable.
    *
    * @example
    *
    * ```typescript
    * try {
-   *   await client.login('user@example.com', 'password123');
+   *   await client.login();
    *   console.log('Login successful!');
    * } catch (error) {
    *   console.error('Login failed:', error.message);
    * }
    * ```
    *
-   * @param emailAddress - The email address of the user.
-   * @param password - The password of the user.
+   * @throws {@link UnauthenticatedError} When authentication fails due to invalid credentials or network issues.
+   */
+  async login() {
+    await this._getFreshSession();
+  }
+  /**
+   * Authenticates with Mysa's Cognito user pool and replaces the current session, if any.
+   *
+   * @returns A promise that resolves to the newly established session.
    * @throws {@link Error} When authentication fails due to invalid credentials or network issues.
    */
-  async login(emailAddress, password) {
+  _login() {
     this._cognitoUser = void 0;
     this._cognitoUserSession = void 0;
     this._mqttClientId = void 0;
     this._mqttInterrupts = [];
-    this.emitter.emit("sessionChanged", this.session);
+    this._mqttConsecutiveResets = 0;
+    const { username, password } = this._credentials;
     return new Promise((resolve, reject) => {
       const user = new import_amazon_cognito_identity_js.CognitoUser({
-        Username: emailAddress,
+        Username: username,
         Pool: new import_amazon_cognito_identity_js.CognitoUserPool({ UserPoolId: CognitoUserPoolId, ClientId: CognitoClientId })
       });
-      user.authenticateUser(new import_amazon_cognito_identity_js.AuthenticationDetails({ Username: emailAddress, Password: password }), {
+      user.authenticateUser(new import_amazon_cognito_identity_js.AuthenticationDetails({ Username: username, Password: password }), {
         onSuccess: (session) => {
           this._cognitoUser = user;
           this._cognitoUserSession = session;
-          this.emitter.emit("sessionChanged", this.session);
-          resolve();
+          resolve(session);
         },
         onFailure: (err) => {
           reject(err);
@@ -385,7 +460,7 @@ var MysaApiClient = class {
    *
    * @returns A promise that resolves to the list of devices.
    * @throws {@link MysaApiError} When the API request fails.
-   * @throws {@link UnauthenticatedError} When the user is not authenticated.
+   * @throws {@link UnauthenticatedError} When the client cannot authenticate with its credentials.
    */
   async getDevices() {
     this._logger.debug(`Fetching devices...`);
@@ -419,7 +494,7 @@ var MysaApiClient = class {
    *
    * @param deviceId - The ID of the device to get the serial number for.
    * @returns A promise that resolves to the serial number, or undefined if not found.
-   * @throws {@link UnauthenticatedError} When the user is not authenticated.
+   * @throws {@link UnauthenticatedError} When the client cannot authenticate with its credentials.
    */
   async getDeviceSerialNumber(deviceId) {
     var _a;
@@ -457,7 +532,7 @@ var MysaApiClient = class {
    *
    * @returns A promise that resolves to the firmware information for all devices.
    * @throws {@link MysaApiError} When the API request fails.
-   * @throws {@link UnauthenticatedError} When the user is not authenticated.
+   * @throws {@link UnauthenticatedError} When the client cannot authenticate with its credentials.
    */
   async getDeviceFirmwares() {
     this._logger.debug(`Fetching device firmwares...`);
@@ -477,7 +552,7 @@ var MysaApiClient = class {
    *
    * @returns A promise that resolves to the current state of all devices.
    * @throws {@link MysaApiError} When the API request fails.
-   * @throws {@link UnauthenticatedError} When the user is not authenticated.
+   * @throws {@link UnauthenticatedError} When the client cannot authenticate with its credentials.
    */
   async getDeviceStates() {
     this._logger.debug(`Fetching device states...`);
@@ -497,7 +572,7 @@ var MysaApiClient = class {
    *
    * @returns A promise that resolves to the homes information.
    * @throws {@link MysaApiError} When the API request fails.
-   * @throws {@link UnauthenticatedError} When the user is not authenticated.
+   * @throws {@link UnauthenticatedError} When the client cannot authenticate with its credentials.
    */
   async getHomes() {
     this._logger.debug(`Fetching homes...`);
@@ -539,29 +614,37 @@ var MysaApiClient = class {
    * @param mode - The operating mode to set (one of MysaDeviceMode values, or undefined to leave unchanged).
    * @param fanSpeed - The fan speed mode to set ('low', 'medium', 'high', 'max', 'auto', or undefined to leave
    *   unchanged).
-   * @throws {@link UnauthenticatedError} When the user is not authenticated.
+   * @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) {
-    var _a;
     this._logger.debug(`Setting device state for '${deviceId}'`);
     if (!this._cachedDevices) {
       this._cachedDevices = await this.getDevices();
     }
+    if (!Object.prototype.hasOwnProperty.call(this._cachedDevices.DevicesObj, deviceId)) {
+      throw new UnknownDeviceError(deviceId);
+    }
     const device = this._cachedDevices.DevicesObj[deviceId];
+    await this._getFreshSession();
     this._logger.debug(`Initializing MQTT connection...`);
     const mqttConnection = await this._getMqttConnection();
     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(),
       time: now.unix(),
       ver: "1.0",
       src: {
-        ref: ((_a = this.session) == null ? void 0 : _a.username) ?? "",
+        ref: this._cognitoUser.getUsername(),
         type: 100
       },
       dest: {
@@ -571,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,
@@ -675,37 +758,102 @@ 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.
    *
    * This method checks if the current session is valid and not expired. If the session is expired, it automatically
-   * refreshes it using the refresh token.
+   * refreshes it using the refresh token. If there is no session yet, or if the refresh token has itself expired or
+   * been revoked, the client logs back in with its credentials.
+   *
+   * Concurrent callers share a single in-flight acquisition, so a burst of API calls never triggers more than one
+   * refresh or login.
    *
    * @returns A promise that resolves to a valid CognitoUserSession.
-   * @throws {@link UnauthenticatedError} When no session exists or refresh fails.
+   * @throws {@link UnauthenticatedError} When neither refreshing nor logging back in succeeds.
    */
   async _getFreshSession() {
-    if (!this._cognitoUser || !this._cognitoUserSession) {
-      throw new UnauthenticatedError("An attempt was made to access a resource without a valid session.");
-    }
-    if (this._cognitoUserSession.isValid() && import_dayjs.default.unix(this._cognitoUserSession.getIdToken().getExpiration()).isAfter()) {
+    var _a;
+    if (this._cognitoUser && ((_a = this._cognitoUserSession) == null ? void 0 : _a.isValid()) && import_dayjs.default.unix(this._cognitoUserSession.getIdToken().getExpiration()).isAfter()) {
       this._logger.debug("Session is valid, no need to refresh");
-      return Promise.resolve(this._cognitoUserSession);
+      return this._cognitoUserSession;
     }
-    this._logger.debug("Session is not valid or expired, refreshing...");
-    return new Promise((resolve, reject) => {
-      this._cognitoUser.refreshSession(this._cognitoUserSession.getRefreshToken(), (error, session) => {
-        if (error) {
-          this._logger.error("Failed to refresh session:", error);
-          reject(new UnauthenticatedError("Unable to refresh the authentication session."));
-        } else {
-          this._logger.debug("Session refreshed successfully");
-          this._cognitoUserSession = session;
-          this.emitter.emit("sessionChanged", this.session);
-          resolve(session);
-        }
-      });
+    this._freshSessionPromise ??= this._acquireFreshSession().finally(() => {
+      this._freshSessionPromise = void 0;
     });
+    return this._freshSessionPromise;
+  }
+  /**
+   * Refreshes the current session, falling back to a full login when it cannot be refreshed.
+   *
+   * @returns A promise that resolves to a valid CognitoUserSession.
+   * @throws {@link UnauthenticatedError} When logging back in fails.
+   */
+  async _acquireFreshSession() {
+    if (this._cognitoUser && this._cognitoUserSession) {
+      this._logger.debug("Session is not valid or expired, refreshing...");
+      try {
+        return await new Promise((resolve, reject) => {
+          this._cognitoUser.refreshSession(this._cognitoUserSession.getRefreshToken(), (error, session) => {
+            if (error) {
+              reject(error);
+            } else {
+              this._logger.debug("Session refreshed successfully");
+              this._cognitoUserSession = session;
+              resolve(session);
+            }
+          });
+        });
+      } catch (error) {
+        this._logger.warn("Failed to refresh session, logging back in:", error);
+      }
+    }
+    try {
+      this._logger.info("Logging in...");
+      return await this._login();
+    } catch (error) {
+      this._logger.error("Failed to log in:", error);
+      throw new UnauthenticatedError("Unable to establish an authentication session.", error);
+    }
   }
   /**
    * Establishes and returns an MQTT connection for real-time communication.
@@ -847,11 +995,11 @@ var MysaApiClient = class {
       throw new Error("MQTT credentials are already expired.");
     }
     if (!this._mqttClientId) {
-      const username = ((_a = this.session) == null ? void 0 : _a.username) ?? "anon";
+      const username = ((_a = this._cognitoUser) == null ? void 0 : _a.getUsername()) ?? "anon";
       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 {
@@ -894,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.
    *
@@ -1012,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,
@@ -1021,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",
@@ -1030,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;
           }
@@ -1060,6 +1295,8 @@ var MysaApiClient = class {
   MysaApiError,
   OutMessageType,
   UnauthenticatedError,
+  UnknownDeviceError,
+  UnsupportedFanSpeedError,
   VoidLogger
 });
 //# sourceMappingURL=index.cjs.map