@khalido/home 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to home.ts (`@khalido/home` on npm), in [Keep a Changelog](h
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-11-12
+
+### Added
+
+- **printers:** printing. `identifyPrinter`, `validateJob`, `printJob` and `cancelJob` over IPP, and `pwgRaster` for a printer that takes no PDF (8-bit grey PWG Raster). The snapshot's `Printer` gains `port` and `rp`, so a write can reach it. `home printers print <file.pdf> [printer]`, `identify` and `cancel`; `print --dry-run` has the printer validate the job and sends no job; a printer with no PDF needs poppler's `pdftoppm`. Live on a Brother HL-L2350DW.
+
+### Fixed
+
+- **cli, enphase:** a stale `IQ_GATEWAY_HOST` no longer leaves `home enphase` refused for good: with the gateway's serial from the address cache, a failed read is followed by mDNS discovery, and the line says where the gateway moved. Without `IQ_GATEWAY_HOST` the address comes from the cache, then from mDNS.
+- **amber, enphase, up:** a 403 is a rejected key (`unavailable`, `reason: "auth"`), as a 401 already was and as Hue and Google weather already read both. It was `disconnected` and retried forever. One check, `isRejectedKey` in `src/connector.ts`, now serves every connector and the CLI.
+- **spotify:** after the first-play lowering ([spotify/soloist#23](https://github.com/spotify/soloist/issues/23)), `anomaly` no longer says only "lowered it" when the volume is back above `maxVolume`: it adds `it is back at <n>`. Soloist puts its own level back about 90 ms after `playing` when it goes active (live, 2026-11-11), and the cap leaves that level alone.
+
 ## [0.2.0] - 2026-11-12
 
 ### Breaking
@@ -34,7 +46,7 @@ All notable changes to home.ts (`@khalido/home` on npm), in [Keep a Changelog](h
 - **cast: `castFreeSpeakers(state)`**: every free speaker and display in one call, a whole group where all of it is free, never a TV; `free` goes straight to `announceAll`.
 - **cast: `castFree(state, targets, { forms })`**: with `forms: ["speaker", "display"]` a TV is left out (`why: "form"`, only when `forms` is given), and a group holding one becomes its other free members.
 - **`home.add(integration)` and `home.remove(name)`** on the home `createHome` returns: add one while the rest keep running (a bridge paired just now), replace one by name (the old run has ended before the new one starts; how an `unavailable` part comes back after a re-key), or stop one and drop its part. `start` now also waits for those added.
-- **spotify: `playingElsewhere(state)`**, and **`spotifyElsewhere(snapshot)`** from `@khalido/home`: the names of the Cast devices and groups playing that track in Spotify, matched by the track's name since Soloist doesn't say where the music is. Empty for a phone or a laptop. `homeDevices` and `home devices` put it in the speaker's line (`silent · "Song" is playing on Front room speaker`), and `spotifyText(state, on)` takes it. Tested on built snapshots only.
+- **spotify: `playingElsewhere(state)`**, and **`spotifyElsewhere(snapshot)`** from `@khalido/home`: the names of the Cast devices and groups playing that track in Spotify, matched by the track's name since Soloist doesn't say where the music is. Empty for a phone or a laptop. `homeDevices` and `home devices` put it in the speaker's line (`silent · "Song" is playing on Den speaker`), and `spotifyText(state, on)` takes it. Tested on built snapshots only.
 - **hue: lights, rooms and scenes by name.** `client.light(name, change)`, `client.room(name, change)` and `client.scene(name, room?)`, each resolving `{ state, confirmed }` (`HueApplied`). `change` (`LightChange`) is `{ on?, brightness?, color?, kelvin?, transitionMs? }`: a colour as hex or `{ r, g, b }`, sent as `xy` inside the light's own gamut; a white temperature in kelvin, checked against the light's range. An unknown name or a value the light can't take throws `HueError` with `code: "invalid"` before anything is sent, and a light the bridge has lost throws with `code: "offline"`.
 - **hue: colour in the state.** Each light's `kelvin` and `kelvinRange`, and on a colour light its `xy`, `hex` and `gamut`. `colorToXy`, `xyToHex`, `kelvinToMirek`, `mirekToKelvin` and `hueText` are exported.
 - **`home light <name> …`**, and `home room` and `home scene` now take a brightness, a temperature (`2700k`) and a colour (`ff8800`) together, name a scene's room (`in <room>`), and print what the bridge then reported.
@@ -139,7 +151,9 @@ First release. Nine connectors: Hue, Daikin, Enphase, Google Cast, AirPrint prin
 - **Agent skills** in `skills/`: `use-home` (reading safely, connecting, the rules for writes) and `draw-home` (an SVG plan of a home and its rooms). `llms.txt` points agents at the docs.
 - **Node.** Hue and Enphase take the fetches in `@khalido/home/node`. The library runs on Bun 1.4+ and Node 24+; the `home` command needs Bun.
 
-[Unreleased]: https://github.com/khalido/home.ts/compare/v0.1.3...HEAD
+[Unreleased]: https://github.com/khalido/home.ts/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/khalido/home.ts/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/khalido/home.ts/compare/v0.1.3...v0.2.0
 [0.1.3]: https://github.com/khalido/home.ts/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/khalido/home.ts/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/khalido/home.ts/compare/v0.1.0...v0.1.1

package/dist/connector.d.ts

@@ -23,6 +23,8 @@ export declare class ConnectorError extends Error {
         cause?: unknown;
     });
 }
+/** A 401 or 403 from a device or service: the key or token is wrong or revoked. Every connector reads it as `reason: "auth"`. */
+export declare const isRejectedKey: (error: unknown) => boolean;
 /** `fetch` that gives up after `timeoutMs`, or as soon as `signal` (a run's) aborts. Returns the response whatever its status. */
 export declare function fetchTimeout(fetcher: typeof fetch, url: string | URL, init?: Omit<RequestInit, "signal">, options?: {
     timeoutMs?: number;

package/dist/connector.js

@@ -24,6 +24,9 @@ export class ConnectorError extends Error {
         this.code = options.code;
     }
 }
+/** A 401 or 403 from a device or service: the key or token is wrong or revoked. Every connector reads it as `reason: "auth"`. */
+export const isRejectedKey = (error) => error instanceof ConnectorError &&
+    (error.status === 401 || error.status === 403);
 /** `fetch` that gives up after `timeoutMs`, or as soon as `signal` (a run's) aborts. Returns the response whatever its status. */
 export function fetchTimeout(fetcher, url, init = {}, options = {}) {
     const timeout = AbortSignal.timeout(options.timeoutMs ?? TIMEOUT_MS);

package/dist/connectors/amber/client.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { ConnectorError } from "../../connector.ts";
-/** A failed Amber call. `status` 401 means the key is wrong or revoked; 429 means the rate limit (50 per 5 min). */
+/** A failed Amber call. `status` 401 or 403 (`isRejectedKey`) means the key is wrong or revoked; 429 means the rate limit (50 per 5 min). */
 export declare class AmberError extends ConnectorError {
 }
 /** One 5-minute price interval on one channel. Prices are c/kWh including GST, as a cost: negative feed-in means you are paid. */

package/dist/connectors/amber/client.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { ConnectorError, getJson } from "../../connector.js";
 // Amber Electric's public API v1 (https://app.amber.com.au/developers; the published spec is 1.0, there is no v2). Shapes checked against live replies,
 // 2026-10-13; every field optional so a change degrades a reading rather than throwing.
-/** A failed Amber call. `status` 401 means the key is wrong or revoked; 429 means the rate limit (50 per 5 min). */
+/** A failed Amber call. `status` 401 or 403 (`isRejectedKey`) means the key is wrong or revoked; 429 means the rate limit (50 per 5 min). */
 export class AmberError extends ConnectorError {
 }
 /** One 5-minute price interval on one channel. Prices are c/kWh including GST, as a cost: negative feed-in means you are paid. */

package/dist/connectors/amber/index.js

@@ -1,5 +1,5 @@
 import { asOf, realClock } from "../../clock.js";
-import { errorText } from "../../connector.js";
+import { errorText, isRejectedKey } from "../../connector.js";
 import { z } from "zod";
 import { envName } from "../../home.js";
 import { energyNow } from "../../energy.js";
@@ -41,7 +41,7 @@ export function amber(config) {
                 catch (error) {
                     if (signal.aborted)
                         return; // stopped mid-read: not a failure
-                    if (error instanceof AmberError && error.status === 401)
+                    if (isRejectedKey(error))
                         return update({
                             status: "unavailable",
                             reason: "auth",

package/dist/connectors/enphase/client.d.ts

@@ -1,5 +1,5 @@
 import { ConnectorError } from "../../connector.ts";
-/** A failed Enphase call. `status` 401 means the token is wrong or expired. */
+/** A failed Enphase call. `status` 401 or 403 (`isRejectedKey`) means the token is wrong or expired. */
 export declare class EnphaseError extends ConnectorError {
 }
 /** Solar right now and today. Watts and watt-hours as the gateway reports them, negatives included. */

package/dist/connectors/enphase/client.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { ConnectorError, fetchTimeout, getJson } from "../../connector.js";
 import { Login, Meters, Production, Readings, } from "./schemas.js";
-/** A failed Enphase call. `status` 401 means the token is wrong or expired. */
+/** A failed Enphase call. `status` 401 or 403 (`isRejectedKey`) means the token is wrong or expired. */
 export class EnphaseError extends ConnectorError {
 }
 /** A daily counter equal to the lifetime one is the software 8 bug seen on KO's gateway (D8.3.5528): not today's energy. */

package/dist/connectors/enphase/index.js

@@ -1,4 +1,5 @@
 import { localDay, realClock } from "../../clock.js";
+import { isRejectedKey } from "../../connector.js";
 import { z } from "zod";
 import { deviceRecords, filePath, } from "../../home.js";
 import { lostDetail, relocator } from "../../discover.js";
@@ -113,7 +114,7 @@ export function enphase(config) {
                 catch (error) {
                     if (signal.aborted)
                         return; // stopped mid-read: not a failure
-                    if (error instanceof EnphaseError && error.status === 401)
+                    if (isRejectedKey(error))
                         return update({
                             status: "unavailable",
                             reason: "auth",

package/dist/connectors/hue/events.d.ts

@@ -7,8 +7,6 @@ export type SseMessage = {
 };
 /** Split an SSE byte stream into messages, one per blank-line-separated block. Comment lines (`:`) are skipped. */
 export declare function parseSse(body: ReadableStream<Uint8Array>): AsyncGenerator<SseMessage>;
-/** A 401 or 403: the key is wrong or revoked. */
-export declare const isRejectedKey: (error: unknown) => boolean;
 /** What the stream yields: a (re)connection, a batch of events, or a drop with the wait before the next try. */
 export type StreamItem = {
     kind: "connected";

package/dist/connectors/hue/events.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { realClock } from "../../clock.js";
+import { isRejectedKey } from "../../connector.js";
 import { HueError } from "./client.js";
 import { HueEvent } from "./schemas.js";
 /** Split an SSE byte stream into messages, one per blank-line-separated block. Comment lines (`:`) are skipped. */
@@ -50,8 +51,6 @@ const safeJson = (text) => {
         return undefined;
     }
 };
-/** A 401 or 403: the key is wrong or revoked. */
-export const isRejectedKey = (error) => error instanceof HueError && (error.status === 401 || error.status === 403);
 /**
  * A connection with no bytes for this long is reconnected: a silent half-close otherwise looks connected forever (aiohue
  * uses 90 s). The bridge sends nothing on its own, so a quiet house trips it too; the reconnect is a silent probe.

package/dist/connectors/hue/index.js

@@ -1,10 +1,10 @@
 import { asOf, realClock } from "../../clock.js";
-import { errorText } from "../../connector.js";
+import { errorText, isRejectedKey } from "../../connector.js";
 import { z } from "zod";
 import { lostDetail, relocator } from "../../discover.js";
 import { envName, filePath, deviceRecords, } from "../../home.js";
 import { bunPinnedFetch, hueClient } from "./client.js";
-import { hueEvents, isRejectedKey } from "./events.js";
+import { hueEvents } from "./events.js";
 import { groups, lights, reduce, snapshotFrom, } from "./state.js";
 export { HUE_BRIDGE_ROOT_CA } from "./ca.js";
 export { colorToXy, kelvinToMirek, mirekToKelvin, xyToHex, } from "./color.js";

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

@@ -17,12 +17,47 @@ export declare function printerUrl(a: PrinterAddress): {
     secure: boolean;
     path: string;
 };
-/**
- * Get-Printer-Attributes over HTTP, through `fetchTimeout`. A non-ok HTTP status or an IPP status of 0x0100 and up throws a
- * ConnectorError saying which. Returns the whole response; `attributesOf` gives the printer's attributes.
- */
-export declare function getPrinterAttributes(fetcher: typeof fetch, address: PrinterAddress, options?: {
+type CallOptions = {
     requestId?: number;
     signal?: AbortSignal;
     timeoutMs?: number;
-}): Promise<IppMessage>;
+};
+/** Get-Printer-Attributes: the whole response; `attributesOf` gives the printer's attributes. `requested` replaces the poll's list. */
+export declare const getPrinterAttributes: (fetcher: typeof fetch, address: PrinterAddress, options?: CallOptions & {
+    requested?: string[];
+}) => Promise<IppMessage>;
+/** Identify-Printer: the printer shows or sounds that it is the one (PWG 5100.13). No paper. */
+export declare const identifyPrinter: (fetcher: typeof fetch, address: PrinterAddress, options?: CallOptions) => Promise<unknown>;
+/**
+ * What a job says about itself. `format` is the document's MIME type and must be one the printer lists; `media` a PWG
+ * media name (`iso_a4_210x297mm`). `sides` defaults to `one-sided`, sent explicitly so a printer's duplex default
+ * never applies to a document made for one side.
+ */
+export type PrintJob = {
+    format: string;
+    name?: string;
+    user?: string;
+    media?: string;
+    sides?: "one-sided" | "two-sided-long-edge" | "two-sided-short-edge";
+    copies?: number;
+};
+/** A job the printer took: its id, and its state when it answered (RFC 8011: 3 pending, 5 processing, 9 completed). */
+export type PrintedJob = {
+    jobId?: number;
+    state?: number;
+    reasons?: string[];
+};
+/** Validate-Job: the printer checks the job's attributes as Print-Job would, and prints nothing. */
+export declare const validateJob: (fetcher: typeof fetch, address: PrinterAddress, job: PrintJob, options?: CallOptions) => Promise<unknown>;
+/** No upload waits longer than this: a page of raster is a few hundred kB, and a printer can be slow to take it. */
+export declare const PRINT_TIMEOUT_MS = 60000;
+/**
+ * Print-Job: the job's attributes and the document in one request. A timeout leaves it unknown whether the printer took
+ * the job, so the error says not to send it again blindly.
+ */
+export declare function printJob(fetcher: typeof fetch, address: PrinterAddress, job: PrintJob, document: Uint8Array, options?: CallOptions): Promise<PrintedJob>;
+/** Cancel-Job: stop a job by its id, from Print-Job's answer. */
+export declare const cancelJob: (fetcher: typeof fetch, address: PrinterAddress, jobId: number, options?: CallOptions & {
+    user?: string;
+}) => Promise<unknown>;
+export {};

package/dist/connectors/printers/client.js

@@ -1,8 +1,8 @@
 import { ConnectorError, fetchTimeout } from "../../connector.js";
-import { attributesOf, decodeMessage, getPrinterAttributesRequest, } from "./codec.js";
-// Pure reads: a `fetch`, an address and a path come in, the printer's attributes go out. No writes here yet.
-// TODO(writes, behind KO's hand): Identify-Printer (0x003C, a beep) first, then Print-Job (0x0002) with application/pdf
-// where `document-format-supported` lists it. Each is one more request builder in codec.ts and one function here.
+import { attributesOf, decodeMessage, getPrinterAttributesRequest, OPERATION, operationRequest, TAG, } from "./codec.js";
+// Pure calls: a `fetch`, an address and the bytes to send come in, the printer's answer goes out. The reads are
+// Get-Printer-Attributes; the writes Identify-Printer, Validate-Job, Print-Job and Cancel-Job. The document is the caller's,
+// already in a format the printer lists (`document-format-supported`): this package makes no PDF into raster.
 /** Everything the integration reads from one printer. */
 export const REQUESTED = [
     "printer-state",
@@ -51,15 +51,15 @@ const STATUS = {
     0x0507: "server-error-busy",
 };
 /**
- * Get-Printer-Attributes over HTTP, through `fetchTimeout`. A non-ok HTTP status or an IPP status of 0x0100 and up throws a
- * ConnectorError saying which. Returns the whole response; `attributesOf` gives the printer's attributes.
+ * One IPP request over HTTP, through `fetchTimeout`. A non-ok HTTP status or an IPP status of 0x0100 and up throws a
+ * ConnectorError saying which (`code: "ipp"`, the IPP status in `status`).
  */
-export async function getPrinterAttributes(fetcher, address, options = {}) {
+async function call(fetcher, address, body, options = {}) {
     const url = printerUrl(address);
     const res = await fetchTimeout(fetcher, url.http, {
         method: "POST",
         headers: { "content-type": "application/ipp", accept: "application/ipp" },
-        body: getPrinterAttributesRequest(url.ipp, REQUESTED, options.requestId),
+        body: body(url.ipp),
     }, options);
     if (!res.ok)
         throw new ConnectorError(`HTTP ${res.status} on POST /${url.path}`, {
@@ -72,3 +72,76 @@ export async function getPrinterAttributes(fetcher, address, options = {}) {
     }
     return message;
 }
+/** Get-Printer-Attributes: the whole response; `attributesOf` gives the printer's attributes. `requested` replaces the poll's list. */
+export const getPrinterAttributes = (fetcher, address, options = {}) => call(fetcher, address, (uri) => getPrinterAttributesRequest(uri, options.requested ?? REQUESTED, options.requestId), options);
+/** Identify-Printer: the printer shows or sounds that it is the one (PWG 5100.13). No paper. */
+export const identifyPrinter = (fetcher, address, options = {}) => call(fetcher, address, (uri) => operationRequest(OPERATION.identifyPrinter, uri, {
+    requestId: options.requestId,
+}), options);
+/** Who asks: RFC 8011 has a client send it on every operation. `home` unless the caller names someone. */
+const userAttribute = (user = "home") => ({
+    name: "requesting-user-name",
+    tag: TAG.nameWithoutLanguage,
+    values: [user],
+});
+function jobAttributes(job) {
+    const attributes = [
+        userAttribute(job.user),
+        {
+            name: "job-name",
+            tag: TAG.nameWithoutLanguage,
+            values: [job.name ?? "home"],
+        },
+        { name: "document-format", tag: TAG.mimeMediaType, values: [job.format] },
+    ];
+    const attrs = [
+        { name: "sides", tag: TAG.keyword, values: [job.sides ?? "one-sided"] },
+    ];
+    if (job.media)
+        attrs.push({ name: "media", tag: TAG.keyword, values: [job.media] });
+    if (job.copies !== undefined)
+        attrs.push({ name: "copies", tag: TAG.integer, values: [job.copies] });
+    return { attributes, job: attrs };
+}
+/** Validate-Job: the printer checks the job's attributes as Print-Job would, and prints nothing. */
+export const validateJob = (fetcher, address, job, options = {}) => call(fetcher, address, (uri) => operationRequest(OPERATION.validateJob, uri, {
+    ...jobAttributes(job),
+    requestId: options.requestId,
+}), options);
+/** No upload waits longer than this: a page of raster is a few hundred kB, and a printer can be slow to take it. */
+export const PRINT_TIMEOUT_MS = 60_000;
+/**
+ * Print-Job: the job's attributes and the document in one request. A timeout leaves it unknown whether the printer took
+ * the job, so the error says not to send it again blindly.
+ */
+export async function printJob(fetcher, address, job, document, options = {}) {
+    let answer;
+    try {
+        answer = await call(fetcher, address, (uri) => operationRequest(OPERATION.printJob, uri, {
+            ...jobAttributes(job),
+            data: document,
+            requestId: options.requestId,
+        }), { timeoutMs: PRINT_TIMEOUT_MS, ...options });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "TimeoutError")
+            throw new ConnectorError("the printer did not answer the print job in time; it may still print, so check the printer before sending it again", { code: "timeout", cause: error });
+        throw error;
+    }
+    const a = attributesOf(answer, TAG.job);
+    const n = (v) => (typeof v === "number" ? v : undefined);
+    const reasons = a["job-state-reasons"]?.filter((r) => typeof r === "string");
+    return {
+        jobId: n(a["job-id"]?.[0]),
+        state: n(a["job-state"]?.[0]),
+        reasons: reasons?.length ? reasons : undefined,
+    };
+}
+/** Cancel-Job: stop a job by its id, from Print-Job's answer. */
+export const cancelJob = (fetcher, address, jobId, options = {}) => call(fetcher, address, (uri) => operationRequest(OPERATION.cancelJob, uri, {
+    requestId: options.requestId,
+    attributes: [
+        { name: "job-id", tag: TAG.integer, values: [jobId] },
+        userAttribute(options.user), // printers often let only the job's owner cancel it
+    ],
+}), options);

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

@@ -23,9 +23,13 @@ export declare const TAG: {
     readonly naturalLanguage: 72;
     readonly mimeMediaType: 73;
 };
-/** The operation ids this package sends. Identify-Printer (0x003C) and Print-Job (0x0002) are the writes that come later. */
+/** The operation ids this package sends (RFC 8011; Identify-Printer from PWG 5100.13). */
 export declare const OPERATION: {
+    readonly printJob: 2;
+    readonly validateJob: 4;
+    readonly cancelJob: 8;
     readonly getPrinterAttributes: 11;
+    readonly identifyPrinter: 60;
 };
 export type IppRange = {
     lower: number;
@@ -65,8 +69,18 @@ export type IppMessage = {
 };
 /** A message as bytes. Collections are not encoded (a Get-Printer-Attributes request has none). */
 export declare function encodeMessage(m: IppMessage): Uint8Array<ArrayBuffer>;
-/** The Get-Printer-Attributes request: IPP 2.0, utf-8, English, the printer's `ipp://` URI, and the attributes wanted. */
-export declare function getPrinterAttributesRequest(printerUri: string, requested: string[], requestId?: number): Uint8Array<ArrayBuffer>;
+/**
+ * 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 declare function operationRequest(code: number, printerUri: string, options?: {
+    attributes?: IppAttribute[];
+    job?: IppAttribute[];
+    data?: Uint8Array;
+    requestId?: number;
+}): Uint8Array<ArrayBuffer>;
+/** The Get-Printer-Attributes request: the attributes wanted. */
+export declare const getPrinterAttributesRequest: (printerUri: string, requested: string[], requestId?: number) => Uint8Array<ArrayBuffer>;
 /**
  * A message's bytes as groups of attributes. An unknown or malformed value is kept as `IppUnknown`, never thrown; only a
  * message that cannot be walked (cut short, a value before any attribute) throws. A collection and its members are skipped.

package/dist/connectors/printers/codec.js

@@ -27,8 +27,14 @@ export const TAG = {
     naturalLanguage: 0x48,
     mimeMediaType: 0x49,
 };
-/** The operation ids this package sends. Identify-Printer (0x003C) and Print-Job (0x0002) are the writes that come later. */
-export const OPERATION = { getPrinterAttributes: 0x000b };
+/** 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,
+};
 const STRING_TAGS = new Set([
     TAG.textWithoutLanguage,
     TAG.nameWithoutLanguage,
@@ -94,14 +100,21 @@ export function encodeMessage(m) {
             });
     }
     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(printerUri, requested, requestId = 1) {
+/**
+ * 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, printerUri, options = {}) {
     return encodeMessage({
         version: [2, 0],
-        code: OPERATION.getPrinterAttributes,
-        requestId,
+        code,
+        requestId: options.requestId ?? 1,
         groups: [
             {
                 tag: TAG.operation,
@@ -113,12 +126,23 @@ export function getPrinterAttributesRequest(printerUri, requested, requestId = 1
                         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, requested, requestId = 1) => operationRequest(OPERATION.getPrinterAttributes, printerUri, {
+    requestId,
+    attributes: [
+        { name: "requested-attributes", tag: TAG.keyword, values: requested },
+    ],
+});
 const fail = (why) => {
     throw new Error(`ipp: ${why}`);
 };

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

@@ -5,6 +5,8 @@ import { type DeviceRecord, type Integration, type Part } from "../../home.ts";
 import type { Manifest } from "../../manifest.ts";
 import { type Printer, type PrinterStatus, type PrintersState } from "./state.ts";
 export { type Marker, type Printer, type PrintersState, 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 declare const configSchema: z.ZodObject<{
     connector: z.ZodLiteral<"printers">;

package/dist/connectors/printers/index.js

@@ -8,6 +8,8 @@ import { getPrinterAttributes, printerUrl } from "./client.js";
 import { attributesOf } from "./codec.js";
 import { printerKey, printerText, toState, } from "./state.js";
 export { printerText, } from "./state.js";
+export { cancelJob, identifyPrinter, printJob, validateJob, } from "./client.js";
+export { mediaPixels, pwgRaster, } from "./raster.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"),
@@ -92,6 +94,8 @@ export function printers(config = {}) {
             name: t.name,
             model: good.model ?? t.foundModel,
             host: t.host,
+            port: t.port,
+            rp: t.rp,
             room: t.room,
             ...(offline ? { state: "offline" } : {}),
             ipps: t.ipps,

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

@@ -0,0 +1,30 @@
+/** 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;
+};
+/** 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 declare function mediaPixels(media: RasterMedia): {
+    width: number;
+    height: number;
+};
+/**
+ * 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 declare function pwgRaster(pages: Iterable<GreyPage>, media: RasterMedia, total?: number): Uint8Array<ArrayBuffer>;
+/** A PWG Raster document back as pages and their headers' key fields; for tests and for checking a file before it prints. */
+export declare function readPwgRaster(file: Uint8Array): (GreyPage & {
+    dpi: number;
+    pageSizeName: string;
+    colorSpace: number;
+    bitsPerPixel: number;
+})[];