harvia-xenio-js

Harvia Xenio WiFi

A Node.js library for controlling Harvia Xenio WiFi sauna control systems.

Features

• Full TypeScript support with comprehensive type definitions
• Simple API for controlling your Harvia sauna from Node.js applications
• Authentication with MyHarvia service using AWS Cognito
• Device discovery and management
• Real-time state monitoring
• Control power, temperature, light, and fan settings

Installation

npm install harvia-xenio-js

Quick Start

const { HarviaClient } = require('harvia-xenio-js');

async function main() {
  try {
    // Create a client instance
    const client = new HarviaClient();
    
    // Authenticate with your MyHarvia account
    await client.login('[e-mail]', 'your-password');
    
    // Get all your devices
    const devices = await client.getDevices();
    
    if (devices.length === 0) {
      console.log('No saunas found');
      return;
    }
    
    // Use the first sauna
    const sauna = devices[0];
    console.log(`Using sauna: ${sauna.name}`);
    
    // Get current state
    const state = await client.getState(sauna.serialNumber);
    console.log(`Current temperature: ${state.temperature.current}°C`);
    
    // Turn the sauna on
    await client.power(sauna.serialNumber, true);
    
    // Set the temperature to 70°C
    await client.setTemperature(sauna.serialNumber, 70);
    
    // Monitor state changes
    const subscription = client.subscribeToState(sauna.serialNumber, (newState) => {
      console.log(`Temperature: ${newState.temperature.current}°C / ${newState.temperature.target}°C`);
    });
    
    // Run for 30 seconds, then clean up
    setTimeout(async () => {
      // Stop monitoring
      subscription.unsubscribe();
      
      // Turn sauna off
      await client.power(sauna.serialNumber, false);
      
      // Logout
      await client.logout();
    }, 30000);
  } catch (error) {
    console.error('Error:', error.message);
  }
}

main();

API Documentation

Client Options

You can configure the client with these options:

const client = new HarviaClient({
  baseUrl: 'https://prod.myharvia-cloud.net', // Default API URL
  timeout: 10000,                            // Request timeout in ms
  autoRefreshToken: true,                    // Auto refresh auth token
  pollingInterval: 5000,                     // State polling interval in ms
});

Basic Methods

Authentication

// Login
await client.login('[e-mail]', 'password');

// Refresh token (happens automatically with autoRefreshToken: true)
await client.refreshToken();

// Logout
await client.logout();

Device Management

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

// Get specific device by serial number
const device = await client.getDevice('SERIAL123');

State Monitoring

// Get current state
const state = await client.getState('SERIAL123');

// Subscribe to state changes
const subscription = client.subscribeToState('SERIAL123', (state) => {
  console.log(`Current temperature: ${state.temperature.current}°C`);
});

// Stop monitoring
subscription.unsubscribe();

Commands

// Power on/off
await client.power('SERIAL123', true);  // On
await client.power('SERIAL123', false); // Off

// Set temperature
await client.setTemperature('SERIAL123', 70); // 70°C

// Light control
await client.setLight('SERIAL123', true);  // On
await client.setLight('SERIAL123', false); // Off

// Fan control
await client.setFan('SERIAL123', true);  // On
await client.setFan('SERIAL123', false); // Off

Data Types

SaunaState

The getState method and state subscription callbacks return a SaunaState object with the following properties:

{
  power: boolean;              // Whether the sauna is on
  temperature: {
    current: number;           // Current temperature
    target: number;            // Target temperature
  };
  humidity: number;            // Current humidity
  light: boolean;              // Whether the light is on
  fan: boolean;                // Whether the fan is on
  doorOpen: boolean;           // Whether the door is open
  remainingTime: number;       // Remaining time in minutes
  heatUpTime?: number;         // Heat up time in minutes (if available)
}

Examples

The library includes several example applications in the examples directory:

• basic-control.js - A simple example showing basic control operations
• monitor-state.js - An example demonstrating state monitoring
• comprehensive-client.js - A complete example showing all API features

Configuration

To run the examples, you need to set your MyHarvia credentials. You can do this in two ways:

• Using environment variables:

HARVIA_EMAIL=[e-mail] HARVIA_PASSWORD=your_password node examples/basic-control.js

• Using a .env file:

Copy the .env.sample file to .env and edit it with your credentials:

HARVIA_EMAIL=[e-mail]
HARVIA_PASSWORD=your_password

Then run the examples normally:

node examples/basic-control.js

Development

Building

npm run build

Testing

The library includes a comprehensive test suite with good coverage:

npm test

To run tests with coverage report:

npm test -- --coverage

Authentication

The MyHarvia API uses AWS Cognito for authentication. This library fully implements the required AWS Cognito authentication using the amazon-cognito-identity-js package.

The authentication flow:

• Fetches endpoint information from the MyHarvia API
• Uses the Cognito User Pool and Client ID from the endpoint response
• Authenticates with AWS Cognito using the provided email and password
• Stores the auth tokens and uses them for subsequent API calls
• Automatically refreshes the token when it expires (if autoRefreshToken is enabled)

Credits

This library is based on reverse-engineered API endpoints from the MyHarvia mobile app. Special thanks to RubenHarms/ha-harvia-xenio-wifi for documenting the API.

License

MIT