@khalido/home 0.2.0 → 0.2.2

package/dist/connectors/cast/writes.js

@@ -1,5 +1,6 @@
 import { errorText } from "../../connector.js";
 import { writeLane } from "../../lane.js";
+import { CAST_WAV, castWav, isWav, wavText } from "./wav.js";
 import { NS } from "./codec.js";
 import { MediaStatus, MultizoneStatus, ReceiverStatus, } from "./schemas.js";
 import { castKey, DEFAULT_MEDIA_RECEIVER, findCast, } from "./state.js";
@@ -221,22 +222,51 @@ export function castActions(ctx) {
             .get(id)
             .send("level" in volume ? "level" : "muted", volume, (v) => receiver(live(find(target)), { type: "SET_VOLUME", volume: v }));
     };
+    const toReceiver = (d, payload) => ({ device: d.name, channel: "receiver", payload });
+    /** A dry SET_VOLUME: the target found and connected, nothing sent. */
+    const dryVolume = (target, volume) => {
+        const d = find(target);
+        live(d);
+        return {
+            wouldSend: [toReceiver(d, { type: "SET_VOLUME", volume })],
+        };
+    };
+    /** Each WAV clip made here, and the format it came from, so a dry run can say what was converted. */
+    const fromWav = new WeakMap();
+    /** WAV bytes as 48 kHz 16-bit stereo, which audio-only speakers play (`wav.ts`); any other clip as it is. */
+    const playable = (clip) => {
+        if ("url" in clip || !isWav(clip.type) || fromWav.has(clip.bytes))
+            return clip;
+        const r = castWav(clip.bytes);
+        if (r.converted)
+            fromWav.set(r.bytes, r.from);
+        return { bytes: r.bytes, type: "audio/wav" };
+    };
     const actions = {
-        async setVolume(target, level) {
+        async setVolume(target, level, options) {
             checkLevel(level);
+            if (options?.dryRun)
+                return dryVolume(target, { level });
             await setVolume(target, { level });
         },
-        async setMuted(target, muted) {
+        async setMuted(target, muted, options) {
+            if (options?.dryRun)
+                return dryVolume(target, { muted });
             await setVolume(target, { muted });
         },
-        async stop(target) {
-            const s = live(find(target));
+        async stop(target, options) {
+            const d = find(target);
+            const s = live(d);
             const app = (await receiver(s)).applications?.[0];
-            if (app && !app.isIdleScreen)
-                await receiver(s, {
-                    type: "STOP",
-                    ...(app.sessionId ? { sessionId: app.sessionId } : {}),
-                });
+            const stop = {
+                type: "STOP",
+                ...(app?.sessionId ? { sessionId: app.sessionId } : {}),
+            };
+            const running = app && !app.isIdleScreen;
+            if (options?.dryRun)
+                return { wouldSend: running ? [toReceiver(d, stop)] : [] };
+            if (running)
+                await receiver(s, stop);
         },
         /**
          * Read the target's state, set the volume if asked and unmute a muted target, launch the Default Media Receiver, play the clip to its end, then
@@ -244,11 +274,13 @@ export function castActions(ctx) {
          * device gets STOP, then the volume (a group's own first, then member by member through each member's own socket). Another app
          * (Spotify, YouTube) is interrupted and cannot be resumed from here; the result says so. Throws only before anything changed.
          */
-        async announce(target, clip, options = {}) {
+        async announce(target, given, options = {}) {
             if (options.volume !== undefined)
                 checkLevel(options.volume);
-            if (!("url" in clip) && !ctx.serve)
+            if (!("url" in given) && !ctx.serve)
                 throw new Error("a clip of bytes needs serve: serveClip from @khalido/home/cast/serve");
+            const clip = playable(given); // a bad WAV throws here, before anything changed
+            const wavFrom = "url" in clip ? undefined : fromWav.get(clip.bytes);
             let d = find(target);
             const s = d.kind === "group" ? await regroup(d) : live(d);
             d = ctx.devices()[d.id] ?? d; // a group's host as discovery gives it now, for serving the clip on its network
@@ -266,6 +298,8 @@ export function castActions(ctx) {
                 restored: [],
                 notRestored: [],
             };
+            if (options.dryRun)
+                return dryAnnounce();
             const serving = new AbortController();
             let served;
             let volumeSet = false;
@@ -311,6 +345,52 @@ export function castActions(ctx) {
                     await restoreVolume();
             }
             return result;
+            /** What the announce would send, from the reads above; what it could not put back goes in `notRestored`. */
+            function dryAnnounce() {
+                const to = (device, payload) => ({
+                    device: device.name,
+                    channel: "receiver",
+                    payload,
+                });
+                const media = (payload) => ({
+                    device: d.name,
+                    channel: "media",
+                    payload,
+                });
+                const sends = [];
+                if (options.volume !== undefined)
+                    sends.push(to(d, { type: "SET_VOLUME", volume: { level: options.volume } }));
+                if (unmute)
+                    sends.push(to(d, { type: "SET_VOLUME", volume: { muted: false } }));
+                sends.push(to(d, { type: "LAUNCH", appId: DEFAULT_MEDIA_RECEIVER }), media({
+                    type: "LOAD",
+                    media: {
+                        contentId: "url" in clip
+                            ? clip.url
+                            : `(${clip.bytes.length} bytes of ${clip.type}${wavFrom ? `, converted from ${wavText(wavFrom)} to ${wavText(CAST_WAV)}` : ""}, served on the LAN)`,
+                        contentType: clip.type ?? "audio/mpeg",
+                        streamType: "BUFFERED",
+                    },
+                    autoplay: true,
+                }));
+                if (priorMedia)
+                    sends.push(media({ type: "LOAD", ...priorMedia }));
+                else {
+                    sends.push(to(d, { type: "STOP" }));
+                    if (!idleApp(prior) && prior?.appId !== DEFAULT_MEDIA_RECEIVER)
+                        result.notRestored.push({
+                            name: d.name,
+                            why: `${prior?.displayName ?? prior?.appId ?? "an app"} would be interrupted and cannot be resumed from here`,
+                        });
+                }
+                for (const step of volumeSteps())
+                    if ("gap" in step)
+                        result.notRestored.push({ name: step.name, why: step.gap });
+                    else
+                        for (const p of step.payloads)
+                            sends.push(to(step, p));
+                return { ...result, why: "dry run", wouldSend: sends };
+            }
             async function restoreApp() {
                 try {
                     // A LAUNCH that timed out may still have started: look before deciding nothing of ours runs.
@@ -346,78 +426,91 @@ export function castActions(ctx) {
                     });
                 }
             }
-            async function restoreVolume() {
-                const each = d.kind === "group"
-                    ? members
-                    : [
-                        {
-                            id: d.id,
-                            name: d.name,
-                            level: before.volume?.level,
-                            muted: before.volume?.muted,
-                        },
-                    ];
-                // A group keeps a level of its own, which its members' levels don't bring back (live, 2026-11-10: it stayed at the
-                // announcement's 30 with every member restored). First, so whatever it does to the members, their own levels land last.
+            /**
+             * The volume put back after the clip, as steps: a group's own level first (it keeps one of its own, which its members'
+             * levels don't bring back: live, 2026-11-10, it stayed at the announcement's 30 with every member restored), so
+             * whatever it does to the members, their own levels land last; then each member's, or the target's, through its own
+             * socket. A step it can't take is a gap with the reason. `restoreVolume` takes them; a dry run reports them.
+             */
+            function volumeSteps() {
+                const steps = [];
                 if (d.kind === "group" && options.volume !== undefined) {
                     const level = before.volume?.level;
-                    if (level === undefined)
-                        result.notRestored.push({
+                    steps.push(level === undefined
+                        ? { name: d.name, gap: "its volume before was not reported" }
+                        : {
                             name: d.name,
-                            why: "its volume before was not reported",
+                            socket: s,
+                            payloads: [{ type: "SET_VOLUME", volume: { level } }],
+                            label: `${d.name}: volume`,
                         });
-                    else
-                        try {
-                            await receiver(s, { type: "SET_VOLUME", volume: { level } });
-                            result.restored.push(`${d.name}: volume`);
-                        }
-                        catch (error) {
-                            result.notRestored.push({
-                                name: d.name,
-                                why: `volume not restored: ${errorText(error)}`,
-                            });
-                        }
                 }
+                const each = d.kind === "group"
+                    ? members
+                    : options.volume !== undefined || unmute
+                        ? [
+                            {
+                                id: d.id,
+                                name: d.name,
+                                level: before.volume?.level,
+                                muted: before.volume?.muted,
+                            },
+                        ]
+                        : [];
                 for (const m of each) {
                     const ms = m.id === d.id ? s : ctx.session(m.id);
                     if (m.level === undefined)
-                        result.notRestored.push({
+                        steps.push({
                             name: m.name,
-                            why: "its volume before was not reported",
+                            gap: "its volume before was not reported",
                         });
                     else if (!ms)
-                        result.notRestored.push({
+                        steps.push({
                             name: m.name,
-                            why: "not connected, so its volume stays as the announcement set it",
+                            gap: "not connected, so its volume stays as the announcement set it",
                         });
                     else
-                        try {
-                            await receiver(ms, {
-                                type: "SET_VOLUME",
-                                volume: { level: m.level },
-                            });
-                            if (m.muted)
-                                await receiver(ms, {
-                                    type: "SET_VOLUME",
-                                    volume: { muted: true },
-                                });
-                            result.restored.push(`${m.name}: volume${m.muted ? ", muted" : ""}`);
-                        }
-                        catch (error) {
-                            result.notRestored.push({
-                                name: m.name,
-                                why: `volume not restored: ${errorText(error)}`,
-                            });
-                        }
+                        steps.push({
+                            name: m.name,
+                            socket: ms,
+                            payloads: [
+                                { type: "SET_VOLUME", volume: { level: m.level } },
+                                ...(m.muted
+                                    ? [{ type: "SET_VOLUME", volume: { muted: true } }]
+                                    : []),
+                            ],
+                            label: `${m.name}: volume${m.muted ? ", muted" : ""}`,
+                        });
+                }
+                return steps;
+            }
+            async function restoreVolume() {
+                for (const step of volumeSteps()) {
+                    if ("gap" in step) {
+                        result.notRestored.push({ name: step.name, why: step.gap });
+                        continue;
+                    }
+                    try {
+                        for (const p of step.payloads)
+                            await receiver(step.socket, p);
+                        result.restored.push(step.label);
+                    }
+                    catch (error) {
+                        result.notRestored.push({
+                            name: step.name,
+                            why: `volume not restored: ${errorText(error)}`,
+                        });
+                    }
                 }
             }
         },
-        async announceAll(targets, clip, options = {}) {
+        async announceAll(targets, given, options = {}) {
             // A caller's mistake is one error, not a failure per speaker.
             if (options.volume !== undefined)
                 checkLevel(options.volume);
-            if (!("url" in clip) && !ctx.serve)
+            if (!("url" in given) && !ctx.serve)
                 throw new Error("a clip of bytes needs serve: serveClip from @khalido/home/cast/serve");
+            const clip = playable(given); // converted once, for every target
             const id = (t) => {
                 try {
                     return find(t).id;

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