@phone-use/sdk 0.2.0 → 0.3.1

package/dist/index.d.mts

@@ -477,6 +477,87 @@ declare function executeAction(core: DeviceCore, action: Action, opts?: ActOptio
  */
 declare function createAgentDeviceBackend(config?: DeviceConfig): DeviceBackend;
 //#endregion
+//#region src/backends/cloud-sandbox.d.ts
+/** Every device verb a cloud sandbox accepts over the RPC wire. The worker's
+ * runtime set is contract-tested against this union. */
+type SandboxRpcMethod = 'snapshot' | 'screenshot' | 'press' | 'longPress' | 'fill' | 'typeText' | 'pressKey' | 'scroll' | 'pan' | 'installApp' | 'waitForText' | 'systemAlert' | 'home' | 'back' | 'openApp' | 'listApps' | 'closeSession';
+/** Body of `POST <endpoint>/rpc`: one verb and its positional arguments. */
+type SandboxRpcRequest = {
+  method: SandboxRpcMethod;
+  args: unknown[];
+};
+/** RPC completed; `result` is the verb-specific payload. */
+type SandboxRpcSuccess = {
+  ok: true;
+  result: unknown;
+};
+/** RPC failed on-device. `code` is a stable taxonomy bucket (`device_gone`,
+ * `timeout`, `session_conflict`, `target_not_found`, `internal`) and
+ * `retryable` tells agents whether retrying may succeed. */
+type SandboxRpcFailure = {
+  ok: false;
+  error: {
+    message: string;
+    code?: string | undefined;
+    retryable?: boolean | undefined;
+  };
+};
+/** Discriminated RPC outcome — branch on `ok`. */
+type SandboxRpcResponse = SandboxRpcSuccess | SandboxRpcFailure;
+/** Connection settings for one provisioned cloud phone: the per-sandbox
+ * `endpoint`/`token` pair returned by `phone-use create` (or `/v1/sandboxes`). */
+type CloudSandboxBackendOptions = {
+  endpoint: string;
+  token: string;
+  capabilities?: Capability[] | undefined;
+  fetch?: typeof globalThis.fetch | undefined;
+};
+declare class CloudSandboxBackend extends BaseDeviceBackend {
+  private readonly endpoint;
+  private readonly token;
+  private readonly fetchImpl;
+  constructor(opts: CloudSandboxBackendOptions);
+  private rpc;
+  snapshot(opts?: {
+    interactiveOnly?: boolean;
+    depth?: number;
+  }): Promise<Snapshot>;
+  screenshot(opts: {
+    path: string;
+    overlayRefs?: boolean;
+  }): Promise<{
+    path: string;
+  }>;
+  press(target: PressTarget): Promise<void>;
+  longPress(ref: string, durationMs?: number): Promise<void>;
+  fill(ref: string, text: string): Promise<void>;
+  typeText(text: string): Promise<void>;
+  pressKey(key: 'return'): Promise<void>;
+  scroll(direction: ScrollDirection): Promise<void>;
+  pan(x: number, y: number, dx: number, dy: number, durationMs?: number): Promise<void>;
+  waitForText(text: string, timeoutMs?: number): Promise<void>;
+  systemAlert(action: AlertAction): Promise<BackendAlertResult>;
+  home(): Promise<void>;
+  back(): Promise<void>;
+  openApp(opts: {
+    app?: string;
+    url?: string;
+    relaunch?: boolean;
+  }): Promise<OpenAppResult>;
+  listApps(): Promise<string[]>;
+  closeSession(): Promise<void>;
+  /** Upload a zipped .app bundle (base64) and install it on the sandbox device. */
+  installApp(base64Zip: string): Promise<{
+    installed?: string;
+  }>;
+}
+/**
+ * Build a CloudSandboxBackend from explicit options or the environment:
+ * PHONE_USE_SANDBOX_URL + PHONE_USE_SANDBOX_TOKEN (printed by
+ * `phone-use sandbox env <id>`).
+ */
+declare function createCloudSandboxBackend(config?: Partial<CloudSandboxBackendOptions>): CloudSandboxBackend;
+//#endregion
 //#region src/backends/device-runner.d.ts
 /**
  * A device-runner is addressed purely by URL, so it takes no DeviceConfig
@@ -535,6 +616,8 @@ declare class DeviceRunnerBackend extends BaseDeviceBackend {
     device?: string;
   }>;
 }
+/** Backend for a phone-runner reached by URL (defaults come from
+ * `PHONE_USE_RUNNER_URL` / `PHONE_USE_RUNNER_TOKEN` when `config` is omitted). */
 declare const createDeviceRunnerBackend: (config?: DeviceRunnerConfig) => DeviceRunnerBackend;
 //#endregion
 //#region src/lifecycle.d.ts
@@ -743,7 +826,7 @@ declare const ios: {
  * deliberately not re-exported here.
  */
 /** The published package version (kept in sync with package.json by the release flow). */
-declare const VERSION = "0.2.0";
+declare const VERSION = "0.3.1";
 //#endregion
-export { ALL_CAPABILITIES, AbortedError, type ActOptions, type Action, type ActionEvidence, ActionFailedError, type ActionResult, type ActionVerb, type AlertAction, type AlertOutcome, type AndroidDeviceConfig, type BackendAlertResult, type BackendFactory, BaseDeviceBackend, type Capability, type CommonDeviceConfig, type CompiledSkill, type CreateDeviceHandleOptions, type Device, type DeviceBackend, type DeviceConfig, DeviceCore, DeviceInUseError, DeviceNotFoundError, type DevicePlatform, DeviceRunnerBackend, type DeviceStatus, type ElementQuery, type IosConnectOptions, type IosDeviceConfig, type IosLaunchOptions, type Observation, type ObserveResult, type ObservedElement, type OpenAppResult, PhoneUseError, type PhoneUseErrorCode, type PhoneUseErrorDetails, type PressTarget, type Rect, type RenderState, type Resolution, type ResolveOpts, type ScrollDirection, SecretStore, SessionNotFoundError, type Snapshot, type SnapshotNode, TimeoutError, type UiElement, UnsupportedCapabilityError, VERSION, buildObserveResult, createAgentDeviceBackend, createDeviceHandle, createDeviceRunnerBackend, describeError, executeAction, getBackendFactory, ios, labelMatches, listBackends, matchInElements, registerBackend, toActions, toPhoneUseError };
+export { ALL_CAPABILITIES, AbortedError, type ActOptions, type Action, type ActionEvidence, ActionFailedError, type ActionResult, type ActionVerb, type AlertAction, type AlertOutcome, type AndroidDeviceConfig, type BackendAlertResult, type BackendFactory, BaseDeviceBackend, type Capability, CloudSandboxBackend, type CloudSandboxBackendOptions, type CommonDeviceConfig, type CompiledSkill, type CreateDeviceHandleOptions, type Device, type DeviceBackend, type DeviceConfig, DeviceCore, DeviceInUseError, DeviceNotFoundError, type DevicePlatform, DeviceRunnerBackend, type DeviceRunnerConfig, type DeviceStatus, type ElementQuery, type IosConnectOptions, type IosDeviceConfig, type IosLaunchOptions, type Observation, type ObserveResult, type ObservedElement, type OpenAppResult, PhoneUseError, type PhoneUseErrorCode, type PhoneUseErrorDetails, type PressTarget, type Rect, type RenderState, type Resolution, type ResolveOpts, type SandboxRpcFailure, type SandboxRpcMethod, type SandboxRpcRequest, type SandboxRpcResponse, type SandboxRpcSuccess, type ScrollDirection, SecretStore, SessionNotFoundError, type Snapshot, type SnapshotNode, TimeoutError, type UiElement, UnsupportedCapabilityError, VERSION, buildObserveResult, createAgentDeviceBackend, createCloudSandboxBackend, createDeviceHandle, createDeviceRunnerBackend, describeError, executeAction, getBackendFactory, ios, labelMatches, listBackends, matchInElements, registerBackend, toActions, toPhoneUseError };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import { a as registerBackend, c as DeviceInUseError, d as SessionNotFoundError, f as TimeoutError, i as listBackends, l as DeviceNotFoundError, m as toPhoneUseError, n as BaseDeviceBackend, o as AbortedError, p as UnsupportedCapabilityError, r as getBackendFactory, s as ActionFailedError, t as ALL_CAPABILITIES, u as PhoneUseError } from "./device-Xsy_LPUF.mjs";
 import { createAgentDeviceClient } from "agent-device";
+import { writeFile } from "node:fs/promises";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 //#region src/observe.ts
@@ -1453,6 +1454,138 @@ function createAgentDeviceBackend(config) {
 	return new AgentDeviceBackend(config);
 }
 //#endregion
+//#region src/backends/cloud-sandbox.ts
+var CloudSandboxBackend = class extends BaseDeviceBackend {
+	endpoint;
+	token;
+	fetchImpl;
+	constructor(opts) {
+		super("phone-use-cloud", opts.capabilities ?? ALL_CAPABILITIES);
+		this.endpoint = opts.endpoint.replace(/\/+$/, "");
+		this.token = opts.token;
+		this.fetchImpl = opts.fetch ?? globalThis.fetch;
+	}
+	async rpc(method, ...args) {
+		const response = await this.fetchImpl(`${this.endpoint}/rpc`, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${this.token}`,
+				"content-type": "application/json"
+			},
+			body: JSON.stringify({
+				method,
+				args
+			})
+		});
+		const body = await response.json().catch(() => ({}));
+		if (!response.ok || !("ok" in body)) throw new PhoneUseError(("error" in body && typeof body.error === "string" ? body.error : void 0) ?? ("message" in body ? body.message : void 0) ?? `HTTP ${response.status}`, {
+			code: "UNKNOWN",
+			retryable: false
+		});
+		if (!body.ok) throw new PhoneUseError(body.error.message, {
+			code: normalizeErrorCode(body.error.code),
+			retryable: body.error.retryable ?? false
+		});
+		return body.result;
+	}
+	snapshot(opts) {
+		return this.rpc("snapshot", opts);
+	}
+	async screenshot(opts) {
+		const result = await this.rpc("screenshot", { overlayRefs: opts.overlayRefs });
+		await writeFile(opts.path, Buffer.from(result.base64, "base64"));
+		return { path: opts.path };
+	}
+	press(target) {
+		return this.rpc("press", target);
+	}
+	longPress(ref, durationMs) {
+		return this.rpc("longPress", ref, durationMs);
+	}
+	fill(ref, text) {
+		return this.rpc("fill", ref, text);
+	}
+	typeText(text) {
+		return this.rpc("typeText", text);
+	}
+	pressKey(key) {
+		return this.rpc("pressKey", key);
+	}
+	scroll(direction) {
+		return this.rpc("scroll", direction);
+	}
+	pan(x, y, dx, dy, durationMs) {
+		return this.rpc("pan", x, y, dx, dy, durationMs);
+	}
+	waitForText(text, timeoutMs) {
+		return this.rpc("waitForText", text, timeoutMs);
+	}
+	systemAlert(action) {
+		return this.rpc("systemAlert", action);
+	}
+	home() {
+		return this.rpc("home");
+	}
+	back() {
+		return this.rpc("back");
+	}
+	openApp(opts) {
+		return this.rpc("openApp", opts);
+	}
+	listApps() {
+		return this.rpc("listApps");
+	}
+	closeSession() {
+		return this.rpc("closeSession");
+	}
+	/** Upload a zipped .app bundle (base64) and install it on the sandbox device. */
+	installApp(base64Zip) {
+		return this.rpc("installApp", base64Zip);
+	}
+};
+/**
+* Build a CloudSandboxBackend from explicit options or the environment:
+* PHONE_USE_SANDBOX_URL + PHONE_USE_SANDBOX_TOKEN (printed by
+* `phone-use sandbox env <id>`).
+*/
+function createCloudSandboxBackend(config) {
+	const endpoint = config?.endpoint ?? process.env.PHONE_USE_SANDBOX_URL;
+	const token = config?.token ?? process.env.PHONE_USE_SANDBOX_TOKEN;
+	if (!endpoint || !token) throw new PhoneUseError("cloud sandbox backend needs PHONE_USE_SANDBOX_URL and PHONE_USE_SANDBOX_TOKEN (see `phone-use sandbox env <id>`)", {
+		code: "BACKEND_NOT_FOUND",
+		retryable: false
+	});
+	return new CloudSandboxBackend({
+		...config,
+		endpoint,
+		token
+	});
+}
+function normalizeErrorCode(code) {
+	if ((/* @__PURE__ */ new Set([
+		"DEVICE_NOT_FOUND",
+		"DEVICE_IN_USE",
+		"SESSION_NOT_FOUND",
+		"TIMEOUT",
+		"ACTION_FAILED",
+		"UNSUPPORTED_CAPABILITY",
+		"BACKEND_NOT_FOUND",
+		"ABORTED",
+		"UNKNOWN"
+	])).has(code ?? "")) return code;
+	return {
+		device_gone: "DEVICE_NOT_FOUND",
+		sandbox_not_found: "DEVICE_NOT_FOUND",
+		timeout: "TIMEOUT",
+		session_conflict: "DEVICE_IN_USE",
+		target_not_found: "ACTION_FAILED",
+		unauthorized: "ABORTED",
+		payload_too_large: "ACTION_FAILED",
+		bad_request: "ACTION_FAILED",
+		internal: "UNKNOWN"
+	}[code ?? ""] ?? "UNKNOWN";
+}
+//#endregion
 //#region src/backends/device-runner.ts
 const RUNNER_CAPABILITIES = [
 	"snapshot",
@@ -1605,6 +1738,8 @@ var DeviceRunnerBackend = class extends BaseDeviceBackend {
 		return this.#rpc("get_context");
 	}
 };
+/** Backend for a phone-runner reached by URL (defaults come from
+* `PHONE_USE_RUNNER_URL` / `PHONE_USE_RUNNER_TOKEN` when `config` is omitted). */
 const createDeviceRunnerBackend = (config) => new DeviceRunnerBackend(config);
 //#endregion
 //#region src/exec.ts
@@ -1994,9 +2129,9 @@ const ios = {
 * deliberately not re-exported here.
 */
 /** The published package version (kept in sync with package.json by the release flow). */
-const VERSION = "0.2.0";
+const VERSION = "0.3.1";
 registerBackend("agent-device", createAgentDeviceBackend);
 //#endregion
-export { ALL_CAPABILITIES, AbortedError, ActionFailedError, BaseDeviceBackend, DeviceCore, DeviceInUseError, DeviceNotFoundError, DeviceRunnerBackend, PhoneUseError, SecretStore, SessionNotFoundError, TimeoutError, UnsupportedCapabilityError, VERSION, buildObserveResult, createAgentDeviceBackend, createDeviceHandle, createDeviceRunnerBackend, describeError, executeAction, getBackendFactory, ios, labelMatches, listBackends, matchInElements, registerBackend, toActions, toPhoneUseError };
+export { ALL_CAPABILITIES, AbortedError, ActionFailedError, BaseDeviceBackend, CloudSandboxBackend, DeviceCore, DeviceInUseError, DeviceNotFoundError, DeviceRunnerBackend, PhoneUseError, SecretStore, SessionNotFoundError, TimeoutError, UnsupportedCapabilityError, VERSION, buildObserveResult, createAgentDeviceBackend, createCloudSandboxBackend, createDeviceHandle, createDeviceRunnerBackend, describeError, executeAction, getBackendFactory, ios, labelMatches, listBackends, matchInElements, registerBackend, toActions, toPhoneUseError };
 
 //# sourceMappingURL=index.mjs.map