@khalido/home 0.0.0-stage → 0.1.0

package/src/connectors/amber/README.md

@@ -0,0 +1,40 @@
+# Amber
+
+Amber Electric's live wholesale-linked prices, read through Amber's public API. Cloud, not local: one HTTPS call with a key. `iot_class`: **cloud_polling**, every 60 s.
+
+## Built
+
+- `amber({ key, fetch })` finds the account's active site once, then polls `GET /v1/sites/{id}/prices/current?next=96` every 60 s (Home Assistant's amberelectric integration polls every minute too). One call took about 270 ms with `next=1` (measured, Bun 1.4.2); `next=96` returns about 52 intervals instead of 3.
+- `toPrices` keeps the **CurrentInterval** of each channel: `importCents` (general), `exportCents` (feed-in, sign flipped so it reads as what you are paid), `priceDescriptor` (the general channel's descriptor) and `exportDescriptor`, `spike` (Amber's own `spikeStatus`: `none`, `potential`, `spike`; the library sets no threshold), `renewables`, `estimate`, and the next interval's import forecast.
+- `forecast`: the current interval, then each forecast one, both channels on one row (`PriceInterval`). `next=96` asks for more than Amber has, so the reply runs as far as Amber forecasts: on 2026-10-28 at 3 pm, 12 five-minute intervals then 14 half-hours, to 11 pm. Amber's `startTime` is a second past the interval's start, so `start` is taken to the minute.
+- `estimate: true` means the current interval's price can still move; it is shown as "(estimate)", never as an anomaly.
+- The Amber line in `home status` shows the descriptor, "(estimate)", a spike other than `none`, and a negative price. `energyNow` combines the prices with Enphase; see Energy below.
+- A 401 marks Amber unavailable and stops polling.
+
+## Energy
+
+`energyNow(enphase, amber)` in `src/energy.ts` is the one place the two combine, so the CLI, jaldi and the bot show the same numbers.
+
+- **Now**: solar, use, grid flow, and what the grid flow costs or earns per hour (`centsPerHour`), plus Amber's descriptor, spike and estimate.
+- **Negative prices**: `negativePrice` is "paid to use" when the import price is below zero, else "exporting at a loss" when the feed-in price is. Both can hold in one interval; the import side wins.
+- **Surplus**: `surplusW` is the export as a positive number (`-gridW` while exporting, else 0; undefined with no grid reading), and `surplusCentsPerHour` what it earns at the export price, negative when exporting costs you, never clamped.
+- **Best window**: `bestWindow(forecast, hours, { by, from })` is the cheapest run of `hours` by import price, or the greenest by renewables, averaged by time over unbroken intervals; undefined when the forecast is shorter or broken. An average some interval lacks is left out (a greenest window can have no `importCents`). A forecast row whose times do not parse is left out and counted in `anomaly`. It ranks by `perKwh`, not Amber's `advancedPrice.predicted` (14.70c against 15.56c on the first forecast interval of the fixture). On the 2026-10-28 forecast (`test/fixtures/amber/forecast.json`, read at 3 pm Sydney) the cheapest 2 hours were 3:40–5:40 pm at 13.7c. Solar is not in it: Enphase has no forecast.
+- **Renewables above 100%**: the same forecast has 101.17 and 102.6. Passed through as Amber sends them.
+- **Flow**: `"importing"`, `"exporting"` or `"balanced"`. Balanced is a display rule: within `BALANCED_W` (20 W) of zero the word and any animation say balanced, so a meter wobbling around zero does not flip; `gridW` and `surplusW` stay as read.
+- **Words and drawing**: `gridText(now)` gives the phrase every view shares ("exporting 1.2 kW, earning 42 c/h"), which `home status` prints in its `now` line. `solarLevel(now, capacityW)` scales solar for a drawing against the array's rated size or, without it, today's peak, and says which.
+
+## What the API said (KO's account, 2026-10-13)
+
+- `GET /v1/sites`: one active site, its network named, `intervalLength: 5`, channels `general` and `feedIn`.
+- `GET …/prices/current?next=1&previous=1`: for each channel an `ActualInterval`, a `CurrentInterval` (with `estimate`) and a `ForecastInterval` (with `advancedPrice`). Fields: `perKwh` and `spotPerKwh` (c/kWh incl. GST), `renewables` (%), `descriptor`, `spikeStatus`, `startTime`, `endTime`, `nemTime`, `tariffInformation`.
+- **Rate limit** from the response headers: `ratelimit-policy: 50;w=300`, so 50 calls per 5 minutes. A 60 s poll uses 5.
+- **Feed-in sign**: the feed-in `perKwh` was −35.3 with spot at +33.1 and descriptor `high`, so a negative feed-in price means you are paid. Amber's spec does not say this; it is inferred from the live reply. A positive feed-in price would mean exporting costs you.
+- Prices move in 5-minute intervals and the current one is revised until `estimate` is false, so polling faster than a minute adds nothing; slower than 5 minutes misses intervals.
+
+## Sources
+
+| Source                                                                                                                   | Licence        | Used for                                                                                                                                                                                                   |
+| ------------------------------------------------------------------------------------------------------------------------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Amber developer page](https://app.amber.com.au/developers)                                                              | Amber's terms  | the key and the API                                                                                                                                                                                        |
+| [amberelectric/public-api](https://github.com/amberelectric/public-api) (`swagger.json`)                                 | MIT per GitHub | endpoints, field enums (`descriptor`: extremelyLow, veryLow, low, neutral, high, spike, and the retired negative; `spikeStatus`: none, potential, spike); the spec is version 1.0 at `/v1`, there is no v2 |
+| [Home Assistant `amberelectric`](https://github.com/home-assistant/core/tree/dev/homeassistant/components/amberelectric) | Apache-2.0     | 1-minute poll, current plus forecast intervals                                                                                                                                                             |

package/src/connectors/amber/client.ts

@@ -0,0 +1,157 @@
+import { z } from "zod";
+import { ConnectorError, getJson } from "../../connector.ts";
+
+// Amber Electric's public API v1 (https://app.amber.com.au/developers; the published spec is 1.0, there is no v2). Shapes checked against live replies,
+// 2026-10-13; every field optional so a change degrades a reading rather than throwing.
+
+/** A failed Amber call. `status` 401 means the key is wrong or revoked; 429 means the rate limit (50 per 5 min). */
+export class AmberError extends ConnectorError {}
+
+/** One 5-minute price interval on one channel. Prices are c/kWh including GST, as a cost: negative feed-in means you are paid. */
+export const Interval = z.looseObject({
+  type: z.string(), // "ActualInterval" | "CurrentInterval" | "ForecastInterval"
+  channelType: z.string(), // "general" (import) | "feedIn" (export) | "controlledLoad"
+  perKwh: z.number(),
+  spotPerKwh: z.number().optional(),
+  renewables: z.number().optional(), // percent of the grid
+  descriptor: z.string().optional(), // "extremelyLow" … "spike"
+  spikeStatus: z.string().optional(), // "none" | "potential" | "spike"
+  startTime: z.string().optional(),
+  endTime: z.string().optional(),
+  estimate: z.boolean().optional(), // CurrentInterval: true until the interval's price is final
+  duration: z.number().optional(), // minutes: 5 for the current hour, 30 further out
+});
+export type Interval = z.infer<typeof Interval>;
+
+const Site = z.looseObject({
+  id: z.string(),
+  status: z.string().optional(),
+  intervalLength: z.number().optional(),
+});
+
+/** Prices now, as a home view wants them: what a kWh costs to import and earns to export. */
+export type AmberState = {
+  importCents?: number; // c/kWh you pay now
+  exportCents?: number; // c/kWh you are paid now (Amber's negative feed-in price, sign flipped)
+  priceDescriptor?: string; // the general (import) channel's descriptor: "extremelyLow" | "veryLow" | "low" | "neutral" | "high" | "spike" ("negative" is legacy)
+  exportDescriptor?: string;
+  spike?: string; // Amber's own spikeStatus on the general channel: "none" | "potential" | "spike"; no threshold of ours
+  renewables?: number; // percent
+  estimate?: boolean; // true while the current interval's price can still move; information, not an anomaly
+  nextImportCents?: number; // the next interval's forecast
+  intervalEnds?: string;
+  anomaly?: string; // forecast intervals left out because their times could not be read
+  forecast?: PriceInterval[]; // the current interval, then Amber's forecast, as far ahead as Amber has one (about 8 hours, 2026-10-28)
+};
+
+/**
+ * One interval of the forecast, both channels. `start` is the interval's own start: Amber's `startTime` is a second past
+ * it (07:15:01 for 07:15–07:20), so it is taken to the minute. `exportCents` is what you are paid, as in `AmberState`.
+ */
+export type PriceInterval = {
+  start: string;
+  end: string;
+  importCents?: number;
+  exportCents?: number;
+  renewables?: number;
+  descriptor?: string;
+};
+
+/** How many intervals to ask for: more than Amber forecasts (48 half-hours), so the reply is as far as Amber has one. */
+export const NEXT = 96;
+
+/** Map `prices/current?next=…` to the state: the CurrentInterval of each channel, the next import forecast, and the forecast. */
+export function toPrices(intervals: unknown): AmberState {
+  const list = z.array(Interval).parse(intervals);
+  const pick = (type: string, channel: string) =>
+    list.find((i) => i.type === type && i.channelType === channel);
+  const buy = pick("CurrentInterval", "general");
+  const sell = pick("CurrentInterval", "feedIn");
+  return {
+    importCents: buy?.perKwh,
+    exportCents: sell === undefined ? undefined : -sell.perKwh,
+    priceDescriptor: buy?.descriptor,
+    exportDescriptor: sell?.descriptor,
+    spike: buy?.spikeStatus,
+    renewables: buy?.renewables,
+    estimate: buy?.estimate,
+    nextImportCents: pick("ForecastInterval", "general")?.perKwh,
+    intervalEnds: buy?.endTime,
+    ...forecastOf(list),
+  };
+}
+
+const MINUTE = 60_000;
+
+/**
+ * The current and forecast intervals, in time order, each channel's price on one row; none when Amber sent none. An interval
+ * whose times do not parse is left out and counted in `anomaly`, so one odd row never fails the prices.
+ */
+function forecastOf(
+  list: Interval[],
+): Pick<AmberState, "forecast" | "anomaly"> {
+  const timed = list.filter(
+    (i) => i.type === "CurrentInterval" || i.type === "ForecastInterval",
+  );
+  const ahead = timed.filter(
+    (i) =>
+      Number.isFinite(Date.parse(i.startTime ?? "")) &&
+      Number.isFinite(Date.parse(i.endTime ?? "")),
+  );
+  const odd = timed.length - ahead.length;
+  const feedIn = new Map(
+    ahead.filter((i) => i.channelType === "feedIn").map((i) => [i.endTime, i]),
+  );
+  const rows = ahead
+    .filter((i) => i.channelType === "general")
+    .map((i) => {
+      const sell = feedIn.get(i.endTime);
+      return {
+        start: new Date(
+          Math.floor(Date.parse(i.startTime!) / MINUTE) * MINUTE,
+        ).toISOString(),
+        end: new Date(Date.parse(i.endTime!)).toISOString(),
+        importCents: i.perKwh,
+        exportCents: sell === undefined ? undefined : -sell.perKwh,
+        renewables: i.renewables,
+        descriptor: i.descriptor,
+      };
+    })
+    .sort((a, b) => a.start.localeCompare(b.start));
+  return {
+    forecast: rows.length ? rows : undefined,
+    anomaly: odd
+      ? `${odd} price row(s) left out: their start or end time could not be read`
+      : undefined,
+  };
+}
+
+/** A read-only client for Amber's API. The key comes in; nothing is stored. */
+export function amberClient(options: { key: string; fetch: typeof fetch }) {
+  const headers = {
+    authorization: `Bearer ${options.key}`,
+    accept: "application/json",
+  };
+  const get = (path: string, signal?: AbortSignal) =>
+    getJson(options.fetch, `https://api.amber.com.au/v1${path}`, {
+      init: { headers },
+      signal,
+      error: AmberError,
+    });
+  return {
+    get,
+    /** The account's active site id (the first active one). */
+    async siteId(signal?: AbortSignal): Promise<string> {
+      const sites = z.array(Site).parse(await get("/sites", signal));
+      const site = sites.find((s) => s.status === "active") ?? sites[0];
+      if (!site) throw new AmberError("no Amber site on this account");
+      return site.id;
+    },
+    /** Prices now and the forecast for a site: one call, ~270 ms (measured with `next=1`, Bun 1.4.2). */
+    async prices(siteId: string, signal?: AbortSignal): Promise<AmberState> {
+      return toPrices(
+        await get(`/sites/${siteId}/prices/current?next=${NEXT}`, signal),
+      );
+    },
+  };
+}

package/src/connectors/amber/index.ts

@@ -0,0 +1,118 @@
+import { asOf, type Clock, realClock } from "../../clock.ts";
+import { errorText } from "../../connector.ts";
+import { z } from "zod";
+import { envName, type Integration } from "../../home.ts";
+import { energyNow } from "../../energy.ts";
+import { field, type Manifest } from "../../manifest.ts";
+import { poller } from "../../poll.ts";
+import { amberClient, AmberError, type AmberState } from "./client.ts";
+
+export {
+  AmberError,
+  type AmberState,
+  amberClient,
+  type Interval,
+  type PriceInterval,
+} from "./client.ts";
+
+/** 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 settings for a home. `siteId` is looked up once when left out. */
+export type AmberConfig = {
+  key: string;
+  siteId?: string;
+  fetch: typeof fetch;
+  clock?: Clock;
+};
+
+/** What the snapshot holds: prices now and when they were read. */
+export type AmberSnapshot = AmberState & { asOf: string };
+
+/** Amber prices as a home integration: one read now, then every 60 s. */
+export function amber(
+  config: AmberConfig,
+): Integration<AmberSnapshot, "amber"> {
+  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: AmberSnapshot | undefined;
+      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: AmberState): string {
+  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: Manifest<AmberSnapshot> = {
+  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/src/connectors/cast/README.md

@@ -0,0 +1,43 @@
+# Google Cast
+
+Nest speakers, Nest Hubs, Chromecasts, Google TV and speaker groups, read over CastV2 on the local network. `iot_class`: **local_push** (one socket per device or group, status pushed, a PING every 5 s). The integration only reads; the writes (volume, mute, stop, announcements) are calls on the same object, never made by the integration itself, and so far tried only on a scripted fake socket. The design and what comes next (casting a page) are in [docs/cast.md](../../../docs/cast.md).
+
+## Built
+
+- `cast({ resolve, connect })` keeps every Cast device and group current as one integration. `resolve()` returns what mDNS `_googlecast._tcp` found (`id`, `name` from TXT `fn`, `model` from `md`, host, port, `group`); the CLI runs `dns-sd`. `connect` is `tlsConnect` from `@khalido/home/cast/tls`. `expect` lists the config's entries, so one discovery misses shows as disconnected rather than vanishing. From a config, `resolve` is the shared two-pass discovery, done after the first pass once every entry has answered. An entry with a cached address (the address cache, `loadHome`'s `cache`) connects at once with a 1 s timeout; discovery runs only when an entry has none or a cached address fails, so a stale one still reads as `connecting` until discovery has had its say. A cached port other than 8009 marks a group, since devices always listen on 8009.
+- Per socket: `CONNECT` to `receiver-0`, receiver `GET_STATUS`, multizone `GET_STATUS` (a group's members; on a device's own port, the device alone, by its current name), then whatever the device pushes. A running app with the media namespace gets a `CONNECT` and media `GET_STATUS` on its `transportId`, as Home Assistant does. A device's `PING` is answered with `PONG`; a socket silent for three heartbeats (15 s), or without a receiver status 10 s after connecting, is closed and the detail says which.
+- A dropped socket reconnects with backoff (1 s doubling to 60 s) at whatever address discovery last gave. The drop starts one shared `resolve()` at once (a group's address changes with its leader); while anything stays down or missing, that one discovery repeats at 1, 5 and 15 minutes, then hourly, as the relocator does, never once per socket. `refresh()` re-asks every open socket and nudges the discovery, which also finds devices when nothing was found at start.
+- The part is `connecting` until every device has answered or failed, then `connected` while any is up; `detail` names the ones down. A payload of a known type the schema rejects is an `anomaly`, never thrown.
+- State (`CastSnapshot`, by mDNS id): app, `idle` (no app, or Backdrop's `isIdleScreen`), `standby`, volume (unrounded), muted, `volumeControl`, player state, title, artist; groups carry `members` and `leader`; devices carry `groups`, and `playingVia` when they show a playing group's media because their own is empty (Home Assistant's model, not yet seen live).
+- Names: a device's `name` in the snapshot is its own, from discovery's `fn` or its own multizone status (the same text on all six live devices, 2026-10-13), so a rename in the Google Home app shows once the device answers, even when every address came from the cache and discovery never ran; the config's name is only the placeholder until then. A group's multizone status lists its members, not itself, so a group's new name shows at the next discovery.
+- Writes, on the object `cast()` returns (`CastActions`), over the sockets it already holds, never a second connection. A target is a name (any case) or a castId; volume is 0 to 1, as the snapshot's. `setVolume`, `setMuted` (receiver `SET_VOLUME`; a group's goes to the group's socket; per device, levels and mutes each at most 30 a minute, the newest waiting one winning; one device's lane never waits on another's) and `stop` (receiver `STOP` of the running app; nothing when idle). Each request waits 10 s for its reply and a refusal (`LAUNCH_ERROR`, `LOAD_FAILED`, …) rejects, naming it.
+- `announce(target, clip, { volume?, timeoutMs? })`: `clip` is `{ url, type? }` or `{ bytes, type }`, bytes served through `serve` (`serveClip` from `@khalido/home/cast/serve`, passed to `cast()`). It reads the receiver status (and a Default Media Receiver's media status), for a group re-runs discovery first and reconnects if the leader moved, sets the volume if given and unmutes a muted target (as two requests: a `SET_VOLUME` takes a level or a mute, not both), launches the Default Media Receiver (`CC1AD845`), `LOAD`s the clip and waits for its media session to go `IDLE` with `FINISHED` (60 s plus the clip's length when the device reports it, or `timeoutMs`). Then, always: what the Default Media Receiver was playing is loaded again at its `currentTime`, an idle device gets `STOP`, then the volume and mute (a group's member by member, through each member's own socket, from the group's multizone status). Another app (Spotify, YouTube) is interrupted, as Google's own announcements do, and the result names it in `notRestored`. It returns `{ played, why?, restored, notRestored }` and throws only before anything changed (an unknown target, a socket down).
+- `serveClip(bytes, type, { host?, signal? })` (`node:http`, Node-only like `tls.ts`): an address of this machine on the target's network (else the first non-internal IPv4), a random port and an unguessable path, `Content-Type` and `Content-Length`; the whole body to every GET and HEAD (a `Range` probe gets a full 200, which HTTP allows), so a player that probes before it fetches still gets the clip. It closes on `close()`, which `announce` calls once the clip has played, when `signal` aborts, or after 60 s. Not yet seen live: how the Default Media Receiver fetches, and the macOS local-network prompt the first serve may raise.
+- CLI: `home cast announce --to <name> (--say "<text>" | --file <path>) [--volume 0-100]`, `home cast volume <name> <0-100>`, `home cast mute <name> on|off`, `home cast stop <name>`. `--say` runs `say -o <tmp>.m4a --file-format=m4af --data-format=aac` (without the data format, m4af holds uncompressed PCM), serves it as `audio/mp4` and deletes the file. The library never runs `say`.
+- Config: one entry per device or group, `{ "connector": "cast", "name": "…", "castId": "…" }`, all folded into one `cast` integration; `home discover --write` fills them and refreshes a renamed entry's `name` (the same `castId` with a new `fn`), printed as `renamed`. No host: discovery gives every address.
+
+## Protocol
+
+CastV2 is TLS to port 8009 (a group: its own port), carrying length-prefixed protobuf `CastMessage`s (`cast_channel.proto`: version, source, destination, namespace, payload type, payload). Every namespace here sends JSON in `payload_utf8`, so `codec.ts` encodes and decodes that one message by hand (about 100 lines with framing and the channel type) rather than taking `protobufjs`. Namespaces: `tp.connection` (`CONNECT`, `CLOSE`), `tp.heartbeat` (`PING`, `PONG`), `receiver` (`GET_STATUS` → `RECEIVER_STATUS`), `media` (on an app's transport), `multizone` (`GET_STATUS` → `MULTIZONE_STATUS`, then `DEVICE_ADDED`, `DEVICE_UPDATED`, `DEVICE_REMOVED`).
+
+**Live, KO's seven entries, 2026-10-13 (Bun 1.4.2, read-only).** Every one answered TLS plus both `GET_STATUS`es in 33–111 ms; TLS 1.2 on the Nest Mini and Home Speaker, 1.3 elsewhere. The recorded payloads, ids and names replaced, are in `test/fixtures/cast/`.
+
+- **Certificates** are self-signed, valid 48 hours, so they rotate. The name (CN) is the device's id as a dashed UUID: the mDNS `id` with dashes.
+- **Groups.** A group is its own mDNS entry, at its leader's address on a high port, and presents **its leader's certificate**. Multizone status on the group's port lists the members (by `deviceId`, the same dashed id) with their volumes; on a device's own port it lists only that device, so membership is read from group sockets only. TXT `rm` does not mark membership. `GET_CASTING_GROUPS` is refused.
+- **Receiver status**: hubs and the Chromecast Ultra run Backdrop (`E8C28D3C`) with `isIdleScreen: true`; the speakers report no application; the TV Streamer reports `isStandBy: true`, `isActiveInput: false` and a `fixed` volume; the Ultra's volume is `attenuation`.
+- No device sent a `PING` in 12 s of listening, so our 5 s ping is what keeps the socket's silence check honest.
+- Not seen yet: media status (nothing was playing), a group playing, a leader change, member changes, and Node's `tls` (no Node caller yet).
+
+## TLS: verification off, the name checked
+
+As with [Enphase](../enphase/README.md#tls-why-the-bun-path-skips-verification), verification is off, here because there is nothing to verify against: each device signs its own certificate and rotates it every two days, and Google's device-auth challenge would need its Cast root. Instead `cast()` checks the certificate's name against discovery: a device's must be its own id, and a group's must be a known device's id, which is then its `leader`. A mismatch (an address now held by another device) closes the socket and discovers again. What this protects against: devices that have shuffled addresses, so one is never read as another. What it does not: a host on the LAN can mint a certificate with any name it likes, so it is not authentication. Nothing secret is sent on these sockets. A write goes to whichever device answers at an address whose certificate names the target, with the same caveat.
+
+`tls.ts` (`node:tls`) and `serve.ts` (`node:http`) are the connector's Node APIs, so they sit outside the runtime-neutral build like `weather/ftp.ts` and are passed in (`connect`, `serve`).
+
+## Sources
+
+- [Google Cast documentation](https://developers.google.com/cast/docs/overview); the receiver and media message shapes are in the [Web Receiver](https://developers.google.com/cast/docs/web_receiver) and [media messages](https://developers.google.com/cast/docs/media/messages) references.
+- [`cast_channel.proto`](https://chromium.googlesource.com/chromium/src/+/main/components/media_router/common/providers/cast/channel/cast_channel.proto) (Chromium, BSD-3-Clause): the `CastMessage` fields.
+- [pychromecast](https://github.com/home-assistant-libs/pychromecast) (MIT): the namespaces, heartbeat, media and multizone controllers. Read for facts, nothing copied.
+- [Home Assistant `cast`](https://github.com/home-assistant/core/tree/dev/homeassistant/components/cast) (Apache-2.0): groups and showing a group's media on its members.
+- [`castv2`](https://github.com/thibauts/node-castv2) (MIT) and [`@foxxmd/chromecast-client`](https://github.com/FoxxMD/chromecast-client) (MIT): looked at and not used; docs/cast.md says why.

package/src/connectors/cast/codec.ts

@@ -0,0 +1,126 @@
+// 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.
+
+/** 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 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",
+} as const;
+
+/** 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: number): number[] => {
+  const out: number[] = [];
+  for (; n > 127; n = Math.floor(n / 128)) out.push((n % 128) | 128);
+  return [...out, n];
+};
+const field = (number: number, value: string): number[] => {
+  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: CastMessage): Uint8Array {
+  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: Uint8Array): CastMessage {
+  const strings: Record<number, string> = {};
+  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: Uint8Array): CastMessage[] => {
+    const joined = new Uint8Array(buffer.length + chunk.length);
+    joined.set(buffer);
+    joined.set(chunk, buffer.length);
+    const out: CastMessage[] = [];
+    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;
+  };
+}
+
+/** 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>;