@mobilerun/sdk 5.1.0 → 5.2.0

package/src/resources/devices/devices.ts

@@ -98,26 +98,32 @@ export class Devices extends APIResource {
   language: LanguageAPI.Language = new LanguageAPI.Language(this._client);
 
   /**
-   * Provision a new device
+   * Requests a new device for the authenticated user from the device spec in the
+   * request body. Optional query parameters select the canonical device type, target
+   * country, billing mode, and a profile to use as the base spec; deprecated
+   * device-type aliases remain accepted only during the documented compatibility
+   * grace period. The response returns the device and its stream token.
    */
   create(params: DeviceCreateParams, options?: RequestOptions): APIPromise<Device> {
-    const { query_country, deviceType, profileId, ...body } = params;
+    const { billing, query_country, deviceType, profileId, ...body } = params;
     return this._client.post('/devices', {
-      query: { country: query_country, deviceType, profileId },
+      query: { billing, country: query_country, deviceType, profileId },
       body,
       ...options,
     });
   }
 
   /**
-   * Get device info
+   * Returns the current state and metadata for a single device, including its
+   * lifecycle state, type, stream URL, billing strategy, and timestamps. A stream
+   * token is included while the device is active.
    */
   retrieve(deviceID: string, options?: RequestOptions): APIPromise<Device> {
     return this._client.get(path`/devices/${deviceID}`, options);
   }
 
   /**
-   * List devices
+   * Returns a paginated list of the user's devices along with pagination metadata.
    */
   list(
     query: DeviceListParams | null | undefined = {},
@@ -127,14 +133,16 @@ export class Devices extends APIResource {
   }
 
   /**
-   * Count claimed devices
+   * Returns the number of claimed devices for the user, broken down by device type.
    */
   count(options?: RequestOptions): APIPromise<DeviceCountResponse> {
     return this._client.get('/devices/count', options);
   }
 
   /**
-   * Device fingerprint snapshot
+   * Returns a live snapshot of the device's spoofed identity, including model,
+   * display, identifiers, and carrier. Devices without fingerprint support return an
+   * unsupported-feature error.
    */
   fingerprint(
     deviceID: string,
@@ -156,7 +164,8 @@ export class Devices extends APIResource {
   }
 
   /**
-   * Reboot a device
+   * Triggers a reboot of the device. The device transitions through its reboot
+   * lifecycle and becomes ready again once the restart completes.
    */
   reboot(deviceID: string, options?: RequestOptions): APIPromise<void> {
     return this._client.post(path`/devices/${deviceID}/reboot`, {
@@ -166,7 +175,9 @@ export class Devices extends APIResource {
   }
 
   /**
-   * Reset a device to a fresh state
+   * Resets the device back to a clean state, clearing installed apps and user data
+   * accumulated during the session. The device transitions through its reset
+   * lifecycle before becoming ready again.
    */
   reset(deviceID: string, options?: RequestOptions): APIPromise<void> {
     return this._client.post(path`/devices/${deviceID}/reset`, {
@@ -176,14 +187,17 @@ export class Devices extends APIResource {
   }
 
   /**
-   * Update device name
+   * Sets the display name for a device from the name in the request body and returns
+   * the updated device.
    */
   setName(deviceID: string, body: DeviceSetNameParams, options?: RequestOptions): APIPromise<Device> {
     return this._client.put(path`/devices/${deviceID}/name`, { body, ...options });
   }
 
   /**
-   * Terminate a device
+   * Terminates the device and releases its resources. Termination can be scheduled
+   * for a future time or chained from a previous device via the request body, in
+   * which case a service key is required.
    */
   terminate(deviceID: string, body: DeviceTerminateParams, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/devices/${deviceID}`, {
@@ -194,7 +208,9 @@ export class Devices extends APIResource {
   }
 
   /**
-   * Wait for device to be ready
+   * Blocks until the device reaches the ready state, then returns the same payload
+   * as Get device info. The call returns early with an error if the wait is
+   * cancelled or times out.
    */
   waitReady(deviceID: string, options?: RequestOptions): APIPromise<Device> {
     return this._client.get(path`/devices/${deviceID}/wait`, options);
@@ -231,10 +247,19 @@ export interface Device {
    */
   $schema?: string;
 
+  billingStrategy?: string;
+
+  createdBy?: string;
+
+  ownerId?: string;
+
   providerId?: string;
 
   streamToken?: string;
 
+  /**
+   * @deprecated Deprecated: use ownerId/createdBy.
+   */
   userId?: string;
 }
 
@@ -293,6 +318,14 @@ export namespace DeviceFingerprintResponse {
 }
 
 export interface DeviceCreateParams {
+  /**
+   * Query param: Billing mode. 'auto' uses a subscription slot when available and
+   * otherwise bills per minute; 'subscription' requires an available subscription
+   * slot; 'minute' bills per minute. Only cloud phone and cloud emulator devices
+   * support per-minute billing.
+   */
+  billing?: 'auto' | 'subscription' | 'minute';
+
   /**
    * Query param: ISO 3166-1 alpha-2 country code. If omitted the system picks the
    * country with the most availability.
@@ -300,9 +333,18 @@ export interface DeviceCreateParams {
   query_country?: string;
 
   /**
-   * Query param
+   * Query param: Deprecated device type aliases are accepted during a compatibility
+   * grace period: dedicated_premium_device maps to android_cloud_phone,
+   * dedicated_physical_device maps to android_physical_phone, dedicated_ios_device
+   * maps to ios_stealth_phone, and dedicated_emulated_device maps to
+   * android_emulator.
    */
-  deviceType?: 'dedicated_physical_device' | 'dedicated_premium_device' | 'dedicated_ios_device';
+  deviceType?:
+    | 'android_cloud_phone'
+    | 'dedicated_premium_device'
+    | 'dedicated_physical_device'
+    | 'dedicated_ios_device'
+    | 'dedicated_emulated_device';
 
   /**
    * Query param: Profile ID to use as device spec
@@ -367,17 +409,45 @@ export interface DeviceCreateParams {
 
 export namespace DeviceCreateParams {
   export interface Proxy {
+    connect?: Proxy.Connect;
+
     name?: string;
 
     smartIp?: boolean;
 
     socks5?: Shared.Socks5;
   }
+
+  export namespace Proxy {
+    export interface Connect {
+      /**
+       * Existing Mobilerun Connect proxy id; its credentials are fetched server-side.
+       */
+      id?: string;
+
+      /**
+       * ISO 3166-1 alpha-2 country code; provisions (or reuses) a rotating residential
+       * Mobilerun Connect proxy for the device.
+       */
+      country?: string;
+    }
+  }
 }
 
 export interface DeviceListParams {
   country?: string;
 
+  /**
+   * Filter to devices created by this user id. Mutually exclusive with mine.
+   */
+  createdBy?: string;
+
+  /**
+   * When true, only return devices created by the calling user (resolved from
+   * X-User-ID, never a client-supplied id).
+   */
+  mine?: boolean;
+
   name?: string;
 
   orderBy?: 'id' | 'createdAt' | 'updatedAt' | 'assignedAt';
@@ -399,10 +469,22 @@ export interface DeviceListParams {
     | 'resetting'
     | 'terminated'
     | 'maintenance'
+    | 'stopped'
     | 'unknown'
   > | null;
 
-  type?: 'dedicated_physical_device' | 'dedicated_premium_device' | 'dedicated_ios_device';
+  /**
+   * Deprecated device type aliases are accepted during a compatibility grace period:
+   * dedicated_premium_device maps to android_cloud_phone, dedicated_physical_device
+   * maps to android_physical_phone, dedicated_ios_device maps to ios_stealth_phone,
+   * and dedicated_emulated_device maps to android_emulator.
+   */
+  type?:
+    | 'android_cloud_phone'
+    | 'dedicated_premium_device'
+    | 'dedicated_physical_device'
+    | 'dedicated_ios_device'
+    | 'dedicated_emulated_device';
 }
 
 export interface DeviceFingerprintParams {

package/src/resources/devices/esim.ts

@@ -8,7 +8,7 @@ import { path } from '../../internal/utils/path';
 
 export class Esim extends APIResource {
   /**
-   * List eSIM subscriptions
+   * Returns the eSIM subscriptions currently provisioned on the device.
    */
   list(
     deviceID: string,
@@ -30,7 +30,7 @@ export class Esim extends APIResource {
   }
 
   /**
-   * Configure eSIM (download profile and/or enable subscription)
+   * Download profile and/or enable subscription.
    */
   activate(
     deviceID: string,
@@ -53,7 +53,8 @@ export class Esim extends APIResource {
   }
 
   /**
-   * Enable an eSIM subscription
+   * Enables the eSIM subscription identified by the subId in the request body so it
+   * becomes the active subscription.
    */
   enable(deviceID: string, params: EsimEnableParams, options?: RequestOptions): APIPromise<void> {
     const { 'X-Device-Display-ID': xDeviceDisplayID, ...body } = params;
@@ -73,7 +74,8 @@ export class Esim extends APIResource {
   }
 
   /**
-   * Delete eSIM subscription
+   * Deletes the eSIM subscription identified by the subId query parameter from the
+   * device.
    */
   remove(deviceID: string, params: EsimRemoveParams, options?: RequestOptions): APIPromise<void> {
     const { subId, 'X-Device-Display-ID': xDeviceDisplayID } = params;

package/src/resources/devices/files.ts

@@ -11,7 +11,8 @@ import { path } from '../../internal/utils/path';
 
 export class Files extends APIResource {
   /**
-   * List files
+   * Lists the files at the directory path given in the path query parameter,
+   * returning each entry's metadata along with the path and total count.
    */
   list(deviceID: string, params: FileListParams, options?: RequestOptions): APIPromise<FileListResponse> {
     const { 'X-Device-Display-ID': xDeviceDisplayID, ...query } = params;
@@ -30,7 +31,7 @@ export class Files extends APIResource {
   }
 
   /**
-   * Delete file
+   * Deletes the file at the path given in the path query parameter from the device.
    */
   delete(deviceID: string, params: FileDeleteParams, options?: RequestOptions): APIPromise<void> {
     const { path: path_, 'X-Device-Display-ID': xDeviceDisplayID } = params;
@@ -50,7 +51,8 @@ export class Files extends APIResource {
   }
 
   /**
-   * Download file
+   * Pulls the file at the given path query parameter from the device and returns its
+   * raw bytes as an octet-stream.
    */
   download(deviceID: string, params: FileDownloadParams, options?: RequestOptions): APIPromise<string> {
     const { 'X-Device-Display-ID': xDeviceDisplayID, ...query } = params;
@@ -69,7 +71,8 @@ export class Files extends APIResource {
   }
 
   /**
-   * Upload file
+   * Uploads a file to the device via multipart form data, writing it into the
+   * directory given by the path query parameter using the uploaded file's name.
    */
   upload(deviceID: string, params: FileUploadParams, options?: RequestOptions): APIPromise<void> {
     const { path: path_, 'X-Device-Display-ID': xDeviceDisplayID, ...body } = params;

package/src/resources/devices/keyboard.ts

@@ -8,7 +8,7 @@ import { path } from '../../internal/utils/path';
 
 export class Keyboard extends APIResource {
   /**
-   * Clear input
+   * Clears the contents of the currently focused text input field.
    */
   clear(
     deviceID: string,
@@ -31,7 +31,7 @@ export class Keyboard extends APIResource {
   }
 
   /**
-   * Input key
+   * Sends a single Android key event to the device, identified by its key code.
    */
   key(deviceID: string, params: KeyboardKeyParams, options?: RequestOptions): APIPromise<void> {
     const { 'X-Device-Display-ID': xDeviceDisplayID, ...body } = params;
@@ -51,7 +51,9 @@ export class Keyboard extends APIResource {
   }
 
   /**
-   * Input text
+   * Types the given text into the focused input field. Supports optionally clearing
+   * the field first and a stealth mode that emulates human typing speed and error
+   * rate on supported devices.
    */
   write(deviceID: string, params: KeyboardWriteParams, options?: RequestOptions): APIPromise<void> {
     const { 'X-Device-Display-ID': xDeviceDisplayID, ...body } = params;

package/src/resources/devices/language.ts

@@ -8,7 +8,7 @@ import { path } from '../../internal/utils/path';
 
 export class Language extends APIResource {
   /**
-   * Get device language/locale
+   * Returns the device's current language/locale as a BCP-47 locale string.
    */
   get(
     deviceID: string,
@@ -30,7 +30,9 @@ export class Language extends APIResource {
   }
 
   /**
-   * Set device language/locale
+   * Sets the device language/locale to the BCP-47 locale in the request body. An
+   * optional restart flag applies the change immediately by restarting the zygote
+   * instead of waiting for the next reboot.
    */
   set(deviceID: string, params: LanguageSetParams, options?: RequestOptions): APIPromise<void> {
     const { 'X-Device-Display-ID': xDeviceDisplayID, ...body } = params;

package/src/resources/devices/location.ts

@@ -9,7 +9,8 @@ import { path } from '../../internal/utils/path';
 
 export class Location extends APIResource {
   /**
-   * Get device location
+   * Returns the device's current simulated GPS location as latitude and longitude.
+   * Devices without geo support return an unsupported-feature error.
    */
   get(
     deviceID: string,
@@ -31,7 +32,8 @@ export class Location extends APIResource {
   }
 
   /**
-   * Set device location
+   * Sets the device's simulated GPS location to the latitude and longitude in the
+   * request body. Devices without geo support return an unsupported-feature error.
    */
   set(deviceID: string, params: LocationSetParams, options?: RequestOptions): APIPromise<void> {
     const { 'X-Device-Display-ID': xDeviceDisplayID, ...body } = params;

package/src/resources/devices/packages.ts

@@ -8,7 +8,8 @@ import { path } from '../../internal/utils/path';
 
 export class Packages extends APIResource {
   /**
-   * List packages
+   * Returns the package names of apps installed on the device. System and protected
+   * packages are excluded unless the corresponding query parameters are set.
    */
   list(
     deviceID: string,

package/src/resources/devices/proxy.ts

@@ -8,7 +8,9 @@ import { path } from '../../internal/utils/path';
 
 export class Proxy extends APIResource {
   /**
-   * Connect proxy
+   * Routes the device's traffic through a SOCKS5 proxy supplied in the request body,
+   * replacing any existing connection. A smartIp option can be used to select an IP
+   * automatically; the legacy flat host/port/user/password fields remain supported.
    */
   connect(deviceID: string, params: ProxyConnectParams, options?: RequestOptions): APIPromise<void> {
     const { 'X-Device-Display-ID': xDeviceDisplayID, ...body } = params;
@@ -28,7 +30,8 @@ export class Proxy extends APIResource {
   }
 
   /**
-   * Disconnect proxy
+   * Disconnects the device's active proxy connection and clears its stored proxy
+   * state. Returns successfully if no proxy is connected.
    */
   disconnect(
     deviceID: string,
@@ -51,7 +54,8 @@ export class Proxy extends APIResource {
   }
 
   /**
-   * Get proxy connection state
+   * Returns the device's current proxy connection state, including whether a proxy
+   * is connected and its protocol and name.
    */
   status(
     deviceID: string,
@@ -93,6 +97,13 @@ export interface ProxyStatusResponse {
 }
 
 export interface ProxyConnectParams {
+  /**
+   * Body param: Mobilerun Connect proxy — pass exactly one of id (use an existing
+   * proxy's credentials) or country (provision or reuse a rotating residential proxy
+   * for the device).
+   */
+  connect?: ProxyConnectParams.Connect;
+
   /**
    * @deprecated Body param
    */
@@ -135,6 +146,24 @@ export interface ProxyConnectParams {
 }
 
 export namespace ProxyConnectParams {
+  /**
+   * Mobilerun Connect proxy — pass exactly one of id (use an existing proxy's
+   * credentials) or country (provision or reuse a rotating residential proxy for the
+   * device).
+   */
+  export interface Connect {
+    /**
+     * Existing Mobilerun Connect proxy id; its credentials are fetched server-side.
+     */
+    id?: string;
+
+    /**
+     * ISO 3166-1 alpha-2 country code; provisions (or reuses) a rotating residential
+     * Mobilerun Connect proxy for the device.
+     */
+    country?: string;
+  }
+
   /**
    * SOCKS5 proxy configuration (required for socks5).
    */

package/src/resources/devices/state.ts

@@ -9,7 +9,8 @@ import { path } from '../../internal/utils/path';
 
 export class State extends APIResource {
   /**
-   * Take screenshot
+   * Captures the device screen and returns it as a PNG image. An optional
+   * hideOverlay query parameter excludes the accessibility overlay from the capture.
    */
   screenshot(
     deviceID: string,
@@ -32,7 +33,7 @@ export class State extends APIResource {
   }
 
   /**
-   * Device time
+   * Returns the device's current wall-clock time as an RFC 3339 timestamp.
    */
   time(
     deviceID: string,
@@ -54,7 +55,9 @@ export class State extends APIResource {
   }
 
   /**
-   * UI state
+   * Returns the current accessibility UI state of the device as a structured tree of
+   * on-screen elements. An optional filter query reduces the result to interactive
+   * elements.
    */
   ui(
     deviceID: string,
@@ -111,6 +114,8 @@ export interface A11YNode {
   resourceId: string;
 
   text: string;
+
+  isVisibleToUser?: boolean;
 }
 
 export namespace A11YNode {

package/src/resources/devices/tasks.ts

@@ -2,16 +2,15 @@
 
 import { APIResource } from '../../core/resource';
 import * as Shared from '../shared';
+import * as ResourcesTasksAPI from '../tasks/tasks';
 import { APIPromise } from '../../core/api-promise';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
-/**
- * Device Management
- */
 export class Tasks extends APIResource {
   /**
-   * List tasks for a device
+   * Returns a paginated list of tasks that have run on the device, along with
+   * pagination metadata.
    */
   list(
     deviceID: string,
@@ -23,7 +22,7 @@ export class Tasks extends APIResource {
 }
 
 export interface TaskListResponse {
-  items: Array<TaskListResponse.Item> | null;
+  items: Array<ResourcesTasksAPI.Task> | null;
 
   pagination: Shared.Meta;
 
@@ -33,16 +32,6 @@ export interface TaskListResponse {
   $schema?: string;
 }
 
-export namespace TaskListResponse {
-  export interface Item {
-    createdAt: string;
-
-    taskId: string;
-
-    updatedAt: string;
-  }
-}
-
 export interface TaskListParams {
   orderBy?: 'id' | 'createdAt' | 'updatedAt' | 'assignedAt';
 

package/src/resources/devices/timezone.ts

@@ -8,7 +8,8 @@ import { path } from '../../internal/utils/path';
 
 export class Timezone extends APIResource {
   /**
-   * Get device timezone
+   * Returns the device's current timezone identifier. Devices that do not support
+   * timezone control return an unsupported-feature error.
    */
   get(
     deviceID: string,
@@ -30,7 +31,8 @@ export class Timezone extends APIResource {
   }
 
   /**
-   * Set device timezone
+   * Sets the device timezone to the identifier in the request body. Devices that do
+   * not support timezone control return an unsupported-feature error.
    */
   set(deviceID: string, params: TimezoneSetParams, options?: RequestOptions): APIPromise<void> {
     const { 'X-Device-Display-ID': xDeviceDisplayID, ...body } = params;