TSVeSync

A TypeScript library for interacting with VeSync smart home devices. This library provides a modern, type-safe interface for controlling VeSync devices including air purifiers, outlets, and switches.

🆕 Recent Updates

• ESWD16 State Parity (v1.3.12): Bypass calls now reuse pyvesync-style trace IDs and mark the dimmer on after backlight tweaks, eliminating the lingering “off” state in HomeKit.
• ESWD16 Bypass Compatibility (v1.3.11): Migrated the dimmer switch to the modern bypass-v1 API so power, brightness, and indicator updates stay in sync with pyvesync.
• ESL Bulb API Parity (v1.3.10): ESL100/ESL100CW/ESL100MC now mirror pyvesync /SmartBulb/v1 and /cloud/v2 payloads for brightness and colour control.
• Enhanced Authentication: Now supports the new VeSync authentication flow (pyvesync PR #340) with automatic fallback to legacy authentication
• Regional API Support: Automatic detection and routing for US (smartapi.vesync.com) and EU (smartapi.vesync.eu) endpoints
• International Account Support: Full support for accounts worldwide including Australia, New Zealand, Japan, and all European countries
• Country Code Configuration: Specify your country code for proper authentication with international accounts
• Improved Error Handling: Better recovery from API changes and authentication errors with helpful guidance
• Cross-Region Support: Automatic handling of cross-region authentication errors

Features

• Full TypeScript support with type definitions
• Support for multiple device types:
  • Air Purifiers (Core200S, Core300S, Core400S, Core600S, LV-PUR131S, Vital100S, Vital200S, EverestAir)
  • Humidifiers (Classic300S, Classic200S, Dual200S, LV600S, OasisMist series, Superior6000S)
  • Smart Bulbs (ESL100, ESL100CW, ESL100MC, XYD0001)
  • Outlets (15A, 10A, 7A models)
  • Smart Tower Fans (LTF-F422S series)
• Real-time device status and control
• Energy monitoring for supported devices
• Air quality monitoring for supported purifiers
• Humidity control for supported humidifiers
• RGB and color temperature control for smart bulbs
• Fan speed and mode control
• Comprehensive error handling
• Modern async/await API

Supported Devices

Air Purifiers

• Core200S
  • Features: Sleep mode, Manual mode, Filter life monitoring
  • Fan speeds: 1-3
• Core300S
  • Features: Auto mode, Sleep mode, Manual mode, Air quality monitoring
  • Fan speeds: 1-4
• Core400S
  • Features: Auto mode, Sleep mode, Manual mode, Air quality monitoring
  • Fan speeds: 1-4
• Core600S
  • Features: Auto mode, Sleep mode, Manual mode, Air quality monitoring
  • Fan speeds: 1-4
• LV-PUR131S
  • Features: Air quality monitoring
• Vital100S
  • Features: Air quality monitoring, Pet mode
  • Modes: Manual, Auto, Sleep, Pet
  • Fan speeds: 1-4
• Vital200S
  • Features: Air quality monitoring, Pet mode
  • Modes: Manual, Auto, Sleep, Pet
  • Fan speeds: 1-4
• EverestAir
  • Features: Air quality monitoring, Fan rotation, Turbo mode
  • Modes: Manual, Auto, Sleep, Turbo
  • Fan speeds: 1-3

Humidifiers

• Classic300S
  • Features: Nightlight
  • Modes: Auto, Sleep, Manual
  • Mist levels: 1-9
• Classic200S
  • Modes: Auto, Manual
  • Mist levels: 1-9
• Dual200S
  • Modes: Auto, Manual
  • Mist levels: 1-2
• LV600S
  • Features: Warm mist, Nightlight
  • Modes: Humidity, Sleep, Manual
  • Mist levels: 1-9
  • Warm mist levels: 0-3
• OasisMist (EU)
  • Features: Warm mist, Nightlight
  • Modes: Auto, Manual
  • Mist levels: 1-9
  • Warm mist levels: 0-3
• OasisMist (US)
  • Features: Warm mist
  • Modes: Auto, Humidity, Sleep, Manual
  • Mist levels: 1-9
  • Warm mist levels: 0-3
• OasisMist1000S
  • Modes: Auto, Sleep, Manual
  • Mist levels: 1-9
• Superior6000S
  • Modes: Auto, Humidity, Sleep, Manual
  • Mist levels: 1-9

Smart Bulbs

• ESL100
  • Features: Basic white light
  • Brightness control
• ESL100CW
  • Features: Tunable white light
  • Brightness control
  • Color temperature control (warm to cool white)
• ESL100MC
  • Features: Full RGB color
  • White and color modes
  • Brightness control
  • RGB color control
• XYD0001
  • Features: Full RGB color with HSV control
  • White and color modes
  • Brightness control
  • Color temperature control
  • HSV (Hue, Saturation, Value) color control

Outlets

• 15A Outlet (ESO15-TB)
  • Power monitoring
  • Energy usage tracking (daily/weekly/monthly/yearly)
  • Voltage monitoring
  • Outdoor rated
• 15A Outlet (ESW15-USA)
  • Power monitoring
  • Energy usage tracking (daily/weekly/monthly/yearly)
  • Voltage monitoring
• 10A Outlet (ESW03-USA)
  • Power monitoring
  • Energy usage tracking (daily/weekly/monthly/yearly)
  • Voltage monitoring
• 10A Outlet (ESW01-EU)
  • Power monitoring
  • Energy usage tracking (daily/weekly/monthly/yearly)
  • Voltage monitoring
• 10A Outlet (ESW10-USA)
  • Power monitoring
  • Energy usage tracking (daily/weekly/monthly/yearly)
  • Voltage monitoring
• 7A Outlet (wifi-switch-1.3)
  • Energy usage tracking (daily/weekly/monthly/yearly)

Smart Tower Fan

• LTF-F422S Series
  • Features: Fan speed control
  • Modes: Normal, Auto, Advanced Sleep, Turbo
  • Fan speeds: 1-12

Wall Switches

• ESWL01
  • Basic on/off control
  • Status monitoring
• ESWL03
  • Basic on/off control
  • Status monitoring
• ESWD16
  • Dimming control
  • RGB indicator light control
  • Status monitoring

Installation

npm install tsvesync

Usage

Basic Setup

import { VeSync } from 'tsvesync';

// Create a VeSync manager instance
const manager = new VeSync(username, password);

// Login
await manager.login();

// Get all devices
await manager.getDevices();

International Account Support

For accounts created outside the United States, you may need to specify your country code:

import { VeSync } from 'tsvesync';

// For Australian users
const manager = new VeSync(username, password, 'America/Sydney', {
    countryCode: 'AU'
});

// For German users
const manager = new VeSync(username, password, 'Europe/Berlin', {
    countryCode: 'DE'
});

// For UK users
const manager = new VeSync(username, password, 'Europe/London', {
    countryCode: 'GB'
});

await manager.login();

Supported Country Codes

The library supports all ISO 3166-1 alpha-2 country codes (e.g. US, DE, AU).

pyvesync parity notes (regions + device list)

VeSync uses two API base URLs:

• US: https://smartapi.vesync.com
• EU: https://smartapi.vesync.eu

This library intentionally mirrors pyvesync behavior for the initial region selection:

• US region: US, CA, MX, JP
• EU region: everything else

Some accounts may still “live” in the opposite region for historical/app reasons; in that case the new auth flow returns a cross‑region response and we automatically retry Step 2 using the server-provided currentRegion/countryCode + bizToken (pyvesync-style).

Device discovery parity note: the device list call uses /cloud/v1/deviceManaged/devices with bypass headers only; token and accountID are supplied in the request body (matching pyvesync’s request model).

Working with Devices

// Get device status
for (const device of manager.devices) {
    await device.update();
    console.log(`${device.deviceName}: ${device.deviceStatus}`);
}

// Control an air purifier
const fan = manager.devices.find(d => d.deviceType === 'Core300S');
if (fan) {
    await fan.setMode('auto');  // Available modes: auto, sleep, manual
    await fan.changeFanSpeed(2);      // Speed range depends on model
}

// Control an outlet
const outlet = manager.devices.find(d => d.deviceType === 'ESO15-TB');
if (outlet) {
    await outlet.turnOn();
    const energy = await outlet.getEnergyUsage();
    console.log('Current power usage:', energy.power, 'W');
}

Environment Variables

The library supports configuration through environment variables:

[email protected]
VESYNC_PASSWORD=your_password
VESYNC_API_URL=https://smartapi.vesync.com  # Optional, defaults to standard API URL

Testing

The project includes a comprehensive test suite:

# Run the standard test suite
npm test

# Run the special device test (requires .env configuration)
npx ts-node test/testSpecial.ts

Development

Building

npm run build

Linting

npm run lint

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Acknowledgments

This project is inspired by the PyVeSync Python library and aims to provide similar functionality for TypeScript/JavaScript developers.