@khalido/home 0.0.0-stage → 0.1.0

package/.env.example

@@ -0,0 +1,25 @@
+# Names the `home` CLI, the live tests and the bench read. Dummy values; copy to .env (gitignored)
+# or export them in your shell. The library never reads these: callers pass everything in. Written by `bun run gen`
+# from each connector's manifest (src/connectors/*/index.ts); edit those, not this file.
+HUE_BRIDGE_HOST=hue-bridge.local      # optional: found by mDNS (dns-sd) when unset
+HUE_BRIDGE_ID=0017880000000000        # optional: the certificate's CN must match it; mDNS finds it when unset
+HUE_APPLICATION_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx # from `home pair`
+HUE_CA_FILE=/path/to/hue-root-ca.pem  # until HUE_BRIDGE_ROOT_CA ships in src/connectors/hue/
+DAIKIN_HOST=192.0.2.20                # the unit's address; `home probe` finds it by UDP broadcast
+IQ_GATEWAY_HOST=envoy.local           # the IQ Gateway on the LAN (a scheme is tolerated)
+IQ_GATEWAY_SERIAL_NUMBER=000000000000 # optional: for `home enphase login`; from the Enphase app: System > Devices > Gateway
+ENPHASE_USERNAME=you@example.com      # optional: for `home enphase login`, once a year: the Enphase account
+ENPHASE_PASSWORD=xxxxxxxx             # optional: for `home enphase login`; never stored, only sent to Enphase's login service
+AMBER_KEY=psk_xxxxxxxx                # Amber Electric API key (app.amber.com.au/developers)
+AMBER_SITE_ID=                        # optional: the first active site is used when unset
+UP_TOKEN=up:yeah:xxxxxxxx             # Up personal access token (api.up.com.au/getting_started)
+UP_ACCOUNT=JOINT TRANSACTIONAL        # optional: which accounts count, by ownership and type; every account when unset
+UP_HOUSEHOLD=home tag:home            # optional: what counts as the household's: Up category ids and tag:labels; everything when unset
+HOME_LATITUDE=-33.8688                # the home's position for weather and the sun (this one is Sydney CBD)
+HOME_LONGITUDE=151.2093
+HOME_TIMEZONE=Australia/Sydney        # optional: the home's IANA time zone for weather times and day blocks; this machine's when unset
+HOME_BOM_FORECAST=Sydney              # optional: BOM précis location by name or aac; unset, the forecast comes from Open-Meteo
+GOOGLE_WEATHER_KEY=                   # optional: Maps Platform key with the Weather API enabled
+SOLOIST_WS=ws://127.0.0.1:9091        # Soloist's --ws address as a URL; `home status` skips the speaker without it
+SOLOIST_MAX_VOLUME=60                 # optional: the loudest `home spotify volume` sets, and where a first play above it is lowered to
+HOME_CONFIG=                          # optional: a home config (JSONC), e.g. ~/home/home.jsonc; else the names above

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to home.ts (`@khalido/home` on npm), in [Keep a Changelog](https://keepachangelog.com/) form. Versions follow [SemVer](https://semver.org) at 0.x: a minor release can break what a consumer calls, a patch can't.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-08
+
+First release. Nine connectors: 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. Each connector's README says what has run against a real device.
+
+### Added
+
+- **One snapshot, typed by name.** `createHome` runs the integrations and keeps their parts; `home.part("weather")?.state` is a `WeatherState`. `loadHome` builds them from a home config.
+- **Health.** Each part carries `lastGoodAt` and `downSince`; `health(snapshot, now)` says ok, stale or down per integration, with its thresholds. `onChange` gets what changed: `{ name, before, after }`.
+- **Writes** hang off the integration (`home.integration("daikin")?.client.write(…)`) and go through a write lane: spaced, a burst merged so the last value lands, and they follow a device that moves.
+- **Weather** by the hour and by part of the day. The parts of the day are yours to name (`blocks`), with UV per part.
+- **Energy.** `energyNow` combines solar, use and price; `bestWindow` finds the cheapest or greenest hours in Amber's forecast.
+- **Spotify.** `spotify()` reads a [Spotify Soloist](https://developer.spotify.com/documentation/soloist) speaker over its local WebSocket and plays, pauses, skips and sets the volume, held to a `maxVolume`. Each write resolves with the state once Soloist reports the change (`{ state, confirmed }`). `duck(fn, { to })` turns the music down around an announcement and `interrupt(fn)` pauses it; both put it back unless someone changed it from a phone meanwhile. `state.upNext` is what plays next, `setRepeat` sets repeat, `speakerState(part)` gives one word to switch on (offline, connecting, waiting, idle, playing, paused, buffering), and `spotifyChanges(before, after)` turns two reports into events (started, resumed, paused, stopped, track, offline, online, waiting, picked), marking the playback ones that come from the library's own `duck` or `interrupt`. It notices playback that stalls while Soloist says playing (Soloist issue #5), says so in `anomaly` and as `stalled` and `recovered` events, and with `repairStalls: true` tries once per track to restart it. The connector has only run against a fake socket; no real Soloist has answered it yet.
+- **A home config** (`home.jsonc`, checked by `home.schema.json`): each device by the identity its own discovery reports, its last address, key env names (never keys) and its room. A device that moves is found again by discovery after failed reads, and `loadHome` keeps an address book.
+- **The `home` command** (Bun): `home` for every connector's status, `home <connector>` for one, `discover`, a read-only `probe`, `config check`, `locate`, `cache`, `pair` for Hue, `enphase login`, and writes for Hue (`lights`, `room`, `scene`), Cast, Up and the Spotify speaker. `--json` on the reads.
+- **Agent skills** in `skills/`: `use-home` (reading safely, connecting, the rules for writes) and `draw-home` (an SVG plan of a home and its rooms). `llms.txt` points agents at the docs.
+- **Node.** Hue and Enphase take the fetches in `@khalido/home/node`. The library runs on Bun 1.4+ and Node 24+; the `home` command needs Bun.
+
+[Unreleased]: https://github.com/khalido/home.ts/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/khalido/home.ts/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khalid Omar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# home.ts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+
+```sh
+bun add @khalido/home     # or: npm install @khalido/home
+```
+
+The library runs on Bun 1.4+ and Node 24+. The `home` command needs Bun.
+
+## Try it
+
+From a clone:
+
+```sh
+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
+```
+
+Copy [.env.example](.env.example) to `.env` and fill in the connectors you have, or describe the home in a [config file](docs/config.md) ([example](examples/home.jsonc)).
+
+## Use it from code
+
+Weather needs no key or device, so this runs anywhere:
+
+```ts
+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 device
+```
+
+The 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](docs/using.md).
+
+## Connectors
+
+| Connector                                     | Reads                                                                                                 | Writes                                                                                                                                                                                                                    |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [hue](src/connectors/hue/README.md)           | lights, rooms, scenes, over the bridge's event stream                                                 | lights, rooms, scenes                                                                                                                                                                                                     |
+| [daikin](src/connectors/daikin/README.md)     | the AC, over its local API                                                                            | power, mode, setpoint, fan                                                                                                                                                                                                |
+| [enphase](src/connectors/enphase/README.md)   | solar production and consumption from the IQ Gateway                                                  | none                                                                                                                                                                                                                      |
+| [cast](src/connectors/cast/README.md)         | every Cast device and speaker group                                                                   | volume, mute, stop, announcements                                                                                                                                                                                         |
+| [printers](src/connectors/printers/README.md) | AirPrint printers over IPP: state, toner, paper                                                       | none                                                                                                                                                                                                                      |
+| [spotify](src/connectors/spotify/README.md)   | a Spotify Soloist speaker: what is playing, volume, shuffle, over its local WebSocket                 | 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](src/connectors/amber/README.md)       | live import and feed-in prices                                                                        | none                                                                                                                                                                                                                      |
+| [up](src/connectors/up/README.md)             | household spending by category, what still needs one                                                  | a category or tag on a transaction                                                                                                                                                                                        |
+| [weather](src/connectors/weather/README.md)   | 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](https://www.home-assistant.io/) is the inspiration and the reference for every protocol.
+
+## More
+
+- [The `home` command](docs/cli.md) and [the home config](docs/config.md)
+- [Why it is shaped this way](docs/philosophy.md) and [decisions](docs/decisions.md)
+- To add a connector, follow [AGENTS.md](AGENTS.md)
+- For agents: [llms.txt](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.

package/dist/clock.d.ts

@@ -0,0 +1,17 @@
+/** Time as a parameter, so queues and backoff run in tests without waiting. */
+export type Clock = {
+    now(): number;
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+};
+/** The wall clock. `sleep` resolves early when `signal` aborts. */
+export declare const realClock: Clock;
+/** The calendar day at `ms` in an IANA time zone (the runtime's when left out), as YYYY-MM-DD: where "today" starts. */
+export declare const localDay: (ms: number, timeZone?: string) => string;
+/** The hour of the day (0–23) at `ms` in an IANA time zone, the runtime's when left out. */
+export declare const localHour: (ms: number, timeZone?: string) => number;
+/** "20:15" at `ms` in an IANA time zone, the runtime's when left out. */
+export declare const localTime: (ms: number, timeZone?: string) => string;
+/** Whether a name is an IANA time zone this runtime knows. */
+export declare function isTimeZone(name: string): boolean;
+/** The clock's now as an ISO string: the `asOf` every snapshot carries. */
+export declare const asOf: (clock: Pick<Clock, "now">) => string;

package/dist/clock.js

@@ -0,0 +1,43 @@
+/** The wall clock. `sleep` resolves early when `signal` aborts. */
+export const realClock = {
+    now: () => Date.now(),
+    sleep: (ms, signal) => new Promise((resolve) => {
+        const done = () => (clearTimeout(timer),
+            signal?.removeEventListener("abort", done),
+            resolve());
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener("abort", done, { once: true });
+    }),
+};
+/** The calendar day at `ms` in an IANA time zone (the runtime's when left out), as YYYY-MM-DD: where "today" starts. */
+export const localDay = (ms, timeZone) => new Intl.DateTimeFormat("en-CA", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+}).format(ms);
+/** The hour of the day (0–23) at `ms` in an IANA time zone, the runtime's when left out. */
+export const localHour = (ms, timeZone) => Number(new Intl.DateTimeFormat("en-GB", {
+    timeZone,
+    hour: "2-digit",
+    hourCycle: "h23",
+}).format(ms));
+/** "20:15" at `ms` in an IANA time zone, the runtime's when left out. */
+export const localTime = (ms, timeZone) => new Intl.DateTimeFormat("en-GB", {
+    timeZone,
+    hour: "2-digit",
+    minute: "2-digit",
+    hourCycle: "h23",
+}).format(ms);
+/** Whether a name is an IANA time zone this runtime knows. */
+export function isTimeZone(name) {
+    try {
+        new Intl.DateTimeFormat("en", { timeZone: name });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The clock's now as an ISO string: the `asOf` every snapshot carries. */
+export const asOf = (clock) => new Date(clock.now()).toISOString();

package/dist/config.d.ts

@@ -0,0 +1,273 @@
+import { z } from "zod";
+import { type Clock } from "./clock.ts";
+import { amber } from "./connectors/amber/index.ts";
+import { daikin } from "./connectors/daikin/index.ts";
+import { cast, type CastConnect, type ServeClip } from "./connectors/cast/index.ts";
+import { enphase } from "./connectors/enphase/index.ts";
+import { type AddressCache, type Connector, type Finder } from "./discover.ts";
+import { hue } from "./connectors/hue/index.ts";
+import { printers } from "./connectors/printers/index.ts";
+import { spotify } from "./connectors/spotify/index.ts";
+import { up } from "./connectors/up/index.ts";
+import { weather } from "./connectors/weather/index.ts";
+/** Where a device or marker sits: `id` matches `<g class="room" id="…">` in the plan's SVG. */
+export declare const Room: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    floor: z.ZodOptional<z.ZodString>;
+    hueRoom: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** JSONC (comments and trailing commas) through jsonc-parser, which runs on Node too; a syntax error throws rather than parsing to part of the file. */
+export declare function parseJsonc(text: string): unknown;
+/** A device is one connector's settings; a new connector adds its `configSchema` here, in one line. */
+export declare const Device: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    connector: z.ZodLiteral<"hue">;
+    host: z.ZodString;
+    bridgeId: z.ZodString;
+    key: z.ZodString;
+    ca: z.ZodString;
+    id: z.ZodString;
+    room: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>, z.ZodObject<{
+    connector: z.ZodLiteral<"daikin">;
+    host: z.ZodString;
+    mac: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    room: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>, z.ZodObject<{
+    connector: z.ZodLiteral<"enphase">;
+    host: z.ZodString;
+    serial: z.ZodOptional<z.ZodString>;
+    token: z.ZodString;
+    marker: z.ZodOptional<z.ZodString>;
+    capacityW: z.ZodOptional<z.ZodNumber>;
+    id: z.ZodString;
+    room: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>, z.ZodObject<{
+    connector: z.ZodLiteral<"amber">;
+    key: z.ZodString;
+    siteId: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    room: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>, z.ZodObject<{
+    connector: z.ZodLiteral<"up">;
+    key: z.ZodString;
+    account: z.ZodOptional<z.ZodObject<{
+        accountType: z.ZodOptional<z.ZodEnum<{
+            HOME_LOAN: "HOME_LOAN";
+            SAVER: "SAVER";
+            TRANSACTIONAL: "TRANSACTIONAL";
+        }>>;
+        ownershipType: z.ZodOptional<z.ZodEnum<{
+            INDIVIDUAL: "INDIVIDUAL";
+            JOINT: "JOINT";
+        }>>;
+    }, z.core.$strip>>;
+    household: z.ZodOptional<z.ZodObject<{
+        categories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    id: z.ZodString;
+    room: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>, z.ZodObject<{
+    connector: z.ZodLiteral<"cast">;
+    name: z.ZodString;
+    castId: z.ZodString;
+    id: z.ZodString;
+    room: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>, z.ZodObject<{
+    connector: z.ZodLiteral<"printers">;
+    name: z.ZodString;
+    uuid: z.ZodString;
+    host: z.ZodOptional<z.ZodString>;
+    port: z.ZodOptional<z.ZodNumber>;
+    offlineDays: z.ZodOptional<z.ZodNumber>;
+    id: z.ZodString;
+    room: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>, z.ZodObject<{
+    connector: z.ZodLiteral<"spotify">;
+    url: z.ZodOptional<z.ZodURL>;
+    maxVolume: z.ZodOptional<z.ZodNumber>;
+    repairStalls: z.ZodOptional<z.ZodBoolean>;
+    id: z.ZodString;
+    room: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>], "connector">;
+export type Device = z.infer<typeof Device>;
+export declare const WEATHER_SOURCES: readonly ["bom", "open-meteo", "google"];
+export declare const HomeConfig: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    location: z.ZodOptional<z.ZodObject<{
+        latitude: z.ZodNumber;
+        longitude: z.ZodNumber;
+        bomForecast: z.ZodOptional<z.ZodString>;
+        timezone: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    weather: z.ZodOptional<z.ZodObject<{
+        sources: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            bom: "bom";
+            google: "google";
+            "open-meteo": "open-meteo";
+        }>>>;
+        pollMinutes: z.ZodOptional<z.ZodNumber>;
+        googleKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    rooms: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        floor: z.ZodOptional<z.ZodString>;
+        hueRoom: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    devices: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        connector: z.ZodLiteral<"hue">;
+        host: z.ZodString;
+        bridgeId: z.ZodString;
+        key: z.ZodString;
+        ca: z.ZodString;
+        id: z.ZodString;
+        room: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        connector: z.ZodLiteral<"daikin">;
+        host: z.ZodString;
+        mac: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        room: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        connector: z.ZodLiteral<"enphase">;
+        host: z.ZodString;
+        serial: z.ZodOptional<z.ZodString>;
+        token: z.ZodString;
+        marker: z.ZodOptional<z.ZodString>;
+        capacityW: z.ZodOptional<z.ZodNumber>;
+        id: z.ZodString;
+        room: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        connector: z.ZodLiteral<"amber">;
+        key: z.ZodString;
+        siteId: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        room: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        connector: z.ZodLiteral<"up">;
+        key: z.ZodString;
+        account: z.ZodOptional<z.ZodObject<{
+            accountType: z.ZodOptional<z.ZodEnum<{
+                HOME_LOAN: "HOME_LOAN";
+                SAVER: "SAVER";
+                TRANSACTIONAL: "TRANSACTIONAL";
+            }>>;
+            ownershipType: z.ZodOptional<z.ZodEnum<{
+                INDIVIDUAL: "INDIVIDUAL";
+                JOINT: "JOINT";
+            }>>;
+        }, z.core.$strip>>;
+        household: z.ZodOptional<z.ZodObject<{
+            categories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+        id: z.ZodString;
+        room: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        connector: z.ZodLiteral<"cast">;
+        name: z.ZodString;
+        castId: z.ZodString;
+        id: z.ZodString;
+        room: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        connector: z.ZodLiteral<"printers">;
+        name: z.ZodString;
+        uuid: z.ZodString;
+        host: z.ZodOptional<z.ZodString>;
+        port: z.ZodOptional<z.ZodNumber>;
+        offlineDays: z.ZodOptional<z.ZodNumber>;
+        id: z.ZodString;
+        room: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        connector: z.ZodLiteral<"spotify">;
+        url: z.ZodOptional<z.ZodURL>;
+        maxVolume: z.ZodOptional<z.ZodNumber>;
+        repairStalls: z.ZodOptional<z.ZodBoolean>;
+        id: z.ZodString;
+        room: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>], "connector">>>;
+    plan: z.ZodOptional<z.ZodObject<{
+        svg: z.ZodOptional<z.ZodString>;
+        json: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type HomeConfig = z.infer<typeof HomeConfig>;
+/** What a valid config would run: each integration, the device it comes from, its settings, and each secret's env name and whether it is set. */
+export type Setup = {
+    name: string;
+    from: string;
+    settings: Record<string, string | number>;
+    secrets: Record<string, "set" | "unset">;
+};
+/** A config that cannot run. `problems` names each field. */
+export declare class HomeConfigError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+/** The drawing side of a config: the schema, unique room and device ids, and every device's room present. Problems, not a throw. */
+export declare function checkPlan(input: unknown): {
+    config?: HomeConfig;
+    problems: string[];
+};
+/**
+ * Validate a parsed config against `env`: `checkPlan`, one device per connector (Cast and printers: any number), and every env name set.
+ * Returns the problems rather than throwing, and what would be set up, secrets shown only as set or unset.
+ */
+export declare function checkHome(input: unknown, env: Record<string, string | undefined>): {
+    config?: HomeConfig;
+    setup: Setup[];
+    problems: string[];
+};
+/**
+ * How `loadHome` reaches devices. `fetch` reaches Daikin, Amber, Up, printers and the weather; Hue and Enphase use `tls`,
+ * Bun's `tls` fetch option by default, `NODE_TLS` from `@khalido/home/node` under Node.
+ */
+export type LoadOptions = {
+    env: Record<string, string | undefined>;
+    /** Reads a path from the config (a CA, a token file); the caller resolves it against the config file's folder. */
+    readFile?: (path: string) => string;
+    /** For Daikin, Amber, Up, printers and the weather; the global `fetch` when left out. */
+    fetch?: typeof fetch;
+    /** Hue's pinned fetch and Enphase's unverified one: Bun's by default, `NODE_TLS` from `@khalido/home/node` under Node. */
+    tls?: {
+        hue(bridgeId: string, ca: string): typeof fetch;
+        enphase(): typeof fetch;
+    };
+    /** BOM's transport: `ftpFetch()` from `@khalido/home/weather/ftp`. Without it a listed `bom` source stops and says why. */
+    ftpFetch?: typeof fetch;
+    /** Each connector's discovery (the CLI's mDNS and UDP), used only after reads keep failing, to find a device that moved. Cast needs its finder always: it is how Cast finds every address. */
+    finders?: Partial<Record<Connector, Finder>>;
+    /** Cast's transport: `tlsConnect` from `@khalido/home/cast/tls`. Needed when the config lists a Cast device. */
+    castConnect?: CastConnect;
+    /** For Cast's `announce` with a clip of bytes: `serveClip` from `@khalido/home/cast/serve`. A URL clip needs none. */
+    castServe?: ServeClip;
+    /** Time for every integration; tests pass a fake. */
+    clock?: Clock;
+    /**
+     * Addresses kept between runs (`fileCache` from `@khalido/home/finders`, or the caller's own). A cached address newer
+     * than the config is tried first; each address that answers is written back when it changed or predates the config. Discovery stays for a miss.
+     */
+    cache?: AddressCache;
+    /** When the config was last edited (ms): a cached address older than this yields to the config's `host`. */
+    configAt?: number;
+};
+/** Any integration `loadHome` builds, typed by its name and state (and Hue's client, Cast's actions), so `createHome(loadHome(…))` is typed. */
+export type HomeIntegration = ReturnType<typeof hue> | ReturnType<typeof daikin> | ReturnType<typeof enphase> | ReturnType<typeof amber> | ReturnType<typeof up> | ReturnType<typeof cast> | ReturnType<typeof printers> | ReturnType<typeof spotify> | ReturnType<typeof weather>;
+/** Build the integrations a config describes, in its device order, weather last. Throws `HomeConfigError` naming every problem. */
+export declare function loadHome(input: unknown, options: LoadOptions): HomeIntegration[];