mysa-js-sdk 1.3.2 → 1.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
 
-[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](#contributors-)
 
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
@@ -247,6 +247,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
   <tbody>
     <tr>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/jagmandan"><img src="https://avatars.githubusercontent.com/u/227265405?v=4?s=100" width="100px;" alt="jagmandan"/><br /><sub><b>jagmandan</b></sub></a><br /><a href="https://github.com/bourquep/mysa-js-sdk/commits?author=jagmandan" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/remiolivier"><img src="https://avatars.githubusercontent.com/u/1379047?v=4?s=100" width="100px;" alt="remiolivier"/><br /><sub><b>remiolivier</b></sub></a><br /><a href="https://github.com/bourquep/mysa-js-sdk/commits?author=remiolivier" title="Code">💻</a></td>
     </tr>
   </tbody>
 </table>

package/dist/index.cjs

@@ -54,6 +54,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   InMessageType: () => InMessageType,
+  MqttPublishError: () => MqttPublishError,
   MysaApiClient: () => MysaApiClient,
   MysaApiError: () => MysaApiError,
   OutMessageType: () => OutMessageType,
@@ -93,6 +94,21 @@ var MysaApiError = class extends Error {
     this.statusText = apiResponse.statusText;
   }
 };
+var MqttPublishError = class extends Error {
+  /**
+   * Creates a new MqttPublishError instance.
+   *
+   * @param message - A human-readable description of the publish failure.
+   * @param attempts - The number of attempts that were made before giving up.
+   * @param original - The original error object thrown by the underlying MQTT library (optional).
+   */
+  constructor(message, attempts, original) {
+    super(message);
+    this.attempts = attempts;
+    this.original = original;
+    this.name = "MqttPublishError";
+  }
+};
 
 // src/api/Logger.ts
 var VoidLogger = class {
@@ -235,8 +251,8 @@ var MysaApiClient = class {
   _logger;
   /** The fetcher function used by the client. */
   _fetcher;
-  /** The MQTT connection used for real-time updates. */
-  _mqttConnection;
+  /** A promise that resolves to the MQTT connection used for real-time updates. */
+  _mqttConnectionPromise;
   /** The device IDs that are currently being updated in real-time, mapped to their respective timeouts. */
   _realtimeDeviceIds = /* @__PURE__ */ new Map();
   /** The cached devices object, if any. */
@@ -356,7 +372,7 @@ var MysaApiClient = class {
    */
   async getDevices() {
     this._logger.debug(`Fetching devices...`);
-    const session = await this.getFreshSession();
+    const session = await this._getFreshSession();
     const response = await this._fetcher(`${MysaApiBaseUrl}/devices`, {
       headers: {
         Authorization: `${session.getIdToken().getJwtToken()}`
@@ -391,7 +407,7 @@ var MysaApiClient = class {
   async getDeviceSerialNumber(deviceId) {
     var _a;
     this._logger.debug(`Fetching serial number for device ${deviceId}...`);
-    const session = await this.getFreshSession();
+    const session = await this._getFreshSession();
     const credentialsProvider = (0, import_credential_providers.fromCognitoIdentityPool)({
       clientConfig: {
         region: AwsRegion
@@ -428,7 +444,7 @@ var MysaApiClient = class {
    */
   async getDeviceFirmwares() {
     this._logger.debug(`Fetching device firmwares...`);
-    const session = await this.getFreshSession();
+    const session = await this._getFreshSession();
     const response = await this._fetcher(`${MysaApiBaseUrl}/devices/firmware`, {
       headers: {
         Authorization: `${session.getIdToken().getJwtToken()}`
@@ -448,7 +464,7 @@ var MysaApiClient = class {
    */
   async getDeviceStates() {
     this._logger.debug(`Fetching device states...`);
-    const session = await this.getFreshSession();
+    const session = await this._getFreshSession();
     const response = await this._fetcher(`${MysaApiBaseUrl}/devices/state`, {
       headers: {
         Authorization: `${session.getIdToken().getJwtToken()}`
@@ -476,31 +492,39 @@ var MysaApiClient = class {
    *
    * // Set temperature and mode
    * await client.setDeviceState('device123', 20, 'heat');
+   *
+   * // Set fan speed
+   * await client.setDeviceState('device123', undefined, undefined, 'auto');
    * ```
    *
    * @param deviceId - The ID of the device to control.
    * @param setPoint - The target temperature set point (optional).
-   * @param mode - The operating mode to set ('off', 'heat', or undefined to leave unchanged).
+   * @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 Error} When MQTT connection or command sending fails.
    */
-  async setDeviceState(deviceId, setPoint, mode) {
+  async setDeviceState(deviceId, setPoint, mode, fanSpeed) {
+    var _a;
     this._logger.debug(`Setting device state for '${deviceId}'`);
     if (!this._cachedDevices) {
       this._cachedDevices = await this.getDevices();
     }
     const device = this._cachedDevices.DevicesObj[deviceId];
     this._logger.debug(`Initializing MQTT connection...`);
-    const mqttConnection = await this.getMqttConnection();
+    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 payload = serializeMqttPayload({
       msg: 44 /* CHANGE_DEVICE_STATE */,
       id: now.valueOf(),
       time: now.unix(),
       ver: "1.0",
       src: {
-        ref: this.session.username,
+        ref: ((_a = this.session) == null ? void 0 : _a.username) ?? "",
         type: 100
       },
       dest: {
@@ -510,17 +534,24 @@ var MysaApiClient = class {
       resp: 2,
       body: {
         ver: 1,
-        type: device.Model.startsWith("BB-V1") ? 1 : device.Model.startsWith("BB-V2") ? device.Model.endsWith("-L") ? 5 : 4 : 0,
+        type: device.Model.startsWith("BB-V1") ? 1 : device.Model.startsWith("AC-V1") ? 2 : device.Model.startsWith("BB-V2") ? device.Model.endsWith("-L") ? 5 : 4 : 0,
         cmd: [
           {
             tm: -1,
             sp: setPoint,
-            md: mode === "off" ? 1 : mode === "heat" ? 3 : void 0
+            md: mode ? modeMap[mode] : void 0,
+            fn: fanSpeed ? fanSpeedMap[fanSpeed] : void 0
           }
         ]
       }
     });
-    await mqttConnection.publish(`/v1/dev/${deviceId}/in`, payload, import_aws_iot_device_sdk_v2.mqtt.QoS.AtLeastOnce);
+    try {
+      await this._publishWithRetry(mqttConnection, `/v1/dev/${deviceId}/in`, payload, import_aws_iot_device_sdk_v2.mqtt.QoS.AtLeastOnce);
+      this._logger.debug(`Device state publish succeeded for '${deviceId}'`);
+    } catch (error) {
+      this._logger.error(`Failed to set device state for '${deviceId}'`, error);
+      throw error;
+    }
   }
   /**
    * Starts receiving real-time updates for the specified device.
@@ -550,10 +581,10 @@ var MysaApiClient = class {
       return;
     }
     this._logger.debug(`Initializing MQTT connection...`);
-    const mqttConnection = await this.getMqttConnection();
+    const mqttConnection = await this._getMqttConnection();
     this._logger.debug(`Subscribing to MQTT topic '/v1/dev/${deviceId}/out'...`);
     await mqttConnection.subscribe(`/v1/dev/${deviceId}/out`, import_aws_iot_device_sdk_v2.mqtt.QoS.AtLeastOnce, (_, payload2) => {
-      this.processMqttMessage(payload2);
+      this._processMqttMessage(payload2);
     });
     this._logger.debug(`Sending request to start publishing device status for '${deviceId}'...`);
     const payload = serializeMqttPayload({
@@ -562,7 +593,7 @@ var MysaApiClient = class {
       Timestamp: (0, import_dayjs.default)().unix(),
       Timeout: RealtimeKeepAliveInterval.asSeconds()
     });
-    await mqttConnection.publish(`/v1/dev/${deviceId}/in`, payload, import_aws_iot_device_sdk_v2.mqtt.QoS.AtLeastOnce);
+    await this._publishWithRetry(mqttConnection, `/v1/dev/${deviceId}/in`, payload, import_aws_iot_device_sdk_v2.mqtt.QoS.AtLeastOnce);
     const timer = setInterval(async () => {
       this._logger.debug(`Sending request to keep-alive publishing device status for '${deviceId}'...`);
       const payload2 = serializeMqttPayload({
@@ -571,7 +602,7 @@ var MysaApiClient = class {
         Timestamp: (0, import_dayjs.default)().unix(),
         Timeout: RealtimeKeepAliveInterval.asSeconds()
       });
-      await mqttConnection.publish(`/v1/dev/${deviceId}/in`, payload2, import_aws_iot_device_sdk_v2.mqtt.QoS.AtLeastOnce);
+      await this._publishWithRetry(mqttConnection, `/v1/dev/${deviceId}/in`, payload2, import_aws_iot_device_sdk_v2.mqtt.QoS.AtLeastOnce);
     }, RealtimeKeepAliveInterval.subtract(10, "seconds").asMilliseconds());
     this._realtimeDeviceIds.set(deviceId, timer);
   }
@@ -592,7 +623,7 @@ var MysaApiClient = class {
       return;
     }
     this._logger.debug(`Initializing MQTT connection...`);
-    const mqttConnection = await this.getMqttConnection();
+    const mqttConnection = await this._getMqttConnection();
     this._logger.debug(`Unsubscribing to MQTT topic '/v1/dev/${deviceId}/out'...`);
     await mqttConnection.unsubscribe(`/v1/dev/${deviceId}/out`);
     clearInterval(timer);
@@ -607,7 +638,7 @@ var MysaApiClient = class {
    * @returns A promise that resolves to a valid CognitoUserSession.
    * @throws {@link UnauthenticatedError} When no session exists or refresh fails.
    */
-  async getFreshSession() {
+  async _getFreshSession() {
     if (!this._cognitoUser || !this._cognitoUserSession) {
       throw new UnauthenticatedError("An attempt was made to access a resource without a valid session.");
     }
@@ -639,11 +670,98 @@ var MysaApiClient = class {
    * @returns A promise that resolves to an active MQTT connection.
    * @throws {@link Error} When connection establishment fails.
    */
-  async getMqttConnection() {
-    if (this._mqttConnection) {
-      return this._mqttConnection;
+  _getMqttConnection() {
+    if (!this._mqttConnectionPromise) {
+      this._mqttConnectionPromise = this._createMqttConnection().catch((err) => {
+        this._mqttConnectionPromise = void 0;
+        throw err;
+      });
+    }
+    return this._mqttConnectionPromise;
+  }
+  /**
+   * Determines whether an MQTT-related error is considered transient and worth retrying.
+   *
+   * Transient errors include timeouts, cancelled operations due to clean sessions, temporary connectivity loss, and
+   * other recoverable network issues. Fatal errors (auth, permission, configuration) should not be retried at this
+   * layer.
+   *
+   * @param err - The error object thrown by the underlying MQTT operation.
+   * @returns True if the error appears transient and a retry should be attempted; false otherwise.
+   */
+  _isTransientMqttError(err) {
+    if (!err || typeof err !== "object") {
+      return false;
     }
-    const session = await this.getFreshSession();
+    const anyErr = err;
+    const code = anyErr.error_code || anyErr.error_name || anyErr.error;
+    const msg = (anyErr.message || anyErr.error || "").toString();
+    const transientMarkers = [
+      "AWS_ERROR_MQTT_TIMEOUT",
+      "AWS_ERROR_MQTT_NO_CONNECTION",
+      "Time limit between request and response",
+      "timeout"
+    ];
+    return transientMarkers.some((m) => code && String(code).includes(m) || msg.includes(m));
+  }
+  /**
+   * Publishes an MQTT message with exponential backoff retries for transient failures.
+   *
+   * Retries occur for errors classified by `_isTransientMqttError`. Between attempts the delay grows exponentially with
+   * jitter to avoid thundering herds after broker recovery. If the connection is not currently marked as connected, a
+   * reconnect is attempted; if that fails, the connection is rebuilt (fresh credentials) before the next retry.
+   *
+   * On final failure (after maxAttempts) a {@link MqttPublishError} is thrown including the number of attempts and
+   * original error for higher-level handling.
+   *
+   * @remarks
+   * Retry options fields:
+   *
+   * - MaxAttempts: Maximum number of publish attempts before failing (default: 5).
+   * - BaseDelayMs: Base delay in milliseconds used for exponential backoff calculation (default: 500).
+   *
+   * @param connection - The active MQTT client connection used to send the publish.
+   * @param topic - The MQTT topic to publish to.
+   * @param payload - The serialized payload (binary buffer or Uint8Array).
+   * @param qos - The desired MQTT QoS level for the publish.
+   * @param opts - Retry options (defaults: maxAttempts=5, baseDelayMs=500).
+   * @returns A promise that resolves when the publish succeeds, or rejects with {@link MqttPublishError}.
+   */
+  async _publishWithRetry(connection, topic, payload, qos, opts = {}) {
+    const maxAttempts = opts.maxAttempts ?? 5;
+    const baseDelayMs = opts.baseDelayMs ?? 500;
+    let attempt = 0;
+    while (true) {
+      attempt++;
+      try {
+        await connection.publish(topic, payload, qos);
+        return;
+      } catch (err) {
+        const isTransient = this._isTransientMqttError(err);
+        if (!isTransient || attempt >= maxAttempts) {
+          throw new MqttPublishError(`MQTT publish failed after ${attempt} attempts`, attempt, err);
+        }
+        const JITTER_MIN_FACTOR = 0.75;
+        const JITTER_RANGE = 0.5;
+        const delay = baseDelayMs * Math.pow(2, attempt - 1) * (JITTER_MIN_FACTOR + Math.random() * JITTER_RANGE);
+        this._logger.warn(
+          `Transient MQTT publish error on '${topic}' (attempt ${attempt}/${maxAttempts}). Retrying in ${Math.round(
+            delay
+          )}ms`
+        );
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+  }
+  /**
+   * Creates a new MQTT connection using AWS IoT WebSocket connections with Cognito credentials.
+   *
+   * @returns A promise that resolves to an active MQTT connection.
+   * @throws {@link Error} When connection establishment fails.
+   */
+  async _createMqttConnection() {
+    var _a;
+    const session = await this._getFreshSession();
     const credentialsProvider = (0, import_credential_providers.fromCognitoIdentityPool)({
       clientConfig: {
         region: AwsRegion
@@ -655,16 +773,49 @@ var MysaApiClient = class {
       logger: this._logger
     });
     const credentials = await credentialsProvider();
-    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(`mysa-js-sdk-${(0, import_dayjs.default)().unix()}`).with_clean_session(true).with_keep_alive_seconds(30).with_ping_timeout_ms(3e3).with_protocol_operation_timeout_ms(6e4);
+    const stableClientId = `mysa-js-sdk-${((_a = this.session) == null ? void 0 : _a.username) ?? ""}`;
+    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(stableClientId).with_clean_session(false).with_keep_alive_seconds(30).with_ping_timeout_ms(3e3).with_protocol_operation_timeout_ms(6e4);
     const config = builder.build();
     const client = new import_aws_iot_device_sdk_v2.mqtt.MqttClient();
-    this._mqttConnection = client.new_connection(config);
-    this._mqttConnection.on("closed", () => {
+    const connection = client.new_connection(config);
+    connection.on("connect", () => {
+      this._logger.debug("MQTT connect");
+    });
+    connection.on("connection_success", () => {
+      this._logger.debug("MQTT connection_success");
+    });
+    connection.on("connection_failure", (e) => {
+      this._logger.error("MQTT connection_failure", e);
+    });
+    connection.on("interrupt", (e) => {
+      this._logger.warn("MQTT interrupt", e);
+    });
+    connection.on("resume", async (returnCode, sessionPresent) => {
+      this._logger.info(`MQTT resume returnCode=${returnCode} sessionPresent=${sessionPresent}`);
+      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);
+            });
+          }
+        } catch (err) {
+          this._logger.error("Failed to re-subscribe after resume", err);
+        }
+      }
+    });
+    connection.on("error", (e) => {
+      this._logger.error("MQTT error", e);
+    });
+    connection.on("closed", () => {
       this._logger.info("MQTT connection closed");
-      this._mqttConnection = void 0;
+      this._mqttConnectionPromise = void 0;
     });
-    await this._mqttConnection.connect();
-    return this._mqttConnection;
+    await connection.connect();
+    return connection;
   }
   /**
    * Processes incoming MQTT messages and emits appropriate events.
@@ -675,7 +826,7 @@ var MysaApiClient = class {
    *
    * @param payload - The raw MQTT message payload to process.
    */
-  processMqttMessage(payload) {
+  _processMqttMessage(payload) {
     try {
       const parsedPayload = parseMqttPayload(payload);
       this.emitter.emit("rawRealtimeMessageReceived", parsedPayload);
@@ -709,13 +860,30 @@ var MysaApiClient = class {
               dutyCycle: parsedPayload.body.dtyCycle
             });
             break;
-          case 44 /* DEVICE_STATE_CHANGE */:
+          case 44 /* DEVICE_STATE_CHANGE */: {
+            const modeMap = {
+              1: "off",
+              2: "auto",
+              3: "heat",
+              4: "cool",
+              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 === 1 ? "off" : parsedPayload.body.state.md === 3 ? "heat" : void 0,
-              setPoint: parsedPayload.body.state.sp
+              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
             });
             break;
+          }
         }
       }
     } catch (error) {
@@ -726,6 +894,7 @@ var MysaApiClient = class {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   InMessageType,
+  MqttPublishError,
   MysaApiClient,
   MysaApiError,
   OutMessageType,