Registry / http-networking / homey-api

homey-api

JSON →
library3.18.2jsnpmunverified

homey-api is the official JavaScript client for Athom's Homey Web APIs, providing programmatic access to Homey Pro and Homey Cloud devices. It is actively maintained with the current stable version being 3.18.2, and new releases typically coincide with API updates or bug fixes. The library supports various JavaScript environments including Node.js (requiring Node.js >=24), browsers (via CDN or bundlers), and React Native, as well as specialized in-app usage for Homey Pro. Key differentiators include its official status, comprehensive TypeScript type definitions, and direct support for both local network (Homey Pro) and cloud-based (Homey Cloud) API interactions. Developers must obtain OAuth2 client credentials from Athom to interact with the Web API.

npm install homey-api
INSTALL
IMPORT
SIG · HOMEY-API
H
homey-api
http-networkingjavascriptv3.18.2
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.

HomeyAPI
import { HomeyAPI } from 'homey-api';
const HomeyAPI = require('homey-api');
This is the primary class for interacting with a Homey device, typically via `createLocalAPI` or `createAppAPI`. Use named import for ESM.
AthomCloudAPI
import { AthomCloudAPI } from 'homey-api';
const AthomCloudAPI = require('homey-api/lib/AthomCloudAPI');
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.

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();
Debug
Known issues
breakingThe `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.
affects: <3.0.0
gotchaThere 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.
affects: >=1.0.0
gotchaExternal 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.
affects: >=1.0.0
deprecatedThe `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.
affects: <3.x
Errors
Common errors & fixes
Error: Cannot find module 'homey-api/lib/AthomCloudAPI' or 'homey'
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
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
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
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.
Upgrade
Version history
3.18.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
17 hits · last 30 days
node
16
OpenAI (training)
1
Resources