@khalido/home 0.0.0-stage → 0.1.0

package/dist/connectors/enphase/schemas.js

@@ -0,0 +1,34 @@
+import { z } from "zod";
+// Shapes from Enphase's TEB-00060 and pyenphase's recorded gateway replies (MIT, software 7 and 8).
+// Loose objects, optional fields: a firmware change degrades a reading, it does not throw.
+/** One measurement in `/production.json`: an `inverters` total or an `eim` meter reading. */
+export const Measurement = z.looseObject({
+    type: z.string(), // "inverters" | "eim" | "acb" (battery)
+    measurementType: z.string().optional(), // eim: "production" | "total-consumption" | "net-consumption"
+    activeCount: z.number().optional(), // 0 means the meter is not really measuring
+    wNow: z.number().optional(),
+    whToday: z.number().optional(),
+    whLifetime: z.number().optional(),
+    readingTime: z.number().optional(), // unix seconds
+});
+/** `GET /production.json?details=1`. */
+export const Production = z.looseObject({
+    production: z.array(Measurement).default([]),
+    consumption: z.array(Measurement).default([]),
+});
+/** `GET /ivp/meters`: which current transformers exist and whether they are switched on. */
+export const Meters = z.array(z.looseObject({
+    eid: z.number().optional(),
+    measurementType: z.string(),
+    state: z.string(),
+}));
+/** `GET /ivp/meters/readings`: one reading per meter, joined to `/ivp/meters` by `eid`. */
+export const Readings = z.array(z.looseObject({
+    eid: z.number(),
+    timestamp: z.number().optional(), // unix seconds
+    activePower: z.number().optional(), // W: production, or grid import (negative = export) on a net meter
+    actEnergyDlvd: z.number().optional(), // Wh lifetime: produced, or imported on a net meter
+    actEnergyRcvd: z.number().optional(), // Wh lifetime: exported on a net meter
+}));
+/** The JSON from Enphase's login: only the session id is used. */
+export const Login = z.looseObject({ session_id: z.string() });

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

@@ -0,0 +1,48 @@
+import { type Kind, Resource } from "./schemas.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 = {
+    host: string;
+    key: string;
+    fetch: typeof fetch;
+    clock?: Clock;
+};
+/** A failed bridge call. `code` is "link_button" when pairing waits on the bridge's button. */
+export declare class HueError extends ConnectorError {
+    readonly code?: "link_button";
+}
+/** Minimum gap between writes, per lane. Signify's guidance (login-gated, unconfirmed): ~10/s to lights, 1/s to groups. */
+export declare const WRITE_GAP_MS: {
+    readonly group: 1000;
+    readonly light: 100;
+};
+type Lane = keyof typeof WRITE_GAP_MS;
+/** Which lane a write goes in: `light` writes are fast, everything else (grouped_light, scene) is a group write. */
+export declare const laneFor: (kind: string) => Lane;
+/** Hue bodies merge field by field, the newer value winning: `{ on }` then `{ dimming }` lands as both. */
+export declare function mergeBody(older: object, newer: object): object;
+/** A typed CLIP v2 client. Reads go straight through; writes go through the bridge's write queue. `host` is read at each call, so a getter follows a move. */
+export declare function hueClient(options: HueOptions): {
+    put: (kind: Kind, id: string, body: object) => Promise<unknown[]>;
+    /** Every resource of one kind, or every resource on the bridge when `kind` is left out (one call). */
+    get(kind?: Kind, signal?: AbortSignal): Promise<Resource[]>;
+    /** Recall a scene in its room or zone. */
+    recallScene(id: string): Promise<unknown[]>;
+};
+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. */
+export declare function pair(options: {
+    host: string;
+    fetch: typeof fetch;
+    deviceType: string;
+}): Promise<{
+    key: string;
+    clientKey?: string;
+}>;
+/**
+ * A `fetch` that trusts only `ca` 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 {};

package/dist/connectors/hue/client.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { Envelope, PairResponse, Resource } from "./schemas.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. */
+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. */
+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";
+/** Hue bodies merge field by field, the newer value winning: `{ on }` then `{ dimming }` lands as both. */
+export function mergeBody(older, newer) {
+    const plain = (x) => typeof x === "object" && x !== null && !Array.isArray(x);
+    const out = { ...older };
+    for (const [k, v] of Object.entries(newer))
+        out[k] = plain(out[k]) && plain(v) ? mergeBody(out[k], v) : v;
+    return out;
+}
+/** A typed CLIP v2 client. Reads go straight through; writes go through the bridge's write queue. `host` is read at each call, so a getter follows a move. */
+export function hueClient(options) {
+    const lanes = {
+        group: writeLane({ gapMs: WRITE_GAP_MS.group, clock: options.clock }),
+        light: writeLane({ gapMs: WRITE_GAP_MS.light, clock: options.clock }),
+    };
+    async function call(method, path, body, signal) {
+        const headers = {
+            "hue-application-key": options.key,
+        };
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        const res = await fetchTimeout(options.fetch, `https://${options.host}${path}`, {
+            method,
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        }, { signal });
+        const parsed = Envelope.safeParse(await res.json().catch(() => undefined));
+        const errors = parsed.success
+            ? parsed.data.errors.map((e) => e.description)
+            : [];
+        if (!res.ok || errors.length)
+            throw new HueError(errors.join("; ") || `HTTP ${res.status} on ${method} ${path}`, { status: res.status });
+        return parsed.success ? parsed.data.data : [];
+    }
+    /** 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 {
+        put,
+        /** Every resource of one kind, or every resource on the bridge when `kind` is left out (one call). */
+        async get(kind, signal) {
+            return z
+                .array(Resource)
+                .parse(await call("GET", `/clip/v2/resource${kind ? `/${kind}` : ""}`, undefined, signal));
+        },
+        /** Recall a scene in its room or zone. */
+        recallScene(id) {
+            return put("scene", id, { recall: { action: "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) {
+    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 parsed = PairResponse.safeParse(await res.json().catch(() => undefined));
+    if (!parsed.success)
+        throw new HueError(`unexpected answer to POST /api (HTTP ${res.status})`, {
+            status: res.status,
+        });
+    const [first] = parsed.data;
+    if (first?.success)
+        return { key: first.success.username, clientKey: first.success.clientkey };
+    const error = first?.error;
+    throw new HueError(error?.description ?? `HTTP ${res.status} on POST /api`, {
+        status: res.status,
+        code: error?.type === 101 ? "link_button" : undefined,
+    });
+}
+/**
+ * A `fetch` that trusts only `ca` 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) {
+    const checkServerIdentity = (_host, cert) => cert.subject?.CN?.toLowerCase() === bridgeId.toLowerCase()
+        ? undefined
+        : new Error(`Hue bridge certificate is for ${cert.subject?.CN ?? "nobody"}, expected ${bridgeId}`);
+    const pinned = (input, init) => fetch(input, { ...init, tls: { ca, checkServerIdentity } });
+    return pinned;
+}

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

@@ -0,0 +1,41 @@
+import { type HueOptions } from "./client.ts";
+import { HueEvent } from "./schemas.ts";
+/** One SSE message: its `id:` line (the bridge sends `<unix seconds>:0`) and its joined `data:` lines. */
+export type SseMessage = {
+    id?: string;
+    data: string;
+};
+/** 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";
+} | {
+    kind: "events";
+    id?: string;
+    events: HueEvent[];
+    skipped?: number;
+} | {
+    kind: "disconnected";
+    error: unknown;
+    retryInMs: number;
+};
+/**
+ * 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.
+ */
+export declare const IDLE_MS = 90000;
+/** Waits between reconnects; the last one repeats. Reset after every successful connect. */
+export declare const BACKOFF_MS: number[];
+/**
+ * Read `GET /eventstream/clip/v2` until `signal` aborts, reconnecting with backoff.
+ * Events missed while disconnected are gone, so refetch everything on each "connected".
+ * A connection silent for `idleMs` is reconnected at once without a "disconnected" or a step up the backoff (the bridge
+ * sends no keep-alive); only a reconnect that then fails is reported, as any failure is.
+ */
+export declare function hueEvents(options: HueOptions & {
+    signal?: AbortSignal;
+    idleMs?: number;
+}): AsyncGenerator<StreamItem>;

package/dist/connectors/hue/events.js

@@ -0,0 +1,156 @@
+import { z } from "zod";
+import { realClock } from "../../clock.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. */
+export async function* parseSse(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                return;
+            buffer += decoder.decode(value, { stream: true });
+            for (let end = buffer.search(/\r?\n\r?\n/); end >= 0; end = buffer.search(/\r?\n\r?\n/)) {
+                const block = buffer.slice(0, end);
+                buffer = buffer.slice(end).replace(/^\r?\n\r?\n/, "");
+                const message = parseBlock(block);
+                if (message)
+                    yield message;
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function parseBlock(block) {
+    let id;
+    const data = [];
+    for (const line of block.split(/\r?\n/)) {
+        if (!line || line.startsWith(":"))
+            continue;
+        const colon = line.indexOf(":");
+        const field = colon < 0 ? line : line.slice(0, colon);
+        const value = colon < 0 ? "" : line.slice(colon + 1).replace(/^ /, "");
+        if (field === "id")
+            id = value;
+        else if (field === "data")
+            data.push(value);
+    }
+    return data.length ? { id, data: data.join("\n") } : undefined;
+}
+const safeJson = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        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.
+ */
+export const IDLE_MS = 90_000;
+/** Waits between reconnects; the last one repeats. Reset after every successful connect. */
+export const BACKOFF_MS = [1000, 5000, 15000, 60000];
+/**
+ * Read `GET /eventstream/clip/v2` until `signal` aborts, reconnecting with backoff.
+ * Events missed while disconnected are gone, so refetch everything on each "connected".
+ * A connection silent for `idleMs` is reconnected at once without a "disconnected" or a step up the backoff (the bridge
+ * sends no keep-alive); only a reconnect that then fails is reported, as any failure is.
+ */
+export async function* hueEvents(options) {
+    const clock = options.clock ?? realClock;
+    const stop = new AbortController();
+    const onAbort = () => stop.abort();
+    if (options.signal?.aborted)
+        stop.abort();
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    let attempt = 0;
+    let watch; // the running watchdog's wait
+    try {
+        while (!stop.signal.aborted) {
+            // Each connection has its own watchdog, on the clock: any bytes (events or the bridge's comment lines) re-arm it.
+            const connection = new AbortController();
+            const idleMs = options.idleMs ?? IDLE_MS;
+            let opened = false; // this connection got as far as "connected"
+            let quiet = false; // the watchdog ended it
+            const arm = () => {
+                watch?.abort();
+                const w = (watch = new AbortController());
+                void clock.sleep(idleMs, w.signal).then(() => {
+                    if (w.signal.aborted || connection.signal.aborted)
+                        return; // re-armed or already over (the clock's sleep resolves on abort)
+                    quiet = true;
+                    connection.abort(new HueError(`no data on the event stream for ${idleMs / 1000} s`));
+                });
+            };
+            try {
+                arm();
+                const res = await options.fetch(`https://${options.host}/eventstream/clip/v2`, {
+                    headers: {
+                        "hue-application-key": options.key,
+                        accept: "text/event-stream",
+                    },
+                    signal: AbortSignal.any([stop.signal, connection.signal]),
+                });
+                if (!res.ok || !res.body)
+                    throw new HueError(`HTTP ${res.status} on the event stream`, {
+                        status: res.status,
+                    });
+                yield { kind: "connected" };
+                opened = true;
+                arm(); // time spent with the consumer is not the bridge's silence
+                // The watchdog errors this pass-through, which ends the read even if the body ignores the abort.
+                const watched = res.body.pipeThrough(new TransformStream({
+                    start: (out) => connection.signal.addEventListener("abort", () => out.error(connection.signal.reason), { once: true }),
+                    transform: (chunk, out) => (arm(), out.enqueue(chunk)),
+                }));
+                for await (const message of parseSse(watched)) {
+                    attempt = 0; // reset only once data flows, so a bridge that accepts and drops still backs off
+                    // One odd batch is skipped and counted, not allowed to drop the stream (a reconnect costs a full read).
+                    const batches = z
+                        .array(z.unknown())
+                        .safeParse(safeJson(message.data));
+                    const parsed = (batches.success ? batches.data : [message.data]).map((b) => HueEvent.safeParse(b));
+                    const events = parsed.flatMap((p) => (p.success ? [p.data] : []));
+                    const skipped = parsed.length - events.length;
+                    yield {
+                        kind: "events",
+                        id: message.id,
+                        events,
+                        ...(skipped ? { skipped } : {}),
+                    };
+                }
+                throw new HueError("the event stream ended");
+            }
+            catch (caught) {
+                watch?.abort();
+                if (stop.signal.aborted)
+                    return;
+                // Quiet, not broken: probe with a fresh connection now. Only a probe that fails is reported (it never opened).
+                if (quiet && opened)
+                    continue;
+                const error = connection.signal.aborted
+                    ? connection.signal.reason
+                    : caught;
+                if (isRejectedKey(error))
+                    throw error; // retrying will not help: pair again
+                const retryInMs = BACKOFF_MS[Math.min(attempt++, BACKOFF_MS.length - 1)];
+                yield { kind: "disconnected", error, retryInMs };
+                await clock.sleep(retryInMs, stop.signal);
+            }
+        }
+    }
+    finally {
+        watch?.abort();
+        stop.abort(); // a consumer that breaks out also closes the connection
+        options.signal?.removeEventListener("abort", onAbort);
+    }
+}

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

@@ -0,0 +1,42 @@
+import { type Clock } from "../../clock.ts";
+import { z } from "zod";
+import { type Finder } from "../../discover.ts";
+import { type Integration } from "../../home.ts";
+import type { Manifest } from "../../manifest.ts";
+import { type HueClient } from "./client.ts";
+import { type HueSnapshot } from "./state.ts";
+export { bunPinnedFetch, type HueClient, HueError, type HueOptions, hueClient, pair, } 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. */
+export declare const configSchema: z.ZodObject<{
+    connector: z.ZodLiteral<"hue">;
+    host: z.ZodString;
+    bridgeId: z.ZodString;
+    key: z.ZodString;
+    ca: 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.
+ * `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;
+    fetch?: typeof fetch;
+    clock?: Clock;
+    find?: Finder;
+    idleMs?: number;
+    seen?: (host: string) => void;
+    hostCached?: boolean;
+};
+/**
+ * Hue as a home integration: a full read on every (re)connect, then patched from the event stream; `refresh` re-reads it all.
+ * A bridge that stops answering is looked for by `bridgeId` after three failed reconnects, and followed to its new address.
+ */
+export declare function hue(config: HueConfig): Integration<HueSnapshot, "hue"> & {
+    readonly client: HueClient;
+};
+export declare const manifest: Manifest<HueSnapshot>;

package/dist/connectors/hue/index.js

@@ -0,0 +1,205 @@
+import { asOf, realClock } from "../../clock.js";
+import { errorText } from "../../connector.js";
+import { z } from "zod";
+import { lostDetail, relocator } from "../../discover.js";
+import { envName, filePath, } from "../../home.js";
+import { bunPinnedFetch, hueClient } from "./client.js";
+import { hueEvents, isRejectedKey } from "./events.js";
+import { groups, lights, reduce, snapshotFrom, } from "./state.js";
+export { bunPinnedFetch, HueError, hueClient, pair, } from "./client.js";
+export { groups, homeGroupedLightId, lights, scenes, } from "./state.js";
+/** A Hue bridge in a home config: what it takes to reach it. Its model and software come live into the snapshot. */
+export const configSchema = z.looseObject({
+    connector: z.literal("hue"),
+    host: z.string().describe("the bridge's last known address"),
+    bridgeId: z
+        .string()
+        .describe("the bridge id, the CN its certificate must carry: its identity"),
+    key: envName.describe("env name holding the application key from `home pair`"),
+    ca: filePath.describe("Signify's root CA (PEM), relative to the config file"),
+});
+/**
+ * Hue as a home integration: a full read on every (re)connect, then patched from the event stream; `refresh` re-reads it all.
+ * A bridge that stops answering is looked for by `bridgeId` after three failed reconnects, and followed to its new address.
+ */
+export function hue(config) {
+    const clock = config.clock ?? realClock;
+    const where = relocator({
+        host: config.host,
+        id: config.bridgeId,
+        find: config.find,
+        clock,
+        cached: config.hostCached,
+    });
+    // One client for the integration's life, at wherever the bridge is now: a move keeps the write lane and the writes waiting in it.
+    const options = {
+        ...config,
+        fetch: config.fetch ?? bunPinnedFetch(config.bridgeId, config.ca),
+        get host() {
+            return where.host();
+        },
+    };
+    const client = hueClient(options);
+    let snapshot;
+    let report;
+    let status = "connecting";
+    let last = { status }; // the last report, said again to a refresh that cannot read
+    let running;
+    let buffered; // events seen while a refresh's GET is in flight, re-applied on top of it
+    let moved; // kept in `detail` so a consumer can persist the new address
+    return {
+        name: "hue",
+        client,
+        /**
+         * One full GET of every resource, replacing the stream-patched state; events that arrive meanwhile are re-applied on
+         * top. Only while connected; a failure keeps the state and says so.
+         */
+        refresh() {
+            where.reset(); // while it is down, the next failed reconnect looks for it at once
+            if (!report || !running || running.aborted)
+                return; // not running: nothing will report
+            // Not connected: nothing to read until the stream is back, so answer with the last report rather than leave the caller waiting out the backoff.
+            if (status !== "connected")
+                return report(last);
+            if (buffered)
+                return; // a refresh already in flight, whose GET covers this one
+            const signal = running;
+            buffered = [];
+            client.get(undefined, signal).then((all) => {
+                let s = snapshotFrom(all, asOf(clock));
+                for (const event of buffered ?? [])
+                    s = reduce(s, event);
+                buffered = undefined;
+                if (signal.aborted || status !== "connected")
+                    return; // the stream dropped meanwhile, or the key was rejected: the next connect reads it all
+                snapshot = s;
+                report?.({ status, detail: moved, state: snapshot });
+            }, (error) => {
+                buffered = undefined;
+                // Still connected (the stream is fine) but this read failed: not a good read, so the last one's time stands.
+                if (!signal.aborted && status === "connected")
+                    report?.({
+                        status,
+                        detail: `refresh failed: ${errorText(error)}`,
+                        state: snapshot,
+                        lastGoodAt: snapshot?.asOf,
+                    });
+            });
+        },
+        async run(signal, rawUpdate) {
+            running = signal;
+            report = (part) => ((status = part.status),
+                (last = part),
+                rawUpdate(part));
+            const update = report;
+            while (!signal.aborted) {
+                try {
+                    for await (const item of hueEvents({ ...options, signal })) {
+                        const now = asOf(clock);
+                        if (item.kind === "disconnected") {
+                            const r = await where.failed(signal);
+                            if (r.moved) {
+                                moved = r.moved;
+                                break; // connect at the new address now; that connection reports, with the move in `detail`
+                            }
+                            update({
+                                status: "disconnected",
+                                detail: lostDetail(r, item.error),
+                                state: snapshot,
+                            });
+                            continue;
+                        }
+                        if (item.kind === "connected") {
+                            snapshot = snapshotFrom(await client.get(undefined, signal), now);
+                            where.ok();
+                            config.seen?.(options.host);
+                        }
+                        else if (item.kind === "events" && snapshot) {
+                            for (const event of item.events)
+                                snapshot = reduce(snapshot, event);
+                            buffered?.push(...item.events);
+                            snapshot = { ...snapshot, lastEventId: item.id, asOf: now };
+                        }
+                        const anomaly = item.kind === "events" && item.skipped
+                            ? `skipped ${item.skipped} event batch(es) the schema did not recognise`
+                            : undefined;
+                        update({
+                            status: "connected",
+                            detail: moved,
+                            anomaly,
+                            state: snapshot,
+                        });
+                    }
+                }
+                catch (error) {
+                    if (signal.aborted)
+                        return; // stopped mid-read: not a failure
+                    if (isRejectedKey(error))
+                        return update({
+                            status: "unavailable",
+                            detail: "the bridge rejected the key; pair again",
+                            state: snapshot,
+                        });
+                    // The full read failed after connecting: say so, wait, and start over with a fresh stream.
+                    update({
+                        status: "disconnected",
+                        detail: errorText(error),
+                        state: snapshot,
+                    });
+                    await clock.sleep(5000, signal);
+                }
+            }
+        },
+    };
+}
+/** Lights on that the bridge can reach, and each room and zone as on or off with its brightness. */
+const view = (s) => ({
+    lightsOn: lights(s).filter((l) => l.on && l.reachable !== false).length,
+    rooms: groups(s).map(({ name, on, brightness }) => ({
+        name,
+        on,
+        brightness,
+    })),
+});
+export const manifest = {
+    name: "hue",
+    title: "Philips Hue",
+    iotClass: "local_push",
+    access: "local HTTPS, key from `home pair`",
+    env: [
+        {
+            name: "HUE_BRIDGE_HOST",
+            example: "hue-bridge.local",
+            optional: true,
+            what: "found by mDNS (dns-sd) when unset",
+        },
+        {
+            name: "HUE_BRIDGE_ID",
+            example: "0017880000000000",
+            optional: true,
+            what: "the certificate's CN must match it; mDNS finds it when unset",
+        },
+        {
+            name: "HUE_APPLICATION_KEY",
+            example: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+            what: "from `home pair`",
+        },
+        {
+            name: "HUE_CA_FILE",
+            example: "/path/to/hue-root-ca.pem",
+            what: "until HUE_BRIDGE_ROOT_CA ships in src/connectors/hue/",
+        },
+    ],
+    files: ["ca"],
+    /** "3 lights on", then "Kitchen: on · 40%" per room and zone. */
+    lines({ state }) {
+        if (!state)
+            return [];
+        const { lightsOn, rooms } = view(state);
+        return [
+            `${lightsOn} lights on`,
+            ...rooms.map((r) => `${r.name}: ${r.on ? `on${r.brightness === undefined ? "" : ` · ${Math.round(r.brightness)}%`}` : "off"}`),
+        ];
+    },
+    record: ({ state }) => (state ? view(state) : {}),
+};