@khalido/home
v0.2.4
Published
home.ts: small, typed home automation for TypeScript: Hue, Daikin, Enphase, Google Cast, AirPrint printers and a Spotify Soloist speaker on the local network; Amber prices, Up Bank spending and the weather from the cloud.
Maintainers
Readme
home.ts
Small, typed home automation for TypeScript, starting with the devices in my house: Philips Hue, a Daikin AC, Enphase solar, Google Cast speakers and screens, AirPrint printers and a Spotify Soloist speaker on the local network, plus Amber Electric's live prices, Up Bank spending and the weather. One small library, published as @khalido/home, and a home command. No server, no cloud of its own.
- Read every device into one typed snapshot, kept current by event stream or on a timer.
- Turn lights on, set the AC, change speaker volume. Writes are spaced and merged, so a burst never floods a device.
- Find what answers on your network, and check it read-only from the terminal.
- Combine solar, grid and price into one energy figure.
Install
bun add @khalido/home # or: npm install @khalido/homeThe library runs on Bun 1.4+ and Node 24+, and is ESM only. The home command needs Bun on your PATH; in a project that added the package, run it as bunx home.
Pointing a coding agent at it? Give it llms.txt: what to call and where each doc is. Using it from an app is the same for people.
Try it
From a clone:
bun install
bun test # runs on fixtures, no device needed
bun link # puts `home` on your PATH
home discover # what answers on this network, and which of it this package supports
home probe # read-only checks, no keys
home # each connector: connected, or what it still needs
home devices # every device, one line eachCopy .env.example to .env and fill in the connectors you have, or describe the home in a config file (example).
Use it from code
Weather needs no key or device, so this runs anywhere:
import { createHome } from "@khalido/home";
import { weather } from "@khalido/home/weather";
const home = createHome(
[weather({ latitude: -33.87, longitude: 151.21 })],
(snapshot) => console.log(snapshot),
);
home.start(new AbortController().signal); // connects, reads, keeps reading, reconnects
home.part("weather")?.state; // typed by name, read from memory, never from the deviceThe library never reads your environment or a file: you pass addresses, keys and a fetch. Under Node, Hue and Enphase take the fetches in @khalido/home/node. From a clone, run bun run build first: the package's entry points resolve to dist/. Health, change events, writes and the energy helpers are in using it from an app.
Connectors
| Connector | Reads | Writes | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | hue | lights, rooms, scenes, over the bridge's event stream | lights, rooms, scenes | | daikin | the AC, over its local API | power, mode, setpoint, fan | | enphase | solar production and consumption from the IQ Gateway | none | | cast | every Cast device and speaker group | volume, mute, stop, announcements | | printers | AirPrint printers over IPP: state, toner, paper | none | | spotify | a Spotify Soloist speaker: what is playing, volume, shuffle, over its local WebSocket | activate, play a link, pause, resume, skip, seek, volume (capped), queue, shuffle, repeat, each confirmed by what the speaker reports; turn down or pause around an announcement; a stalled stream noticed and, if asked, restarted | | amber | live import and feed-in prices | none | | up | household spending by category, what still needs one | a category or tag on a transaction | | weather | now, forecast by the hour and by part of the day, rain soon, the sun, from BOM, Open-Meteo and Google | none |
Each connector's README says what has run against a real device and what has not. This covers only the devices I own; Home Assistant is the inspiration and the reference for every protocol.
More
- Using it from an app: the wiring, each write and what it returns
- The
homecommand and the home config - Hue: Signify's guidance on certificates, pairing and write rates
- Why it is shaped this way and decisions
- To add a connector, follow AGENTS.md
- For agents: llms.txt
I use it from jaldi, a Mac launcher, and chota-bot, a family bot on a Raspberry Pi, both on Bun; the docs name both.
Licence
MIT. Each connector's README lists its sources and their licences. Two Daikin sources are GPL-3.0 and are read for facts only, never copied.
