eWeLink API Client for Node.js

Common errors

• Error: Account authentication failed. Please check your login credentials and region.

  cause 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

  cause 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.

  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).
  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.

Warnings

• breaking 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Prioritize `setWSDevicePowerState(deviceId, state)` for controlling device power states. Ensure your eWeLink account and devices support WebSocket communication.

Install

• npm install ewelink-api npm
• yarn add ewelink-api yarn
• pnpm add ewelink-api pnpm

Imports

• EwelinkApi
  wrong:

  import { EwelinkApi } from 'ewelink-api';

  correct:

  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)
  wrong:

  import EwelinkApi from 'ewelink-api';

  correct:

  const EwelinkApi = require('ewelink-api');

  For CommonJS environments (Node.js older projects), use `require` to import the default exported class.
• Device types (TypeScript)
  wrong:

  import { Device, DeviceStatus } from 'ewelink-api';

  correct:

  import type { Device, DeviceStatus } from 'ewelink-api/dist/ts/interface';

  TypeScript types are located in a separate path. Always use `import type` for type-only imports.

Quickstart

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();