@khalido/home 0.0.0-stage → 0.1.0

package/dist/connectors/amber/index.js

@@ -0,0 +1,94 @@
+import { asOf, realClock } from "../../clock.js";
+import { errorText } from "../../connector.js";
+import { z } from "zod";
+import { envName } from "../../home.js";
+import { energyNow } from "../../energy.js";
+import { field } from "../../manifest.js";
+import { poller } from "../../poll.js";
+import { amberClient, AmberError } from "./client.js";
+export { AmberError, amberClient, } from "./client.js";
+/** Poll every 60 s: prices move in 5-minute intervals and the current one is revised inside it; 5 calls in 5 min, limit 50. */
+export const POLL_MS = 60_000;
+/** Amber in a home config: the key's env name, and the site when the account has more than one. */
+export const configSchema = z.looseObject({
+    connector: z.literal("amber"),
+    key: envName.describe("env name holding the Amber API key"),
+    siteId: z
+        .string()
+        .optional()
+        .describe("the site; the first active one when left out"),
+});
+/** Amber prices as a home integration: one read now, then every 60 s. */
+export function amber(config) {
+    const client = amberClient(config);
+    const clock = config.clock ?? realClock;
+    const poll = poller(clock);
+    return {
+        name: "amber",
+        refresh: poll.nudge,
+        async run(signal, update) {
+            let siteId = config.siteId;
+            let last;
+            while (!signal.aborted) {
+                try {
+                    siteId ??= await client.siteId(signal);
+                    last = {
+                        ...(await client.prices(siteId, signal)),
+                        asOf: asOf(clock),
+                    };
+                    update({ status: "connected", anomaly: last.anomaly, state: last });
+                }
+                catch (error) {
+                    if (signal.aborted)
+                        return; // stopped mid-read: not a failure
+                    if (error instanceof AmberError && error.status === 401)
+                        return update({
+                            status: "unavailable",
+                            detail: "Amber rejected the key",
+                            state: last,
+                        });
+                    update({
+                        status: "disconnected",
+                        detail: errorText(error),
+                        state: last,
+                    });
+                }
+                await poll.wait(POLL_MS, signal);
+            }
+        },
+    };
+}
+/** Amber's prices in a few words: "buy 40.9c low (estimate) · sell 35.3c · 7% renewables", with a spike and a negative price when there is one. */
+export function amberText(a) {
+    const { negativePrice } = energyNow(undefined, a);
+    return [
+        `buy ${a.importCents?.toFixed(1) ?? "?"}c${a.priceDescriptor ? ` ${a.priceDescriptor}` : ""}${a.estimate ? " (estimate)" : ""}`,
+        a.spike && a.spike !== "none" ? `spike ${a.spike}` : "",
+        `sell ${a.exportCents?.toFixed(1) ?? "?"}c`,
+        negativePrice ?? "",
+        field(a.renewables, (v) => `${Math.round(v)}% renewables`),
+    ]
+        .filter(Boolean)
+        .join(" · ");
+}
+export const manifest = {
+    name: "amber",
+    title: "Amber Electric",
+    iotClass: "cloud_polling",
+    pollSeconds: POLL_MS / 1000,
+    access: "cloud HTTPS, AMBER_KEY; 50 calls per 5 min",
+    env: [
+        {
+            name: "AMBER_KEY",
+            example: "psk_xxxxxxxx",
+            what: "Amber Electric API key (app.amber.com.au/developers)",
+        },
+        {
+            name: "AMBER_SITE_ID",
+            example: "",
+            optional: true,
+            what: "the first active site is used when unset",
+        },
+    ],
+    lines: ({ state }) => state?.importCents === undefined ? [] : [amberText(state)],
+};

package/dist/connectors/cast/codec.d.ts

@@ -0,0 +1,38 @@
+/** One message on a Cast socket. `payload` is the JSON text; a binary payload (unused by any namespace here) comes as undefined. */
+export type CastMessage = {
+    source: string;
+    destination: string;
+    namespace: string;
+    payload?: string;
+};
+/** The namespaces a state reader uses. */
+export declare const NS: {
+    readonly connection: "urn:x-cast:com.google.cast.tp.connection";
+    readonly heartbeat: "urn:x-cast:com.google.cast.tp.heartbeat";
+    readonly receiver: "urn:x-cast:com.google.cast.receiver";
+    readonly media: "urn:x-cast:com.google.cast.media";
+    readonly multizone: "urn:x-cast:com.google.cast.multizone";
+};
+/** The largest message the protocol allows (64 KiB); a longer length prefix means the stream is out of step. */
+export declare const MAX_MESSAGE = 65536;
+/** A message as framed on the socket: version 0, string payload. */
+export declare function encode(m: CastMessage): Uint8Array;
+/** One message's bytes (without the length prefix). Unknown fields are skipped. */
+export declare function decode(bytes: Uint8Array): CastMessage;
+/** Splits a byte stream into messages: `push` each chunk as it arrives, get back every message it completed. */
+export declare function framer(): (chunk: Uint8Array) => CastMessage[];
+/** An open Cast socket. `peer` is its certificate's name (a device's id), `protocol` its TLS version. Tests pass a fake. */
+export type CastChannel = {
+    peer?: string;
+    protocol?: string;
+    send(message: CastMessage): void;
+    messages: AsyncIterable<CastMessage>;
+    close(): void;
+};
+/** How to open one: `tlsConnect` from `@khalido/home/cast/tls` in Bun and Node. */
+export type CastConnect = (to: {
+    host: string;
+    port: number;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}) => Promise<CastChannel>;

package/dist/connectors/cast/codec.js

@@ -0,0 +1,102 @@
+// CastV2's one protobuf message, CastMessage (cast_channel.proto), by hand: six fields, two wire types. Each message on
+// the socket is a 4-byte big-endian length, then the encoded message. Only string payloads (JSON) are used.
+/** The namespaces a state reader uses. */
+export const NS = {
+    connection: "urn:x-cast:com.google.cast.tp.connection",
+    heartbeat: "urn:x-cast:com.google.cast.tp.heartbeat",
+    receiver: "urn:x-cast:com.google.cast.receiver",
+    media: "urn:x-cast:com.google.cast.media",
+    multizone: "urn:x-cast:com.google.cast.multizone",
+};
+/** The largest message the protocol allows (64 KiB); a longer length prefix means the stream is out of step. */
+export const MAX_MESSAGE = 65_536;
+const text = new TextEncoder();
+const varint = (n) => {
+    const out = [];
+    for (; n > 127; n = Math.floor(n / 128))
+        out.push((n % 128) | 128);
+    return [...out, n];
+};
+const field = (number, value) => {
+    const bytes = text.encode(value);
+    return [(number << 3) | 2, ...varint(bytes.length), ...bytes];
+};
+/** A message as framed on the socket: version 0, string payload. */
+export function encode(m) {
+    const body = [
+        0x08,
+        0,
+        ...field(2, m.source),
+        ...field(3, m.destination),
+        ...field(4, m.namespace),
+        0x28,
+        0,
+        ...field(6, m.payload ?? ""),
+    ];
+    const out = new Uint8Array(4 + body.length);
+    new DataView(out.buffer).setUint32(0, body.length);
+    out.set(body, 4);
+    return out;
+}
+/** One message's bytes (without the length prefix). Unknown fields are skipped. */
+export function decode(bytes) {
+    const strings = {};
+    let i = 0;
+    const read = () => {
+        let n = 0;
+        for (let scale = 1;; scale *= 128) {
+            if (i >= bytes.length)
+                throw new Error("cast: truncated varint");
+            const b = bytes[i++];
+            n += (b & 127) * scale;
+            if (b < 128)
+                return n;
+        }
+    };
+    const decoder = new TextDecoder();
+    while (i < bytes.length) {
+        const key = read();
+        const wire = key & 7;
+        if (wire === 0)
+            read();
+        else if (wire === 2) {
+            const length = read();
+            if (i + length > bytes.length)
+                throw new Error("cast: truncated field");
+            strings[key >> 3] = decoder.decode(bytes.subarray(i, i + length));
+            i += length;
+        }
+        else if (wire === 1 || wire === 5)
+            i += wire === 1 ? 8 : 4;
+        else
+            throw new Error(`cast: unknown wire type ${wire}`);
+    }
+    return {
+        source: strings[2] ?? "",
+        destination: strings[3] ?? "",
+        namespace: strings[4] ?? "",
+        payload: strings[6],
+    };
+}
+/** Splits a byte stream into messages: `push` each chunk as it arrives, get back every message it completed. */
+export function framer() {
+    let buffer = new Uint8Array(0);
+    return (chunk) => {
+        const joined = new Uint8Array(buffer.length + chunk.length);
+        joined.set(buffer);
+        joined.set(chunk, buffer.length);
+        const out = [];
+        let at = 0;
+        while (joined.length - at >= 4) {
+            const length = new DataView(joined.buffer, at).getUint32(0);
+            if (length > MAX_MESSAGE)
+                throw new Error(`cast: a ${length}-byte message, over the protocol's ${MAX_MESSAGE}`);
+            if (joined.length - at < 4 + length)
+                break;
+            out.push(decode(joined.subarray(at + 4, at + 4 + length)));
+            at += 4 + length;
+        }
+        buffer = joined.slice(at);
+        return out;
+    };
+}

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

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { type Clock } from "../../clock.ts";
+import { type Found } from "../../discover.ts";
+import type { Integration } from "../../home.ts";
+import type { Manifest } from "../../manifest.ts";
+import { type CastConnect } from "./codec.ts";
+import { type CastDevice, type CastSnapshot, type Resolved } from "./state.ts";
+import { type CastActions, type ServeClip } from "./writes.ts";
+export type { CastConnect } from "./codec.ts";
+export type { CastDevice, CastSnapshot, Resolved } from "./state.ts";
+export type { AnnounceResult, CastActions, CastClip, ServeClip, } from "./writes.ts";
+/** A Cast device or speaker group in a home config. No host: a group's moves with its leader, so every address comes from discovery. */
+export declare const configSchema: z.ZodObject<{
+    connector: z.ZodLiteral<"cast">;
+    name: z.ZodString;
+    castId: z.ZodString;
+}, z.core.$loose>;
+/** Discovery's answers as `resolve` returns them: Cast entries only, port 8009 unless discovery said otherwise. */
+export declare const resolvedFrom: (found: Found[]) => Resolved[];
+export type CastConfig = {
+    /** Every Cast device and group on the network (the CLI runs `dns-sd`). Called at start, after any drop, and on refresh while one is missing. */
+    resolve: () => Promise<Resolved[]>;
+    /** Opens a socket: `tlsConnect` from `@khalido/home/cast/tls`. */
+    connect: CastConnect;
+    /**
+     * The config's entries: one discovery does not find shows as disconnected rather than not at all. With a cached
+     * `host` and `port` (an address cache) an entry connects at once; discovery runs only when an entry has none, or a
+     * cached address fails. A cached port other than 8009 is a group's (devices always listen on 8009).
+     */
+    expect?: {
+        castId: string;
+        name: string;
+        host?: string;
+        port?: number;
+    }[];
+    /** Each address that connected and passed the certificate check, for an address cache; again with the device's new name when it reports a rename. `name` is the device's own, never a config's. */
+    seen?: (id: string, address: {
+        host: string;
+        port: number;
+        name?: string;
+    }) => void;
+    clock?: Clock;
+    /** Heartbeat interval; a socket silent for three of them is dropped. */
+    pingMs?: number;
+    /** For `announce` with a clip of bytes: `serveClip` from `@khalido/home/cast/serve`. */
+    serve?: ServeClip;
+};
+/**
+ * Every Cast device and group as one integration, state only: one socket per entry, CONNECT, receiver and multizone
+ * status (a group's members, a device's own name), media status from a running media app's transport, then pushed updates; a PING every 5 s.
+ * A dropped socket starts one shared re-discovery (a group's leader may have changed) and reconnects with backoff at
+ * whatever address discovery last gave. While anything is down or missing, discovery repeats at 1, 5 and 15 minutes, then
+ * hourly, as the relocator does; never once per socket. The writes (`CastActions`) go over these same sockets.
+ */
+export declare function cast(config: CastConfig): Integration<CastSnapshot, "cast"> & CastActions;
+/** One Cast device or group in a few words: "Nest Hub: idle · 47%", "Group: idle · 43% · 3 members: A, B, C, led by A". */
+export declare function castText(d: CastDevice, s: CastSnapshot): string;
+/** Devices first, then groups, each by name. */
+export declare const castDevices: (s: CastSnapshot) => CastDevice[];
+export declare const manifest: Manifest<CastSnapshot>;