mysa-js-sdk
    Preparing search index...

    Class MysaApiClient

    Main client for interacting with the Mysa API and real-time device communication.

    The MysaApiClient provides a comprehensive interface for authenticating with Mysa services, managing device data, and receiving real-time updates from Mysa thermostats and heating devices. It handles both REST API calls for device management and MQTT connections for live status updates and control commands.

    const client = new MysaApiClient({ username: 'user@example.com', password: 'password' });

    await client.login();
    const devices = await client.getDevices();

    client.emitter.on('statusChanged', (status) => {
      console.log(`Device ${status.deviceId} temperature: ${status.temperature}°C`);
    });

    for (const device of Object.entries(devices.DevicesObj)) {
      await client.startRealtimeUpdates(device[0]);
    }
    Index
    constructor
    emitter
    getDeviceFirmwares getDevices getDeviceSerialNumber getDeviceStates getHomes login setDeviceState setTrackedSensor startRawTopicCapture startRealtimeUpdates stopRealtimeUpdates
    emitter: EventEmitter<MysaApiClientEventTypes> = ...

    Event emitter for client events.

    MysaApiClientEventTypes for the possible events and their payloads.

    • 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.

      Returns Promise<Devices>

      A promise that resolves to the list of devices.

      const devices = await client.getDevices();
      for (const [deviceId, device] of Object.entries(devices.DevicesObj)) {
        console.log(`Device: ${device.DisplayName} (${device.Model})`);
      }

      MysaApiError When the API request fails.

      UnauthenticatedError When the client cannot authenticate with its credentials.

    • 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.

      Parameters

      • deviceId: string

        The ID of the device to get the serial number for.

      Returns Promise<string | undefined>

      A promise that resolves to the serial number, or undefined if not found.

      const serialNumber = await client.getDeviceSerialNumber('device123');
      if (serialNumber) {
        console.log(`Device serial: ${serialNumber}`);
      } else {
        console.log('Serial number not available');
      }

      UnauthenticatedError When the client cannot authenticate with its credentials.

    • Ensures the client has a usable session, logging in with the credentials it was constructed with if needed.

      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.

      Returns Promise<void>

      try {
        await client.login();
        console.log('Login successful!');
      } catch (error) {
        console.error('Login failed:', error.message);
      }

      UnauthenticatedError When authentication fails due to invalid credentials or network issues.

    • 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.

      Parameters

      • deviceId: string

        The ID of the device to control.

      • OptionalsetPoint: number

        The target temperature set point (optional).

      • Optionalmode: MysaDeviceMode

        The operating mode to set (one of MysaDeviceMode values, or undefined to leave unchanged).

      • OptionalfanSpeed: MysaFanSpeedMode

        The fan speed mode to set ('low', 'medium', 'high', 'max', 'auto', or undefined to leave unchanged).

      • OptionaltrackedSensor: MysaTrackedSensor

        The sensor an in-floor thermostat should regulate against, or undefined to leave unchanged.

      Returns Promise<void>

      // 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');

      UnauthenticatedError When the client cannot authenticate with its credentials.

      UnknownDeviceError When the device id does not match any device on the account.

      UnsupportedFanSpeedError When the requested fan speed is not supported by the device.

      UnsupportedTrackedSensorError When a tracked sensor is requested for a device that has no floor probe to select.

      Error When MQTT connection or command sending fails.

    • Chooses which temperature sensor an in-floor heating thermostat regulates against.

      In-floor units (INF-V1-0) carry both an ambient air sensor and a probe embedded in the floor, and this selects between them — the same setting the Mysa app exposes. The device confirms the change on its next status message via Status.trackedSensor, and immediately via StateChange.trackedSensor.

      Parameters

      • deviceId: string

        The ID of the in-floor thermostat to control.

      • trackedSensor: MysaTrackedSensor

        The sensor to regulate against.

      Returns Promise<void>

      await client.setTrackedSensor('device123', 'floor');

      UnauthenticatedError When the client cannot authenticate with its credentials.

      UnknownDeviceError When the device id does not match any device on the account.

      UnsupportedTrackedSensorError When the device is not an in-floor thermostat.

      Error When MQTT connection or command sending fails.

    • Subscribes to raw MQTT topic filters and relays every message verbatim.

      Unlike 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.

      Parameters

      • topicFilters: string[]

        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.

      • handler: (topic: string, payload: string) => void

        Invoked with the full message topic and the decoded UTF-8 payload for every message received.

      Returns Promise<void>

      Error When the MQTT connection cannot be established.

    • 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.

      Parameters

      • deviceId: string

        The ID of the device to start receiving updates for.

      Returns Promise<void>

      // Start receiving updates and listen for events
      await client.startRealtimeUpdates('device123');

      client.emitter.on('statusChanged', (status) => {
        console.log(`Temperature: ${status.temperature}°C`);
      });

      Error When MQTT connection or subscription fails.

    • 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.

      Parameters

      • deviceId: string

        The ID of the device to stop receiving real-time updates for.

      Returns Promise<void>

      Error When MQTT unsubscription fails.

    Settings
    Member Visibility

    On This Page
    Constructors
    Properties
    Methods