@khalido/home 0.2.0 → 0.2.1

package/src/connectors/printers/codec.ts

@@ -29,8 +29,14 @@ export const TAG = {
   mimeMediaType: 0x49,
 } as const;
 
-/** The operation ids this package sends. Identify-Printer (0x003C) and Print-Job (0x0002) are the writes that come later. */
-export const OPERATION = { getPrinterAttributes: 0x000b } as const;
+/** The operation ids this package sends (RFC 8011; Identify-Printer from PWG 5100.13). */
+export const OPERATION = {
+  printJob: 0x0002,
+  validateJob: 0x0004,
+  cancelJob: 0x0008,
+  getPrinterAttributes: 0x000b,
+  identifyPrinter: 0x003c,
+} as const;
 
 const STRING_TAGS: ReadonlySet<number> = new Set([
   TAG.textWithoutLanguage,
@@ -138,19 +144,30 @@ export function encodeMessage(m: IppMessage): Uint8Array<ArrayBuffer> {
       });
   }
   out.push(TAG.end);
-  return Uint8Array.from([...out, ...(m.data ?? [])]);
+  const bytes = new Uint8Array(out.length + (m.data?.length ?? 0));
+  bytes.set(out);
+  if (m.data) bytes.set(m.data, out.length);
+  return bytes;
 }
 
-/** The Get-Printer-Attributes request: IPP 2.0, utf-8, English, the printer's `ipp://` URI, and the attributes wanted. */
-export function getPrinterAttributesRequest(
+/**
+ * A request to one printer: IPP 2.0, utf-8, English, the printer's `ipp://` URI, then `attributes` in the operation
+ * group, `job` (when given) in a job group, and `data` (a document) after the end tag.
+ */
+export function operationRequest(
+  code: number,
   printerUri: string,
-  requested: string[],
-  requestId = 1,
+  options: {
+    attributes?: IppAttribute[];
+    job?: IppAttribute[];
+    data?: Uint8Array;
+    requestId?: number;
+  } = {},
 ): Uint8Array<ArrayBuffer> {
   return encodeMessage({
     version: [2, 0],
-    code: OPERATION.getPrinterAttributes,
-    requestId,
+    code,
+    requestId: options.requestId ?? 1,
     groups: [
       {
         tag: TAG.operation,
@@ -162,13 +179,30 @@ export function getPrinterAttributesRequest(
             values: ["en"],
           },
           { name: "printer-uri", tag: TAG.uri, values: [printerUri] },
-          { name: "requested-attributes", tag: TAG.keyword, values: requested },
+          ...(options.attributes ?? []),
         ],
       },
+      ...(options.job?.length
+        ? [{ tag: TAG.job, attributes: options.job }]
+        : []),
     ],
+    data: options.data,
   });
 }
 
+/** The Get-Printer-Attributes request: the attributes wanted. */
+export const getPrinterAttributesRequest = (
+  printerUri: string,
+  requested: string[],
+  requestId = 1,
+) =>
+  operationRequest(OPERATION.getPrinterAttributes, printerUri, {
+    requestId,
+    attributes: [
+      { name: "requested-attributes", tag: TAG.keyword, values: requested },
+    ],
+  });
+
 const fail = (why: string): never => {
   throw new Error(`ipp: ${why}`);
 };

package/src/connectors/printers/index.ts

@@ -39,6 +39,21 @@ export {
   type PrinterStatus,
   printerText,
 } from "./state.ts";
+export {
+  cancelJob,
+  identifyPrinter,
+  type PrintedJob,
+  type PrinterAddress,
+  type PrintJob,
+  printJob,
+  validateJob,
+} from "./client.ts";
+export {
+  type GreyPage,
+  mediaPixels,
+  pwgRaster,
+  type RasterMedia,
+} from "./raster.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 const configSchema = z.looseObject({
@@ -184,6 +199,8 @@ export function printers(
       name: t.name,
       model: good.model ?? t.foundModel,
       host: t.host,
+      port: t.port,
+      rp: t.rp,
       room: t.room,
       ...(offline ? { state: "offline" as const } : {}),
       ipps: t.ipps,

package/src/connectors/printers/raster.ts

@@ -0,0 +1,215 @@
+// PWG Raster (PWG 5102.4), 8-bit grey only: what an AirPrint printer that lists `image/pwg-raster` takes when it lists no
+// PDF. A file is "RaS2", then per page a 1796-byte big-endian header and the page's pixels, compressed line by line:
+// a line-repeat byte (the line appears n + 1 times), then runs: 0 to 127 is one pixel repeated n + 1 times, 129 to 255 is
+// 257 − n pixels as they are. Checked against a page macOS's own filters made for a Brother (test/fixtures/printers).
+
+/** One page: `pixels` is `width × height` bytes, row by row from the top, 0 black to 255 white. */
+export type GreyPage = {
+  width: number;
+  height: number;
+  pixels: Uint8Array;
+};
+
+/** What every page is printed as: the printer's resolution and the PWG media name and size it lists. */
+export type RasterMedia = {
+  /** PWG self-describing name, as the printer lists it in `media-supported`: `iso_a4_210x297mm`. */
+  name: string;
+  /** dots per inch, one of the printer's `pwg-raster-document-resolution-supported`. */
+  dpi: number;
+};
+
+const HEADER = 1796;
+const SGRAY = 18; // cupsColorSpace for sgray (PWG 5102.4 table 9)
+const WHITE = 0xffffff; // AlternatePrimary: the white point, as PWG 5102.4 recommends
+
+/** A PWG media name's size in inches: `iso_a4_210x297mm` is 8.27 × 11.69. */
+function mediaInches(name: string): { width: number; height: number } {
+  const m = /_(\d+(?:\.\d+)?)x(\d+(?:\.\d+)?)(mm|in)$/.exec(name);
+  if (!m) throw new RangeError(`not a PWG media size: ${name}`);
+  const per = m[3] === "mm" ? 1 / 25.4 : 1;
+  return { width: Number(m[1]) * per, height: Number(m[2]) * per };
+}
+
+/** The pixels a page of this media is at its resolution, rounded down as macOS's filters do: A4 at 600 dpi is 4960 × 7015. */
+export function mediaPixels(media: RasterMedia): {
+  width: number;
+  height: number;
+} {
+  const i = mediaInches(media.name);
+  return {
+    width: Math.floor(i.width * media.dpi),
+    height: Math.floor(i.height * media.dpi),
+  };
+}
+
+function header(page: GreyPage, media: RasterMedia, total: number) {
+  const h = new Uint8Array(HEADER);
+  const v = new DataView(h.buffer);
+  const u32 = (offset: number, n: number) => v.setUint32(offset, n);
+  const str = (offset: number, s: string) =>
+    h.set(new TextEncoder().encode(s).subarray(0, 63), offset);
+  const pt = mediaPixels({ name: media.name, dpi: 72 }); // PageSize is in points
+  str(0, "PwgRaster"); // MediaClass
+  u32(276, media.dpi); // HWResolution
+  u32(280, media.dpi);
+  u32(340, 1); // NumCopies: copies are the job's, not the page's
+  u32(352, pt.width); // PageSize, points
+  u32(356, pt.height);
+  u32(372, page.width); // Width, Height in pixels
+  u32(376, page.height);
+  u32(384, 8); // BitsPerColor
+  u32(388, 8); // BitsPerPixel
+  u32(392, page.width); // BytesPerLine
+  u32(400, SGRAY); // ColorSpace; ColorOrder (396) 0 is chunky
+  u32(420, 1); // NumColors
+  u32(452, total); // TotalPageCount
+  u32(456, 1); // CrossFeedTransform
+  u32(460, 1); // FeedTransform
+  u32(480, WHITE); // AlternatePrimary
+  str(1732, media.name); // PageSizeName
+  return h;
+}
+
+/** One line's runs, appended to `out`. */
+function packLine(line: Uint8Array, out: number[]) {
+  let i = 0;
+  while (i < line.length) {
+    let run = 1;
+    while (run < 128 && i + run < line.length && line[i + run] === line[i])
+      run++;
+    if (run > 1 || i + 1 === line.length) {
+      out.push(run - 1, line[i]!);
+      i += run;
+      continue;
+    }
+    // Literal: up to 128 pixels, stopping before two equal pixels that would pack better as a repeat.
+    let n = 1;
+    while (
+      n < 128 &&
+      i + n < line.length &&
+      !(i + n + 1 < line.length && line[i + n] === line[i + n + 1])
+    )
+      n++;
+    if (n === 1) {
+      out.push(0, line[i]!); // a lone pixel is a repeat of one: 257 − 256 can't be written
+      i += 1;
+      continue;
+    }
+    out.push(257 - n);
+    for (let k = 0; k < n; k++) out.push(line[i + k]!);
+    i += n;
+  }
+}
+
+/**
+ * Pages as one PWG Raster document, `image/pwg-raster`. Every page must be `width × height` bytes. Pages may come one at
+ * a time (a generator), so only the packed document and the current page are held; then `total` is the page count.
+ */
+export function pwgRaster(
+  pages: Iterable<GreyPage>,
+  media: RasterMedia,
+  total = Array.isArray(pages) ? pages.length : 0,
+): Uint8Array<ArrayBuffer> {
+  const chunks: Uint8Array[] = [new TextEncoder().encode("RaS2")];
+  for (const page of pages) {
+    if (page.pixels.length !== page.width * page.height)
+      throw new RangeError(
+        `a ${page.width} × ${page.height} page needs ${page.width * page.height} bytes, got ${page.pixels.length}`,
+      );
+    chunks.push(header(page, media, total));
+    let y = 0;
+    while (y < page.height) {
+      const line = page.pixels.subarray(y * page.width, (y + 1) * page.width);
+      let repeat = 0;
+      while (
+        repeat < 255 &&
+        y + repeat + 1 < page.height &&
+        equal(
+          line,
+          page.pixels.subarray(
+            (y + repeat + 1) * page.width,
+            (y + repeat + 2) * page.width,
+          ),
+        )
+      )
+        repeat++;
+      const out = [repeat]; // one line at a time: a page as a number[] would be hundreds of MB
+      packLine(line, out);
+      chunks.push(Uint8Array.from(out));
+      y += repeat + 1;
+    }
+  }
+  const size = chunks.reduce((n, c) => n + c.length, 0);
+  const file = new Uint8Array(size);
+  let at = 0;
+  for (const c of chunks) (file.set(c, at), (at += c.length));
+  return file;
+}
+
+function equal(a: Uint8Array, b: Uint8Array) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/** A PWG Raster document back as pages and their headers' key fields; for tests and for checking a file before it prints. */
+export function readPwgRaster(file: Uint8Array): (GreyPage & {
+  dpi: number;
+  pageSizeName: string;
+  colorSpace: number;
+  bitsPerPixel: number;
+})[] {
+  const text = new TextDecoder();
+  if (text.decode(file.subarray(0, 4)) !== "RaS2")
+    throw new Error("pwg raster: no RaS2 sync word");
+  const pages = [];
+  let at = 4;
+  while (at < file.length) {
+    const v = new DataView(file.buffer, file.byteOffset + at, HEADER);
+    const width = v.getUint32(372);
+    const height = v.getUint32(376);
+    const bitsPerPixel = v.getUint32(388);
+    const bytes = bitsPerPixel / 8;
+    const name = file.subarray(at + 1732, at + 1796);
+    const pageSizeName = text.decode(name.subarray(0, name.indexOf(0)));
+    const page = {
+      width,
+      height,
+      dpi: v.getUint32(276),
+      pageSizeName,
+      colorSpace: v.getUint32(400),
+      bitsPerPixel,
+      pixels: new Uint8Array(width * height * bytes),
+    };
+    at += HEADER;
+    const lineBytes = width * bytes;
+    let y = 0;
+    while (y < height) {
+      const repeat = file[at++]! + 1;
+      const line = new Uint8Array(lineBytes);
+      let x = 0;
+      while (x < lineBytes) {
+        const c = file[at++]!;
+        if (c === 128) {
+          line.fill(255, x); // the rest of the line is white
+          break;
+        }
+        if (c < 128) {
+          const px = file.subarray(at, at + bytes);
+          for (let k = 0; k <= c; k++) line.set(px, x + k * bytes);
+          at += bytes;
+          x += (c + 1) * bytes;
+        } else {
+          const n = (257 - c) * bytes;
+          line.set(file.subarray(at, at + n), x);
+          at += n;
+          x += n;
+        }
+      }
+      for (let k = 0; k < repeat && y < height; k++, y++)
+        page.pixels.set(line, y * lineBytes);
+    }
+    pages.push(page);
+  }
+  return pages;
+}

package/src/connectors/printers/state.ts

@@ -21,6 +21,8 @@ export type Printer = {
   name: string;
   model?: string;
   host?: string;
+  port?: number; // where it last answered, with `rp`: what a write needs to reach it
+  rp?: string; // the IPP path from discovery's TXT; absent is `ipp/print`
   room?: string;
   state?: PrinterStatus; // absent when the printer sent a code outside 3 to 5; `stateCode` has it
   stateCode?: number;

package/src/connectors/spotify/README.md

@@ -58,6 +58,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 +72,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

@@ -390,6 +390,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 +421,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();
         }

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",