@houwert/conductor 0.29.3 → 0.31.0

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

package/dist/drivers/roku/key-mapping.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROKU_ECP_KEYS = void 0;
+exports.rokuEcpKey = rokuEcpKey;
+exports.rokuSwipeKey = rokuSwipeKey;
+/** Canonical key name (as listed in `press-key`) → ECP key. */
+exports.ROKU_ECP_KEYS = {
+    'Remote Dpad Up': 'Up',
+    'Remote Dpad Down': 'Down',
+    'Remote Dpad Left': 'Left',
+    'Remote Dpad Right': 'Right',
+    'Remote Dpad Center': 'Select',
+    Enter: 'Select',
+    Return: 'Select',
+    Back: 'Back',
+    Escape: 'Back',
+    Backspace: 'Backspace',
+    Delete: 'Backspace',
+    Home: 'Home',
+    'Remote Media Play Pause': 'Play',
+    'Remote Media Stop': 'Play', // Roku uses Play as a toggle
+    'Remote Media Fast Forward': 'Fwd',
+    'Remote Media Rewind': 'Rev',
+    'Remote Media Next': 'Fwd',
+    'Remote Media Previous': 'Rev',
+    'Remote Menu': 'Info', // The * (options) button is Roku's menu
+    'Remote Info': 'Info',
+    'Remote Instant Replay': 'InstantReplay',
+    'Remote Search': 'Search',
+    Search: 'Search',
+    Power: 'PowerOff',
+    VolumeUp: 'VolumeUp',
+    VolumeDown: 'VolumeDown',
+    'Remote Button A': 'A',
+    'Remote Button B': 'B',
+};
+/**
+ * Key names reach us in several spellings — `Remote Dpad Up` from the CLI,
+ * `REMOTE DPAD UP` from flow YAML, `VOLUME_UP` from the underscore convention —
+ * so lookups compare on letters and digits alone.
+ */
+function normalizeKeyName(name) {
+    return name.toUpperCase().replace(/[^A-Z0-9]/g, '');
+}
+const BY_NORMALIZED = new Map(Object.entries(exports.ROKU_ECP_KEYS).map(([name, key]) => [normalizeKeyName(name), key]));
+/** ECP key for a key name, matched loosely; undefined if unsupported. */
+function rokuEcpKey(name) {
+    return BY_NORMALIZED.get(normalizeKeyName(name));
+}
+/**
+ * D-pad key for a swipe. A swipe drags the content, so it reveals what lies on the
+ * far side: swiping up brings up what is *below*, which on a focus-driven UI is a
+ * move down. Every direction inverts — matching Vega and web, where swiping up
+ * increases the scroll offset.
+ */
+function rokuSwipeKey(direction) {
+    switch (direction) {
+        case 'up':
+            return 'Down';
+        case 'down':
+            return 'Up';
+        case 'left':
+            return 'Right';
+        case 'right':
+            return 'Left';
+    }
+}