@khalido/home 0.0.0-stage → 0.1.0

package/src/connectors/hue/state.ts

@@ -0,0 +1,124 @@
+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. */
+export type HueSnapshot = {
+  resources: Record<string, Resource>;
+  asOf: string;
+  lastEventId?: string;
+  lastError?: HueEvent;
+};
+
+/** A snapshot from one full `get()`. */
+export function snapshotFrom(resources: Resource[], asOf: string): HueSnapshot {
+  return {
+    resources: Object.fromEntries(resources.map((r) => [r.id, r])),
+    asOf,
+  };
+}
+
+/** Apply one event batch. Pure: returns a new snapshot. Updates carry only changed fields, so they merge; unknown types are ignored. */
+export function reduce(snapshot: HueSnapshot, event: HueEvent): HueSnapshot {
+  if (event.type === "error") return { ...snapshot, lastError: event };
+  if (!["add", "update", "delete"].includes(event.type)) return snapshot;
+  const resources = { ...snapshot.resources };
+  for (const item of event.data) {
+    const prev = resources[item.id];
+    if (event.type === "delete") delete resources[item.id];
+    else
+      resources[item.id] = (
+        event.type === "update" && prev ? merge(prev, item) : item
+      ) as Resource;
+  }
+  return { ...snapshot, resources };
+}
+
+type Plain = Record<string, unknown>;
+const isPlain = (v: unknown): v is Plain =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+function merge(a: Plain, b: Plain): Plain {
+  const out = { ...a };
+  for (const [k, v] of Object.entries(b))
+    out[k] = isPlain(v) && isPlain(a[k]) ? merge(a[k], v) : v;
+  return out;
+}
+
+const ofType = (s: HueSnapshot, type: string) =>
+  Object.values(s.resources).filter((r) => r.type === type);
+const groupedLightOf = (s: HueSnapshot, r: Resource) =>
+  r.services
+    ?.map((x) => s.resources[x.rid])
+    .find((x) => x?.type === "grouped_light");
+
+/** A light as a row shows it. `reachable` is undefined when the bridge has no connectivity record for it. */
+export type LightView = {
+  id: string;
+  name?: string;
+  on?: boolean;
+  brightness?: number;
+  reachable?: boolean;
+};
+
+/** Every light, with on, brightness and reachability. */
+export function lights(s: HueSnapshot): LightView[] {
+  const zigbee = ofType(s, "zigbee_connectivity");
+  return ofType(s, "light").map((l) => {
+    const link = zigbee.find((z) => z.owner?.rid === l.owner?.rid);
+    return {
+      id: l.id,
+      name: l.metadata?.name,
+      on: l.on?.on,
+      brightness: l.dimming?.brightness,
+      reachable: link ? link.status === "connected" : undefined,
+    };
+  });
+}
+
+/** A room or zone as a row shows it, with its grouped light's state. */
+export type GroupView = {
+  id: string;
+  type: "room" | "zone";
+  name?: string;
+  groupedLightId?: string;
+  on?: boolean;
+  brightness?: number;
+  lightIds: string[];
+};
+
+/** Rooms and zones. A room's children are devices; a zone's are lights. */
+export function groups(s: HueSnapshot): GroupView[] {
+  const all = ofType(s, "light");
+  return [...ofType(s, "room"), ...ofType(s, "zone")].map((g) => {
+    const kids = new Set(g.children?.map((c) => c.rid));
+    const grouped = groupedLightOf(s, g);
+    return {
+      id: g.id,
+      type: g.type as "room" | "zone",
+      name: g.metadata?.name,
+      groupedLightId: grouped?.id,
+      on: grouped?.on?.on,
+      brightness: grouped?.dimming?.brightness,
+      lightIds: all
+        .filter((l) => kids.has(l.id) || kids.has(l.owner?.rid ?? ""))
+        .map((l) => l.id),
+    };
+  });
+}
+
+/** The grouped light for the whole home: one PUT `{ on: { on: false } }` to it is "Lights off". */
+export function homeGroupedLightId(s: HueSnapshot): string | undefined {
+  const home = ofType(s, "bridge_home")[0];
+  return home && groupedLightOf(s, home)?.id;
+}
+
+/** Scenes with their room or zone and whether one is active (`status.active` other than "inactive"). */
+export function scenes(s: HueSnapshot) {
+  return ofType(s, "scene").map((sc) => {
+    const active = (sc.status as { active?: string } | undefined)?.active;
+    return {
+      id: sc.id,
+      name: sc.metadata?.name,
+      groupId: sc.group?.rid,
+      active: active !== undefined && active !== "inactive",
+    };
+  });
+}

package/src/connectors/printers/README.md

@@ -0,0 +1,46 @@
+# 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; **untried on a live printer** (the Brother KO has did not answer mDNS on 2026-10-14, see Live findings).
+
+Try it: `home printers`
+
+## Built
+
+- `printers({ printers, fetch, find, seen })` keeps every printer current as one integration. A config entry per printer (`uuid`, `name`, last known `host` and `port`, `room`, `offlineDays`); discovery adds any AirPrint printer the config does not list.
+- Per poll: one `POST` to each printer. The snapshot (`PrintersState`) holds one `Printer` per UUID (lowercase, no dashes): `name`, `model`, `host`, `state` (`idle`, `printing`, `stopped`, `offline`), `stateCode`, `reasons`, `message`, `markers` (`name`, `level`, `type`, `color`), `media` (`media-ready`), `queuedJobs`, `acceptingJobs`, `formats`, `ippVersions`, `alerts`, `ipps`, `lastSeen`, `asOf`, `detail`, `anomaly`.
+- **Offline.** An unreachable printer stays in the snapshot as `offline`, keeping its last good values and `lastSeen`. The part is `connected` while any printer answers and `disconnected` otherwise, never `unavailable` for being unreachable (printers go on and off). After `offlineDays` (default 14) without an answer the entry says so in `anomaly`; after a day its `detail` says "no answer for a day". `lastSeen` lives in memory: a restart starts the count again.
+- **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`.
+
+## Protocol
+
+IPP is a binary message in an HTTP `POST` with `content-type: application/ipp`, to `http://host:port/<rp>`; `ipps` is the same over TLS. The path `rp` is TXT `rp` (most printers: `ipp/print`; the default here). The request names the printer by an `ipp://` or `ipps://` URI.
+
+The Get-Printer-Attributes request (`codec.ts`), RFC 8010 section 3: version 2.0, operation `0x000B`, a request id, then the operation-attributes group with `attributes-charset` `utf-8`, `attributes-natural-language` `en`, `printer-uri`, and `requested-attributes`: `printer-state`, `printer-state-reasons`, `printer-state-message`, `marker-names`, `marker-levels`, `marker-types`, `marker-colors`, `media-ready`, `queued-job-count`, `printer-alert`, `printer-make-and-model`, `printer-uuid`, `document-format-supported`, `ipp-versions-supported`, `printer-is-accepting-jobs`.
+
+The codec is about 200 lines by hand, like Cast's, in place of the `ipp` npm package. It decodes integer, enum, boolean, every string tag, dateTime, resolution, rangeOfInteger and octetString; any other tag, a wrong length for a known tag, and a whole collection (skipped by depth) come back as `{ tag, bytes }`, never thrown. Only a message cut short throws. A response status of `0x0100` or more, or a non-2xx HTTP status, is a `ConnectorError` naming it.
+
+Discovery is mDNS `_ipp._tcp` and `_ipps._tcp` ([Apple's AirPrint TXT keys](https://developer.apple.com/bonjour/printing-specification/bonjourprinting-1.2.pdf)): `UUID` is the identity (the instance name when absent), `ty` the name and model, `rp` the path; `pdl`, `URF`, `product`, `adminurl` and `note` are kept in the found record's `txt`. A printer on both types is one entry, the plain `_ipp._tcp` one, so a self-signed certificate on `_ipps._tcp` never decides; a printer on `_ipps._tcp` alone is read over TLS.
+
+**TLS.** Printers sign their own certificates. `fetch` verifies them, and the read fails with its error in `detail`; nothing here turns verification off. If a printer only speaks IPPS, the fix is the caller's `fetch` (pin the certificate, as Hue's does), not this package's.
+
+**Node.** Node's `fetch` refuses port 631 (it is on the WHATWG bad-port list, as IPP's well-known port). Bun does not. A Node caller would need a `fetch` that allows it, or the IPPS entry on 443. Not tried.
+
+## 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.
+
+## Live findings
+
+None yet. 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).
+
+## Sources
+
+- [RFC 8010](https://www.rfc-editor.org/rfc/rfc8010) (IPP/1.1: Encoding and Transport) and [RFC 8011](https://www.rfc-editor.org/rfc/rfc8011) (Model and Semantics): the layout, the tags, `Get-Printer-Attributes`, `printer-state`. IETF documents; facts and layouts used, no text copied.
+- [PWG 5100.13](https://ftp.pwg.org/pub/pwg/candidates/cs-ippjobprinterext3v10-20120727-5100.13.pdf) (IPP Job and Printer Extensions Set 3): `marker-*`. [PWG 5101.1](https://ftp.pwg.org/pub/pwg/candidates/cs-pwgmsn20-20130328-5101.1.pdf): media keywords such as `iso_a4_210x297mm`. PWG documents, facts only.
+- [CUPS](https://www.cups.org/doc/spec-ipp.html) documentation of the IPP attributes it uses (Apache-2.0 with exceptions); read, not copied.
+- Home Assistant's [`ipp` integration](https://www.home-assistant.io/integrations/ipp/) (Apache-2.0) and its library [pyipp](https://github.com/ctalkington/python-ipp) (MIT): read for which attributes to ask for and how states and markers are interpreted.
+- Apple's [Bonjour Printing Specification](https://developer.apple.com/bonjour/printing-specification/) for the TXT keys.
+- The fixture (`test/fixtures/printers/get-printer-attributes.hex`) is an invented printer built with this codec: documentation-style values, a made-up UUID, nothing from a real device.

package/src/connectors/printers/client.ts

@@ -0,0 +1,114 @@
+import { ConnectorError, fetchTimeout } from "../../connector.ts";
+import {
+  attributesOf,
+  decodeMessage,
+  getPrinterAttributesRequest,
+  type IppMessage,
+} 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.
+
+/** Everything the integration reads from one printer. */
+export const REQUESTED = [
+  "printer-state",
+  "printer-state-reasons",
+  "printer-state-message",
+  "marker-names",
+  "marker-levels",
+  "marker-types",
+  "marker-colors",
+  "media-ready",
+  "queued-job-count",
+  "printer-alert",
+  "printer-make-and-model",
+  "printer-uuid",
+  "document-format-supported",
+  "ipp-versions-supported",
+  "printer-is-accepting-jobs",
+];
+
+/** Where a printer answers: IPP is HTTP POST to `/<rp>`; port 443 (or a found `_ipps._tcp`) is TLS. */
+export type PrinterAddress = {
+  host: string;
+  port?: number;
+  rp?: string;
+  secure?: boolean;
+};
+
+/** Most printers answer on this path (IPP Everywhere); the TXT `rp` says when theirs differs. */
+export const DEFAULT_RP = "ipp/print";
+
+/** The URL to POST to and the `ipp(s)://` URI the request names. A TXT `rp` may or may not start with a slash. */
+export function printerUrl(a: PrinterAddress): {
+  http: string;
+  ipp: string;
+  secure: boolean;
+  path: string;
+} {
+  const secure = a.secure ?? a.port === 443;
+  const port = a.port ?? (secure ? 443 : 631);
+  const path = (a.rp || DEFAULT_RP).replace(/^\/+/, "");
+  const host = a.host.includes(":") ? `[${a.host}]` : a.host;
+  return {
+    http: `${secure ? "https" : "http"}://${host}:${port}/${path}`,
+    ipp: `${secure ? "ipps" : "ipp"}://${host}:${port}/${path}`,
+    secure,
+    path,
+  };
+}
+
+/** A few status codes by name, for the error text; any other shows as hex. */
+const STATUS: Record<number, string> = {
+  0x0400: "client-error-bad-request",
+  0x0401: "client-error-forbidden",
+  0x0402: "client-error-not-authenticated",
+  0x0403: "client-error-not-authorized",
+  0x0404: "client-error-not-possible",
+  0x0406: "client-error-not-found",
+  0x040a: "client-error-document-format-not-supported",
+  0x0500: "server-error-internal-error",
+  0x0501: "server-error-operation-not-supported",
+  0x0503: "server-error-service-unavailable",
+  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.
+ */
+export async function getPrinterAttributes(
+  fetcher: typeof fetch,
+  address: PrinterAddress,
+  options: {
+    requestId?: number;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+  } = {},
+): Promise<IppMessage> {
+  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),
+    },
+    options,
+  );
+  if (!res.ok)
+    throw new ConnectorError(`HTTP ${res.status} on POST /${url.path}`, {
+      status: res.status,
+    });
+  const message = decodeMessage(new Uint8Array(await res.arrayBuffer()));
+  if (message.code >= 0x0100) {
+    const why = attributesOf(message, 1)["status-message"]?.[0];
+    throw new ConnectorError(
+      `IPP ${STATUS[message.code] ?? `status 0x${message.code.toString(16).padStart(4, "0")}`}${typeof why === "string" ? `: ${why}` : ""}`,
+      { status: message.code, code: "ipp" },
+    );
+  }
+  return message;
+}

package/src/connectors/printers/codec.ts

@@ -0,0 +1,292 @@
+// IPP's binary encoding (RFC 8010) by hand, enough for Get-Printer-Attributes: a request out, a response in. A message is
+// version (2 bytes), operation or status code (2), request id (4), then attribute groups, then 0x03, then any document data.
+// Each attribute is a value tag, a name (length + bytes) and a value (length + bytes); a further value of the same attribute
+// repeats the tag with a zero-length name. Both directions share the one layout, so one encoder and one decoder.
+
+/** Delimiter tags open a group; value tags (0x10 and up) carry one value. Only the ones this package reads or writes are named. */
+export const TAG = {
+  operation: 0x01,
+  job: 0x02,
+  end: 0x03,
+  printer: 0x04,
+  unsupported: 0x05,
+  integer: 0x21,
+  boolean: 0x22,
+  enum: 0x23,
+  octetString: 0x30,
+  dateTime: 0x31,
+  resolution: 0x32,
+  rangeOfInteger: 0x33,
+  begCollection: 0x34,
+  endCollection: 0x37,
+  textWithoutLanguage: 0x41,
+  nameWithoutLanguage: 0x42,
+  keyword: 0x44,
+  uri: 0x45,
+  uriScheme: 0x46,
+  charset: 0x47,
+  naturalLanguage: 0x48,
+  mimeMediaType: 0x49,
+} as const;
+
+/** The operation ids this package sends. Identify-Printer (0x003C) and Print-Job (0x0002) are the writes that come later. */
+export const OPERATION = { getPrinterAttributes: 0x000b } as const;
+
+const STRING_TAGS: ReadonlySet<number> = new Set([
+  TAG.textWithoutLanguage,
+  TAG.nameWithoutLanguage,
+  TAG.keyword,
+  TAG.uri,
+  TAG.uriScheme,
+  TAG.charset,
+  TAG.naturalLanguage,
+  TAG.mimeMediaType,
+]);
+
+export type IppRange = { lower: number; upper: number };
+export type IppResolution = {
+  x: number;
+  y: number;
+  units: "dpi" | "dpcm" | number;
+};
+/** A value whose tag this decoder does not read (a language-tagged string, a collection, an out-of-band marker), or whose length is wrong for its tag: the bytes, unchanged. */
+export type IppUnknown = { tag: number; bytes: Uint8Array };
+/**
+ * One decoded value. Integers and enums are numbers; every string tag is a string; a dateTime is an ISO 8601 string with
+ * its offset; an octetString is bytes. A collection decodes to one `IppUnknown` with no bytes, its members skipped.
+ */
+export type IppValue =
+  | number
+  | boolean
+  | string
+  | Uint8Array
+  | IppRange
+  | IppResolution
+  | IppUnknown;
+
+export type IppAttribute = { name: string; tag: number; values: IppValue[] };
+export type IppGroup = { tag: number; attributes: IppAttribute[] };
+/** A request or a response: `code` is the operation id of a request or the status code of a response. */
+export type IppMessage = {
+  version: [number, number];
+  code: number;
+  requestId: number;
+  groups: IppGroup[];
+  data?: Uint8Array;
+};
+
+const utf8 = new TextEncoder();
+const text = new TextDecoder();
+
+const u16 = (n: number) => [(n >> 8) & 255, n & 255];
+const u32 = (n: number) => [
+  (n >>> 24) & 255,
+  (n >>> 16) & 255,
+  (n >>> 8) & 255,
+  n & 255,
+];
+
+function encodeValue(tag: number, value: IppValue): number[] {
+  if (STRING_TAGS.has(tag)) return [...utf8.encode(String(value))];
+  if (tag === TAG.integer || tag === TAG.enum) return u32(Number(value));
+  if (tag === TAG.boolean) return [value ? 1 : 0];
+  if (tag === TAG.rangeOfInteger)
+    return [
+      ...u32((value as IppRange).lower),
+      ...u32((value as IppRange).upper),
+    ];
+  if (tag === TAG.resolution) {
+    const r = value as IppResolution;
+    return [
+      ...u32(r.x),
+      ...u32(r.y),
+      r.units === "dpi" ? 3 : r.units === "dpcm" ? 4 : Number(r.units),
+    ];
+  }
+  if (tag === TAG.dateTime) {
+    const m = String(value).match(
+      /^(\d{4})-(\d\d)-(\d\d)T(\d\d):(\d\d):(\d\d)\.(\d)([+-])(\d\d):(\d\d)$/,
+    );
+    if (!m)
+      throw new Error(
+        `ipp: a dateTime is YYYY-MM-DDTHH:MM:SS.d+HH:MM, got ${String(value)}`,
+      );
+    const n = m.slice(1).map((x, i) => (i === 7 ? x.charCodeAt(0) : Number(x)));
+    return [...u16(n[0]!), ...n.slice(1)];
+  }
+  if (value instanceof Uint8Array) return [...value];
+  if (typeof value === "object" && "bytes" in value) return [...value.bytes];
+  throw new Error(`ipp: cannot encode tag 0x${tag.toString(16)}`);
+}
+
+/** A message as bytes. Collections are not encoded (a Get-Printer-Attributes request has none). */
+export function encodeMessage(m: IppMessage): Uint8Array<ArrayBuffer> {
+  const out: number[] = [...m.version, ...u16(m.code), ...u32(m.requestId)];
+  for (const g of m.groups) {
+    out.push(g.tag);
+    for (const a of g.attributes)
+      a.values.forEach((v, i) => {
+        const name = i === 0 ? utf8.encode(a.name) : new Uint8Array();
+        const value = encodeValue(a.tag, v);
+        out.push(
+          a.tag,
+          ...u16(name.length),
+          ...name,
+          ...u16(value.length),
+          ...value,
+        );
+      });
+  }
+  out.push(TAG.end);
+  return Uint8Array.from([...out, ...(m.data ?? [])]);
+}
+
+/** The Get-Printer-Attributes request: IPP 2.0, utf-8, English, the printer's `ipp://` URI, and the attributes wanted. */
+export function getPrinterAttributesRequest(
+  printerUri: string,
+  requested: string[],
+  requestId = 1,
+): Uint8Array<ArrayBuffer> {
+  return encodeMessage({
+    version: [2, 0],
+    code: OPERATION.getPrinterAttributes,
+    requestId,
+    groups: [
+      {
+        tag: TAG.operation,
+        attributes: [
+          { name: "attributes-charset", tag: TAG.charset, values: ["utf-8"] },
+          {
+            name: "attributes-natural-language",
+            tag: TAG.naturalLanguage,
+            values: ["en"],
+          },
+          { name: "printer-uri", tag: TAG.uri, values: [printerUri] },
+          { name: "requested-attributes", tag: TAG.keyword, values: requested },
+        ],
+      },
+    ],
+  });
+}
+
+const fail = (why: string): never => {
+  throw new Error(`ipp: ${why}`);
+};
+
+function decodeValue(tag: number, bytes: Uint8Array): IppValue {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.length);
+  const unknown = { tag, bytes };
+  if (STRING_TAGS.has(tag)) return text.decode(bytes);
+  if (tag === TAG.octetString) return bytes;
+  if (tag === TAG.integer || tag === TAG.enum)
+    return bytes.length === 4 ? view.getInt32(0) : unknown;
+  if (tag === TAG.boolean) return bytes.length === 1 ? bytes[0] !== 0 : unknown;
+  if (tag === TAG.rangeOfInteger)
+    return bytes.length === 8
+      ? { lower: view.getInt32(0), upper: view.getInt32(4) }
+      : unknown;
+  if (tag === TAG.resolution) {
+    if (bytes.length !== 9) return unknown;
+    const units = bytes[8]!;
+    return {
+      x: view.getInt32(0),
+      y: view.getInt32(4),
+      units: units === 3 ? "dpi" : units === 4 ? "dpcm" : units,
+    };
+  }
+  if (tag === TAG.dateTime) {
+    if (bytes.length !== 11) return unknown;
+    const p = (n: number) => String(n).padStart(2, "0");
+    const [mo, d, h, mi, s, ds, dir, uh, um] = [2, 3, 4, 5, 6, 7, 8, 9, 10].map(
+      (i) => bytes[i]!,
+    );
+    return `${view.getUint16(0)}-${p(mo!)}-${p(d!)}T${p(h!)}:${p(mi!)}:${p(s!)}.${ds}${String.fromCharCode(dir!)}${p(uh!)}:${p(um!)}`;
+  }
+  return unknown;
+}
+
+/**
+ * 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.
+ */
+export function decodeMessage(bytes: Uint8Array): IppMessage {
+  if (bytes.length < 9) fail("a message is at least 9 bytes");
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.length);
+  let i = 8;
+  const need = (n: number) =>
+    i + n <= bytes.length || fail("the message is cut short");
+  /** One attribute element at `i`: tag, name, value bytes. */
+  const element = () => {
+    need(3);
+    const tag = bytes[i++]!;
+    const nameLength = view.getUint16(i);
+    i += 2;
+    need(nameLength + 2);
+    const name = text.decode(bytes.subarray(i, i + nameLength));
+    i += nameLength;
+    const valueLength = view.getUint16(i);
+    i += 2;
+    need(valueLength);
+    const value = bytes.subarray(i, i + valueLength);
+    i += valueLength;
+    return { tag, name, value };
+  };
+  const groups: IppGroup[] = [];
+  let group: IppGroup | undefined;
+  let last: IppAttribute | undefined;
+  for (;;) {
+    need(1);
+    const tag = bytes[i]!;
+    if (tag === TAG.end) {
+      i++;
+      break;
+    }
+    if (tag < 0x10) {
+      i++;
+      groups.push((group = { tag, attributes: [] }));
+      last = undefined;
+      continue;
+    }
+    const e = element();
+    let value: IppValue;
+    if (e.tag === TAG.begCollection) {
+      for (let depth = 1; depth > 0;) {
+        const inner = element();
+        if (inner.tag === TAG.begCollection) depth++;
+        else if (inner.tag === TAG.endCollection) depth--;
+      }
+      value = { tag: e.tag, bytes: new Uint8Array() };
+    } else value = decodeValue(e.tag, e.value.slice());
+    if (!group) fail("an attribute before any group");
+    if (e.name === "") {
+      if (!last) fail("a further value before any attribute");
+      last!.values.push(value);
+    } else {
+      last = group!.attributes.find((a) => a.name === e.name);
+      if (last) last.values.push(value);
+      else
+        group!.attributes.push(
+          (last = { name: e.name, tag: e.tag, values: [value] }),
+        );
+    }
+  }
+  return {
+    version: [bytes[0]!, bytes[1]!],
+    code: view.getUint16(2),
+    requestId: view.getUint32(4),
+    groups,
+    ...(i < bytes.length ? { data: bytes.slice(i) } : {}),
+  };
+}
+
+/** Every attribute of the groups with this tag (default: the printer's), by name, repeats merged. */
+export function attributesOf(
+  m: IppMessage,
+  groupTag: number = TAG.printer,
+): Record<string, IppValue[]> {
+  const out: Record<string, IppValue[]> = {};
+  for (const g of m.groups)
+    if (g.tag === groupTag)
+      for (const a of g.attributes) (out[a.name] ??= []).push(...a.values);
+  return out;
+}

package/src/connectors/printers/found.ts

@@ -0,0 +1,46 @@
+import type { Found } from "../../discover.ts";
+
+/** One resolved mDNS instance, as `mdnsResolve` in src/finders.ts returns it. */
+export type Answer = {
+  host: string;
+  port: number;
+  instance: string;
+  txt: Record<string, string>;
+};
+
+/** TXT keys are case-insensitive in DNS-SD; AirPrint's are written `UUID`, `ty`, `rp`. */
+const lower = (txt: Record<string, string>) =>
+  Object.fromEntries(Object.entries(txt).map(([k, v]) => [k.toLowerCase(), v]));
+
+/**
+ * AirPrint printers as found devices: the identity is TXT `UUID` (the instance name when absent), the name TXT `ty` (else
+ * the instance name), the model `ty`. `txt` keeps the whole record for the connector (`rp`, `pdl`, `URF`, `product`,
+ * `adminurl`, `note`). A printer on both types is one entry, the plain `_ipp._tcp` one (`ipp` listed first), so a
+ * self-signed certificate on `_ipps._tcp` never decides; a printer on `_ipps._tcp` alone is `secure`.
+ */
+export function printersFound(ipp: Answer[], ipps: Answer[]): Found[] {
+  const seen = new Set<string>();
+  const out: Found[] = [];
+  for (const [secure, answers] of [
+    [false, ipp],
+    [true, ipps],
+  ] as const)
+    for (const a of answers) {
+      const txt = lower(a.txt);
+      const id = txt.uuid || a.instance;
+      const key = id.toLowerCase().replace(/[^0-9a-z]/g, "");
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({
+        connector: "printers",
+        id,
+        host: a.host,
+        port: a.port,
+        name: txt.ty || a.instance,
+        model: txt.ty,
+        secure,
+        txt,
+      });
+    }
+  return out;
+}