Homey Web API Client

Common errors

• Error: Cannot find module 'homey-api/lib/AthomCloudAPI' or 'homey'

  cause Attempting to `require()` a specific internal path for `AthomCloudAPI` in an ESM context, or confusing `homey-api` with the `homey` SDK package.
  fix For ESM, use `import { AthomCloudAPI } from 'homey-api';`. Ensure you are installing `homey-api` for external clients, not the `homey` SDK package.

• TypeError: HomeyAPI.createLocalAPI is not a function

  cause Attempting to call a static method on a wrongly imported or non-existent `HomeyAPI` object, or importing `HomeyAPI` as a default import.
  fix Ensure `HomeyAPI` is imported as a named export: `import { HomeyAPI } from 'homey-api';`.

• RangeError: The value of 'options.signal' is invalid for the type AbortSignal

  cause This error can occur in older Node.js environments when `fetch` or `AbortController` implementations are not fully compatible or if polyfills are missing, which might interact with the library's internal HTTP client.
  fix Ensure your Node.js environment meets the `>=24` requirement. If still problematic, investigate potential polyfill conflicts or environment-specific issues with `fetch` and `AbortController`.

• APIError: [401] Invalid Token

  cause The provided personal access token is either missing, expired, or invalid for the target Homey device.
  fix Generate a new personal access token from the Homey Web App and ensure it is correctly configured as `HOMEY_TOKEN` in your environment variables. Verify the `HOMEY_ADDRESS` is correct and the Homey is online.

Warnings

• breaking The `homey-api` package requires Node.js version 24 or higher. Running with older Node.js versions will result in runtime errors.
  Fix: Upgrade your Node.js environment to version 24 or newer. Use `nvm` or your preferred Node.js version manager.
• gotcha There are two distinct Homey-related packages: `homey-api` (this client library) and `homey` (the Homey Apps SDK for developing apps that run *on* Homey). Ensure you are importing from `homey-api` when developing external clients, as `import Homey from 'homey'` is for in-app development and will lead to 'module not found' errors in external projects.
  Fix: For external applications, use `import { HomeyAPI } from 'homey-api';`. If you intend to develop a Homey app, install the `homey` package and refer to the Homey Apps SDK documentation.
• gotcha External applications require an OAuth2 Client ID and Secret obtained from the Homey Developer Tools. Users must authenticate with your application to grant API access. New API clients are limited to 100 Homey Pro users by default.
  Fix: Register your application in the Homey Developer Tools to get your OAuth2 Client ID and Secret. Implement the OAuth2 flow to obtain access tokens. Request a limit increase if you need to support more than 100 users or connect to Homey Cloud.
• deprecated The `athom-api` package has been deprecated. Developers should switch to `homey-api` for all new projects and migrate existing projects.
  Fix: Replace `athom-api` with `homey-api` in your `package.json` and update import statements. The core `HomeyAPI` and `AthomCloudAPI` classes remain available.

Install

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

Imports

• HomeyAPI
  wrong:

  const HomeyAPI = require('homey-api');

  correct:

  import { HomeyAPI } from 'homey-api';

  This is the primary class for interacting with a Homey device, typically via `createLocalAPI` or `createAppAPI`. Use named import for ESM.
• AthomCloudAPI
  wrong:

  const AthomCloudAPI = require('homey-api/lib/AthomCloudAPI');

  correct:

  import { AthomCloudAPI } from 'homey-api';

  Used for cloud-based authentication and interactions. While the README shows a CJS require from a subpath, a named import from the root is the idiomatic ESM approach for modern Node.js.
• APIError

  import { APIError } from 'homey-api';

  A utility class for handling API-specific errors, typically available as a named export.

Quickstart

Demonstrates how to connect to a local Homey Pro device using a personal access token and list all connected devices. This requires a `.env` file with `HOMEY_ADDRESS` and `HOMEY_TOKEN`.

import { HomeyAPI } from 'homey-api';
import 'dotenv/config'; // For loading environment variables

const HOMEY_ADDRESS = process.env.HOMEY_ADDRESS ?? 'http://192.168.1.100'; // e.g., 'http://192.168.1.100:80'
const HOMEY_TOKEN = process.env.HOMEY_TOKEN ?? ''; // Personal Access Token from Homey Web App

if (!HOMEY_TOKEN) {
  console.error('HOMEY_TOKEN environment variable is not set. Please create a .env file or set it directly.');
  process.exit(1);
}

async function connectAndListDevices() {
  try {
    console.log(`Attempting to connect to Homey at ${HOMEY_ADDRESS}...`);
    const homeyApi = await HomeyAPI.createLocalAPI({
      address: HOMEY_ADDRESS,
      token: HOMEY_TOKEN,
    });

    console.log('Successfully connected to Homey!');

    const devices = await homeyApi.devices.getDevices();
    console.log('--- Connected Devices ---');
    if (Object.keys(devices).length === 0) {
      console.log('No devices found.');
    } else {
      for (const deviceId in devices) {
        const device = devices[deviceId];
        console.log(`ID: ${deviceId}, Name: ${device.name}, Class: ${device.class}`);
      }
    }

    await homeyApi.disconnect();
    console.log('Disconnected from Homey.');

  } catch (error) {
    console.error('Failed to connect or retrieve devices:', error instanceof Error ? error.message : error);
    console.error('Please ensure Homey is reachable at the specified address and the token is valid.');
  }
}

connectAndListDevices();