@khalido/home 0.1.1 → 0.1.3

package/src/connectors/spotify/client.ts

@@ -185,7 +185,7 @@ export type SpotifyState = {
   /** The playlist, album or show playing from. */
   context?: { uri: string; type?: string; name?: string };
   position?: PositionAnchor;
-  /** 0–100, as Soloist reports it. */
+  /** 0–100, as Soloist reports it, rounded. Until `active` it isn't the level that will play (it reads `--initial-volume`, seen live). */
   volume?: number;
   shuffle?: boolean;
   /** off, context or track. */

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,
@@ -99,9 +110,11 @@ export type Aside<T> = { value: T; music: Music; why?: string };
 /**
  * The writes, on the object `spotify()` returns. Each resolves once Soloist reports the change it asked for, with the state
  * then (`confirmed: true`), or after `CONFIRM_MS` with the state as it stands (`confirmed: false`). Each rejects with a
- * `ConnectorError` whose `code` is `offline`, `waiting` (nobody has picked the speaker), `refused`, `timeout` or `invalid`.
+ * `ConnectorError` whose `code` is `offline`, `waiting` (nobody has picked the speaker), `inactive` (`setVolume` on a speaker that isn't the active device: `activate()` first), `refused`, `timeout` or `invalid`.
  */
 export type SpotifyActions = {
+  /** Make this the account's active Spotify device. Soloist drops volume changes until it is. It makes a new audio stream, so the volume can jump to the level last saved. */
+  activate(): Promise<Applied>;
   /** Play a Spotify link or URI (track, album, playlist, artist, episode, show), or resume what is loaded when none is given. */
   play(linkOrUri?: string): Promise<Applied>;
   pause(): Promise<Applied>;
@@ -137,10 +150,12 @@ const COMMAND_TIMEOUT_MS = 3000;
 const QUERY_TIMEOUT_MS = 1000;
 /** A socket that has said nothing this long after opening is closed: Soloist sends `auth_state` at once on connect. */
 const HELLO_MS = 10_000;
-/** After an idle → playing change, a volume above the cap is lowered for this long: the volume can come before or after the status (issue #23). */
+/** After a start signal, a volume above the cap is lowered for this long: the volume can come before or after the status (issue #23). */
 const CAP_WINDOW_MS = 10_000;
 /** How long a write waits for Soloist to report the change it asked for. Loopback events arrive in milliseconds; a stated guess. */
 const CONFIRM_MS = 2000;
+/** Between the two halves of `setRepeat`: back to back left repeat on `track`, 600 ms apart worked (live, 2026-11-09). */
+const REPEAT_GAP_MS = 600;
 /** Between two commands. Soloist publishes no limit; it is on loopback; a stated guess. */
 const WRITE_GAP_MS = 100;
 /** While playing, a stall check this often: one `get_state`. Soloist issue #5 reports stalls 71–150 s into a track; a stated guess. */
@@ -149,6 +164,8 @@ const STALL_CHECK_MS = 20_000;
 const OVERRUN_MS = 15_000;
 /** After a repair's seek, how long before looking whether the position moves again. */
 const REPAIR_WAIT_MS = 5000;
+/** A reported volume is rounded (phone steps are sixteenths: 43.75 shows as 44), so "it took" allows this much. */
+const VOLUME_SLACK = 1;
 const MIN_BACKOFF_MS = 1000;
 const MAX_BACKOFF_MS = 60_000;
 
@@ -190,15 +207,16 @@ export function spotify(
 
   let state: SpotifyState = { asOf: asOf(clock) };
   let socket: SocketLike | undefined;
-  let open = false;
-  let heard = false; // an auth_state on this socket: until then the part stays connecting
-  let whole = false; // signed in, the first playback_state has come too (or HELLO_MS passed): a one-shot read sees the track
+  // This socket's progress. "heard": signed in, the first playback_state still to come. "whole": a one-shot read sees the track (or HELLO_MS passed).
+  let link: "down" | "open" | "heard" | "whole" = "down";
+  const isOpen = () => link !== "down";
   let down: string | undefined; // why the last socket ended, while there is none open
   let statusKnown = false; // Soloist has told this socket its status: only then is idle → playing an edge
   let queueAsked = false; // get_queue sent on this socket
   let signedIn = false; // signed out → in on this socket: the first status after it counts as a start if it is playing
   let capUntil = -Infinity;
-  let capped = false; // the cap has been sent in this window
+  let capped = false; // the cap took in this window
+  let capping = false; // a lowering is on its way
   let startBuffering = false; // a start from idle is still buffering
   let capNote: string | undefined; // the last first-play lowering, in `anomaly` until the speaker goes idle
   let frameNote: string | undefined; // a frame the schema rejected, or an error nothing was waiting for
@@ -214,11 +232,10 @@ export function spotify(
   const publish = () => {
     let status: Status;
     let detail: string | undefined;
-    if (!open)
+    if (link === "down")
       ((status = reported || down ? "disconnected" : "connecting"),
         (detail = down));
-    else if (!heard || (state.loggedIn === true && !whole))
-      status = "connecting";
+    else if (link !== "whole") status = "connecting";
     else
       ((status = "connected"),
         (detail = state.loggedIn === false ? WAITING : note));
@@ -251,7 +268,7 @@ export function spotify(
   ) =>
     new Promise<void>((resolve, reject) => {
       const s = socket;
-      if (!s || !open || s.readyState !== OPEN) return reject(offline());
+      if (!s || !isOpen() || s.readyState !== OPEN) return reject(offline());
       if (state.loggedIn === false && !answers)
         return reject(new ConnectorError(WAITING, { code: "waiting" }));
       const stop = new AbortController();
@@ -291,12 +308,20 @@ export function spotify(
     answers?: string;
     then?: { command: string; fields: Record<string, unknown> };
     took?: (now: SpotifyState, before: SpotifyState, at: number) => boolean;
+    activeFirst?: boolean; // an inactive speaker goes active before this, in this write's own turn so the last transport write still wins
   };
   const send = async (body: Body) => {
+    if (body.activeFirst && inactive()) {
+      await command("activate").catch(() => {}); // best effort: the write itself says how it went
+      await waitFor(() => state.active === true || !isOpen(), CONFIRM_MS);
+    }
     const before = state;
     const at = clock.now();
     await command(body.command, body.fields, body.answers);
-    if (body.then) await command(body.then.command, body.then.fields); // repeat's second half, still this write's turn
+    if (body.then) {
+      await clock.sleep(REPEAT_GAP_MS);
+      await command(body.then.command, body.then.fields); // repeat's second half, still this write's turn
+    }
     return { before, at };
   };
   let once = 0; // skips and queued tracks never merge: two nexts are two skips
@@ -309,7 +334,7 @@ export function spotify(
   const change = async (slot: string, body: Body): Promise<Applied> => {
     const sent = await write(slot, body);
     const took = () => body.took?.(state, sent.before, sent.at) ?? true;
-    await waitFor(() => took() || !open, CONFIRM_MS);
+    await waitFor(() => took() || !isOpen(), CONFIRM_MS);
     return { state, confirmed: took() };
   };
   /** The track restarted: a new anchor near 0 when it had been 5 s or more in (a prev past the first seconds, a next on repeat-track). */
@@ -321,12 +346,17 @@ export function spotify(
     !!s.track && s.track.uri !== b.track?.uri;
   const invalid = (message: string) =>
     new ConnectorError(message, { code: "invalid" });
+  const near = (volume: number | undefined, v: number) =>
+    volume !== undefined && Math.abs(volume - v) <= VOLUME_SLACK;
   const volumeTo = (v: number) =>
     change("volume", {
       command: "set_volume",
       fields: { volume: v },
-      took: (s) => s.volume === v,
+      took: (s) => near(s.volume, v),
     });
+  /** Soloist accepts a `set_volume` while it isn't the active device and drops it (three times live, 2026-11-09). */
+  const inactive = () =>
+    isOpen() && state.loggedIn !== false && state.active === false;
   /** Ask Soloist for something, through the lane; the same query twice merges. A refusal is an anomaly, a drop is the status's to say. */
   const ANSWERS = {
     get_state: "playback_state",
@@ -353,27 +383,50 @@ export function spotify(
       publish();
     });
 
-  /** Within the window after a start from idle, a volume above the cap is lowered to it, once (issue #23). */
+  /**
+   * Within the window after a start signal, a volume above the cap is lowered to it (issue #23). Only while active, since
+   * Soloist drops it otherwise, and retried until Soloist reports it. A volume raised after that is someone's choice;
+   * one raised before it is reported can't be told from the start's own jump, so it is lowered too.
+   */
   const applyCap = () => {
     if (
       cap === undefined ||
       capped ||
+      capping ||
       state.volume === undefined ||
-      clock.now() > capUntil ||
-      state.volume <= cap
+      state.volume <= cap + VOLUME_SLACK ||
+      state.active === false ||
+      clock.now() > capUntil
     )
       return;
-    capped = true;
-    capNote = `started at volume ${state.volume}, above maxVolume ${cap}; lowered it (Soloist issue #23)`;
-    change("volume", {
-      command: "set_volume",
-      fields: { volume: cap },
-      took: (s) => s.volume === cap,
-    }).catch(
-      (error) => (
-        (note = `lowering the volume to ${cap} failed: ${errorText(error)}`),
-        publish()
-      ),
+    capping = true;
+    const from = state.volume;
+    const window = capUntil;
+    volumeTo(cap).then(
+      ({ confirmed }) => {
+        capping = false;
+        if (capUntil !== window) return applyCap(); // a new start while it went: this lowering doesn't speak for that one
+        if (confirmed) {
+          capped = true;
+          if (state.status === "idle") return;
+          capNote = `started at volume ${from}, above maxVolume ${cap}; lowered it (Soloist issue #23)`;
+          note = undefined;
+          return publish();
+        }
+        if (clock.now() > capUntil) {
+          note = `could not lower the volume to ${cap}: Soloist has not reported it`;
+          return publish();
+        }
+        applyCap();
+      },
+      (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();
+      },
     );
   };
 
@@ -411,11 +464,16 @@ export function spotify(
     }
     const before = state.status;
     const wasSignedIn = state.loggedIn;
+    const wasActive = link === "open" ? undefined : state.active; // the first frames on a socket are not a change
     state = fold(state, f, asOf(clock));
+    if (state.track?.uri !== repairedFor) repairedFor = undefined; // one repair per play of a track
+    // Going active makes a new stream, at WirePlumber's saved level (live, 2026-11-09): the likeliest moment for a loud start.
+    if (wasActive === false && state.active === true)
+      ((capUntil = clock.now() + CAP_WINDOW_MS), (capped = false));
     if (f.type === "auth_state") {
       // Signed out there is no playback_state to wait for, and a later sign-in must not send the part back to connecting.
-      if (!heard && f.logged_in !== true) whole = true;
-      heard = true;
+      if (link === "open" || (link === "heard" && f.logged_in === false))
+        link = f.logged_in === true ? "heard" : "whole";
       if (f.logged_in === false) statusKnown = false;
       // A first sign-in (someone picked the speaker) sends only auth_state; the docs don't promise a playback_state after it.
       else if (f.logged_in === true && wasSignedIn === false)
@@ -423,15 +481,15 @@ export function spotify(
     }
     if (f.type === "playback_state") {
       if (!queueAsked) ((queueAsked = true), query("get_queue", { limit: 10 })); // queue_changed pushes changes only, so ask once per socket
-      whole = true;
+      link = "whole";
     }
     if (pending?.answers === f.type) pending.finish();
     if (
       (f.type === "playback_state" || f.type === "playback_changed") &&
       f.status !== undefined
     ) {
-      // A start is idle → playing or buffering, or a sign-in whose first status is either: a phone picked the speaker and played (issue #23).
-      // Soloist's jump to 100 comes about 100 ms after `playing` (issue #23), so a start through buffering opens the window again then.
+      // A start is idle → playing or buffering, or a sign-in whose first status is either: a phone picked the speaker and played.
+      // The volume can land just after `playing` (issue #23), so a start through buffering opens the window again then.
       const started =
         ((f.status === "playing" || f.status === "buffering") &&
           (statusKnown ? before === "idle" : signedIn)) ||
@@ -470,10 +528,8 @@ export function spotify(
         quiet.abort();
         signal.removeEventListener("abort", stop);
         if (socket === s) socket = undefined;
-        const was = open;
-        open = false;
-        heard = false;
-        whole = false;
+        const was = isOpen();
+        link = "down";
         queueAsked = false;
         statusKnown = false;
         signedIn = false;
@@ -488,17 +544,17 @@ export function spotify(
       // An ended socket's late events belong to no session: they must not touch the next socket's state.
       s.onopen = () => {
         if (ended) return;
-        open = true;
+        link = "open";
         down = undefined;
         note = undefined; // a new socket: what failed on the last one is history
         void clock.sleep(HELLO_MS, quiet.signal).then(() => {
           if (quiet.signal.aborted) return;
-          if (!heard)
+          if (link === "open")
             return (
               end(`Soloist said nothing in ${HELLO_MS / 1000} s`),
               s.close()
             );
-          if (!whole) ((whole = true), publish()); // signed in, no playback_state: connected with what there is
+          if (link === "heard") ((link = "whole"), publish()); // signed in, no playback_state: connected with what there is
         });
       };
       s.onmessage = (ev) => void (ended || handle(ev.data));
@@ -518,7 +574,7 @@ export function spotify(
 
   /** Not connected or not playing: the reason `duck` and `interrupt` just run `fn`. */
   const notPlaying = () =>
-    !open
+    !isOpen()
       ? "Soloist is not connected"
       : state.status === "playing" || state.status === "buffering"
         ? undefined
@@ -544,7 +600,7 @@ export function spotify(
     leave: () => Promise<Left>,
   ) => {
     const run = async (): Promise<Aside<T>> => {
-      if (open) marked(kind);
+      if (isOpen()) marked(kind);
       try {
         return await within();
       } finally {
@@ -578,10 +634,20 @@ export function spotify(
         };
 
   const actions: SpotifyActions = {
+    async activate() {
+      if (isOpen() && state.loggedIn !== false && state.active === true)
+        return { state, confirmed: true }; // a second activate might make a new stream
+      return change("activate", {
+        command: "activate",
+        took: (s) => s.active === true,
+      });
+    },
+    // A `play` while inactive didn't take live; going active first is untested for this. `resume` worked inactive, so it doesn't.
     async play(linkOrUri) {
       if (linkOrUri === undefined)
         return change("transport", {
           command: "play",
+          activeFirst: true,
           took: (s) => s.status === "playing",
         });
       const uri = toSpotifyUri(linkOrUri);
@@ -589,6 +655,7 @@ export function spotify(
       return change("transport", {
         command: "play",
         fields: { uri },
+        activeFirst: true,
         took: (s) =>
           s.status === "playing" &&
           (s.track?.uri === uri || s.context?.uri === uri),
@@ -632,6 +699,11 @@ export function spotify(
     async setVolume(volume) {
       if (!Number.isFinite(volume) || volume < 0 || volume > 100)
         throw invalid(`volume is 0–100, not ${volume}`);
+      if (inactive())
+        throw new ConnectorError(
+          "the speaker is not the active Spotify device, so Soloist would drop this; activate it first (`home spotify activate`; its volume may jump to the level last saved)",
+          { code: "inactive" },
+        );
       return volumeTo(
         Math.round(cap === undefined ? volume : Math.min(volume, cap)),
       );
@@ -673,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
@@ -712,6 +787,8 @@ export function spotify(
         async () => {
           const no = notPlaying();
           if (no) return no;
+          if (inactive())
+            return "it is not the active device, so its volume can't be changed";
           if (state.volume === undefined) return "its volume is not known";
           if (state.volume <= to) return `it was already at ${state.volume}`;
           earlier = state.volume;
@@ -724,7 +801,7 @@ export function spotify(
           }
         },
         async () => {
-          if (state.volume !== Math.round(to))
+          if (!near(state.volume, Math.round(to)))
             return {
               music: "kept",
               why: shown
@@ -766,7 +843,7 @@ export function spotify(
     state = rest;
   }
   let seen: { track: string; ms: number; atMs: number } | undefined; // the last check's reported position
-  let repairedFor: string | undefined; // at most one repair per track
+  let repairedFor: string | undefined; // at most one repair per play of a track
   /** Ask Soloist where it is, waiting for the answer (or the query's timeout). */
   const fresh = () =>
     write("query-get_state", {
@@ -793,7 +870,7 @@ export function spotify(
     a.track === b.track &&
     b.atMs - a.atMs >= gap &&
     Math.abs(b.ms - a.ms) < 1000;
-  const playing = () => open && state.status === "playing" && !state.aside;
+  const playing = () => isOpen() && state.status === "playing" && !state.aside;
 
   /** One look while playing: a fresh position, then frozen, overrun, recovered or fine (Soloist issue #5). */
   const checkStall = async () => {
@@ -837,7 +914,7 @@ export function spotify(
       state.stalled && stallAs({ ...state.stalled, tried: what });
     // Still ours to fix: playing this track, stalled, and no duck, interrupt or person in between.
     const ours = () =>
-      open &&
+      isOpen() &&
       state.status === "playing" &&
       state.track?.uri === track &&
       state.stalled?.track === track &&
@@ -875,9 +952,11 @@ export function spotify(
     /** Ask Soloist for its state again (`get_state`, or `get_auth_state` without a session); while it is unreachable, reconnect now. */
     refresh() {
       const s = socket;
-      if (s && open && s.readyState === OPEN)
+      if (s && isOpen() && s.readyState === OPEN)
         return query(
-          state.loggedIn === false || !heard ? "get_auth_state" : "get_state",
+          state.loggedIn === false || link === "open"
+            ? "get_auth_state"
+            : "get_state",
         );
       wake?.abort();
     },
@@ -935,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/README.md

@@ -7,7 +7,7 @@ Reads the household's spending from Up Bank's API: two months of transactions, s
 - **`client.ts`**: `upClient({ token, fetch })`. Reads: `ping`, `accounts(filter)`, `transactions(query)` following cursors to `limit` (default 1000) and `pageCap` (20) and returning `{ transactions, truncated }` so a cut-off list never looks complete, `transaction(id)`, `categories`, `tags`, `webhooks`, `webhook(id)`, `webhookLogs(id)`. Writes: `setCategory(id, categoryId | null)`, `addTags(id, labels)`, `removeTags(id, labels)`, each re-reading and returning the transaction as Up now holds it; `createWebhook`, `deleteWebhook`, `pingWebhook`. A transaction is flattened to cents (Up's `valueInBaseUnits`) and ids.
 - **`spend.ts`**, pure, one owner per number. `notSpend(t)` is the rule and says why: held, money in, `transferAccount` set (a movement between your own accounts), or a description Up gives its own movements ("Cover from", "Forward to", "Round Up", "Quick save transfer"). "Transfer to …" is not on the list: paying someone else is spend. `isSpend`, `spendByCategory` (parents and children, excluded movements counted and summed so a total can be checked), `spendByMerchant`, `uncategorised` (spend with no category; money in is categorisable too but left out), `recurring` (a heuristic: three or more months within 20% of the median), `unusual` (over twice the median of three or more earlier purchases at that merchant), `dollars` for display.
 - **`webhook.ts`**: `verifyWebhook(rawBody, signature, secret)`, the SHA-256 HMAC of the raw body in hex, Web Crypto, compared in constant time; `parseWebhookEvent(body)` gives the event type and the transaction id. A consumer's handler verifies, then calls `home.refresh("up")`.
-- **The integration** (`up({ token, account?, timeZone?, fetch })`): every 15 minutes it reads the categories, the accounts the filter names, and 63 days of transactions, then cuts this month and last in the home's time zone. The snapshot holds each month's spend by category and top five merchants, the ids still to categorise, and the latest 20 purchases trimmed to id, time, description, amount, category, status and tags (movements between your own accounts are left out: their descriptions name the accounts). Never kept: raw text, message, note, who spent (`performingCustomer`), account ids, balances. A 401 is `unavailable`; a read that hit its page cap is an `anomaly`, as is an amount missing or not in AUD. It never writes.
+- **The integration** (`up({ token, account?, timeZone?, fetch })`, with `client` on it for a consumer's writes): every 15 minutes it reads the categories, the accounts the filter names, and 63 days of transactions, then cuts this month and last in the home's time zone. The snapshot holds each month's spend by category and top five merchants, the ids still to categorise, and the latest 20 purchases trimmed to id, time, description, amount, category, status and tags (movements between your own accounts are left out: their descriptions name the accounts). Never kept: raw text, message, note, who spent (`performingCustomer`), account ids, balances. A 401 is `unavailable`; a read that hit its page cap is an `anomaly`, as is an amount missing or not in AUD. It never writes.
 - **Config**: `{ connector: "up", key: "UP_TOKEN", account: { ownershipType: "JOINT", accountType: "TRANSACTIONAL" } }`. Accounts are chosen by type and ownership, never by id. Without `account`, every account is read; transfers between them are excluded by `transferAccount`.
 - **CLI**: `home up` (this month, last month, to categorise, top five categories), `home up transactions [--since] [--until] [--category] [--tag] [--status] [--limit] [--json|--csv]`, `categories`, `uncategorised`, `spend [--by category|merchant|recurring]`, and the writes `categorise <id> <category|none>`, `tag <id> <label> [--remove]`, `webhooks [get|logs|ping|create|delete]`. `UP_ACCOUNT` ("JOINT TRANSACTIONAL") is the filter's env form.
 - **Household filter** (`household: { categories, tags }` in the config, `UP_HOUSEHOLD="home tag:home"` in env): the totals, top merchants and recent rows count only purchases in a listed category or its parent, or with a listed tag, so a family dashboard shows groceries and utilities, not personal spending. Tag anything else `home` in the Up app to bring it in. "To categorise" still looks at every purchase, since a category is how one joins. A listed category Up does not have is an `anomaly`, not a silent zero. `inHousehold` is the one owner of the rule; `home up spend` applies it too. `webhooks create` writes the secret Up returns once to `~/.config/home/up-webhook-<id>.secret` (0600); it is never printed.

package/src/connectors/up/index.ts

@@ -241,13 +241,16 @@ export function toSnapshot(
   };
 }
 
-/** Up as a home integration: two months of transactions now, then every 15 minutes. Reads only; it never writes. */
-export function up(config: UpConfig): Integration<UpSnapshot, "up"> {
+/** Up as a home integration: two months of transactions now, then every 15 minutes. The integration only reads; `client` is there for a consumer's writes. */
+export function up(config: UpConfig): Integration<UpSnapshot, "up"> & {
+  client: UpClient;
+} {
   const client = upClient(config);
   const clock = config.clock ?? realClock;
   const poll = poller(clock);
   return {
     name: "up",
+    client,
     refresh: poll.nudge,
     async run(signal, update) {
       let last: UpSnapshot | undefined;
@@ -288,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