{"id":16021,"library":"ewelink-api","title":"eWeLink API Client for Node.js","description":"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.","status":"active","version":"3.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/skydiver/ewelink-api","tags":["javascript","ewelink","sonoff","api","node","nodejs","typescript"],"install":[{"cmd":"npm install ewelink-api","lang":"bash","label":"npm"},{"cmd":"yarn add ewelink-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add ewelink-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary class is exported as the default export. You can name it whatever you like, but 'EwelinkApi' is a common convention for clarity.","wrong":"import { EwelinkApi } from 'ewelink-api';","symbol":"EwelinkApi","correct":"import EwelinkApi from 'ewelink-api';"},{"note":"For CommonJS environments (Node.js older projects), use `require` to import the default exported class.","wrong":"import EwelinkApi from 'ewelink-api';","symbol":"EwelinkApi (CommonJS)","correct":"const EwelinkApi = require('ewelink-api');"},{"note":"TypeScript types are located in a separate path. Always use `import type` for type-only imports.","wrong":"import { Device, DeviceStatus } from 'ewelink-api';","symbol":"Device types (TypeScript)","correct":"import type { Device, DeviceStatus } from 'ewelink-api/dist/ts/interface';"}],"quickstart":{"code":"import EwelinkApi from 'ewelink-api';\n\nconst EMAIL = process.env.EWELINK_EMAIL ?? '';\nconst PASSWORD = process.env.EWELINK_PASSWORD ?? '';\nconst REGION = process.env.EWELINK_REGION ?? 'us'; // e.g., 'us', 'eu', 'as'\nconst DEVICE_ID = process.env.EWELINK_DEVICE_ID ?? '';\n\nasync function controlDevice() {\n  if (!EMAIL || !PASSWORD || !DEVICE_ID) {\n    console.error('Please set EWELINK_EMAIL, EWELINK_PASSWORD, and EWELINK_DEVICE_ID environment variables.');\n    process.exit(1);\n  }\n\n  try {\n    const connection = new EwelinkApi({ email: EMAIL, password: PASSWORD, region: REGION });\n    await connection.get and set things\n    const devices = await connection.getDevices();\n    const targetDevice = devices.find(d => d.deviceid === DEVICE_ID);\n\n    if (targetDevice) {\n      console.log(`Found device: ${targetDevice.name} (ID: ${targetDevice.deviceid})`);\n      \n      // Toggle power state using the newer WebSocket method (v3.1.0+)\n      console.log('Toggling device power state via WebSocket...');\n      const currentState = targetDevice.params.switch === 'on' ? 'off' : 'on';\n      await connection.setWSDevicePowerState(DEVICE_ID, currentState);\n      console.log(`Device state toggled to ${currentState}.`);\n\n      // Or using the standard HTTP method\n      // console.log('Toggling device power state via HTTP...');\n      // await connection.setDevicePowerState(DEVICE_ID, currentState);\n      // console.log(`Device state toggled to ${currentState}.`);\n\n      const status = await connection.getDevicePowerState(DEVICE_ID);\n      console.log(`Device new power state: ${status.state}`);\n    } else {\n      console.log(`Device with ID ${DEVICE_ID} not found.`);\n    }\n\n  } catch (error) {\n    console.error('An error occurred:', error.message);\n  }\n}\n\ncontrolDevice();","lang":"typescript","description":"Demonstrates initializing the API, logging in, finding a specific device, and toggling its power state using the recommended WebSocket method."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"The 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.","severity":"breaking","affected_versions":">=2.0.1 <3.1.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Prioritize `setWSDevicePowerState(deviceId, state)` for controlling device power states. Ensure your eWeLink account and devices support WebSocket communication.","message":"For 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.","severity":"gotcha","affected_versions":">=3.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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').","cause":"Incorrect email, phone number, password, or an invalid region provided during `EwelinkApi` class initialization.","error":"Error: Account authentication failed. Please check your login credentials and region."},{"fix":"Change your import statement to `import EwelinkApi from 'ewelink-api';` for ES Modules or `const EwelinkApi = require('ewelink-api');` for CommonJS.","cause":"Attempting to import `EwelinkApi` as a named export (`import { EwelinkApi } from 'ewelink-api';`) when it is exported as a default.","error":"TypeError: EwelinkApi is not a constructor"},{"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.","cause":"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).","error":"Error: Device not found or unreachable."}],"ecosystem":"npm"}