@khalido/home 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,65 @@
+import { z } from "zod";
+/** The resource kinds this library reads. */
+export declare const KINDS: readonly ["light", "room", "zone", "grouped_light", "scene", "bridge_home", "zigbee_connectivity"];
+export type Kind = (typeof KINDS)[number];
+/** One CLIP v2 resource, loosely typed: id and type, plus the optional fields the snapshot uses. */
+export declare const Resource: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    owner: z.ZodOptional<z.ZodObject<{
+        rid: z.ZodString;
+        rtype: z.ZodString;
+    }, z.core.$strip>>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    on: z.ZodOptional<z.ZodObject<{
+        on: z.ZodBoolean;
+    }, z.core.$loose>>;
+    dimming: z.ZodOptional<z.ZodObject<{
+        brightness: z.ZodNumber;
+    }, z.core.$loose>>;
+    children: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        rid: z.ZodString;
+        rtype: z.ZodString;
+    }, z.core.$strip>>>;
+    services: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        rid: z.ZodString;
+        rtype: z.ZodString;
+    }, z.core.$strip>>>;
+    group: z.ZodOptional<z.ZodObject<{
+        rid: z.ZodString;
+        rtype: z.ZodString;
+    }, z.core.$strip>>;
+    status: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$loose>;
+export type Resource = z.infer<typeof Resource>;
+/** The CLIP v2 response envelope: `{ errors, data }`. */
+export declare const Envelope: z.ZodObject<{
+    errors: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+    }, z.core.$strip>>>;
+    data: z.ZodDefault<z.ZodArray<z.ZodUnknown>>;
+}, z.core.$strip>;
+/** One event-stream batch. `data` holds partial resources: only the fields that changed. */
+export declare const HueEvent: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    creationtime: z.ZodString;
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
+export type HueEvent = z.infer<typeof HueEvent>;
+/** `POST /api` answers with a one-element array holding `success` or `error` (v1 shape). */
+export declare const PairResponse: z.ZodArray<z.ZodObject<{
+    success: z.ZodOptional<z.ZodObject<{
+        username: z.ZodString;
+        clientkey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    error: z.ZodOptional<z.ZodObject<{
+        type: z.ZodNumber;
+        description: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;

package/dist/connectors/hue/schemas.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+// Shapes from Signify's CLIP v2, checked against openhue-api's OpenAPI spec (Apache-2.0,
+// github.com/openhue/openhue-api, 2026-10). Signify's own reference is login-gated, so every
+// field is unconfirmed from the primary source. Only the fields the snapshot reads are parsed;
+// 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() });
+/** The resource kinds this library reads. */
+export const KINDS = [
+    "light",
+    "room",
+    "zone",
+    "grouped_light",
+    "scene",
+    "bridge_home",
+    "zigbee_connectivity",
+];
+/** One CLIP v2 resource, loosely typed: id and type, plus the optional fields the snapshot uses. */
+export const Resource = z.looseObject({
+    id: z.string(),
+    type: z.string(),
+    owner: ref.optional(),
+    metadata: z.looseObject({ name: z.string().optional() }).optional(),
+    on: z.looseObject({ on: z.boolean() }).optional(),
+    dimming: z.looseObject({ brightness: z.number() }).optional(),
+    children: z.array(ref).optional(),
+    services: z.array(ref).optional(),
+    group: ref.optional(), // scene: the room or zone it belongs to
+    status: z.unknown().optional(), // scene: { active }; zigbee_connectivity: "connected" | …
+});
+/** The CLIP v2 response envelope: `{ errors, data }`. */
+export const Envelope = z.object({
+    errors: z.array(z.object({ description: z.string() })).default([]),
+    data: z.array(z.unknown()).default([]),
+});
+/** One event-stream batch. `data` holds partial resources: only the fields that changed. */
+export const HueEvent = z.object({
+    id: z.string(),
+    type: z.string(), // "add" | "update" | "delete" | "error"; anything newer is ignored, not fatal
+    creationtime: z.string(),
+    data: z.array(z.looseObject({ id: z.string(), type: z.string() })),
+});
+/** `POST /api` answers with a one-element array holding `success` or `error` (v1 shape). */
+export const PairResponse = z.array(z.object({
+    success: z
+        .object({ username: z.string(), clientkey: z.string().optional() })
+        .optional(),
+    error: z.object({ type: z.number(), description: z.string() }).optional(),
+}));

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

@@ -0,0 +1,43 @@
+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 declare function snapshotFrom(resources: Resource[], asOf: string): HueSnapshot;
+/** Apply one event batch. Pure: returns a new snapshot. Updates carry only changed fields, so they merge; unknown types are ignored. */
+export declare function reduce(snapshot: HueSnapshot, event: HueEvent): HueSnapshot;
+/** 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 declare function lights(s: HueSnapshot): LightView[];
+/** 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 declare function groups(s: HueSnapshot): GroupView[];
+/** The grouped light for the whole home: one PUT `{ on: { on: false } }` to it is "Lights off". */
+export declare function homeGroupedLightId(s: HueSnapshot): string | undefined;
+/** Scenes with their room or zone and whether one is active (`status.active` other than "inactive"). */
+export declare function scenes(s: HueSnapshot): {
+    id: string;
+    name: string | undefined;
+    groupId: string | undefined;
+    active: boolean;
+}[];

package/dist/connectors/hue/state.js

@@ -0,0 +1,84 @@
+/** A snapshot from one full `get()`. */
+export function snapshotFrom(resources, asOf) {
+    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, event) {
+    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);
+    }
+    return { ...snapshot, resources };
+}
+const isPlain = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function merge(a, b) {
+    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, type) => Object.values(s.resources).filter((r) => r.type === type);
+const groupedLightOf = (s, r) => r.services
+    ?.map((x) => s.resources[x.rid])
+    .find((x) => x?.type === "grouped_light");
+/** Every light, with on, brightness and reachability. */
+export function lights(s) {
+    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,
+        };
+    });
+}
+/** Rooms and zones. A room's children are devices; a zone's are lights. */
+export function groups(s) {
+    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,
+            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) {
+    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) {
+    return ofType(s, "scene").map((sc) => {
+        const active = sc.status?.active;
+        return {
+            id: sc.id,
+            name: sc.metadata?.name,
+            groupId: sc.group?.rid,
+            active: active !== undefined && active !== "inactive",
+        };
+    });
+}

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

@@ -0,0 +1,28 @@
+import { type IppMessage } from "./codec.ts";
+/** Everything the integration reads from one printer. */
+export declare const REQUESTED: string[];
+/** 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 declare 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 declare function printerUrl(a: PrinterAddress): {
+    http: string;
+    ipp: string;
+    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?: {
+    requestId?: number;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<IppMessage>;

package/dist/connectors/printers/client.js

@@ -0,0 +1,74 @@
+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.
+/** 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",
+];
+/** 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) {
+    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 = {
+    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, address, 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),
+    }, 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/dist/connectors/printers/codec.d.ts

@@ -0,0 +1,76 @@
+/** Delimiter tags open a group; value tags (0x10 and up) carry one value. Only the ones this package reads or writes are named. */
+export declare const TAG: {
+    readonly operation: 1;
+    readonly job: 2;
+    readonly end: 3;
+    readonly printer: 4;
+    readonly unsupported: 5;
+    readonly integer: 33;
+    readonly boolean: 34;
+    readonly enum: 35;
+    readonly octetString: 48;
+    readonly dateTime: 49;
+    readonly resolution: 50;
+    readonly rangeOfInteger: 51;
+    readonly begCollection: 52;
+    readonly endCollection: 55;
+    readonly textWithoutLanguage: 65;
+    readonly nameWithoutLanguage: 66;
+    readonly keyword: 68;
+    readonly uri: 69;
+    readonly uriScheme: 70;
+    readonly charset: 71;
+    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. */
+export declare const OPERATION: {
+    readonly getPrinterAttributes: 11;
+};
+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;
+};
+/** 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 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 declare function decodeMessage(bytes: Uint8Array): IppMessage;
+/** Every attribute of the groups with this tag (default: the printer's), by name, repeats merged. */
+export declare function attributesOf(m: IppMessage, groupTag?: number): Record<string, IppValue[]>;

package/dist/connectors/printers/codec.js

@@ -0,0 +1,246 @@
+// 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,
+};
+/** The operation ids this package sends. Identify-Printer (0x003C) and Print-Job (0x0002) are the writes that come later. */
+export const OPERATION = { getPrinterAttributes: 0x000b };
+const STRING_TAGS = new Set([
+    TAG.textWithoutLanguage,
+    TAG.nameWithoutLanguage,
+    TAG.keyword,
+    TAG.uri,
+    TAG.uriScheme,
+    TAG.charset,
+    TAG.naturalLanguage,
+    TAG.mimeMediaType,
+]);
+const utf8 = new TextEncoder();
+const text = new TextDecoder();
+const u16 = (n) => [(n >> 8) & 255, n & 255];
+const u32 = (n) => [
+    (n >>> 24) & 255,
+    (n >>> 16) & 255,
+    (n >>> 8) & 255,
+    n & 255,
+];
+function encodeValue(tag, value) {
+    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.lower),
+            ...u32(value.upper),
+        ];
+    if (tag === TAG.resolution) {
+        const r = value;
+        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) {
+    const out = [...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, requested, requestId = 1) {
+    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) => {
+    throw new Error(`ipp: ${why}`);
+};
+function decodeValue(tag, bytes) {
+    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) => 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) {
+    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) => 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 = [];
+    let group;
+    let last;
+    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;
+        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, groupTag = TAG.printer) {
+    const out = {};
+    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/dist/connectors/printers/found.d.ts

@@ -0,0 +1,15 @@
+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>;
+};
+/**
+ * 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 declare function printersFound(ipp: Answer[], ipps: Answer[]): Found[];