@khalido/home 0.1.1 → 0.1.3

package/dist/connectors/spotify/index.js

@@ -1,8 +1,9 @@
 import { z } from "zod";
 import { asOf, realClock } from "../../clock.js";
 import { ConnectorError, errorText } from "../../connector.js";
+import { deviceRecords, } from "../../home.js";
 import { writeLane } from "../../lane.js";
-import { spotifyText, stallText } from "./changes.js";
+import { speakerState, spotifyText, stallText, } from "./changes.js";
 import { commandFrame, fold, Frame, FRAME_TYPES, OPEN, oddities, positionMs, toSpotifyUri, } from "./client.js";
 export { positionMs, toSpotifyUri, } from "./client.js";
 export { speakerState, spotifyChanges, spotifyText, } from "./changes.js";
@@ -33,10 +34,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. */
@@ -45,6 +48,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;
 /** Signed out is Soloist's normal state until someone picks the speaker (seen live 2026-11-08); a bad key looks the same (issue #18). */
@@ -78,15 +83,16 @@ export function spotify(config = {}) {
     const checkMs = config.stallCheckMs ?? STALL_CHECK_MS;
     let state = { asOf: asOf(clock) };
     let socket;
-    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";
+    const isOpen = () => link !== "down";
     let down; // 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; // the last first-play lowering, in `anomaly` until the speaker goes idle
     let frameNote; // a frame the schema rejected, or an error nothing was waiting for
@@ -99,10 +105,10 @@ export function spotify(config = {}) {
     const publish = () => {
         let status;
         let detail;
-        if (!open)
+        if (link === "down")
             ((status = reported || down ? "disconnected" : "connecting"),
                 (detail = down));
-        else if (!heard || (state.loggedIn === true && !whole))
+        else if (link !== "whole")
             status = "connecting";
         else
             ((status = "connected"),
@@ -128,7 +134,7 @@ export function spotify(config = {}) {
      */
     const command = (name, fields = {}, answers) => new Promise((resolve, reject) => {
         const s = socket;
-        if (!s || !open || s.readyState !== OPEN)
+        if (!s || !isOpen() || s.readyState !== OPEN)
             return reject(offline());
         if (state.loggedIn === false && !answers)
             return reject(new ConnectorError(WAITING, { code: "waiting" }));
@@ -157,11 +163,17 @@ export function spotify(config = {}) {
             p.finish(new ConnectorError(`Soloist did not answer ${name} in ${ms / 1000} s`, { code: "timeout" })));
     });
     const send = async (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)
+        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
@@ -174,7 +186,7 @@ export function spotify(config = {}) {
     const change = async (slot, body) => {
         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). */
@@ -183,11 +195,14 @@ export function spotify(config = {}) {
         (positionMs(b, at) ?? 0) >= 5000;
     const newTrack = (s, b) => !!s.track && s.track.uri !== b.track?.uri;
     const invalid = (message) => new ConnectorError(message, { code: "invalid" });
+    const near = (volume, v) => volume !== undefined && Math.abs(volume - v) <= VOLUME_SLACK;
     const volumeTo = (v) => 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",
@@ -207,22 +222,50 @@ export function spotify(config = {}) {
         frameNote = `${name} failed: ${errorText(error)}`;
         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();
+        });
     };
     const handle = (data) => {
         let raw;
@@ -254,12 +297,17 @@ export function spotify(config = {}) {
         }
         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.
@@ -269,14 +317,14 @@ export function spotify(config = {}) {
         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)) ||
                 (f.status === "playing" && startBuffering);
@@ -319,10 +367,8 @@ export function spotify(config = {}) {
             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;
@@ -339,17 +385,17 @@ export function spotify(config = {}) {
         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));
@@ -367,7 +413,7 @@ export function spotify(config = {}) {
         waiters.delete(check);
     };
     /** Not connected or not playing: the reason `duck` and `interrupt` just run `fn`. */
-    const notPlaying = () => !open
+    const notPlaying = () => !isOpen()
         ? "Soloist is not connected"
         : state.status === "playing" || state.status === "buffering"
             ? undefined
@@ -388,7 +434,7 @@ export function spotify(config = {}) {
      */
     const aside = (kind, fn, enter, leave) => {
         const run = async () => {
-            if (open)
+            if (isOpen())
                 marked(kind);
             try {
                 return await within();
@@ -423,10 +469,20 @@ export function spotify(config = {}) {
             why: failed(`sent the ${what}; Soloist has not reported it`),
         };
     const actions = {
+        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);
@@ -435,6 +491,7 @@ export function spotify(config = {}) {
             return change("transport", {
                 command: "play",
                 fields: { uri },
+                activeFirst: true,
                 took: (s) => s.status === "playing" &&
                     (s.track?.uri === uri || s.context?.uri === uri),
             });
@@ -471,6 +528,8 @@ export function spotify(config = {}) {
         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)));
         },
         async queue(track) {
@@ -507,6 +566,9 @@ export function spotify(config = {}) {
                 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
@@ -544,6 +606,8 @@ export function spotify(config = {}) {
                 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)
@@ -556,7 +620,7 @@ export function spotify(config = {}) {
                     return failed(`lowering the volume for duck failed: ${errorText(error)}`);
                 }
             }, async () => {
-                if (state.volume !== Math.round(to))
+                if (!near(state.volume, Math.round(to)))
                     return {
                         music: "kept",
                         why: shown
@@ -593,7 +657,7 @@ export function spotify(config = {}) {
         state = rest;
     }
     let seen; // the last check's reported position
-    let repairedFor; // at most one repair per track
+    let repairedFor; // 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", {
         command: "get_state",
@@ -614,7 +678,7 @@ export function spotify(config = {}) {
         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 () => {
         if (!playing())
@@ -654,7 +718,7 @@ export function spotify(config = {}) {
         repairedFor = track;
         const tried = (what) => 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 &&
+        const ours = () => isOpen() &&
             state.status === "playing" &&
             state.track?.uri === track &&
             state.stalled?.track === track &&
@@ -698,8 +762,10 @@ export function spotify(config = {}) {
         /** 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)
-                return query(state.loggedIn === false || !heard ? "get_auth_state" : "get_state");
+            if (s && isOpen() && s.readyState === OPEN)
+                return query(state.loggedIn === false || link === "open"
+                    ? "get_auth_state"
+                    : "get_state");
             wake?.abort();
         },
         async run(signal, update) {
@@ -752,3 +818,22 @@ export const manifest = {
         ? [spotifyText(state)]
         : [],
 };
+/** The one speaker, once Soloist has said something. Its name is Soloist's `--device-name`, the one phones show. */
+export function spotifyHomeDevices(part) {
+    const s = part?.state;
+    if (!s || (s.loggedIn === undefined && s.status === undefined))
+        return [];
+    return deviceRecords(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/dist/connectors/up/index.d.ts

@@ -82,8 +82,10 @@ export declare function toSnapshot(txs: Transaction[], categories: Category[], a
     truncated: boolean;
     household?: Household;
 }): UpSnapshot;
-/** Up as a home integration: two months of transactions now, then every 15 minutes. Reads only; it never writes. */
-export declare 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 declare function up(config: UpConfig): Integration<UpSnapshot, "up"> & {
+    client: UpClient;
+};
 /** "Oct so far $2,140 · Sep $1,980 · 3 to categorise": this month's spend against last month's. */
 export declare function upText(s: UpSnapshot): string;
 /** One line per parent category this month, largest five: "home $1,030: groceries $620, utilities $410". */

package/dist/connectors/up/index.js

@@ -97,13 +97,14 @@ export function toSnapshot(txs, categories, at) {
         truncated: at.truncated,
     };
 }
-/** Up as a home integration: two months of transactions now, then every 15 minutes. Reads only; it never writes. */
+/** 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) {
     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;
@@ -141,6 +142,7 @@ export function up(config) {
                     if (error instanceof UpError && error.status === 401)
                         return update({
                             status: "unavailable",
+                            reason: "auth",
                             detail: "Up rejected the token",
                             state: last,
                         });

package/dist/connectors/weather/bom.js

@@ -185,6 +185,7 @@ export function bom(options = {}) {
             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/dist/connectors/weather/google.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { getJson } from "../../connector.js";
+import { ConnectorError, fetchTimeout } from "../../connector.js";
 import { RAIN_INTENSITIES } from "./rain.js";
 import { sunDisagrees } from "./sun.js";
 import { HOURLY_MINUTES, iso, nextPoll, num, RAIN_HORIZON_MINUTES, USER_AGENT, } from "./source.js";
@@ -273,6 +273,28 @@ export function toRain(minutes, fetchedAt) {
  */
 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) {
+    try {
+        const body = (await res.json());
+        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 {
+    why;
+    constructor(message, status, why) {
+        super(message, { status });
+        this.why = why;
+    }
+}
 /**
  * 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).
@@ -295,11 +317,20 @@ export function google(options) {
         },
         minPollMinutes: MIN_POLL_MINUTES,
         async read({ place, at, pollMinutes, force, signal, }) {
-            const q = (extra) => `key=${encodeURIComponent(options.key)}&location.latitude=${place.latitude}&location.longitude=${place.longitude}${extra}`;
-            const json = (path) => getJson(fetcher, `${base}/${path}`, {
-                init: { headers: { "user-agent": USER_AGENT } },
-                signal,
-            });
+            const q = (extra) => `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) => {
+                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 }), (error) => ({ error: error }));
             let problem;
@@ -324,10 +355,22 @@ export function google(options) {
                 }
             }
             catch (error) {
-                const status = error.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
+                    : {};
+                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.message}`; // the old slices stay; the minute forecast below is still used

package/dist/connectors/weather/index.d.ts

@@ -1,5 +1,5 @@
 import { type Clock } from "../../clock.ts";
-import type { Integration } from "../../home.ts";
+import type { Integration, Reason } from "../../home.ts";
 import { type Manifest } from "../../manifest.ts";
 import { type BlockDef, type DayBlocks } from "./blocks.ts";
 import { type RainSoon } from "./rain.ts";
@@ -38,6 +38,7 @@ export type WeatherState = Slices & {
         read: boolean;
         problem?: string;
         stopped?: string;
+        reason?: Exclude<Reason, "crashed">;
         anomaly?: string;
     }>;
 };

package/dist/connectors/weather/index.js

@@ -66,6 +66,7 @@ export function weather(config) {
                             read: r !== undefined,
                             problem: r?.problem,
                             stopped: r?.stop,
+                            reason: r?.stop ? (r.stopReason ?? "config") : undefined,
                             anomaly: r?.anomaly,
                         },
                     ];
@@ -87,6 +88,12 @@ export function weather(config) {
                     : undefined;
                 update({
                     status,
+                    // Every source has stopped: a rejected key outranks a wrong setting, since it needs a person.
+                    reason: status !== "unavailable"
+                        ? undefined
+                        : Object.values(report).some((r) => r.reason === "auth")
+                            ? "auth"
+                            : "config",
                     detail,
                     anomaly: notes("anomaly"),
                     lastGoodAt,

package/dist/connectors/weather/source.d.ts

@@ -1,3 +1,4 @@
+import type { Reason } from "../../home.ts";
 /** Sent on every request, so each service can see who is calling rather than a runtime's default string. */
 export declare const USER_AGENT = "home (+https://github.com/khalido/home.ts)";
 export type Place = {
@@ -116,6 +117,7 @@ export type SourceReading = Slices & {
     problem?: string;
     anomaly?: string;
     stop?: string;
+    stopReason?: Exclude<Reason, "crashed">;
 };
 /**
  * A weather provider. `owns` names the slices it can fill and how old each may get (by its `at`, beyond one polling

package/dist/devices.d.ts

@@ -0,0 +1,27 @@
+import { type CastHomeDevice, castHomeDevices } from "./connectors/cast/index.ts";
+import { type DaikinHomeDevice, daikinHomeDevices } from "./connectors/daikin/index.ts";
+import { type EnphaseHomeDevice, enphaseHomeDevices } from "./connectors/enphase/index.ts";
+import { type HueHomeDevice, hueHomeDevices } from "./connectors/hue/index.ts";
+import { type PrinterHomeDevice, printersHomeDevices } from "./connectors/printers/index.ts";
+import { type SpotifyHomeDevice, spotifyHomeDevices } from "./connectors/spotify/index.ts";
+import type { HomeConfig } from "./config.ts";
+import type { Part } from "./home.ts";
+/** Any device this library reads. `connector`, then `kind` where a connector has more than one, narrows `detail` and `state`. */
+export type HomeDevice = HueHomeDevice | DaikinHomeDevice | EnphaseHomeDevice | CastHomeDevice | PrinterHomeDevice | SpotifyHomeDevice;
+/** Each connector's devices from its part, in the order `home status` lists the connectors. */
+export declare const DEVICES: {
+    hue: typeof hueHomeDevices;
+    daikin: typeof daikinHomeDevices;
+    enphase: typeof enphaseHomeDevices;
+    cast: typeof castHomeDevices;
+    printers: typeof printersHomeDevices;
+    spotify: typeof spotifyHomeDevices;
+};
+/** Connectors that read a service, not a device: nothing to list. */
+export declare const SERVICES: readonly string[];
+/**
+ * Every device in the snapshot. With the home `config`, a device takes the `room` its entry gives it, a Hue room or zone
+ * (and its lights) the room whose `hueRoom` names it (a light in a room and a zone, the room's), and a device that reports
+ * no name of its own (the Daikin, the Enphase gateway) the entry's `name`. A device's own name is never replaced.
+ */
+export declare function homeDevices(snapshot: Record<string, Part | undefined>, config?: Pick<HomeConfig, "devices" | "rooms">): HomeDevice[];