{"id":16052,"library":"homey-api","title":"Homey Web API Client","description":"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.","status":"active","version":"3.18.2","language":"javascript","source_language":"en","source_url":"https://github.com/athombv/node-homey-api","tags":["javascript","typescript"],"install":[{"cmd":"npm install homey-api","lang":"bash","label":"npm"},{"cmd":"yarn add homey-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add homey-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is the primary class for interacting with a Homey device, typically via `createLocalAPI` or `createAppAPI`. Use named import for ESM.","wrong":"const HomeyAPI = require('homey-api');","symbol":"HomeyAPI","correct":"import { HomeyAPI } from 'homey-api';"},{"note":"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.","wrong":"const AthomCloudAPI = require('homey-api/lib/AthomCloudAPI');","symbol":"AthomCloudAPI","correct":"import { AthomCloudAPI } from 'homey-api';"},{"note":"A utility class for handling API-specific errors, typically available as a named export.","wrong":null,"symbol":"APIError","correct":"import { APIError } from 'homey-api';"}],"quickstart":{"code":"import { HomeyAPI } from 'homey-api';\nimport 'dotenv/config'; // For loading environment variables\n\nconst HOMEY_ADDRESS = process.env.HOMEY_ADDRESS ?? 'http://192.168.1.100'; // e.g., 'http://192.168.1.100:80'\nconst HOMEY_TOKEN = process.env.HOMEY_TOKEN ?? ''; // Personal Access Token from Homey Web App\n\nif (!HOMEY_TOKEN) {\n  console.error('HOMEY_TOKEN environment variable is not set. Please create a .env file or set it directly.');\n  process.exit(1);\n}\n\nasync function connectAndListDevices() {\n  try {\n    console.log(`Attempting to connect to Homey at ${HOMEY_ADDRESS}...`);\n    const homeyApi = await HomeyAPI.createLocalAPI({\n      address: HOMEY_ADDRESS,\n      token: HOMEY_TOKEN,\n    });\n\n    console.log('Successfully connected to Homey!');\n\n    const devices = await homeyApi.devices.getDevices();\n    console.log('--- Connected Devices ---');\n    if (Object.keys(devices).length === 0) {\n      console.log('No devices found.');\n    } else {\n      for (const deviceId in devices) {\n        const device = devices[deviceId];\n        console.log(`ID: ${deviceId}, Name: ${device.name}, Class: ${device.class}`);\n      }\n    }\n\n    await homeyApi.disconnect();\n    console.log('Disconnected from Homey.');\n\n  } catch (error) {\n    console.error('Failed to connect or retrieve devices:', error instanceof Error ? error.message : error);\n    console.error('Please ensure Homey is reachable at the specified address and the token is valid.');\n  }\n}\n\nconnectAndListDevices();\n","lang":"typescript","description":"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`."},"warnings":[{"fix":"Upgrade your Node.js environment to version 24 or newer. Use `nvm` or your preferred Node.js version manager.","message":"The `homey-api` package requires Node.js version 24 or higher. Running with older Node.js versions will result in runtime errors.","severity":"breaking","affected_versions":"<3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Replace `athom-api` with `homey-api` in your `package.json` and update import statements. The core `HomeyAPI` and `AthomCloudAPI` classes remain available.","message":"The `athom-api` package has been deprecated. Developers should switch to `homey-api` for all new projects and migrate existing projects.","severity":"deprecated","affected_versions":"<3.x"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"For ESM, use `import { AthomCloudAPI } from 'homey-api';`. Ensure you are installing `homey-api` for external clients, not the `homey` SDK package.","cause":"Attempting to `require()` a specific internal path for `AthomCloudAPI` in an ESM context, or confusing `homey-api` with the `homey` SDK package.","error":"Error: Cannot find module 'homey-api/lib/AthomCloudAPI' or 'homey'"},{"fix":"Ensure `HomeyAPI` is imported as a named export: `import { HomeyAPI } from 'homey-api';`.","cause":"Attempting to call a static method on a wrongly imported or non-existent `HomeyAPI` object, or importing `HomeyAPI` as a default import.","error":"TypeError: HomeyAPI.createLocalAPI is not a function"},{"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`.","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.","error":"RangeError: The value of 'options.signal' is invalid for the type AbortSignal"},{"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.","cause":"The provided personal access token is either missing, expired, or invalid for the target Homey device.","error":"APIError: [401] Invalid Token"}],"ecosystem":"npm"}