@khalido/home 0.1.2 → 0.2.0

package/src/connectors/weather/bom.ts

@@ -284,6 +284,7 @@ export function bom(options: BomOptions = {}): WeatherSource {
       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/src/connectors/weather/google.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { type ConnectorError, getJson } from "../../connector.ts";
+import { ConnectorError, fetchTimeout } from "../../connector.ts";
 import { RAIN_INTENSITIES } from "./rain.ts";
 import { sunDisagrees } from "./sun.ts";
 import {
@@ -324,6 +324,33 @@ export type GoogleOptions = {
 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: Response): Promise<string | undefined> {
+  try {
+    const body = (await res.json()) as {
+      error?: { details?: { reason?: unknown }[] };
+    };
+    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 {
+  constructor(
+    message: string,
+    status: number,
+    readonly why?: string,
+  ) {
+    super(message, { status });
+  }
+}
+
 /**
  * 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).
@@ -353,12 +380,28 @@ export function google(options: GoogleOptions): WeatherSource {
       signal,
     }): Promise<SourceReading> {
       const q = (extra: string) =>
-        `key=${encodeURIComponent(options.key)}&location.latitude=${place.latitude}&location.longitude=${place.longitude}${extra}`;
-      const json = (path: string) =>
-        getJson(fetcher, `${base}/${path}`, {
-          init: { headers: { "user-agent": USER_AGENT } },
-          signal,
-        });
+        `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: string): Promise<unknown> => {
+        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 }),
@@ -385,10 +428,23 @@ export function google(options: GoogleOptions): WeatherSource {
           slowDue = nextPoll(at, Math.max(pollMinutes, CURRENT_MINUTES));
         }
       } catch (error) {
-        const status = (error as ConnectorError).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
+            : ({} as { status?: number; why?: string });
+        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 as Error).message}`; // the old slices stay; the minute forecast below is still used

package/src/connectors/weather/index.ts

@@ -1,5 +1,5 @@
 import { type Clock, localTime, realClock } from "../../clock.ts";
-import type { Integration, Status } from "../../home.ts";
+import type { Integration, Reason, Status } from "../../home.ts";
 import { field, type Manifest } from "../../manifest.ts";
 import { poller } from "../../poll.ts";
 import {
@@ -88,7 +88,13 @@ export type WeatherState = Slices & {
   timeZone?: string; // the config's, which the blocks and the text use
   sources: Record<
     string,
-    { read: boolean; problem?: string; stopped?: string; anomaly?: string }
+    {
+      read: boolean;
+      problem?: string;
+      stopped?: string; // it will not be read again, and why
+      reason?: Exclude<Reason, "crashed">; // with `stopped`, for code: a dead key shows here even while another source keeps the part connected
+      anomaly?: string;
+    }
   >;
 };
 
@@ -149,6 +155,7 @@ export function weather(
                 read: r !== undefined,
                 problem: r?.problem,
                 stopped: r?.stop,
+                reason: r?.stop ? (r.stopReason ?? "config") : undefined,
                 anomaly: r?.anomaly,
               },
             ];
@@ -174,6 +181,13 @@ export function weather(
             : 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/src/connectors/weather/source.ts

@@ -1,4 +1,5 @@
 import { ConnectorError, fetchTimeout } from "../../connector.ts";
+import type { Reason } from "../../home.ts";
 
 // The one place a weather provider plugs in: a `WeatherSource` returns slices, and `mergeWeather` picks one per slice.
 
@@ -142,6 +143,7 @@ export type SourceReading = Slices & {
   problem?: string; // a failed product, a missing option; the source keeps going
   anomaly?: string; // a value the source sent that could not be read as given
   stop?: string; // a terminal problem (a rejected key): the integration stops calling this source
+  stopReason?: Exclude<Reason, "crashed">; // with `stop`: a person must re-key, or fix a setting (the default)
 };
 
 /**

package/src/devices.ts

@@ -0,0 +1,182 @@
+import {
+  type CastHomeDevice,
+  type CastSnapshot,
+  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 {
+  playingElsewhere,
+  type SpotifyHomeDevice,
+  type SpotifyState,
+  spotifyHomeDevices,
+  spotifyText,
+} from "./connectors/spotify/index.ts";
+import type { HomeConfig } from "./config.ts";
+import { IDENTITY, sameId } from "./discover.ts";
+import type { DeviceRecord, Part } from "./home.ts";
+import { manifestOf } from "./manifests.ts";
+
+// Every device in the home in one list, each answering the same few questions (`DeviceRecord`), with its connector's own
+// typed row in `detail`. A connector with devices exports `<name>HomeDevices(part)` and is listed here, once in the union
+// and once in DEVICES; test/devices.test.ts fails for a manifest that is in neither DEVICES nor SERVICES.
+
+/** 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 const DEVICES = {
+  hue: hueHomeDevices,
+  daikin: daikinHomeDevices,
+  enphase: enphaseHomeDevices,
+  cast: castHomeDevices,
+  printers: printersHomeDevices,
+  spotify: spotifyHomeDevices,
+} satisfies Record<string, (part: Part<any> | undefined) => DeviceRecord[]>;
+
+/** Connectors that read a service, not a device: nothing to list. */
+export const SERVICES: readonly string[] = ["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: Record<string, Part | undefined>,
+  config?: Pick<HomeConfig, "devices" | "rooms">,
+): HomeDevice[] {
+  // Soloist doesn't say where its music went; a Cast device playing that track does, so the speaker's line names it.
+  const on = spotifyElsewhere(snapshot);
+  const all = Object.entries(DEVICES)
+    .flatMap(([name, devices]): HomeDevice[] =>
+      devices(snapshot[name] as never),
+    )
+    .map((d) =>
+      d.connector === "spotify" && on.length
+        ? { ...d, text: spotifyText(d.detail, on) }
+        : d,
+    );
+  if (!config) return all;
+  const entries = config.devices ?? [];
+  const hueRooms = new Map<string, string>(); // 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 as Record<string, string>)[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 as Record<string, unknown>)[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 } : {}) };
+  });
+}
+
+/**
+ * Where the account's Spotify is playing when the Soloist speaker says it is on another device: the names of the Cast
+ * devices and groups playing a track of that name in Spotify. A group is named, not its members. Empty when the music is
+ * on the speaker itself, nothing is playing, or it is on something Cast can't see (a phone, a laptop). Matched by the
+ * track's name, since neither side names the other.
+ */
+export function spotifyElsewhere(
+  snapshot: Record<string, Part | undefined>,
+): string[] {
+  const s = snapshot.spotify?.state as SpotifyState | undefined;
+  const cast = snapshot.cast?.state as CastSnapshot | undefined;
+  const name = s?.track?.name;
+  if (!playingElsewhere(s) || !name || !cast) return [];
+  return Object.values(cast.devices)
+    .filter(
+      (d) =>
+        d.status === "connected" &&
+        !d.playingVia && // its group's music: the group is named
+        d.app === "Spotify" &&
+        d.title === name &&
+        (d.playerState === "PLAYING" || d.playerState === "BUFFERING"),
+    )
+    .map((d) => d.name);
+}
+
+/** A room of the home config with the devices placed in it. `noData`: device connectors the config places here that listed nothing in it (never reached, not set up, or a `hueRoom` the bridge doesn't have), so the room isn't empty, it is unread. Per connector, not per device. */
+export type RoomDevices = {
+  id: string;
+  name: string;
+  floor?: string;
+  devices: HomeDevice[];
+  noData: string[];
+};
+
+/**
+ * `homeDevices` room by room, in the config's order, for a map of the home. A connector that is down but has read before
+ * still lists its devices, `available: false`; `noData` names one the config places in the room (a device's `room`, or
+ * `hueRoom`) that has nothing to list. `unplaced`: devices with no room, or one the config doesn't have.
+ */
+export function byRoom(
+  snapshot: Record<string, Part | undefined>,
+  config: Pick<HomeConfig, "devices" | "rooms">,
+): { rooms: RoomDevices[]; unplaced: HomeDevice[] } {
+  const all = homeDevices(snapshot, config);
+  const ids = new Set((config.rooms ?? []).map((r) => r.id));
+  return {
+    rooms: (config.rooms ?? []).map((r) => {
+      const devices = all.filter((d) => d.room === r.id);
+      const expected = new Set([
+        ...(config.devices ?? [])
+          .filter((d) => d.room === r.id)
+          .map((d) => d.connector),
+        ...(r.hueRoom === undefined ? [] : ["hue"]),
+      ]);
+      return {
+        id: r.id,
+        name: r.name,
+        ...(r.floor === undefined ? {} : { floor: r.floor }),
+        devices,
+        noData: [...expected].filter(
+          (c) => c in DEVICES && !devices.some((d) => d.connector === c),
+        ),
+      };
+    }),
+    unplaced: all.filter((d) => !d.room || !ids.has(d.room)),
+  };
+}

package/src/discover.ts

@@ -134,8 +134,7 @@ function newEntry(f: Found): Record<string, string | number> {
     host: f.host,
     [IDENTITY[f.connector]]: f.id,
   };
-  if (f.connector === "hue")
-    return { ...base, key: "HUE_APPLICATION_KEY", ca: "hue-root-ca.pem" };
+  if (f.connector === "hue") return { ...base, key: "HUE_APPLICATION_KEY" };
   if (f.connector === "enphase")
     return { ...base, token: "~/.config/home/enphase-token.json" };
   return base;

package/src/finders-entry.ts

@@ -1,2 +1,2 @@
 // `@khalido/home/finders`: what a Node consumer passes to `loadHome`. The rest of finders.ts is the CLI's.
-export { FINDERS, fileCache } from "./finders.ts";
+export { FINDERS, fileCache, MissingTool } from "./finders.ts";

package/src/finders.ts

@@ -32,6 +32,7 @@ import {
 // `fileCache` keeps the addresses discovery found in a file between runs, so the next run connects straight away.
 
 /** The system's mDNS tool is not installed: discovery can't run until it is. */
+/** The discovery tool isn't installed (`dns-sd` on macOS, `avahi-browse` from avahi-utils on Linux): the message names it. */
 export class MissingTool extends Error {}
 
 /**
@@ -153,21 +154,32 @@ function decoded(v: string): string {
   }
 }
 
-/** Broadcast pydaikin's discovery packet (UDP 30000 → 30050) and collect who answers within `ms`. */
+/** Broadcast pydaikin's discovery packet (UDP 30000 → 30050), three times across `ms`, and collect who answers, each unit once. */
 export function findDaikins(
   ms = 1500,
 ): Promise<{ ip: string; fields: Record<string, string> }[]> {
   return new Promise((resolve) => {
     const found: { ip: string; fields: Record<string, string> }[] = [];
     const sock = createSocket({ type: "udp4", reuseAddr: true });
-    sock.on("message", (msg, from) =>
-      found.push({ ip: from.address, fields: daikinFields(msg.toString()) }),
+    sock.on("message", (msg, from) => {
+      if (!found.some((f) => f.ip === from.address))
+        found.push({ ip: from.address, fields: daikinFields(msg.toString()) });
+    });
+    const asks: ReturnType<typeof setTimeout>[] = [];
+    const done = () => (
+      asks.forEach(clearTimeout),
+      sock.close(),
+      resolve(found)
     );
-    sock.on("error", () => (sock.close(), resolve(found)));
+    sock.on("error", done);
     sock.bind(30000, () => {
       sock.setBroadcast(true);
-      sock.send("DAIKIN_UDP/common/basic_info", 30050, "255.255.255.255");
-      setTimeout(() => (sock.close(), resolve(found)), ms);
+      // UDP drops packets, more so while mDNS is busy beside it: one ask missed KO's unit in 2 runs of 3 (2026-11-11). Ask three times.
+      const ask = () =>
+        sock.send("DAIKIN_UDP/common/basic_info", 30050, "255.255.255.255");
+      ask();
+      asks.push(setTimeout(ask, ms / 3), setTimeout(ask, (2 * ms) / 3));
+      setTimeout(done, ms);
     });
   });
 }

package/src/health.ts

@@ -1,4 +1,4 @@
-import type { Part, Status } from "./home.ts";
+import type { Part, Reason, Status } from "./home.ts";
 import { MANIFESTS } from "./manifests.ts";
 
 /**
@@ -14,6 +14,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, */
@@ -61,7 +62,7 @@ function healthOf(
     (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,
@@ -70,5 +71,6 @@ function healthOf(
     staleAfterMs,
     downAfterMs,
     detail,
+    reason,
   };
 }