@mobilerun/sdk 4.0.0 → 5.2.0

package/src/resources/devices/devices.ts

@@ -19,7 +19,7 @@ import {
   AppListParams,
   AppListResponse,
   AppStartParams,
-  AppUpdateParams,
+  AppStopParams,
   Apps,
 } from './apps';
 import * as EsimAPI from './esim';
@@ -45,8 +45,10 @@ import {
 } from './files';
 import * as KeyboardAPI from './keyboard';
 import { Keyboard, KeyboardClearParams, KeyboardKeyParams, KeyboardWriteParams } from './keyboard';
+import * as LanguageAPI from './language';
+import { Language, LanguageGetParams, LanguageGetResponse, LanguageSetParams } from './language';
 import * as LocationAPI from './location';
-import { Location, LocationGetParams, LocationGetResponse, LocationSetParams } from './location';
+import { Location, LocationGetParams, LocationSetParams } from './location';
 import * as PackagesAPI from './packages';
 import { PackageListParams, PackageListResponse, Packages } from './packages';
 import * as ProfileAPI from './profile';
@@ -61,60 +63,67 @@ import {
 } from './proxy';
 import * as StateAPI from './state';
 import {
+  A11YNode,
   Rect,
   State,
   StateScreenshotParams,
   StateScreenshotResponse,
+  StateTimeParams,
+  StateTimeResponse,
   StateUiParams,
   StateUiResponse,
 } from './state';
 import * as TasksAPI from './tasks';
 import { TaskListParams, TaskListResponse, Tasks } from './tasks';
-import * as TimeAPI from './time';
-import {
-  Time,
-  TimeSetTimezoneParams,
-  TimeTimeParams,
-  TimeTimeResponse,
-  TimeTimezoneParams,
-  TimeTimezoneResponse,
-} from './time';
+import * as TimezoneAPI from './timezone';
+import { Timezone, TimezoneGetParams, TimezoneGetResponse, TimezoneSetParams } from './timezone';
 import { APIPromise } from '../../core/api-promise';
 import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
 export class Devices extends APIResource {
-  time: TimeAPI.Time = new TimeAPI.Time(this._client);
-  profile: ProfileAPI.Profile = new ProfileAPI.Profile(this._client);
-  files: FilesAPI.Files = new FilesAPI.Files(this._client);
-  proxy: ProxyAPI.Proxy = new ProxyAPI.Proxy(this._client);
-  location: LocationAPI.Location = new LocationAPI.Location(this._client);
   actions: ActionsAPI.Actions = new ActionsAPI.Actions(this._client);
-  state: StateAPI.State = new StateAPI.State(this._client);
   apps: AppsAPI.Apps = new AppsAPI.Apps(this._client);
-  packages: PackagesAPI.Packages = new PackagesAPI.Packages(this._client);
+  esim: EsimAPI.Esim = new EsimAPI.Esim(this._client);
+  files: FilesAPI.Files = new FilesAPI.Files(this._client);
   keyboard: KeyboardAPI.Keyboard = new KeyboardAPI.Keyboard(this._client);
+  location: LocationAPI.Location = new LocationAPI.Location(this._client);
+  packages: PackagesAPI.Packages = new PackagesAPI.Packages(this._client);
+  profile: ProfileAPI.Profile = new ProfileAPI.Profile(this._client);
+  proxy: ProxyAPI.Proxy = new ProxyAPI.Proxy(this._client);
+  state: StateAPI.State = new StateAPI.State(this._client);
   tasks: TasksAPI.Tasks = new TasksAPI.Tasks(this._client);
-  esim: EsimAPI.Esim = new EsimAPI.Esim(this._client);
+  timezone: TimezoneAPI.Timezone = new TimezoneAPI.Timezone(this._client);
+  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 { deviceType, ...body } = params;
-    return this._client.post('/devices', { query: { deviceType }, body, ...options });
+    const { billing, query_country, deviceType, profileId, ...body } = params;
+    return this._client.post('/devices', {
+      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 = {},
@@ -124,21 +133,71 @@ 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);
   }
 
   /**
-   * Update device name
+   * 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,
+    params: DeviceFingerprintParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<DeviceFingerprintResponse> {
+    const { 'X-Device-Display-ID': xDeviceDisplayID } = params ?? {};
+    return this._client.get(path`/devices/${deviceID}/fingerprint`, {
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xDeviceDisplayID?.toString() != null ?
+            { 'X-Device-Display-ID': xDeviceDisplayID?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * 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`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * 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`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * 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}`, {
@@ -149,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);
@@ -186,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;
 }
 
@@ -206,15 +276,85 @@ export interface DeviceListResponse {
 
 export type DeviceCountResponse = { [key: string]: number };
 
+export interface DeviceFingerprintResponse {
+  carrier: Shared.DeviceCarrier;
+
+  display: DeviceFingerprintResponse.Display;
+
+  identifiers: Shared.DeviceIdentifiers;
+
+  model: DeviceFingerprintResponse.Model;
+
+  /**
+   * A URL to the JSON Schema for this object.
+   */
+  $schema?: string;
+}
+
+export namespace DeviceFingerprintResponse {
+  export interface Display {
+    densityDpi?: number;
+
+    height?: number;
+
+    width?: number;
+  }
+
+  export interface Model {
+    aospVersion?: string;
+
+    brand?: string;
+
+    device?: string;
+
+    hardware?: string;
+
+    imageRepository?: string;
+
+    manufacturer?: string;
+
+    model?: string;
+  }
+}
+
 export interface DeviceCreateParams {
   /**
-   * Query param
+   * 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.
+   */
+  query_country?: string;
+
+  /**
+   * 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'
+    | 'android_cloud_phone'
     | 'dedicated_premium_device'
-    | 'dedicated_emulated_device'
-    | 'dedicated_ios_device';
+    | 'dedicated_physical_device'
+    | 'dedicated_ios_device'
+    | 'dedicated_emulated_device';
+
+  /**
+   * Query param: Profile ID to use as device spec
+   */
+  profileId?: string;
+
+  /**
+   * Body param
+   */
+  androidVersion?: number;
 
   /**
    * Body param
@@ -226,6 +366,11 @@ export interface DeviceCreateParams {
    */
   carrier?: Shared.DeviceCarrier;
 
+  /**
+   * Body param
+   */
+  body_country?: string;
+
   /**
    * Body param
    */
@@ -236,6 +381,16 @@ export interface DeviceCreateParams {
    */
   identifiers?: Shared.DeviceIdentifiers;
 
+  /**
+   * Body param
+   */
+  locale?: string;
+
+  /**
+   * Body param
+   */
+  location?: Shared.Location;
+
   /**
    * Body param
    */
@@ -245,28 +400,36 @@ export interface DeviceCreateParams {
    * Body param
    */
   proxy?: DeviceCreateParams.Proxy;
+
+  /**
+   * Body param
+   */
+  timezone?: string;
 }
 
 export namespace DeviceCreateParams {
   export interface Proxy {
+    connect?: Proxy.Connect;
+
     name?: string;
 
     smartIp?: boolean;
 
-    socks5?: Proxy.Socks5;
-
-    wireguard?: string;
+    socks5?: Shared.Socks5;
   }
 
   export namespace Proxy {
-    export interface Socks5 {
-      host: string;
-
-      password: string;
-
-      port: number;
-
-      user: string;
+    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;
     }
   }
 }
@@ -274,6 +437,17 @@ export namespace DeviceCreateParams {
 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';
@@ -287,14 +461,34 @@ export interface DeviceListParams {
   providerId?: string;
 
   state?: Array<
-    'creating' | 'assigned' | 'ready' | 'rebooting' | 'migrating' | 'terminated' | 'maintenance' | 'unknown'
+    | 'creating'
+    | 'assigned'
+    | 'ready'
+    | 'rebooting'
+    | 'migrating'
+    | 'resetting'
+    | 'terminated'
+    | 'maintenance'
+    | 'stopped'
+    | 'unknown'
   > | null;
 
+  /**
+   * 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?:
-    | 'dedicated_physical_device'
+    | 'android_cloud_phone'
     | 'dedicated_premium_device'
-    | 'dedicated_emulated_device'
-    | 'dedicated_ios_device';
+    | 'dedicated_physical_device'
+    | 'dedicated_ios_device'
+    | 'dedicated_emulated_device';
+}
+
+export interface DeviceFingerprintParams {
+  'X-Device-Display-ID'?: number;
 }
 
 export interface DeviceSetNameParams {
@@ -307,40 +501,62 @@ export interface DeviceTerminateParams {
   terminateAt?: string;
 }
 
-Devices.Time = Time;
-Devices.Profile = Profile;
-Devices.Files = Files;
-Devices.Proxy = ProxyAPIProxy;
-Devices.Location = Location;
 Devices.Actions = Actions;
-Devices.State = State;
 Devices.Apps = Apps;
-Devices.Packages = Packages;
+Devices.Esim = Esim;
+Devices.Files = Files;
 Devices.Keyboard = Keyboard;
+Devices.Location = Location;
+Devices.Packages = Packages;
+Devices.Profile = Profile;
+Devices.Proxy = ProxyAPIProxy;
+Devices.State = State;
 Devices.Tasks = Tasks;
-Devices.Esim = Esim;
+Devices.Timezone = Timezone;
+Devices.Language = Language;
 
 export declare namespace Devices {
   export {
     type Device as Device,
     type DeviceListResponse as DeviceListResponse,
     type DeviceCountResponse as DeviceCountResponse,
+    type DeviceFingerprintResponse as DeviceFingerprintResponse,
     type DeviceCreateParams as DeviceCreateParams,
     type DeviceListParams as DeviceListParams,
+    type DeviceFingerprintParams as DeviceFingerprintParams,
     type DeviceSetNameParams as DeviceSetNameParams,
     type DeviceTerminateParams as DeviceTerminateParams,
   };
 
   export {
-    Time as Time,
-    type TimeTimeResponse as TimeTimeResponse,
-    type TimeTimezoneResponse as TimeTimezoneResponse,
-    type TimeSetTimezoneParams as TimeSetTimezoneParams,
-    type TimeTimeParams as TimeTimeParams,
-    type TimeTimezoneParams as TimeTimezoneParams,
+    Actions as Actions,
+    type ActionOverlayVisibleResponse as ActionOverlayVisibleResponse,
+    type ActionGlobalParams as ActionGlobalParams,
+    type ActionOverlayVisibleParams as ActionOverlayVisibleParams,
+    type ActionSetOverlayVisibleParams as ActionSetOverlayVisibleParams,
+    type ActionSwipeParams as ActionSwipeParams,
+    type ActionTapParams as ActionTapParams,
   };
 
-  export { Profile as Profile, type ProfileUpdateParams as ProfileUpdateParams };
+  export {
+    Apps as Apps,
+    type AppListResponse as AppListResponse,
+    type AppListParams as AppListParams,
+    type AppDeleteParams as AppDeleteParams,
+    type AppInstallParams as AppInstallParams,
+    type AppStartParams as AppStartParams,
+    type AppStopParams as AppStopParams,
+  };
+
+  export {
+    Esim as Esim,
+    type EsimListResponse as EsimListResponse,
+    type EsimActivateResponse as EsimActivateResponse,
+    type EsimListParams as EsimListParams,
+    type EsimActivateParams as EsimActivateParams,
+    type EsimEnableParams as EsimEnableParams,
+    type EsimRemoveParams as EsimRemoveParams,
+  };
 
   export {
     Files as Files,
@@ -354,71 +570,59 @@ export declare namespace Devices {
   };
 
   export {
-    ProxyAPIProxy as Proxy,
-    type ProxyStatusResponse as ProxyStatusResponse,
-    type ProxyConnectParams as ProxyConnectParams,
-    type ProxyDisconnectParams as ProxyDisconnectParams,
-    type ProxyStatusParams as ProxyStatusParams,
+    Keyboard as Keyboard,
+    type KeyboardClearParams as KeyboardClearParams,
+    type KeyboardKeyParams as KeyboardKeyParams,
+    type KeyboardWriteParams as KeyboardWriteParams,
   };
 
   export {
     Location as Location,
-    type LocationGetResponse as LocationGetResponse,
     type LocationGetParams as LocationGetParams,
     type LocationSetParams as LocationSetParams,
   };
 
   export {
-    Actions as Actions,
-    type ActionOverlayVisibleResponse as ActionOverlayVisibleResponse,
-    type ActionGlobalParams as ActionGlobalParams,
-    type ActionOverlayVisibleParams as ActionOverlayVisibleParams,
-    type ActionSetOverlayVisibleParams as ActionSetOverlayVisibleParams,
-    type ActionSwipeParams as ActionSwipeParams,
-    type ActionTapParams as ActionTapParams,
+    Packages as Packages,
+    type PackageListResponse as PackageListResponse,
+    type PackageListParams as PackageListParams,
+  };
+
+  export { Profile as Profile, type ProfileUpdateParams as ProfileUpdateParams };
+
+  export {
+    ProxyAPIProxy as Proxy,
+    type ProxyStatusResponse as ProxyStatusResponse,
+    type ProxyConnectParams as ProxyConnectParams,
+    type ProxyDisconnectParams as ProxyDisconnectParams,
+    type ProxyStatusParams as ProxyStatusParams,
   };
 
   export {
     State as State,
+    type A11YNode as A11YNode,
     type Rect as Rect,
     type StateScreenshotResponse as StateScreenshotResponse,
+    type StateTimeResponse as StateTimeResponse,
     type StateUiResponse as StateUiResponse,
     type StateScreenshotParams as StateScreenshotParams,
+    type StateTimeParams as StateTimeParams,
     type StateUiParams as StateUiParams,
   };
 
-  export {
-    Apps as Apps,
-    type AppListResponse as AppListResponse,
-    type AppUpdateParams as AppUpdateParams,
-    type AppListParams as AppListParams,
-    type AppDeleteParams as AppDeleteParams,
-    type AppInstallParams as AppInstallParams,
-    type AppStartParams as AppStartParams,
-  };
-
-  export {
-    Packages as Packages,
-    type PackageListResponse as PackageListResponse,
-    type PackageListParams as PackageListParams,
-  };
+  export { Tasks as Tasks, type TaskListResponse as TaskListResponse, type TaskListParams as TaskListParams };
 
   export {
-    Keyboard as Keyboard,
-    type KeyboardClearParams as KeyboardClearParams,
-    type KeyboardKeyParams as KeyboardKeyParams,
-    type KeyboardWriteParams as KeyboardWriteParams,
+    Timezone as Timezone,
+    type TimezoneGetResponse as TimezoneGetResponse,
+    type TimezoneGetParams as TimezoneGetParams,
+    type TimezoneSetParams as TimezoneSetParams,
   };
 
-  export { Tasks as Tasks, type TaskListResponse as TaskListResponse, type TaskListParams as TaskListParams };
-
   export {
-    Esim as Esim,
-    type EsimListResponse as EsimListResponse,
-    type EsimActivateResponse as EsimActivateResponse,
-    type EsimListParams as EsimListParams,
-    type EsimActivateParams as EsimActivateParams,
-    type EsimEnableParams as EsimEnableParams,
-    type EsimRemoveParams as EsimRemoveParams,
+    Language as Language,
+    type LanguageGetResponse as LanguageGetResponse,
+    type LanguageGetParams as LanguageGetParams,
+    type LanguageSetParams as LanguageSetParams,
   };
 }

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;
@@ -152,12 +154,19 @@ export interface EsimActivateParams {
   /**
    * Body param
    */
-  matchingId: string;
+  smDpAddr: string;
+
+  /**
+   * Body param: Optional carrier-issued confirmation code (the 4th LPA segment).
+   * Required only for plans whose SM-DP+ challenges the device for one. Requires
+   * matchingId — the LPA spec only interprets segment 4 when segment 3 is present.
+   */
+  confirmationCode?: string;
 
   /**
    * Body param
    */
-  smDpAddr: string;
+  matchingId?: string;
 
   /**
    * Header param