@putdotio/rokit 1.5.0 → 1.6.0

package/README.md

@@ -1,8 +1,4 @@
 <div align="center">
-  <p>
-    <img src="https://static.put.io/images/putio-boncuk.png" width="72">
-  </p>
-
   <h1>rokit</h1>
 
   <p>A tiny CLI companion for Roku device harness work.</p>
@@ -85,7 +81,9 @@ await waitForSceneGraphAssertion(context, "expected player", (xml) => {
 rokit check
 rokit device-info
 rokit active-app
+rokit media-player
 rokit wait-active <app-id> [--timeout-ms <ms>]
+rokit wait-media-player <state> [--timeout-ms <ms>]
 rokit launch <app-id> [--param key=value]
 rokit press [--delay-ms <ms>] <key> [key...]
 rokit query <ecp-path>
@@ -111,8 +109,12 @@ and reports failures as `{ "status": "failed", "error": { "message": "..." } }`.
   is reachable.
 - `device-info` prints enhanced Roku device metadata as JSON.
 - `active-app` prints the foreground app.
+- `media-player` prints parsed `/query/media-player` playback state, including
+  state, container, position, duration, and format metadata.
 - `wait-active` waits until the requested app is foregrounded and tolerates
   transient ECP read failures while polling.
+- `wait-media-player` waits until `/query/media-player` reports a target state
+  such as `play`, `pause`, or `buffer`.
 - `launch` opens an app and waits until it is active. Use repeated `--param`
   values for deeplink parameters. Roku launch responses can race app startup, so
   launch accepts transient timeout/fetch failures and then verifies foreground
@@ -152,6 +154,7 @@ tokens, and app-specific media identifiers do not belong in git.
 - launch and deeplink parameters
 - remote keypresses
 - raw ECP queries
+- parsed media-player state from `/query/media-player`
 - SceneGraph state queries and named-node assertions
 - SceneGraph attribute, numeric geometry, bounds, and translation readers
 - SceneGraph geometry assertions, status/failure readers, and custom assertion

package/dist/index.d.mts

@@ -57,6 +57,24 @@ type DeviceSummary = {
   readonly model: string;
   readonly name: string;
 };
+type MediaPlayerState = "buffer" | "close" | "error" | "none" | "open" | "pause" | "play" | "stop" | string;
+type MediaPlayerInfo = {
+  readonly audio?: string;
+  readonly buffering?: {
+    readonly current?: number;
+    readonly max?: number;
+    readonly target?: number;
+  };
+  readonly captions?: string;
+  readonly container?: string;
+  readonly durationMs?: number;
+  readonly error: boolean;
+  readonly isLive?: boolean;
+  readonly positionMs?: number;
+  readonly state?: MediaPlayerState;
+  readonly video?: string;
+  readonly videoResolution?: string;
+};
 type RetryOptions = {
   readonly attempts?: number;
   readonly retryDelayMs?: number;
@@ -73,6 +91,14 @@ declare const waitForActiveApp: (context: RokuContext, appId: string, timeoutMs?
 declare const launchApp: (context: RokuContext, appId: string, params?: ReadonlyMap<string, string>) => Promise<ActiveApp>;
 declare const pressKey: (context: RokuContext, key: string) => Promise<void>;
 declare const queryEcp: (context: RokuContext, path: string) => Promise<string>;
+declare const queryMediaPlayerXml: (context: RokuContext) => Promise<string>;
+declare const queryMediaPlayer: (context: RokuContext) => Promise<MediaPlayerInfo>;
+declare const readMediaPlayerInfo: (xml: string) => MediaPlayerInfo;
+declare const readMediaPlayerState: (xml: string) => MediaPlayerState | undefined;
+declare const readMediaPlayerPositionMs: (xml: string) => number | undefined;
+declare const readMediaPlayerContainer: (xml: string) => string | undefined;
+declare const isActiveMediaPlayerState: (state: string | undefined) => boolean;
+declare const waitForMediaPlayerState: (context: RokuContext, expectedState: MediaPlayerState, timeoutMs?: number) => Promise<MediaPlayerInfo>;
 declare const querySceneGraph: (context: RokuContext, options?: RetryOptions) => Promise<string>;
 declare const assertSceneGraphNode: (context: RokuContext, nodeName: string, expectation: NodeExpectation) => Promise<void>;
 declare const waitForSceneGraphNode: (context: RokuContext, nodeName: string, expectation: NodeExpectation, timeoutMs?: number) => Promise<void>;
@@ -85,4 +111,4 @@ declare const takeScreenshot: (context: RokuContext & {
 }, outputPath: string) => Promise<string>;
 declare const validateRemoteKey: (key: string) => void;
 //#endregion
-export { type ActiveApp, type DeviceSummary, type NodeExpectation, type NodeState, type RemoteKey, type RetryOptions, type RokuContext, type SceneGraphAssertion, type SceneGraphBounds, type SceneGraphPoint, type SceneGraphStatus, type WaitForSceneGraphAssertionOptions, assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, checkDevice, getDeviceInfo, installPackage, isNamedNodeVisible, launchApp, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, querySceneGraph, readActiveApp, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForSceneGraphAssertion, waitForSceneGraphNode };
+export { type ActiveApp, type DeviceSummary, type MediaPlayerInfo, type MediaPlayerState, type NodeExpectation, type NodeState, type RemoteKey, type RetryOptions, type RokuContext, type SceneGraphAssertion, type SceneGraphBounds, type SceneGraphPoint, type SceneGraphStatus, type WaitForSceneGraphAssertionOptions, assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, checkDevice, getDeviceInfo, installPackage, isActiveMediaPlayerState, isNamedNodeVisible, launchApp, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, queryMediaPlayer, queryMediaPlayerXml, querySceneGraph, readActiveApp, readMediaPlayerContainer, readMediaPlayerInfo, readMediaPlayerPositionMs, readMediaPlayerState, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForMediaPlayerState, waitForSceneGraphAssertion, waitForSceneGraphNode };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { A as readActiveApp, C as readNamedNodeAttribute, D as readNamedNodeTranslation, E as readNamedNodeNumber, M as readXmlTag, O as readSceneGraphFailure, S as parseSceneGraphNumberList, T as readNamedNodeBounds, _ as assertNamedNodeState, a as launchApp, b as assertSceneGraphNumberNear, c as queryEcp, d as validateRemoteKey, f as waitForActiveApp, g as assertNamedNodeSize, h as assertNamedNode, i as installPackage, j as readXmlAttribute, k as readSceneGraphStatus, l as querySceneGraph, m as waitForSceneGraphNode, n as checkDevice, o as pressKey, p as waitForSceneGraphAssertion, r as getDeviceInfo, s as queryActiveApp, t as assertSceneGraphNode, u as takeScreenshot, v as assertNamedNodeText, w as readNamedNodeAttributes, x as isNamedNodeVisible, y as assertNamedNodeTranslation } from "./roku-CNLr4tbj.mjs";
-export { assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, checkDevice, getDeviceInfo, installPackage, isNamedNodeVisible, launchApp, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, querySceneGraph, readActiveApp, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForSceneGraphAssertion, waitForSceneGraphNode };
+import { A as parseSceneGraphNumberList, B as readXmlTag, C as assertNamedNode, D as assertNamedNodeTranslation, E as assertNamedNodeText, F as readNamedNodeTranslation, I as readSceneGraphFailure, L as readSceneGraphStatus, M as readNamedNodeAttributes, N as readNamedNodeBounds, O as assertSceneGraphNumberNear, P as readNamedNodeNumber, R as readActiveApp, S as waitForSceneGraphNode, T as assertNamedNodeState, _ as takeScreenshot, a as isActiveMediaPlayerState, b as waitForMediaPlayerState, c as queryActiveApp, d as queryMediaPlayerXml, f as querySceneGraph, g as readMediaPlayerState, h as readMediaPlayerPositionMs, i as installPackage, j as readNamedNodeAttribute, k as isNamedNodeVisible, l as queryEcp, m as readMediaPlayerInfo, n as checkDevice, o as launchApp, p as readMediaPlayerContainer, r as getDeviceInfo, s as pressKey, t as assertSceneGraphNode, u as queryMediaPlayer, v as validateRemoteKey, w as assertNamedNodeSize, x as waitForSceneGraphAssertion, y as waitForActiveApp, z as readXmlAttribute } from "./roku-CXHAzYR-.mjs";
+export { assertNamedNode, assertNamedNodeSize, assertNamedNodeState, assertNamedNodeText, assertNamedNodeTranslation, assertSceneGraphNode, assertSceneGraphNumberNear, checkDevice, getDeviceInfo, installPackage, isActiveMediaPlayerState, isNamedNodeVisible, launchApp, parseSceneGraphNumberList, pressKey, queryActiveApp, queryEcp, queryMediaPlayer, queryMediaPlayerXml, querySceneGraph, readActiveApp, readMediaPlayerContainer, readMediaPlayerInfo, readMediaPlayerPositionMs, readMediaPlayerState, readNamedNodeAttribute, readNamedNodeAttributes, readNamedNodeBounds, readNamedNodeNumber, readNamedNodeTranslation, readSceneGraphFailure, readSceneGraphStatus, readXmlAttribute, readXmlTag, takeScreenshot, validateRemoteKey, waitForActiveApp, waitForMediaPlayerState, waitForSceneGraphAssertion, waitForSceneGraphNode };

package/dist/rokit.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as launchApp, c as queryEcp, f as waitForActiveApp, i as installPackage, l as querySceneGraph, m as waitForSceneGraphNode, n as checkDevice, o as pressKey, r as getDeviceInfo, s as queryActiveApp, t as assertSceneGraphNode, u as takeScreenshot } from "./roku-CNLr4tbj.mjs";
+import { S as waitForSceneGraphNode, _ as takeScreenshot, b as waitForMediaPlayerState, c as queryActiveApp, f as querySceneGraph, i as installPackage, l as queryEcp, n as checkDevice, o as launchApp, r as getDeviceInfo, s as pressKey, t as assertSceneGraphNode, u as queryMediaPlayer, y as waitForActiveApp } from "./roku-CXHAzYR-.mjs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { existsSync, mkdirSync } from "node:fs";
@@ -98,6 +98,24 @@ const runCommand = async (context, command) => {
 			status: "ok"
 		};
 	}
+	if (command.name === "media-player") {
+		const mediaPlayer = await queryMediaPlayer(context);
+		return {
+			command: command.name,
+			data: mediaPlayer,
+			message: formatMediaPlayerMessage(mediaPlayer),
+			status: "ok"
+		};
+	}
+	if (command.name === "wait-media-player") {
+		const mediaPlayer = await waitForMediaPlayerState(context, command.state, command.timeoutMs);
+		return {
+			command: command.name,
+			data: mediaPlayer,
+			message: formatMediaPlayerMessage(mediaPlayer),
+			status: "ok"
+		};
+	}
 	if (command.name === "wait-active") {
 		const app = await waitForActiveApp(context, command.appId, command.timeoutMs);
 		return {
@@ -254,6 +272,16 @@ const parseCommand = (argv) => {
 	if (name === "check") return { name };
 	if (name === "device-info") return { name };
 	if (name === "active-app") return { name };
+	if (name === "media-player") return { name };
+	if (name === "wait-media-player") {
+		const state = args[0];
+		if (!state) fail("usage: rokit wait-media-player <state> [--timeout-ms <ms>]");
+		return {
+			name,
+			state,
+			timeoutMs: parseTimeoutOption(args.slice(1), "rokit wait-media-player <state>")
+		};
+	}
 	if (name === "wait-active") {
 		const appId = args[0];
 		if (!appId) fail("usage: rokit wait-active <app-id> [--timeout-ms <ms>]");
@@ -382,6 +410,15 @@ const formatNodeData = ({ expectation, nodeName, timeoutMs }) => ({
 	nodeName,
 	timeoutMs
 });
+const formatMediaPlayerMessage = (mediaPlayer) => {
+	return `media-player: ${[
+		`state=${mediaPlayer.state ?? "unknown"}`,
+		`container=${mediaPlayer.container ?? "unknown"}`,
+		`position=${formatMaybeMs(mediaPlayer.positionMs)}`,
+		`duration=${formatMaybeMs(mediaPlayer.durationMs)}`
+	].join(" ")}`;
+};
+const formatMaybeMs = (value) => value === void 0 ? "unknown" : `${value}ms`;
 const sleep = (ms) => new Promise((resolve) => {
 	setTimeout(resolve, ms);
 });
@@ -411,7 +448,9 @@ usage:
   rokit check
   rokit device-info
   rokit active-app
+  rokit media-player
   rokit wait-active <app-id> [--timeout-ms <ms>]
+  rokit wait-media-player <state> [--timeout-ms <ms>]
   rokit launch <app-id> [--param key=value]
   rokit press [--delay-ms <ms>] <key> [key...]
   rokit query <ecp-path>

package/dist/{roku-CNLr4tbj.mjs → roku-CXHAzYR-.mjs}

@@ -189,6 +189,52 @@ const pressKey = async (context, key) => {
 	await postOk(context, ecpUrl(context, `/keypress/${encodeURIComponent(key)}`));
 };
 const queryEcp = async (context, path) => await fetchText(context, path.startsWith("/") ? path : `/${path}`);
+const queryMediaPlayerXml = async (context) => await queryEcp(context, "/query/media-player");
+const queryMediaPlayer = async (context) => readMediaPlayerInfo(await queryMediaPlayerXml(context));
+const readMediaPlayerInfo = (xml) => {
+	const playerAttributes = /<player(?:\s+([^>]*))?>/.exec(xml)?.[1] ?? "";
+	const formatAttributes = /<format(?:\s+([^>]*))?\/>/.exec(xml)?.[1] ?? "";
+	const bufferingAttributes = /<buffering(?:\s+([^>]*))?\/>/.exec(xml)?.[1];
+	return {
+		audio: readXmlAttribute(formatAttributes, "audio"),
+		buffering: bufferingAttributes === void 0 ? void 0 : {
+			current: readXmlNumberAttribute(bufferingAttributes, "current"),
+			max: readXmlNumberAttribute(bufferingAttributes, "max"),
+			target: readXmlNumberAttribute(bufferingAttributes, "target")
+		},
+		captions: readXmlAttribute(formatAttributes, "captions"),
+		container: readXmlAttribute(formatAttributes, "container"),
+		durationMs: readXmlNumberTag(xml, "duration"),
+		error: readXmlAttribute(playerAttributes, "error") === "true",
+		isLive: readXmlBooleanTag(xml, "is_live"),
+		positionMs: readXmlNumberTag(xml, "position"),
+		state: readXmlAttribute(playerAttributes, "state"),
+		video: readXmlAttribute(formatAttributes, "video"),
+		videoResolution: readXmlAttribute(formatAttributes, "video_res")
+	};
+};
+const readMediaPlayerState = (xml) => readMediaPlayerInfo(xml).state;
+const readMediaPlayerPositionMs = (xml) => readMediaPlayerInfo(xml).positionMs;
+const readMediaPlayerContainer = (xml) => readMediaPlayerInfo(xml).container;
+const isActiveMediaPlayerState = (state) => state === "buffer" || state === "pause" || state === "play";
+const waitForMediaPlayerState = async (context, expectedState, timeoutMs = 1e4) => {
+	const start = Date.now();
+	let lastState;
+	let lastError;
+	while (Date.now() - start < timeoutMs) {
+		try {
+			const mediaPlayer = await queryMediaPlayer(context);
+			lastState = mediaPlayer.state;
+			lastError = void 0;
+			if (mediaPlayer.state === expectedState) return mediaPlayer;
+		} catch (error) {
+			lastError = formatErrorMessage(error);
+		}
+		await sleep(500);
+	}
+	const suffix = lastError ? `; last ECP error: ${lastError}` : "";
+	throw new Error(`expected media-player state ${expectedState}, got ${lastState ?? "unknown"}${suffix}`);
+};
 const querySceneGraph = async (context, options = {}) => {
 	const attempts = options.attempts ?? 1;
 	const retryDelayMs = options.retryDelayMs ?? 500;
@@ -291,9 +337,27 @@ const postLaunchMaybeAccepted = async (context, url) => {
 	}
 };
 const ecpUrl = (context, path) => new URL(path, `http://${context.target}:${ecpPort}`);
+const readXmlNumberTag = (xml, tag) => {
+	const rawValue = readXmlTag(xml, tag);
+	if (rawValue === void 0) return;
+	const match = /-?\d+(?:\.\d+)?/.exec(rawValue);
+	if (!match) return;
+	return Number(match[0]);
+};
+const readXmlBooleanTag = (xml, tag) => {
+	const value = readXmlTag(xml, tag);
+	if (value === "true") return true;
+	if (value === "false") return false;
+};
+const readXmlNumberAttribute = (attributes, name) => {
+	const value = readXmlAttribute(attributes, name);
+	if (value === void 0) return;
+	const parsed = Number(value);
+	return Number.isFinite(parsed) ? parsed : void 0;
+};
 const sleep = (ms) => new Promise((resolve) => {
 	setTimeout(resolve, ms);
 });
 const formatErrorMessage = (error) => error instanceof Error ? error.message : String(error);
 //#endregion
-export { readActiveApp as A, readNamedNodeAttribute as C, readNamedNodeTranslation as D, readNamedNodeNumber as E, readXmlTag as M, readSceneGraphFailure as O, parseSceneGraphNumberList as S, readNamedNodeBounds as T, assertNamedNodeState as _, launchApp as a, assertSceneGraphNumberNear as b, queryEcp as c, validateRemoteKey as d, waitForActiveApp as f, assertNamedNodeSize as g, assertNamedNode as h, installPackage as i, readXmlAttribute as j, readSceneGraphStatus as k, querySceneGraph as l, waitForSceneGraphNode as m, checkDevice as n, pressKey as o, waitForSceneGraphAssertion as p, getDeviceInfo as r, queryActiveApp as s, assertSceneGraphNode as t, takeScreenshot as u, assertNamedNodeText as v, readNamedNodeAttributes as w, isNamedNodeVisible as x, assertNamedNodeTranslation as y };
+export { parseSceneGraphNumberList as A, readXmlTag as B, assertNamedNode as C, assertNamedNodeTranslation as D, assertNamedNodeText as E, readNamedNodeTranslation as F, readSceneGraphFailure as I, readSceneGraphStatus as L, readNamedNodeAttributes as M, readNamedNodeBounds as N, assertSceneGraphNumberNear as O, readNamedNodeNumber as P, readActiveApp as R, waitForSceneGraphNode as S, assertNamedNodeState as T, takeScreenshot as _, isActiveMediaPlayerState as a, waitForMediaPlayerState as b, queryActiveApp as c, queryMediaPlayerXml as d, querySceneGraph as f, readMediaPlayerState as g, readMediaPlayerPositionMs as h, installPackage as i, readNamedNodeAttribute as j, isNamedNodeVisible as k, queryEcp as l, readMediaPlayerInfo as m, checkDevice as n, launchApp as o, readMediaPlayerContainer as p, getDeviceInfo as r, pressKey as s, assertSceneGraphNode as t, queryMediaPlayer as u, validateRemoteKey as v, assertNamedNodeSize as w, waitForSceneGraphAssertion as x, waitForActiveApp as y, readXmlAttribute as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@putdotio/rokit",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "A tiny CLI companion for Roku device harness work.",
   "keywords": [
     "cli",