@khalido/home 0.2.0 → 0.2.1

package/src/cli/printers.ts

@@ -1,9 +1,34 @@
 // Printers without a config: what `home status`, `home printers` and `home probe` run. Cached addresses first, then
-// discovery (AirPrint over mDNS) finds the rest. Read-only; the integration has no writes yet.
-import { printers } from "../connectors/printers/index.ts";
+// discovery (AirPrint over mDNS) finds the rest.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { basename } from "node:path";
+import {
+  cancelJob,
+  getPrinterAttributes,
+  identifyPrinter,
+  type PrinterAddress,
+  type PrintJob,
+  printJob,
+  validateJob,
+} from "../connectors/printers/client.ts";
+import { attributesOf } from "../connectors/printers/codec.ts";
+import {
+  printerList,
+  printers,
+  type PrintersState,
+} from "../connectors/printers/index.ts";
+import {
+  type GreyPage,
+  mediaPixels,
+  pwgRaster,
+  type RasterMedia,
+} from "../connectors/printers/raster.ts";
+import { printerKey } from "../connectors/printers/state.ts";
 import { addressBook } from "../discover.ts";
 import { FINDERS } from "../finders.ts";
-import { addresses } from "./context.ts";
+import { settle } from "../home.ts";
+import { addresses, fail, usage, type Verbs } from "./context.ts";
 
 /** Every printer the address cache knows plus whatever discovery finds, read once. */
 export function printersNow() {
@@ -19,3 +44,229 @@ export function printersNow() {
     seen: (uuid, a) => book.seen("printers", uuid, a),
   });
 }
+
+// `home printers identify | print | cancel`: the writes. A printer that lists no PDF gets PWG Raster, rendered here with
+// poppler's pdftoppm (the one tool this needs; `brew install poppler`, `apt install poppler-utils`).
+// Live 2026-11-12 on a Brother HL-L2350DW (Bun 1.4.4): identify, validate and one A4 page.
+
+export const PRINTERS_USAGE =
+  "usage: home printers identify [printer] | print <file.pdf> [printer] | cancel <job> [printer]";
+
+/** One printer by name or UUID, or the only one there is; with its address. */
+async function onePrinter(name: string | undefined) {
+  const part = (await settle([printersNow()], { ms: 15_000 })).printers!;
+  const all = printerList(
+    (part.state as PrintersState | undefined) ?? { printers: {}, asOf: "" },
+  );
+  const p = name
+    ? (all.find((x) => x.uuid === printerKey(name)) ??
+      all.find((x) => x.name.toLowerCase() === name.toLowerCase()))
+    : all.length === 1
+      ? all[0]
+      : undefined;
+  if (!p)
+    return fail(
+      name
+        ? `no printer named ${name}; \`home printers\` lists them`
+        : all.length
+          ? `${all.length} printers: name one (${all.map((x) => x.name).join(", ")})`
+          : "no printer found; `home discover` looks for them",
+      name || !all.length ? "error" : "usage",
+    );
+  if (p.state === "offline" || !p.host)
+    return fail(`${p.name} is offline`, "network");
+  const address: PrinterAddress = {
+    host: p.host,
+    port: p.port,
+    rp: p.rp,
+    secure: p.ipps,
+  };
+  return { printer: p, address };
+}
+
+/** What the printer takes, asked for once before a print. */
+async function capabilities(address: PrinterAddress) {
+  const a = attributesOf(
+    await getPrinterAttributes(fetch, address, {
+      requested: [
+        "document-format-supported",
+        "pwg-raster-document-resolution-supported",
+        "pwg-raster-document-type-supported",
+        "media-ready",
+        "media-default",
+      ],
+    }),
+  );
+  const strings = (k: string) =>
+    (a[k] ?? []).filter((v): v is string => typeof v === "string");
+  const dpis = (a["pwg-raster-document-resolution-supported"] ?? []).flatMap(
+    (r) =>
+      typeof r === "object" && "x" in r && r.units === "dpi" && r.x === r.y
+        ? [r.x]
+        : [],
+  );
+  return {
+    formats: strings("document-format-supported"),
+    rasterTypes: strings("pwg-raster-document-type-supported"),
+    dpis,
+    media: strings("media-ready")[0] ?? strings("media-default")[0],
+  };
+}
+
+/**
+ * A PDF's pages as 8-bit grey, one at a time, each fitted to the media and centred on white, through pdfinfo and
+ * pdftoppm. A page's `/Rotate` is applied, as pdftoppm does; a landscape page is shrunk to fit, not turned.
+ */
+function renderPdf(
+  file: string,
+  media: RasterMedia,
+): { count: number; pages: Iterable<GreyPage> } {
+  const run = (command: string, args: string[]) => {
+    const r = spawnSync(command, args, { maxBuffer: 1 << 30 });
+    if (r.error)
+      fail(
+        `${command} is not installed: it renders the PDF for a printer that takes no PDF`,
+        "error",
+        process.platform === "darwin"
+          ? "brew install poppler"
+          : "sudo apt install poppler-utils",
+      );
+    if (r.status !== 0) fail(`${command}: ${r.stderr.toString().trim()}`);
+    return r.stdout;
+  };
+  const info = run("pdfinfo", ["-l", "9999", file]).toString();
+  const turned = new Map(
+    [...info.matchAll(/^Page\s+(\d+) rot:\s+(\d+)/gm)].map((m) => [
+      Number(m[1]),
+      Number(m[2]) % 180 === 90,
+    ]),
+  );
+  const sizes = [
+    ...info.matchAll(/^Page\s+(\d+) size:\s+([\d.]+) x ([\d.]+) pts/gm),
+  ].map((m) =>
+    turned.get(Number(m[1]))
+      ? { w: Number(m[3]), h: Number(m[2]) }
+      : { w: Number(m[2]), h: Number(m[3]) },
+  );
+  if (!sizes.length) fail(`${file}: pdfinfo found no pages`);
+  const out = mediaPixels(media);
+  function* pages(): Generator<GreyPage> {
+    for (const [i, size] of sizes.entries()) {
+      // The largest resolution at which the page fits the media, so nothing is cut off; never above the printer's.
+      const r = Math.min(
+        media.dpi,
+        (out.width / size.w) * 72,
+        (out.height / size.h) * 72,
+      );
+      const pgm = run("pdftoppm", [
+        "-gray",
+        "-r",
+        r.toFixed(3),
+        "-f",
+        String(i + 1),
+        "-l",
+        String(i + 1),
+        "-singlefile",
+        file,
+      ]);
+      const head = /^P5\s+(\d+)\s+(\d+)\s+255\s/.exec(
+        pgm.subarray(0, 64).toString("latin1"),
+      );
+      if (!head)
+        return fail(`pdftoppm: page ${i + 1} is not an 8-bit grey image`);
+      const w = Number(head[1]);
+      const h = Number(head[2]);
+      // A pixel over is rounding; more means the size was misread, and a clipped page must not print.
+      if (w > out.width + 1 || h > out.height + 1)
+        return fail(
+          `page ${i + 1} rendered at ${w} × ${h}, larger than ${media.name} (${out.width} × ${out.height}); nothing sent`,
+        );
+      const pixels = new Uint8Array(out.width * out.height).fill(255);
+      const left = Math.max(0, Math.floor((out.width - w) / 2));
+      const top = Math.max(0, Math.floor((out.height - h) / 2));
+      const from = pgm.subarray(head[0].length);
+      for (let y = 0; y < Math.min(h, out.height); y++)
+        pixels.set(
+          from.subarray(y * w, y * w + Math.min(w, out.width)),
+          (top + y) * out.width + left,
+        );
+      yield { ...out, pixels };
+    }
+  }
+  return { count: sizes.length, pages: pages() };
+}
+
+const STATES: Record<number, string> = {
+  3: "pending",
+  4: "held",
+  5: "printing",
+  6: "stopped",
+  7: "cancelled",
+  8: "aborted",
+  9: "completed",
+};
+
+export const printersVerbs: Verbs = {
+  async identify([name, extra], o) {
+    if (o.dryRun) usage("home printers identify has no dry run");
+    if (extra) usage(PRINTERS_USAGE);
+    const { printer, address } = await onePrinter(name);
+    await identifyPrinter(fetch, address);
+    console.log(`${printer.name}: identify sent`);
+  },
+
+  async print([file, name, extra], o) {
+    if (!file || extra) return usage(PRINTERS_USAGE);
+    if (!/\.pdf$/i.test(file)) return usage(`${file}: only a PDF prints`);
+    if (!existsSync(file)) return usage(`${file}: no such file`);
+    const { printer, address } = await onePrinter(name);
+    const can = await capabilities(address);
+    const job: PrintJob = {
+      format: "application/pdf",
+      name: basename(file),
+      media: can.media,
+    };
+    let document: Uint8Array | undefined;
+    let what = `${basename(file)} as PDF`;
+    if (!can.formats.includes("application/pdf")) {
+      const dpi = can.dpis.includes(600) ? 600 : can.dpis[0];
+      if (!can.formats.includes("image/pwg-raster") || !dpi)
+        return fail(
+          `${printer.name} takes neither PDF nor PWG Raster (it lists ${can.formats.join(", ") || "nothing"})`,
+        );
+      if (!can.rasterTypes.includes("sgray_8"))
+        return fail(
+          `${printer.name}'s PWG Raster is ${can.rasterTypes.join(", ")}; only sgray_8 is built`,
+        );
+      if (!can.media)
+        return fail(`${printer.name} reports no media loaded or default`);
+      const { count, pages } = renderPdf(file, { name: can.media, dpi });
+      document = pwgRaster(pages, { name: can.media, dpi }, count);
+      job.format = "image/pwg-raster";
+      what = `${count} page${count === 1 ? "" : "s"} of ${can.media} at ${dpi} dpi as PWG Raster (${Math.round(document.length / 1024)} kB)`;
+    }
+    await validateJob(fetch, address, job); // prints nothing: a dry run checks the job as the printer would
+    if (o.dryRun)
+      return console.log(
+        `dry run, no job sent: the printer accepts it; would print ${what} on ${printer.name}`,
+      );
+    const done = await printJob(
+      fetch,
+      address,
+      job,
+      document ?? readFileSync(file),
+    );
+    console.log(
+      `${printer.name}: job ${done.jobId ?? "?"} ${STATES[done.state ?? 0] ?? "sent"} · ${what}`,
+    );
+  },
+
+  async cancel([id, name, extra], o) {
+    if (o.dryRun) usage("home printers cancel has no dry run");
+    const job = Number(id);
+    if (!Number.isInteger(job) || extra) return usage(PRINTERS_USAGE);
+    const { printer, address } = await onePrinter(name);
+    await cancelJob(fetch, address, job);
+    console.log(`${printer.name}: job ${job} cancelled`);
+  },
+};

package/src/connector.ts

@@ -51,6 +51,11 @@ export class ConnectorError extends Error {
   }
 }
 
+/** 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: unknown) =>
+  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: typeof fetch,

package/src/connectors/amber/README.md

@@ -9,7 +9,7 @@ Amber Electric's live wholesale-linked prices, read through Amber's public API.
 - `forecast`: the current interval, then each forecast one, both channels on one row (`PriceInterval`). `next=96` asks for more than Amber has, so the reply runs as far as Amber forecasts: on 2026-10-28 at 3 pm, 12 five-minute intervals then 14 half-hours, to 11 pm. Amber's `startTime` is a second past the interval's start, so `start` is taken to the minute.
 - `estimate: true` means the current interval's price can still move; it is shown as "(estimate)", never as an anomaly.
 - The Amber line in `home status` shows the descriptor, "(estimate)", a spike other than `none`, and a negative price. `energyNow` combines the prices with Enphase; see Energy below.
-- A 401 marks Amber unavailable and stops polling.
+- A 401 or 403 marks Amber unavailable and stops polling.
 
 ## Energy
 

package/src/connectors/amber/client.ts

@@ -4,7 +4,7 @@ import { ConnectorError, getJson } from "../../connector.ts";
 // 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/src/connectors/amber/index.ts

@@ -1,5 +1,5 @@
 import { asOf, type Clock, realClock } from "../../clock.ts";
-import { errorText } from "../../connector.ts";
+import { errorText, isRejectedKey } from "../../connector.ts";
 import { z } from "zod";
 import { envName, type Integration } from "../../home.ts";
 import { energyNow } from "../../energy.ts";
@@ -62,7 +62,7 @@ export function amber(
           update({ status: "connected", anomaly: last.anomaly, state: last });
         } 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/src/connectors/enphase/README.md

@@ -10,9 +10,11 @@ Reads an IQ Gateway (Envoy) on the LAN: production, consumption and grid flow. `
 - `host` may be pasted with a scheme or a trailing slash (`https://…/`); `gatewayHost` reduces it to the bare host for requests, discovery and the address cache.
 - In the home config the device may carry `marker` (the plan's marker where the array is drawn, on the roof outside any room) and `capacityW` (the array's rated watts from the installer's paperwork, never guessed from the gateway). Neither reaches the gateway; they are for drawing.
 - A meter counts only when `/ivp/meters` says `enabled` **and** its reading has `activeCount > 0`; otherwise production comes from the inverters and Wh today is left out, since pyenphase found the inverter daily total unreliable.
-- The token's days left ride in the snapshot; under 30 the status says to run `home enphase login`. A 401 marks Enphase unavailable and stops polling.
+- The token's days left ride in the snapshot; under 30 the status says to run `home enphase login`. A 401 or 403 marks Enphase unavailable and stops polling.
 - `home enphase login` mints the token (below) and writes `~/.config/home/enphase-token.json` (0600, directory 0700), printing only the days left. `home status` shows solar now, consumption and the token's days left.
 
+**Live, 2026-11-12 (Bun 1.4.4).** From late October `home enphase` said ECONNREFUSED. The gateway had not changed: DHCP had given it a new address, mDNS and the address cache had the new one, and an `IQ_GATEWAY_HOST` in the shell still named the old one, which the CLI trusted without a fallback. The CLI now takes the serial from the address cache and runs discovery after one failed read, so the status line reads and says "moved from a to b". The owner token was fine throughout (338 days left).
+
 **Live, KO's gateway, 2026-10-13 (D8.3.5528, owner token).** `/info` answers without a token; everything else answers 401 without one. With the token, one GET each:
 
 - `/ivp/meters`: `production` and `net-consumption` **enabled**, `meteringStatus normal`; `storage`, `backfeed`, `load`, `evse`, `pv3p` disabled. So both CTs are fitted.

package/src/connectors/enphase/client.ts

@@ -8,7 +8,7 @@ import {
   type Measurement,
 } from "./schemas.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 class EnphaseError extends ConnectorError {}
 
 /** Solar right now and today. Watts and watt-hours as the gateway reports them, negatives included. */

package/src/connectors/enphase/index.ts

@@ -1,4 +1,5 @@
 import { type Clock, localDay, realClock } from "../../clock.ts";
+import { isRejectedKey } from "../../connector.ts";
 import { z } from "zod";
 import {
   type DeviceRecord,
@@ -180,7 +181,7 @@ export function enphase(
           });
         } 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/src/connectors/hue/events.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { type Clock, realClock } from "../../clock.ts";
+import { isRejectedKey } from "../../connector.ts";
 import { HueError, type HueOptions } from "./client.ts";
 import { HueEvent } from "./schemas.ts";
 
@@ -56,10 +57,6 @@ const safeJson = (text: string): unknown => {
   }
 };
 
-/** A 401 or 403: the key is wrong or revoked. */
-export const isRejectedKey = (error: unknown) =>
-  error instanceof HueError && (error.status === 401 || error.status === 403);
-
 /** 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/src/connectors/hue/index.ts

@@ -1,5 +1,5 @@
 import { asOf, type Clock, realClock } from "../../clock.ts";
-import { errorText } from "../../connector.ts";
+import { errorText, isRejectedKey } from "../../connector.ts";
 import { z } from "zod";
 import { type Finder, lostDetail, relocator } from "../../discover.ts";
 import {
@@ -13,7 +13,7 @@ import {
 } from "../../home.ts";
 import type { Manifest } from "../../manifest.ts";
 import { bunPinnedFetch, type HueClient, hueClient } from "./client.ts";
-import { hueEvents, isRejectedKey } from "./events.ts";
+import { hueEvents } from "./events.ts";
 import type { HueEvent } from "./schemas.ts";
 import {
   type GroupView,

package/src/connectors/printers/README.md

@@ -1,8 +1,8 @@
 # Printers
 
-AirPrint printers, found by mDNS and read over IPP on the local network. `iot_class`: **local_polling** (one Get-Printer-Attributes per printer every 120 s). Built read-only; first read of a live printer 2026-11-10 (see Live findings).
+AirPrint printers, found by mDNS and read over IPP on the local network, and a PDF printed on one. `iot_class`: **local_polling** (one Get-Printer-Attributes per printer every 120 s). Reads live since 2026-11-10; a print live on 2026-11-12 (see Live findings).
 
-Try it: `home printers`
+Try it: `home printers`, `home printers print page.pdf --dry-run`
 
 ## Built
 
@@ -12,7 +12,10 @@ Try it: `home printers`
 - **Odd values pass through.** A `printer-state` outside 3 to 5 leaves `state` out, keeps `stateCode`, and is named in `anomaly`. A marker level outside 0 to 100 stays as sent and is named (PWG 5100.13 reserves negative levels for "unknown" kinds; read it before treating one as empty). Marker lists of different lengths are named too.
 - **Identity check.** The printer's `printer-uuid` must match the entry's UUID, or the read fails with "the address answers as another printer", so a recycled address never shows one printer's toner under another's name.
 - **Discovery** is one shared scan, as Cast's is, not a relocator per printer (the relocator is one device and one scan each; three printers down would be three `dns-sd` runs). It runs at start, after a failed read at 1, 5 and 15 minutes then hourly (`rescanDelay`), hourly for new printers, and a `refresh()` resets the backoff. A moved printer is found by its UUID and read again at once; `detail` says "not found by discovery" only after a scan looked and missed it (`lostDetail`).
-- `home discover` lists printers and `--write` adds them (`uuid`, `name`, `host`, `port`); `home probe` reads each once. No writes. The place for them is marked `TODO(writes…)` in `client.ts`.
+- `home discover` lists printers and `--write` adds them (`uuid`, `name`, `host`, `port`); `home probe` reads each once.
+- **Writes** (`client.ts`, exported): `identifyPrinter` (the printer shows or sounds; no paper), `validateJob` (checks a job, prints nothing), `printJob` (attributes and document in one request; resolves the job's id and state) and `cancelJob`. Each takes the printer's address (`host`, `port`, `rp` and `ipps` are in the snapshot) and bytes already in a format the printer lists. A job is `one-sided` unless it says otherwise, so a printer's duplex default never applies. A Print-Job that times out (60 s) is a `timeout` error that says it may still print: never resend it blindly.
+- **PWG Raster** (`raster.ts`): `pwgRaster(pages, media, total?)` packs 8-bit grey pages, an array or one at a time from a generator, into `image/pwg-raster` (PWG 5102.4), for a printer that lists no PDF. `mediaPixels` gives a page's size at a resolution. Only `sgray_8`.
+- **`home printers print <file.pdf> [printer]`**: sends the PDF as is when the printer lists `application/pdf`; otherwise renders each page with poppler's `pdftoppm` at the printer's raster resolution, fitted to the loaded media and centred (a page's `/Rotate` applied; a landscape page shrunk to fit, not turned), then Validate-Job, then Print-Job. One page is held at a time. `--dry-run` renders and has the printer validate the job (Validate-Job prints nothing), and sends no job. `home printers identify [printer]` and `cancel <job> [printer]`. The printer can be left out when there is one.
 
 ## Protocol
 
@@ -30,10 +33,12 @@ Discovery is mDNS `_ipp._tcp` and `_ipps._tcp` ([Apple's AirPrint TXT keys](http
 
 ## Unverified
 
-Everything, until a real printer answers: the request bytes (the codec is checked against RFC 8010's layout and a fixture of invented values, not a printer), the default path `ipp/print`, that `printer-uuid` equals TXT `UUID` on a Brother, that a sleeping printer wakes for the request, what a Brother sends for `marker-levels` and `printer-alert` (the sample uses invented values), Bun's `fetch` on port 631, and the macOS local-network prompt on first use.
+`printer-uuid` against TXT `UUID` on a Brother, a sleeping printer waking for a request, what `printer-alert` means on it, and the macOS local-network prompt on first use. For printing: a printer that takes PDF, a document of more than one page, two-sided, a colour printer, and the Node CLI (only Bun has run it).
 
 ## Live findings
 
+**2026-11-12, from a Mac (Bun 1.4.4), Brother HL-L2350DW.** It lists `application/octet-stream`, `image/urf` and `image/pwg-raster`, no PDF; PWG Raster at 600 dpi, `sgray_8` only, `pwg-raster-document-sheet-back` `rotated`; operations include Validate-Job, Cancel-Job and Identify-Printer. Identify-Printer and Validate-Job answered OK. Two one-page jobs printed: first a raster macOS's own filters made (`cupsfilter` with the AirPrint PPD; now `test/fixtures/printers/macos-a4-600.pwg`), then one from `home printers print` and `pwgRaster`, 60 kB for a page of text. Each answered `job-state` 5 (processing), both pages came out right (two lines of text, A4), and the printer was idle again within 30 s.
+
 **2026-11-10, from a Pi (Bun 1.4.4, 0.1.2; chota-bot's session).** `home discover` found the Brother by mDNS and `home printers` read it: "Brother HL-L2350DW series: idle · BK 80% · A4 ready". So discovery, the request, the default path, a real `marker-levels` and `media-ready` work on this model. Still unverified from the list above: `printer-uuid` against TXT `UUID`, a sleeping printer waking, `printer-alert`, and the macOS local-network prompt.
 
 2026-10-14 (Bun 1.4.3): `home discover` (two passes) and `home printers` found no `_ipp._tcp` or `_ipps._tcp` instance on the network, so the Brother was not advertising (off, asleep, or on another network).

package/src/connectors/printers/client.ts

@@ -3,12 +3,16 @@ import {
   attributesOf,
   decodeMessage,
   getPrinterAttributesRequest,
+  type IppAttribute,
   type IppMessage,
+  OPERATION,
+  operationRequest,
+  TAG,
 } from "./codec.ts";
 
-// 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.
+// 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 = [
@@ -74,18 +78,21 @@ const STATUS: Record<number, string> = {
   0x0507: "server-error-busy",
 };
 
+type CallOptions = {
+  requestId?: number;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+};
+
 /**
- * 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(
+async function call(
   fetcher: typeof fetch,
   address: PrinterAddress,
-  options: {
-    requestId?: number;
-    signal?: AbortSignal;
-    timeoutMs?: number;
-  } = {},
+  body: (ippUri: string) => Uint8Array<ArrayBuffer>,
+  options: CallOptions = {},
 ): Promise<IppMessage> {
   const url = printerUrl(address);
   const res = await fetchTimeout(
@@ -94,7 +101,7 @@ export async function getPrinterAttributes(
     {
       method: "POST",
       headers: { "content-type": "application/ipp", accept: "application/ipp" },
-      body: getPrinterAttributesRequest(url.ipp, REQUESTED, options.requestId),
+      body: body(url.ipp),
     },
     options,
   );
@@ -112,3 +119,170 @@ export async function getPrinterAttributes(
   }
   return message;
 }
+
+/** Get-Printer-Attributes: the whole response; `attributesOf` gives the printer's attributes. `requested` replaces the poll's list. */
+export const getPrinterAttributes = (
+  fetcher: typeof fetch,
+  address: PrinterAddress,
+  options: CallOptions & { requested?: string[] } = {},
+): Promise<IppMessage> =>
+  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: typeof fetch,
+  address: PrinterAddress,
+  options: CallOptions = {},
+): Promise<unknown> =>
+  call(
+    fetcher,
+    address,
+    (uri) =>
+      operationRequest(OPERATION.identifyPrinter, uri, {
+        requestId: options.requestId,
+      }),
+    options,
+  );
+
+/**
+ * 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[] };
+
+/** Who asks: RFC 8011 has a client send it on every operation. `home` unless the caller names someone. */
+const userAttribute = (user = "home"): IppAttribute => ({
+  name: "requesting-user-name",
+  tag: TAG.nameWithoutLanguage,
+  values: [user],
+});
+
+function jobAttributes(job: PrintJob): {
+  attributes: IppAttribute[];
+  job: IppAttribute[];
+} {
+  const attributes: IppAttribute[] = [
+    userAttribute(job.user),
+    {
+      name: "job-name",
+      tag: TAG.nameWithoutLanguage,
+      values: [job.name ?? "home"],
+    },
+    { name: "document-format", tag: TAG.mimeMediaType, values: [job.format] },
+  ];
+  const attrs: IppAttribute[] = [
+    { 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: typeof fetch,
+  address: PrinterAddress,
+  job: PrintJob,
+  options: CallOptions = {},
+): Promise<unknown> =>
+  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: typeof fetch,
+  address: PrinterAddress,
+  job: PrintJob,
+  document: Uint8Array,
+  options: CallOptions = {},
+): Promise<PrintedJob> {
+  let answer: IppMessage;
+  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: unknown) => (typeof v === "number" ? v : undefined);
+  const reasons = a["job-state-reasons"]?.filter(
+    (r): r is string => 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: typeof fetch,
+  address: PrinterAddress,
+  jobId: number,
+  options: CallOptions & { user?: string } = {},
+): Promise<unknown> =>
+  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,
+  );