@khalido/home 0.1.1 → 0.1.3

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,102 @@
+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 { 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[] {
+  const all = Object.entries(DEVICES).flatMap(([name, devices]): HomeDevice[] =>
+    devices(snapshot[name] as never),
+  );
+  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 } : {}) };
+  });
+}

package/src/discover.ts

@@ -307,6 +307,7 @@ export type CachedAddress = {
   host: string;
   port?: number;
   name?: string;
+  model?: string; // Cast: what kind of device, without a discovery
   seenAt: string;
 };
 
@@ -345,7 +346,7 @@ export function addressBook(
     seen(
       connector: Connector,
       id: string | undefined,
-      address: { host: string; port?: number; name?: string },
+      address: { host: string; port?: number; name?: string; model?: string },
     ): void {
       if (!cache || id === undefined) return;
       const key = addressKey(connector, id);
@@ -355,14 +356,17 @@ export function addressBook(
         c.host === address.host &&
         c.port === address.port &&
         isFresh(c) &&
-        (!address.name || address.name === c.name)
+        (!address.name || address.name === c.name) &&
+        (!address.model || address.model === c.model)
       )
         return;
       const name = address.name || c?.name;
+      const model = address.model || c?.model;
       entries[key] = {
         host: address.host,
         ...(address.port === undefined ? {} : { port: address.port }),
         ...(name ? { name } : {}),
+        ...(model ? { model } : {}),
         seenAt: new Date(now()).toISOString(),
       };
       cache.write({ ...entries });

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,
   };
 }

package/src/home.ts

@@ -9,15 +9,18 @@ export const envName = z
     /^[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);
 
 /** 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.
@@ -25,12 +28,68 @@ export type Status =
 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 const deviceRecords = <R extends DeviceRecord>(
+  part: Part | undefined,
+  records: R[],
+): R[] => {
+  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 },
+  );
+};
+
 /**
  * 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`.
@@ -94,12 +153,16 @@ export function createHome<I extends Integration<any, string>>(
     integrations.map((i) => [i.name, { status: "connecting" }]),
   ) as HomeSnapshot<I>;
   const waiting = new Map<string, (() => void)[]>(); // refresh() callers, resolved by the integration's next report
-  const finished = new Set<string>(); // integrations whose run has ended: a refresh of one resolves at once, nothing will report
+  const finished = new Set<string>(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: Name, reported: Part) => {
     const before = (snapshot as Record<string, Part>)[name]!;
     const part = stamped(reported, before, asOf(clock));
     snapshot = { ...snapshot, [name]: part };
-    onChange?.(snapshot, { name, before, after: part } as Change<I>);
+    Promise.try(() =>
+      onChange?.(snapshot, { name, before, after: part } as Change<I>),
+    ).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);
@@ -119,7 +182,7 @@ export function createHome<I extends Integration<any, string>>(
         Extract<I, { name: N }> | 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?: Name): Promise<void> {
       const targets =
@@ -154,10 +217,14 @@ export function createHome<I extends Integration<any, string>>(
       ) as HomeSnapshot<I>;
       await Promise.all(
         integrations.map((i) =>
-          i
-            .run(signal, (part) => set(i.name, part))
+          Promise.try(() => i.run(signal, (part) => set(i.name, part)))
             .catch((error) =>
-              set(i.name, { status: "unavailable", detail: errorText(error) }),
+              set(i.name, {
+                status: "unavailable",
+                reason: "crashed",
+                detail: errorText(error),
+                state: (snapshot as Record<string, Part>)[i.name]!.state, // the last good state stays, as it does through a failed read
+              }),
             )
             .finally(() => {
               finished.add(i.name);

package/src/index.ts

@@ -3,12 +3,15 @@
 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";
@@ -19,8 +22,9 @@ export {
   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,

package/src/lane.ts

@@ -54,28 +54,31 @@ export function writeLane(options: LaneOptions) {
 
   async function run() {
     running = true;
-    while (queue.length) {
-      const now = clock.now();
-      const next = queue.find((p) => readyAt(p.slot) <= now);
-      if (!next) {
-        wake = new AbortController();
-        await clock.sleep(
-          Math.min(...queue.map((p) => readyAt(p.slot))) - now,
-          wake.signal,
-        );
-        continue;
-      }
-      queue.splice(queue.indexOf(next), 1);
-      lastAt = now;
-      sent.set(next.slot, [...recent(next.slot), now]);
-      try {
-        const result = await next.write(next.body);
-        for (const w of next.waiters) w.resolve(result);
-      } catch (error) {
-        for (const w of next.waiters) w.reject(error);
+    try {
+      while (queue.length) {
+        const now = clock.now();
+        const next = queue.find((p) => readyAt(p.slot) <= now);
+        if (!next) {
+          wake = new AbortController();
+          await clock.sleep(
+            Math.min(...queue.map((p) => readyAt(p.slot))) - now,
+            wake.signal,
+          );
+          continue;
+        }
+        queue.splice(queue.indexOf(next), 1);
+        lastAt = now;
+        sent.set(next.slot, [...recent(next.slot), now]);
+        try {
+          const result = await next.write(next.body);
+          for (const w of next.waiters) w.resolve(result);
+        } catch (error) {
+          for (const w of next.waiters) w.reject(error);
+        }
       }
+    } finally {
+      running = false; // a throw here must not leave the lane stuck
     }
-    running = false;
   }
 
   return {