@khalido/home 0.2.0 → 0.2.2

package/src/connectors/spotify/README.md

@@ -26,6 +26,8 @@ Soloist is Spotify's own headless Spotify Connect client (Linux arm64, armv7, x8
 
 **`maxVolume`** holds requests (rounded to a whole percent). For 10 s after a start signal, a reported volume above it is lowered: a start from idle (to playing or buffering), the first such status after a sign-in, `playing` after a start through buffering, or the speaker going active. Event order differs between runs, so no one pattern is relied on. It waits until the speaker is active, retries until Soloist reports the lower volume, and only then says so in `anomaly`, until the speaker goes idle; if it never shows or Soloist refuses it, `detail` says so. A reported volume within 1 of the cap is left alone. Not on resuming from pause while active, not on connecting to a song already playing, and a person turning it up after the lowering keeps it (before Soloist has reported the lowering, a person's raise looks like the start's own jump and is lowered too). `--initial-volume` is ignored on PipeWire ([#23](https://github.com/spotify/soloist/issues/23)).
 
+**Dry run.** Every write takes `{ dryRun: true }` last: the checks run (connected, signed in, the input, `inactive` for `setVolume`, `maxVolume`), nothing is sent, and it resolves `confirmed: false` with `wouldSend`, the commands in order (an inactive speaker's `play` lists `activate` first). `duck` and `interrupt` with `dryRun` run `fn`, touch nothing, and say in `why` what they would have done; they don't wait behind a real `duck` or `interrupt`. Tested on a fake socket only.
+
 **`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, 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.
@@ -58,6 +60,8 @@ Not built: `deactivate`, `available_actions`. An ad (`entity_type: "ad"`) shows
 
 ## Unverified
 
+What Soloist does that this connector works around, and the upstream issues to watch: [khalido/home.ts#1](https://github.com/khalido/home.ts/issues/1).
+
 Writes through this connector, and what a live read hasn't shown. In particular:
 
 - **Stalls:** whether the reported position freezes in one (if not, only an overrun is caught), whether `get_state` re-anchors the position, and whether a seek or a pause and play restarts it.
@@ -70,7 +74,7 @@ Writes through this connector, and what a live read hasn't shown. In particular:
 
 **2026-11-11, Raspberry Pi 5, Bun 1.4.4, on 0.1.3** (chota-bot's session; `maxVolume: 40` watching, writes from the CLI in another process). Two gaps in the cap, not fixed:
 
-- From inactive and paused at 60, `play`: lowered to 40 within 2 ms of going active, `playing` at 40, then 60 again 90 ms after `playing`, and it played at 60. The cap takes its first confirmed lowering as done, so nothing lowered it again, and `anomaly` still said "lowered it". Soloist puts its own level back after `playing`.
+- From inactive and paused at 60, `play`: lowered to 40 within 2 ms of going active, `playing` at 40, then 60 again 90 ms after `playing`, and it played at 60. The cap takes its first confirmed lowering as done, so nothing lowered it again, and `anomaly` still said "lowered it". After 0.2.0 the note adds "it is back at 60"; the level is left alone, since it is the one the speaker was playing at. Soloist puts its own level back after `playing`.
 - The connector started while the speaker was already active and paused at 60: `play` resumed at 60, nothing lowered it, no anomaly. This is the documented "not on resuming from pause while active".
 - A volume set by hand (35) held through pause and play, so the put-back belongs to activation, not to pause.
 

package/src/connectors/spotify/changes.ts

@@ -138,7 +138,7 @@ export function spotifyChanges(
 /**
  * The speaker in a few words: `Kitchen speaker: playing "Song" by Band · 35%`, `…: waiting for someone to pick it`, or,
  * for music on another Spotify device, `…: silent · "Song" by Band is playing on another Spotify device` (no volume: it isn't this speaker's playing level).
- * `on` names where, when the caller knows (`spotifyElsewhere`): `… is playing on Front room speaker`.
+ * `on` names where, when the caller knows (`spotifyElsewhere`): `… is playing on Den speaker`.
  */
 export function spotifyText(s: SpotifyState, on: string[] = []): string {
   const who = s.deviceName ?? "Soloist";

package/src/connectors/spotify/index.ts

@@ -96,8 +96,23 @@ export type SpotifyConfig = {
 /** Soloist's repeat modes. */
 export type Repeat = "off" | "context" | "track";
 
-/** What a write left: the state once Soloist reported the change (`confirmed`), or the state as it stood when `CONFIRM_MS` ran out without it. */
-export type Applied = { state: SpotifyState; confirmed: boolean };
+/** One WebSocket command, as a dry run reports it: Soloist's command name and its fields. */
+export type SpotifyRequest = {
+  command: string;
+  fields?: Record<string, unknown>;
+};
+/** `dryRun`: run every check a real write runs (connected, signed in, the input), send nothing, and say what would go. */
+export type SpotifyWriteOptions = { dryRun?: boolean };
+
+/**
+ * What a write left: the state once Soloist reported the change (`confirmed`), or the state as it stood when `CONFIRM_MS`
+ * ran out without it. A dry run resolves `confirmed: false` with `wouldSend`, the commands in order; an `activate` already done resolves `confirmed: true` with `wouldSend: []`.
+ */
+export type Applied = {
+  state: SpotifyState;
+  confirmed: boolean;
+  wouldSend?: SpotifyRequest[];
+};
 
 /**
  * What happened to the music around `duck` or `interrupt`'s `fn`: `untouched` (it was not playing, not connected, already
@@ -115,34 +130,41 @@ export type Aside<T> = { value: T; music: Music; why?: string };
  */
 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>;
+  activate(options?: SpotifyWriteOptions): 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>;
-  resume(): Promise<Applied>;
-  next(): Promise<Applied>;
-  prev(): Promise<Applied>;
+  play(linkOrUri?: string, options?: SpotifyWriteOptions): Promise<Applied>;
+  pause(options?: SpotifyWriteOptions): Promise<Applied>;
+  resume(options?: SpotifyWriteOptions): Promise<Applied>;
+  next(options?: SpotifyWriteOptions): Promise<Applied>;
+  prev(options?: SpotifyWriteOptions): Promise<Applied>;
   /** Jump to a position in the current track, in ms. */
-  seek(ms: number): Promise<Applied>;
+  seek(ms: number, options?: SpotifyWriteOptions): Promise<Applied>;
   /** Set the volume 0–100, held to `maxVolume` and rounded to a whole percent: `state.volume` is what Soloist then reports. */
-  setVolume(volume: number): Promise<Applied>;
+  setVolume(volume: number, options?: SpotifyWriteOptions): Promise<Applied>;
   /** Add a track to the queue (Soloist queues tracks only); confirmed when it shows in `upNext`. */
-  queue(track: string): Promise<Applied>;
-  setShuffle(on: boolean): Promise<Applied>;
+  queue(track: string, options?: SpotifyWriteOptions): Promise<Applied>;
+  setShuffle(on: boolean, options?: SpotifyWriteOptions): Promise<Applied>;
   /** Repeat off, the context (playlist, album) or the track: two commands, in the order Soloist's docs give, as one write. */
-  setRepeat(mode: Repeat): Promise<Applied>;
+  setRepeat(mode: Repeat, options?: SpotifyWriteOptions): Promise<Applied>;
   /**
    * Pause if playing, run `fn`, then resume, unless someone changed it meanwhile (resumed, stopped or skipped it from a
    * phone): then it is theirs and stays. The resume runs even if `fn` throws. Not playing or not connected: just `fn`.
    * One `interrupt` or `duck` at a time; a second waits for the first, so never call either from inside `fn` (it would wait
    * forever). Two announcements back to back belong in one `fn`, or the music comes back between them.
    */
-  interrupt<T>(fn: () => Promise<T> | T): Promise<Aside<T>>;
+  interrupt<T>(
+    fn: () => Promise<T> | T,
+    options?: SpotifyWriteOptions,
+  ): Promise<Aside<T>>;
   /**
    * Lower the volume to `to` while `fn` runs, then put the earlier volume back, unless someone set the volume meanwhile.
    * For a short announcement over the music. Not playing, not connected or already at `to` or below: just `fn`.
+   * With `dryRun`, `interrupt` and `duck` run `fn`, touch nothing, and say in `why` what they would have done.
    */
-  duck<T>(fn: () => Promise<T> | T, options: { to: number }): Promise<Aside<T>>;
+  duck<T>(
+    fn: () => Promise<T> | T,
+    options: { to: number } & SpotifyWriteOptions,
+  ): Promise<Aside<T>>;
 };
 
 /** How long a command waits for Soloist's answer. Loopback answers in milliseconds; a stated guess. */
@@ -332,12 +354,34 @@ export function spotify(
    * Soloist accepted the command that carried it (a merged write's may be another's: a pause merged into a later play never
    * confirms). A drop ends the wait early, unconfirmed.
    */
-  const change = async (slot: string, body: Body): Promise<Applied> => {
+  const change = async (
+    slot: string,
+    body: Body,
+    options: SpotifyWriteOptions = {},
+  ): Promise<Applied> => {
+    if (options.dryRun) return dry(body);
     const sent = await write(slot, body);
     const took = () => body.took?.(state, sent.before, sent.at) ?? true;
     await waitFor(() => took() || !isOpen(), CONFIRM_MS);
     return { state, confirmed: took() };
   };
+  /** A dry run: `command`'s own checks (connected, signed in), then the commands `send` would send, in order. */
+  const dry = (body: Body): Applied => {
+    if (!socket || !isOpen() || socket.readyState !== OPEN) throw offline();
+    if (state.loggedIn === false)
+      throw new ConnectorError(WAITING, { code: "waiting" });
+    const one = (command: string, fields?: Record<string, unknown>) =>
+      fields ? { command, fields } : { command };
+    return {
+      state,
+      confirmed: false,
+      wouldSend: [
+        ...(body.activeFirst && inactive() ? [one("activate")] : []),
+        one(body.command, body.fields),
+        ...(body.then ? [one(body.then.command, body.then.fields)] : []),
+      ],
+    };
+  };
   /** 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). */
   const restarted = (s: SpotifyState, b: SpotifyState, at: number) =>
     s.position !== b.position &&
@@ -349,12 +393,16 @@ export function spotify(
     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) => near(s.volume, v),
-    });
+  const volumeTo = (v: number, options?: SpotifyWriteOptions) =>
+    change(
+      "volume",
+      {
+        command: "set_volume",
+        fields: { volume: v },
+        took: (s) => near(s.volume, v),
+      },
+      options,
+    );
   /** 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;
@@ -390,6 +438,17 @@ export function spotify(
    * one raised before it is reported can't be told from the start's own jump, so it is lowered too.
    */
   const applyCap = () => {
+    // Lowered, then above the cap again in the same window: Soloist putting its own level back (seen live) or a person.
+    // The note says where it is now, not only that it was lowered.
+    if (capped && capNote && cap !== undefined && state.volume !== undefined) {
+      const base = capNote.replace(/; it is back at \d+$/, "");
+      const note =
+        state.volume > cap + VOLUME_SLACK
+          ? `${base}; it is back at ${state.volume}`
+          : base;
+      if (note !== capNote) ((capNote = note), publish());
+      return;
+    }
     if (
       cap === undefined ||
       capped ||
@@ -410,7 +469,7 @@ export function spotify(
         if (confirmed) {
           capped = true;
           if (state.status === "idle") return;
-          capNote = `started at volume ${from}, above maxVolume ${cap}; lowered it (Soloist issue #23)`;
+          capNote = `started at volume ${from}, above maxVolume ${cap}; lowered it to ${cap} (Soloist issue #23)`;
           note = undefined;
           return publish();
         }
@@ -626,6 +685,33 @@ export function spotify(
     return p;
   };
   type Left = Omit<Aside<never>, "value">;
+  /** Why `interrupt` would leave the music alone, if it would. */
+  const interruptSkip = () =>
+    notPlaying() ??
+    // "playing" while inactive is the account playing on another speaker (live, 2026-11-10): a pause would stop that one.
+    (inactive()
+      ? "it is not the active device, so the music playing is on another speaker"
+      : undefined);
+  /** Why `duck` would leave the volume alone, if it would. */
+  const duckSkip = (to: number) =>
+    notPlaying() ??
+    (inactive()
+      ? "it is not the active device, so its volume can't be changed"
+      : state.volume === undefined
+        ? "its volume is not known"
+        : state.volume <= to
+          ? `it was already at ${state.volume}`
+          : undefined);
+  /** A dry `interrupt` or `duck`: `fn` runs, the music is not touched, and `why` says what would have happened to it. */
+  const dryAside = async <T>(
+    fn: () => Promise<T> | T,
+    skip: string | undefined,
+    would: string,
+  ): Promise<Aside<T>> => ({
+    value: await fn(),
+    music: "untouched",
+    why: `dry run: ${skip ? `${skip}, so the music would be left alone` : `would ${would}`}`,
+  });
   const putBack = (r: Applied, what: string): Left =>
     r.confirmed
       ? { music: "restored" }
@@ -635,69 +721,96 @@ export function spotify(
         };
 
   const actions: SpotifyActions = {
-    async activate() {
+    async activate(options) {
       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,
-      });
+        return {
+          state,
+          confirmed: true,
+          ...(options?.dryRun ? { wouldSend: [] } : {}),
+        }; // a second activate might make a new stream
+      return change(
+        "activate",
+        { command: "activate", took: (s) => s.active === true },
+        options,
+      );
     },
     // 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) {
+    async play(linkOrUri, options) {
       if (linkOrUri === undefined)
-        return change("transport", {
-          command: "play",
-          activeFirst: true,
-          took: (s) => s.status === "playing",
-        });
+        return change(
+          "transport",
+          {
+            command: "play",
+            activeFirst: true,
+            took: (s) => s.status === "playing",
+          },
+          options,
+        );
       const uri = toSpotifyUri(linkOrUri);
       if (!uri) throw invalid(`not a Spotify link or URI: ${linkOrUri}`);
-      return change("transport", {
-        command: "play",
-        fields: { uri },
-        activeFirst: true,
-        took: (s) =>
-          s.status === "playing" &&
-          (s.track?.uri === uri || s.context?.uri === uri),
-      });
+      return change(
+        "transport",
+        {
+          command: "play",
+          fields: { uri },
+          activeFirst: true,
+          took: (s) =>
+            s.status === "playing" &&
+            (s.track?.uri === uri || s.context?.uri === uri),
+        },
+        options,
+      );
     },
-    pause: () =>
-      change("transport", {
-        command: "pause",
-        took: (s) => s.status === "paused",
-      }),
-    resume: () =>
-      change("transport", {
-        command: "play",
-        took: (s) => s.status === "playing",
-      }),
+    pause: (options) =>
+      change(
+        "transport",
+        { command: "pause", took: (s) => s.status === "paused" },
+        options,
+      ),
+    resume: (options) =>
+      change(
+        "transport",
+        { command: "play", took: (s) => s.status === "playing" },
+        options,
+      ),
     // The end of the queue goes idle; repeat-track restarts it.
-    next: () =>
-      change(`once-${++once}`, {
-        command: "skip_next",
-        took: (s, b, at) =>
-          newTrack(s, b) ||
-          (s.status === "idle" && b.status !== "idle") ||
-          restarted(s, b, at),
-      }),
-    prev: () =>
-      change(`once-${++once}`, {
-        command: "skip_prev",
-        took: (s, b, at) => newTrack(s, b) || restarted(s, b, at),
-      }),
-    async seek(ms) {
+    next: (options) =>
+      change(
+        `once-${++once}`,
+        {
+          command: "skip_next",
+          took: (s, b, at) =>
+            newTrack(s, b) ||
+            (s.status === "idle" && b.status !== "idle") ||
+            restarted(s, b, at),
+        },
+        options,
+      ),
+    prev: (options) =>
+      change(
+        `once-${++once}`,
+        {
+          command: "skip_prev",
+          took: (s, b, at) => newTrack(s, b) || restarted(s, b, at),
+        },
+        options,
+      ),
+    async seek(ms, options) {
       if (!Number.isFinite(ms) || ms < 0)
         throw invalid(`a position in ms, 0 or more, not ${ms}`);
-      return change("seek", {
-        command: "seek",
-        fields: { position_ms: ms },
-        took: (s, b) =>
-          s.position !== b.position &&
-          Math.abs((s.position?.ms ?? -Infinity) - ms) < 2000,
-      });
+      return change(
+        "seek",
+        {
+          command: "seek",
+          fields: { position_ms: ms },
+          took: (s, b) =>
+            s.position !== b.position &&
+            Math.abs((s.position?.ms ?? -Infinity) - ms) < 2000,
+        },
+        options,
+      );
     },
-    async setVolume(volume) {
+    async setVolume(volume, options) {
       if (!Number.isFinite(volume) || volume < 0 || volume > 100)
         throw invalid(`volume is 0–100, not ${volume}`);
       if (inactive())
@@ -707,48 +820,60 @@ export function spotify(
         );
       return volumeTo(
         Math.round(cap === undefined ? volume : Math.min(volume, cap)),
+        options,
       );
     },
-    async queue(track) {
+    async queue(track, options) {
       const uri = toSpotifyUri(track);
       if (!uri?.startsWith("spotify:track:"))
         throw invalid(`only a Spotify track can be queued, not ${track}`);
-      return change(`once-${++once}`, {
-        command: "add_to_queue",
-        fields: { uri },
-        took: (s) => !!s.upNext?.some((t) => t.uri === uri),
-      });
+      return change(
+        `once-${++once}`,
+        {
+          command: "add_to_queue",
+          fields: { uri },
+          took: (s) => !!s.upNext?.some((t) => t.uri === uri),
+        },
+        options,
+      );
     },
-    setShuffle: (on) =>
-      change("shuffle", {
-        command: "set_shuffle",
-        fields: { enabled: on },
-        took: (s) => s.shuffle === on,
-      }),
-    async setRepeat(mode) {
+    setShuffle: (on, options) =>
+      change(
+        "shuffle",
+        {
+          command: "set_shuffle",
+          fields: { enabled: on },
+          took: (s) => s.shuffle === on,
+        },
+        options,
+      ),
+    async setRepeat(mode, options) {
       // developer.spotify.com/documentation/soloist/reference/websocket-api: clear the other mode first, then set this one.
       if (!Object.hasOwn(REPEAT_ORDER, mode))
         throw invalid(`repeat is off, context or track, not ${mode}`);
       const [first, second] = REPEAT_ORDER[mode];
-      return change("repeat", {
-        command: first[0],
-        fields: { enabled: first[1] },
-        then: { command: second[0], fields: { enabled: second[1] } },
-        took: (s) => s.repeat === mode,
-      });
+      return change(
+        "repeat",
+        {
+          command: first[0],
+          fields: { enabled: first[1] },
+          then: { command: second[0], fields: { enabled: second[1] } },
+          took: (s) => s.repeat === mode,
+        },
+        options,
+      );
     },
-    interrupt(fn) {
+    interrupt(fn, options) {
+      if (options?.dryRun)
+        return dryAside(fn, interruptSkip(), "pause the music, then resume it");
       let track: string | undefined;
       let shown = false; // the pause showed
       return aside(
         "interrupt",
         fn,
         async () => {
-          const no = notPlaying();
+          const no = interruptSkip();
           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
@@ -777,22 +902,24 @@ export function spotify(
         },
       );
     },
-    duck(fn, { to }) {
+    duck(fn, { to, dryRun }) {
       if (!Number.isFinite(to) || to < 0 || to > 100)
         return Promise.reject(invalid(`duck's volume is 0–100, not ${to}`));
+      if (dryRun)
+        return dryAside(
+          fn,
+          duckSkip(to),
+          `lower the volume from ${state.volume} to ${Math.round(to)}, then put it back`,
+        );
       let earlier = 0;
       let shown = false; // the lowered volume showed
       return aside(
         "duck",
         fn,
         async () => {
-          const no = notPlaying();
+          const no = duckSkip(to);
           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;
+          earlier = state.volume!;
           try {
             shown = (await volumeTo(Math.round(to))).confirmed;
           } catch (error) {

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 })`, 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.
+- **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 or 403 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/client.ts

@@ -6,7 +6,7 @@ import { ConnectorError, fetchTimeout, getJson } from "../../connector.ts";
 
 const BASE = "https://api.up.com.au/api/v1";
 
-/** A failed Up call. `status` 401 means the token is wrong or revoked; 429 the rate limit (unpublished: read `X-RateLimit-Remaining`). */
+/** A failed Up call. `status` 401 or 403 (`isRejectedKey`) means the token is wrong or revoked; 429 the rate limit (unpublished: read `X-RateLimit-Remaining`). */
 export class UpError extends ConnectorError {}
 
 const Money = z.looseObject({

package/src/connectors/up/index.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { asOf, type Clock, realClock } from "../../clock.ts";
-import { errorText } from "../../connector.ts";
+import { errorText, isRejectedKey } from "../../connector.ts";
 import { envName, type Integration } from "../../home.ts";
 import type { Manifest } from "../../manifest.ts";
 import { poller } from "../../poll.ts";
@@ -288,7 +288,7 @@ export function up(config: UpConfig): Integration<UpSnapshot, "up"> & {
           });
         } catch (error) {
           if (signal.aborted) return; // stopped mid-read: not a failure
-          if (error instanceof UpError && error.status === 401)
+          if (isRejectedKey(error))
             return update({
               status: "unavailable",
               reason: "auth",

package/src/connectors/weather/google.ts

@@ -1,5 +1,9 @@
 import { z } from "zod";
-import { ConnectorError, fetchTimeout } from "../../connector.ts";
+import {
+  ConnectorError,
+  fetchTimeout,
+  isRejectedKey,
+} from "../../connector.ts";
 import { RAIN_INTENSITIES } from "./rain.ts";
 import { sunDisagrees } from "./sun.ts";
 import {
@@ -434,7 +438,7 @@ export function google(options: GoogleOptions): WeatherSource {
             ? error
             : ({} as { status?: number; why?: string });
         const said = `HTTP ${status}${why ? ` ${why}` : ""}`;
-        if (status === 401 || status === 403 || why?.startsWith("API_KEY_"))
+        if (isRejectedKey(error) || why?.startsWith("API_KEY_"))
           return {
             stop: `google: the key was rejected (${said})`,
             stopReason: "auth",