@khalido/home 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,9 +1,39 @@
 # 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.
+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. A release that breaks something opens with a **Breaking** heading, so a consumer on `latest` sees it first.
 
 ## [Unreleased]
 
+## [0.1.3] - 2026-11-10
+
+### Added
+
+- **`Part.reason`:** why a part is `unavailable`, for code to switch on: `auth` (a key or token was rejected or unusable, so a person must re-key), `config` (a setting or file is wrong) or `crashed` (its `run` threw). `health()` and `home --json` carry it. It can be absent. Hue, Enphase, Amber and Up set `auth` on a rejected key, and so does an Enphase token that does not parse. In `home status`, a connector that fails to build from the environment says `auth` or `config`.
+- **`homeDevices(snapshot, config?)`:** every device in one list (Amber, Up and the weather read services and list nothing), each answering the same questions (`connector`, `id`, `name`, `kind`, `available`, `reason`, `asOf`, `state`, `text`, `room`, `members`), with the connector's own typed row in `detail` and `connector` narrowing its type. Each device connector also exports its own: `hueHomeDevices`, `daikinHomeDevices`, `enphaseHomeDevices`, `castHomeDevices`, `printersHomeDevices`, `spotifyHomeDevices`. `DeviceRecord` is the common shape and `deviceRecords(part, records)` what a connector returns them through: while its part isn't connected, none is `available`.
+- **`ConnectorCode`:** the type of `ConnectorError.code`, every code the library sets, so a consumer's table of messages fails to compile when one is added.
+- **cast:** `castStatus(snapshot)` says what each device and group is doing (`idle`, `restorable`, `busy` or `offline`, with the app, title and volume), and `castFree(snapshot, targets)` gives the targets an announcement would not disturb, with the ones it `skipped` and why. For announcing only where nothing is playing.
+- **weather:** `reason` on an `unavailable` weather part (`auth` if a stopped source's key was rejected, else `config`), and `state.sources.<name>.reason` beside `stopped`, so code can see a dead Google key while another source keeps the part `connected`. A custom `WeatherSource` can return `stopReason` with `stop`.
+
+### Changed
+
+- **`ConnectorError.code`** is typed `ConnectorCode`, no longer `string`. Reading it is unchanged. Only code that builds a `ConnectorError` with a code outside that set stops compiling; chota-bot and jaldi don't.
+- **hue:** a room or zone the bridge gives no on or off for prints its name alone in `home hue`, no longer "off".
+- **weather:** Google's key is sent in the `X-Goog-Api-Key` header, no longer in the URL.
+- **weather:** Google's stop text says which it was: `google: the key was rejected (HTTP 400 API_KEY_INVALID)` or `google: the request was refused (HTTP 400); check the latitude and longitude`. Before, both read `google: key rejected or request refused (HTTP 400)`.
+
+### Fixed
+
+- **cast:** `announce` to a group with a `volume` left the group's own level at the announcement's, though every member's was put back. The group's is now restored too, before its members', so theirs land last.
+- **spotify:** `interrupt` paused the music when the account was playing on another speaker (the box reports `playing` while not the active device). It now leaves it alone and returns `music: "untouched"`, as `duck` does.
+- **spotify:** `maxVolume` gave up when a lowering was refused or unanswered after a second start signal (buffering, then playing) had opened a new window, leaving the volume above the cap. The new window now lowers again.
+- **`createHome`:** an `onChange` that throws or rejects no longer marks the integration `unavailable`; the error goes to `console.error` and the integration keeps running.
+- **`createHome`:** `refresh()` before `start()` resolves at once instead of never.
+- **`createHome`:** an integration whose `run` fails after a good report keeps its last `state`.
+- **`createHome`:** a `run` that throws synchronously marks that integration `unavailable`; the others still start.
+- **`home <connector> --config`** needs only that connector's keys, and runs only that connector.
+- **`realClock.sleep`** resolves at once on an already-aborted signal.
+- **Docs:** the `readFile` in `docs/config.md` expands `~/`, which `home discover --write` puts in Enphase's `token`. The README says the package is ESM only.
+
 ## [0.1.2] - 2026-11-09
 
 From chota-bot's live writes on a Raspberry Pi. `setVolume` on an inactive speaker now rejects, and `track` events can come later than before.
@@ -68,7 +98,8 @@ First release. Nine connectors: Hue, Daikin, Enphase, Google Cast, AirPrint prin
 - **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.2...HEAD
+[Unreleased]: https://github.com/khalido/home.ts/compare/v0.1.3...HEAD
+[0.1.3]: https://github.com/khalido/home.ts/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/khalido/home.ts/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/khalido/home.ts/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/khalido/home.ts/releases/tag/v0.1.0

package/README.md

@@ -13,7 +13,7 @@ Small, typed home automation for TypeScript, starting with the devices in my hou
 bun add @khalido/home     # or: npm install @khalido/home
 ```
 
-The library runs on Bun 1.4+ and Node 24+. The `home` command needs Bun.
+The library runs on Bun 1.4+ and Node 24+, and is ESM only. The `home` command needs Bun.
 
 ## Try it
 

package/dist/clock.js

@@ -2,6 +2,8 @@
 export const realClock = {
     now: () => Date.now(),
     sleep: (ms, signal) => new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
         const done = () => (clearTimeout(timer),
             signal?.removeEventListener("abort", done),
             resolve());

package/dist/connector.d.ts

@@ -6,13 +6,20 @@ export declare const TIMEOUT_MS = 10000;
  * Node's fetch puts the reason there: "fetch failed: connect ECONNREFUSED 192.0.2.10:443".
  */
 export declare function errorText(error: unknown): string;
+/**
+ * Every `code` a `ConnectorError` from this library carries, so a consumer's table of messages fails to compile when one is added.
+ * The spotify connector's writes: `offline` (not connected), `waiting` (nobody signed in), `inactive` (not the active device), `refused`
+ * (the device said no), `timeout` (no answer), `invalid` (bad input, nothing sent). `link_button`: Hue wants its button
+ * pressed. `ipp`: a printer answered with an IPP error, its code in `status`.
+ */
+export type ConnectorCode = "offline" | "waiting" | "inactive" | "refused" | "timeout" | "invalid" | "link_button" | "ipp";
 /** A failed device or service call. `status` is the HTTP status (or a device's own code); `code` a connector's own reason. */
 export declare class ConnectorError extends Error {
     readonly status?: number;
-    readonly code?: string;
+    readonly code?: ConnectorCode;
     constructor(message: string, options?: {
         status?: number;
-        code?: string;
+        code?: ConnectorCode;
         cause?: unknown;
     });
 }

package/dist/connectors/amber/index.js

@@ -44,6 +44,7 @@ export function amber(config) {
                     if (error instanceof AmberError && error.status === 401)
                         return update({
                             status: "unavailable",
+                            reason: "auth",
                             detail: "Amber rejected the key",
                             state: last,
                         });

package/dist/connectors/cast/index.d.ts

@@ -1,14 +1,14 @@
 import { z } from "zod";
 import { type Clock } from "../../clock.ts";
 import { type Found } from "../../discover.ts";
-import type { Integration } from "../../home.ts";
+import { type DeviceRecord, type Integration, type Part } from "../../home.ts";
 import type { Manifest } from "../../manifest.ts";
 import { type CastConnect } from "./codec.ts";
-import { type CastDevice, type CastSnapshot, type Resolved } from "./state.ts";
+import { type CastDevice, type CastSnapshot, type Resolved, type CastForm, type CastStatus } from "./state.ts";
 import { type CastActions, type ServeClip } from "./writes.ts";
 export type { CastConnect } from "./codec.ts";
-export { castForm } from "./state.ts";
-export type { CastDevice, CastForm, CastSnapshot, Resolved } from "./state.ts";
+export { castDevices, castForm, castFree, castStatus } from "./state.ts";
+export type { CastDevice, CastForm, CastSkipped, CastSnapshot, CastStatus, Resolved, } from "./state.ts";
 export type { AnnounceResult, CastActions, CastClip, ServeClip, } from "./writes.ts";
 /** A Cast device or speaker group in a home config. No host: a group's moves with its leader, so every address comes from discovery. */
 export declare const configSchema: z.ZodObject<{
@@ -58,6 +58,8 @@ export type CastConfig = {
 export declare function cast(config: CastConfig): Integration<CastSnapshot, "cast"> & CastActions;
 /** One Cast device or group in a few words: "Nest Hub: idle · 47%", "Group: idle · 43% · 3 members: A, B, C, led by A". */
 export declare function castText(d: CastDevice, s: CastSnapshot): string;
-/** Devices first, then groups, each by name. */
-export declare const castDevices: (s: CastSnapshot) => CastDevice[];
+/** A Cast device or group as a home device: `kind` is its form (`cast` for a model it doesn't know) or `group`; `detail` its `CastStatus`. */
+export type CastHomeDevice = DeviceRecord<"cast", CastForm | "cast" | "group", CastStatus["state"], CastStatus>;
+/** Every Cast device and group as a home device, devices first, each by name. */
+export declare function castHomeDevices(part: Part<CastSnapshot> | undefined): CastHomeDevice[];
 export declare const manifest: Manifest<CastSnapshot>;

package/dist/connectors/cast/index.js

@@ -3,11 +3,12 @@ import { asOf, realClock } from "../../clock.js";
 import { errorText } from "../../connector.js";
 import { HOUR, lostDetail, rescanDelay } from "../../discover.js";
 import { poller } from "../../poll.js";
+import { deviceRecords, } from "../../home.js";
 import { NS } from "./codec.js";
 import { CastPayload, KNOWN_TYPES } from "./schemas.js";
-import { castKey, connection, found, mediaApp, reduce, } from "./state.js";
+import { castKey, connection, found, mediaApp, reduce, castDevices, castStatus, } from "./state.js";
 import { castActions, } from "./writes.js";
-export { castForm } from "./state.js";
+export { castDevices, castForm, castFree, castStatus } from "./state.js";
 /** A Cast device or speaker group in a home config. No host: a group's moves with its leader, so every address comes from discovery. */
 export const configSchema = z.looseObject({
     connector: z.literal("cast"),
@@ -411,8 +412,33 @@ export function castText(d, s) {
     ];
     return `${d.name}: ${parts.filter(Boolean).join(" · ")}`;
 }
-/** Devices first, then groups, each by name. */
-export const castDevices = (s) => Object.values(s.devices).sort((a, b) => a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name));
+/** Every Cast device and group as a home device, devices first, each by name. */
+export function castHomeDevices(part) {
+    const s = part?.state;
+    if (!s)
+        return [];
+    return deviceRecords(part, castStatus(s).map((detail) => {
+        const d = s.devices[detail.id];
+        // Connected and heard from: available. Connecting, or connected with no status yet: not known.
+        const available = d.status === "disconnected"
+            ? false
+            : d.status === "connected" && detail.state !== "offline"
+                ? true
+                : undefined;
+        return {
+            connector: "cast",
+            id: d.id,
+            name: d.name,
+            kind: d.kind === "group" ? "group" : (d.form ?? "cast"),
+            ...(available === undefined ? {} : { available }),
+            ...(d.asOf ? { asOf: d.asOf } : {}), // never answered: no time to give
+            state: detail.state,
+            text: castText(d, s),
+            ...(d.members ? { members: d.members } : {}),
+            detail,
+        };
+    }));
+}
 /** How many entries have an address, and one line per device and group. */
 const castView = (s) => ({
     found: Object.values(s.devices).filter((d) => d.host).length,

package/dist/connectors/cast/state.d.ts

@@ -64,3 +64,55 @@ export declare const mediaApp: (app?: {
     }[];
     transportId?: string;
 }) => boolean;
+/** Google's own player for a URL of audio or video: what `announce` plays a clip with, and can put back. */
+export declare const DEFAULT_MEDIA_RECEIVER = "CC1AD845";
+/** Devices first, then groups, each by name. */
+export declare const castDevices: (s: CastSnapshot) => CastDevice[];
+/** A target is a castId, else a name in any case. `announce` and `castFree` find it the same way. */
+export declare const findCast: (devices: Record<string, CastDevice>, target: string) => CastDevice | undefined;
+/**
+ * What a device or group is doing, for a caller choosing where to play something. `state`:
+ * - `idle`: no app, or the idle screen.
+ * - `restorable`: the Default Media Receiver, whose clip `announce` puts back at its position.
+ * - `busy`: another app, playing or paused. An announce ends it and nothing here can resume it.
+ * - `offline`: not connected, or connected and not heard from yet.
+ * A member playing its group's media takes the group's state, with `via` naming the group and `app` the group's. A group
+ * is as free as its least free connected member. `standby` is a TV that is off or on another input: `idle` by its app,
+ * but a clip may wake it.
+ */
+export type CastStatus = {
+    id: string;
+    name: string;
+    kind: "device" | "group";
+    state: "idle" | "restorable" | "busy" | "offline";
+    app?: string;
+    playerState?: string;
+    title?: string;
+    artist?: string;
+    via?: string;
+    volume?: number;
+    muted?: boolean;
+    standby?: boolean;
+    members?: CastStatus[];
+};
+/** Every device and group in the snapshot as a `CastStatus`, devices first, each by name. */
+export declare function castStatus(s: CastSnapshot): CastStatus[];
+/** A target `castFree` left out: `standby` is a TV that is off, which a clip may wake. */
+export type CastSkipped = {
+    name: string;
+    why: "busy" | "offline" | "standby" | "unknown";
+    app?: string;
+};
+/**
+ * Of these targets (names in any case, or ids), the ones an announcement would not disturb: `idle` or `restorable`, and
+ * not a TV in standby. `free` is names, for `announceAll`; `skipped` says which were left out and why.
+ * - A group stays a group while every connected member is free. An offline member doesn't split it: the group plays without it.
+ * - A group playing another app is skipped whole. Otherwise a group with a busy member, or one whose own socket is down,
+ *   becomes its free members, named one by one (they then play out of step with each other).
+ * - A device is never named beside a free group that holds it, nor two groups that share a member: the second becomes its
+ *   members not yet covered.
+ */
+export declare function castFree(s: CastSnapshot, targets: string[]): {
+    free: string[];
+    skipped: CastSkipped[];
+};

package/dist/connectors/cast/state.js

@@ -143,3 +143,125 @@ function link(s) {
             delete d.playingVia;
     return { devices, asOf: s.asOf };
 }
+/** Google's own player for a URL of audio or video: what `announce` plays a clip with, and can put back. */
+export const DEFAULT_MEDIA_RECEIVER = "CC1AD845";
+/** Devices first, then groups, each by name. */
+export const castDevices = (s) => Object.values(s.devices).sort((a, b) => a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name));
+/** A target is a castId, else a name in any case. `announce` and `castFree` find it the same way. */
+export const findCast = (devices, target) => {
+    const all = Object.values(devices);
+    return (all.find((x) => x.id === castKey(target)) ??
+        all.find((x) => x.name.toLowerCase() === target.toLowerCase()));
+};
+const RANK = { idle: 0, restorable: 1, busy: 2, offline: 3 };
+/** By its own app alone: not its group's media, not its members. */
+const ownState = (d) => d.status !== "connected" || d.idle === undefined
+    ? "offline"
+    : d.idle
+        ? "idle"
+        : d.appId === DEFAULT_MEDIA_RECEIVER
+            ? "restorable"
+            : "busy";
+/** Every device and group in the snapshot as a `CastStatus`, devices first, each by name. */
+export function castStatus(s) {
+    const one = (d) => {
+        const group = d.playingVia ? s.devices[d.playingVia] : undefined;
+        const own = ownState(d);
+        // Its group's media is playing on it: the group's app decides, and an unknown one counts as busy.
+        const self = own === "offline" || !d.playingVia
+            ? own
+            : group && ownState(group) === "restorable"
+                ? "restorable"
+                : "busy";
+        const members = d.kind === "group"
+            ? (d.members ?? []).flatMap((id) => s.devices[id] ? [one(s.devices[id])] : [])
+            : undefined;
+        const state = self === "offline"
+            ? self
+            : (members ?? [])
+                .map((m) => m.state)
+                .filter((m) => m !== "offline")
+                .reduce((a, b) => (RANK[b] > RANK[a] ? b : a), self);
+        const status = {
+            id: d.id,
+            name: d.name,
+            kind: d.kind,
+            state,
+            app: d.idle === false
+                ? d.app
+                : group?.idle === false
+                    ? group.app
+                    : undefined,
+            playerState: d.playerState,
+            title: d.title,
+            artist: d.artist,
+            via: d.playingVia && (group?.name ?? d.playingVia),
+            volume: d.volume,
+            muted: d.muted,
+            standby: d.standby,
+            members,
+        };
+        for (const k of Object.keys(status))
+            if (status[k] === undefined)
+                delete status[k];
+        return status;
+    };
+    return castDevices(s).map(one);
+}
+/**
+ * Of these targets (names in any case, or ids), the ones an announcement would not disturb: `idle` or `restorable`, and
+ * not a TV in standby. `free` is names, for `announceAll`; `skipped` says which were left out and why.
+ * - A group stays a group while every connected member is free. An offline member doesn't split it: the group plays without it.
+ * - A group playing another app is skipped whole. Otherwise a group with a busy member, or one whose own socket is down,
+ *   becomes its free members, named one by one (they then play out of step with each other).
+ * - A device is never named beside a free group that holds it, nor two groups that share a member: the second becomes its
+ *   members not yet covered.
+ */
+export function castFree(s, targets) {
+    const status = new Map(castStatus(s).map((c) => [c.id, c]));
+    const free = new Map();
+    const covered = new Set(); // members of the groups in `free`
+    const skipped = new Map();
+    const ok = (c) => (c.state === "idle" || c.state === "restorable") && !c.standby;
+    const skip = (c) => skipped.set(c.id, {
+        name: c.name,
+        why: c.state === "offline"
+            ? "offline"
+            : c.standby && c.state !== "busy"
+                ? "standby"
+                : "busy",
+        ...(c.app ? { app: c.app } : {}),
+    });
+    const device = (c) => (ok(c) ? free.set(c.id, c) : skip(c));
+    for (const target of targets) {
+        const d = findCast(s.devices, target);
+        const c = d && status.get(d.id);
+        if (!d || !c)
+            skipped.set(target, { name: target, why: "unknown" });
+        else if (c.kind === "device")
+            device(c);
+        else {
+            const members = c.members ?? [];
+            const own = ownState(d);
+            const up = members.filter((m) => m.state !== "offline");
+            if (own === "busy" || (own === "offline" && !members.length))
+                skip(c);
+            else if (own !== "offline" &&
+                up.every(ok) &&
+                !members.some((m) => covered.has(m.id))) {
+                free.set(c.id, c);
+                for (const m of members)
+                    covered.add(m.id);
+            }
+            else
+                for (const m of members)
+                    device(m);
+        }
+    }
+    return {
+        free: [...free.values()]
+            .filter((c) => c.kind === "group" || !covered.has(c.id))
+            .map((c) => c.name),
+        skipped: [...skipped.values()],
+    };
+}

package/dist/connectors/cast/writes.d.ts

@@ -1,7 +1,5 @@
 import type { Clock } from "../../clock.ts";
 import { type CastDevice } from "./state.ts";
-/** Google's own player for a URL of audio or video. */
-export declare const DEFAULT_MEDIA_RECEIVER = "CC1AD845";
 /** Each request (a status, a volume, LAUNCH, LOAD, STOP) gets this long to answer. */
 export declare const ANSWER_MS = 10000;
 /** How long an announcement waits for its clip to finish, beyond the clip's own length when the device reports it. */

package/dist/connectors/cast/writes.js

@@ -2,11 +2,9 @@ import { errorText } from "../../connector.js";
 import { writeLane } from "../../lane.js";
 import { NS } from "./codec.js";
 import { MediaStatus, MultizoneStatus, ReceiverStatus, } from "./schemas.js";
-import { castKey } from "./state.js";
+import { castKey, DEFAULT_MEDIA_RECEIVER, findCast, } from "./state.js";
 // Writes over the sockets `cast()` already holds: volume, mute, stop, and an announcement that plays a clip and puts
-// the device back as it was. Never called by the integration itself; tried on a scripted fake socket, not yet live.
-/** Google's own player for a URL of audio or video. */
-export const DEFAULT_MEDIA_RECEIVER = "CC1AD845";
+// the device back as it was. Never called by the integration itself; announce, volume and mute have run on real devices (the README has the dates).
 /** Each request (a status, a volume, LAUNCH, LOAD, STOP) gets this long to answer. */
 export const ANSWER_MS = 10_000;
 /** How long an announcement waits for its clip to finish, beyond the clip's own length when the device reports it. */
@@ -83,8 +81,7 @@ export function castActions(ctx) {
     const { clock } = ctx;
     const find = (target) => {
         const all = Object.values(ctx.devices());
-        const d = all.find((x) => x.id === castKey(target)) ??
-            all.find((x) => x.name.toLowerCase() === target.toLowerCase());
+        const d = findCast(ctx.devices(), target);
         if (!d)
             throw new Error(`no Cast device or group "${target}"; have: ${all
                 .map((x) => x.name)
@@ -244,7 +241,7 @@ export function castActions(ctx) {
         /**
          * Read the target's state, set the volume if asked and unmute a muted target, launch the Default Media Receiver, play the clip to its end, then
          * put back what it can, always: what the Default Media Receiver was playing is loaded again where it was, an idle
-         * device gets STOP, then the volume (a group's, member by member through each member's own socket). Another app
+         * device gets STOP, then the volume (a group's own first, then member by member through each member's own socket). Another app
          * (Spotify, YouTube) is interrupted and cannot be resumed from here; the result says so. Throws only before anything changed.
          */
         async announce(target, clip, options = {}) {
@@ -360,6 +357,27 @@ export function castActions(ctx) {
                             muted: before.volume?.muted,
                         },
                     ];
+                // A group keeps a level of its own, which its members' levels don't bring back (live, 2026-11-10: it stayed at the
+                // announcement's 30 with every member restored). First, so whatever it does to the members, their own levels land last.
+                if (d.kind === "group" && options.volume !== undefined) {
+                    const level = before.volume?.level;
+                    if (level === undefined)
+                        result.notRestored.push({
+                            name: d.name,
+                            why: "its volume before was not reported",
+                        });
+                    else
+                        try {
+                            await receiver(s, { type: "SET_VOLUME", volume: { level } });
+                            result.restored.push(`${d.name}: volume`);
+                        }
+                        catch (error) {
+                            result.notRestored.push({
+                                name: d.name,
+                                why: `volume not restored: ${errorText(error)}`,
+                            });
+                        }
+                }
                 for (const m of each) {
                     const ms = m.id === d.id ? s : ctx.session(m.id);
                     if (m.level === undefined)

package/dist/connectors/daikin/index.d.ts

@@ -1,9 +1,9 @@
 import { type Clock } from "../../clock.ts";
 import { z } from "zod";
-import type { Integration } from "../../home.ts";
+import { type DeviceRecord, type Integration, type Part } from "../../home.ts";
 import { type Finder } from "../../discover.ts";
 import type { Manifest } from "../../manifest.ts";
-import { daikinClient, type DaikinState } from "./client.ts";
+import { daikinClient, type DaikinState, type Mode } from "./client.ts";
 export { DaikinError, type DaikinState, daikinClient, type Fan, type Mode, setFan, setMode, setPower, setTarget, type WriteRequest, } from "./client.ts";
 /** Poll every 120 s, as Home Assistant's daikin integration does (its coordinator's update_interval). */
 export declare const POLL_MS = 120000;
@@ -39,3 +39,7 @@ export declare function daikin(config: DaikinConfig): Integration<DaikinSnapshot
 /** The AC in a few words: "off · cool 25 °C · room 24 °C · outdoor unit 19.5 °C". */
 export declare function acText(s: DaikinState): string;
 export declare const manifest: Manifest<DaikinSnapshot>;
+/** The AC as a home device: `state` is `off`, its mode while on, or `on` when it hasn't said which; `detail` its snapshot. */
+export type DaikinHomeDevice = DeviceRecord<"daikin", "ac", "off" | "on" | Mode, DaikinSnapshot>;
+/** The one unit, once it has been read. It reports no name or id of its own: a home config's entry names and places it. */
+export declare function daikinHomeDevices(part: Part<DaikinSnapshot> | undefined): DaikinHomeDevice[];

package/dist/connectors/daikin/index.js

@@ -1,8 +1,9 @@
 import { asOf, realClock } from "../../clock.js";
 import { z } from "zod";
+import { deviceRecords, } from "../../home.js";
 import { lostDetail, relocator } from "../../discover.js";
 import { poller } from "../../poll.js";
-import { daikinClient, DaikinError } from "./client.js";
+import { daikinClient, DaikinError, } from "./client.js";
 export { DaikinError, daikinClient, setFan, setMode, setPower, setTarget, } from "./client.js";
 /** Poll every 120 s, as Home Assistant's daikin integration does (its coordinator's update_interval). */
 export const POLL_MS = 120_000;
@@ -106,3 +107,22 @@ export const manifest = {
     ],
     lines: ({ state }) => (state ? [acText(state)] : []),
 };
+/** The one unit, once it has been read. It reports no name or id of its own: a home config's entry names and places it. */
+export function daikinHomeDevices(part) {
+    const s = part?.state;
+    if (!s)
+        return [];
+    return deviceRecords(part, [
+        {
+            connector: "daikin",
+            id: "daikin",
+            name: manifest.title,
+            kind: "ac",
+            available: true,
+            ...(s.on === undefined ? {} : { state: s.on ? (s.mode ?? "on") : "off" }),
+            asOf: s.asOf,
+            text: `${manifest.title}: ${acText(s)}`,
+            detail: s,
+        },
+    ]);
+}

package/dist/connectors/enphase/index.d.ts

@@ -1,6 +1,6 @@
 import { type Clock } from "../../clock.ts";
 import { z } from "zod";
-import { type Integration } from "../../home.ts";
+import { type DeviceRecord, type Integration, type Part } from "../../home.ts";
 import { type Finder } from "../../discover.ts";
 import { type Manifest } from "../../manifest.ts";
 import { type EnphaseState } from "./client.ts";
@@ -41,3 +41,7 @@ export declare function enphase(config: EnphaseConfig): Integration<EnphaseSnaps
 /** "solar 2.1 kW, using 0.6 kW · token 300 days left". The login ask near the end is the integration's, in `detail`. */
 export declare function enphaseText(s: EnphaseSnapshot): string;
 export declare const manifest: Manifest<EnphaseSnapshot>;
+/** The gateway as a home device: `state` is `producing` while the solar makes power, else `idle`; `detail` its snapshot. */
+export type EnphaseHomeDevice = DeviceRecord<"enphase", "solar", "producing" | "idle", EnphaseSnapshot>;
+/** The one gateway, once it has been read. */
+export declare function enphaseHomeDevices(part: Part<EnphaseSnapshot> | undefined): EnphaseHomeDevice[];

package/dist/connectors/enphase/index.js

@@ -1,6 +1,6 @@
 import { localDay, realClock } from "../../clock.js";
 import { z } from "zod";
-import { filePath } from "../../home.js";
+import { deviceRecords, filePath, } from "../../home.js";
 import { lostDetail, relocator } from "../../discover.js";
 import { kw } from "../../manifest.js";
 import { poller } from "../../poll.js";
@@ -51,7 +51,17 @@ export function enphase(config) {
         name: "enphase",
         refresh: () => (where.reset(), poll.nudge()),
         async run(signal, update) {
-            const expiresAt = tokenExpiry(config.token); // a bad token fails this integration only
+            let expiresAt;
+            try {
+                expiresAt = tokenExpiry(config.token); // a bad token fails this integration only
+            }
+            catch {
+                return update({
+                    status: "unavailable",
+                    reason: "auth",
+                    detail: "the token is unreadable; run `home enphase login`",
+                });
+            }
             let last;
             let day;
             let moved; // kept in `detail` so a consumer can persist the new address
@@ -106,6 +116,7 @@ export function enphase(config) {
                     if (error instanceof EnphaseError && error.status === 401)
                         return update({
                             status: "unavailable",
+                            reason: "auth",
                             detail: "the gateway rejected the token; run `home enphase login`",
                             state: last,
                         });
@@ -172,3 +183,24 @@ export const manifest = {
     files: ["token"],
     lines: ({ state }) => (state ? [enphaseText(state)] : []),
 };
+/** The one gateway, once it has been read. */
+export function enphaseHomeDevices(part) {
+    const s = part?.state;
+    if (!s)
+        return [];
+    return deviceRecords(part, [
+        {
+            connector: "enphase",
+            id: "enphase",
+            name: manifest.title,
+            kind: "solar",
+            available: true,
+            ...(s.productionW === undefined
+                ? {}
+                : { state: s.productionW > 0 ? "producing" : "idle" }),
+            asOf: s.asOf,
+            text: `${manifest.title}: ${enphaseText(s)}`,
+            detail: s,
+        },
+    ]);
+}

package/dist/connectors/hue/index.d.ts

@@ -1,10 +1,10 @@
 import { type Clock } from "../../clock.ts";
 import { z } from "zod";
 import { type Finder } from "../../discover.ts";
-import { type Integration } from "../../home.ts";
+import { type DeviceRecord, type Integration, type Part } from "../../home.ts";
 import type { Manifest } from "../../manifest.ts";
 import { type HueClient } from "./client.ts";
-import { type HueSnapshot } from "./state.ts";
+import { type GroupView, type HueSnapshot, type LightView } from "./state.ts";
 export { bunPinnedFetch, type HueClient, HueError, type HueOptions, hueClient, pair, } from "./client.ts";
 export type { HueEvent, Resource } from "./schemas.ts";
 export { type GroupView, groups, type HueSnapshot, homeGroupedLightId, type LightView, lights, scenes, } from "./state.ts";
@@ -39,4 +39,8 @@ export type HueConfig = {
 export declare function hue(config: HueConfig): Integration<HueSnapshot, "hue"> & {
     readonly client: HueClient;
 };
+/** A Hue light, or a room or zone, as a home device: `detail` is its `LightView` or `GroupView`. */
+export type HueHomeDevice = DeviceRecord<"hue", "light", "on" | "off", LightView> | DeviceRecord<"hue", "group", "on" | "off", GroupView>;
+/** Every light, then every room and zone. A light's `available` is its Zigbee link; a group's `members` are its lights. */
+export declare function hueHomeDevices(part: Part<HueSnapshot> | undefined): HueHomeDevice[];
 export declare const manifest: Manifest<HueSnapshot>;