@khalido/home 0.1.2 → 0.2.0

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { Clock } from "../../clock.ts";
+import { type Clock } from "../../clock.ts";
 import { ConnectorError } from "../../connector.ts";
 /** A failed Daikin call. `status` is the HTTP status, or the dsiot `rsc` when HTTP succeeded. */
 export declare class DaikinError extends ConnectorError {
@@ -23,6 +23,41 @@ type Node = {
     pch?: Node[];
 };
 declare const Node: z.ZodType<Node>;
+/**
+ * The setpoint a mode gets when the caller names none: this library's opinion (KO's: not too cold, properly warm).
+ * Without one, "cool" would mean whatever the remote last left. Auto keeps the unit's own.
+ */
+export declare const DEFAULT_TARGET_C: {
+    readonly cool: 25;
+    readonly heat: 27;
+};
+/**
+ * What a write left: the state once the unit reported the change (`confirmed`), or as it stood when `CONFIRM_MS` ran out
+ * without it. With `{ dryRun: true }` nothing is sent: `wouldSend` is the request and what it sets, `state` the unit as it
+ * reads now, and `confirmed` is false. Check `wouldSend` first.
+ */
+export type DaikinApplied = {
+    state: DaikinState;
+    confirmed: boolean;
+    wouldSend?: DaikinRequest;
+};
+/** One write: `POST /dsiot/multireq` with `body`; `sets` is what it changes, in this library's words. */
+export type DaikinRequest = {
+    method: "POST";
+    path: "/dsiot/multireq";
+    body: WriteRequest;
+    sets: {
+        on?: boolean;
+        mode?: Mode;
+        targetC?: number;
+    };
+};
+/** `dryRun`: every check a write makes (the mode, the setpoint's range), one read for the state, and nothing sent. */
+export type DaikinWriteOptions = {
+    dryRun?: boolean;
+};
+/** How long `power` and `mode` wait for the unit to report what was asked, reading once a second. */
+export declare const CONFIRM_MS = 5000;
 /** Little-endian hex to an integer, two's complement when `signed`: "2700" → 39, "EEFF" → -18. */
 export declare function hexLE(hex: string, signed?: boolean): number | undefined;
 /** Map the indoor and outdoor `dgc_status` trees to a state. Unknown codes go to `anomaly`, never to a guess. */
@@ -48,7 +83,7 @@ export declare const setMode: (mode: Mode) => WriteRequest;
 export declare function setTarget(c: number, mode: Mode): WriteRequest;
 /** Set the fan speed of `mode` (usually the current one). */
 export declare function setFan(fan: Fan, mode: Mode): WriteRequest;
-/** A client for one unit. Reads are op 2; `write` sends a body built by setPower, setMode, setTarget or setFan. */
+/** A client for one unit. Reads are op 2. `power` and `mode` are the writes most callers want; `write` sends any body built by setPower, setMode, setTarget or setFan. */
 export declare function daikinClient(options: {
     host: string;
     fetch: typeof fetch;
@@ -61,5 +96,13 @@ export declare function daikinClient(options: {
      * unconfirmed; re-read to be sure). Writes waiting their turn merge (`mergeWrites`) and resolve with the send that carried them.
      */
     write(request: WriteRequest): Promise<void>;
+    /** Turn the unit on or off, as it was last left. Only when a person asks. Resolves with what the unit then reported. */
+    power: (on: boolean, options?: DaikinWriteOptions) => Promise<DaikinApplied>;
+    /**
+     * Select a mode, turn the unit on and set its setpoint, in one request: `targetC`, else `DEFAULT_TARGET_C` (cool 25,
+     * heat 27), else (auto) the unit's own. Dry and fan take none, and a `targetC` for them throws before anything is
+     * sent, as one off the unit's range does. Only when a person asks. Resolves with what the unit then reported.
+     */
+    mode(mode: Mode, targetC?: number, options?: DaikinWriteOptions): Promise<DaikinApplied>;
 };
 export {};

package/dist/connectors/daikin/client.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { realClock } from "../../clock.js";
 import { ConnectorError, getJson } from "../../connector.js";
 import { writeLane } from "../../lane.js";
 // Daikin's JSON dsiot API (the BRP084 family): POST /dsiot/multireq, plain HTTP, no key. Field paths and value
@@ -56,6 +57,16 @@ const TARGET_RANGE = {
     heat: [10, 30],
     auto: [18, 30],
 };
+/**
+ * The setpoint a mode gets when the caller names none: this library's opinion (KO's: not too cold, properly warm).
+ * Without one, "cool" would mean whatever the remote last left. Auto keeps the unit's own.
+ */
+export const DEFAULT_TARGET_C = {
+    cool: 25,
+    heat: 27,
+};
+/** How long `power` and `mode` wait for the unit to report what was asked, reading once a second. */
+export const CONFIRM_MS = 5000;
 /** Little-endian hex to an integer, two's complement when `signed`: "2700" → 39, "EEFF" → -18. */
 export function hexLE(hex, signed = false) {
     if (!/^(?:[0-9a-f]{2})+$/i.test(hex))
@@ -173,7 +184,7 @@ export function setFan(fan, mode) {
         throw new DaikinError(`${mode} mode has no fan speed`);
     return write([["e_3001", FAN[mode], key(FANS, fan)]]);
 }
-/** A client for one unit. Reads are op 2; `write` sends a body built by setPower, setMode, setTarget or setFan. */
+/** A client for one unit. Reads are op 2. `power` and `mode` are the writes most callers want; `write` sends any body built by setPower, setMode, setTarget or setFan. */
 export function daikinClient(options) {
     const lane = writeLane({
         gapMs: WRITE_GAP_MS,
@@ -190,7 +201,8 @@ export function daikinClient(options) {
         schema: Multi,
         error: DaikinError,
     });
-    return {
+    const clock = options.clock ?? realClock;
+    const client = {
         /** The indoor and outdoor status in one request. A failed outdoor read leaves `outsideC` empty. */
         async read(signal) {
             const m = await multireq({
@@ -218,4 +230,57 @@ export function daikinClient(options) {
             }, mergeWrites);
         },
     };
+    /** Send `request`, then read once a second until the unit reports `asked` or `CONFIRM_MS` passes. Rejects if the write is refused, or if no read after it succeeds. */
+    async function apply(request, sets, asked, options) {
+        if (options?.dryRun)
+            return {
+                state: await client.read(),
+                confirmed: false,
+                wouldSend: {
+                    method: "POST",
+                    path: "/dsiot/multireq",
+                    body: request,
+                    sets,
+                },
+            };
+        await client.write(request);
+        const until = clock.now() + CONFIRM_MS;
+        let state;
+        let failed;
+        // The write was accepted, so one dropped read must not turn it into a failure: keep reading until the time is up.
+        for (;;) {
+            try {
+                state = await client.read();
+                if (asked(state))
+                    break;
+            }
+            catch (error) {
+                failed = error;
+            }
+            if (clock.now() >= until)
+                break;
+            await clock.sleep(1000);
+        }
+        if (!state)
+            throw failed; // sent, but the unit answered no read since: nothing to report
+        return { state, confirmed: asked(state) };
+    }
+    return {
+        ...client,
+        /** Turn the unit on or off, as it was last left. Only when a person asks. Resolves with what the unit then reported. */
+        power: (on, options) => apply(setPower(on), { on }, (s) => s.on === on, options),
+        /**
+         * Select a mode, turn the unit on and set its setpoint, in one request: `targetC`, else `DEFAULT_TARGET_C` (cool 25,
+         * heat 27), else (auto) the unit's own. Dry and fan take none, and a `targetC` for them throws before anything is
+         * sent, as one off the unit's range does. Only when a person asks. Resolves with what the unit then reported.
+         */
+        async mode(mode, targetC, options) {
+            const c = targetC ?? DEFAULT_TARGET_C[mode];
+            return apply(c === undefined
+                ? setMode(mode)
+                : mergeWrites(setMode(mode), setTarget(c, mode)), { on: true, mode, ...(c === undefined ? {} : { targetC: c }) }, (s) => s.on === true &&
+                s.mode === mode &&
+                (c === undefined || s.targetC === c), options);
+        },
+    };
 }

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

@@ -1,10 +1,10 @@
 import { type Clock } from "../../clock.ts";
 import { z } from "zod";
-import type { Integration } from "../../home.ts";
+import { type DeviceRecord, type Integration, type Part } from "../../home.ts";
 import { type Finder } from "../../discover.ts";
 import type { Manifest } from "../../manifest.ts";
-import { daikinClient, type DaikinState } from "./client.ts";
-export { DaikinError, type DaikinState, daikinClient, type Fan, type Mode, setFan, setMode, setPower, setTarget, type WriteRequest, } from "./client.ts";
+import { daikinClient, type DaikinState, type Mode } from "./client.ts";
+export { CONFIRM_MS, type DaikinApplied, type DaikinRequest, type DaikinWriteOptions, DaikinError, type DaikinState, DEFAULT_TARGET_C, daikinClient, type Fan, type Mode, setFan, setMode, setPower, setTarget, type WriteRequest, } from "./client.ts";
 /** Poll every 120 s, as Home Assistant's daikin integration does (its coordinator's update_interval). */
 export declare const POLL_MS = 120000;
 /** A Daikin AC in a home config: its last known address, and the MAC its UDP discovery reports, which is how it is recognised. */
@@ -30,7 +30,7 @@ export type DaikinSnapshot = DaikinState & {
 /** What `daikin().client` is: the reads and writes of the unit, at wherever it is now. */
 export type DaikinClient = ReturnType<typeof daikinClient>;
 /**
- * One Daikin AC as a home integration: one read now, then every 120 s. Its writes are `client.write(setPower(true))`: one
+ * One Daikin AC as a home integration: one read now, then every 120 s. Its writes are `client.power(on)` and `client.mode(mode, targetC?)`: one
  * client for the integration's life, so the writes share its lane and follow the unit when it moves.
  */
 export declare function daikin(config: DaikinConfig): Integration<DaikinSnapshot, "daikin"> & {
@@ -39,3 +39,7 @@ export declare function daikin(config: DaikinConfig): Integration<DaikinSnapshot
 /** The AC in a few words: "off · cool 25 °C · room 24 °C · outdoor unit 19.5 °C". */
 export declare function acText(s: DaikinState): string;
 export declare const manifest: Manifest<DaikinSnapshot>;
+/** The AC as a home device: `state` is `off`, its mode while on, or `on` when it hasn't said which; `detail` its snapshot. */
+export type DaikinHomeDevice = DeviceRecord<"daikin", "ac", "off" | "on" | Mode, DaikinSnapshot>;
+/** The one unit, once it has been read. It reports no name or id of its own: a home config's entry names and places it. */
+export declare function daikinHomeDevices(part: Part<DaikinSnapshot> | undefined): DaikinHomeDevice[];

package/dist/connectors/daikin/index.js

@@ -1,9 +1,10 @@
 import { asOf, realClock } from "../../clock.js";
 import { z } from "zod";
+import { deviceRecords, } from "../../home.js";
 import { lostDetail, relocator } from "../../discover.js";
 import { poller } from "../../poll.js";
-import { daikinClient, DaikinError } from "./client.js";
-export { DaikinError, daikinClient, setFan, setMode, setPower, setTarget, } from "./client.js";
+import { daikinClient, DaikinError, } from "./client.js";
+export { CONFIRM_MS, DaikinError, DEFAULT_TARGET_C, daikinClient, setFan, setMode, setPower, setTarget, } from "./client.js";
 /** Poll every 120 s, as Home Assistant's daikin integration does (its coordinator's update_interval). */
 export const POLL_MS = 120_000;
 /** A Daikin AC in a home config: its last known address, and the MAC its UDP discovery reports, which is how it is recognised. */
@@ -16,7 +17,7 @@ export const configSchema = z.looseObject({
         .describe("the unit's MAC as its UDP discovery reports it: its identity"),
 });
 /**
- * One Daikin AC as a home integration: one read now, then every 120 s. Its writes are `client.write(setPower(true))`: one
+ * One Daikin AC as a home integration: one read now, then every 120 s. Its writes are `client.power(on)` and `client.mode(mode, targetC?)`: one
  * client for the integration's life, so the writes share its lane and follow the unit when it moves.
  */
 export function daikin(config) {
@@ -101,8 +102,28 @@ export const manifest = {
         {
             name: "DAIKIN_HOST",
             example: "192.0.2.20",
-            what: "the unit's address; `home probe` finds it by UDP broadcast",
+            optional: true,
+            what: "the unit's address; found by UDP broadcast when unset (1.5 s a run)",
         },
     ],
     lines: ({ state }) => (state ? [acText(state)] : []),
 };
+/** The one unit, once it has been read. It reports no name or id of its own: a home config's entry names and places it. */
+export function daikinHomeDevices(part) {
+    const s = part?.state;
+    if (!s)
+        return [];
+    return deviceRecords(part, [
+        {
+            connector: "daikin",
+            id: "daikin",
+            name: manifest.title,
+            kind: "ac",
+            available: true,
+            ...(s.on === undefined ? {} : { state: s.on ? (s.mode ?? "on") : "off" }),
+            asOf: s.asOf,
+            text: `${manifest.title}: ${acText(s)}`,
+            detail: s,
+        },
+    ]);
+}

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

@@ -1,6 +1,6 @@
 import { type Clock } from "../../clock.ts";
 import { z } from "zod";
-import { type Integration } from "../../home.ts";
+import { type DeviceRecord, type Integration, type Part } from "../../home.ts";
 import { type Finder } from "../../discover.ts";
 import { type Manifest } from "../../manifest.ts";
 import { type EnphaseState } from "./client.ts";
@@ -41,3 +41,7 @@ export declare function enphase(config: EnphaseConfig): Integration<EnphaseSnaps
 /** "solar 2.1 kW, using 0.6 kW · token 300 days left". The login ask near the end is the integration's, in `detail`. */
 export declare function enphaseText(s: EnphaseSnapshot): string;
 export declare const manifest: Manifest<EnphaseSnapshot>;
+/** The gateway as a home device: `state` is `producing` while the solar makes power, else `idle`; `detail` its snapshot. */
+export type EnphaseHomeDevice = DeviceRecord<"enphase", "solar", "producing" | "idle", EnphaseSnapshot>;
+/** The one gateway, once it has been read. */
+export declare function enphaseHomeDevices(part: Part<EnphaseSnapshot> | undefined): EnphaseHomeDevice[];

package/dist/connectors/enphase/index.js

@@ -1,6 +1,6 @@
 import { localDay, realClock } from "../../clock.js";
 import { z } from "zod";
-import { filePath } from "../../home.js";
+import { deviceRecords, filePath, } from "../../home.js";
 import { lostDetail, relocator } from "../../discover.js";
 import { kw } from "../../manifest.js";
 import { poller } from "../../poll.js";
@@ -51,7 +51,17 @@ export function enphase(config) {
         name: "enphase",
         refresh: () => (where.reset(), poll.nudge()),
         async run(signal, update) {
-            const expiresAt = tokenExpiry(config.token); // a bad token fails this integration only
+            let expiresAt;
+            try {
+                expiresAt = tokenExpiry(config.token); // a bad token fails this integration only
+            }
+            catch {
+                return update({
+                    status: "unavailable",
+                    reason: "auth",
+                    detail: "the token is unreadable; run `home enphase login`",
+                });
+            }
             let last;
             let day;
             let moved; // kept in `detail` so a consumer can persist the new address
@@ -106,6 +116,7 @@ export function enphase(config) {
                     if (error instanceof EnphaseError && error.status === 401)
                         return update({
                             status: "unavailable",
+                            reason: "auth",
                             detail: "the gateway rejected the token; run `home enphase login`",
                             state: last,
                         });
@@ -172,3 +183,24 @@ export const manifest = {
     files: ["token"],
     lines: ({ state }) => (state ? [enphaseText(state)] : []),
 };
+/** The one gateway, once it has been read. */
+export function enphaseHomeDevices(part) {
+    const s = part?.state;
+    if (!s)
+        return [];
+    return deviceRecords(part, [
+        {
+            connector: "enphase",
+            id: "enphase",
+            name: manifest.title,
+            kind: "solar",
+            available: true,
+            ...(s.productionW === undefined
+                ? {}
+                : { state: s.productionW > 0 ? "producing" : "idle" }),
+            asOf: s.asOf,
+            text: `${manifest.title}: ${enphaseText(s)}`,
+            detail: s,
+        },
+    ]);
+}

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

@@ -0,0 +1,2 @@
+/** Signify's root certificates for Hue bridges (PEM, two certificates): the default `ca` everywhere one is taken. */
+export declare const HUE_BRIDGE_ROOT_CA = "-----BEGIN CERTIFICATE-----\nMIICMjCCAdigAwIBAgIUO7FSLbaxikuXAljzVaurLXWmFw4wCgYIKoZIzj0EAwIw\nOTELMAkGA1UEBhMCTkwxFDASBgNVBAoMC1BoaWxpcHMgSHVlMRQwEgYDVQQDDAty\nb290LWJyaWRnZTAiGA8yMDE3MDEwMTAwMDAwMFoYDzIwMzgwMTE5MDMxNDA3WjA5\nMQswCQYDVQQGEwJOTDEUMBIGA1UECgwLUGhpbGlwcyBIdWUxFDASBgNVBAMMC3Jv\nb3QtYnJpZGdlMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEjNw2tx2AplOf9x86\naTdvEcL1FU65QDxziKvBpW9XXSIcibAeQiKxegpq8Exbr9v6LBnYbna2VcaK0G22\njOKkTqOBuTCBtjAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNV\nHQ4EFgQUZ2ONTFrDT6o8ItRnKfqWKnHFGmQwdAYDVR0jBG0wa4AUZ2ONTFrDT6o8\nItRnKfqWKnHFGmShPaQ7MDkxCzAJBgNVBAYTAk5MMRQwEgYDVQQKDAtQaGlsaXBz\nIEh1ZTEUMBIGA1UEAwwLcm9vdC1icmlkZ2WCFDuxUi22sYpLlwJY81Wrqy11phcO\nMAoGCCqGSM49BAMCA0gAMEUCIEBYYEOsa07TH7E5MJnGw557lVkORgit2Rm1h3B2\nsFgDAiEA1Fj/C3AN5psFMjo0//mrQebo0eKd3aWRx+pQY08mk48=\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIBzDCCAXOgAwIBAgICEAAwCgYIKoZIzj0EAwIwPDELMAkGA1UEBhMCTkwxFDAS\nBgNVBAoMC1NpZ25pZnkgSHVlMRcwFQYDVQQDDA5IdWUgUm9vdCBDQSAwMTAgFw0y\nNTAyMjUwMDAwMDBaGA8yMDUwMTIzMTIzNTk1OVowPDELMAkGA1UEBhMCTkwxFDAS\nBgNVBAoMC1NpZ25pZnkgSHVlMRcwFQYDVQQDDA5IdWUgUm9vdCBDQSAwMTBZMBMG\nByqGSM49AgEGCCqGSM49AwEHA0IABFfOO0jfSAUXGQ9kjEDzyBrcMQ3ItyA5krE+\ncyvb1Y3xFti7KlAad8UOnAx0FBLn7HZrlmIwm1QnX0fK3LPM13mjYzBhMB0GA1Ud\nDgQWBBTF1pSpsCASX/z0VHLigxU2CAaqoTAfBgNVHSMEGDAWgBTF1pSpsCASX/z0\nVHLigxU2CAaqoTAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBBjAKBggq\nhkjOPQQDAgNHADBEAiAk7duT+IHbOGO4UUuGLAEpyYejGZK9Z7V9oSfnvuQ5BQIg\nIYSgwwxHXm73/JgcU9lAM6c8Bmu3UE3kBIUwBs1qXFw=\n-----END CERTIFICATE-----\n";

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