@khalido/home 0.1.2 → 0.2.0

package/src/connectors/hue/client.ts

@@ -1,6 +1,17 @@
 import { z } from "zod";
+import { colorToXy, kelvinToMirek, type Rgb, type XY } from "./color.ts";
 import { Envelope, type Kind, PairResponse, Resource } from "./schemas.ts";
-import type { Clock } from "../../clock.ts";
+import {
+  type GroupView,
+  groups,
+  type LightView,
+  lights,
+  scenes,
+  snapshotFrom,
+  homeGroupedLightId,
+} from "./state.ts";
+import { HUE_BRIDGE_ROOT_CA } from "./ca.ts";
+import { type Clock, realClock } from "../../clock.ts";
 import { ConnectorError, fetchTimeout } from "../../connector.ts";
 import { writeLane } from "../../lane.ts";
 
@@ -12,12 +23,43 @@ export type HueOptions = {
   clock?: Clock;
 };
 
-/** A failed bridge call. `code` is "link_button" when pairing waits on the bridge's button. */
+/** A failed bridge call. `code` is "link_button" when pairing waits on the bridge's button, "invalid" for a change that can't be made (an unknown name, a value off the light's range) and "offline" for a light the bridge has lost, both caught before anything is sent. */
 export class HueError extends ConnectorError {
-  declare readonly code?: "link_button";
+  declare readonly code?: "link_button" | "invalid" | "offline";
 }
 
-/** Minimum gap between writes, per lane. Signify's guidance (login-gated, unconfirmed): ~10/s to lights, 1/s to groups. */
+/**
+ * What to change on a light, or on a room or zone: only what is given is sent. `brightness` is 1–100, `color` a hex
+ * string or `{ r, g, b }`, `kelvin` a white temperature; `color` and `kelvin` are one or the other. Without `on`, a
+ * change turns the light on, since a light that is off takes no brightness or colour. `transitionMs` is the fade (the
+ * bridge's own is 400 ms; 0 is at once).
+ */
+export type LightChange = {
+  on?: boolean;
+  brightness?: number;
+  color?: string | Rgb;
+  kelvin?: number;
+  transitionMs?: number;
+};
+
+/**
+ * What a write left: the light or group once the bridge reported the change (`confirmed`), or as it stood when
+ * `CONFIRM_MS` ran out. With `{ dryRun: true }` nothing is sent: `wouldSend` is the request the write would make, `state`
+ * is how things stand now, and `confirmed` is false. Check `wouldSend` first.
+ */
+export type HueApplied<V> = {
+  state: V;
+  confirmed: boolean;
+  wouldSend?: HueRequest;
+};
+/** One CLIP v2 write: `PUT /clip/v2/resource/<path>` with this body. */
+export type HueRequest = { method: "PUT"; path: string; body: object };
+/** `dryRun`: every check a write makes before sending (the name, the range, a lost light) and nothing sent. For testing a bot with people home. */
+export type HueWriteOptions = { dryRun?: boolean };
+/** How long `light`, `room` and `scene` wait for the bridge to report what was asked, reading every half second. */
+export const CONFIRM_MS = 3000;
+
+/** Minimum gap between writes, per lane: Signify's guidance (Hue System Performance, read 2026-11-11), about 10 a second to lights and 1 a second to groups. */
 export const WRITE_GAP_MS = { group: 1000, light: 100 } as const;
 type Lane = keyof typeof WRITE_GAP_MS;
 
@@ -83,7 +125,8 @@ export function hueClient(options: HueOptions) {
       mergeBody,
     );
 
-  return {
+  const clock = options.clock ?? realClock;
+  const base = {
     put,
     /** Every resource of one kind, or every resource on the bridge when `kind` is left out (one call). */
     async get(kind?: Kind, signal?: AbortSignal): Promise<Resource[]> {
@@ -103,6 +146,266 @@ export function hueClient(options: HueOptions) {
       return put("scene", id, { recall: { action: "active" } });
     },
   };
+
+  /** Whether two of these labels are the same, so only an id tells them apart. */
+  const same = (labels: string[]) => new Set(labels).size < labels.length;
+  const invalid = (message: string) =>
+    new HueError(message, { code: "invalid" });
+  /** One of `items` by id or by name (any case). A miss, or a name two of them share, throws listing what exists. */
+  function pick<T extends { id: string; name?: string }>(
+    items: T[],
+    target: string,
+    what: string,
+    label: (item: T) => string = (i) => i.name ?? i.id,
+  ): T {
+    const wanted = target.trim().toLowerCase();
+    const found = items.filter(
+      (i) => i.id === target || i.name?.toLowerCase() === wanted,
+    );
+    if (found.length === 1) return found[0]!;
+    throw invalid(
+      found.length
+        ? `"${target}" names ${found.length}: ${same(found.map(label)) ? found.map((i) => `${label(i)} (${i.id})`).join(", ") : found.map(label).join(", ")}`
+        : `no ${what} "${target}"; have: ${items.map(label).join(", ") || "none"}`,
+    );
+  }
+  const read = async () => snapshotFrom(await base.get(), "");
+
+  /** The CLIP body for `change`, checked against what the light (or a group's lights) can take. Throws before anything is sent. */
+  function bodyFor(
+    change: LightChange,
+    name: string,
+    members: LightView[],
+    isOn: boolean | undefined,
+  ): Record<string, unknown> {
+    const { on, brightness, color, kelvin, transitionMs } = change;
+    const look =
+      brightness !== undefined || color !== undefined || kelvin !== undefined;
+    if (on === undefined && !look) throw invalid("nothing to change");
+    if (on === false && look)
+      throw invalid("off takes no brightness or colour");
+    if (color !== undefined && kelvin !== undefined)
+      throw invalid("a colour or a white temperature, not both");
+    const body: Record<string, unknown> = {};
+    if (on !== undefined) body.on = { on };
+    else if (isOn !== true) body.on = { on: true }; // off, or a group where some may be
+    if (brightness !== undefined) {
+      if (!(brightness >= 1 && brightness <= 100))
+        throw invalid(`brightness is 1–100, not ${brightness}`);
+      body.dimming = { brightness };
+    }
+    if (color !== undefined) {
+      const gamut = members.find((l) => l.gamut)?.gamut;
+      if (!gamut) throw invalid(`${name} has no colour light`);
+      try {
+        body.color = { xy: colorToXy(color, gamut) };
+      } catch (error) {
+        throw invalid((error as Error).message); // a bad colour, as every other change that can't be made
+      }
+    }
+    if (kelvin !== undefined) {
+      const ranges = members.flatMap((l) =>
+        l.kelvinRange ? [l.kelvinRange] : [],
+      );
+      if (!ranges.length) throw invalid(`${name} takes no white temperature`);
+      const low = Math.min(...ranges.map((r) => r[0]));
+      const high = Math.max(...ranges.map((r) => r[1]));
+      if (!(kelvin >= low && kelvin <= high))
+        throw invalid(
+          `${kelvin} K is outside ${name}'s range, ${low}–${high} K`,
+        );
+      body.color_temperature = { mirek: kelvinToMirek(kelvin) };
+    }
+    if (transitionMs !== undefined) {
+      if (!(Number.isInteger(transitionMs) && transitionMs >= 0))
+        throw invalid(
+          `transitionMs is a whole number of ms, not ${transitionMs}`,
+        );
+      body.dynamics = { duration: transitionMs };
+    }
+    return body;
+  }
+
+  /** Read every half second until `view()` gives a state that is as `asked`, or `CONFIRM_MS` passes. A failed read is not a failed write. */
+  async function confirm<V>(
+    view: () => Promise<V | undefined>,
+    asked: (v: V) => boolean,
+  ): Promise<HueApplied<V>> {
+    const until = clock.now() + CONFIRM_MS;
+    let state: V | undefined;
+    let failed: unknown;
+    for (;;) {
+      try {
+        state = (await view()) ?? state;
+        if (state !== undefined && asked(state)) break;
+      } catch (error) {
+        failed = error;
+      }
+      if (clock.now() >= until) break;
+      await clock.sleep(500);
+    }
+    if (state === undefined)
+      throw failed ?? new HueError("sent, but it is no longer on the bridge");
+    return { state, confirmed: asked(state) };
+  }
+  /**
+   * Whether a view shows what the body asked: on, brightness within a point, and on a light the white temperature within
+   * 2 mirek or the colour within 0.02 in `xy`. A room reports neither, so its colour is not compared (its `on` is).
+   */
+  const shows =
+    (body: Record<string, unknown>, light: boolean) =>
+    (v: Partial<LightView>): boolean => {
+      const on = (body.on as { on: boolean } | undefined)?.on;
+      const brightness = (body.dimming as { brightness: number } | undefined)
+        ?.brightness;
+      const mirek = (body.color_temperature as { mirek: number } | undefined)
+        ?.mirek;
+      const xy = (body.color as { xy: XY } | undefined)?.xy;
+      return (
+        (on === undefined || v.on === on) &&
+        (brightness === undefined ||
+          (v.brightness !== undefined &&
+            Math.abs(v.brightness - brightness) <= 1)) &&
+        (!light ||
+          mirek === undefined ||
+          (v.kelvin !== undefined &&
+            Math.abs(kelvinToMirek(v.kelvin) - mirek) <= 2)) &&
+        (!light ||
+          xy === undefined ||
+          (v.xy !== undefined &&
+            Math.abs(v.xy.x - xy.x) <= 0.02 &&
+            Math.abs(v.xy.y - xy.y) <= 0.02))
+      );
+    };
+
+  /** Send, or with `dryRun` say what would be sent and how `now` stands. */
+  async function send<V>(
+    options: HueWriteOptions | undefined,
+    kind: Kind,
+    id: string,
+    body: object,
+    now: V | undefined,
+    after: () => Promise<HueApplied<V>>,
+  ): Promise<HueApplied<V>> {
+    if (options?.dryRun) {
+      if (now === undefined)
+        throw new HueError("its room or zone is not on the bridge");
+      return {
+        state: now,
+        confirmed: false,
+        wouldSend: { method: "PUT", path: `${kind}/${id}`, body },
+      };
+    }
+    await put(kind, id, body);
+    return after();
+  }
+  return {
+    ...base,
+    /** Change one light, by name or id. Only when a person asks. Resolves with the light as the bridge then reported it. */
+    async light(
+      target: string,
+      change: LightChange,
+      options?: HueWriteOptions,
+    ): Promise<HueApplied<LightView>> {
+      const l = pick(lights(await read()), target, "light");
+      // The bridge takes a write to a light it has lost and answers "may not have effect": say so before sending.
+      if (l.reachable === false)
+        throw new HueError(
+          `${l.name ?? l.id} is unreachable: the bridge has lost it (is it switched off at the wall?)`,
+          { code: "offline" },
+        );
+      const body = bodyFor(change, l.name ?? l.id, [l], l.on);
+      return send(options, "light", l.id, body, l, () =>
+        confirm(
+          async () => lights(await read()).find((x) => x.id === l.id),
+          shows(body, true),
+        ),
+      );
+    },
+    /**
+     * Every light in the home off, with one write to the bridge's home group. Only when a person asks. Resolves with
+     * every light as the bridge then reported it, `confirmed` once none it can reach is on.
+     */
+    async allOff(options?: HueWriteOptions): Promise<HueApplied<LightView[]>> {
+      const s = await read();
+      const id = homeGroupedLightId(s);
+      if (!id) throw invalid("the bridge has no home group");
+      return send(
+        options,
+        "grouped_light",
+        id,
+        { on: { on: false } },
+        lights(s),
+        () =>
+          confirm(
+            async () => lights(await read()),
+            (all) => all.every((l) => !l.on || l.reachable === false),
+          ),
+      );
+    },
+    /**
+     * Change every light in a room or zone with one write, by name or id. Only when a person asks. Resolves with the
+     * group as the bridge then reported it; its brightness is the bridge's figure for the group, so a group holding a
+     * light that is off or unreachable may stay unconfirmed.
+     */
+    async room(
+      target: string,
+      change: LightChange,
+      options?: HueWriteOptions,
+    ): Promise<HueApplied<GroupView>> {
+      const s = await read();
+      const g = pick(groups(s), target, "room or zone");
+      const name = g.name ?? g.id;
+      if (!g.groupedLightId) throw invalid(`${name} has no lights`);
+      const members = lights(s).filter((l) => g.lightIds.includes(l.id));
+      const body = bodyFor(change, name, members, undefined);
+      return send(options, "grouped_light", g.groupedLightId, body, g, () =>
+        confirm(
+          async () => groups(await read()).find((x) => x.id === g.id),
+          shows(body, false),
+        ),
+      );
+    },
+    /**
+     * Recall a scene by name or id. A name several rooms use ("Relax") needs `room`. Only when a person asks. Resolves
+     * with the scene's room or zone, `confirmed` once the bridge reports the scene active.
+     */
+    async scene(
+      target: string,
+      room?: string,
+      options?: HueWriteOptions,
+    ): Promise<HueApplied<GroupView>> {
+      const s = await read();
+      const all = groups(s);
+      const within =
+        room === undefined ? undefined : pick(all, room, "room or zone");
+      const roomName = (id?: string) =>
+        all.find((g) => g.id === id)?.name ?? "no room";
+      const sc = pick(
+        scenes(s).filter((x) => !within || x.groupId === within.id),
+        target,
+        "scene",
+        (x) => `${x.name ?? x.id} in ${roomName(x.groupId)}`,
+      );
+      let active = false;
+      return send(
+        options,
+        "scene",
+        sc.id,
+        { recall: { action: "active" } },
+        all.find((g) => g.id === sc.groupId),
+        () =>
+          confirm(
+            async () => {
+              const now = await read();
+              active = scenes(now).find((x) => x.id === sc.id)?.active === true;
+              return groups(now).find((x) => x.id === sc.groupId);
+            },
+            () => active,
+          ),
+      );
+    },
+  };
 }
 export type HueClient = ReturnType<typeof hueClient>;
 
@@ -111,15 +414,21 @@ export async function pair(options: {
   host: string;
   fetch: typeof fetch;
   deviceType: string;
+  signal?: AbortSignal;
 }): Promise<{ key: string; clientKey?: string }> {
-  const res = await fetchTimeout(options.fetch, `https://${options.host}/api`, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({
-      devicetype: options.deviceType,
-      generateclientkey: true,
-    }),
-  });
+  const res = await fetchTimeout(
+    options.fetch,
+    `https://${options.host}/api`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        devicetype: options.deviceType,
+        generateclientkey: true,
+      }),
+    },
+    { signal: options.signal },
+  );
   const parsed = PairResponse.safeParse(
     await res.json().catch(() => undefined),
   );
@@ -138,10 +447,48 @@ export async function pair(options: {
 }
 
 /**
- * A `fetch` that trusts only `ca` and accepts only a certificate whose CN is `bridgeId`.
+ * `pair`, asked again every `everyMs` (2 s) until someone presses the bridge's button, for `timeoutMs` (30 s, as long as
+ * the button stays pressed). `onWaiting` is called once, when the bridge first says the button isn't pressed: the moment
+ * to tell the person. Throws the last `link_button` error when time runs out, any other error at once, and the signal's
+ * reason when aborted.
+ */
+export async function pairWhenPressed(options: {
+  host: string;
+  fetch: typeof fetch;
+  deviceType: string;
+  timeoutMs?: number;
+  everyMs?: number;
+  onWaiting?: () => void;
+  clock?: Clock;
+  signal?: AbortSignal;
+}): Promise<{ key: string; clientKey?: string }> {
+  const clock = options.clock ?? realClock;
+  const until = clock.now() + (options.timeoutMs ?? 30_000);
+  let waiting = false;
+  while (true) {
+    try {
+      return await pair(options);
+    } catch (error) {
+      const pressed = !(
+        error instanceof HueError && error.code === "link_button"
+      );
+      if (pressed || clock.now() >= until) throw error;
+      if (!waiting) options.onWaiting?.();
+      waiting = true;
+    }
+    await clock.sleep(options.everyMs ?? 2000, options.signal);
+    options.signal?.throwIfAborted();
+  }
+}
+
+/**
+ * A `fetch` that trusts only `ca` (Signify's roots, `HUE_BRIDGE_ROOT_CA`, when left out) and accepts only a certificate whose CN is `bridgeId`.
  * Uses Bun's `tls` fetch option; Node ignores it and then rejects the bridge, so it fails closed there; Node uses `nodePinnedFetch` from `@khalido/home/node`.
  */
-export function bunPinnedFetch(bridgeId: string, ca: string): typeof fetch {
+export function bunPinnedFetch(
+  bridgeId: string,
+  ca: string = HUE_BRIDGE_ROOT_CA,
+): typeof fetch {
   const checkServerIdentity = (
     _host: string,
     cert: { subject?: { CN?: string } },

package/src/connectors/hue/color.ts

@@ -0,0 +1,123 @@
+import { ConnectorError } from "../../connector.ts";
+
+// Colour for Hue lights. A light's colour is an `xy` point in the CIE 1931 space, and each light can show the points
+// inside its gamut triangle, which the bridge reports per light. The steps are the standard sRGB ones (gamma, the D65
+// matrix), as Signify's "Color Conversion Formulas" page describes; that page's SDK extract is not copied.
+
+export type XY = { x: number; y: number };
+export type Gamut = { red: XY; green: XY; blue: XY };
+export type Rgb = { r: number; g: number; b: number };
+
+/** A colour as a caller gives it: "#ff8800", "ff8800", "#f80", or `{ r, g, b }` each 0–255. Throws on anything else. */
+export function parseColor(color: string | Rgb): Rgb {
+  if (typeof color !== "string") {
+    const ok = [color.r, color.g, color.b].every(
+      (v) => Number.isFinite(v) && v >= 0 && v <= 255,
+    );
+    if (!ok)
+      throw new ConnectorError("a colour's r, g and b are each 0–255", {
+        code: "invalid",
+      });
+    return color;
+  }
+  const hex = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim())?.[1];
+  if (!hex)
+    throw new ConnectorError(`"${color}" is not a colour like #ff8800`, {
+      code: "invalid",
+    });
+  const full = hex.length === 3 ? [...hex].map((c) => c + c).join("") : hex;
+  const n = Number.parseInt(full, 16);
+  return { r: n >> 16, g: (n >> 8) & 255, b: n & 255 };
+}
+
+const linear = (v: number) =>
+  v > 0.04045 ? ((v + 0.055) / 1.055) ** 2.4 : v / 12.92;
+const gamma = (v: number) =>
+  v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055;
+
+const cross = (a: XY, b: XY) => a.x * b.y - a.y * b.x;
+const minus = (a: XY, b: XY): XY => ({ x: a.x - b.x, y: a.y - b.y });
+
+/** Whether `p` is inside the gamut triangle. */
+export function inGamut(p: XY, g: Gamut): boolean {
+  const v1 = minus(g.green, g.red);
+  const v2 = minus(g.blue, g.red);
+  const q = minus(p, g.red);
+  const s = cross(q, v2) / cross(v1, v2);
+  const t = cross(v1, q) / cross(v1, v2);
+  return s >= 0 && t >= 0 && s + t <= 1;
+}
+
+/** The nearest point to `p` on the segment a–b. */
+function onSegment(a: XY, b: XY, p: XY): XY {
+  const ab = minus(b, a);
+  const t = Math.min(
+    1,
+    Math.max(
+      0,
+      ((p.x - a.x) * ab.x + (p.y - a.y) * ab.y) / (ab.x ** 2 + ab.y ** 2),
+    ),
+  );
+  return { x: a.x + ab.x * t, y: a.y + ab.y * t };
+}
+
+/** `p` if the light can show it, else the nearest point on its gamut's edge: the colour it can show that is closest. */
+export function nearestInGamut(p: XY, g: Gamut): XY {
+  if (inGamut(p, g)) return p;
+  const edges = [
+    onSegment(g.red, g.green, p),
+    onSegment(g.green, g.blue, p),
+    onSegment(g.blue, g.red, p),
+  ];
+  const far = (q: XY) => (q.x - p.x) ** 2 + (q.y - p.y) ** 2;
+  return edges.reduce((best, q) => (far(q) < far(best) ? q : best));
+}
+
+/**
+ * A colour's `xy`, moved inside `gamut` when one is given. Brightness is not part of it: black has no colour and throws
+ * (turn the light off instead), and a dark red and a bright red are the same point.
+ */
+export function colorToXy(color: string | Rgb, gamut?: Gamut): XY {
+  const { r, g, b } = parseColor(color);
+  const [lr, lg, lb] = [r, g, b].map((v) => linear(v / 255)) as [
+    number,
+    number,
+    number,
+  ];
+  const X = lr * 0.4124 + lg * 0.3576 + lb * 0.1805;
+  const Y = lr * 0.2126 + lg * 0.7152 + lb * 0.0722;
+  const Z = lr * 0.0193 + lg * 0.1192 + lb * 0.9505;
+  const sum = X + Y + Z;
+  if (sum === 0)
+    throw new ConnectorError("black is not a colour a light can show", {
+      code: "invalid",
+    });
+  const xy = { x: X / sum, y: Y / sum };
+  const at = gamut ? nearestInGamut(xy, gamut) : xy;
+  return { x: round4(at.x), y: round4(at.y) };
+}
+const round4 = (v: number) => Math.round(v * 1e4) / 1e4;
+
+/** An `xy` as a hex colour for a screen, at full brightness: what the light's colour looks like, not how bright it is. */
+export function xyToHex(xy: XY): string {
+  if (xy.y <= 0) return "#000000";
+  const X = xy.x / xy.y;
+  const Z = (1 - xy.x - xy.y) / xy.y;
+  const rgb = [
+    X * 3.2406 - 1.5372 - Z * 0.4986,
+    -X * 0.9689 + 1.8758 + Z * 0.0415,
+    X * 0.0557 - 0.204 + Z * 1.057,
+  ].map((v) => Math.max(0, v));
+  const max = Math.max(...rgb);
+  return `#${rgb
+    .map((v) =>
+      Math.round(255 * Math.min(1, Math.max(0, gamma(max > 0 ? v / max : 0))))
+        .toString(16)
+        .padStart(2, "0"),
+    )
+    .join("")}`;
+}
+
+/** Colour temperature: Hue counts in mirek, a million over the kelvin. 2700 K is 370 mirek. */
+export const kelvinToMirek = (kelvin: number) => Math.round(1e6 / kelvin);
+export const mirekToKelvin = (mirek: number) => Math.round(1e6 / mirek);