@khalido/home 0.0.0-stage → 0.1.0

package/dist/connectors/printers/found.js

@@ -0,0 +1,35 @@
+/** TXT keys are case-insensitive in DNS-SD; AirPrint's are written `UUID`, `ty`, `rp`. */
+const lower = (txt) => Object.fromEntries(Object.entries(txt).map(([k, v]) => [k.toLowerCase(), v]));
+/**
+ * AirPrint printers as found devices: the identity is TXT `UUID` (the instance name when absent), the name TXT `ty` (else
+ * the instance name), the model `ty`. `txt` keeps the whole record for the connector (`rp`, `pdl`, `URF`, `product`,
+ * `adminurl`, `note`). A printer on both types is one entry, the plain `_ipp._tcp` one (`ipp` listed first), so a
+ * self-signed certificate on `_ipps._tcp` never decides; a printer on `_ipps._tcp` alone is `secure`.
+ */
+export function printersFound(ipp, ipps) {
+    const seen = new Set();
+    const out = [];
+    for (const [secure, answers] of [
+        [false, ipp],
+        [true, ipps],
+    ])
+        for (const a of answers) {
+            const txt = lower(a.txt);
+            const id = txt.uuid || a.instance;
+            const key = id.toLowerCase().replace(/[^0-9a-z]/g, "");
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({
+                connector: "printers",
+                id,
+                host: a.host,
+                port: a.port,
+                name: txt.ty || a.instance,
+                model: txt.ty,
+                secure,
+                txt,
+            });
+        }
+    return out;
+}

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

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { type Clock } from "../../clock.ts";
+import { type Finder } from "../../discover.ts";
+import type { Integration } from "../../home.ts";
+import type { Manifest } from "../../manifest.ts";
+import { type Printer, type PrintersState } from "./state.ts";
+export { type Marker, type Printer, type PrintersState, type PrinterStatus, printerText, } from "./state.ts";
+/** One printer in a home config. Everything the printer reports about itself (model, markers, state) comes live; `host` and `port` are only where it last answered. */
+export declare const configSchema: z.ZodObject<{
+    connector: z.ZodLiteral<"printers">;
+    name: z.ZodString;
+    uuid: z.ZodString;
+    host: z.ZodOptional<z.ZodString>;
+    port: z.ZodOptional<z.ZodNumber>;
+    offlineDays: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export type PrinterEntry = {
+    uuid: string;
+    name?: string;
+    host?: string;
+    port?: number;
+    room?: string;
+    offlineDays?: number;
+};
+export type PrintersConfig = {
+    /** The config's printers (a `name` is the config's and stays; without one the printer's own, from discovery, is used). Discovery adds any others it finds. */
+    printers?: PrinterEntry[];
+    /** Plain HTTP and HTTPS; the global `fetch` when left out. A printer's self-signed certificate on IPPS fails here, as it should. */
+    fetch?: typeof fetch;
+    /** mDNS discovery (`FINDERS.printers`): at start, then after a failed read on the relocator's cadence (1, 5, 15 minutes, hourly), and hourly for new printers. Without it only the configured addresses are read. */
+    find?: Finder;
+    /** Each address that answered, for an address cache. */
+    seen?: (uuid: string, address: {
+        host: string;
+        port: number;
+        name?: string;
+    }) => void;
+    clock?: Clock;
+    /** Poll interval; default 120 s. */
+    pollMs?: number;
+};
+export declare const POLL_MS = 120000;
+/**
+ * Every printer as one integration, state only: a Get-Printer-Attributes over IPP to each, every 120 s. An unreachable
+ * printer stays in the snapshot as `offline` with its last good values and `lastSeen`, and the part is never
+ * `unavailable` for that. Discovery is one shared scan, as Cast's is, not a relocator per printer: it finds printers
+ * the config does not list, and after a failed read it looks for the printer's new address (at 1, 5 and 15 minutes, then hourly).
+ */
+export declare function printers(config?: PrintersConfig): Integration<PrintersState, "printers">;
+/** Printers sorted by name. */
+export declare const printerList: (s: PrintersState) => Printer[];
+export declare const manifest: Manifest<PrintersState>;

package/dist/connectors/printers/index.js

@@ -0,0 +1,282 @@
+import { z } from "zod";
+import { asOf, realClock } from "../../clock.js";
+import { errorText } from "../../connector.js";
+import { DAY_MS, discover, HOUR, lostDetail, rescanDelay, } from "../../discover.js";
+import { poller } from "../../poll.js";
+import { getPrinterAttributes, printerUrl } from "./client.js";
+import { attributesOf } from "./codec.js";
+import { printerKey, printerText, toState, } from "./state.js";
+export { printerText, } from "./state.js";
+/** One printer in a home config. Everything the printer reports about itself (model, markers, state) comes live; `host` and `port` are only where it last answered. */
+export const configSchema = z.looseObject({
+    connector: z.literal("printers"),
+    name: z
+        .string()
+        .describe("the printer's name for display (mDNS `ty`, or its instance name); `home discover --write` fills it"),
+    uuid: z
+        .string()
+        .describe("the printer's UUID from its mDNS TXT record, the stable identity; `home discover --write` fills it"),
+    host: z
+        .string()
+        .optional()
+        .describe("the address it last answered at; discovery refreshes it"),
+    port: z
+        .number()
+        .int()
+        .min(1)
+        .max(65535)
+        .optional()
+        .describe("its IPP port (631 plain, 443 TLS); discovery fills it"),
+    offlineDays: z
+        .number()
+        .positive()
+        .optional()
+        .describe("days an unreachable printer shows as offline with its last-seen time before its entry flags it as long gone; default 14"),
+});
+export const POLL_MS = 120_000;
+/** A printer unreachable this many days gets a note in `anomaly`, unless its config says otherwise. */
+const OFFLINE_DAYS = 14;
+/**
+ * Every printer as one integration, state only: a Get-Printer-Attributes over IPP to each, every 120 s. An unreachable
+ * printer stays in the snapshot as `offline` with its last good values and `lastSeen`, and the part is never
+ * `unavailable` for that. Discovery is one shared scan, as Cast's is, not a relocator per printer: it finds printers
+ * the config does not list, and after a failed read it looks for the printer's new address (at 1, 5 and 15 minutes, then hourly).
+ */
+export function printers(config = {}) {
+    const clock = config.clock ?? realClock;
+    const fetcher = config.fetch ?? fetch;
+    const pollMs = config.pollMs ?? POLL_MS;
+    const poll = poller(clock);
+    const targets = new Map();
+    const add = (t) => {
+        const target = {
+            offlineDays: OFFLINE_DAYS,
+            since: clock.now(),
+            lost: {},
+            ipps: false,
+            ...t,
+        };
+        targets.set(t.key, target);
+        return target;
+    };
+    for (const p of config.printers ?? [])
+        add({
+            key: printerKey(p.uuid),
+            name: p.name ?? p.uuid,
+            fixedName: p.name !== undefined,
+            room: p.room,
+            host: p.host,
+            port: p.port,
+            offlineDays: p.offlineDays ?? OFFLINE_DAYS,
+        });
+    let report;
+    let polled = false;
+    let requestId = 0;
+    let lastScan = Number.NEGATIVE_INFINITY;
+    let nextScan = 0;
+    let attempt = 0;
+    let scanError;
+    /** The entry for the snapshot: the last good values, `offline` while the latest read has failed. */
+    function view(t, now) {
+        const { uuid: _, anomaly: oddReading, ...good } = t.good ?? {};
+        const offline = t.failure !== undefined;
+        const base = t.lastSeen ?? t.since;
+        const idle = clock.now() - base;
+        const long = offline && idle > t.offlineDays * DAY_MS
+            ? `no answer for ${Math.floor(idle / DAY_MS)} days`
+            : undefined;
+        return {
+            ...good,
+            uuid: t.key,
+            name: t.name,
+            model: good.model ?? t.foundModel,
+            host: t.host,
+            room: t.room,
+            ...(offline ? { state: "offline" } : {}),
+            ipps: t.ipps,
+            lastSeen: t.lastSeen === undefined
+                ? undefined
+                : new Date(t.lastSeen).toISOString(),
+            asOf: now,
+            detail: offline
+                ? lostDetail({ ...t.lost, ...(idle >= DAY_MS ? { overADay: true } : {}) }, t.failure)
+                : undefined,
+            anomaly: [oddReading, long].filter(Boolean).join("; ") || undefined,
+        };
+    }
+    function publish() {
+        const now = asOf(clock);
+        const list = [...targets.values()].map((t) => view(t, now));
+        const down = list.filter((p) => p.state === "offline");
+        const status = !polled
+            ? "connecting"
+            : list.length && down.length < list.length
+                ? "connected"
+                : "disconnected";
+        const detail = [
+            scanError && `discovery failed: ${scanError}`,
+            list.length
+                ? down.length
+                    ? `${down.map((p) => p.name).join(", ")} offline`
+                    : ""
+                : config.find
+                    ? "no printers found"
+                    : "no printers configured",
+        ]
+            .filter(Boolean)
+            .join("; ") || undefined;
+        const anomaly = list
+            .filter((p) => p.anomaly)
+            .map((p) => `${p.name}: ${p.anomaly}`)
+            .join("; ") || undefined;
+        report?.({
+            status,
+            detail,
+            anomaly,
+            state: {
+                printers: Object.fromEntries(list.map((p) => [p.uuid, p])),
+                asOf: now,
+            },
+        });
+    }
+    /** One read. A failure is data (`failure`), never thrown; an address that answers as another printer is a failure. */
+    async function read(t, signal) {
+        if (!t.host) {
+            t.failure = "no address yet";
+            return;
+        }
+        const address = { host: t.host, port: t.port, rp: t.rp, secure: t.secure };
+        t.ipps = printerUrl(address).secure;
+        try {
+            const reading = toState(attributesOf(await getPrinterAttributes(fetcher, address, {
+                signal,
+                requestId: ++requestId,
+            })));
+            if (reading.uuid &&
+                /^[0-9a-f]{32}$/.test(t.key) &&
+                printerKey(reading.uuid) !== t.key)
+                throw new Error("the address answers as another printer");
+            t.good = reading;
+            t.lastSeen = clock.now();
+            t.failure = undefined;
+            t.lost = {};
+            config.seen?.(t.key, {
+                host: t.host,
+                port: t.port ?? (t.ipps ? 443 : 631),
+                name: t.fixedName ? undefined : t.name,
+            });
+        }
+        catch (error) {
+            if (!signal.aborted)
+                t.failure = errorText(error);
+        }
+    }
+    /** One discovery. Printers it finds get their address and TXT; ones the config lacks join the snapshot. Returns those that need reading again. */
+    async function scan(signal, failed) {
+        lastScan = clock.now();
+        let all;
+        try {
+            const wanted = failed.map((t) => t.key);
+            all = await discover(config.find, {
+                clock,
+                signal,
+                passes: failed.length ? undefined : 1,
+                done: wanted.length
+                    ? (found) => wanted.every((k) => found.some((f) => printerKey(f.id) === k))
+                    : undefined,
+            });
+            scanError = undefined;
+        }
+        catch (error) {
+            scanError = errorText(error);
+            for (const t of failed)
+                t.lost = { discoveryFailed: scanError };
+            return [];
+        }
+        const changed = [];
+        const mine = all.filter((f) => f.connector === "printers");
+        for (const f of mine) {
+            const key = printerKey(f.id);
+            const known = targets.get(key);
+            const t = known ?? add({ key, name: f.name ?? f.id, fixedName: false });
+            const moved = t.host !== f.host || (f.port !== undefined && t.port !== f.port);
+            // A printer known by host alone was read at the default path over http; the TXT may say otherwise.
+            const reroute = (f.txt?.rp !== undefined && f.txt.rp !== t.rp) ||
+                (f.secure !== undefined && f.secure !== t.secure);
+            if (!t.fixedName && f.name)
+                t.name = f.name;
+            Object.assign(t, {
+                host: f.host,
+                port: f.port ?? t.port,
+                rp: f.txt?.rp ?? t.rp,
+                secure: f.secure ?? t.secure,
+                foundModel: f.model ?? t.foundModel,
+            });
+            if (!known || moved || reroute)
+                changed.push(t);
+            else if (failed.includes(t))
+                t.lost = { seenHere: true };
+        }
+        for (const t of failed)
+            if (!mine.some((f) => printerKey(f.id) === t.key))
+                t.lost = { seenHere: false };
+        return changed;
+    }
+    async function pollOnce(signal) {
+        const first = !polled;
+        await Promise.all([...targets.values()].map((t) => read(t, signal)));
+        if (signal.aborted || !config.find)
+            return;
+        const now = clock.now();
+        const failed = () => [...targets.values()].filter((t) => t.failure !== undefined);
+        if (!(first ||
+            (failed().length && now >= nextScan) ||
+            now >= lastScan + HOUR))
+            return;
+        const changed = await scan(signal, failed());
+        await Promise.all(changed.map((t) => read(t, signal)));
+        if (failed().length)
+            nextScan = now + rescanDelay(attempt++);
+        else
+            ((attempt = 0), (nextScan = 0));
+    }
+    return {
+        name: "printers",
+        /** Read now; a printer that is down is looked for again at once. */
+        refresh() {
+            attempt = 0;
+            nextScan = 0;
+            poll.nudge();
+        },
+        async run(signal, update) {
+            report = update;
+            while (!signal.aborted) {
+                await pollOnce(signal);
+                if (signal.aborted)
+                    return;
+                polled = true;
+                publish();
+                await poll.wait(pollMs, signal);
+            }
+        },
+    };
+}
+/** Printers sorted by name. */
+export const printerList = (s) => Object.values(s.printers).sort((a, b) => a.name.localeCompare(b.name));
+export const manifest = {
+    name: "printers",
+    title: "Printers",
+    iotClass: "local_polling",
+    pollSeconds: POLL_MS / 1000,
+    access: "local IPP over HTTP, no key; found by mDNS (AirPrint)",
+    env: [],
+    lines({ state }) {
+        if (!state)
+            return [];
+        const list = printerList(state);
+        return [
+            `${list.length} printer${list.length === 1 ? "" : "s"}`,
+            ...list.map(printerText),
+        ];
+    },
+};

package/dist/connectors/printers/state.d.ts

@@ -0,0 +1,60 @@
+import { idKey } from "../../discover.ts";
+import type { IppValue } from "./codec.ts";
+/** One consumable as the printer lists it: ink or toner, a drum, a fuser, waste. The level is the printer's own number, unrounded. */
+export type Marker = {
+    name?: string;
+    level?: number;
+    type?: string;
+    color?: string;
+};
+export type PrinterStatus = "idle" | "printing" | "stopped" | "offline";
+/**
+ * One printer. Every field the printer reports is optional; an odd reading passes through and is named in `anomaly`.
+ * `uuid` is the key: the mDNS `UUID` (or `printer-uuid`) lowercase without dashes. An unreachable printer keeps its last good
+ * values, with `state: "offline"` and `lastSeen`; `asOf` is when this entry was last checked, `lastSeen` when it last answered.
+ */
+export type Printer = {
+    uuid: string;
+    name: string;
+    model?: string;
+    host?: string;
+    room?: string;
+    state?: PrinterStatus;
+    stateCode?: number;
+    reasons?: string[];
+    message?: string;
+    markers?: Marker[];
+    media?: string[];
+    queuedJobs?: number;
+    acceptingJobs?: boolean;
+    formats?: string[];
+    ippVersions?: string[];
+    alerts?: string[];
+    ipps: boolean;
+    lastSeen?: string;
+    asOf: string;
+    detail?: string;
+    anomaly?: string;
+};
+export type PrintersState = {
+    printers: Record<string, Printer>;
+    asOf: string;
+};
+/** An id as the snapshot keys it: a UUID in any form (`urn:uuid:…`, dashed, upper case) is its 32 hex digits; an instance name keeps its letters and digits. */
+export declare const printerKey: typeof idKey;
+/** The fields of `Printer` that come from Get-Printer-Attributes. */
+export type Reading = Partial<Pick<Printer, "model" | "state" | "stateCode" | "reasons" | "message" | "markers" | "media" | "queuedJobs" | "acceptingJobs" | "formats" | "ippVersions" | "alerts" | "anomaly">> & {
+    uuid?: string;
+};
+/**
+ * The printer's attributes (name → values, from `attributesOf`) as a `Reading`. Nothing is clamped or corrected: a state
+ * outside 3 to 5 leaves `state` out and keeps the code; a marker level outside 0 to 100 (PWG 5100.13 gives the negative ones
+ * special meanings) stays as sent; both, and lists that disagree in length, are named in `anomaly`.
+ */
+export declare function toState(attrs: Record<string, IppValue[]>): Reading;
+/** A PWG media keyword for reading: `iso_a4_210x297mm` is "A4", `na_letter_8.5x11in` "Letter". A keyword in another shape stays as it is. */
+export declare function mediaName(keyword: string): string;
+/** "5 min ago", "2 h ago", "3 days ago" from two instants; whole units, down. */
+export declare function ago(fromMs: number, toMs: number): string;
+/** One printer in a few words: "Office: idle · Black Toner 40% · A4 ready", "Office: offline, last seen 2 h ago". */
+export declare function printerText(p: Printer): string;

package/dist/connectors/printers/state.js

@@ -0,0 +1,99 @@
+import { idKey } from "../../discover.js";
+/** An id as the snapshot keys it: a UUID in any form (`urn:uuid:…`, dashed, upper case) is its 32 hex digits; an instance name keeps its letters and digits. */
+export const printerKey = idKey;
+const strings = (v) => v?.flatMap((x) => typeof x === "string"
+    ? [x]
+    : x instanceof Uint8Array
+        ? [new TextDecoder().decode(x)]
+        : []);
+const numbers = (v) => v?.flatMap((x) => (typeof x === "number" ? [x] : []));
+const STATES = {
+    3: "idle",
+    4: "printing",
+    5: "stopped",
+};
+/**
+ * The printer's attributes (name → values, from `attributesOf`) as a `Reading`. Nothing is clamped or corrected: a state
+ * outside 3 to 5 leaves `state` out and keeps the code; a marker level outside 0 to 100 (PWG 5100.13 gives the negative ones
+ * special meanings) stays as sent; both, and lists that disagree in length, are named in `anomaly`.
+ */
+export function toState(attrs) {
+    const odd = [];
+    const [stateCode] = numbers(attrs["printer-state"]) ?? [];
+    const state = stateCode === undefined ? undefined : STATES[stateCode];
+    if (stateCode !== undefined && !state)
+        odd.push(`printer-state ${stateCode}, not 3 (idle), 4 (processing) or 5 (stopped)`);
+    const names = strings(attrs["marker-names"]);
+    const levels = numbers(attrs["marker-levels"]);
+    const types = strings(attrs["marker-types"]);
+    const colors = strings(attrs["marker-colors"]);
+    const count = Math.max(names?.length ?? 0, levels?.length ?? 0, types?.length ?? 0, colors?.length ?? 0);
+    const lengths = [names, levels, types, colors].flatMap((x) => x ? [x.length] : []);
+    if (new Set(lengths).size > 1)
+        odd.push(`marker lists of different lengths (${lengths.join(", ")})`);
+    const markers = Array.from({ length: count }, (_, i) => ({
+        name: names?.[i],
+        level: levels?.[i],
+        type: types?.[i],
+        color: colors?.[i],
+    }));
+    for (const m of markers)
+        if (m.level !== undefined && (m.level < 0 || m.level > 100))
+            odd.push(`marker ${m.name ?? "?"} level ${m.level}, outside 0 to 100`);
+    const accepting = attrs["printer-is-accepting-jobs"]?.[0];
+    const uuid = strings(attrs["printer-uuid"])?.[0];
+    return {
+        uuid,
+        model: strings(attrs["printer-make-and-model"])?.[0],
+        state,
+        stateCode,
+        reasons: strings(attrs["printer-state-reasons"]),
+        message: strings(attrs["printer-state-message"])?.[0],
+        markers: count ? markers : undefined,
+        media: strings(attrs["media-ready"]),
+        queuedJobs: numbers(attrs["queued-job-count"])?.[0],
+        acceptingJobs: typeof accepting === "boolean" ? accepting : undefined,
+        formats: strings(attrs["document-format-supported"]),
+        ippVersions: strings(attrs["ipp-versions-supported"]),
+        alerts: strings(attrs["printer-alert"]),
+        anomaly: odd.length ? odd.join("; ") : undefined,
+    };
+}
+/** A PWG media keyword for reading: `iso_a4_210x297mm` is "A4", `na_letter_8.5x11in` "Letter". A keyword in another shape stays as it is. */
+export function mediaName(keyword) {
+    const parts = keyword.split("_");
+    if (parts.length < 3)
+        return keyword;
+    const name = parts[1];
+    return /^[a-z]\d+$/.test(name)
+        ? name.toUpperCase()
+        : name.charAt(0).toUpperCase() + name.slice(1);
+}
+/** "5 min ago", "2 h ago", "3 days ago" from two instants; whole units, down. */
+export function ago(fromMs, toMs) {
+    const min = Math.max(0, Math.floor((toMs - fromMs) / 60_000));
+    if (min < 60)
+        return `${min} min ago`;
+    const h = Math.floor(min / 60);
+    return h < 48 ? `${h} h ago` : `${Math.floor(h / 24)} days ago`;
+}
+/** One printer in a few words: "Office: idle · Black Toner 40% · A4 ready", "Office: offline, last seen 2 h ago". */
+export function printerText(p) {
+    if (p.state === "offline") {
+        const seen = p.lastSeen === undefined
+            ? "never seen"
+            : `last seen ${ago(Date.parse(p.lastSeen), Date.parse(p.asOf))}`;
+        return `${p.name}: offline, ${seen}`;
+    }
+    const attention = (p.reasons ?? []).filter((r) => /-(error|warning)$/.test(r));
+    const media = [...new Set((p.media ?? []).map(mediaName))];
+    const parts = [
+        p.state ?? (p.stateCode === undefined ? "" : `state ${p.stateCode}`),
+        ...(p.markers ?? []).map((m) => `${m.name ?? "?"} ${m.level ?? "?"}%`),
+        media.length ? `${media.join(", ")} ready` : "",
+        p.queuedJobs ? `${p.queuedJobs} queued` : "",
+        p.acceptingJobs === false ? "not accepting jobs" : "",
+        ...attention,
+    ];
+    return `${p.name}: ${parts.filter(Boolean).join(" · ")}`;
+}

package/dist/connectors/spotify/changes.d.ts

@@ -0,0 +1,32 @@
+import type { Part } from "../../home.ts";
+import type { SpotifyState, Stall, Track } from "./client.ts";
+/** A stall in a few words: `playback stalled at 1:39 (Soloist issue #5); tried a seek`. */
+export declare function stallText(s: Stall | undefined): string | undefined;
+/** The speaker in one word, to switch on. `offline`: not reached (or no part); `waiting`: running, nobody has picked it. A status Soloist sends beyond its four passes through. */
+export type SpeakerState = "offline" | "connecting" | "waiting" | "idle" | "playing" | "paused" | "buffering" | (string & {});
+export declare function speakerState(part: Part<SpotifyState> | undefined): SpeakerState;
+/**
+ * A change worth telling someone about, from two reports of the speaker. `own`, on playback events only: it happened while
+ * this library's `duck`, `interrupt` or stall repair ran (its own writes, or a person's change in that time), so a consumer
+ * needn't react to it. `offline`, `online`, `waiting`, `picked`, `stalled` and `recovered` are never `own`.
+ */
+export type SpotifyEvent = {
+    own?: true;
+} & ({
+    type: "offline" | "online" | "waiting" | "picked" | "started" | "resumed" | "paused" | "stopped" | "recovered";
+} | {
+    type: "stalled";
+    stall: Stall;
+} | {
+    type: "track";
+    track: Track;
+});
+/**
+ * The events between two reports, for `onChange`'s `before` and `after`: `offline` and `online`; `waiting` (signed out) and
+ * `picked` (someone picked the speaker); `started` (from idle), `resumed` (from paused), `paused`, `stopped` (to idle), then
+ * `track` for a new track, so "started" and the track come as a pair, then `stalled` and `recovered` (Soloist issue #5). Buffering counts as playing. No `before`, or one
+ * with no state (createHome's placeholder before the first report, as at a restart): nothing, since nothing was seen to change. No volume or queue events: read the state.
+ */
+export declare function spotifyChanges(before: Part<SpotifyState> | undefined, after: Part<SpotifyState> | undefined): SpotifyEvent[];
+/** The speaker in a few words: `Kitchen speaker: playing "Song" by Band · 35%`, or `…: waiting for someone to pick it`. */
+export declare function spotifyText(s: SpotifyState): string;

package/dist/connectors/spotify/changes.js

@@ -0,0 +1,84 @@
+// What a consumer reads off the speaker's parts: one word, the events between two reports, a line of text. Pure: no socket, no clock.
+/** A stall in a few words: `playback stalled at 1:39 (Soloist issue #5); tried a seek`. */
+export function stallText(s) {
+    if (!s)
+        return undefined;
+    const at = `${Math.floor(s.ms / 60_000)}:${String(Math.floor((s.ms % 60_000) / 1000)).padStart(2, "0")}`;
+    const what = s.how === "overrun"
+        ? `playback stuck past the end of the track (Soloist issue #5)`
+        : `playback stalled at ${at} (Soloist issue #5)`;
+    return s.tried ? `${what}; tried ${s.tried}` : what;
+}
+export function speakerState(part) {
+    if (!part || part.status === "disconnected" || part.status === "unavailable")
+        return "offline";
+    if (part.status === "connecting")
+        return "connecting";
+    if (part.state?.loggedIn === false)
+        return "waiting";
+    return part.state?.status ?? "idle"; // signed in, nothing reported yet: nothing is playing
+}
+const PLAYING = new Set(["playing", "buffering"]);
+/**
+ * The events between two reports, for `onChange`'s `before` and `after`: `offline` and `online`; `waiting` (signed out) and
+ * `picked` (someone picked the speaker); `started` (from idle), `resumed` (from paused), `paused`, `stopped` (to idle), then
+ * `track` for a new track, so "started" and the track come as a pair, then `stalled` and `recovered` (Soloist issue #5). Buffering counts as playing. No `before`, or one
+ * with no state (createHome's placeholder before the first report, as at a restart): nothing, since nothing was seen to change. No volume or queue events: read the state.
+ */
+export function spotifyChanges(before, after) {
+    if (!before?.state)
+        return []; // createHome's first `before` is a bare connecting part: a boot is no change
+    const own = before.state?.aside || after?.state?.aside ? { own: true } : {}; // playback events only: a drop or a sign-out is never the library's
+    const down = (p) => ["offline", "connecting"].includes(speakerState(p)); // a reconnect passes through connecting
+    const was = down(before);
+    if (speakerState(after) === "offline")
+        return was ? [] : [{ type: "offline" }];
+    if (after?.status === "connecting")
+        return [];
+    const events = [];
+    const add = (e) => events.push({ ...e, ...own });
+    if (was)
+        events.push({ type: "online" });
+    const b = before.state;
+    const a = after?.state;
+    if (b?.loggedIn !== false && a?.loggedIn === false)
+        events.push({ type: "waiting" });
+    if (b?.loggedIn === false && a?.loggedIn === true)
+        events.push({ type: "picked" });
+    const from = b?.status;
+    const to = a?.status;
+    const playingNow = to !== undefined && PLAYING.has(to);
+    const playingThen = from !== undefined && PLAYING.has(from);
+    if (playingNow && !playingThen)
+        add({ type: from === "paused" ? "resumed" : "started" });
+    if (to === "paused" && from !== "paused")
+        add({ type: "paused" });
+    if (to === "idle" && from !== undefined && from !== "idle")
+        add({ type: "stopped" });
+    if (a?.track && a.track.uri !== b?.track?.uri)
+        add({ type: "track", track: a.track });
+    if (a?.stalled && !b?.stalled)
+        events.push({ type: "stalled", stall: a.stalled });
+    if (b?.stalled &&
+        !a?.stalled &&
+        a?.status === "playing" &&
+        a.track?.uri === b.stalled.track)
+        events.push({ type: "recovered" });
+    return events;
+}
+/** The speaker in a few words: `Kitchen speaker: playing "Song" by Band · 35%`, or `…: waiting for someone to pick it`. */
+export function spotifyText(s) {
+    const who = s.deviceName ?? "Soloist";
+    if (s.loggedIn === false)
+        return `${who}: waiting for someone to pick it`;
+    const t = s.track;
+    const what = t
+        ? `${t.name ? ` "${t.name}"` : ` ${t.uri}`}${t.artists.length ? ` by ${t.artists.join(", ")}` : ""}`
+        : "";
+    const parts = [
+        `${s.status ?? "status unknown"}${what}`,
+        s.volume === undefined ? "" : `${s.volume}%`,
+        s.shuffle ? "shuffle" : "",
+    ];
+    return `${who}: ${parts.filter(Boolean).join(" · ")}`;
+}