A TypeScript library for interacting with VeSync smart home devices
npm install tsvesyncA 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.
- 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
- 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
``bash`
npm install tsvesync
`typescript
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();
`
For accounts created outside the United States, you may need to specify your country code:
`typescript
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:
This library intentionally mirrors pyvesync behavior for the initial region selection:
- US region: US, CA, MX, JP
- 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).
`typescript${device.deviceName}: ${device.deviceStatus}
// Get device status
for (const device of manager.devices) {
await device.update();
console.log();
}
// 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');
}
`
The library supports configuration through environment variables:
`env`
VESYNC_USERNAME=your_email@example.com
VESYNC_PASSWORD=your_password
VESYNC_API_URL=https://smartapi.vesync.com # Optional, defaults to standard API URL
The project includes a comprehensive test suite:
`bashRun the standard test suite
npm test
Development
$3
bash
npm run build
`$3
bash
npm run lint
``Contributions are welcome! Please feel free to submit a Pull Request.
MIT
This project is inspired by the PyVeSync Python library and aims to provide similar functionality for TypeScript/JavaScript developers.