@khalido/home 0.1.3 → 0.2.1

package/dist/connectors/hue/ca.js

@@ -0,0 +1,38 @@
+// Signify's two root certificates for Hue bridges, so pinning needs no file: `bunPinnedFetch(bridgeId)` and
+// `nodePinnedFetch(bridgeId)` trust these and nothing else. Public certificates, as Signify's "Using HTTPS" page gives
+// them (login-gated); these bytes are the ones openHAB, hb-hue-tools, openhue-go and Raycast's Hue extension ship.
+//
+//   CN=root-bridge, O=Philips Hue       to 2038-01-19   the one in use: KO's square bridge (BSB002) chains to it
+//     SHA-256 F0:BD:8E:65:09:E8:2F:77:4D:63:BC:00:9D:53:88:C9:69:FE:3D:CF:7D:6D:54:1D:63:51:B7:2B:89:8D:8A:CF
+//   CN=Hue Root CA 01, O=Signify Hue    to 2050-12-31   Signify's spare, likely behind an intermediate: untried here
+//     SHA-256 D8:B8:94:48:B2:AF:8E:16:76:18:5A:C0:72:19:EE:9D:CB:C8:F0:1C:12:2A:02:6A:2A:4B:7B:5C:FE:03:28:B8
+//
+// test/hue.test.ts checks both fingerprints, so an edit here fails.
+/** Signify's root certificates for Hue bridges (PEM, two certificates): the default `ca` everywhere one is taken. */
+export const HUE_BRIDGE_ROOT_CA = `-----BEGIN CERTIFICATE-----
+MIICMjCCAdigAwIBAgIUO7FSLbaxikuXAljzVaurLXWmFw4wCgYIKoZIzj0EAwIw
+OTELMAkGA1UEBhMCTkwxFDASBgNVBAoMC1BoaWxpcHMgSHVlMRQwEgYDVQQDDAty
+b290LWJyaWRnZTAiGA8yMDE3MDEwMTAwMDAwMFoYDzIwMzgwMTE5MDMxNDA3WjA5
+MQswCQYDVQQGEwJOTDEUMBIGA1UECgwLUGhpbGlwcyBIdWUxFDASBgNVBAMMC3Jv
+b3QtYnJpZGdlMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEjNw2tx2AplOf9x86
+aTdvEcL1FU65QDxziKvBpW9XXSIcibAeQiKxegpq8Exbr9v6LBnYbna2VcaK0G22
+jOKkTqOBuTCBtjAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNV
+HQ4EFgQUZ2ONTFrDT6o8ItRnKfqWKnHFGmQwdAYDVR0jBG0wa4AUZ2ONTFrDT6o8
+ItRnKfqWKnHFGmShPaQ7MDkxCzAJBgNVBAYTAk5MMRQwEgYDVQQKDAtQaGlsaXBz
+IEh1ZTEUMBIGA1UEAwwLcm9vdC1icmlkZ2WCFDuxUi22sYpLlwJY81Wrqy11phcO
+MAoGCCqGSM49BAMCA0gAMEUCIEBYYEOsa07TH7E5MJnGw557lVkORgit2Rm1h3B2
+sFgDAiEA1Fj/C3AN5psFMjo0//mrQebo0eKd3aWRx+pQY08mk48=
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+MIIBzDCCAXOgAwIBAgICEAAwCgYIKoZIzj0EAwIwPDELMAkGA1UEBhMCTkwxFDAS
+BgNVBAoMC1NpZ25pZnkgSHVlMRcwFQYDVQQDDA5IdWUgUm9vdCBDQSAwMTAgFw0y
+NTAyMjUwMDAwMDBaGA8yMDUwMTIzMTIzNTk1OVowPDELMAkGA1UEBhMCTkwxFDAS
+BgNVBAoMC1NpZ25pZnkgSHVlMRcwFQYDVQQDDA5IdWUgUm9vdCBDQSAwMTBZMBMG
+ByqGSM49AgEGCCqGSM49AwEHA0IABFfOO0jfSAUXGQ9kjEDzyBrcMQ3ItyA5krE+
+cyvb1Y3xFti7KlAad8UOnAx0FBLn7HZrlmIwm1QnX0fK3LPM13mjYzBhMB0GA1Ud
+DgQWBBTF1pSpsCASX/z0VHLigxU2CAaqoTAfBgNVHSMEGDAWgBTF1pSpsCASX/z0
+VHLigxU2CAaqoTAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBBjAKBggq
+hkjOPQQDAgNHADBEAiAk7duT+IHbOGO4UUuGLAEpyYejGZK9Z7V9oSfnvuQ5BQIg
+IYSgwwxHXm73/JgcU9lAM6c8Bmu3UE3kBIUwBs1qXFw=
+-----END CERTIFICATE-----
+`;

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

@@ -1,5 +1,7 @@
+import { type Rgb } from "./color.ts";
 import { type Kind, Resource } from "./schemas.ts";
-import type { Clock } from "../../clock.ts";
+import { type GroupView, type LightView } from "./state.ts";
+import { type Clock } from "../../clock.ts";
 import { ConnectorError } from "../../connector.ts";
 /** What a Hue client needs: the bridge's LAN address, its application key, and a pinned `fetch`. */
 export type HueOptions = {
@@ -8,11 +10,46 @@ export type HueOptions = {
     fetch: typeof fetch;
     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 declare class HueError extends ConnectorError {
-    readonly code?: "link_button";
+    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 declare 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 declare const WRITE_GAP_MS: {
     readonly group: 1000;
     readonly light: 100;
@@ -29,6 +66,24 @@ export declare function hueClient(options: HueOptions): {
     get(kind?: Kind, signal?: AbortSignal): Promise<Resource[]>;
     /** Recall a scene in its room or zone. */
     recallScene(id: string): Promise<unknown[]>;
+    /** Change one light, by name or id. Only when a person asks. Resolves with the light as the bridge then reported it. */
+    light(target: string, change: LightChange, options?: HueWriteOptions): Promise<HueApplied<LightView>>;
+    /**
+     * 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.
+     */
+    allOff(options?: HueWriteOptions): Promise<HueApplied<LightView[]>>;
+    /**
+     * 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.
+     */
+    room(target: string, change: LightChange, options?: HueWriteOptions): Promise<HueApplied<GroupView>>;
+    /**
+     * 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.
+     */
+    scene(target: string, room?: string, options?: HueWriteOptions): Promise<HueApplied<GroupView>>;
 };
 export type HueClient = ReturnType<typeof hueClient>;
 /** Ask the bridge for an application key. One call: throws `HueError` with code "link_button" until KO presses it. */
@@ -36,13 +91,33 @@ export declare function pair(options: {
     host: string;
     fetch: typeof fetch;
     deviceType: string;
+    signal?: AbortSignal;
+}): Promise<{
+    key: string;
+    clientKey?: string;
+}>;
+/**
+ * `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 declare 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;
 }>;
 /**
- * A `fetch` that trusts only `ca` and accepts only a certificate whose CN is `bridgeId`.
+ * 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 declare function bunPinnedFetch(bridgeId: string, ca: string): typeof fetch;
+export declare function bunPinnedFetch(bridgeId: string, ca?: string): typeof fetch;
 export {};

package/dist/connectors/hue/client.js

@@ -1,11 +1,17 @@
 import { z } from "zod";
+import { colorToXy, kelvinToMirek } from "./color.js";
 import { Envelope, PairResponse, Resource } from "./schemas.js";
+import { groups, lights, scenes, snapshotFrom, homeGroupedLightId, } from "./state.js";
+import { HUE_BRIDGE_ROOT_CA } from "./ca.js";
+import { realClock } from "../../clock.js";
 import { ConnectorError, fetchTimeout } from "../../connector.js";
 import { writeLane } from "../../lane.js";
-/** 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 {
 }
-/** Minimum gap between writes, per lane. Signify's guidance (login-gated, unconfirmed): ~10/s to lights, 1/s to groups. */
+/** 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 };
 /** Which lane a write goes in: `light` writes are fast, everything else (grouped_light, scene) is a group write. */
 export const laneFor = (kind) => kind === "light" ? "light" : "group";
@@ -44,7 +50,8 @@ export function hueClient(options) {
     }
     /** Change one resource, e.g. `put("grouped_light", id, { on: { on: false } })`. Spaced per lane; writes to one resource waiting their turn merge. */
     const put = (kind, id, body) => lanes[laneFor(kind)].send(`${kind}/${id}`, body, (b) => call("PUT", `/clip/v2/resource/${kind}/${id}`, b), 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, signal) {
@@ -57,6 +64,184 @@ export function hueClient(options) {
             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) => new Set(labels).size < labels.length;
+    const invalid = (message) => 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(items, target, what, label = (i) => i.name ?? i.id) {
+        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, name, members, isOn) {
+        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 = {};
+        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.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(view, asked) {
+        const until = clock.now() + CONFIRM_MS;
+        let state;
+        let failed;
+        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, light) => (v) => {
+        const on = body.on?.on;
+        const brightness = body.dimming
+            ?.brightness;
+        const mirek = body.color_temperature
+            ?.mirek;
+        const xy = body.color?.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(options, kind, id, body, now, after) {
+        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, change, options) {
+            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) {
+            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, change, options) {
+            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, room, options) {
+            const s = await read();
+            const all = groups(s);
+            const within = room === undefined ? undefined : pick(all, room, "room or zone");
+            const roomName = (id) => 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));
+        },
+    };
 }
 /** Ask the bridge for an application key. One call: throws `HueError` with code "link_button" until KO presses it. */
 export async function pair(options) {
@@ -67,7 +252,7 @@ export async function pair(options) {
             devicetype: options.deviceType,
             generateclientkey: true,
         }),
-    });
+    }, { signal: options.signal });
     const parsed = PairResponse.safeParse(await res.json().catch(() => undefined));
     if (!parsed.success)
         throw new HueError(`unexpected answer to POST /api (HTTP ${res.status})`, {
@@ -83,10 +268,36 @@ 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) {
+    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, ca) {
+export function bunPinnedFetch(bridgeId, ca = HUE_BRIDGE_ROOT_CA) {
     const checkServerIdentity = (_host, cert) => cert.subject?.CN?.toLowerCase() === bridgeId.toLowerCase()
         ? undefined
         : new Error(`Hue bridge certificate is for ${cert.subject?.CN ?? "nobody"}, expected ${bridgeId}`);

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

@@ -0,0 +1,30 @@
+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 declare function parseColor(color: string | Rgb): Rgb;
+/** Whether `p` is inside the gamut triangle. */
+export declare function inGamut(p: XY, g: Gamut): boolean;
+/** `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 declare function nearestInGamut(p: XY, g: Gamut): XY;
+/**
+ * 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 declare function colorToXy(color: string | Rgb, gamut?: Gamut): XY;
+/** 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 declare function xyToHex(xy: XY): string;
+/** Colour temperature: Hue counts in mirek, a million over the kelvin. 2700 K is 370 mirek. */
+export declare const kelvinToMirek: (kelvin: number) => number;
+export declare const mirekToKelvin: (mirek: number) => number;

package/dist/connectors/hue/color.js

@@ -0,0 +1,92 @@
+import { ConnectorError } from "../../connector.js";
+/** 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) {
+    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) => v > 0.04045 ? ((v + 0.055) / 1.055) ** 2.4 : v / 12.92;
+const gamma = (v) => v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055;
+const cross = (a, b) => a.x * b.y - a.y * b.x;
+const minus = (a, b) => ({ x: a.x - b.x, y: a.y - b.y });
+/** Whether `p` is inside the gamut triangle. */
+export function inGamut(p, g) {
+    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, b, p) {
+    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, g) {
+    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) => (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, gamut) {
+    const { r, g, b } = parseColor(color);
+    const [lr, lg, lb] = [r, g, b].map((v) => linear(v / 255));
+    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) => 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) {
+    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) => Math.round(1e6 / kelvin);
+export const mirekToKelvin = (mirek) => Math.round(1e6 / mirek);

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

@@ -7,8 +7,6 @@ export type SseMessage = {
 };
 /** Split an SSE byte stream into messages, one per blank-line-separated block. Comment lines (`:`) are skipped. */
 export declare function parseSse(body: ReadableStream<Uint8Array>): AsyncGenerator<SseMessage>;
-/** A 401 or 403: the key is wrong or revoked. */
-export declare const isRejectedKey: (error: unknown) => boolean;
 /** What the stream yields: a (re)connection, a batch of events, or a drop with the wait before the next try. */
 export type StreamItem = {
     kind: "connected";

package/dist/connectors/hue/events.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { realClock } from "../../clock.js";
+import { isRejectedKey } from "../../connector.js";
 import { HueError } from "./client.js";
 import { HueEvent } from "./schemas.js";
 /** Split an SSE byte stream into messages, one per blank-line-separated block. Comment lines (`:`) are skipped. */
@@ -50,8 +51,6 @@ const safeJson = (text) => {
         return undefined;
     }
 };
-/** A 401 or 403: the key is wrong or revoked. */
-export const isRejectedKey = (error) => error instanceof HueError && (error.status === 401 || error.status === 403);
 /**
  * A connection with no bytes for this long is reconnected: a silent half-close otherwise looks connected forever (aiohue
  * uses 90 s). The bridge sends nothing on its own, so a quiet house trips it too; the reconnect is a silent probe.

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

@@ -5,7 +5,9 @@ import { type DeviceRecord, type Integration, type Part } from "../../home.ts";
 import type { Manifest } from "../../manifest.ts";
 import { type HueClient } from "./client.ts";
 import { type GroupView, type HueSnapshot, type LightView } from "./state.ts";
-export { bunPinnedFetch, type HueClient, HueError, type HueOptions, hueClient, pair, } from "./client.ts";
+export { HUE_BRIDGE_ROOT_CA } from "./ca.ts";
+export { colorToXy, type Gamut, kelvinToMirek, mirekToKelvin, type Rgb, type XY, xyToHex, } from "./color.ts";
+export { bunPinnedFetch, CONFIRM_MS, type HueApplied, type HueRequest, type HueWriteOptions, type LightChange, type HueClient, HueError, type HueOptions, hueClient, pair, pairWhenPressed, } from "./client.ts";
 export type { HueEvent, Resource } from "./schemas.ts";
 export { type GroupView, groups, type HueSnapshot, homeGroupedLightId, type LightView, lights, scenes, } from "./state.ts";
 /** A Hue bridge in a home config: what it takes to reach it. Its model and software come live into the snapshot. */
@@ -14,17 +16,17 @@ export declare const configSchema: z.ZodObject<{
     host: z.ZodString;
     bridgeId: z.ZodString;
     key: z.ZodString;
-    ca: z.ZodString;
+    ca: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
 /**
- * Hue settings for a home. Leave out `fetch` in Bun and it pins to `ca` and `bridgeId`; in Node pass a pinned one.
+ * Hue settings for a home. Leave out `fetch` in Bun and it pins to `bridgeId` and `ca` (Signify's roots, `HUE_BRIDGE_ROOT_CA`, when left out); in Node pass a pinned one.
  * `find` (mDNS, matched by `bridgeId`) finds the bridge again after three failed reconnects; `idleMs` is the stream's watchdog.
  */
 export type HueConfig = {
     host: string;
     bridgeId: string;
     key: string;
-    ca: string;
+    ca?: string;
     fetch?: typeof fetch;
     clock?: Clock;
     find?: Finder;
@@ -39,6 +41,15 @@ export type HueConfig = {
 export declare function hue(config: HueConfig): Integration<HueSnapshot, "hue"> & {
     readonly client: HueClient;
 };
+/** A light, room or zone in a line: "Kitchen: on · 40%", "Desk: on · 40% · 2700 K", "Strip: on · 80% · #ff8800", "Kitchen: off", or the name alone when the bridge hasn't said. */
+export declare const hueText: (v: {
+    name?: string;
+    id: string;
+    on?: boolean;
+    brightness?: number;
+    kelvin?: number;
+    hex?: string;
+}) => string;
 /** A Hue light, or a room or zone, as a home device: `detail` is its `LightView` or `GroupView`. */
 export type HueHomeDevice = DeviceRecord<"hue", "light", "on" | "off", LightView> | DeviceRecord<"hue", "group", "on" | "off", GroupView>;
 /** Every light, then every room and zone. A light's `available` is its Zigbee link; a group's `members` are its lights. */