@khalido/home 0.1.2 → 0.1.3

package/src/connectors/cast/writes.ts

@@ -8,13 +8,16 @@ import {
   MultizoneStatus,
   ReceiverStatus,
 } from "./schemas.ts";
-import { type CastDevice, castKey } from "./state.ts";
+import {
+  type CastDevice,
+  castKey,
+  DEFAULT_MEDIA_RECEIVER,
+  findCast,
+} from "./state.ts";
 
 // Writes over the sockets `cast()` already holds: volume, mute, stop, and an announcement that plays a clip and puts
-// the device back as it was. Never called by the integration itself; tried on a scripted fake socket, not yet live.
+// the device back as it was. Never called by the integration itself; announce, volume and mute have run on real devices (the README has the dates).
 
-/** Google's own player for a URL of audio or video. */
-export const DEFAULT_MEDIA_RECEIVER = "CC1AD845";
 /** Each request (a status, a volume, LAUNCH, LOAD, STOP) gets this long to answer. */
 export const ANSWER_MS = 10_000;
 /** How long an announcement waits for its clip to finish, beyond the clip's own length when the device reports it. */
@@ -200,9 +203,7 @@ export function castActions(ctx: WriteContext): CastActions {
 
   const find = (target: string): CastDevice => {
     const all = Object.values(ctx.devices());
-    const d =
-      all.find((x) => x.id === castKey(target)) ??
-      all.find((x) => x.name.toLowerCase() === target.toLowerCase());
+    const d = findCast(ctx.devices(), target);
     if (!d)
       throw new Error(
         `no Cast device or group "${target}"; have: ${
@@ -427,7 +428,7 @@ export function castActions(ctx: WriteContext): CastActions {
     /**
      * Read the target's state, set the volume if asked and unmute a muted target, launch the Default Media Receiver, play the clip to its end, then
      * put back what it can, always: what the Default Media Receiver was playing is loaded again where it was, an idle
-     * device gets STOP, then the volume (a group's, member by member through each member's own socket). Another app
+     * device gets STOP, then the volume (a group's own first, then member by member through each member's own socket). Another app
      * (Spotify, YouTube) is interrupted and cannot be resumed from here; the result says so. Throws only before anything changed.
      */
     async announce(target, clip, options = {}) {
@@ -549,6 +550,26 @@ export function castActions(ctx: WriteContext): CastActions {
                   muted: before.volume?.muted,
                 },
               ];
+        // A group keeps a level of its own, which its members' levels don't bring back (live, 2026-11-10: it stayed at the
+        // announcement's 30 with every member restored). First, so whatever it does to the members, their own levels land last.
+        if (d.kind === "group" && options.volume !== undefined) {
+          const level = before.volume?.level;
+          if (level === undefined)
+            result.notRestored.push({
+              name: d.name,
+              why: "its volume before was not reported",
+            });
+          else
+            try {
+              await receiver(s, { type: "SET_VOLUME", volume: { level } });
+              result.restored.push(`${d.name}: volume`);
+            } catch (error) {
+              result.notRestored.push({
+                name: d.name,
+                why: `volume not restored: ${errorText(error)}`,
+              });
+            }
+        }
         for (const m of each) {
           const ms = m.id === d.id ? s : ctx.session(m.id);
           if (m.level === undefined)

package/src/connectors/daikin/README.md

@@ -63,6 +63,10 @@ All setpoint and fan fields, read from `e_3001` with `md` (setpoint is one byte,
 
 Unmapped and unread: `p_27` (`0A00`, like auto), `p_34` (one signed byte, `00`, `mi FA`, `mx 00`), and the `p_05`–`p_08`, `p_20`–`p_25` fields (3- and 4-byte values, mostly `0F…`, likely schedules or limits). Meaning unknown.
 
+## Read from a Pi (2026-11-10)
+
+`home daikin` on 0.1.2 (Bun 1.4.4; chota-bot's session): "connected · off · dry · room 26 °C · outdoor unit 28 °C". `home discover` found the unit by UDP. No write was sent.
+
 ## Sources
 
 Both Daikin protocol sources are GPL-3.0, so they are read for facts only (endpoints, field paths, value maps) and no code is copied; that keeps this package MIT.

package/src/connectors/daikin/index.ts

@@ -1,10 +1,20 @@
 import { asOf, type Clock, realClock } from "../../clock.ts";
 import { z } from "zod";
-import type { Integration } from "../../home.ts";
+import {
+  type DeviceRecord,
+  deviceRecords,
+  type Integration,
+  type Part,
+} from "../../home.ts";
 import { type Finder, lostDetail, relocator } from "../../discover.ts";
 import type { Manifest } from "../../manifest.ts";
 import { poller } from "../../poll.ts";
-import { daikinClient, DaikinError, type DaikinState } from "./client.ts";
+import {
+  daikinClient,
+  DaikinError,
+  type DaikinState,
+  type Mode,
+} from "./client.ts";
 
 export {
   DaikinError,
@@ -143,3 +153,32 @@ export const manifest: Manifest<DaikinSnapshot> = {
   ],
   lines: ({ state }) => (state ? [acText(state)] : []),
 };
+
+/** The AC as a home device: `state` is `off`, its mode while on, or `on` when it hasn't said which; `detail` its snapshot. */
+export type DaikinHomeDevice = DeviceRecord<
+  "daikin",
+  "ac",
+  "off" | "on" | Mode,
+  DaikinSnapshot
+>;
+
+/** The one unit, once it has been read. It reports no name or id of its own: a home config's entry names and places it. */
+export function daikinHomeDevices(
+  part: Part<DaikinSnapshot> | undefined,
+): DaikinHomeDevice[] {
+  const s = part?.state;
+  if (!s) return [];
+  return deviceRecords<DaikinHomeDevice>(part, [
+    {
+      connector: "daikin",
+      id: "daikin",
+      name: manifest.title,
+      kind: "ac",
+      available: true,
+      ...(s.on === undefined ? {} : { state: s.on ? (s.mode ?? "on") : "off" }),
+      asOf: s.asOf,
+      text: `${manifest.title}: ${acText(s)}`,
+      detail: s,
+    },
+  ]);
+}

package/src/connectors/enphase/index.ts

@@ -1,6 +1,12 @@
 import { type Clock, localDay, realClock } from "../../clock.ts";
 import { z } from "zod";
-import { filePath, type Integration } from "../../home.ts";
+import {
+  type DeviceRecord,
+  deviceRecords,
+  filePath,
+  type Integration,
+  type Part,
+} from "../../home.ts";
 import { type Finder, lostDetail, relocator } from "../../discover.ts";
 import { kw, type Manifest } from "../../manifest.ts";
 import { poller } from "../../poll.ts";
@@ -102,7 +108,16 @@ export function enphase(
     name: "enphase",
     refresh: () => (where.reset(), poll.nudge()),
     async run(signal, update) {
-      const expiresAt = tokenExpiry(config.token); // a bad token fails this integration only
+      let expiresAt: Date;
+      try {
+        expiresAt = tokenExpiry(config.token); // a bad token fails this integration only
+      } catch {
+        return update({
+          status: "unavailable",
+          reason: "auth",
+          detail: "the token is unreadable; run `home enphase login`",
+        });
+      }
       let last: EnphaseSnapshot | undefined;
       let day:
         | {
@@ -168,6 +183,7 @@ export function enphase(
           if (error instanceof EnphaseError && error.status === 401)
             return update({
               status: "unavailable",
+              reason: "auth",
               detail:
                 "the gateway rejected the token; run `home enphase login`",
               state: last,
@@ -239,3 +255,34 @@ export const manifest: Manifest<EnphaseSnapshot> = {
   files: ["token"],
   lines: ({ state }) => (state ? [enphaseText(state)] : []),
 };
+
+/** The gateway as a home device: `state` is `producing` while the solar makes power, else `idle`; `detail` its snapshot. */
+export type EnphaseHomeDevice = DeviceRecord<
+  "enphase",
+  "solar",
+  "producing" | "idle",
+  EnphaseSnapshot
+>;
+
+/** The one gateway, once it has been read. */
+export function enphaseHomeDevices(
+  part: Part<EnphaseSnapshot> | undefined,
+): EnphaseHomeDevice[] {
+  const s = part?.state;
+  if (!s) return [];
+  return deviceRecords<EnphaseHomeDevice>(part, [
+    {
+      connector: "enphase",
+      id: "enphase",
+      name: manifest.title,
+      kind: "solar",
+      available: true,
+      ...(s.productionW === undefined
+        ? {}
+        : { state: s.productionW > 0 ? "producing" : "idle" }),
+      asOf: s.asOf,
+      text: `${manifest.title}: ${enphaseText(s)}`,
+      detail: s,
+    },
+  ]);
+}

package/src/connectors/hue/index.ts

@@ -5,6 +5,8 @@ import { type Finder, lostDetail, relocator } from "../../discover.ts";
 import {
   envName,
   filePath,
+  type DeviceRecord,
+  deviceRecords,
   type Integration,
   type Part,
   type Status,
@@ -14,8 +16,10 @@ import { bunPinnedFetch, type HueClient, hueClient } from "./client.ts";
 import { hueEvents, isRejectedKey } from "./events.ts";
 import type { HueEvent } from "./schemas.ts";
 import {
+  type GroupView,
   groups,
   type HueSnapshot,
+  type LightView,
   lights,
   reduce,
   snapshotFrom,
@@ -189,6 +193,7 @@ export function hue(
           if (isRejectedKey(error))
             return update({
               status: "unavailable",
+              reason: "auth",
               detail: "the bridge rejected the key; pair again",
               state: snapshot,
             });
@@ -215,6 +220,56 @@ const view = (s: HueSnapshot) => ({
   })),
 });
 
+/** "Kitchen: on · 40%", "Kitchen: off", or the name alone when the bridge hasn't said. */
+const onText = (v: {
+  name?: string;
+  id: string;
+  on?: boolean;
+  brightness?: number;
+}) =>
+  `${v.name ?? v.id}${v.on === undefined ? "" : `: ${v.on ? `on${v.brightness === undefined ? "" : ` · ${Math.round(v.brightness)}%`}` : "off"}`}`;
+
+/** A Hue light, or a room or zone, as a home device: `detail` is its `LightView` or `GroupView`. */
+export type HueHomeDevice =
+  | DeviceRecord<"hue", "light", "on" | "off", LightView>
+  | DeviceRecord<"hue", "group", "on" | "off", GroupView>;
+
+/** Every light, then every room and zone. A light's `available` is its Zigbee link; a group's `members` are its lights. */
+export function hueHomeDevices(
+  part: Part<HueSnapshot> | undefined,
+): HueHomeDevice[] {
+  const s = part?.state;
+  if (!s) return [];
+  const on = (v: { on?: boolean }) =>
+    v.on === undefined
+      ? {}
+      : { state: v.on ? ("on" as const) : ("off" as const) };
+  return deviceRecords<HueHomeDevice>(part, [
+    ...lights(s).map((l): HueHomeDevice => ({
+      connector: "hue",
+      id: l.id,
+      name: l.name ?? l.id,
+      kind: "light",
+      ...(l.reachable === undefined ? {} : { available: l.reachable }),
+      ...on(l),
+      asOf: s.asOf,
+      text: onText(l),
+      detail: l,
+    })),
+    ...groups(s).map((g): HueHomeDevice => ({
+      connector: "hue",
+      id: g.id,
+      name: g.name ?? g.id,
+      kind: "group",
+      ...on(g),
+      asOf: s.asOf,
+      text: onText(g),
+      members: g.lightIds,
+      detail: g,
+    })),
+  ]);
+}
+
 export const manifest: Manifest<HueSnapshot> = {
   name: "hue",
   title: "Philips Hue",
@@ -248,14 +303,8 @@ export const manifest: Manifest<HueSnapshot> = {
   /** "3 lights on", then "Kitchen: on · 40%" per room and zone. */
   lines({ state }) {
     if (!state) return [];
-    const { lightsOn, rooms } = view(state);
-    return [
-      `${lightsOn} lights on`,
-      ...rooms.map(
-        (r) =>
-          `${r.name}: ${r.on ? `on${r.brightness === undefined ? "" : ` · ${Math.round(r.brightness)}%`}` : "off"}`,
-      ),
-    ];
+    const { lightsOn } = view(state);
+    return [`${lightsOn} lights on`, ...groups(state).map(onText)];
   },
   record: ({ state }) => (state ? view(state) : {}),
 };

package/src/connectors/printers/README.md

@@ -1,6 +1,6 @@
 # Printers
 
-AirPrint printers, found by mDNS and read over IPP on the local network. `iot_class`: **local_polling** (one Get-Printer-Attributes per printer every 120 s). Built read-only; **untried on a live printer** (the Brother KO has did not answer mDNS on 2026-10-14, see Live findings).
+AirPrint printers, found by mDNS and read over IPP on the local network. `iot_class`: **local_polling** (one Get-Printer-Attributes per printer every 120 s). Built read-only; first read of a live printer 2026-11-10 (see Live findings).
 
 Try it: `home printers`
 
@@ -34,7 +34,9 @@ Everything, until a real printer answers: the request bytes (the codec is checke
 
 ## Live findings
 
-None yet. 2026-10-14 (Bun 1.4.3): `home discover` (two passes) and `home printers` found no `_ipp._tcp` or `_ipps._tcp` instance on the network, so the Brother was not advertising (off, asleep, or on another network).
+**2026-11-10, from a Pi (Bun 1.4.4, 0.1.2; chota-bot's session).** `home discover` found the Brother by mDNS and `home printers` read it: "Brother HL-L2350DW series: idle · BK 80% · A4 ready". So discovery, the request, the default path, a real `marker-levels` and `media-ready` work on this model. Still unverified from the list above: `printer-uuid` against TXT `UUID`, a sleeping printer waking, `printer-alert`, and the macOS local-network prompt.
+
+2026-10-14 (Bun 1.4.3): `home discover` (two passes) and `home printers` found no `_ipp._tcp` or `_ipps._tcp` instance on the network, so the Brother was not advertising (off, asleep, or on another network).
 
 ## Sources
 

package/src/connectors/printers/index.ts

@@ -11,7 +11,13 @@ import {
   lostDetail,
   rescanDelay,
 } from "../../discover.ts";
-import type { Integration, Part, Status } from "../../home.ts";
+import {
+  type DeviceRecord,
+  deviceRecords,
+  type Integration,
+  type Part,
+  type Status,
+} from "../../home.ts";
 import type { Manifest } from "../../manifest.ts";
 import { poller } from "../../poll.ts";
 import { getPrinterAttributes, printerUrl } from "./client.ts";
@@ -19,6 +25,7 @@ import { attributesOf } from "./codec.ts";
 import {
   type Printer,
   printerKey,
+  type PrinterStatus,
   printerText,
   type PrintersState,
   type Reading,
@@ -383,3 +390,38 @@ export const manifest: Manifest<PrintersState> = {
     ];
   },
 };
+
+/** A printer as a home device: `state` is the printer's own (`idle`, `printing`, `stopped`, `offline`); `detail` its `Printer`. */
+export type PrinterHomeDevice = DeviceRecord<
+  "printers",
+  "printer",
+  PrinterStatus,
+  Printer
+>;
+
+/** Every printer, by name. One that has stopped answering is not `available`, and keeps its last values. */
+export function printersHomeDevices(
+  part: Part<PrintersState> | undefined,
+): PrinterHomeDevice[] {
+  if (!part?.state) return [];
+  return deviceRecords(
+    part,
+    printerList(part.state).map((p): PrinterHomeDevice => ({
+      connector: "printers",
+      id: p.uuid,
+      name: p.name,
+      kind: "printer",
+      ...(p.state === undefined ? {} : { available: p.state !== "offline" }),
+      ...(p.state === undefined ? {} : { state: p.state }),
+      // An offline printer's values are from when it last answered, not from this check.
+      ...(p.state === "offline"
+        ? p.lastSeen === undefined
+          ? {}
+          : { asOf: p.lastSeen }
+        : { asOf: p.asOf }),
+      text: printerText(p),
+      ...(p.room ? { room: p.room } : {}),
+      detail: p,
+    })),
+  );
+}

package/src/connectors/spotify/README.md

@@ -18,7 +18,7 @@ Soloist is Spotify's own headless Spotify Connect client (Linux arm64, armv7, x8
 
 - Each resolves `{ state, confirmed }`: after Soloist accepts (`command_result`), it waits up to 2 s for the event that shows _this caller's_ change (the volume sent, `paused` or `playing`, a new track URI, the context or track played, a position near the seek, the shuffle or repeat set, the track in `upNext`), then gives the state. No such event: `confirmed: false`, the state as it stands. A write merged into a later one confirms only if its own change shows; a write of what is already so confirms at once; a drop ends the wait. `next` also confirms on idle (end of queue) or a restart, `prev` on a restart from 5 s or more in.
 - A volume reported within 1 of the request confirms, since Soloist rounds it (phone steps are sixteenths).
-- **While inactive** (`state.active: false`), Soloist accepts `set_volume` and drops it, three times live. `setVolume` is refused unsent with code `inactive`; `duck` runs `fn` over the music with `music: "untouched"`. `activate()` fixes it, but makes a new audio stream, so the volume can jump to the level last saved (62 to 40, live). `play` while inactive goes active first (a `play` alone didn't take live; going active first is untested). `resume` doesn't: it worked inactive, and `interrupt` relies on that.
+- **While inactive** (`state.active: false`), Soloist accepts `set_volume` and drops it, three times live. `setVolume` is refused unsent with code `inactive`; `duck` and `interrupt` run `fn` over the music with `music: "untouched"`: "playing" while inactive is the account playing on another speaker, which a pause would stop. `activate()` fixes it, but makes a new audio stream, so the volume can jump to the level last saved (62 to 40, live). `play` while inactive goes active first (a `play` alone didn't take live; going active first is untested). `resume` doesn't: it worked inactive, and `interrupt` relies on that.
 - Errors are `ConnectorError` with `code`: `offline`, `waiting`, `inactive`, `refused` (Soloist's `error`), `timeout` (3 s), `invalid` (bad input, nothing sent).
 - One write lane, 100 ms apart (a guess). `volume`, `seek`, `shuffle`, `repeat` merge to the last; `play`, `pause`, `resume` share a slot, so the last wins; each `next`, `prev`, `queue` is its own. Queries go through the lane too, at most 1 s each, since Soloist's `error` names no command.
 - `setRepeat` is two commands in the docs' order (clear the other mode, then set this one), 600 ms apart: back to back, `off` from `track` stayed on `track` live, and 600 ms apart worked. If the second is refused, repeat may be left off.
@@ -28,7 +28,7 @@ Soloist is Spotify's own headless Spotify Connect client (Linux arm64, armv7, x8
 
 **`duck(fn, { to })` and `interrupt(fn)`** turn the music down, or pause it, around `fn`, then put it back. Both resolve `{ value, music, why? }`, `music` one of:
 
-- `untouched`: not playing or buffering, not connected, (duck) the volume unknown or already at `to` or below, or the lowering or pause failed, so `fn` ran over it.
+- `untouched`: not playing or buffering, not connected, not the active device, (duck) the volume unknown or already at `to` or below, or the lowering or pause failed, so `fn` ran over it.
 - `restored`: put back as it was.
 - `kept`: someone changed it meanwhile (resumed, skipped, set the volume), or the pause or lower volume never showed. Theirs stays.
 - `failed`: the restore failed or was never reported; it may be left quiet or paused.
@@ -68,6 +68,18 @@ Writes through this connector, and what a live read hasn't shown. In particular:
 
 ## Live findings
 
+**2026-11-10, Raspberry Pi 5, Bun 1.4.4, on 0.1.2, through this connector** (chota-bot's session, KO listening).
+
+- Confirmed with `maxVolume: 60`, the speaker active and playing: `activate`, `setVolume(50)`, `setVolume(90)` (came back 60), `seek`, `setShuffle`, `setRepeat("context")` and `("off")` (about 2.1 s each), `queue` (first in `upNext`), `play` of a playlist URI. `duck(fn, { to: 20 })` around a Cast announce: 20 inside, `music: "restored"`, 60 after, 5.2 s in all.
+- **The level can jump above the cap on a pause, not only on a start.** One-shot CLI, cap 60: `volume 45` read 45, `play` 45, then `pause` read 62 and the next `play` 62 (62 was the level before the test). Nothing lowered it: a pause is not a start signal, and each CLI command is a new process.
+- **That jump did not repeat, and it is not WirePlumber.** A second pass the same day, the speaker already active: 60, `volume 45`, `pause`, `play`, `volume 60`. Soloist's number and the stream's live level (`wpctl get-volume`) matched at every step (0.60, 0.45, 0.45, 0.45, 0.60), WirePlumber 0.5.8 never wrote a saved entry for the stream in `stream-properties`, and the stream kept its id across pause and play. The run that jumped had just been made active with `activate`, minutes after the account was casting from a phone, which points at the account side. One case each way.
+- **`active: false` with `status: "playing"`:** the account playing on another speaker. `speakerState` says `playing`, `spotifyText` prints it as this speaker's, and `spotifyChanges` fired `resumed`, with the box silent.
+- Through chota-bot's wrapper, later the same day: `play` of a playlist confirmed in 241 ms, `next` in 134 ms, `pause` in 17 ms; `duck` to 15 and `interrupt`, 2.5 s each, both `restored`. `play()` with the music paused on a Cast speaker: confirmed in 1.3 s, playing on the box at the same position.
+- **`interrupt` paused music that was on another speaker** (found in chota's switch): it checked `playing` and not `active`. Fixed after 0.1.2.
+- `positionMs` around a duck and an interrupt read 2 s, 2 s, 3 s, 5 s, then 4 s after a pause: it can step back a second.
+- A consumer's test with a fake socket: a write goes out behind the connector's own queries (`get_state`, `get_queue`), up to about 1 s on a fresh socket, so "the command was sent" can't be checked straight after the call.
+- Not run: the first-play cap from idle (the box never went active), stall events.
+
 **2026-11-09, Raspberry Pi 5, Bun 1.4.4, Soloist 1.3.10.51, PipeWire and WirePlumber 0.5.8, on 0.1.1** (chota-bot's session; writes with KO's OK).
 
 - Confirmed: pause, resume, next, prev, seek, shuffle, repeat to context and track, queue, all under 900 ms. `interrupt` restored the music.

package/src/connectors/spotify/index.ts

@@ -1,10 +1,21 @@
 import { z } from "zod";
 import { asOf, type Clock, realClock } from "../../clock.ts";
 import { ConnectorError, errorText } from "../../connector.ts";
-import type { Integration, Part, Status } from "../../home.ts";
+import {
+  type DeviceRecord,
+  deviceRecords,
+  type Integration,
+  type Part,
+  type Status,
+} from "../../home.ts";
 import { writeLane } from "../../lane.ts";
 import type { Manifest } from "../../manifest.ts";
-import { spotifyText, stallText } from "./changes.ts";
+import {
+  type SpeakerState,
+  speakerState,
+  spotifyText,
+  stallText,
+} from "./changes.ts";
 import {
   commandFrame,
   fold,
@@ -411,6 +422,7 @@ export function spotify(
       (error) => {
         capping = false;
         if (error instanceof ConnectorError && error.code === "offline") return; // the status says it
+        if (capUntil !== window) return applyCap(); // a new start while it went: this failure doesn't speak for that one
         capped = true; // refused or unanswered: not again this window
         note = `lowering the volume to ${cap} failed: ${errorText(error)}`;
         publish();
@@ -733,6 +745,9 @@ export function spotify(
         async () => {
           const no = notPlaying();
           if (no) return no;
+          // "playing" while inactive is the account playing on another speaker (live, 2026-11-10): a pause would stop that one.
+          if (inactive())
+            return "it is not the active device, so the music playing is on another speaker";
           track = state.track?.uri;
           try {
             shown = (await actions.pause()).confirmed; // a pause that never shows still runs fn: what interrupts matters more
@@ -999,3 +1014,32 @@ export const manifest: Manifest<SpotifyState> = {
       ? [spotifyText(state)]
       : [],
 };
+
+/** The Soloist speaker as a home device: `state` is `speakerState`'s word; `detail` its `SpotifyState`. */
+export type SpotifyHomeDevice = DeviceRecord<
+  "spotify",
+  "speaker",
+  SpeakerState,
+  SpotifyState
+>;
+
+/** The one speaker, once Soloist has said something. Its name is Soloist's `--device-name`, the one phones show. */
+export function spotifyHomeDevices(
+  part: Part<SpotifyState> | undefined,
+): SpotifyHomeDevice[] {
+  const s = part?.state;
+  if (!s || (s.loggedIn === undefined && s.status === undefined)) return [];
+  return deviceRecords<SpotifyHomeDevice>(part, [
+    {
+      connector: "spotify",
+      id: "spotify",
+      name: s.deviceName ?? "Soloist",
+      kind: "speaker",
+      available: true,
+      state: speakerState(part),
+      asOf: s.asOf,
+      text: spotifyText(s),
+      detail: s,
+    },
+  ]);
+}

package/src/connectors/up/index.ts

@@ -291,6 +291,7 @@ export function up(config: UpConfig): Integration<UpSnapshot, "up"> & {
           if (error instanceof UpError && error.status === 401)
             return update({
               status: "unavailable",
+              reason: "auth",
               detail: "Up rejected the token",
               state: last,
             });

package/src/connectors/weather/README.md

@@ -62,7 +62,7 @@ Plain `fetch` cannot read `ftp://` (Bun 1.4.2: "protocol must be http:, https: o
 
 **Open-Meteo** (`open-meteo.ts`, [docs](https://open-meteo.com/en/docs)). One keyless JSON call per poll: `current` is 15-minutely model data (`interval: 900`), so it is read every poll, and the daily and hourly parts, from models that update hourly at best (6-hourly for IFS), are added to one call an hour. That call reads 48 hours from today's local midnight (`forecast_days=2`) for `hourly`; `sky.hours` is the 6 from the hour it was read. Open-Meteo gives local times and one `utc_offset_seconds`, and applies that offset to every time, across a daylight-saving change too (it returned 02:00 on the night Sydney skipped it; live, 2026-10-16), so `wall − offset` is right for all of them. `dayBlocks` labels each UTC hour in the real zone. 96 calls a day at the default, against 10,000 free. No `models` parameter: [Open-Meteo's BOM page](https://open-meteo.com/en/docs/bom-api) says BOM's open-data delivery is still suspended, and its `bom_access_global` answers only nulls. Radiation is the mean over the preceding interval. `precipitation` is the last 15 minutes, so `now.rainMm` stays empty rather than pretending to be since 9am. 1.3 s a call from Sydney, nearly all of it the TLS handshake with a server in Germany. Plain `fetch` of the JSON API, not the `openmeteo` SDK: the SDK forces FlatBuffers, reads variables by position, calls the global `fetch` (no injection for tests) and adds about 700 KB.
 
-**Google Weather** (`google.ts`, [docs](https://developers.google.com/maps/documentation/weather)). Built from the docs' example responses (`test/fixtures/weather/google-*.json`, the complete objects only; the docs elide the rest) and checked live against Sydney on 2026-10-13: `now`, `forecast` and `sky` in 1.19 s. `google({ key })` reads `forecast/minutes:lookup` every 15 minutes (its floor), `currentConditions:lookup` every 30 and `forecast/days:lookup?days=2` and `forecast/hours:lookup?hours=6` hourly, since Google documents nothing that changes faster. That is 192 calls a day, about 5,800–5,950 a month. Google bills each call as one Weather Usage event: 10,000 free a month, then $0.15 per 1,000 ([pricing](https://developers.google.com/maps/billing-and-pricing/pricing)). Any other use of the same key shares that quota. Whether the minute forecast bills as the same event is unverified: its docs page shows no price. Every slice is `modelled: true`: the docs never say it is observed. A day's rain chance is the higher of its day and night halves, its amount their sum; `currentConditionsHistory.qpf` is a rolling 24 hours, so it is not used as rain since 9am. A 400, 401 or 403 stops the source (`stop`), with no retry loop. The key goes in the query string and never into a message.
+**Google Weather** (`google.ts`, [docs](https://developers.google.com/maps/documentation/weather)). Built from the docs' example responses (`test/fixtures/weather/google-*.json`, the complete objects only; the docs elide the rest) and checked live against Sydney on 2026-10-13: `now`, `forecast` and `sky` in 1.19 s. `google({ key })` reads `forecast/minutes:lookup` every 15 minutes (its floor), `currentConditions:lookup` every 30 and `forecast/days:lookup?days=2` and `forecast/hours:lookup?hours=6` hourly, since Google documents nothing that changes faster. That is 192 calls a day, about 5,800–5,950 a month. Google bills each call as one Weather Usage event: 10,000 free a month, then $0.15 per 1,000 ([pricing](https://developers.google.com/maps/billing-and-pricing/pricing)). Any other use of the same key shares that quota. The key goes in the `X-Goog-Api-Key` header: all four lookups answered 200 that way, live against a public Sydney point on 2026-11-10 (Bun 1.4.4). A bad key and a bad latitude both come back HTTP 400 `INVALID_ARGUMENT`; only the key's error body carries `API_KEY_INVALID`, which is how the source tells `auth` from `config`, and no key at all is 403. Other key failures (expired, the API not enabled) are assumed to be 401, 403 or an `API_KEY_…` reason: unverified. Whether the minute forecast bills as the same event is unverified: its docs page shows no price. Every slice is `modelled: true`: the docs never say it is observed. A day's rain chance is the higher of its day and night halves, its amount their sum; `currentConditionsHistory.qpf` is a rolling 24 hours, so it is not used as rain since 9am. A rejected key or a refused request stops the source (`stop`, with `stopReason`), with no retry loop.
 
 **Google minute forecast** (`toRain` in `google.ts`, [docs](https://developers.google.com/maps/documentation/weather/minute-forecast)). `GET /v1/forecast/minutes:lookup` for a point returns `overallPredictionTimeframe` and 24 `segments` (6 hours) of 15 minutes, each with `type` (`NONE`, `RAIN`, `SNOW`, `HAIL`), `probability` 0–100, `qpf` in mm and `intensity`. Probed for Sydney CBD on 2026-10-15 (curl): HTTP 200 in 1.0 s, every segment dry; the first segment began 12 minutes before the forecast's start. Google calls it Experimental, so its failure is a `problem` on `rain` and never stops the other slices. The docs do not list its coverage by country, say nothing of how it is made, and allow keeping minute values for one hour at most: `rain` owns 15 minutes of age on top of one poll, so a stale slice is dropped, not served (with a `pollMinutes` above 45 the slice outlives that hour: keep it at 15), and the test fixture is invented values in the real shape. We keep the segments that start within 2 hours (`RAIN_HORIZON_MINUTES`). **`rainSoon(rain, at, windowMin = 120)` is the owner**: when the first wet stretch starts and ends, its chance, amount and weight, and `coveredMin`, how much of the window the forecast covers. A segment with no `type` is unknown, not dry. Next: if the minute forecast fails, fall back to the hourly rain chance (`forecast/hours:lookup` already carries `precipitation`; not read yet).
 

package/src/connectors/weather/bom.ts

@@ -284,6 +284,7 @@ export function bom(options: BomOptions = {}): WeatherSource {
       if (!options.fetch && base.startsWith("ftp:"))
         return {
           stop: "bom: plain fetch cannot read ftp://; pass fetch: ftpFetch() from @khalido/home/weather/ftp",
+          stopReason: "config",
           nextAt: Infinity,
         };
       if (force || at >= obsDue) {

package/src/connectors/weather/google.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { type ConnectorError, getJson } from "../../connector.ts";
+import { ConnectorError, fetchTimeout } from "../../connector.ts";
 import { RAIN_INTENSITIES } from "./rain.ts";
 import { sunDisagrees } from "./sun.ts";
 import {
@@ -324,6 +324,33 @@ export type GoogleOptions = {
 export const MIN_POLL_MINUTES = 15;
 export const CURRENT_MINUTES = 30;
 
+/**
+ * Why Google refused: the `reason` of its error body's ErrorInfo ("API_KEY_INVALID"), since the status alone doesn't say.
+ * A bad key and a bad latitude are both HTTP 400 INVALID_ARGUMENT; only the key's carries a reason (live, 2026-11-10).
+ */
+async function refusal(res: Response): Promise<string | undefined> {
+  try {
+    const body = (await res.json()) as {
+      error?: { details?: { reason?: unknown }[] };
+    };
+    const reason = body.error?.details?.find((d) => d.reason)?.reason;
+    return typeof reason === "string" ? reason : undefined;
+  } catch {
+    return undefined; // not JSON: the status is all there is
+  }
+}
+
+/** Google's refusal: the HTTP status, and `why`, the reason its error body gave. */
+class GoogleError extends ConnectorError {
+  constructor(
+    message: string,
+    status: number,
+    readonly why?: string,
+  ) {
+    super(message, { status });
+  }
+}
+
 /**
  * Google Weather as a source: modelled `now`, `forecast` (10 days available, 2 read), `sky` without radiation, and `rain` from the
  * minute forecast (Experimental at Google, so its failure is a `problem` on `rain` and never stops the other slices).
@@ -353,12 +380,28 @@ export function google(options: GoogleOptions): WeatherSource {
       signal,
     }): Promise<SourceReading> {
       const q = (extra: string) =>
-        `key=${encodeURIComponent(options.key)}&location.latitude=${place.latitude}&location.longitude=${place.longitude}${extra}`;
-      const json = (path: string) =>
-        getJson(fetcher, `${base}/${path}`, {
-          init: { headers: { "user-agent": USER_AGENT } },
-          signal,
-        });
+        `location.latitude=${place.latitude}&location.longitude=${place.longitude}${extra}`;
+      // The key goes in a header, never the URL, so no error, log or proxy that shows a URL can show it (all four lookups answered 200 this way, live 2026-11-10).
+      const json = async (path: string): Promise<unknown> => {
+        const res = await fetchTimeout(
+          fetcher,
+          `${base}/${path}`,
+          {
+            headers: {
+              "user-agent": USER_AGENT,
+              "x-goog-api-key": options.key,
+            },
+          },
+          { signal },
+        );
+        if (res.ok) return res.json();
+        const why = await refusal(res);
+        throw new GoogleError(
+          `HTTP ${res.status}${why ? ` ${why}` : ""} on GET /${path.split("?")[0]}`,
+          res.status,
+          why,
+        );
+      };
       // Started first and never throws: a failed minute forecast must not sink the rest.
       const minutes = json(`forecast/minutes:lookup?${q("")}`).then(
         (value) => ({ value }),
@@ -385,10 +428,23 @@ export function google(options: GoogleOptions): WeatherSource {
           slowDue = nextPoll(at, Math.max(pollMinutes, CURRENT_MINUTES));
         }
       } catch (error) {
-        const status = (error as ConnectorError).status;
-        if (status === 400 || status === 401 || status === 403)
+        // Only a GoogleError is Google's answer; a timeout or an abort is a DOMException, with fields of its own.
+        const { status, why } =
+          error instanceof GoogleError
+            ? error
+            : ({} as { status?: number; why?: string });
+        const said = `HTTP ${status}${why ? ` ${why}` : ""}`;
+        if (status === 401 || status === 403 || why?.startsWith("API_KEY_"))
+          return {
+            stop: `google: the key was rejected (${said})`,
+            stopReason: "auth",
+            nextAt: Infinity,
+          };
+        // A 400 with a good key is the request itself, and here that is the location: asking again won't change it.
+        if (status === 400)
           return {
-            stop: `google: key rejected or request refused (HTTP ${status})`,
+            stop: `google: the request was refused (${said}); check the latitude and longitude`,
+            stopReason: "config",
             nextAt: Infinity,
           };
         problem = `google: ${(error as Error).message}`; // the old slices stay; the minute forecast below is still used