@khalido/home 0.1.3 → 0.2.1

package/src/connectors/hue/color.ts

@@ -0,0 +1,123 @@
+import { ConnectorError } from "../../connector.ts";
+
+// Colour for Hue lights. A light's colour is an `xy` point in the CIE 1931 space, and each light can show the points
+// inside its gamut triangle, which the bridge reports per light. The steps are the standard sRGB ones (gamma, the D65
+// matrix), as Signify's "Color Conversion Formulas" page describes; that page's SDK extract is not copied.
+
+export type XY = { x: number; y: number };
+export type Gamut = { red: XY; green: XY; blue: XY };
+export type Rgb = { r: number; g: number; b: number };
+
+/** A colour as a caller gives it: "#ff8800", "ff8800", "#f80", or `{ r, g, b }` each 0–255. Throws on anything else. */
+export function parseColor(color: string | Rgb): Rgb {
+  if (typeof color !== "string") {
+    const ok = [color.r, color.g, color.b].every(
+      (v) => Number.isFinite(v) && v >= 0 && v <= 255,
+    );
+    if (!ok)
+      throw new ConnectorError("a colour's r, g and b are each 0–255", {
+        code: "invalid",
+      });
+    return color;
+  }
+  const hex = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim())?.[1];
+  if (!hex)
+    throw new ConnectorError(`"${color}" is not a colour like #ff8800`, {
+      code: "invalid",
+    });
+  const full = hex.length === 3 ? [...hex].map((c) => c + c).join("") : hex;
+  const n = Number.parseInt(full, 16);
+  return { r: n >> 16, g: (n >> 8) & 255, b: n & 255 };
+}
+
+const linear = (v: number) =>
+  v > 0.04045 ? ((v + 0.055) / 1.055) ** 2.4 : v / 12.92;
+const gamma = (v: number) =>
+  v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055;
+
+const cross = (a: XY, b: XY) => a.x * b.y - a.y * b.x;
+const minus = (a: XY, b: XY): XY => ({ x: a.x - b.x, y: a.y - b.y });
+
+/** Whether `p` is inside the gamut triangle. */
+export function inGamut(p: XY, g: Gamut): boolean {
+  const v1 = minus(g.green, g.red);
+  const v2 = minus(g.blue, g.red);
+  const q = minus(p, g.red);
+  const s = cross(q, v2) / cross(v1, v2);
+  const t = cross(v1, q) / cross(v1, v2);
+  return s >= 0 && t >= 0 && s + t <= 1;
+}
+
+/** The nearest point to `p` on the segment a–b. */
+function onSegment(a: XY, b: XY, p: XY): XY {
+  const ab = minus(b, a);
+  const t = Math.min(
+    1,
+    Math.max(
+      0,
+      ((p.x - a.x) * ab.x + (p.y - a.y) * ab.y) / (ab.x ** 2 + ab.y ** 2),
+    ),
+  );
+  return { x: a.x + ab.x * t, y: a.y + ab.y * t };
+}
+
+/** `p` if the light can show it, else the nearest point on its gamut's edge: the colour it can show that is closest. */
+export function nearestInGamut(p: XY, g: Gamut): XY {
+  if (inGamut(p, g)) return p;
+  const edges = [
+    onSegment(g.red, g.green, p),
+    onSegment(g.green, g.blue, p),
+    onSegment(g.blue, g.red, p),
+  ];
+  const far = (q: XY) => (q.x - p.x) ** 2 + (q.y - p.y) ** 2;
+  return edges.reduce((best, q) => (far(q) < far(best) ? q : best));
+}
+
+/**
+ * A colour's `xy`, moved inside `gamut` when one is given. Brightness is not part of it: black has no colour and throws
+ * (turn the light off instead), and a dark red and a bright red are the same point.
+ */
+export function colorToXy(color: string | Rgb, gamut?: Gamut): XY {
+  const { r, g, b } = parseColor(color);
+  const [lr, lg, lb] = [r, g, b].map((v) => linear(v / 255)) as [
+    number,
+    number,
+    number,
+  ];
+  const X = lr * 0.4124 + lg * 0.3576 + lb * 0.1805;
+  const Y = lr * 0.2126 + lg * 0.7152 + lb * 0.0722;
+  const Z = lr * 0.0193 + lg * 0.1192 + lb * 0.9505;
+  const sum = X + Y + Z;
+  if (sum === 0)
+    throw new ConnectorError("black is not a colour a light can show", {
+      code: "invalid",
+    });
+  const xy = { x: X / sum, y: Y / sum };
+  const at = gamut ? nearestInGamut(xy, gamut) : xy;
+  return { x: round4(at.x), y: round4(at.y) };
+}
+const round4 = (v: number) => Math.round(v * 1e4) / 1e4;
+
+/** An `xy` as a hex colour for a screen, at full brightness: what the light's colour looks like, not how bright it is. */
+export function xyToHex(xy: XY): string {
+  if (xy.y <= 0) return "#000000";
+  const X = xy.x / xy.y;
+  const Z = (1 - xy.x - xy.y) / xy.y;
+  const rgb = [
+    X * 3.2406 - 1.5372 - Z * 0.4986,
+    -X * 0.9689 + 1.8758 + Z * 0.0415,
+    X * 0.0557 - 0.204 + Z * 1.057,
+  ].map((v) => Math.max(0, v));
+  const max = Math.max(...rgb);
+  return `#${rgb
+    .map((v) =>
+      Math.round(255 * Math.min(1, Math.max(0, gamma(max > 0 ? v / max : 0))))
+        .toString(16)
+        .padStart(2, "0"),
+    )
+    .join("")}`;
+}
+
+/** Colour temperature: Hue counts in mirek, a million over the kelvin. 2700 K is 370 mirek. */
+export const kelvinToMirek = (kelvin: number) => Math.round(1e6 / kelvin);
+export const mirekToKelvin = (mirek: number) => Math.round(1e6 / mirek);

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,
@@ -25,13 +25,29 @@ import {
   snapshotFrom,
 } from "./state.ts";
 
+export { HUE_BRIDGE_ROOT_CA } from "./ca.ts";
+export {
+  colorToXy,
+  type Gamut,
+  kelvinToMirek,
+  mirekToKelvin,
+  type Rgb,
+  type XY,
+  xyToHex,
+} from "./color.ts";
 export {
   bunPinnedFetch,
+  CONFIRM_MS,
+  type HueApplied,
+  type HueRequest,
+  type HueWriteOptions,
+  type LightChange,
   type HueClient,
   HueError,
   type HueOptions,
   hueClient,
   pair,
+  pairWhenPressed,
 } from "./client.ts";
 export type { HueEvent, Resource } from "./schemas.ts";
 export {
@@ -54,18 +70,22 @@ export const configSchema = z.looseObject({
   key: envName.describe(
     "env name holding the application key from `home pair`",
   ),
-  ca: filePath.describe("Signify's root CA (PEM), relative to the config file"),
+  ca: filePath
+    .optional()
+    .describe(
+      "a root CA (PEM) to trust instead of Signify's two, which the package carries; relative to the config file",
+    ),
 });
 
 /**
- * Hue settings for a home. Leave out `fetch` in Bun and it pins to `ca` and `bridgeId`; in Node pass a pinned one.
+ * Hue settings for a home. Leave out `fetch` in Bun and it pins to `bridgeId` and `ca` (Signify's roots, `HUE_BRIDGE_ROOT_CA`, when left out); in Node pass a pinned one.
  * `find` (mDNS, matched by `bridgeId`) finds the bridge again after three failed reconnects; `idleMs` is the stream's watchdog.
  */
 export type HueConfig = {
   host: string;
   bridgeId: string;
   key: string;
-  ca: string;
+  ca?: string;
   fetch?: typeof fetch;
   clock?: Clock;
   find?: Finder;
@@ -220,14 +240,26 @@ const view = (s: HueSnapshot) => ({
   })),
 });
 
-/** "Kitchen: on · 40%", "Kitchen: off", or the name alone when the bridge hasn't said. */
-const onText = (v: {
+/** A light, room or zone in a line: "Kitchen: on · 40%", "Desk: on · 40% · 2700 K", "Strip: on · 80% · #ff8800", "Kitchen: off", or the name alone when the bridge hasn't said. */
+export const hueText = (v: {
   name?: string;
   id: string;
   on?: boolean;
   brightness?: number;
-}) =>
-  `${v.name ?? v.id}${v.on === undefined ? "" : `: ${v.on ? `on${v.brightness === undefined ? "" : ` · ${Math.round(v.brightness)}%`}` : "off"}`}`;
+  kelvin?: number;
+  hex?: string;
+}) => {
+  if (v.on === undefined) return v.name ?? v.id;
+  const parts = v.on
+    ? [
+        "on",
+        v.brightness === undefined ? "" : `${Math.round(v.brightness)}%`,
+        // A colour light showing a white reports both; the white is what it is showing.
+        v.kelvin !== undefined ? `${v.kelvin} K` : (v.hex ?? ""),
+      ]
+    : ["off"];
+  return `${v.name ?? v.id}: ${parts.filter(Boolean).join(" · ")}`;
+};
 
 /** A Hue light, or a room or zone, as a home device: `detail` is its `LightView` or `GroupView`. */
 export type HueHomeDevice =
@@ -253,7 +285,7 @@ export function hueHomeDevices(
       ...(l.reachable === undefined ? {} : { available: l.reachable }),
       ...on(l),
       asOf: s.asOf,
-      text: onText(l),
+      text: hueText(l),
       detail: l,
     })),
     ...groups(s).map((g): HueHomeDevice => ({
@@ -263,7 +295,7 @@ export function hueHomeDevices(
       kind: "group",
       ...on(g),
       asOf: s.asOf,
-      text: onText(g),
+      text: hueText(g),
       members: g.lightIds,
       detail: g,
     })),
@@ -296,7 +328,8 @@ export const manifest: Manifest<HueSnapshot> = {
     {
       name: "HUE_CA_FILE",
       example: "/path/to/hue-root-ca.pem",
-      what: "until HUE_BRIDGE_ROOT_CA ships in src/connectors/hue/",
+      optional: true,
+      what: "a root CA to trust instead of Signify's two, which the package carries",
     },
   ],
   files: ["ca"],
@@ -304,7 +337,7 @@ export const manifest: Manifest<HueSnapshot> = {
   lines({ state }) {
     if (!state) return [];
     const { lightsOn } = view(state);
-    return [`${lightsOn} lights on`, ...groups(state).map(onText)];
+    return [`${lightsOn} lights on`, ...groups(state).map(hueText)];
   },
   record: ({ state }) => (state ? view(state) : {}),
 };

package/src/connectors/hue/schemas.ts

@@ -6,6 +6,7 @@ import { z } from "zod";
 // all are optional and unknown fields pass through, so a schema change degrades, never throws.
 
 const ref = z.object({ rid: z.string(), rtype: z.string() });
+const xy = z.looseObject({ x: z.number(), y: z.number() });
 
 /** The resource kinds this library reads. */
 export const KINDS = [
@@ -27,6 +28,31 @@ export const Resource = z.looseObject({
   metadata: z.looseObject({ name: z.string().optional() }).optional(),
   on: z.looseObject({ on: z.boolean() }).optional(),
   dimming: z.looseObject({ brightness: z.number() }).optional(),
+  // A light's colour and the triangle of colours it can show; absent on a white light. A shape this doesn't expect
+  // reads as absent, so one odd light never fails the whole read.
+  color: z
+    .looseObject({
+      xy: xy.optional().catch(undefined),
+      gamut: z
+        .looseObject({ red: xy, green: xy, blue: xy })
+        .optional()
+        .catch(undefined),
+    })
+    .optional()
+    .catch(undefined),
+  // mirek is null while the light shows a colour; the schema is this light's own range.
+  color_temperature: z
+    .looseObject({
+      mirek: z.number().nullable().optional(),
+      mirek_schema: z
+        .looseObject({
+          mirek_minimum: z.number().optional(),
+          mirek_maximum: z.number().optional(),
+        })
+        .optional(),
+    })
+    .optional()
+    .catch(undefined),
   children: z.array(ref).optional(),
   services: z.array(ref).optional(),
   group: ref.optional(), // scene: the room or zone it belongs to

package/src/connectors/hue/state.ts

@@ -1,3 +1,4 @@
+import { type Gamut, mirekToKelvin, type XY, xyToHex } from "./color.ts";
 import type { HueEvent, Resource } from "./schemas.ts";
 
 /** Every resource on the bridge by id, from the last full read plus every event since. `asOf` is local time it was last known fresh. */
@@ -56,9 +57,17 @@ export type LightView = {
   on?: boolean;
   brightness?: number;
   reachable?: boolean;
+  /** White temperature in kelvin, while the light shows a white; its range is `kelvinRange` (warmest, coolest). */
+  kelvin?: number;
+  kelvinRange?: [number, number];
+  /** The colour it shows: the bridge's `xy`, and `hex` for a screen (the hue at full brightness). Colour lights only. */
+  xy?: XY;
+  hex?: string;
+  /** The colours it can show. Present on a colour light, so its presence says "takes a colour". */
+  gamut?: Gamut;
 };
 
-/** Every light, with on, brightness and reachability. */
+/** Every light, with on, brightness, reachability, and its white temperature and colour where it has them. */
 export function lights(s: HueSnapshot): LightView[] {
   const zigbee = ofType(s, "zigbee_connectivity");
   return ofType(s, "light").map((l) => {
@@ -69,10 +78,27 @@ export function lights(s: HueSnapshot): LightView[] {
       on: l.on?.on,
       brightness: l.dimming?.brightness,
       reachable: link ? link.status === "connected" : undefined,
+      ...colorOf(l),
     };
   });
 }
 
+/** A light's temperature and colour fields, only those the bridge reported. */
+function colorOf(l: Resource): Partial<LightView> {
+  const out: Partial<LightView> = {};
+  const ct = l.color_temperature;
+  if (typeof ct?.mirek === "number") out.kelvin = mirekToKelvin(ct.mirek);
+  const { mirek_minimum: min, mirek_maximum: max } = ct?.mirek_schema ?? {};
+  if (min !== undefined && max !== undefined)
+    out.kelvinRange = [mirekToKelvin(max), mirekToKelvin(min)];
+  if (l.color?.xy) {
+    out.xy = l.color.xy;
+    out.hex = xyToHex(l.color.xy);
+  }
+  if (l.color?.gamut) out.gamut = l.color.gamut;
+  return out;
+}
+
 /** A room or zone as a row shows it, with its grouped light's state. */
 export type GroupView = {
   id: string;

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,
+  );