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('[email protected]', '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('[email protected]', '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:

1. Using environment variables:

[email protected] HARVIA_PASSWORD=your_password node examples/basic-control.js

2. Using a .env file:

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

[email protected]
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:

1. Fetches endpoint information from the MyHarvia API
2. Uses the Cognito User Pool and Client ID from the endpoint response
3. Authenticates with AWS Cognito using the provided email and password
4. Stores the auth tokens and uses them for subsequent API calls
5. 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