@khalido/home 0.1.2 → 0.1.3

package/dist/connectors/hue/index.js

@@ -2,7 +2,7 @@ import { asOf, realClock } from "../../clock.js";
 import { errorText } from "../../connector.js";
 import { z } from "zod";
 import { lostDetail, relocator } from "../../discover.js";
-import { envName, filePath, } from "../../home.js";
+import { envName, filePath, deviceRecords, } from "../../home.js";
 import { bunPinnedFetch, hueClient } from "./client.js";
 import { hueEvents, isRejectedKey } from "./events.js";
 import { groups, lights, reduce, snapshotFrom, } from "./state.js";
@@ -137,6 +137,7 @@ export function hue(config) {
                     if (isRejectedKey(error))
                         return update({
                             status: "unavailable",
+                            reason: "auth",
                             detail: "the bridge rejected the key; pair again",
                             state: snapshot,
                         });
@@ -161,6 +162,41 @@ const view = (s) => ({
         brightness,
     })),
 });
+/** "Kitchen: on · 40%", "Kitchen: off", or the name alone when the bridge hasn't said. */
+const onText = (v) => `${v.name ?? v.id}${v.on === undefined ? "" : `: ${v.on ? `on${v.brightness === undefined ? "" : ` · ${Math.round(v.brightness)}%`}` : "off"}`}`;
+/** Every light, then every room and zone. A light's `available` is its Zigbee link; a group's `members` are its lights. */
+export function hueHomeDevices(part) {
+    const s = part?.state;
+    if (!s)
+        return [];
+    const on = (v) => v.on === undefined
+        ? {}
+        : { state: v.on ? "on" : "off" };
+    return deviceRecords(part, [
+        ...lights(s).map((l) => ({
+            connector: "hue",
+            id: l.id,
+            name: l.name ?? l.id,
+            kind: "light",
+            ...(l.reachable === undefined ? {} : { available: l.reachable }),
+            ...on(l),
+            asOf: s.asOf,
+            text: onText(l),
+            detail: l,
+        })),
+        ...groups(s).map((g) => ({
+            connector: "hue",
+            id: g.id,
+            name: g.name ?? g.id,
+            kind: "group",
+            ...on(g),
+            asOf: s.asOf,
+            text: onText(g),
+            members: g.lightIds,
+            detail: g,
+        })),
+    ]);
+}
 export const manifest = {
     name: "hue",
     title: "Philips Hue",
@@ -195,11 +231,8 @@ export const manifest = {
     lines({ state }) {
         if (!state)
             return [];
-        const { lightsOn, rooms } = view(state);
-        return [
-            `${lightsOn} lights on`,
-            ...rooms.map((r) => `${r.name}: ${r.on ? `on${r.brightness === undefined ? "" : ` · ${Math.round(r.brightness)}%`}` : "off"}`),
-        ];
+        const { lightsOn } = view(state);
+        return [`${lightsOn} lights on`, ...groups(state).map(onText)];
     },
     record: ({ state }) => (state ? view(state) : {}),
 };

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

@@ -1,9 +1,9 @@
 import { z } from "zod";
 import { type Clock } from "../../clock.ts";
 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 Printer, type PrintersState } from "./state.ts";
+import { type Printer, type PrinterStatus, type PrintersState } from "./state.ts";
 export { type Marker, type Printer, type PrintersState, type PrinterStatus, printerText, } from "./state.ts";
 /** One printer in a home config. Everything the printer reports about itself (model, markers, state) comes live; `host` and `port` are only where it last answered. */
 export declare const configSchema: z.ZodObject<{
@@ -50,3 +50,7 @@ export declare function printers(config?: PrintersConfig): Integration<PrintersS
 /** Printers sorted by name. */
 export declare const printerList: (s: PrintersState) => Printer[];
 export declare const manifest: Manifest<PrintersState>;
+/** A printer as a home device: `state` is the printer's own (`idle`, `printing`, `stopped`, `offline`); `detail` its `Printer`. */
+export type PrinterHomeDevice = DeviceRecord<"printers", "printer", PrinterStatus, Printer>;
+/** Every printer, by name. One that has stopped answering is not `available`, and keeps its last values. */
+export declare function printersHomeDevices(part: Part<PrintersState> | undefined): PrinterHomeDevice[];

package/dist/connectors/printers/index.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { asOf, realClock } from "../../clock.js";
 import { errorText } from "../../connector.js";
 import { DAY_MS, discover, HOUR, lostDetail, rescanDelay, } from "../../discover.js";
+import { deviceRecords, } from "../../home.js";
 import { poller } from "../../poll.js";
 import { getPrinterAttributes, printerUrl } from "./client.js";
 import { attributesOf } from "./codec.js";
@@ -280,3 +281,25 @@ export const manifest = {
         ];
     },
 };
+/** Every printer, by name. One that has stopped answering is not `available`, and keeps its last values. */
+export function printersHomeDevices(part) {
+    if (!part?.state)
+        return [];
+    return deviceRecords(part, printerList(part.state).map((p) => ({
+        connector: "printers",
+        id: p.uuid,
+        name: p.name,
+        kind: "printer",
+        ...(p.state === undefined ? {} : { available: p.state !== "offline" }),
+        ...(p.state === undefined ? {} : { state: p.state }),
+        // An offline printer's values are from when it last answered, not from this check.
+        ...(p.state === "offline"
+            ? p.lastSeen === undefined
+                ? {}
+                : { asOf: p.lastSeen }
+            : { asOf: p.asOf }),
+        text: printerText(p),
+        ...(p.room ? { room: p.room } : {}),
+        detail: p,
+    })));
+}

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

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { type Clock } from "../../clock.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 SpeakerState } from "./changes.ts";
 import { type SocketFactory, type SpotifyState } from "./client.ts";
 export { positionMs, type PositionAnchor, type SocketFactory, type SocketLike, type SpotifyState, type Stall, toSpotifyUri, type Track, } from "./client.ts";
 export { type SpeakerState, speakerState, type SpotifyEvent, spotifyChanges, spotifyText, } from "./changes.ts";
@@ -92,3 +93,7 @@ export type SpotifyActions = {
  */
 export declare function spotify(config?: SpotifyConfig): Integration<SpotifyState, "spotify"> & SpotifyActions;
 export declare const manifest: Manifest<SpotifyState>;
+/** The Soloist speaker as a home device: `state` is `speakerState`'s word; `detail` its `SpotifyState`. */
+export type SpotifyHomeDevice = DeviceRecord<"spotify", "speaker", SpeakerState, SpotifyState>;
+/** The one speaker, once Soloist has said something. Its name is Soloist's `--device-name`, the one phones show. */
+export declare function spotifyHomeDevices(part: Part<SpotifyState> | undefined): SpotifyHomeDevice[];

package/dist/connectors/spotify/index.js

@@ -1,8 +1,9 @@
 import { z } from "zod";
 import { asOf, realClock } from "../../clock.js";
 import { ConnectorError, errorText } from "../../connector.js";
+import { deviceRecords, } from "../../home.js";
 import { writeLane } from "../../lane.js";
-import { spotifyText, stallText } from "./changes.js";
+import { speakerState, spotifyText, stallText, } from "./changes.js";
 import { commandFrame, fold, Frame, FRAME_TYPES, OPEN, oddities, positionMs, toSpotifyUri, } from "./client.js";
 export { positionMs, toSpotifyUri, } from "./client.js";
 export { speakerState, spotifyChanges, spotifyText, } from "./changes.js";
@@ -259,6 +260,8 @@ export function spotify(config = {}) {
             capping = false;
             if (error instanceof ConnectorError && error.code === "offline")
                 return; // the status says it
+            if (capUntil !== window)
+                return applyCap(); // a new start while it went: this failure doesn't speak for that one
             capped = true; // refused or unanswered: not again this window
             note = `lowering the volume to ${cap} failed: ${errorText(error)}`;
             publish();
@@ -563,6 +566,9 @@ export function spotify(config = {}) {
                 const no = notPlaying();
                 if (no)
                     return no;
+                // "playing" while inactive is the account playing on another speaker (live, 2026-11-10): a pause would stop that one.
+                if (inactive())
+                    return "it is not the active device, so the music playing is on another speaker";
                 track = state.track?.uri;
                 try {
                     shown = (await actions.pause()).confirmed; // a pause that never shows still runs fn: what interrupts matters more
@@ -812,3 +818,22 @@ export const manifest = {
         ? [spotifyText(state)]
         : [],
 };
+/** The one speaker, once Soloist has said something. Its name is Soloist's `--device-name`, the one phones show. */
+export function spotifyHomeDevices(part) {
+    const s = part?.state;
+    if (!s || (s.loggedIn === undefined && s.status === undefined))
+        return [];
+    return deviceRecords(part, [
+        {
+            connector: "spotify",
+            id: "spotify",
+            name: s.deviceName ?? "Soloist",
+            kind: "speaker",
+            available: true,
+            state: speakerState(part),
+            asOf: s.asOf,
+            text: spotifyText(s),
+            detail: s,
+        },
+    ]);
+}

package/dist/connectors/up/index.js

@@ -142,6 +142,7 @@ export function up(config) {
                     if (error instanceof UpError && error.status === 401)
                         return update({
                             status: "unavailable",
+                            reason: "auth",
                             detail: "Up rejected the token",
                             state: last,
                         });

package/dist/connectors/weather/bom.js

@@ -185,6 +185,7 @@ export function bom(options = {}) {
             if (!options.fetch && base.startsWith("ftp:"))
                 return {
                     stop: "bom: plain fetch cannot read ftp://; pass fetch: ftpFetch() from @khalido/home/weather/ftp",
+                    stopReason: "config",
                     nextAt: Infinity,
                 };
             if (force || at >= obsDue) {

package/dist/connectors/weather/google.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { getJson } from "../../connector.js";
+import { ConnectorError, fetchTimeout } from "../../connector.js";
 import { RAIN_INTENSITIES } from "./rain.js";
 import { sunDisagrees } from "./sun.js";
 import { HOURLY_MINUTES, iso, nextPoll, num, RAIN_HORIZON_MINUTES, USER_AGENT, } from "./source.js";
@@ -273,6 +273,28 @@ export function toRain(minutes, fetchedAt) {
  */
 export const MIN_POLL_MINUTES = 15;
 export const CURRENT_MINUTES = 30;
+/**
+ * Why Google refused: the `reason` of its error body's ErrorInfo ("API_KEY_INVALID"), since the status alone doesn't say.
+ * A bad key and a bad latitude are both HTTP 400 INVALID_ARGUMENT; only the key's carries a reason (live, 2026-11-10).
+ */
+async function refusal(res) {
+    try {
+        const body = (await res.json());
+        const reason = body.error?.details?.find((d) => d.reason)?.reason;
+        return typeof reason === "string" ? reason : undefined;
+    }
+    catch {
+        return undefined; // not JSON: the status is all there is
+    }
+}
+/** Google's refusal: the HTTP status, and `why`, the reason its error body gave. */
+class GoogleError extends ConnectorError {
+    why;
+    constructor(message, status, why) {
+        super(message, { status });
+        this.why = why;
+    }
+}
 /**
  * Google Weather as a source: modelled `now`, `forecast` (10 days available, 2 read), `sky` without radiation, and `rain` from the
  * minute forecast (Experimental at Google, so its failure is a `problem` on `rain` and never stops the other slices).
@@ -295,11 +317,20 @@ export function google(options) {
         },
         minPollMinutes: MIN_POLL_MINUTES,
         async read({ place, at, pollMinutes, force, signal, }) {
-            const q = (extra) => `key=${encodeURIComponent(options.key)}&location.latitude=${place.latitude}&location.longitude=${place.longitude}${extra}`;
-            const json = (path) => getJson(fetcher, `${base}/${path}`, {
-                init: { headers: { "user-agent": USER_AGENT } },
-                signal,
-            });
+            const q = (extra) => `location.latitude=${place.latitude}&location.longitude=${place.longitude}${extra}`;
+            // The key goes in a header, never the URL, so no error, log or proxy that shows a URL can show it (all four lookups answered 200 this way, live 2026-11-10).
+            const json = async (path) => {
+                const res = await fetchTimeout(fetcher, `${base}/${path}`, {
+                    headers: {
+                        "user-agent": USER_AGENT,
+                        "x-goog-api-key": options.key,
+                    },
+                }, { signal });
+                if (res.ok)
+                    return res.json();
+                const why = await refusal(res);
+                throw new GoogleError(`HTTP ${res.status}${why ? ` ${why}` : ""} on GET /${path.split("?")[0]}`, res.status, why);
+            };
             // Started first and never throws: a failed minute forecast must not sink the rest.
             const minutes = json(`forecast/minutes:lookup?${q("")}`).then((value) => ({ value }), (error) => ({ error: error }));
             let problem;
@@ -324,10 +355,22 @@ export function google(options) {
                 }
             }
             catch (error) {
-                const status = error.status;
-                if (status === 400 || status === 401 || status === 403)
+                // Only a GoogleError is Google's answer; a timeout or an abort is a DOMException, with fields of its own.
+                const { status, why } = error instanceof GoogleError
+                    ? error
+                    : {};
+                const said = `HTTP ${status}${why ? ` ${why}` : ""}`;
+                if (status === 401 || status === 403 || why?.startsWith("API_KEY_"))
+                    return {
+                        stop: `google: the key was rejected (${said})`,
+                        stopReason: "auth",
+                        nextAt: Infinity,
+                    };
+                // A 400 with a good key is the request itself, and here that is the location: asking again won't change it.
+                if (status === 400)
                     return {
-                        stop: `google: key rejected or request refused (HTTP ${status})`,
+                        stop: `google: the request was refused (${said}); check the latitude and longitude`,
+                        stopReason: "config",
                         nextAt: Infinity,
                     };
                 problem = `google: ${error.message}`; // the old slices stay; the minute forecast below is still used

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

@@ -1,5 +1,5 @@
 import { type Clock } from "../../clock.ts";
-import type { Integration } from "../../home.ts";
+import type { Integration, Reason } from "../../home.ts";
 import { type Manifest } from "../../manifest.ts";
 import { type BlockDef, type DayBlocks } from "./blocks.ts";
 import { type RainSoon } from "./rain.ts";
@@ -38,6 +38,7 @@ export type WeatherState = Slices & {
         read: boolean;
         problem?: string;
         stopped?: string;
+        reason?: Exclude<Reason, "crashed">;
         anomaly?: string;
     }>;
 };

package/dist/connectors/weather/index.js

@@ -66,6 +66,7 @@ export function weather(config) {
                             read: r !== undefined,
                             problem: r?.problem,
                             stopped: r?.stop,
+                            reason: r?.stop ? (r.stopReason ?? "config") : undefined,
                             anomaly: r?.anomaly,
                         },
                     ];
@@ -87,6 +88,12 @@ export function weather(config) {
                     : undefined;
                 update({
                     status,
+                    // Every source has stopped: a rejected key outranks a wrong setting, since it needs a person.
+                    reason: status !== "unavailable"
+                        ? undefined
+                        : Object.values(report).some((r) => r.reason === "auth")
+                            ? "auth"
+                            : "config",
                     detail,
                     anomaly: notes("anomaly"),
                     lastGoodAt,

package/dist/connectors/weather/source.d.ts

@@ -1,3 +1,4 @@
+import type { Reason } from "../../home.ts";
 /** Sent on every request, so each service can see who is calling rather than a runtime's default string. */
 export declare const USER_AGENT = "home (+https://github.com/khalido/home.ts)";
 export type Place = {
@@ -116,6 +117,7 @@ export type SourceReading = Slices & {
     problem?: string;
     anomaly?: string;
     stop?: string;
+    stopReason?: Exclude<Reason, "crashed">;
 };
 /**
  * A weather provider. `owns` names the slices it can fill and how old each may get (by its `at`, beyond one polling

package/dist/devices.d.ts

@@ -0,0 +1,27 @@
+import { type CastHomeDevice, castHomeDevices } from "./connectors/cast/index.ts";
+import { type DaikinHomeDevice, daikinHomeDevices } from "./connectors/daikin/index.ts";
+import { type EnphaseHomeDevice, enphaseHomeDevices } from "./connectors/enphase/index.ts";
+import { type HueHomeDevice, hueHomeDevices } from "./connectors/hue/index.ts";
+import { type PrinterHomeDevice, printersHomeDevices } from "./connectors/printers/index.ts";
+import { type SpotifyHomeDevice, spotifyHomeDevices } from "./connectors/spotify/index.ts";
+import type { HomeConfig } from "./config.ts";
+import type { Part } from "./home.ts";
+/** Any device this library reads. `connector`, then `kind` where a connector has more than one, narrows `detail` and `state`. */
+export type HomeDevice = HueHomeDevice | DaikinHomeDevice | EnphaseHomeDevice | CastHomeDevice | PrinterHomeDevice | SpotifyHomeDevice;
+/** Each connector's devices from its part, in the order `home status` lists the connectors. */
+export declare const DEVICES: {
+    hue: typeof hueHomeDevices;
+    daikin: typeof daikinHomeDevices;
+    enphase: typeof enphaseHomeDevices;
+    cast: typeof castHomeDevices;
+    printers: typeof printersHomeDevices;
+    spotify: typeof spotifyHomeDevices;
+};
+/** Connectors that read a service, not a device: nothing to list. */
+export declare const SERVICES: readonly string[];
+/**
+ * Every device in the snapshot. With the home `config`, a device takes the `room` its entry gives it, a Hue room or zone
+ * (and its lights) the room whose `hueRoom` names it (a light in a room and a zone, the room's), and a device that reports
+ * no name of its own (the Daikin, the Enphase gateway) the entry's `name`. A device's own name is never replaced.
+ */
+export declare function homeDevices(snapshot: Record<string, Part | undefined>, config?: Pick<HomeConfig, "devices" | "rooms">): HomeDevice[];

package/dist/devices.js

@@ -0,0 +1,61 @@
+import { castHomeDevices, } from "./connectors/cast/index.js";
+import { daikinHomeDevices, } from "./connectors/daikin/index.js";
+import { enphaseHomeDevices, } from "./connectors/enphase/index.js";
+import { hueHomeDevices } from "./connectors/hue/index.js";
+import { printersHomeDevices, } from "./connectors/printers/index.js";
+import { spotifyHomeDevices, } from "./connectors/spotify/index.js";
+import { IDENTITY, sameId } from "./discover.js";
+import { manifestOf } from "./manifests.js";
+/** Each connector's devices from its part, in the order `home status` lists the connectors. */
+export const DEVICES = {
+    hue: hueHomeDevices,
+    daikin: daikinHomeDevices,
+    enphase: enphaseHomeDevices,
+    cast: castHomeDevices,
+    printers: printersHomeDevices,
+    spotify: spotifyHomeDevices,
+};
+/** Connectors that read a service, not a device: nothing to list. */
+export const SERVICES = ["amber", "up", "weather"];
+/**
+ * Every device in the snapshot. With the home `config`, a device takes the `room` its entry gives it, a Hue room or zone
+ * (and its lights) the room whose `hueRoom` names it (a light in a room and a zone, the room's), and a device that reports
+ * no name of its own (the Daikin, the Enphase gateway) the entry's `name`. A device's own name is never replaced.
+ */
+export function homeDevices(snapshot, config) {
+    const all = Object.entries(DEVICES).flatMap(([name, devices]) => devices(snapshot[name]));
+    if (!config)
+        return all;
+    const entries = config.devices ?? [];
+    const hueRooms = new Map(); // a Hue group's or light's id → the config room showing it
+    for (const d of all)
+        if (d.connector === "hue" && d.kind === "group") {
+            const room = config.rooms?.find((r) => r.hueRoom !== undefined &&
+                (r.hueRoom === d.id || r.hueRoom === d.detail.groupedLightId))?.id;
+            // A light in a room and a zone takes the room's: rooms come first, and the first one stays.
+            if (room)
+                for (const id of [d.id, ...d.detail.lightIds])
+                    if (!hueRooms.has(id))
+                        hueRooms.set(id, room);
+        }
+    return all.map((d) => {
+        const mine = entries.filter((e) => e.connector === d.connector);
+        const field = IDENTITY[d.connector];
+        // One device for the connector: its entry is this device. Many: the entry whose identity is this device's id.
+        const entry = d.id === d.connector
+            ? mine[0]
+            : mine.find((e) => {
+                const id = field && e[field];
+                return typeof id === "string" && sameId(id, d.id);
+            });
+        const room = d.room ?? entry?.room ?? hueRooms.get(d.id);
+        // A device with no name of its own carries its connector's title: only then does the entry's name replace it.
+        const unnamed = d.name === manifestOf(d.connector)?.title;
+        const name = unnamed ? (entry?.name ?? d.name) : d.name;
+        // Its line opens with its name, so a new name opens the line too.
+        const text = name !== d.name && d.text.startsWith(`${d.name}: `)
+            ? name + d.text.slice(d.name.length)
+            : d.text;
+        return { ...d, name, text, ...(room ? { room } : {}) };
+    });
+}

package/dist/health.d.ts

@@ -1,4 +1,4 @@
-import type { Part, Status } from "./home.ts";
+import type { Part, Reason, Status } from "./home.ts";
 /**
  * How one integration is doing, judged by time: `ok`, `stale` (no good read for a while, last values still shown) or `down`.
  * The thresholds come with it, so a page can say "stale after 4 min". Push connectors (Hue, Cast) have no poll to be late
@@ -12,6 +12,7 @@ export type Health = {
     staleAfterMs?: number;
     downAfterMs: number;
     detail?: string;
+    reason?: Reason;
 };
 /** A polling connector is stale after this many polls with no good read: two missed, plus half of one so a slow read that ends in a timeout does not flap it, */
 export declare const STALE_POLLS = 2.5;

package/dist/health.js

@@ -22,7 +22,7 @@ function healthOf(part, now, pollSeconds) {
         (part.status !== "connected" && (age(part.downSince) ?? 0) >= downAfterMs);
     const goodAge = age(part.lastGoodAt) ?? age(part.downSince); // never good: as old as the wait for it
     const stale = staleAfterMs !== undefined && (goodAge ?? 0) >= staleAfterMs;
-    const { status, lastGoodAt, downSince, detail } = part;
+    const { status, lastGoodAt, downSince, detail, reason } = part;
     return {
         level: down ? "down" : stale ? "stale" : "ok",
         status,
@@ -31,5 +31,6 @@ function healthOf(part, now, pollSeconds) {
         staleAfterMs,
         downAfterMs,
         detail,
+        reason,
     };
 }

package/dist/home.d.ts

@@ -2,12 +2,14 @@ import { z } from "zod";
 import { type Clock } from "./clock.ts";
 /** A secret in a home config is the name of an environment variable, never the secret: a pasted key fails here. */
 export declare const envName: z.ZodString;
-/** A file a connector needs (a CA, a token), relative to the config file. The caller reads it; the library reads no files. */
+/** A file a connector needs (a CA, a token), relative to the config file or from `~/`. The caller reads it, and expands `~/`; the library reads no files. */
 export declare const filePath: z.ZodString;
 /** How an integration is doing. "unavailable" means it stopped and will not retry by itself. */
 export type Status = "connecting" | "connected" | "disconnected" | "unavailable";
+/** Why a part is `unavailable`, for code to switch on; `detail` is the text for people. `auth`: a key or token was rejected or is unusable, so a person must re-key. `config`: a setting or a file is wrong. `crashed`: its `run` threw. */
+export type Reason = "auth" | "config" | "crashed";
 /**
- * One integration's slice of the home: its status, a human detail, anything odd the device reported, and its state.
+ * One integration's slice of the home: its status, a human detail, `reason` (why it is `unavailable`, for code to switch on), anything odd the device reported, and its state.
  * `createHome` stamps the times (UTC ISO). `lastGoodAt`: its last report while connected, or the read time a connected report
  * gives when it repeats an older read (weather's 5-minute sun tick). `downSince`: when it stopped being connected (or started,
  * if it never has); none while connected. Any other time an integration sets is ignored.
@@ -15,11 +17,47 @@ export type Status = "connecting" | "connected" | "disconnected" | "unavailable"
 export type Part<S = unknown> = {
     status: Status;
     detail?: string;
+    reason?: Reason;
     anomaly?: string;
     state?: S;
     lastGoodAt?: string;
     downSince?: string;
 };
+/**
+ * The few things every device answers, whatever it is, in the same words; a connector's `<name>HomeDevices(part)` returns
+ * these and `homeDevices(snapshot)` collects them. Everything particular to its kind is in `detail`, the connector's own
+ * typed row, and `connector` (with `kind`) says which type that is. Unknown stays absent, never guessed.
+ * - `id`: the device's own stable id (a Hue light id, a castId, a printer's UUID), or the connector's name when it has one device.
+ * - `kind`: light, group, speaker, display, tv, ac, printer, solar (and `cast` for a Cast model this library doesn't know).
+ * - `available`: it answered and can be used now. When it is false, `reason` says why in one word: `offline`, or the
+ *   connector's own reason for being `unavailable` (`auth`, `config`, `crashed`).
+ * - `asOf`: when the device last reported (a push connector) or was last read (a polled one). A quiet light can be hours
+ *   old and current: `available` says whether it is.
+ * - `state`: one short word in that kind's vocabulary: on, off, idle, busy, cool, printing.
+ * - `text`: one line for people, "Kitchen: on · 60%".
+ * - `room`: a room id from the home config, when one places it.
+ * - `members`: a group's device ids.
+ */
+export type DeviceRecord<C extends string = string, K extends string = string, S extends string = string, D = unknown> = {
+    connector: C;
+    id: string;
+    name: string;
+    kind: K;
+    available?: boolean;
+    reason?: Reason | "offline";
+    asOf?: string;
+    state?: S;
+    text: string;
+    room?: string;
+    members?: string[];
+    detail: D;
+};
+/**
+ * A connector's device records from its part. While the connector isn't connected none is `available`, and each keeps its
+ * last values, as the part's state does. A device that isn't available gets its `reason`: the part's when it stopped for
+ * good, else `offline`.
+ */
+export declare const deviceRecords: <R extends DeviceRecord>(part: Part | undefined, records: R[]) => R[];
 /**
  * An integration is a folder in `src/` that exports a factory returning this.
  * `run` keeps its state current until `signal` aborts, reporting each change through `update`.
@@ -64,7 +102,7 @@ export declare function createHome<I extends Integration<any, string>>(integrati
     }> | undefined;
     /**
      * Read now: one integration by name, or every one. Results arrive through the snapshot and `onChange` as usual; the
-     * promise resolves once each target has reported (its next update, good or bad), or at once for one whose run has ended.
+     * promise resolves once each target has reported (its next update, good or bad), or at once for one that isn't running.
      */
     refresh(name?: I["name"]): Promise<void>;
     /** Run every integration until `signal` aborts. One failing marks itself unavailable; the rest carry on. */

package/dist/home.js

@@ -5,8 +5,21 @@ import { errorText } from "./connector.js";
 export const envName = z
     .string()
     .regex(/^[A-Z_][A-Z0-9_]*$/, "an environment variable name (e.g. AMBER_KEY), not the secret itself");
-/** A file a connector needs (a CA, a token), relative to the config file. The caller reads it; the library reads no files. */
+/** A file a connector needs (a CA, a token), relative to the config file or from `~/`. The caller reads it, and expands `~/`; the library reads no files. */
 export const filePath = z.string().min(1);
+/**
+ * A connector's device records from its part. While the connector isn't connected none is `available`, and each keeps its
+ * last values, as the part's state does. A device that isn't available gets its `reason`: the part's when it stopped for
+ * good, else `offline`.
+ */
+export const deviceRecords = (part, records) => {
+    const up = part?.status === "connected";
+    // A part that stopped for good without saying why is a custom integration's: `config` is the nearest true word, since it won't come back by itself.
+    const why = part?.status === "unavailable" ? (part.reason ?? "config") : "offline";
+    return records.map((r) => up && r.available !== false
+        ? r
+        : { ...r, available: false, reason: up ? "offline" : why });
+};
 /** The times `createHome` keeps on a part, from the one before it: when it was last good, and when it stopped being. */
 function stamped(part, before, now) {
     if (part.status === "connected")
@@ -29,12 +42,12 @@ export function createHome(integrations, onChange, options = {}) {
     const clock = options.clock ?? realClock;
     let snapshot = Object.fromEntries(integrations.map((i) => [i.name, { status: "connecting" }]));
     const waiting = new Map(); // refresh() callers, resolved by the integration's next report
-    const finished = new Set(); // integrations whose run has ended: a refresh of one resolves at once, nothing will report
+    const finished = new Set(integrations.map((i) => i.name)); // not running, before start or after its run ended: a refresh of one resolves at once, nothing will report
     const set = (name, reported) => {
         const before = snapshot[name];
         const part = stamped(reported, before, asOf(clock));
         snapshot = { ...snapshot, [name]: part };
-        onChange?.(snapshot, { name, before, after: part });
+        Promise.try(() => onChange?.(snapshot, { name, before, after: part })).catch((error) => console.error(`onChange threw on ${name}: ${errorText(error)}`)); // the caller's bug, thrown or async, not the device's: the integration keeps running
         const w = waiting.get(name);
         if (w) {
             waiting.delete(name);
@@ -51,7 +64,7 @@ export function createHome(integrations, onChange, options = {}) {
         integration: (name) => integrations.find((i) => i.name === name),
         /**
          * Read now: one integration by name, or every one. Results arrive through the snapshot and `onChange` as usual; the
-         * promise resolves once each target has reported (its next update, good or bad), or at once for one whose run has ended.
+         * promise resolves once each target has reported (its next update, good or bad), or at once for one that isn't running.
          */
         refresh(name) {
             const targets = name === undefined
@@ -78,9 +91,13 @@ export function createHome(integrations, onChange, options = {}) {
                     ? { ...p, downSince: p.downSince ?? now }
                     : p,
             ]));
-            await Promise.all(integrations.map((i) => i
-                .run(signal, (part) => set(i.name, part))
-                .catch((error) => set(i.name, { status: "unavailable", detail: errorText(error) }))
+            await Promise.all(integrations.map((i) => Promise.try(() => i.run(signal, (part) => set(i.name, part)))
+                .catch((error) => set(i.name, {
+                status: "unavailable",
+                reason: "crashed",
+                detail: errorText(error),
+                state: snapshot[i.name].state, // the last good state stays, as it does through a failed read
+            }))
                 .finally(() => {
                 finished.add(i.name);
                 for (const resolve of waiting.get(i.name) ?? [])

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-export { type Change, createHome, envName, filePath, settle, type HomeSnapshot, type Integration, type Part, type StateOf, type Status, } from "./home.ts";
+export { type Change, createHome, type DeviceRecord, deviceRecords, envName, filePath, settle, type HomeSnapshot, type Integration, type Part, type Reason, type StateOf, type Status, } from "./home.ts";
 export { DOWN_POLLS, type Health, health, PUSH_DOWN_MS, STALE_POLLS, } from "./health.ts";
+export { type HomeDevice, homeDevices } from "./devices.ts";
 export { asOf, type Clock, realClock } from "./clock.ts";
-export { ConnectorError } from "./connector.ts";
+export { type ConnectorCode, ConnectorError } from "./connector.ts";
 export { bestWindow, type EnergyNow, energyNow, gridText, type PriceWindow, solarLevel, } from "./energy.ts";
 export { checkHome, checkPlan, Device, HomeConfig, HomeConfigError, type HomeIntegration, type LoadOptions, loadHome, parseJsonc, Room, type Setup, } from "./config.ts";
 export type { AddressCache, CachedAddress, Connector, Finder, Found, } from "./discover.ts";

package/dist/index.js

@@ -1,7 +1,8 @@
 // The root entry: the home, its config, discovery types, the clock, energy, and the sun, rain and day-block helpers. The weather types are in `./weather`.
 // Each connector has its own entry point (`@khalido/home/hue` and so on). Every export is named; test/exports.test.ts lists them.
-export { createHome, envName, filePath, settle, } from "./home.js";
+export { createHome, deviceRecords, envName, filePath, settle, } from "./home.js";
 export { DOWN_POLLS, health, PUSH_DOWN_MS, STALE_POLLS, } from "./health.js";
+export { homeDevices } from "./devices.js";
 export { asOf, realClock } from "./clock.js";
 export { ConnectorError } from "./connector.js";
 export { bestWindow, energyNow, gridText, solarLevel, } from "./energy.js";