@phone-use/sdk 0.4.1 → 0.5.0

package/src/backends/cloud-sandbox.ts

@@ -42,7 +42,18 @@ export type SandboxRpcMethod =
   | 'back'
   | 'openApp'
   | 'listApps'
-  | 'closeSession';
+  | 'closeSession'
+  | 'checkpoint'
+  | 'restoreCheckpoint'
+  | 'listCheckpoints'
+  | 'deleteCheckpoint';
+
+/** One saved device state, as reported by the worker. */
+export type SandboxCheckpointInfo = {
+  id: string;
+  label?: string | undefined;
+  createdAt: string;
+};
 
 /** Body of `POST <endpoint>/rpc`: one verb and its positional arguments. */
 export type SandboxRpcRequest = { method: SandboxRpcMethod; args: unknown[] };
@@ -162,6 +173,36 @@ export class CloudSandboxBackend extends BaseDeviceBackend {
     return this.rpc('closeSession');
   }
 
+  // -------------------------------------------------------------------------
+  // Checkpoints: save/restore the WHOLE device state (apps, logins, photos,
+  // settings). Not a UI snapshot — see `snapshot` for the accessibility tree.
+  // The device is briefly unavailable while a checkpoint saves or restores
+  // (shutdown → clone → boot on the worker); verbs issued meanwhile fail and
+  // should be retried after the checkpoint call resolves.
+  // -------------------------------------------------------------------------
+
+  /** Save the device's current state. Returns the checkpoint's id. */
+  checkpoint(opts?: { label?: string }): Promise<SandboxCheckpointInfo> {
+    return this.rpc('checkpoint', opts);
+  }
+
+  /** Restore a checkpoint by id or label. The checkpoint survives — restore as
+   * often as needed. Device identity may change server-side; the sandbox
+   * endpoint/token stay valid. */
+  restoreCheckpoint(ref: string): Promise<{ checkpointId: string }> {
+    return this.rpc('restoreCheckpoint', ref);
+  }
+
+  /** List this sandbox's checkpoints. */
+  listCheckpoints(): Promise<SandboxCheckpointInfo[]> {
+    return this.rpc('listCheckpoints');
+  }
+
+  /** Delete a checkpoint by id or label. */
+  deleteCheckpoint(ref: string): Promise<{ deleted: boolean }> {
+    return this.rpc('deleteCheckpoint', ref);
+  }
+
   /** Upload a zipped .app bundle (base64) and install it on the sandbox device. */
   /**
    * Upload a zipped .app as a raw stream. Prefer this over {@link installApp}:

package/src/index.ts

@@ -1,13 +1,13 @@
 /**
  * @phone-use/sdk — the device runtime SDK: engine-as-object lifecycle
- * (ios.launch/connect → Device), Device backends, config, errors, capabilities,
+ * (ios.launch/connect and android.launch/connect → Device), Device backends, config, errors, capabilities,
  * and the action verb surface.
  *
  * The test double (FakeBackend) lives on the "@phone-use/sdk/testing" subpath,
  * deliberately not re-exported here.
  */
 /** The published package version (kept in sync with package.json by the release flow). */
-export const VERSION = '0.4.1';
+export const VERSION = '0.5.0';
 
 export {
   type Action,
@@ -31,10 +31,23 @@ export {
   registerBackend,
 } from './backend.ts';
 export { createAgentDeviceBackend } from './backends/agent-device.ts';
+export {
+  AndroidBackend,
+  type AndroidBackendOptions,
+  type AndroidConnectOptions,
+  type AndroidDeviceInfo,
+  type AndroidLaunchOptions,
+  type AndroidListOptions,
+  android,
+  type BinaryExecRunner,
+  createAndroidBackend,
+  type EmulatorProcess,
+} from './backends/android.ts';
 export {
   CloudSandboxBackend,
   type CloudSandboxBackendOptions,
   createCloudSandboxBackend,
+  type SandboxCheckpointInfo,
   type SandboxRpcFailure,
   type SandboxRpcMethod,
   type SandboxRpcRequest,
@@ -97,5 +110,7 @@ export { SecretStore } from './secrets.ts';
 // of the *published* dist, where the barrel is the entry).
 import { registerBackend as _register } from './backend.ts';
 import { createAgentDeviceBackend as _createAd } from './backends/agent-device.ts';
+import { createAndroidBackend as _createAndroid } from './backends/android.ts';
 
 _register('agent-device', _createAd);
+_register('android-adb', _createAndroid);

package/src/lifecycle.ts

@@ -21,8 +21,8 @@ export type DeviceStatus = 'running' | 'closed';
 /**
  * The Device lifecycle handle: id, pinned backend, close/dispose, idle lease +
  * reaper — plus the action verb surface layered onto the same type.
- * `ios.launch()` and `ios.connect()` return it; the future android engine will
- * share `createDeviceHandle`.
+ * `ios.launch()`/`ios.connect()` and `android.launch()`/`android.connect()`
+ * all return it, built over `createDeviceHandle`.
  */
 export interface Device {
   /** udid (iOS) / serial (Android). */
@@ -177,7 +177,7 @@ export type CreateDeviceHandleOptions = {
 
 /**
  * Assemble a Device handle over a backend: lease/reaper, verb surface,
- * close/dispose semantics. Engine authors (ios here, android in item 7b,
+ * close/dispose semantics. Engine authors (ios and android here,
  * phone-backend-* third parties) build on this; tests fabricate devices with
  * it over a FakeBackend.
  */