@khalido/home 0.0.0-stage → 0.1.1

package/dist/connectors/cast/index.js

@@ -0,0 +1,428 @@
+import { z } from "zod";
+import { asOf, realClock } from "../../clock.js";
+import { errorText } from "../../connector.js";
+import { HOUR, lostDetail, rescanDelay } from "../../discover.js";
+import { poller } from "../../poll.js";
+import { NS } from "./codec.js";
+import { CastPayload, KNOWN_TYPES } from "./schemas.js";
+import { castKey, connection, found, mediaApp, reduce, } from "./state.js";
+import { castActions, } from "./writes.js";
+/** 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 const configSchema = z.looseObject({
+    connector: z.literal("cast"),
+    name: z
+        .string()
+        .describe("the device's or group's name in the Google Home app (mDNS fn), for display; `home discover --write` fills it and refreshes it after a rename"),
+    castId: z
+        .string()
+        .describe("the mDNS id, the stable identity; `home discover --write` fills it"),
+});
+/** Discovery's answers as `resolve` returns them: Cast entries only, port 8009 unless discovery said otherwise. */
+export const resolvedFrom = (found) => found.flatMap((f) => f.connector === "cast"
+    ? [
+        {
+            id: f.id,
+            name: f.name ?? f.id,
+            model: f.model,
+            host: f.host,
+            port: f.port ?? 8009,
+            group: f.group ?? false,
+        },
+    ]
+    : []);
+const SENDER = "sender-0";
+const RECEIVER = "receiver-0";
+const MAX_BACKOFF_MS = 60_000;
+/** A cached address gets this long to answer before discovery: live connects take 33–111 ms (Bun 1.4.2), a dead address hangs. */
+const CACHED_CONNECT_MS = 1000;
+/** A socket that has not answered its status request in this long is dropped, so the part never sits in "connecting". */
+const STATUS_TIMEOUT_MS = 10_000;
+/**
+ * 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 function cast(config) {
+    const clock = config.clock ?? realClock;
+    const pingMs = config.pingMs ?? 5000;
+    let snapshot = { devices: {}, asOf: asOf(clock) };
+    let resolved = false;
+    let resolveError;
+    let lastFound; // the ids the last discovery that ran returned
+    const anomalies = new Map();
+    const sessions = new Map();
+    const opened = new Set(); // woken whenever a socket opens, for a write waiting on a reconnect
+    const named = new Set(); // ids whose name came from the device (discovery's fn, its own multizone status), not a config
+    const loops = new Map();
+    let report;
+    let running;
+    let discovering;
+    const rescan = poller(clock); // the shared re-discovery's wait; a drop or a refresh nudges it
+    let attempt = 0; // re-discoveries since anything was last nudged or all up; a refresh starts it over
+    const publish = () => {
+        const all = Object.values(snapshot.devices);
+        const down = all.filter((d) => d.status === "disconnected");
+        const answered = (d) => d.status === "disconnected" || d.asOf !== undefined;
+        const status = !resolved || !all.every(answered)
+            ? "connecting"
+            : all.length && down.length < all.length
+                ? "connected"
+                : "disconnected";
+        const detail = resolveError ??
+            (all.length
+                ? down.length
+                    ? `${down.map((d) => d.name).join(", ")} disconnected`
+                    : undefined
+                : "no Cast devices found");
+        const anomaly = anomalies.size
+            ? [...anomalies]
+                .map(([id, a]) => `${snapshot.devices[id]?.name ?? id}: ${a}`)
+                .join("; ")
+            : undefined;
+        report?.({ status, detail, anomaly, state: snapshot });
+    };
+    /** One discovery at a time; each found entry not yet running gets its loop, each expected one not found shows as missing. */
+    const discover = () => (discovering ??= (async () => {
+        try {
+            const all = await config.resolve();
+            snapshot = found(snapshot, all, asOf(clock));
+            for (const r of all)
+                named.add(castKey(r.id));
+            lastFound = new Set(all.map((r) => castKey(r.id)));
+            resolveError = undefined;
+        }
+        catch (error) {
+            resolveError = `discovery failed: ${errorText(error)}`;
+        }
+        resolved = true;
+        const missing = (config.expect ?? []).filter((e) => !snapshot.devices[castKey(e.castId)]);
+        if (missing.length) {
+            const placeholders = missing.map((e) => [
+                castKey(e.castId),
+                {
+                    id: castKey(e.castId),
+                    name: e.name,
+                    kind: "device",
+                    status: "disconnected",
+                    detail: "not found by discovery",
+                },
+            ]);
+            snapshot = {
+                ...snapshot,
+                devices: { ...snapshot.devices, ...Object.fromEntries(placeholders) },
+            };
+        }
+        for (const d of Object.values(snapshot.devices))
+            if (d.host && !loops.has(d.id) && running)
+                loops.set(d.id, keep(d.id, running));
+        publish();
+    })().finally(() => (discovering = undefined)));
+    /** The socket's certificate must name this device, or for a group a known device, its leader. Returns the leader. */
+    const checkPeer = (id, peer) => {
+        const d = snapshot.devices[id];
+        if (!peer)
+            throw new Error("the socket has no certificate name");
+        if (d.kind === "device") {
+            if (castKey(peer) !== id)
+                throw new Error("the certificate names another device; the address has moved");
+            return undefined;
+        }
+        const leader = snapshot.devices[castKey(peer)];
+        if (leader?.kind !== "device")
+            throw new Error("the certificate names no known Cast device");
+        return leader.id;
+    };
+    /** Whether anything is missing or down, so the shared re-discovery keeps going. */
+    const needed = () => !Object.keys(snapshot.devices).length ||
+        Object.values(snapshot.devices).some((d) => d.status === "disconnected");
+    /** The one re-discovery loop: at once when nudged by a drop or a refresh, then at the relocator's cadence while anything stays down. */
+    async function rediscover(signal) {
+        while (!signal.aborted) {
+            const nudged = await rescan.wait(needed() ? rescanDelay(attempt) : HOUR, signal);
+            if (signal.aborted)
+                return;
+            if (!needed()) {
+                attempt = 0;
+                continue;
+            }
+            if (!nudged)
+                attempt++;
+            await discover();
+        }
+    }
+    /** One socket's life: open, check, ask, then apply what arrives until it closes. Throws why it ended; `up` says whether it got as far as connected. */
+    async function session(id, signal, up, timeoutMs) {
+        const d = snapshot.devices[id];
+        const channel = await config.connect({
+            host: d.host,
+            port: d.port,
+            signal,
+            timeoutMs,
+        });
+        const stop = new AbortController();
+        let requestId = 0;
+        const send = (namespace, destination, payload) => channel.send({
+            source: SENDER,
+            destination,
+            namespace,
+            payload: JSON.stringify(payload),
+        });
+        let closed = false;
+        const end = () => closed || ((closed = true), channel.close()); // abort and the finally both end it: close once
+        const leave = () => closed || (send(NS.connection, RECEIVER, { type: "CLOSE" }), end());
+        signal.addEventListener("abort", leave, { once: true });
+        const listeners = new Set();
+        const joined = new Set(); // transports CONNECTed on this socket
+        const s = {
+            host: d.host,
+            port: d.port,
+            send,
+            nextId: () => ++requestId,
+            listen: (listener) => (listeners.add(listener),
+                () => void listeners.delete(listener)),
+            connect: (transport) => void (joined.has(transport) ||
+                (joined.add(transport),
+                    send(NS.connection, transport, { type: "CONNECT" }))),
+            end: (why) => ((ended = why), (up.rediscovered = true), end()),
+            ask: (namespace, destination, type) => send(namespace, destination, { type, requestId: ++requestId }),
+        };
+        let heard = clock.now();
+        let ended; // why we closed it, if we did
+        let answered = false;
+        try {
+            const leader = checkPeer(id, channel.peer);
+            send(NS.connection, RECEIVER, { type: "CONNECT" });
+            s.ask(NS.receiver, RECEIVER, "GET_STATUS");
+            s.ask(NS.multizone, RECEIVER, "GET_STATUS"); // a group's members; a device's own current name
+            sessions.set(id, s);
+            for (const wake of [...opened])
+                wake();
+            up.connected = true;
+            snapshot = connection(snapshot, id, { status: "connected", leader }, asOf(clock));
+            config.seen?.(id, {
+                host: d.host,
+                port: d.port,
+                name: named.has(id) ? d.name : undefined,
+            }); // a config's name never reaches the cache
+            publish();
+            void (async () => {
+                while (!stop.signal.aborted) {
+                    await clock.sleep(pingMs, stop.signal);
+                    if (stop.signal.aborted)
+                        return;
+                    if (clock.now() - heard > 3 * pingMs)
+                        return ((ended = `silent for ${(3 * pingMs) / 1000} s`), end());
+                    send(NS.heartbeat, RECEIVER, { type: "PING" });
+                }
+            })();
+            void clock.sleep(STATUS_TIMEOUT_MS, stop.signal).then(() => {
+                if (!stop.signal.aborted && !answered)
+                    ((ended = `no status in ${STATUS_TIMEOUT_MS / 1000} s`), end());
+            });
+            for await (const m of channel.messages) {
+                heard = clock.now();
+                let raw;
+                try {
+                    raw = JSON.parse(m.payload ?? "");
+                }
+                catch {
+                    continue;
+                }
+                if (typeof raw !== "object" || raw === null)
+                    continue;
+                for (const listener of [...listeners])
+                    listener(raw); // a write's replies, refusals included, before the reducer's filter
+                if (m.namespace === NS.heartbeat && raw?.type === "PING")
+                    send(NS.heartbeat, m.source, { type: "PONG" });
+                if (m.namespace === NS.connection &&
+                    raw?.type === "CLOSE" &&
+                    m.source === RECEIVER)
+                    break;
+                if (typeof raw?.type !== "string" || !KNOWN_TYPES.has(raw.type))
+                    continue;
+                const parsed = CastPayload.safeParse(raw);
+                if (!parsed.success) {
+                    anomalies.set(id, `a ${raw.type} the schema did not recognise`);
+                    publish();
+                    continue;
+                }
+                const p = parsed.data;
+                if (p.type === "RECEIVER_STATUS") {
+                    answered = true;
+                    const app = p.status?.applications?.[0];
+                    const transport = mediaApp(app) ? app.transportId : undefined;
+                    if (transport && transport !== s.transport) {
+                        s.connect(transport);
+                        s.ask(NS.media, transport, "GET_STATUS");
+                    }
+                    s.transport = transport;
+                }
+                const name = snapshot.devices[id]?.name;
+                snapshot = reduce(snapshot, id, p, asOf(clock));
+                const renamed = snapshot.devices[id]?.name;
+                if (p.type === "MULTIZONE_STATUS" &&
+                    renamed !== undefined &&
+                    renamed !== name)
+                    (named.add(id),
+                        config.seen?.(id, { host: d.host, port: d.port, name: renamed }));
+                publish();
+            }
+            throw new Error(ended ?? "the device closed the socket");
+        }
+        finally {
+            stop.abort();
+            for (const listener of [...listeners])
+                listener(undefined);
+            sessions.delete(id);
+            signal.removeEventListener("abort", leave);
+            end();
+        }
+    }
+    /** Keep one entry connected until `signal` aborts: a drop nudges the shared re-discovery, then it reconnects with backoff. */
+    async function keep(id, signal, cached = false) {
+        for (let backoff = 1000; !signal.aborted; backoff = Math.min(backoff * 2, MAX_BACKOFF_MS)) {
+            const began = clock.now();
+            const up = {
+                connected: false,
+            };
+            try {
+                await session(id, signal, up, cached ? CACHED_CONNECT_MS : undefined);
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return;
+                if (cached) {
+                    // A cached address that fails is only stale: discover now and try where it answers, still "connecting".
+                    cached = false;
+                    await discover();
+                    // Unless discovery can't find it: then the address is the one that just failed, and a second try only waits out the timeout. The backoff still retries.
+                    if (!lastFound || lastFound.has(id))
+                        continue;
+                }
+                const why = errorText(error);
+                // A cached address the last discovery did not find says so, as a polling connector's does.
+                snapshot = connection(snapshot, id, {
+                    status: "disconnected",
+                    detail: lostDetail(lastFound && !lastFound.has(id) ? { seenHere: false } : {}, why),
+                }, asOf(clock));
+                publish();
+                if (up.connected && !up.rediscovered)
+                    rescan.nudge(); // a drop, not a failed retry: look once now; retries wait for the cadence. A write that closed it has just discovered.
+            }
+            if (clock.now() - began > MAX_BACKOFF_MS)
+                backoff = 1000; // it had been up a while: start the backoff over
+            await clock.sleep(backoff, signal);
+        }
+    }
+    /** The entry's socket once it is open at the address the snapshot now holds, within `ms`. */
+    async function connected(id, ms) {
+        const start = clock.now();
+        for (;;) {
+            const d = snapshot.devices[id];
+            const s = sessions.get(id);
+            if (s && d && s.host === d.host && s.port === d.port)
+                return s;
+            const left = start + ms - clock.now();
+            if (left <= 0)
+                throw new Error(`${d?.name ?? id} did not connect in ${ms / 1000} s`);
+            const woken = new AbortController();
+            const wake = () => woken.abort();
+            opened.add(wake);
+            await clock.sleep(left, woken.signal);
+            opened.delete(wake);
+        }
+    }
+    return {
+        ...castActions({
+            clock,
+            devices: () => snapshot.devices,
+            session: (id) => sessions.get(id),
+            discover,
+            connected,
+            serve: config.serve,
+        }),
+        name: "cast",
+        /** Re-ask every open socket for its status; while an entry is missing or down, discover again too. */
+        refresh() {
+            for (const s of sessions.values()) {
+                s.ask(NS.receiver, RECEIVER, "GET_STATUS");
+                s.ask(NS.multizone, RECEIVER, "GET_STATUS");
+                if (s.transport)
+                    s.ask(NS.media, s.transport, "GET_STATUS");
+            }
+            attempt = 0; // as the relocator's reset: the cadence starts over
+            rescan.nudge(); // discovers if anything is missing or down, even with nothing found yet
+        },
+        async run(signal, update) {
+            report = update;
+            running = signal;
+            const expect = config.expect ?? [];
+            const cached = expect.filter((e) => e.host !== undefined && e.port !== undefined);
+            snapshot = found(snapshot, cached.map((e) => ({
+                id: e.castId,
+                name: e.name,
+                host: e.host,
+                port: e.port,
+                group: e.port !== 8009,
+            })), asOf(clock));
+            for (const d of Object.values(snapshot.devices))
+                loops.set(d.id, keep(d.id, signal, true));
+            if (expect.length && cached.length === expect.length)
+                resolved = true;
+            else
+                await discover();
+            publish();
+            const rediscovery = rediscover(signal);
+            await new Promise((resolve) => signal.aborted
+                ? resolve()
+                : signal.addEventListener("abort", () => resolve(), { once: true }));
+            await Promise.all([rediscovery, ...loops.values()]);
+        },
+    };
+}
+/** 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 function castText(d, s) {
+    const name = (id) => (id && s.devices[id]?.name) || id;
+    if (d.status !== "connected")
+        return `${d.name}: ${d.status}${d.detail ? ` (${d.detail})` : ""}`;
+    const media = d.playerState &&
+        `${d.playerState.toLowerCase()}${d.title ? ` "${d.title}"` : ""}${d.artist ? ` by ${d.artist}` : ""}${d.playingVia ? ` via ${name(d.playingVia)}` : ""}`;
+    const parts = [
+        d.standby ? "standby" : d.idle ? "idle" : (d.app ?? ""),
+        media ?? "",
+        d.muted
+            ? "muted"
+            : d.volumeControl === "fixed"
+                ? "fixed volume"
+                : d.volume === undefined
+                    ? ""
+                    : `${Math.round(d.volume * 100)}%`,
+        d.kind === "group"
+            ? `${d.members?.length ?? "?"} members${d.members?.length ? `: ${d.members.map(name).join(", ")}` : ""}${d.leader ? `, led by ${name(d.leader)}` : ""}`
+            : "",
+    ];
+    return `${d.name}: ${parts.filter(Boolean).join(" · ")}`;
+}
+/** Devices first, then groups, each by name. */
+export const castDevices = (s) => Object.values(s.devices).sort((a, b) => a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name));
+/** How many entries have an address, and one line per device and group. */
+const castView = (s) => ({
+    found: Object.values(s.devices).filter((d) => d.host).length,
+    lines: castDevices(s).map((d) => castText(d, s)),
+});
+export const manifest = {
+    name: "cast",
+    title: "Google Cast",
+    iotClass: "local_push",
+    access: "local CastV2 over TLS, no key; certificates self-signed, their names checked",
+    env: [],
+    lines({ state }) {
+        if (!state)
+            return [];
+        const { found, lines } = castView(state);
+        return [`${found} found`, ...lines];
+    },
+    record: ({ state }) => state ? { ...castView(state), devices: state.devices } : {},
+};

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

@@ -0,0 +1,167 @@
+import { z } from "zod";
+export declare const Application: z.ZodObject<{
+    appId: z.ZodOptional<z.ZodString>;
+    displayName: z.ZodOptional<z.ZodString>;
+    isIdleScreen: z.ZodOptional<z.ZodBoolean>;
+    namespaces: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    statusText: z.ZodOptional<z.ZodString>;
+    transportId: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type Application = z.infer<typeof Application>;
+export declare const ReceiverStatus: z.ZodObject<{
+    type: z.ZodLiteral<"RECEIVER_STATUS">;
+    status: z.ZodOptional<z.ZodObject<{
+        applications: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            appId: z.ZodOptional<z.ZodString>;
+            displayName: z.ZodOptional<z.ZodString>;
+            isIdleScreen: z.ZodOptional<z.ZodBoolean>;
+            namespaces: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>>;
+            sessionId: z.ZodOptional<z.ZodString>;
+            statusText: z.ZodOptional<z.ZodString>;
+            transportId: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+        isStandBy: z.ZodOptional<z.ZodBoolean>;
+        isActiveInput: z.ZodOptional<z.ZodBoolean>;
+        volume: z.ZodOptional<z.ZodObject<{
+            controlType: z.ZodOptional<z.ZodString>;
+            level: z.ZodOptional<z.ZodNumber>;
+            muted: z.ZodOptional<z.ZodBoolean>;
+            stepInterval: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export declare const MediaStatus: z.ZodObject<{
+    type: z.ZodLiteral<"MEDIA_STATUS">;
+    status: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        mediaSessionId: z.ZodOptional<z.ZodNumber>;
+        playerState: z.ZodOptional<z.ZodString>;
+        idleReason: z.ZodOptional<z.ZodString>;
+        currentTime: z.ZodOptional<z.ZodNumber>;
+        media: z.ZodOptional<z.ZodObject<{
+            contentId: z.ZodOptional<z.ZodString>;
+            contentType: z.ZodOptional<z.ZodString>;
+            streamType: z.ZodOptional<z.ZodString>;
+            duration: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            metadata: z.ZodOptional<z.ZodObject<{
+                title: z.ZodOptional<z.ZodString>;
+                artist: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export declare const MultizoneStatus: z.ZodObject<{
+    type: z.ZodLiteral<"MULTIZONE_STATUS">;
+    status: z.ZodOptional<z.ZodObject<{
+        devices: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            deviceId: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+            volume: z.ZodOptional<z.ZodObject<{
+                controlType: z.ZodOptional<z.ZodString>;
+                level: z.ZodOptional<z.ZodNumber>;
+                muted: z.ZodOptional<z.ZodBoolean>;
+                stepInterval: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/** A group's membership changing while connected: added and updated carry the member, removed only its id. */
+export declare const MemberChange: z.ZodObject<{
+    type: z.ZodEnum<{
+        DEVICE_ADDED: "DEVICE_ADDED";
+        DEVICE_REMOVED: "DEVICE_REMOVED";
+        DEVICE_UPDATED: "DEVICE_UPDATED";
+    }>;
+    device: z.ZodOptional<z.ZodObject<{
+        deviceId: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        volume: z.ZodOptional<z.ZodObject<{
+            controlType: z.ZodOptional<z.ZodString>;
+            level: z.ZodOptional<z.ZodNumber>;
+            muted: z.ZodOptional<z.ZodBoolean>;
+            stepInterval: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    deviceId: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/** Every payload the reducer reads; anything else (PONG, LAUNCH_STATUS, …) fails to parse and is ignored by type. */
+export declare const CastPayload: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"RECEIVER_STATUS">;
+    status: z.ZodOptional<z.ZodObject<{
+        applications: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            appId: z.ZodOptional<z.ZodString>;
+            displayName: z.ZodOptional<z.ZodString>;
+            isIdleScreen: z.ZodOptional<z.ZodBoolean>;
+            namespaces: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>>;
+            sessionId: z.ZodOptional<z.ZodString>;
+            statusText: z.ZodOptional<z.ZodString>;
+            transportId: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+        isStandBy: z.ZodOptional<z.ZodBoolean>;
+        isActiveInput: z.ZodOptional<z.ZodBoolean>;
+        volume: z.ZodOptional<z.ZodObject<{
+            controlType: z.ZodOptional<z.ZodString>;
+            level: z.ZodOptional<z.ZodNumber>;
+            muted: z.ZodOptional<z.ZodBoolean>;
+            stepInterval: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>, z.ZodObject<{
+    type: z.ZodLiteral<"MEDIA_STATUS">;
+    status: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        mediaSessionId: z.ZodOptional<z.ZodNumber>;
+        playerState: z.ZodOptional<z.ZodString>;
+        idleReason: z.ZodOptional<z.ZodString>;
+        currentTime: z.ZodOptional<z.ZodNumber>;
+        media: z.ZodOptional<z.ZodObject<{
+            contentId: z.ZodOptional<z.ZodString>;
+            contentType: z.ZodOptional<z.ZodString>;
+            streamType: z.ZodOptional<z.ZodString>;
+            duration: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            metadata: z.ZodOptional<z.ZodObject<{
+                title: z.ZodOptional<z.ZodString>;
+                artist: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>, z.ZodObject<{
+    type: z.ZodLiteral<"MULTIZONE_STATUS">;
+    status: z.ZodOptional<z.ZodObject<{
+        devices: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            deviceId: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+            volume: z.ZodOptional<z.ZodObject<{
+                controlType: z.ZodOptional<z.ZodString>;
+                level: z.ZodOptional<z.ZodNumber>;
+                muted: z.ZodOptional<z.ZodBoolean>;
+                stepInterval: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>, z.ZodObject<{
+    type: z.ZodEnum<{
+        DEVICE_ADDED: "DEVICE_ADDED";
+        DEVICE_REMOVED: "DEVICE_REMOVED";
+        DEVICE_UPDATED: "DEVICE_UPDATED";
+    }>;
+    device: z.ZodOptional<z.ZodObject<{
+        deviceId: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        volume: z.ZodOptional<z.ZodObject<{
+            controlType: z.ZodOptional<z.ZodString>;
+            level: z.ZodOptional<z.ZodNumber>;
+            muted: z.ZodOptional<z.ZodBoolean>;
+            stepInterval: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+    deviceId: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>], "type">;
+export type CastPayload = z.infer<typeof CastPayload>;
+/** The types the reducer knows; a payload of one of these that fails its schema is an anomaly, any other type is ignored. */
+export declare const KNOWN_TYPES: Set<string>;

package/dist/connectors/cast/schemas.js

@@ -0,0 +1,87 @@
+import { z } from "zod";
+// The JSON payloads a state reader receives, every field optional, unknown fields kept. Shapes from the live devices
+// (2026-10-13, see README) and pychromecast for media status, which nothing was playing to record.
+const Volume = z.looseObject({
+    controlType: z.string().optional(), // "master" | "attenuation" | "fixed"
+    level: z.number().optional(),
+    muted: z.boolean().optional(),
+    stepInterval: z.number().optional(),
+});
+export const Application = z.looseObject({
+    appId: z.string().optional(),
+    displayName: z.string().optional(),
+    isIdleScreen: z.boolean().optional(),
+    namespaces: z
+        .array(z.looseObject({ name: z.string().optional() }))
+        .optional(),
+    sessionId: z.string().optional(),
+    statusText: z.string().optional(),
+    transportId: z.string().optional(),
+});
+export const ReceiverStatus = z.looseObject({
+    type: z.literal("RECEIVER_STATUS"),
+    status: z
+        .looseObject({
+        applications: z.array(Application).optional(),
+        isStandBy: z.boolean().optional(),
+        isActiveInput: z.boolean().optional(),
+        volume: Volume.optional(),
+    })
+        .optional(),
+});
+export const MediaStatus = z.looseObject({
+    type: z.literal("MEDIA_STATUS"),
+    status: z
+        .array(z.looseObject({
+        mediaSessionId: z.number().optional(),
+        playerState: z.string().optional(), // "PLAYING" | "PAUSED" | "BUFFERING" | "IDLE"
+        idleReason: z.string().optional(), // "FINISHED" | "CANCELLED" | "INTERRUPTED" | "ERROR"
+        currentTime: z.number().optional(), // seconds into the media
+        media: z
+            .looseObject({
+            contentId: z.string().optional(),
+            contentType: z.string().optional(),
+            streamType: z.string().optional(),
+            duration: z.number().nullish(), // seconds; null for a live stream
+            metadata: z
+                .looseObject({
+                title: z.string().optional(),
+                artist: z.string().optional(),
+            })
+                .optional(),
+        })
+            .optional(),
+    }))
+        .optional(),
+});
+const Member = z.looseObject({
+    deviceId: z.string().optional(),
+    name: z.string().optional(),
+    volume: Volume.optional(),
+});
+export const MultizoneStatus = z.looseObject({
+    type: z.literal("MULTIZONE_STATUS"),
+    status: z.looseObject({ devices: z.array(Member).optional() }).optional(),
+});
+/** A group's membership changing while connected: added and updated carry the member, removed only its id. */
+export const MemberChange = z.looseObject({
+    type: z.enum(["DEVICE_ADDED", "DEVICE_UPDATED", "DEVICE_REMOVED"]),
+    device: Member.optional(),
+    deviceId: z.string().optional(),
+});
+/** Every payload the reducer reads; anything else (PONG, LAUNCH_STATUS, …) fails to parse and is ignored by type. */
+export const CastPayload = z.discriminatedUnion("type", [
+    ReceiverStatus,
+    MediaStatus,
+    MultizoneStatus,
+    MemberChange,
+]);
+/** The types the reducer knows; a payload of one of these that fails its schema is an anomaly, any other type is ignored. */
+export const KNOWN_TYPES = new Set([
+    "RECEIVER_STATUS",
+    "MEDIA_STATUS",
+    "MULTIZONE_STATUS",
+    "DEVICE_ADDED",
+    "DEVICE_UPDATED",
+    "DEVICE_REMOVED",
+]);