@houwert/conductor 0.29.2 → 0.30.0

package/dist/drivers/roku/app-ui-parser.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRokuAppUI = parseRokuAppUI;
+/**
+ * Converts Roku's ECP `/query/app-ui` SceneGraph XML into the uiautomator-style
+ * `<node>` XML that conductor's Android element resolver (`parseAndroidHierarchy`,
+ * `findAndroidElement`, `inspectAndroidToText`) already understands — the same
+ * trick Vega uses, so Roku reuses the entire inspection and element-resolution path.
+ *
+ * app-ui shape:
+ * ```
+ * <app-ui>
+ *   <status>OK</status>
+ *   <topscreen>
+ *     <plugin id="dev" name="MyApp"/>
+ *     <screen focused="true" type="screen">
+ *       <RenderableNode name="myId" subtype="Group" bounds="{0, 0, 1920, 1080}" …>
+ * ```
+ * Node `name` attributes (SceneGraph node ids) become `resource-id`, `subtype`
+ * becomes `class`, and `bounds` are accumulated with parent `translation` offsets
+ * into scene-absolute `[x1,y1][x2,y2]` rects — the Android adapter's format.
+ */
+const xml_js_1 = require("../xml.js");
+const EMPTY = '<?xml version="1.0" encoding="UTF-8"?>\n<hierarchy />';
+/** Parse Roku app-ui XML and re-emit it as uiautomator `<node>` XML. */
+function parseRokuAppUI(xml, screenWidth = 1920, screenHeight = 1080) {
+    const root = (0, xml_js_1.parseXml)(xml);
+    if (!root)
+        return EMPTY;
+    const topscreen = (0, xml_js_1.childElement)(root, 'topscreen');
+    const screen = topscreen && (0, xml_js_1.childElement)(topscreen, 'screen');
+    if (!screen)
+        return EMPTY;
+    const lines = ['<?xml version="1.0" encoding="UTF-8"?>', '<hierarchy>'];
+    // A root node spanning the screen: it gives the screenshot cropper its reference
+    // bounds, matching the window node Android and Vega both emit.
+    // Never focused: `<screen focused>` means the screen holds device focus, not that
+    // it is the focused element, and claiming it here would shadow the real one.
+    const rootAttrs = [
+        'class="Screen"',
+        `bounds="[0,0][${screenWidth},${screenHeight}]"`,
+        'clickable="false"',
+        'focusable="false"',
+        'focused="false"',
+        'enabled="true"',
+    ];
+    lines.push(`  <node ${rootAttrs.join(' ')}>`);
+    emitChildren(screen, { x: 0, y: 0 }, false, lines, 2);
+    lines.push('  </node>');
+    lines.push('</hierarchy>');
+    return lines.join('\n');
+}
+function emitChildren(parent, offset, parentIsRowListItem, lines, depth) {
+    // A RowListItem's trailing Group duplicates the item it wraps.
+    const children = parentIsRowListItem && parent.children.length > 1
+        ? parent.children.slice(0, -1)
+        : parent.children;
+    for (const child of children)
+        emitNode(child, offset, parentIsRowListItem, lines, depth);
+}
+function emitNode(node, parentOffset, parentIsRowListItem, lines, depth) {
+    // SceneGraph doesn't render an invisible node or anything beneath it, but ECP
+    // still reports the subtree with real bounds. Keeping them would let
+    // assert-visible match a hidden element and assert-not-visible fail on one.
+    if (node.attrs['visible'] === 'false')
+        return;
+    const opacity = parseFloat(node.attrs['opacity'] ?? '100');
+    if (!isNaN(opacity) && opacity <= 0)
+        return;
+    // ECP reports the SceneGraph type in `subtype`; the element name is only a
+    // fallback, and for a generic `RenderableNode` it says nothing at all.
+    const subtype = node.attrs['subtype'] || (node.tag === 'RenderableNode' ? 'Group' : node.tag);
+    const translation = parseNumericArray(node.attrs['translation'], 2);
+    const bounds = parseNumericArray(node.attrs['bounds'], 4);
+    // Offset this node's children inherit.
+    let nodeOffset = parentOffset;
+    if (subtype === 'MarkupGrid' && parentIsRowListItem) {
+        if (bounds)
+            nodeOffset = { x: bounds[0] + parentOffset.x, y: bounds[1] + parentOffset.y };
+    }
+    else if (translation) {
+        nodeOffset = { x: translation[0] + parentOffset.x, y: translation[1] + parentOffset.y };
+    }
+    const focusable = node.attrs['focusable'] === 'true';
+    const focused = node.attrs['focused'] === 'true';
+    const attrs = [`class="${(0, xml_js_1.xmlEscape)(subtype)}"`];
+    if (node.attrs['name'])
+        attrs.push(`resource-id="${(0, xml_js_1.xmlEscape)(node.attrs['name'])}"`);
+    if (node.attrs['text'])
+        attrs.push(`text="${(0, xml_js_1.xmlEscape)(node.attrs['text'])}"`);
+    if (bounds) {
+        const x1 = Math.round(bounds[0] + parentOffset.x);
+        const y1 = Math.round(bounds[1] + parentOffset.y);
+        attrs.push(`bounds="[${x1},${y1}][${x1 + Math.round(bounds[2])},${y1 + Math.round(bounds[3])}]"`);
+    }
+    attrs.push(`clickable="${focusable}"`, `focusable="${focusable}"`);
+    attrs.push(`focused="${focused}"`, `selected="${focused}"`, 'enabled="true"');
+    const indent = '  '.repeat(depth);
+    if (node.children.length === 0) {
+        lines.push(`${indent}<node ${attrs.join(' ')} />`);
+        return;
+    }
+    lines.push(`${indent}<node ${attrs.join(' ')}>`);
+    emitChildren(node, nodeOffset, node.tag === 'RowListItem', lines, depth + 1);
+    lines.push(`${indent}</node>`);
+}
+/**
+ * Parses a Roku numeric array attribute (`{0, 0, 1920, 1080}`), or null if it
+ * doesn't hold at least `minSize` values — callers index it positionally, so a
+ * short array is no more usable than a missing one.
+ */
+function parseNumericArray(value, minSize) {
+    if (!value)
+        return null;
+    const cleaned = value.replace(/[{}]/g, '').trim();
+    if (!cleaned)
+        return null;
+    const parsed = cleaned.split(',').map((p) => parseFloat(p.trim()));
+    if (parsed.length < minSize || parsed.some((v) => isNaN(v)))
+        return null;
+    return parsed;
+}

package/dist/drivers/roku/discovery.js

@@ -0,0 +1,136 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rokuPassword = rokuPassword;
+exports.discoverRokuDevices = discoverRokuDevices;
+exports.describe = describe;
+exports.isPortOpen = isPortOpen;
+exports.parseSsdpLocation = parseSsdpLocation;
+/**
+ * Discovers Roku devices on the local network. Two best-effort methods:
+ *  1. `CONDUCTOR_ROKU_HOST` — a manually pinned device IP/hostname (always checked).
+ *  2. SSDP multicast (`M-SEARCH` with `ST: roku:ecp`) — opt-in via
+ *     `CONDUCTOR_ROKU_DISCOVERY`, because the scan multicasts on the LAN and adds
+ *     ~1s to every device listing.
+ */
+const dgram_1 = __importDefault(require("dgram"));
+const net_1 = __importDefault(require("net"));
+const verbose_js_1 = require("../../verbose.js");
+const ecp_client_js_1 = require("./ecp-client.js");
+const SSDP_ADDRESS = '239.255.255.250';
+const SSDP_PORT = 1900;
+const SSDP_TIMEOUT_MS = 1000;
+const PROBE_TIMEOUT_MS = 500;
+/** The dev-mode password used for screenshots, from the environment. */
+function rokuPassword() {
+    return process.env.CONDUCTOR_ROKU_PASSWORD ?? '';
+}
+function discoveryEnabled() {
+    const v = (process.env.CONDUCTOR_ROKU_DISCOVERY ?? '').toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes';
+}
+/** All Roku devices reachable right now: the pinned env-var host plus any SSDP hits. */
+async function discoverRokuDevices() {
+    const hosts = new Set();
+    const pinned = process.env.CONDUCTOR_ROKU_HOST?.trim();
+    if (pinned)
+        hosts.add(pinned);
+    if (discoveryEnabled()) {
+        for (const host of await ssdpScan())
+            hosts.add(host);
+    }
+    const described = await Promise.all([...hosts].map((host) => describe(host)));
+    return described.filter((d) => d !== null);
+}
+/** Resolve a host into a described device, or null if it isn't reachable. */
+async function describe(host) {
+    if (!(await isPortOpen(host, ecp_client_js_1.DEFAULT_ECP_PORT))) {
+        (0, verbose_js_1.log)(`roku: device at ${host} is not reachable on port ${ecp_client_js_1.DEFAULT_ECP_PORT}`);
+        return null;
+    }
+    const info = await new ecp_client_js_1.RokuEcpClient(host).getDeviceInfo();
+    return {
+        host,
+        modelName: info?.modelName ?? 'Roku Device',
+        friendlyName: info?.friendlyName || host,
+        serialNumber: info?.serialNumber ?? '',
+        softwareVersion: info?.softwareVersion ?? '',
+    };
+}
+/** Quick TCP probe so an offline pinned host fails in ~500ms, not a full HTTP timeout. */
+function isPortOpen(host, port) {
+    return new Promise((resolve) => {
+        const socket = new net_1.default.Socket();
+        const done = (result) => {
+            socket.destroy();
+            resolve(result);
+        };
+        socket.setTimeout(PROBE_TIMEOUT_MS);
+        socket.once('connect', () => done(true));
+        socket.once('timeout', () => done(false));
+        socket.once('error', () => done(false));
+        socket.connect(port, host);
+    });
+}
+/** SSDP M-SEARCH for `roku:ecp` targets; resolves to the responding hosts. */
+function ssdpScan() {
+    const request = Buffer.from([
+        'M-SEARCH * HTTP/1.1',
+        `HOST: ${SSDP_ADDRESS}:${SSDP_PORT}`,
+        'MAN: "ssdp:discover"',
+        'ST: roku:ecp',
+        'MX: 1',
+        '',
+        '',
+    ].join('\r\n'));
+    return new Promise((resolve) => {
+        const hosts = new Set();
+        const socket = dgram_1.default.createSocket({ type: 'udp4', reuseAddr: true });
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                socket.close();
+            }
+            catch {
+                /* already closed */
+            }
+            resolve([...hosts]);
+        };
+        const timer = setTimeout(finish, SSDP_TIMEOUT_MS);
+        socket.on('message', (msg) => {
+            const host = parseSsdpLocation(msg.toString('utf-8'));
+            if (host)
+                hosts.add(host);
+        });
+        socket.on('error', (err) => {
+            (0, verbose_js_1.log)(`roku: SSDP scan failed: ${err.message}`);
+            finish();
+        });
+        socket.bind(() => {
+            socket.send(request, SSDP_PORT, SSDP_ADDRESS, (err) => {
+                if (err) {
+                    (0, verbose_js_1.log)(`roku: SSDP send failed: ${err.message}`);
+                    finish();
+                }
+            });
+        });
+    });
+}
+/** Extract the device host from an SSDP response's `LOCATION: http://<ip>:8060/` header. */
+function parseSsdpLocation(response) {
+    const line = response.split(/\r?\n/).find((l) => /^location:/i.test(l));
+    if (!line)
+        return null;
+    try {
+        return new URL(line.slice(line.indexOf(':') + 1).trim()).hostname || null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/drivers/roku/ecp-client.js

@@ -0,0 +1,396 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RokuEcpClient = exports.RokuEcpError = exports.DEFAULT_ECP_PORT = void 0;
+exports.hintForStatus = hintForStatus;
+exports.encodePathSegment = encodePathSegment;
+exports.parseDigestChallenge = parseDigestChallenge;
+exports.md5Hex = md5Hex;
+/**
+ * HTTP client for the Roku External Control Protocol (ECP). All Roku device
+ * communication goes through a REST API on device port 8060; screenshots go through
+ * the developer web server on port 80 (digest auth with the dev-mode password).
+ *
+ * Requires the device to be in developer mode with ECP network access set to
+ * "Permissive" — recent Roku OS versions return 403 on input commands otherwise.
+ */
+const crypto_1 = __importDefault(require("crypto"));
+const verbose_js_1 = require("../../verbose.js");
+const utils_js_1 = require("../../utils.js");
+const xml_js_1 = require("../xml.js");
+exports.DEFAULT_ECP_PORT = 8060;
+const DEV_USERNAME = 'rokudev';
+const REQUEST_TIMEOUT_MS = 10000;
+const RETRY_BACKOFF_MS = 50;
+const SCREENSHOT_FORMATS = ['jpg', 'png'];
+const SCREENSHOT_TIMEOUT_MS = 10000;
+const SCREENSHOT_POLL_INTERVAL_MS = 250;
+/** `statusCode` is the status the device answered with, or undefined on a transport failure. */
+class RokuEcpError extends Error {
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'RokuEcpError';
+    }
+}
+exports.RokuEcpError = RokuEcpError;
+class RokuEcpClient {
+    constructor(host, opts = {}) {
+        this.host = host;
+        /** RFC 2617 `nc` counts requests sent with one nonce, restarting at 1 for a new one. */
+        this.digestNonce = null;
+        this.digestNonceCount = 0;
+        this.password = opts.password ?? '';
+        this.ecpPort = opts.ecpPort ?? exports.DEFAULT_ECP_PORT;
+        this.keypressDelayMs = opts.keypressDelayMs ?? 100;
+        this.maxRetries = opts.maxRetries ?? 3;
+    }
+    get baseUrl() {
+        return `http://${this.host}:${this.ecpPort}`;
+    }
+    // ── Key input ───────────────────────────────────────────────────────────────
+    async sendKeypress(key) {
+        await this.ecpPost(`keypress/${encodePathSegment(key)}`);
+        if (this.keypressDelayMs > 0)
+            await (0, utils_js_1.sleep)(this.keypressDelayMs);
+    }
+    async sendKeyDown(key) {
+        await this.ecpPost(`keydown/${encodePathSegment(key)}`);
+    }
+    async sendKeyUp(key) {
+        await this.ecpPost(`keyup/${encodePathSegment(key)}`);
+    }
+    /** Types text character-by-character via ECP `LIT_` keypresses. */
+    async sendText(text) {
+        for (const char of text) {
+            await this.ecpPost(`keypress/${encodePathSegment(`LIT_${char}`)}`);
+            if (this.keypressDelayMs > 0)
+                await (0, utils_js_1.sleep)(this.keypressDelayMs);
+        }
+    }
+    // ── App lifecycle ───────────────────────────────────────────────────────────
+    /**
+     * Launches a channel with the caller's parameters and nothing else — no
+     * `RTA_LAUNCH` flag, which asks a roku-test-automation channel *not* to restart
+     * (the opposite of the cold launch `launchApp` guarantees) and on any other
+     * channel is an unexpected parameter riding along with the flow's deep link.
+     */
+    async launchChannel(channelId, params = {}) {
+        const query = Object.entries(params)
+            .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+            .join('&');
+        await this.ecpPost(query ? `launch/${channelId}?${query}` : `launch/${channelId}`);
+    }
+    async getActiveApp() {
+        const root = await this.ecpGetXml('query/active-app');
+        const app = root ? (0, xml_js_1.childElement)(root, 'app') : undefined;
+        if (!app)
+            return null;
+        return {
+            id: app.attrs['id'] ?? '',
+            title: app.text.trim(),
+            type: app.attrs['type'] ?? '',
+            version: app.attrs['version'] ?? '',
+        };
+    }
+    async isActiveApp(channelId) {
+        return (await this.getActiveApp())?.id === channelId;
+    }
+    // ── Device info ─────────────────────────────────────────────────────────────
+    async getDeviceInfo() {
+        const root = await this.ecpGetXml('query/device-info');
+        if (!root)
+            return null;
+        const fields = {};
+        for (const child of root.children)
+            fields[child.tag] = child.text.trim();
+        const uiResolution = fields['ui-resolution'] || '1080p';
+        const is1080 = uiResolution.includes('1080');
+        return {
+            modelName: fields['model-name'] || 'Unknown',
+            modelNumber: fields['model-number'] ?? '',
+            serialNumber: fields['serial-number'] ?? '',
+            softwareVersion: fields['software-version'] ?? '',
+            uiResolution,
+            friendlyName: fields['friendly-device-name'] || fields['device-name'] || '',
+            widthPixels: is1080 ? 1920 : 1280,
+            heightPixels: is1080 ? 1080 : 720,
+        };
+    }
+    // ── View hierarchy ──────────────────────────────────────────────────────────
+    /** Raw SceneGraph XML from `/query/app-ui`, or null when the query fails. */
+    async getAppUIRaw() {
+        try {
+            const res = await this.executeWithRetry(`${this.baseUrl}/query/app-ui`, { method: 'GET' });
+            return await res.text();
+        }
+        catch (err) {
+            // Queries stay tolerant: callers treat null as "hierarchy unavailable".
+            (0, verbose_js_1.log)(`roku ecp: GET query/app-ui failed: ${errMessage(err)}`);
+            return null;
+        }
+    }
+    // ── Screenshot ──────────────────────────────────────────────────────────────
+    /**
+     * Captures a screenshot. Two steps: POST `/plugin_inspect` to generate it, then
+     * GET `/pkgs/dev.jpg` (or `.png`) to download it.
+     *
+     * The dev server acknowledges the generation POST before the capture file is
+     * written (observed on Roku OS 14), so the download polls until the file's ETag
+     * differs from the pre-generation one; on timeout the current file is used — a
+     * re-capture of an unchanged screen can legitimately produce identical bytes.
+     */
+    async takeScreenshot() {
+        const previousEtags = new Map();
+        for (const format of SCREENSHOT_FORMATS) {
+            previousEtags.set(format, await this.screenshotEtag(format));
+        }
+        await this.generateScreenshot();
+        const deadline = Date.now() + SCREENSHOT_TIMEOUT_MS;
+        for (;;) {
+            const timedOut = Date.now() >= deadline;
+            for (const format of SCREENSHOT_FORMATS) {
+                // Cache-bust with a timestamp so no intermediary replays an old capture.
+                const url = `http://${this.host}/pkgs/dev.${format}?time=${Date.now()}`;
+                try {
+                    const res = await this.digestFetch(url, { method: 'GET' });
+                    if (!res.ok)
+                        continue;
+                    const etag = res.headers.get('etag');
+                    const previous = previousEtags.get(format) ?? null;
+                    const isFresh = previous === null || etag === null || etag !== previous;
+                    if (isFresh || timedOut) {
+                        if (!isFresh) {
+                            (0, verbose_js_1.log)(`roku ecp: screenshot ETag unchanged after ${SCREENSHOT_TIMEOUT_MS}ms; using current capture`);
+                        }
+                        return Buffer.from(await res.arrayBuffer());
+                    }
+                }
+                catch (err) {
+                    (0, verbose_js_1.log)(`roku ecp: failed to download screenshot as ${format}: ${errMessage(err)}`);
+                }
+            }
+            if (timedOut)
+                break;
+            await (0, utils_js_1.sleep)(SCREENSHOT_POLL_INTERVAL_MS);
+        }
+        throw new Error(`Failed to capture a screenshot from the Roku device at ${this.host}. ` +
+            `Screenshots require the developer-mode password (CONDUCTOR_ROKU_PASSWORD).`);
+    }
+    /** ETag of the current capture file, or null if none exists (or the server omits it). */
+    async screenshotEtag(format) {
+        try {
+            const res = await this.digestFetch(`http://${this.host}/pkgs/dev.${format}`, {
+                method: 'HEAD',
+            });
+            return res.ok ? res.headers.get('etag') : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async generateScreenshot() {
+        const url = `http://${this.host}/plugin_inspect`;
+        // The dev server only runs the form action when the multipart body arrives on an
+        // already-authorized request (curl's --digest behavior: an empty-body probe
+        // collects the challenge, then the form is sent with Authorization attached up
+        // front). Sending the body on the unauthenticated request and retrying returns a
+        // 200 whose action silently never ran — so the handshake is explicit here.
+        let challenge = null;
+        try {
+            const probe = await fetchWithTimeout(url, { method: 'POST', body: '' });
+            if (probe.status === 401)
+                challenge = probe.headers.get('www-authenticate');
+        }
+        catch (err) {
+            throw new Error(`Screenshot generation request to the Roku device at ${this.host} failed: ${errMessage(err)}`);
+        }
+        // Two quirks, both verified against Roku OS 14 hardware: the empty `archive`
+        // field is required (without it the form handler silently does nothing), and
+        // parts must carry ONLY a Content-Disposition header — the server's parser
+        // ignores parts with a per-part Content-Length. So the body is built by hand.
+        const boundary = `----ConductorRokuFormBoundary${process.hrtime.bigint()}`;
+        const body = `--${boundary}\r\n` +
+            `Content-Disposition: form-data; name="mysubmit"\r\n\r\n` +
+            `Screenshot\r\n` +
+            `--${boundary}\r\n` +
+            `Content-Disposition: form-data; name="archive"\r\n\r\n` +
+            `\r\n` +
+            `--${boundary}--\r\n`;
+        const headers = {
+            'content-type': `multipart/form-data; boundary=${boundary}`,
+        };
+        const auth = challenge && this.buildDigestHeader(challenge, 'POST', '/plugin_inspect');
+        if (auth)
+            headers['authorization'] = auth;
+        let text;
+        try {
+            const res = await fetchWithTimeout(url, { method: 'POST', headers, body });
+            if (!res.ok) {
+                throw new Error(`Screenshot generation failed (HTTP ${res.status}). ` +
+                    `Check the developer-mode password (CONDUCTOR_ROKU_PASSWORD).`);
+            }
+            text = await res.text();
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.startsWith('Screenshot generation failed'))
+                throw err;
+            throw new Error(`Screenshot generation request to the Roku device at ${this.host} failed: ${errMessage(err)}`);
+        }
+        // The dev server reports the result inside the returned page; anything else
+        // means no fresh capture was written to /pkgs/dev.jpg.
+        if (!text.includes('Screenshot ok')) {
+            (0, verbose_js_1.log)(`roku ecp: plugin_inspect did not confirm: ${text.replace(/\n/g, ' ').slice(0, 300)}`);
+            throw new Error(`The Roku device at ${this.host} did not confirm the screenshot ` +
+                `(requires a sideloaded dev channel in the foreground).`);
+        }
+    }
+    // ── Connectivity ────────────────────────────────────────────────────────────
+    async isReachable() {
+        try {
+            await fetchWithTimeout(`${this.baseUrl}/`, { method: 'GET' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ── Digest auth ─────────────────────────────────────────────────────────────
+    /** Issue a request, answering a 401 digest challenge with a signed retry. */
+    async digestFetch(url, init) {
+        const first = await fetchWithTimeout(url, init);
+        if (first.status !== 401)
+            return first;
+        const challenge = first.headers.get('www-authenticate');
+        if (!challenge)
+            return first;
+        const auth = this.buildDigestHeader(challenge, init.method ?? 'GET', new URL(url).pathname);
+        if (!auth)
+            return first;
+        return fetchWithTimeout(url, {
+            ...init,
+            headers: { ...init.headers, authorization: auth },
+        });
+    }
+    nextNonceCount(nonce) {
+        if (nonce !== this.digestNonce) {
+            this.digestNonce = nonce;
+            this.digestNonceCount = 0;
+        }
+        return ++this.digestNonceCount;
+    }
+    buildDigestHeader(challengeHeader, method, uri) {
+        if (!/^digest /i.test(challengeHeader))
+            return null;
+        const params = parseDigestChallenge(challengeHeader.replace(/^digest /i, ''));
+        const realm = params['realm'];
+        const nonce = params['nonce'];
+        if (!realm || !nonce)
+            return null;
+        const qop = params['qop'];
+        const nc = this.nextNonceCount(nonce).toString(16).padStart(8, '0');
+        const cnonce = (process.hrtime.bigint() & 0xffffffffn).toString(16).padStart(8, '0');
+        const ha1 = md5Hex(`${DEV_USERNAME}:${realm}:${this.password}`);
+        const ha2 = md5Hex(`${method}:${uri}`);
+        const response = qop
+            ? md5Hex(`${ha1}:${nonce}:${nc}:${cnonce}:${qop}:${ha2}`)
+            : md5Hex(`${ha1}:${nonce}:${ha2}`);
+        let header = `Digest username="${DEV_USERNAME}", realm="${realm}", nonce="${nonce}", uri="${uri}"`;
+        if (qop)
+            header += `, qop=${qop}, nc=${nc}, cnonce="${cnonce}"`;
+        return `${header}, response="${response}"`;
+    }
+    // ── Internal HTTP helpers ───────────────────────────────────────────────────
+    /**
+     * Issues a state-changing ECP call (input, launch). Throws on failure: a command
+     * that never reached the device must fail the flow rather than let it keep
+     * asserting against a screen no keypress ever touched.
+     */
+    async ecpPost(path) {
+        await this.executeWithRetry(`${this.baseUrl}/${path}`, {
+            method: 'POST',
+            headers: { 'content-type': 'text/plain' },
+            body: '',
+        });
+    }
+    async ecpGetXml(path) {
+        try {
+            const res = await this.executeWithRetry(`${this.baseUrl}/${path}`, { method: 'GET' });
+            return (0, xml_js_1.parseXml)(await res.text());
+        }
+        catch (err) {
+            (0, verbose_js_1.log)(`roku ecp: GET ${path} failed: ${errMessage(err)}`);
+            return null;
+        }
+    }
+    /**
+     * Executes a request, retrying transport failures and 5xx responses. The HTTP
+     * status survives into the error because it is the detail that matters most —
+     * a 403 means ECP access isn't set to Permissive.
+     */
+    async executeWithRetry(url, init) {
+        let lastFailure = null;
+        for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
+            let failure;
+            try {
+                const res = await fetchWithTimeout(url, init);
+                if (res.ok)
+                    return res;
+                failure = new RokuEcpError(`ECP request to ${url} failed with HTTP ${res.status}.${hintForStatus(res.status)}`, res.status);
+            }
+            catch (err) {
+                failure = new RokuEcpError(`ECP request to ${url} failed: ${errMessage(err)}`);
+            }
+            lastFailure = failure;
+            // 4xx is the device's verdict on this request — a retry re-sends what it
+            // already rejected, so report it now instead of after three round trips.
+            if (failure.statusCode !== undefined && failure.statusCode < 500)
+                break;
+            if (attempt < this.maxRetries) {
+                (0, verbose_js_1.log)(`roku ecp: ${failure.message} (attempt ${attempt}/${this.maxRetries}). Retrying.`);
+                await (0, utils_js_1.sleep)(RETRY_BACKOFF_MS);
+            }
+        }
+        throw lastFailure ?? new RokuEcpError(`ECP request to ${url} failed`);
+    }
+}
+exports.RokuEcpClient = RokuEcpClient;
+// ── Standalone helpers (exported for tests) ───────────────────────────────────
+/** Setup advice for the statuses a misconfigured device actually returns. */
+function hintForStatus(status) {
+    if (status === 403) {
+        return (' The device is refusing ECP commands: set Settings > System > Advanced system ' +
+            'settings > Control by mobile apps > Network access to "Permissive".');
+    }
+    if (status === 401)
+        return ' Check the developer-mode password (CONDUCTOR_ROKU_PASSWORD).';
+    return '';
+}
+/**
+ * Percent-encode a URL path segment. `encodeURIComponent` leaves `!'()*` alone and
+ * ECP would deliver those literally, so they are escaped too — a space must arrive
+ * as `%20`, never `+` (`LIT_+` types a plus, not a space).
+ */
+function encodePathSegment(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function parseDigestChallenge(header) {
+    const params = {};
+    const re = /(\w+)=(?:"([^"]*)"|([\w/]+))/g;
+    let m;
+    while ((m = re.exec(header)) !== null) {
+        params[m[1]] = m[2] || m[3];
+    }
+    return params;
+}
+function md5Hex(input) {
+    return crypto_1.default.createHash('md5').update(input).digest('hex');
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function fetchWithTimeout(url, init) {
+    return fetch(url, { ...init, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+}