@khalido/home 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,11 @@
+import type { ServeClip } from "./writes.ts";
+/** How long a clip stays served when nothing fetches it. */
+export declare const SERVE_MS = 60000;
+/** This machine's IPv4 on the subnet that holds `host`, or with no host, its first non-internal IPv4. */
+export declare function lanAddress(host?: string, interfaces?: NodeJS.Dict<import("node:os").NetworkInterfaceInfo[]>): string;
+/**
+ * Serve `bytes`: a random port, an unguessable path, the given `Content-Type` and its `Content-Length`, the whole body
+ * to every GET (a player may probe before it fetches). It closes on `close()` (`announce` calls it when the clip has
+ * played), when `signal` aborts, or after `SERVE_MS`. `host` is the device that will fetch it, so the address is on its network.
+ */
+export declare const serveClip: ServeClip;

package/dist/connectors/cast/serve.js

@@ -0,0 +1,57 @@
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { networkInterfaces } from "node:os";
+// Node APIs (http, os), so this sits outside the runtime-neutral build like tls.ts and is passed to `cast()` as
+// `serve`. A Cast device fetches the clip itself, so it must be served over HTTP on the LAN, never loopback.
+/** How long a clip stays served when nothing fetches it. */
+export const SERVE_MS = 60_000;
+const ipv4 = (a) => a.split(".").reduce((n, part) => n * 256 + Number(part), 0);
+/** The network an address is on under a netmask: the address with its host bits cleared. */
+const network = (address, netmask) => ipv4(address) - (ipv4(address) % (2 ** 32 - ipv4(netmask)));
+/** This machine's IPv4 on the subnet that holds `host`, or with no host, its first non-internal IPv4. */
+export function lanAddress(host, interfaces = networkInterfaces()) {
+    const all = Object.values(interfaces)
+        .flatMap((list) => list ?? [])
+        .filter((i) => i.family === "IPv4");
+    const pick = host
+        ? all.find((i) => network(i.address, i.netmask) === network(host, i.netmask))
+        : all.find((i) => !i.internal);
+    if (!pick)
+        throw new Error(host
+            ? `no address of this machine on ${host}'s network`
+            : "no LAN IPv4 address on this machine");
+    return pick.address;
+}
+/**
+ * Serve `bytes`: a random port, an unguessable path, the given `Content-Type` and its `Content-Length`, the whole body
+ * to every GET (a player may probe before it fetches). It closes on `close()` (`announce` calls it when the clip has
+ * played), when `signal` aborts, or after `SERVE_MS`. `host` is the device that will fetch it, so the address is on its network.
+ */
+export const serveClip = (bytes, type, options = {}) => new Promise((resolve, reject) => {
+    if (options.signal?.aborted)
+        return reject(new Error("aborted"));
+    const address = lanAddress(options.host);
+    const path = `/${randomUUID()}`;
+    const server = createServer((req, res) => {
+        if (req.url !== path || (req.method !== "GET" && req.method !== "HEAD"))
+            return res.writeHead(404).end();
+        res.writeHead(200, {
+            "Content-Type": type,
+            "Content-Length": bytes.length,
+        });
+        res.end(req.method === "HEAD" ? undefined : bytes);
+    });
+    const timer = setTimeout(() => close(), SERVE_MS);
+    function close() {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", close);
+        server.close();
+        server.closeAllConnections();
+    }
+    options.signal?.addEventListener("abort", close, { once: true });
+    server.once("error", (error) => (close(), reject(error)));
+    server.listen(0, address, () => {
+        const { port } = server.address();
+        resolve({ url: `http://${address}:${port}${path}`, close });
+    });
+});

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

@@ -0,0 +1,62 @@
+import type { CastPayload } from "./schemas.ts";
+/** A Cast device or group as found by discovery: what `resolve` returns for each. */
+export type Resolved = {
+    id: string;
+    name: string;
+    model?: string;
+    host: string;
+    port: number;
+    group: boolean;
+};
+/**
+ * One Cast device or group. `name` is the device's own (mDNS fn, or a device's own multizone status), a config's only until it answers. Ids are the mDNS id, lowercase without dashes; `members`, `leader`, `groups` and
+ * `playingVia` name other entries by id. Volume is the device's own number, unrounded.
+ */
+export type CastDevice = {
+    id: string;
+    name: string;
+    model?: string;
+    kind: "device" | "group";
+    host?: string;
+    port?: number;
+    app?: string;
+    appId?: string;
+    idle?: boolean;
+    standby?: boolean;
+    volume?: number;
+    muted?: boolean;
+    volumeControl?: string;
+    playerState?: string;
+    title?: string;
+    artist?: string;
+    members?: string[];
+    leader?: string;
+    groups?: string[];
+    playingVia?: string;
+    status: "connecting" | "connected" | "disconnected";
+    detail?: string;
+    asOf?: string;
+};
+export type CastSnapshot = {
+    devices: Record<string, CastDevice>;
+    asOf: string;
+};
+/** An id as the snapshot keys it: the mDNS id (32 hex) and the certificate's and multizone's dashed UUID are one key. */
+export declare const castKey: (id: string) => string;
+/** Add or update what discovery found; devices it did not find this time are kept as they were. */
+export declare function found(s: CastSnapshot, entries: Resolved[], asOf: string): CastSnapshot;
+/** A socket opened or dropped. A group's `leader` comes with its socket. */
+export declare function connection(s: CastSnapshot, id: string, change: {
+    status: CastDevice["status"];
+    detail?: string;
+    leader?: string;
+}, asOf: string): CastSnapshot;
+/** One payload from one entry's socket. Pure: returns a new snapshot. */
+export declare function reduce(s: CastSnapshot, id: string, p: CastPayload, asOf: string): CastSnapshot;
+/** The app's transport speaks media status: connect to it to read what is playing. */
+export declare const mediaApp: (app?: {
+    namespaces?: {
+        name?: string;
+    }[];
+    transportId?: string;
+}) => boolean;

package/dist/connectors/cast/state.js

@@ -0,0 +1,133 @@
+/** An id as the snapshot keys it: the mDNS id (32 hex) and the certificate's and multizone's dashed UUID are one key. */
+export const castKey = (id) => id.toLowerCase().replace(/-/g, "");
+/** Add or update what discovery found; devices it did not find this time are kept as they were. */
+export function found(s, entries, asOf) {
+    const devices = { ...s.devices };
+    for (const e of entries) {
+        const id = castKey(e.id);
+        const kind = e.group ? "group" : "device";
+        devices[id] = {
+            ...(devices[id] ?? { status: "connecting" }),
+            id,
+            name: e.name,
+            model: e.model,
+            kind,
+            host: e.host,
+            port: e.port,
+        };
+    }
+    return link({ devices, asOf });
+}
+/** A socket opened or dropped. A group's `leader` comes with its socket. */
+export function connection(s, id, change, asOf) {
+    const key = castKey(id);
+    const d = s.devices[key];
+    if (!d)
+        return s;
+    const leader = change.leader === undefined ? d.leader : castKey(change.leader);
+    return link({
+        devices: {
+            ...s.devices,
+            [key]: { ...d, status: change.status, detail: change.detail, leader },
+        },
+        asOf,
+    });
+}
+/** One payload from one entry's socket. Pure: returns a new snapshot. */
+export function reduce(s, id, p, asOf) {
+    const key = castKey(id);
+    const prev = s.devices[key];
+    if (!prev)
+        return s;
+    const d = { ...prev, asOf };
+    if (p.type === "RECEIVER_STATUS") {
+        const app = p.status?.applications?.[0];
+        const v = p.status?.volume;
+        Object.assign(d, {
+            app: app?.displayName,
+            appId: app?.appId,
+            idle: !app || app.isIdleScreen === true,
+            standby: p.status?.isStandBy,
+            volume: v?.level,
+            muted: v?.muted,
+            volumeControl: v?.controlType,
+        });
+        if (!mediaApp(app))
+            Object.assign(d, {
+                playerState: undefined,
+                title: undefined,
+                artist: undefined,
+            });
+    }
+    else if (p.type === "MEDIA_STATUS") {
+        const m = p.status?.[0];
+        delete d.playingVia; // its own media now: link borrows the group's again only if this is empty
+        Object.assign(d, {
+            playerState: m?.playerState,
+            title: m?.media?.metadata?.title,
+            artist: m?.media?.metadata?.artist,
+        });
+    }
+    else if (d.kind === "device") {
+        // A device's own port lists only itself, by its current name in the Google Home app (mDNS fn; all six live devices
+        // matched, 2026-10-13): the name follows a rename without a discovery. Membership is read from a group's port alone.
+        if (p.type === "MULTIZONE_STATUS") {
+            const self = p.status?.devices?.find((m) => m.deviceId !== undefined && castKey(m.deviceId) === key);
+            if (self?.name)
+                d.name = self.name;
+        }
+    }
+    else {
+        const members = new Set(d.members ?? []);
+        if (p.type === "MULTIZONE_STATUS")
+            d.members = (p.status?.devices ?? []).flatMap((m) => m.deviceId ? [castKey(m.deviceId)] : []);
+        else {
+            const member = p.type === "DEVICE_REMOVED" ? p.deviceId : p.device?.deviceId;
+            if (member)
+                p.type === "DEVICE_REMOVED"
+                    ? members.delete(castKey(member))
+                    : members.add(castKey(member));
+            d.members = [...members];
+        }
+    }
+    return link({ devices: { ...s.devices, [key]: d }, asOf });
+}
+/** The app's transport speaks media status: connect to it to read what is playing. */
+export const mediaApp = (app) => app?.transportId !== undefined &&
+    (app.namespaces ?? []).some((n) => n.name === "urn:x-cast:com.google.cast.media");
+const active = (state) => state !== undefined && state !== "IDLE";
+/**
+ * The cross-links, recomputed from scratch on every change: each device's groups, and a member with no media of its
+ * own shows a playing group's, with `playingVia` naming the group (Home Assistant's model).
+ */
+function link(s) {
+    const devices = {};
+    for (const [id, d] of Object.entries(s.devices)) {
+        const own = d.playingVia
+            ? { playerState: undefined, title: undefined, artist: undefined }
+            : {};
+        devices[id] = { ...d, ...own, groups: undefined, playingVia: undefined };
+    }
+    for (const g of Object.values(devices).filter((d) => d.kind === "group")) {
+        for (const m of g.members ?? []) {
+            const d = devices[m];
+            if (!d || d.kind === "group")
+                continue;
+            d.groups = [...(d.groups ?? []), g.id];
+            if (active(g.playerState) && !active(d.playerState))
+                Object.assign(d, {
+                    playerState: g.playerState,
+                    title: g.title,
+                    artist: g.artist,
+                    playingVia: g.id,
+                });
+        }
+    }
+    for (const d of Object.values(devices))
+        if (d.groups === undefined)
+            delete d.groups;
+    for (const d of Object.values(devices))
+        if (d.playingVia === undefined)
+            delete d.playingVia;
+    return { devices, asOf: s.asOf };
+}

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

@@ -0,0 +1,3 @@
+import { type CastConnect } from "./codec.ts";
+/** Open a Cast socket: TLS to host:port within `timeoutMs`, framed CastMessages in and out. */
+export declare const tlsConnect: CastConnect;

package/dist/connectors/cast/tls.js

@@ -0,0 +1,67 @@
+import { connect } from "node:tls";
+import { encode, framer, } from "./codec.js";
+// The one Node API in the Cast connector, so it sits outside the runtime-neutral build (tsconfig.build.json), like
+// weather/ftp.ts, and is passed in as `connect`. Runs in Bun (1.4.2, checked live) and, untried, Node.
+//
+// Verification is off: every Cast device presents a self-signed certificate that rotates every 48 hours, so there is
+// nothing to pin. The integration instead checks the certificate's name (`peer`, the device's id) against discovery.
+/** Open a Cast socket: TLS to host:port within `timeoutMs`, framed CastMessages in and out. */
+export const tlsConnect = ({ host, port, signal, timeoutMs = 10_000, }) => new Promise((resolve, reject) => {
+    const socket = connect({ host, port, rejectUnauthorized: false });
+    let timer;
+    const fail = (error) => (clearTimeout(timer),
+        signal?.removeEventListener("abort", abort),
+        socket.destroy(),
+        reject(error));
+    timer = setTimeout(() => fail(new Error(`cast: no TLS answer from ${host}:${port} in ${timeoutMs / 1000} s`)), timeoutMs);
+    const abort = () => fail(new Error("aborted"));
+    signal?.addEventListener("abort", abort, { once: true });
+    socket.once("error", fail);
+    socket.once("secureConnect", () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", abort);
+        socket.off("error", fail);
+        const name = socket.getPeerCertificate().subject?.CN;
+        resolve(channel(socket, Array.isArray(name) ? name[0] : name, socket.getProtocol() ?? undefined));
+    });
+});
+/** The socket as an async stream of messages; the stream ends when the socket closes and throws on a socket error. */
+function channel(socket, peer, protocol) {
+    const split = framer();
+    const queue = [];
+    let ended = false;
+    let failure;
+    let wake;
+    const notify = () => (wake?.(), (wake = undefined));
+    socket.on("data", (chunk) => {
+        try {
+            queue.push(...split(new Uint8Array(chunk)));
+        }
+        catch (error) {
+            failure = error;
+            socket.destroy();
+        }
+        notify();
+    });
+    socket.on("error", (error) => ((failure ??= error), notify()));
+    socket.on("close", () => ((ended = true), notify()));
+    return {
+        peer,
+        protocol,
+        send: (m) => void (socket.writable && socket.write(encode(m))),
+        // end() flushes a CLOSE written just before; a device that does not close its side within a second is cut off.
+        close: () => (socket.end(),
+            setTimeout(() => socket.destroy(), 1000).unref()),
+        messages: (async function* () {
+            for (;;) {
+                while (queue.length)
+                    yield queue.shift();
+                if (failure)
+                    throw failure;
+                if (ended)
+                    return;
+                await new Promise((r) => (wake = r));
+            }
+        })(),
+    };
+}

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

@@ -0,0 +1,80 @@
+import type { Clock } from "../../clock.ts";
+import { type CastDevice } from "./state.ts";
+/** Google's own player for a URL of audio or video. */
+export declare const DEFAULT_MEDIA_RECEIVER = "CC1AD845";
+/** Each request (a status, a volume, LAUNCH, LOAD, STOP) gets this long to answer. */
+export declare const ANSWER_MS = 10000;
+/** How long an announcement waits for its clip to finish, beyond the clip's own length when the device reports it. */
+export declare const PLAY_MS = 60000;
+/** Level writes, and mute writes, per device or group in any minute; more wait their turn, the newest winning. A guess: Cast publishes no limit. */
+export declare const VOLUME_PER_MINUTE = 30;
+/** What to play: a URL the device can fetch (type defaults to audio/mpeg), or bytes for `serve` to put on the LAN. */
+export type CastClip = {
+    url: string;
+    type?: string;
+} | {
+    bytes: Uint8Array;
+    type: string;
+};
+/** What `announce` did: whether the clip played to its end, why not, and what it put back or could not. */
+export type AnnounceResult = {
+    played: boolean;
+    why?: string;
+    restored: string[];
+    notRestored: {
+        name: string;
+        why: string;
+    }[];
+};
+/** Serves bytes once over HTTP on the LAN: `serveClip` from `@khalido/home/cast/serve`. `host` is the device that will fetch it. */
+export type ServeClip = (bytes: Uint8Array, type: string, options?: {
+    host?: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    url: string;
+    close(): void;
+}>;
+/** The writes on `cast()`'s object. A target is a device's or group's name (any case) or its castId; volume is 0 to 1, as the snapshot's. */
+export type CastActions = {
+    setVolume(target: string, level: number): Promise<void>;
+    setMuted(target: string, muted: boolean): Promise<void>;
+    /** Ends the running app (receiver STOP), which returns the device to its idle screen. Nothing running: nothing sent. */
+    stop(target: string): Promise<void>;
+    announce(target: string, clip: CastClip, options?: {
+        volume?: number;
+        timeoutMs?: number;
+    }): Promise<AnnounceResult>;
+};
+/** A payload as it came, before any schema. */
+export type RawPayload = {
+    type?: unknown;
+    requestId?: unknown;
+    reason?: unknown;
+    [key: string]: unknown;
+};
+/** Sees every payload a socket receives, then `undefined` once when it closes. */
+export type Listener = (raw: RawPayload | undefined) => void;
+/** What a write needs of one live socket. */
+export type CastSession = {
+    host: string;
+    port: number;
+    send(namespace: string, destination: string, payload: object): void;
+    nextId(): number;
+    listen(listener: Listener): () => void;
+    /** CONNECT to an app's transport, once per transport however many callers ask. */
+    connect(transport: string): void;
+    /** Close it after a discovery the caller just ran: it reconnects at the address the snapshot holds, without another discovery. */
+    end(why: string): void;
+};
+/** What `castActions` needs of the integration. */
+export type WriteContext = {
+    clock: Clock;
+    devices(): Record<string, CastDevice>;
+    session(id: string): CastSession | undefined;
+    discover(): Promise<void>;
+    /** The entry's socket once it is open at the address the snapshot holds, within `ms`. */
+    connected(id: string, ms: number): Promise<CastSession>;
+    serve?: ServeClip;
+};
+/** Writes over the integration's sockets. */
+export declare function castActions(ctx: WriteContext): CastActions;