Registry / http-networking / ewelink-api

ewelink-api

JSON →
library3.1.1jsnpmunverified

The ewelink-api library provides a programmatic interface for interacting with eWeLink-compatible smart home devices, such as Sonoff products, from Node.js environments. It supports both cloud-based interaction (requiring internet access) and ZeroConf (LAN mode) for local control without an internet connection. The current stable version is 3.1.1, with releases occurring on a moderate, irregular cadence, focusing on bug fixes, dependency updates, and feature enhancements like improved error handling and new device control methods. Key differentiators include its multi-environment compatibility (Node.js, browsers, serverless), robust device state management, and power consumption monitoring for compatible devices.

npm install ewelink-api
INSTALL
IMPORT
SIG · EWELINK-API
E
ewelink-api
http-networkingjavascriptv3.1.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

EwelinkApi
import EwelinkApi from 'ewelink-api';
import { EwelinkApi } from 'ewelink-api';
The primary class is exported as the default export. You can name it whatever you like, but 'EwelinkApi' is a common convention for clarity.
EwelinkApi (CommonJS)
const EwelinkApi = require('ewelink-api');
import EwelinkApi from 'ewelink-api';
For CommonJS environments (Node.js older projects), use `require` to import the default exported class.
Device types (TypeScript)
import type { Device, DeviceStatus } from 'ewelink-api/dist/ts/interface';
import { Device, DeviceStatus } from 'ewelink-api';
TypeScript types are located in a separate path. Always use `import type` for type-only imports.

Demonstrates initializing the API, logging in, finding a specific device, and toggling its power state using the recommended WebSocket method.

import EwelinkApi from 'ewelink-api'; const EMAIL = process.env.EWELINK_EMAIL ?? ''; const PASSWORD = process.env.EWELINK_PASSWORD ?? ''; const REGION = process.env.EWELINK_REGION ?? 'us'; // e.g., 'us', 'eu', 'as' const DEVICE_ID = process.env.EWELINK_DEVICE_ID ?? ''; async function controlDevice() { if (!EMAIL || !PASSWORD || !DEVICE_ID) { console.error('Please set EWELINK_EMAIL, EWELINK_PASSWORD, and EWELINK_DEVICE_ID environment variables.'); process.exit(1); } try { const connection = new EwelinkApi({ email: EMAIL, password: PASSWORD, region: REGION }); await connection.get and set things const devices = await connection.getDevices(); const targetDevice = devices.find(d => d.deviceid === DEVICE_ID); if (targetDevice) { console.log(`Found device: ${targetDevice.name} (ID: ${targetDevice.deviceid})`); // Toggle power state using the newer WebSocket method (v3.1.0+) console.log('Toggling device power state via WebSocket...'); const currentState = targetDevice.params.switch === 'on' ? 'off' : 'on'; await connection.setWSDevicePowerState(DEVICE_ID, currentState); console.log(`Device state toggled to ${currentState}.`); // Or using the standard HTTP method // console.log('Toggling device power state via HTTP...'); // await connection.setDevicePowerState(DEVICE_ID, currentState); // console.log(`Device state toggled to ${currentState}.`); const status = await connection.getDevicePowerState(DEVICE_ID); console.log(`Device new power state: ${status.state}`); } else { console.log(`Device with ID ${DEVICE_ID} not found.`); } } catch (error) { console.error('An error occurred:', error.message); } } controlDevice();
Debug
Known issues
breakingVersion 3.0.0 introduced significant changes to the authentication process, primarily switching to phone number and password login. If you were previously logging in with email, your authentication method will need to be updated.
fix
Update your login credentials to use a phone number and password combination when initializing the `EwelinkApi` class. Refer to the official documentation for specific parameter names.
affects: >=3.0.0
breakingThe default APP_ID and APP_SECRET used by the library were updated in version 2.0.1. If you were relying on hardcoded or previous default values, these may no longer function correctly, leading to authentication failures.
fix
Upgrade to version 3.1.0 or later and utilize the new feature that allows custom `APP_ID` and `APP_SECRET` to be passed during class initialization, or ensure your local environment uses the current correct values.
affects: >=2.0.1 <3.1.0
gotchaThe underlying HTTP client was changed from `requests` to `node-fetch` in version 3.0.0. While this primarily impacts internal implementation, it might subtly alter error structures or network request behavior in edge cases.
fix
Review any custom error handling logic you may have implemented that depends on specific error object properties from previous versions. Standard error handling should remain compatible.
affects: >=3.0.0
gotchaFor optimal performance and real-time control, particularly for power state changes, use the `setWSDevicePowerState` method (available since v3.1.0) which leverages WebSockets. The older `setDevicePowerState` method uses HTTP, which can be slower and less responsive.
fix
Prioritize `setWSDevicePowerState(deviceId, state)` for controlling device power states. Ensure your eWeLink account and devices support WebSocket communication.
affects: >=3.1.0
Errors
Common errors & fixes
Error: Account authentication failed. Please check your login credentials and region.
Incorrect email, phone number, password, or an invalid region provided during `EwelinkApi` class initialization.
fix
Double-check your `email` (or `phoneNumber`), `password`, and `region` parameters. Ensure the region corresponds to your eWeLink account server (e.g., 'us', 'eu', 'as').
TypeError: EwelinkApi is not a constructor
Attempting to import `EwelinkApi` as a named export (`import { EwelinkApi } from 'ewelink-api';`) when it is exported as a default.
fix
Change your import statement to `import EwelinkApi from 'ewelink-api';` for ES Modules or `const EwelinkApi = require('ewelink-api');` for CommonJS.
Error: Device not found or unreachable.
The provided device ID does not correspond to an existing device, or the device is offline/not registered to the authenticated account, or there's a network issue preventing connection (especially in LAN mode).
fix
Verify the `DEVICE_ID` is correct. Ensure the device is powered on and connected to Wi-Fi. If using LAN mode, confirm your network setup allows local communication with the device.
Upgrade
Version history
3.1.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
35 hits · last 30 days
node
32
OpenAI (training)
1
Resources
ewelink-api — npm install ewelink-api · libregistry