mysa-js-sdk

Mysa Smart Thermostat JavaScript SDK

A JavaScript SDK for accessing Mysa smart thermostats.

Description

This SDK provides a simple and intuitive way to interact with Mysa smart thermostats, allowing developers to easily query and update data from their Mysa smart thermostats, including real-time updates.

Disclaimer

This SDK was developed without the consent of the Mysa Smart Thermostats company, and makes use of undocumented and unsupported APIs. Use at your own risk, and be aware that Mysa may change the APIs at any time and break this repository permanently.

Installation

Prerequisites

You must own at least one Mysa Smart Thermostat or have credentials to access a working setup.
Node.js version 22.4.0 or higher.

# Using npm
npm install mysa-js-sdk

# Using yarn
yarn add mysa-js-sdk

# Using pnpm
pnpm add mysa-js-sdk

Running the Example Application

To run the example application, you'll need to provide your Mysa credentials. Create a .env file in the project root:

MYSA_USERNAME=your-email@example.com
MYSA_PASSWORD=your-password

Then, run the example:

npm run example

If you prefer to see the raw data published by your Mysa smart thermostats, run:

npm run example:raw

Using

The Mysa SDK provides a simple interface to interact with Mysa smart thermostats.

Basic Authentication

import { MysaApiClient } from 'mysa-js-sdk';

const client = new MysaApiClient();

// Login with email and password
await client.login('your-email@example.com', 'your-password');

// Check if authenticated
if (client.isAuthenticated) {
  console.log('Successfully authenticated!');
}

Retrieving Thermostat Data

Once authenticated, you can access your thermostat data:

// Get all devices
const devices = await client.getDevices();

// Access individual devices
for (const [deviceId, device] of Object.entries(devices.DevicesObj)) {
  console.log(`Device: ${device.Name}`);
  console.log(`Model: ${device.Model}`);
  console.log(`Location: ${device.Location}`);
  console.log(`Voltage: ${device.Voltage}V`);
}

// Set device temperature and mode
await client.setDeviceState('device-id', 22, 'heat'); // Set to 22°C in heat mode
await client.setDeviceState('device-id', undefined, 'off'); // Turn off

Real-time Updates

The SDK also supports real-time updates:

// Listen for temperature and status changes
client.emitter.on('statusChanged', (status) => {
  console.log(`Device ${status.deviceId}:`);
  console.log(`  Temperature: ${status.temperature}°C`);
  console.log(`  Humidity: ${status.humidity}%`);
  console.log(`  Set Point: ${status.setPoint}°C`);
  if (status.current !== undefined) {
    console.log(`  Current: ${status.current}A`);
  }
});

// Listen for setpoint changes
client.emitter.on('setPointChanged', (change) => {
  console.log(`Setpoint changed from ${change.previousSetPoint}°C to ${change.newSetPoint}°C`);
});

// Listen for device state changes
client.emitter.on('stateChanged', (change) => {
  console.log(`Device mode changed to: ${change.mode}`);
  console.log(`New setpoint: ${change.setPoint}°C`);
});

// Start real-time updates for all devices
const devices = await client.getDevices();
for (const deviceId of Object.keys(devices.DevicesObj)) {
  await client.startRealtimeUpdates(deviceId);
}

Error Handling

The SDK provides specific error types to handle API errors:

import { MysaApiClient, MysaApiError, UnauthenticatedError } from 'mysa-js-sdk';

const client = new MysaApiClient();

try {
  await client.login('user@example.com', 'password');
  const devices = await client.getDevices();
} catch (error) {
  if (error instanceof UnauthenticatedError) {
    console.error('Authentication failed:', error.message);
  } else if (error instanceof MysaApiError) {
    console.error(`API Error ${error.status}: ${error.statusText}`);
  } else {
    console.error('Unexpected error:', error);
  }
}

Advanced Configuration

You can customize the client with various options:

import { MysaApiClient } from 'mysa-js-sdk';
import { pino } from 'pino';

// Create a custom logger
const logger = pino({
  name: 'mysa-client',
  level: 'debug'
});

// Configure client with options
const client = new MysaApiClient(undefined, {
  logger: logger,
  fetcher: fetch // Custom fetch implementation if needed
});

// Or restore from a saved session
const savedSession = {
  username: 'user@example.com',
  idToken: 'eyJ...',
  accessToken: 'eyJ...',
  refreshToken: 'abc123...'
};

const clientWithSession = new MysaApiClient(savedSession, { logger });

// Listen for session changes to persist them
client.emitter.on('sessionChanged', (newSession) => {
  if (newSession) {
    // Save session to storage (file, database, etc.)
    localStorage.setItem('mysaSession', JSON.stringify(newSession));
  } else {
    // Session expired or logged out
    localStorage.removeItem('mysaSession');
  }
});

Reference documentation

The complete reference documentation for the mysa-js-sdk library can be found at https://bourquep.github.io/mysa-js-sdk/.

Contributing

If you want to contribute to this project, please read the CONTRIBUTING.md file for guidelines.

License

mysa-js-sdk is licensed under the MIT License. This is a permissive license that allows you to use, modify, and redistribute this software in both private and commercial projects. You can change the code and distribute your changes without being required to release your source code. The MIT License only requires that you include the original copyright notice and license text in any copy of the software or substantial portion of it.

Copyright

Support

For bug reports and feature requests, please use the GitHub Issues page.

For general questions and discussions, join our Discussion Forum.

Acknowledgments

This library would not be possible without the amazing work by @dlenski in his mysotherm repository. He's the one who reversed-engineered the Mysa MQTT protocol which is being used by this library.