docs: add remiolivier as a contributor for code (#169)

Adds @remiolivier as a contributor for code.

This was requested by bourquep [in this
comment](https://github.com/bourquep/mysa-js-sdk/pull/156#issuecomment-3474627057)

---------

Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com>
Co-authored-by: Pascal Bourque <pascal@cosmos.moi>

.all-contributorsrc

@@ -0,0 +1,29 @@
+{
+  "files": ["README.md"],
+  "imageSize": 100,
+  "commit": false,
+  "commitType": "docs",
+  "commitConvention": "angular",
+  "contributors": [
+    {
+      "login": "jagmandan",
+      "name": "jagmandan",
+      "avatar_url": "https://avatars.githubusercontent.com/u/227265405?v=4",
+      "profile": "https://github.com/jagmandan",
+      "contributions": ["code"]
+    },
+    {
+      "login": "remiolivier",
+      "name": "remiolivier",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1379047?v=4",
+      "profile": "https://github.com/remiolivier",
+      "contributions": ["code"]
+    }
+  ],
+  "contributorsPerLine": 7,
+  "skipCi": true,
+  "repoType": "github",
+  "repoHost": "https://github.com",
+  "projectName": "mysa-js-sdk",
+  "projectOwner": "bourquep"
+}

.github/workflows/codeql.yml

@@ -0,0 +1,100 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: 'CodeQL Advanced'
+
+on:
+  push:
+    branches: ['main']
+  pull_request:
+    branches: ['main']
+  schedule:
+    - cron: '44 5 * * 5'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: actions
+            build-mode: none
+          - language: javascript-typescript
+            build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Add any setup steps before running the `github/codeql-action/init` action.
+      # This includes steps like installing compilers or runtimes (`actions/setup-node`
+      # or others). This is typically only required for manual builds.
+      # - name: Setup runtime (example)
+      #   uses: actions/setup-example@v1
+
+      # Initializes the CodeQL tools for scanning.
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+          # If you wish to specify custom queries, you can do so here or in a config file.
+          # By default, queries listed here will override any specified in a config file.
+          # Prefix the list here with "+" to use these queries and those in the config file.
+
+          # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+          # queries: security-extended,security-and-quality
+
+      # If the analyze step fails for one of the languages you are analyzing with
+      # "We were unable to automatically build your code", modify the matrix above
+      # to set the build mode to "manual" for that language. Then modify this step
+      # to build your code.
+      # ℹ️ Command-line programs to run using the OS shell.
+      # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+      - if: matrix.build-mode == 'manual'
+        shell: bash
+        run: |
+          echo 'If you are using a "manual" build mode for one or more of the' \
+            'languages you are analyzing, replace this with the commands to build' \
+            'your code, for example:'
+          echo '  make bootstrap'
+          echo '  make release'
+          exit 1
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: '/language:${{matrix.language}}'

README.md

@@ -1,5 +1,11 @@
 # Mysa Smart Thermostat JavaScript SDK
 
+<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
+
+[![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](#contributors-)
+
+<!-- ALL-CONTRIBUTORS-BADGE:END -->
+
 [![NPM Version](https://img.shields.io/npm/v/mysa-js-sdk)](https://www.npmjs.com/package/mysa-js-sdk)
 [![CodeQL](https://github.com/bourquep/mysa-js-sdk/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/bourquep/mysa-js-sdk/actions/workflows/github-code-scanning/codeql)
 [![CI: lint, build and release](https://github.com/bourquep/mysa-js-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/bourquep/mysa-js-sdk/actions/workflows/ci.yml)
@@ -51,6 +57,12 @@ Then, run the example:
 npm run example
 ```
 
+If you prefer to see the raw data published by your Mysa smart thermostats, run:
+
+```bash
+npm run example:raw
+```
+
 ## Using
 
 The Mysa SDK provides a simple interface to interact with Mysa smart thermostats.
@@ -223,3 +235,27 @@ For general questions and discussions, join our [Discussion Forum](https://githu
 This library would not be possible without the amazing work by [@dlenski](https://github.com/dlenski) in his
 [mysotherm](https://github.com/dlenski/mysotherm) repository. He's the one who reversed-engineered the Mysa MQTT
 protocol which is being used by this library.
+
+## Contributors ✨
+
+Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <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>
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification.
+Contributions of any kind welcome!

eslint.config.js

@@ -16,7 +16,8 @@ export default [
     rules: {
       'jsdoc/tag-lines': 'off',
       'jsdoc/check-tag-names': 'off',
-      'jsdoc/valid-types': 'off'
+      'jsdoc/valid-types': 'off',
+      'jsdoc/require-throws-type': 'off'
     }
   },
   { plugins: { tsdoc }, rules: { 'tsdoc/syntax': 'warn' } }

example/main.ts

@@ -57,15 +57,20 @@ async function main() {
 
   const devices = await client.getDevices();
 
+  if (process.env.MYSA_OUTPUT_RAW_DATA === 'true') {
+    client.emitter.on('rawRealtimeMessageReceived', (data) => {
+      rootLogger.info(data, 'Raw message received');
+    });
+  } else {
     client.emitter.on('statusChanged', (status) => {
       try {
         const device = devices.DevicesObj[status.deviceId];
         const watts = status.current !== undefined ? status.current * device.Voltage : undefined;
         rootLogger.info(
-        `'${device.Name}' status changed: ${status.temperature}°C, ${status.humidity}%, ${watts ?? 'na'}W`
+          `[${status.deviceId}] '${device.Name}' status changed: ${status.temperature}°C, ${status.humidity}%, ${watts ?? 'na'}W`
         );
       } catch (error) {
-      rootLogger.error(`Error processing status update for device '${status.deviceId}':`, error);
+        rootLogger.error(error, `Error processing status update for device '${status.deviceId}'`);
       }
     });
 
@@ -74,7 +79,7 @@ async function main() {
         const device = devices.DevicesObj[change.deviceId];
         rootLogger.info(`'${device.Name}' setpoint changed from ${change.previousSetPoint} to ${change.newSetPoint}`);
       } catch (error) {
-      rootLogger.error(`Error processing setpoint update for device '${change.deviceId}':`, error);
+        rootLogger.error(error, `Error processing setpoint update for device '${change.deviceId}'`);
       }
     });
 
@@ -83,13 +88,19 @@ async function main() {
         const device = devices.DevicesObj[change.deviceId];
         rootLogger.info(change, `'${device.Name}' state changed.`);
       } catch (error) {
-      rootLogger.error(`Error processing setpoint update for device '${change.deviceId}':`, error);
+        rootLogger.error(error, `Error processing state update for device '${change.deviceId}'`);
       }
     });
-
-  for (const device of Object.entries(devices.DevicesObj)) {
-    await client.startRealtimeUpdates(device[0]);
   }
+
+  await Promise.all(
+    Object.entries(devices.DevicesObj).map(async ([deviceId, device]) => {
+      const serial = await client.getDeviceSerialNumber(deviceId);
+      rootLogger.info(`Serial number for device '${deviceId}' (${device.Name}): ${serial}`);
+
+      await client.startRealtimeUpdates(deviceId);
+    })
+  );
 }
 
 main().catch((error) => {

package.json

@@ -40,39 +40,44 @@
   "browser": false,
   "scripts": {
     "example": "tsx --watch ./example/main.ts",
+    "example:raw": "MYSA_OUTPUT_RAW_DATA=true tsx --watch ./example/main.ts",
     "lint": "eslint --max-warnings 0 src/**/*.ts",
     "style-lint": "prettier -c .",
     "build": "tsup",
     "build:docs": "typedoc"
   },
+  "overrides": {
+    "brace-expansion": "^2.0.2"
+  },
   "dependencies": {
-    "@aws-sdk/credential-providers": "3.823.0",
+    "@aws-sdk/client-iot": "3.920.0",
+    "@aws-sdk/credential-providers": "3.901.0",
     "amazon-cognito-identity-js": "6.3.15",
-    "aws-iot-device-sdk-v2": "1.21.5",
+    "aws-iot-device-sdk-v2": "1.22.0",
-    "dayjs": "1.11.13",
+    "dayjs": "1.11.18",
     "lodash": "4.17.21"
   },
   "devDependencies": {
-    "@eslint/js": "9.28.0",
+    "@eslint/js": "9.38.0",
-    "@semantic-release/npm": "12.0.1",
+    "@semantic-release/npm": "13.1.1",
-    "@types/lodash": "4.17.17",
+    "@types/lodash": "4.17.20",
-    "@types/node": "22.15.29",
+    "@types/node": "24.9.2",
-    "conventional-changelog-conventionalcommits": "9.0.0",
+    "conventional-changelog-conventionalcommits": "9.1.0",
-    "dotenv": "16.5.0",
+    "dotenv": "17.2.3",
-    "eslint": "9.28.0",
+    "eslint": "9.38.0",
-    "eslint-plugin-jsdoc": "50.7.1",
+    "eslint-plugin-jsdoc": "61.1.11",
     "eslint-plugin-tsdoc": "0.4.0",
-    "pino": "9.7.0",
+    "pino": "9.13.0",
     "pino-pretty": "13.0.0",
-    "prettier": "3.5.3",
+    "prettier": "3.6.2",
-    "prettier-plugin-jsdoc": "1.3.2",
+    "prettier-plugin-jsdoc": "1.5.0",
-    "prettier-plugin-organize-imports": "4.1.0",
+    "prettier-plugin-organize-imports": "4.3.0",
-    "semantic-release": "24.2.5",
+    "semantic-release": "25.0.1",
     "tsup": "8.5.0",
-    "tsx": "4.19.4",
+    "tsx": "4.20.6",
-    "typedoc": "0.28.5",
+    "typedoc": "0.28.13",
     "typedoc-material-theme": "1.4.0",
-    "typescript": "5.8.3",
+    "typescript": "5.9.3",
-    "typescript-eslint": "8.33.1"
+    "typescript-eslint": "8.41.0"
   }
 }

src/api/Errors.ts

@@ -32,3 +32,22 @@ export class MysaApiError extends Error {
     this.statusText = apiResponse.statusText;
   }
 }
+
+/** Error thrown when an MQTT publish ultimately fails after retry attempts. */
+export class MqttPublishError 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: string,
+    public attempts: number,
+    public original?: unknown
+  ) {
+    super(message);
+    this.name = 'MqttPublishError';
+  }
+}

src/api/MysaApiClient.ts

@@ -7,6 +7,7 @@ import { InMessageType } from '@/types/mqtt/in/InMessageType';
 import { StartPublishingDeviceStatus } from '@/types/mqtt/in/StartPublishingDeviceStatus';
 import { OutMessageType } from '@/types/mqtt/out/OutMessageType';
 import { Devices, DeviceStates, Firmwares } from '@/types/rest';
+import { DescribeThingCommand, IoTClient } from '@aws-sdk/client-iot';
 import { fromCognitoIdentityPool } from '@aws-sdk/credential-providers';
 import {
   AuthenticationDetails,
@@ -19,15 +20,23 @@ import {
 } from 'amazon-cognito-identity-js';
 import { iot, mqtt } from 'aws-iot-device-sdk-v2';
 import dayjs from 'dayjs';
-import duration from 'dayjs/plugin/duration';
+import duration from 'dayjs/plugin/duration.js';
-import { MysaApiError, UnauthenticatedError } from './Errors';
+import { MqttPublishError, MysaApiError, UnauthenticatedError } from './Errors';
 import { Logger, VoidLogger } from './Logger';
 import { MysaApiClientEventTypes } from './MysaApiClientEventTypes';
 import { MysaApiClientOptions } from './MysaApiClientOptions';
-import { MysaDeviceMode } from './MysaDeviceMode';
+import { MysaDeviceMode, MysaFanSpeedMode } from './MysaDeviceMode';
 
 dayjs.extend(duration);
 
+/** Options for MQTT publish operations. */
+export interface MqttPublishOptions {
+  /** Maximum number of publish attempts before failing (default: 5). */
+  maxAttempts?: number;
+  /** Base delay in milliseconds used for exponential backoff calculation (default: 500). */
+  baseDelayMs?: number;
+}
+
 const AwsRegion = 'us-east-1';
 const CognitoUserPoolId = 'us-east-1_GUFWfhI7g';
 const CognitoClientId = '19efs8tgqe942atbqmot5m36t3';
@@ -74,8 +83,8 @@ export class MysaApiClient {
   /** The fetcher function used by the client. */
   private _fetcher: typeof fetch;
 
-  /** The MQTT connection used for real-time updates. */
+  /** A promise that resolves to the MQTT connection used for real-time updates. */
-  private _mqttConnection?: mqtt.MqttClientConnection;
+  private _mqttConnectionPromise?: Promise<mqtt.MqttClientConnection>;
 
   /** The device IDs that are currently being updated in real-time, mapped to their respective timeouts. */
   private _realtimeDeviceIds: Map<string, NodeJS.Timeout> = new Map();
@@ -143,8 +152,23 @@ export class MysaApiClient {
   /**
    * Logs in the user with the given email address and password.
    *
+   * 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.
+   *
+   * @example
+   *
+   * ```typescript
+   * try {
+   *   await client.login('user@example.com', 'password123');
+   *   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 Error} When authentication fails due to invalid credentials or network issues.
    */
   async login(emailAddress: string, password: string): Promise<void> {
     this._cognitoUser = undefined;
@@ -175,12 +199,26 @@ export class MysaApiClient {
   /**
    * Retrieves the list of devices associated with the user.
    *
+   * This method fetches all Mysa devices linked to the authenticated user's account, including device information such
+   * as models, locations, and configuration details.
+   *
+   * @example
+   *
+   * ```typescript
+   * const devices = await client.getDevices();
+   * for (const [deviceId, device] of Object.entries(devices.DevicesObj)) {
+   *   console.log(`Device: ${device.DisplayName} (${device.Model})`);
+   * }
+   * ```
+   *
    * @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.
    */
   async getDevices(): Promise<Devices> {
     this._logger.debug(`Fetching devices...`);
 
-    const session = await this.getFreshSession();
+    const session = await this._getFreshSession();
 
     const response = await this._fetcher(`${MysaApiBaseUrl}/devices`, {
       headers: {
@@ -195,10 +233,74 @@ export class MysaApiClient {
     return response.json();
   }
 
+  /**
+   * Retrieves the serial number for a specific device.
+   *
+   * This method uses AWS IoT's DescribeThing API to fetch the serial number attribute for the specified device. This
+   * requires additional AWS IoT permissions and may not be available for all devices.
+   *
+   * @example
+   *
+   * ```typescript
+   * const serialNumber = await client.getDeviceSerialNumber('device123');
+   * if (serialNumber) {
+   *   console.log(`Device serial: ${serialNumber}`);
+   * } else {
+   *   console.log('Serial number not available');
+   * }
+   * ```
+   *
+   * @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.
+   */
+  async getDeviceSerialNumber(deviceId: string): Promise<string | undefined> {
+    this._logger.debug(`Fetching serial number for device ${deviceId}...`);
+
+    const session = await this._getFreshSession();
+
+    // Get AWS credentials for IoT client
+    const credentialsProvider = fromCognitoIdentityPool({
+      clientConfig: {
+        region: AwsRegion
+      },
+      identityPoolId: CognitoIdentityPoolId,
+      logins: {
+        [CognitoLoginKey]: session.getIdToken().getJwtToken()
+      }
+    });
+
+    const credentials = await credentialsProvider();
+    const iotClient = new IoTClient({
+      region: AwsRegion,
+      credentials: {
+        accessKeyId: credentials.accessKeyId,
+        secretAccessKey: credentials.secretAccessKey,
+        sessionToken: credentials.sessionToken
+      }
+    });
+
+    try {
+      const command = new DescribeThingCommand({ thingName: deviceId });
+      const response = await iotClient.send(command);
+      return response.attributes?.['Serial'];
+    } catch (error) {
+      this._logger.warn(`Could not get serial number for device ${deviceId}:`, error);
+      return undefined;
+    }
+  }
+
+  /**
+   * Retrieves firmware information for all devices.
+   *
+   * @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.
+   */
   async getDeviceFirmwares(): Promise<Firmwares> {
     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: {
@@ -213,10 +315,17 @@ export class MysaApiClient {
     return response.json();
   }
 
+  /**
+   * Retrieves the current state information for all devices.
+   *
+   * @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.
+   */
   async getDeviceStates(): Promise<DeviceStates> {
     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: {
@@ -231,7 +340,37 @@ export class MysaApiClient {
     return response.json();
   }
 
-  async setDeviceState(deviceId: string, setPoint?: number, mode?: MysaDeviceMode) {
+  /**
+   * Sets the state of a specific device by sending commands via MQTT.
+   *
+   * This method allows you to change the temperature set point and/or operating mode of a Mysa device. The command is
+   * sent through the MQTT connection for real-time device control.
+   *
+   * @example
+   *
+   * ```typescript
+   * // Set temperature to 22°C
+   * await client.setDeviceState('device123', 22);
+   *
+   * // Turn device off
+   * await client.setDeviceState('device123', undefined, 'off');
+   *
+   * // 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 (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: string, setPoint?: number, mode?: MysaDeviceMode, fanSpeed?: MysaFanSpeedMode) {
     this._logger.debug(`Setting device state for '${deviceId}'`);
 
     if (!this._cachedDevices) {
@@ -241,18 +380,21 @@ export class MysaApiClient {
     const device = this._cachedDevices.DevicesObj[deviceId];
 
     this._logger.debug(`Initializing MQTT connection...`);
-    const mqttConnection = await this.getMqttConnection();
+    const mqttConnection = await this._getMqttConnection();
 
     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 payload = serializeMqttPayload<ChangeDeviceState>({
       msg: InMessageType.CHANGE_DEVICE_STATE,
-      id: now.unix(),
+      id: now.valueOf(),
       time: now.unix(),
       ver: '1.0',
       src: {
-        ref: this.session!.username,
+        ref: this.session?.username ?? '',
         type: 100
       },
       dest: {
@@ -264,6 +406,8 @@ export class MysaApiClient {
         ver: 1,
         type: device.Model.startsWith('BB-V1')
           ? 1
+          : device.Model.startsWith('AC-V1')
+            ? 2
             : device.Model.startsWith('BB-V2')
               ? device.Model.endsWith('-L')
                 ? 5
@@ -273,19 +417,42 @@ export class MysaApiClient {
           {
             tm: -1,
             sp: setPoint,
-            md: mode === 'off' ? 1 : mode === 'heat' ? 3 : undefined
+            md: mode ? modeMap[mode] : undefined,
+            fn: fanSpeed ? fanSpeedMap[fanSpeed] : undefined
           }
         ]
       }
     });
 
-    await mqttConnection.publish(`/v1/dev/${deviceId}/in`, payload, mqtt.QoS.AtLeastOnce);
+    try {
+      await this._publishWithRetry(mqttConnection, `/v1/dev/${deviceId}/in`, payload, 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.
    *
+   * This method establishes an MQTT subscription to receive live status updates from the device, including temperature,
+   * humidity, set point changes, and other state information. The client will automatically send keep-alive messages to
+   * maintain the connection.
+   *
+   * @example
+   *
+   * ```typescript
+   * // Start receiving updates and listen for events
+   * await client.startRealtimeUpdates('device123');
+   *
+   * client.emitter.on('statusChanged', (status) => {
+   *   console.log(`Temperature: ${status.temperature}°C`);
+   * });
+   * ```
+   *
    * @param deviceId - The ID of the device to start receiving updates for.
+   * @throws {@link Error} When MQTT connection or subscription fails.
    */
   async startRealtimeUpdates(deviceId: string) {
     this._logger.info(`Starting real-time updates for device '${deviceId}'`);
@@ -296,11 +463,11 @@ export class MysaApiClient {
     }
 
     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`, mqtt.QoS.AtLeastOnce, (_, payload) => {
-      this.processMqttMessage(payload);
+      this._processMqttMessage(payload);
     });
 
     this._logger.debug(`Sending request to start publishing device status for '${deviceId}'...`);
@@ -310,7 +477,7 @@ export class MysaApiClient {
       Timestamp: dayjs().unix(),
       Timeout: RealtimeKeepAliveInterval.asSeconds()
     });
-    await mqttConnection.publish(`/v1/dev/${deviceId}/in`, payload, mqtt.QoS.AtLeastOnce);
+    await this._publishWithRetry(mqttConnection, `/v1/dev/${deviceId}/in`, payload, mqtt.QoS.AtLeastOnce);
 
     const timer = setInterval(async () => {
       this._logger.debug(`Sending request to keep-alive publishing device status for '${deviceId}'...`);
@@ -320,7 +487,7 @@ export class MysaApiClient {
         Timestamp: dayjs().unix(),
         Timeout: RealtimeKeepAliveInterval.asSeconds()
       });
-      await mqttConnection.publish(`/v1/dev/${deviceId}/in`, payload, mqtt.QoS.AtLeastOnce);
+      await this._publishWithRetry(mqttConnection, `/v1/dev/${deviceId}/in`, payload, mqtt.QoS.AtLeastOnce);
     }, RealtimeKeepAliveInterval.subtract(10, 'seconds').asMilliseconds());
 
     this._realtimeDeviceIds.set(deviceId, timer);
@@ -329,7 +496,11 @@ export class MysaApiClient {
   /**
    * Stops receiving real-time updates for the specified device.
    *
+   * This method unsubscribes from the MQTT topic for the specified device and clears any associated timers to stop the
+   * keep-alive messages.
+   *
    * @param deviceId - The ID of the device to stop receiving real-time updates for.
+   * @throws {@link Error} When MQTT unsubscription fails.
    */
   async stopRealtimeUpdates(deviceId: string) {
     this._logger.info(`Stopping real-time updates for device '${deviceId}'`);
@@ -341,7 +512,7 @@ export class MysaApiClient {
     }
 
     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`);
@@ -350,7 +521,16 @@ export class MysaApiClient {
     this._realtimeDeviceIds.delete(deviceId);
   }
 
-  private async getFreshSession(): Promise<CognitoUserSession> {
+  /**
+   * 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.
+   *
+   * @returns A promise that resolves to a valid CognitoUserSession.
+   * @throws {@link UnauthenticatedError} When no session exists or refresh fails.
+   */
+  private async _getFreshSession(): Promise<CognitoUserSession> {
     if (!this._cognitoUser || !this._cognitoUserSession) {
       throw new UnauthenticatedError('An attempt was made to access a resource without a valid session.');
     }
@@ -379,12 +559,126 @@ export class MysaApiClient {
     });
   }
 
-  private async getMqttConnection(): Promise<mqtt.MqttClientConnection> {
+  /**
-    if (this._mqttConnection) {
+   * Establishes and returns an MQTT connection for real-time communication.
-      return this._mqttConnection;
+   *
+   * This method creates a new MQTT connection if one doesn't exist, using AWS IoT WebSocket connections with Cognito
+   * credentials. The connection is cached and reused for subsequent calls.
+   *
+   * @returns A promise that resolves to an active MQTT connection.
+   * @throws {@link Error} When connection establishment fails.
+   */
+  private _getMqttConnection(): Promise<mqtt.MqttClientConnection> {
+    if (!this._mqttConnectionPromise) {
+      this._mqttConnectionPromise = this._createMqttConnection().catch((err) => {
+        this._mqttConnectionPromise = undefined;
+        throw err;
+      });
     }
 
-    const session = await this.getFreshSession();
+    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.
+   */
+  private _isTransientMqttError(err: unknown): boolean {
+    if (!err || typeof err !== 'object') {
+      return false;
+    }
+
+    const anyErr = err as { error_code?: unknown; error_name?: unknown; error?: unknown; message?: unknown };
+    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}.
+   */
+  private async _publishWithRetry(
+    connection: mqtt.MqttClientConnection,
+    topic: string,
+    payload: ArrayBuffer | Uint8Array,
+    qos: mqtt.QoS,
+    opts: MqttPublishOptions = {}
+  ): Promise<void> {
+    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);
+        }
+
+        // Apply jitter: delay is randomized between 75% and 125% of the base exponential backoff
+        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.
+   */
+  private async _createMqttConnection(): Promise<mqtt.MqttClientConnection> {
+    const session = await this._getFreshSession();
     const credentialsProvider = fromCognitoIdentityPool({
       clientConfig: {
         region: AwsRegion
@@ -397,30 +691,81 @@ export class MysaApiClient {
     });
     const credentials = await credentialsProvider();
 
+    // Stable client id + persistent session to retain QoS1 queue & subscriptions across reconnects.
+    const stableClientId = `mysa-js-sdk-${this.session?.username ?? ''}`;
+
     const builder = iot.AwsIotMqttConnectionConfigBuilder.new_with_websockets()
       .with_credentials(AwsRegion, credentials.accessKeyId, credentials.secretAccessKey, credentials.sessionToken)
       .with_endpoint(MqttEndpoint)
-      .with_client_id(`mysa-js-sdk-${dayjs().unix()}`) // Unique client ID
+      .with_client_id(stableClientId)
-      .with_clean_session(true)
+      .with_clean_session(false)
       .with_keep_alive_seconds(30)
       .with_ping_timeout_ms(3000)
       .with_protocol_operation_timeout_ms(60000);
 
     const config = builder.build();
     const client = new mqtt.MqttClient();
-    this._mqttConnection = client.new_connection(config);
+    const connection = client.new_connection(config);
 
-    this._mqttConnection.on('closed', () => {
+    connection.on('connect', () => {
-      this._logger.info('MQTT connection closed');
+      this._logger.debug('MQTT connect');
-      this._mqttConnection = undefined;
     });
 
-    await this._mqttConnection.connect();
+    connection.on('connection_success', () => {
+      this._logger.debug('MQTT connection_success');
+    });
 
-    return this._mqttConnection;
+    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, 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._mqttConnectionPromise = undefined;
+    });
+
+    await connection.connect();
+
+    return connection;
   }
 
-  private processMqttMessage(payload: ArrayBuffer) {
+  /**
+   * Processes incoming MQTT messages and emits appropriate events.
+   *
+   * This method parses MQTT payloads and converts them into typed events that can be listened to via the client's event
+   * emitter. It handles both v1 and v2 device message formats and emits events like 'statusChanged', 'setPointChanged',
+   * and 'stateChanged'.
+   *
+   * @param payload - The raw MQTT message payload to process.
+   */
+  private _processMqttMessage(payload: ArrayBuffer) {
     try {
       const parsedPayload = parseMqttPayload(payload);
 
@@ -458,15 +803,33 @@ export class MysaApiClient {
             });
             break;
 
-          case OutMessageType.DEVICE_STATE_CHANGE:
+          case OutMessageType.DEVICE_STATE_CHANGE: {
+            const modeMap: Record<number, MysaDeviceMode> = {
+              1: 'off',
+              2: 'auto',
+              3: 'heat',
+              4: 'cool',
+              5: 'fan_only',
+              6: 'dry'
+            };
+            const fanSpeedMap: Record<number, MysaFanSpeedMode> = {
+              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' : undefined,
+              mode: parsedPayload.body.state.md ? modeMap[parsedPayload.body.state.md] : undefined,
-              setPoint: parsedPayload.body.state.sp
+              setPoint: parsedPayload.body.state.sp,
+              fanSpeed: parsedPayload.body.state.fn !== undefined ? fanSpeedMap[parsedPayload.body.state.fn] : undefined
             });
             break;
           }
         }
+      }
     } catch (error) {
       this._logger.error('Error handling MQTT message:', error);
     }

src/api/MysaDeviceMode.ts

@@ -4,4 +4,11 @@
  * Defines the possible operational states that a Mysa thermostat or heating device can be set to. These modes control
  * the device's heating behavior and power consumption.
  */
-export type MysaDeviceMode = 'off' | 'heat';
+export type MysaDeviceMode = 'off' | 'heat' | 'cool' | 'dry' | 'fan_only' | 'auto';
+
+/**
+ * Union type representing the available fan speed modes for Mysa devices.
+ *
+ * Defines the possible fan speed states that a Mysa thermostat device can be set to.
+ */
+export type MysaFanSpeedMode = 'auto' | 'low' | 'medium' | 'high' | 'max';

src/api/events/StateChange.ts

@@ -1,4 +1,4 @@
-import { MysaDeviceMode } from '@/api/MysaDeviceMode';
+import { MysaDeviceMode, MysaFanSpeedMode } from '@/api/MysaDeviceMode';
 
 /**
  * Interface representing a device state change event for a Mysa device.
@@ -14,4 +14,6 @@ export interface StateChange {
   mode?: MysaDeviceMode;
   /** Current temperature setpoint after the state change */
   setPoint: number;
+  /** Optional fan speed (1 = auto, 3 = low, 5 = medium, 7 = high, 8 = max). AC only */
+  fanSpeed?: MysaFanSpeedMode;
 }

src/lib/PayloadParser.ts

@@ -32,7 +32,7 @@ export function parseMqttPayload(payload: ArrayBuffer): OutPayload {
  * @param payload - The typed payload object to serialize
  * @returns The serialized payload as ArrayBuffer ready for MQTT transmission
  */
-export function serializeMqttPayload<T extends InPayload>(payload: T): ArrayBuffer {
+export function serializeMqttPayload<T extends InPayload>(payload: T): Uint8Array<ArrayBuffer> {
   const jsonString = JSON.stringify(payload);
   const encoder = new TextEncoder();
   return encoder.encode(jsonString);

src/types/mqtt/in/ChangeDeviceState.ts

@@ -36,6 +36,8 @@ export interface ChangeDeviceState extends MsgPayload<InMessageType.CHANGE_DEVIC
         md?: number;
         /** Unknown, should always be -1 */
         tm: number;
+        /** Optional fan speed (1 = auto, 3 = low, 5 = medium, 7 = high, 8 = max). AC only */
+        fn?: number;
       }
     ];
     /**

src/types/mqtt/out/DeviceStateChange.ts

@@ -25,10 +25,12 @@ export interface DeviceStateChange extends MsgPayload<OutMessageType.DEVICE_STAT
       ho: number;
       /** Unknown */
       lk: number;
-      /** Device mode (1 = OFF, 3 = HEAT) */
+      /** Device mode (1 = OFF, 2 = AUTO, 3 = HEAT, 4 = COOL, 5 = FAN_ONLY, 6 = DRY) */
       md: number;
       /** Temperature setpoint */
       sp: number;
+      /** Optional fan speed (1 = auto, 3 = low, 5 = medium, 7 = high, 8 = max). AC only */
+      fn?: number;
     };
     /** Success indicator for the state change operation (1 = success, 0 = failure) */
     success: number;

src/types/rest/States.ts

@@ -50,6 +50,8 @@ export interface DeviceState {
   Humidity: TimestampedValue<number>;
   /** Lock status */
   Lock: TimestampedValue<number>;
+  /** Fan speed */
+  FanSpeed?: TimestampedValue<number>;
 }
 
 /**