droidline 0.0.0-stage → 0.1.2

package/dist/generated.js

@@ -0,0 +1,397 @@
+// generated by scripts/gen.mjs from spec/commands.json, do not edit
+import { EventEmitter } from "node:events";
+import { collect } from "./args.js";
+export const PROTO = 1;
+/** HTTP status and default retryable flag of each error code. */
+export const ERRORS = {
+    /** The target did not appear in time. The current package/activity is returned in screen. */
+    NOT_FOUND: { http: 422, retryable: true },
+    /** Several elements match. Only raised in strict mode; candidates are returned. */
+    AMBIGUOUS: { http: 422, retryable: false },
+    /** Both the node action and the coordinate tap failed. */
+    NOT_CLICKABLE: { http: 422, retryable: true },
+    /** The action itself timed out. Safe to retry. */
+    TIMEOUT: { http: 504, retryable: true },
+    /** Accessibility service is off. */
+    NO_ACCESSIBILITY: { http: 409, retryable: false },
+    /** The Droidline keyboard is not selected, so key codes, text and clipboard reads are unavailable. */
+    NO_IME: { http: 409, retryable: false },
+    /** A permission such as VPN or notification access is missing. The permission name is returned. */
+    NO_PERMISSION: { http: 409, retryable: false },
+    /** Package is not installed. Similar package names are suggested. */
+    APP_NOT_FOUND: { http: 422, retryable: false },
+    /** Tried to start a non-exported activity. Suggests launching the package default. */
+    ACTIVITY_BLOCKED: { http: 422, retryable: false },
+    /** Upstream connection or authentication failed. reason is auth, timeout, refused or protocol. */
+    PROXY_FAILED: { http: 502, retryable: true },
+    /** Command not supported. The agent version is returned. */
+    UNKNOWN_CMD: { http: 404, retryable: false },
+    /** The phone's Android version cannot do this without ADB or root. */
+    UNSUPPORTED: { http: 422, retryable: false },
+    /** Missing or invalid parameters. */
+    BAD_ARGS: { http: 400, retryable: false },
+    /** No paired device has that ID or name. */
+    DEVICE_NOT_FOUND: { http: 404, retryable: false },
+    /** The device is paired but offline. Commands wait for a reconnect before failing. */
+    DEVICE_OFFLINE: { http: 503, retryable: true },
+    /** No device was given and more than one is online. */
+    DEVICE_AMBIGUOUS: { http: 400, retryable: false },
+    /** The phone is leased and the request did not carry that lease. */
+    DEVICE_LEASED: { http: 409, retryable: true },
+    /** The lease in the request was released or expired. */
+    LEASE_NOT_FOUND: { http: 404, retryable: false },
+    /** lease waited and every matching phone stayed leased or offline. */
+    NO_FREE_DEVICE: { http: 409, retryable: true },
+    /** Tesseract or the requested language data is missing on the PC. */
+    OCR_UNAVAILABLE: { http: 501, retryable: false },
+    /** The phone app restarted with this command in flight. Not retried automatically to avoid running it twice. */
+    AGENT_RESTARTED: { http: 503, retryable: true },
+    /** Client API token missing or wrong. */
+    UNAUTHORIZED: { http: 401, retryable: false },
+    /** The pairing code did not match a waiting phone. */
+    PAIRING_FAILED: { http: 422, retryable: false },
+    /** Bug. Please report it with the server log. */
+    INTERNAL: { http: 500, retryable: false },
+};
+/** The chrome.* commands, reached as d.chrome. */
+export class ChromeCommands {
+    _run;
+    constructor(_run) {
+        this._run = _run;
+    }
+    async go(...args) {
+        return this._run("chrome.go", "fields", collect("chrome.go", args, ["url"], ["new_tab"]));
+    }
+}
+/** Commands that run on one phone. Device extends this and implements the hooks. */
+export class DeviceCommands {
+    get chrome() {
+        return new ChromeCommands((cmd, kind, params) => this._run(cmd, kind, params));
+    }
+    async dump(...args) {
+        return this._saveJson("dump", collect("dump", args, [], ["path"]));
+    }
+    async screenshot(...args) {
+        return this._saveImage("screenshot", collect("screenshot", args, [], ["path"]));
+    }
+    async record(...args) {
+        return this._run("record", "none", collect("record", args, ["on"], ["minutes"]));
+    }
+    async find_image(...args) {
+        const params = collect("find_image", args, ["image"], ["threshold", "timeout"]);
+        params["image"] = await this._loadImage(params["image"]);
+        return this._run("find_image", "fields", params);
+    }
+    async findImage(...args) {
+        const params = collect("find_image", args, ["image"], ["threshold", "timeout"]);
+        params["image"] = await this._loadImage(params["image"]);
+        return this._run("find_image", "fields", params);
+    }
+    async tap_image(...args) {
+        const params = collect("tap_image", args, ["image"], ["threshold", "timeout"]);
+        params["image"] = await this._loadImage(params["image"]);
+        return this._run("tap_image", "fields", params);
+    }
+    async tapImage(...args) {
+        const params = collect("tap_image", args, ["image"], ["threshold", "timeout"]);
+        params["image"] = await this._loadImage(params["image"]);
+        return this._run("tap_image", "fields", params);
+    }
+    async ocr(...args) {
+        return this._run("ocr", "fields", collect("ocr", args, [], ["lang"]));
+    }
+    async ocr_find(...args) {
+        return this._run("ocr_find", "fields", collect("ocr_find", args, ["text"], ["lang", "timeout"]));
+    }
+    async ocrFind(...args) {
+        return this._run("ocr_find", "fields", collect("ocr_find", args, ["text"], ["lang", "timeout"]));
+    }
+    async ocr_tap(...args) {
+        return this._run("ocr_tap", "fields", collect("ocr_tap", args, ["text"], ["lang", "timeout"]));
+    }
+    async ocrTap(...args) {
+        return this._run("ocr_tap", "fields", collect("ocr_tap", args, ["text"], ["lang", "timeout"]));
+    }
+    async current(...args) {
+        return this._run("current", "fields", collect("current", args, [], []));
+    }
+    async tap(...args) {
+        return this._run("tap", "fields", collect("tap", args, ["x", "y"], []));
+    }
+    async long_tap(...args) {
+        return this._run("long_tap", "fields", collect("long_tap", args, ["x", "y"], ["ms"]));
+    }
+    async longTap(...args) {
+        return this._run("long_tap", "fields", collect("long_tap", args, ["x", "y"], ["ms"]));
+    }
+    async swipe(...args) {
+        return this._run("swipe", "fields", collect("swipe", args, ["x1"], ["y1", "x2", "y2", "ms"]));
+    }
+    async touch(...args) {
+        return this._run("touch", "fields", collect("touch", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["nth", "timeout"]));
+    }
+    async touchById(...args) {
+        return this._run("touchById", "fields", collect("touchById", args, ["value"], ["nth", "timeout"]));
+    }
+    async touchByText(...args) {
+        return this._run("touchByText", "fields", collect("touchByText", args, ["value"], ["nth", "timeout"]));
+    }
+    async touchByDesc(...args) {
+        return this._run("touchByDesc", "fields", collect("touchByDesc", args, ["value"], ["nth", "timeout"]));
+    }
+    async long_touch(...args) {
+        return this._run("long_touch", "fields", collect("long_touch", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["ms", "nth", "timeout"]));
+    }
+    async longTouch(...args) {
+        return this._run("long_touch", "fields", collect("long_touch", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["ms", "nth", "timeout"]));
+    }
+    async scroll_to(...args) {
+        return this._run("scroll_to", "fields", collect("scroll_to", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["direction", "max_swipes", "nth"]));
+    }
+    async scrollTo(...args) {
+        return this._run("scroll_to", "fields", collect("scroll_to", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["direction", "max_swipes", "nth"]));
+    }
+    async input(...args) {
+        return this._run("input", "fields", collect("input", args, typeof args[0] === "string" ? ["by", "value", "text"] : ["by", "text"], ["append", "nth", "timeout"]));
+    }
+    async clear(...args) {
+        return this._run("clear", "fields", collect("clear", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["nth", "timeout"]));
+    }
+    async sendkey(...args) {
+        return this._run("sendkey", "fields", collect("sendkey", args, [], ["key", "text"]));
+    }
+    async exists(...args) {
+        return this._run("exists", "value", collect("exists", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["nth"]));
+    }
+    async wait(...args) {
+        return this._run("wait", "fields", collect("wait", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["timeout", "nth"]));
+    }
+    async wait_gone(...args) {
+        return this._run("wait_gone", "fields", collect("wait_gone", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["timeout"]));
+    }
+    async waitGone(...args) {
+        return this._run("wait_gone", "fields", collect("wait_gone", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["timeout"]));
+    }
+    async wait_idle(...args) {
+        return this._run("wait_idle", "fields", collect("wait_idle", args, [], ["ms", "timeout"]));
+    }
+    async waitIdle(...args) {
+        return this._run("wait_idle", "fields", collect("wait_idle", args, [], ["ms", "timeout"]));
+    }
+    async find(...args) {
+        return this._runElement("find", "value", collect("find", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["nth", "timeout"]));
+    }
+    async find_all(...args) {
+        return this._runElement("find_all", "value", collect("find_all", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["timeout"]));
+    }
+    async findAll(...args) {
+        return this._runElement("find_all", "value", collect("find_all", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["timeout"]));
+    }
+    async get_text(...args) {
+        return this._run("get_text", "value", collect("get_text", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["nth"]));
+    }
+    async getText(...args) {
+        return this._run("get_text", "value", collect("get_text", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["nth"]));
+    }
+    async checked(...args) {
+        return this._run("checked", "value", collect("checked", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["nth"]));
+    }
+    async enabled(...args) {
+        return this._run("enabled", "value", collect("enabled", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["nth"]));
+    }
+    async selected(...args) {
+        return this._run("selected", "value", collect("selected", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["nth"]));
+    }
+    async count(...args) {
+        return this._run("count", "value", collect("count", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], []));
+    }
+    async which(...args) {
+        return this._run("which", "value", collect("which", args, ["candidates"], ["timeout"]));
+    }
+    async in_app(...args) {
+        return this._run("in_app", "value", collect("in_app", args, ["package"], []));
+    }
+    async inApp(...args) {
+        return this._run("in_app", "value", collect("in_app", args, ["package"], []));
+    }
+    async keyboard_shown(...args) {
+        return this._run("keyboard_shown", "value", collect("keyboard_shown", args, [], []));
+    }
+    async keyboardShown(...args) {
+        return this._run("keyboard_shown", "value", collect("keyboard_shown", args, [], []));
+    }
+    async last_toast(...args) {
+        return this._run("last_toast", "value", collect("last_toast", args, [], ["max_age"]));
+    }
+    async lastToast(...args) {
+        return this._run("last_toast", "value", collect("last_toast", args, [], ["max_age"]));
+    }
+    async color(...args) {
+        return this._run("color", "value", collect("color", args, ["x", "y"], []));
+    }
+    async screen_on(...args) {
+        return this._run("screen_on", "value", collect("screen_on", args, [], []));
+    }
+    async screenOn(...args) {
+        return this._run("screen_on", "value", collect("screen_on", args, [], []));
+    }
+    async locked(...args) {
+        return this._run("locked", "value", collect("locked", args, [], []));
+    }
+    async wake(...args) {
+        return this._run("wake", "fields", collect("wake", args, [], []));
+    }
+    async lock(...args) {
+        return this._run("lock", "none", collect("lock", args, [], []));
+    }
+    async battery(...args) {
+        return this._run("battery", "fields", collect("battery", args, [], []));
+    }
+    async orientation(...args) {
+        return this._run("orientation", "value", collect("orientation", args, [], []));
+    }
+    async info(...args) {
+        return this._run("info", "fields", collect("info", args, [], []));
+    }
+    async network(...args) {
+        return this._run("network", "fields", collect("network", args, [], []));
+    }
+    async launch(...args) {
+        return this._run("launch", "fields", collect("launch", args, ["package"], ["activity"]));
+    }
+    async open_url(...args) {
+        return this._run("open_url", "none", collect("open_url", args, ["url"], ["package"]));
+    }
+    async openUrl(...args) {
+        return this._run("open_url", "none", collect("open_url", args, ["url"], ["package"]));
+    }
+    async intent(...args) {
+        return this._run("intent", "none", collect("intent", args, ["action"], ["data", "package"]));
+    }
+    async clear_data(...args) {
+        return this._run("clear_data", "fields", collect("clear_data", args, ["package"], []));
+    }
+    async clearData(...args) {
+        return this._run("clear_data", "fields", collect("clear_data", args, ["package"], []));
+    }
+    async apps(...args) {
+        return this._run("apps", "value", collect("apps", args, [], ["system"]));
+    }
+    async installed(...args) {
+        return this._run("installed", "value", collect("installed", args, ["package"], []));
+    }
+    async back(...args) {
+        return this._run("back", "none", collect("back", args, [], []));
+    }
+    async home(...args) {
+        return this._run("home", "none", collect("home", args, [], []));
+    }
+    async recents(...args) {
+        return this._run("recents", "none", collect("recents", args, [], []));
+    }
+    async open_notifications(...args) {
+        return this._run("open_notifications", "none", collect("open_notifications", args, [], []));
+    }
+    async openNotifications(...args) {
+        return this._run("open_notifications", "none", collect("open_notifications", args, [], []));
+    }
+    async quick_settings(...args) {
+        return this._run("quick_settings", "none", collect("quick_settings", args, [], []));
+    }
+    async quickSettings(...args) {
+        return this._run("quick_settings", "none", collect("quick_settings", args, [], []));
+    }
+    async clipboard(...args) {
+        return this._run("clipboard", "value", collect("clipboard", args, [], ["text"]));
+    }
+    async batch(...args) {
+        return this._run("batch", "fields", collect("batch", args, ["steps"], ["stop_on_error", "cuts_network"]));
+    }
+    async proxy(...args) {
+        return this._run("proxy", "fields", collect("proxy", args, ["url"], ["app"]));
+    }
+    async proxy_check(...args) {
+        return this._run("proxy_check", "fields", collect("proxy_check", args, [], ["app"]));
+    }
+    async proxyCheck(...args) {
+        return this._run("proxy_check", "fields", collect("proxy_check", args, [], ["app"]));
+    }
+    async notifications(...args) {
+        return this._run("notifications", "value", collect("notifications", args, [], ["package"]));
+    }
+    async has_notification(...args) {
+        return this._run("has_notification", "value", collect("has_notification", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], []));
+    }
+    async hasNotification(...args) {
+        return this._run("has_notification", "value", collect("has_notification", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], []));
+    }
+    async wait_notification(...args) {
+        return this._run("wait_notification", "value", collect("wait_notification", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["timeout", "package"]));
+    }
+    async waitNotification(...args) {
+        return this._run("wait_notification", "value", collect("wait_notification", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["timeout", "package"]));
+    }
+    async notification_reply(...args) {
+        return this._run("notification_reply", "none", collect("notification_reply", args, ["key", "text"], []));
+    }
+    async notificationReply(...args) {
+        return this._run("notification_reply", "none", collect("notification_reply", args, ["key", "text"], []));
+    }
+    async notification_click(...args) {
+        return this._run("notification_click", "none", collect("notification_click", args, ["key"], []));
+    }
+    async notificationClick(...args) {
+        return this._run("notification_click", "none", collect("notification_click", args, ["key"], []));
+    }
+    async notification_dismiss(...args) {
+        return this._run("notification_dismiss", "none", collect("notification_dismiss", args, ["key"], []));
+    }
+    async notificationDismiss(...args) {
+        return this._run("notification_dismiss", "none", collect("notification_dismiss", args, ["key"], []));
+    }
+    async notify_filter(...args) {
+        return this._run("notify_filter", "value", collect("notify_filter", args, [], ["packages"]));
+    }
+    async notifyFilter(...args) {
+        return this._run("notify_filter", "value", collect("notify_filter", args, [], ["packages"]));
+    }
+}
+/** Commands the PC server answers itself. Droidline extends this and implements _run. */
+export class ClientCommands extends EventEmitter {
+    async wait_notification(...args) {
+        return this._run("wait_notification", "value", collect("wait_notification", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["timeout", "package"]));
+    }
+    async waitNotification(...args) {
+        return this._run("wait_notification", "value", collect("wait_notification", args, typeof args[0] === "string" ? ["by", "value"] : ["by"], ["timeout", "package"]));
+    }
+    async devices(...args) {
+        return this._run("devices", "value", collect("devices", args, [], []));
+    }
+    async pair(...args) {
+        return this._run("pair", "value", collect("pair", args, ["code"], ["name"]));
+    }
+    async pair_qr(...args) {
+        return this._run("pair_qr", "fields", collect("pair_qr", args, [], ["name"]));
+    }
+    async pairQr(...args) {
+        return this._run("pair_qr", "fields", collect("pair_qr", args, [], ["name"]));
+    }
+    async rename(...args) {
+        return this._run("rename", "value", collect("rename", args, ["device", "name"], []));
+    }
+    async revoke(...args) {
+        return this._run("revoke", "none", collect("revoke", args, ["device"], []));
+    }
+    async subscribe(...args) {
+        return this._run("subscribe", "none", collect("subscribe", args, ["events"], ["device"]));
+    }
+    async server_info(...args) {
+        return this._run("server_info", "fields", collect("server_info", args, [], []));
+    }
+    async serverInfo(...args) {
+        return this._run("server_info", "fields", collect("server_info", args, [], []));
+    }
+    async auth(...args) {
+        return this._run("auth", "none", collect("auth", args, ["token"], []));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { connect, lease, Droidline, Device, LeasedDevice, DEFAULT_HOST, DEFAULT_PORT, type ClientOptions, type ConnectOptions, type HistoryEntry, type LeaseOptions, type NotificationCallback, type NotificationFilter, } from "./client.js";
+export { DroidlineError, type ClientErrorCode } from "./errors.js";
+export { Element } from "./element.js";
+export type { Params } from "./args.js";
+export * from "./generated.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { connect, lease, Droidline, Device, LeasedDevice, DEFAULT_HOST, DEFAULT_PORT, } from "./client.js";
+export { DroidlineError } from "./errors.js";
+export { Element } from "./element.js";
+export * from "./generated.js";

package/dist/testing.d.ts

@@ -0,0 +1,14 @@
+import type { Device, HistoryEntry } from "./client.js";
+/** The command log as text, one line per request. */
+export declare function formatHistory(entries: readonly HistoryEntry[]): string;
+/**
+ * Save a screenshot, the screen tree and the command log of a phone into folder, for a failed
+ * test. Each part is best effort: a phone that is offline still gets its command log.
+ * Resolves with the files written.
+ *
+ * @example
+ * afterEach(async (ctx) => {
+ *   if (ctx.task.result?.state === "fail") await saveFailure(d, `artifacts/${ctx.task.name}`);
+ * });
+ */
+export declare function saveFailure(device: Device, folder: string): Promise<string[]>;

package/dist/testing.js

@@ -0,0 +1,43 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/** The command log as text, one line per request. */
+export function formatHistory(entries) {
+    return entries
+        .map((e) => {
+        const stamp = new Date(e.time).toTimeString().slice(0, 8);
+        return `${stamp} ${e.cmd} ${JSON.stringify(e.params)} -> ${e.ok ? "ok" : e.error} (${e.ms} ms)`;
+    })
+        .join("\n");
+}
+/**
+ * Save a screenshot, the screen tree and the command log of a phone into folder, for a failed
+ * test. Each part is best effort: a phone that is offline still gets its command log.
+ * Resolves with the files written.
+ *
+ * @example
+ * afterEach(async (ctx) => {
+ *   if (ctx.task.result?.state === "fail") await saveFailure(d, `artifacts/${ctx.task.name}`);
+ * });
+ */
+export async function saveFailure(device, folder) {
+    await mkdir(folder, { recursive: true });
+    const saved = [];
+    const log = join(folder, "commands.txt");
+    await writeFile(log, formatHistory(device.history) + "\n", "utf8");
+    saved.push(log);
+    const parts = [
+        ["screen.png", (p) => device.screenshot(p, { format: "png" })],
+        ["screen.json", (p) => device.dump(p)],
+    ];
+    for (const [name, take] of parts) {
+        const path = join(folder, name);
+        try {
+            await take(path);
+            saved.push(path);
+        }
+        catch {
+            // The phone may be offline or the screen protected; the log above is still useful.
+        }
+    }
+    return saved;
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "droidline",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Control Android phones from Node.js without ADB or root: find elements, tap, type, take screenshots and read notifications.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.test.json && node --test build-test/test/client.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "android",
+    "android-automation",
+    "mobile-automation",
+    "ui-automation",
+    "test-automation",
+    "testing",
+    "appium",
+    "uiautomator",
+    "adb",
+    "accessibility",
+    "rpa",
+    "device-farm",
+    "mcp",
+    "typescript",
+    "droidline"
+  ],
+  "homepage": "https://droidline.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KnifeLemon/Droidline.git",
+    "directory": "sdk/node"
+  },
+  "bugs": {
+    "url": "https://github.com/KnifeLemon/Droidline/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^18.19.0",
+    "typescript": "^5.9.3"
+  }
+}