@phone-use/sdk 0.2.0 → 0.3.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@phone-use/sdk",
-  "version": "0.2.0",
-  "description": "Typed mobile-device SDK — Device, backends, errors, actions",
+  "version": "0.3.1",
+  "description": "Typed mobile-device SDK \u2014 Device, backends, errors, actions",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,

package/src/backends/cloud-sandbox.ts

@@ -0,0 +1,226 @@
+import { writeFile } from 'node:fs/promises';
+import { BaseDeviceBackend } from '../backend.ts';
+import {
+  ALL_CAPABILITIES,
+  type AlertAction,
+  type BackendAlertResult,
+  type Capability,
+  type OpenAppResult,
+  type PressTarget,
+  type ScrollDirection,
+  type Snapshot,
+} from '../device.ts';
+import { PhoneUseError } from '../errors.ts';
+
+// ---------------------------------------------------------------------------
+// CloudSandboxBackend: drives a phone-use cloud sandbox (a simulator on a
+// remote worker) over the worker's sandbox-scoped RPC endpoint. This is the
+// client half of apps/api's worker protocol; it lives in the SDK so the
+// CLI/MCP/agent can attach to a sandbox without depending on @phone-use/cloud
+// (which also contains the server side and is not published).
+//
+// Wire protocol (shared with apps/api — keep in sync):
+//   POST <endpoint>/rpc  {method, args}  ->  {ok:true,result} | {ok:false,error}
+// ---------------------------------------------------------------------------
+
+/** Every device verb a cloud sandbox accepts over the RPC wire. The worker's
+ * runtime set is contract-tested against this union. */
+export 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. */
+export type SandboxRpcRequest = { method: SandboxRpcMethod; args: unknown[] };
+/** RPC completed; `result` is the verb-specific payload. */
+export 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. */
+export type SandboxRpcFailure = {
+  ok: false;
+  error: { message: string; code?: string | undefined; retryable?: boolean | undefined };
+};
+/** Discriminated RPC outcome — branch on `ok`. */
+export 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`). */
+export type CloudSandboxBackendOptions = {
+  endpoint: string;
+  token: string;
+  capabilities?: Capability[] | undefined;
+  fetch?: typeof globalThis.fetch | undefined;
+};
+
+export class CloudSandboxBackend extends BaseDeviceBackend {
+  private readonly endpoint: string;
+  private readonly token: string;
+  private readonly fetchImpl: typeof globalThis.fetch;
+
+  constructor(opts: CloudSandboxBackendOptions) {
+    super('phone-use-cloud', opts.capabilities ?? ALL_CAPABILITIES);
+    this.endpoint = opts.endpoint.replace(/\/+$/, '');
+    this.token = opts.token;
+    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+  }
+
+  private async rpc<T>(method: SandboxRpcMethod, ...args: unknown[]): Promise<T> {
+    const response = await this.fetchImpl(`${this.endpoint}/rpc`, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${this.token}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({ method, args } satisfies SandboxRpcRequest),
+    });
+    const body = (await response.json().catch(() => ({}))) as
+      | SandboxRpcResponse
+      | { error?: string; message?: string };
+    if (!response.ok || !('ok' in body)) {
+      const message =
+        ('error' in body && typeof body.error === 'string' ? body.error : undefined) ??
+        ('message' in body ? body.message : undefined) ??
+        `HTTP ${response.status}`;
+      throw new PhoneUseError(message, { 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 as T;
+  }
+
+  override snapshot(opts?: { interactiveOnly?: boolean; depth?: number }): Promise<Snapshot> {
+    return this.rpc('snapshot', opts);
+  }
+
+  override async screenshot(opts: { path: string; overlayRefs?: boolean }): Promise<{ path: string }> {
+    const result = await this.rpc<{ base64: string }>('screenshot', {
+      overlayRefs: opts.overlayRefs,
+    });
+    await writeFile(opts.path, Buffer.from(result.base64, 'base64'));
+    return { path: opts.path };
+  }
+
+  override press(target: PressTarget): Promise<void> {
+    return this.rpc('press', target);
+  }
+  override longPress(ref: string, durationMs?: number): Promise<void> {
+    return this.rpc('longPress', ref, durationMs);
+  }
+  override fill(ref: string, text: string): Promise<void> {
+    return this.rpc('fill', ref, text);
+  }
+  override typeText(text: string): Promise<void> {
+    return this.rpc('typeText', text);
+  }
+  override pressKey(key: 'return'): Promise<void> {
+    return this.rpc('pressKey', key);
+  }
+  override scroll(direction: ScrollDirection): Promise<void> {
+    return this.rpc('scroll', direction);
+  }
+  override pan(x: number, y: number, dx: number, dy: number, durationMs?: number): Promise<void> {
+    return this.rpc('pan', x, y, dx, dy, durationMs);
+  }
+  override waitForText(text: string, timeoutMs?: number): Promise<void> {
+    return this.rpc('waitForText', text, timeoutMs);
+  }
+  override systemAlert(action: AlertAction): Promise<BackendAlertResult> {
+    return this.rpc('systemAlert', action);
+  }
+  override home(): Promise<void> {
+    return this.rpc('home');
+  }
+  override back(): Promise<void> {
+    return this.rpc('back');
+  }
+  override openApp(opts: { app?: string; url?: string; relaunch?: boolean }): Promise<OpenAppResult> {
+    return this.rpc('openApp', opts);
+  }
+  override listApps(): Promise<string[]> {
+    return this.rpc('listApps');
+  }
+  override closeSession(): Promise<void> {
+    return this.rpc('closeSession');
+  }
+
+  /** Upload a zipped .app bundle (base64) and install it on the sandbox device. */
+  installApp(base64Zip: string): Promise<{ installed?: string }> {
+    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>`).
+ */
+export function createCloudSandboxBackend(config?: Partial<CloudSandboxBackendOptions>): CloudSandboxBackend {
+  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: string | undefined,
+):
+  | 'DEVICE_NOT_FOUND'
+  | 'DEVICE_IN_USE'
+  | 'SESSION_NOT_FOUND'
+  | 'TIMEOUT'
+  | 'ACTION_FAILED'
+  | 'UNSUPPORTED_CAPABILITY'
+  | 'BACKEND_NOT_FOUND'
+  | 'ABORTED'
+  | 'UNKNOWN' {
+  const codes = new Set([
+    'DEVICE_NOT_FOUND',
+    'DEVICE_IN_USE',
+    'SESSION_NOT_FOUND',
+    'TIMEOUT',
+    'ACTION_FAILED',
+    'UNSUPPORTED_CAPABILITY',
+    'BACKEND_NOT_FOUND',
+    'ABORTED',
+    'UNKNOWN',
+  ]);
+  if (codes.has(code ?? '')) return code as ReturnType<typeof normalizeErrorCode>;
+  // The cloud worker's lowercase taxonomy (device_gone/timeout/…) maps into
+  // the typed PhoneUseError codes instead of collapsing to UNKNOWN.
+  const cloud: Record<string, ReturnType<typeof normalizeErrorCode>> = {
+    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',
+  };
+  return cloud[code ?? ''] ?? 'UNKNOWN';
+}

package/src/backends/device-runner.ts

@@ -201,5 +201,7 @@ export class DeviceRunnerBackend extends BaseDeviceBackend {
   }
 }
 
+/** Backend for a phone-runner reached by URL (defaults come from
+ * `PHONE_USE_RUNNER_URL` / `PHONE_USE_RUNNER_TOKEN` when `config` is omitted). */
 export const createDeviceRunnerBackend = (config?: DeviceRunnerConfig): DeviceRunnerBackend =>
   new DeviceRunnerBackend(config);

package/src/index.ts

@@ -7,7 +7,7 @@
  * deliberately not re-exported here.
  */
 /** The published package version (kept in sync with package.json by the release flow). */
-export const VERSION = '0.2.0';
+export const VERSION = '0.3.1';
 
 export {
   type Action,
@@ -31,7 +31,21 @@ export {
   registerBackend,
 } from './backend.ts';
 export { createAgentDeviceBackend } from './backends/agent-device.ts';
-export { createDeviceRunnerBackend, DeviceRunnerBackend } from './backends/device-runner.ts';
+export {
+  CloudSandboxBackend,
+  type CloudSandboxBackendOptions,
+  createCloudSandboxBackend,
+  type SandboxRpcFailure,
+  type SandboxRpcMethod,
+  type SandboxRpcRequest,
+  type SandboxRpcResponse,
+  type SandboxRpcSuccess,
+} from './backends/cloud-sandbox.ts';
+export {
+  createDeviceRunnerBackend,
+  DeviceRunnerBackend,
+  type DeviceRunnerConfig,
+} from './backends/device-runner.ts';
 export { type IosConnectOptions, type IosLaunchOptions, ios } from './backends/ios.ts';
 export type { AndroidDeviceConfig, CommonDeviceConfig, DeviceConfig, IosDeviceConfig } from './config.ts';
 export type {