@mobilerun/sdk 5.5.0 → 6.0.0

package/src/resources/devices/devices.ts

@@ -77,6 +77,8 @@ import {
   RecordingDeleteParams,
   RecordingListParams,
   RecordingListResponse,
+  RecordingScreenshotsParams,
+  RecordingScreenshotsResponse,
   RecordingStartParams,
   RecordingStartResponse,
   RecordingStatusParams,
@@ -87,6 +89,16 @@ import {
   RecordingVideoParams,
   Recordings,
 } from './recordings';
+import * as ScreenshotsAPI from './screenshots';
+import {
+  ScreenshotCaptureParams,
+  ScreenshotCaptureResponse,
+  ScreenshotDeleteParams,
+  ScreenshotImageParams,
+  ScreenshotListParams,
+  ScreenshotListResponse,
+  Screenshots,
+} from './screenshots';
 import * as StateAPI from './state';
 import {
   A11YNode,
@@ -142,6 +154,7 @@ export class Devices extends APIResource {
   packages: PackagesAPI.Packages = new PackagesAPI.Packages(this._client);
   profile: ProfileAPI.Profile = new ProfileAPI.Profile(this._client);
   proxy: ProxyAPI.Proxy = new ProxyAPI.Proxy(this._client);
+  screenshots: ScreenshotsAPI.Screenshots = new ScreenshotsAPI.Screenshots(this._client);
   state: StateAPI.State = new StateAPI.State(this._client);
   tasks: TasksAPI.Tasks = new TasksAPI.Tasks(this._client);
   clipboard: ClipboardAPI.Clipboard = new ClipboardAPI.Clipboard(this._client);
@@ -155,11 +168,10 @@ export class Devices extends APIResource {
   trafficSessions: TrafficSessionsAPI.TrafficSessions = new TrafficSessionsAPI.TrafficSessions(this._client);
 
   /**
-   * 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.
+   * Requests a new device from the specification in the request body. Optional query
+   * parameters select the canonical device type, country, billing mode, and base
+   * profile. Returns the device, its resolved billing strategy, and its stream
+   * token.
    */
   create(params: DeviceCreateParams, options?: RequestOptions): APIPromise<DeviceCreateResponse> {
     const { billing, query_country, deviceType, profileId, ...body } = params;
@@ -181,6 +193,10 @@ export class Devices extends APIResource {
 
   /**
    * Returns a paginated list of the user's devices along with pagination metadata.
+   * By default every device except terminated and unknown-state ones is listed,
+   * including stopped and maintenance devices; narrow with e.g. `state=ready` or
+   * `state=stopped,maintenance`, and pass `state=terminated` or `state=unknown` to
+   * see those.
    */
   list(
     query: DeviceListParams | null | undefined = {},
@@ -190,7 +206,11 @@ export class Devices extends APIResource {
   }
 
   /**
-   * Returns the number of claimed devices for the user, broken down by device type.
+   * Deprecated: use GET /devices/summary instead. Returns the number of active
+   * claimed devices for the user, broken down by device type, in the legacy response
+   * shape.
+   *
+   * @deprecated
    */
   count(options?: RequestOptions): APIPromise<DeviceCountResponse> {
     return this._client.get('/devices/count', options);
@@ -256,11 +276,8 @@ export class Devices extends APIResource {
   }
 
   /**
-   * Returns the set of capabilities supported by this device. For a legacy device
-   * this reflects the live instance's actual tools rather than its static type; for
-   * a core-managed device it is resolved from provider/pool configuration without
-   * guaranteeing a live instance. Used to determine which tools and features are
-   * available for the device.
+   * Returns the set of capabilities supported by this device. Used to determine
+   * which tools and features are available for the device.
    */
   retrieveCapabilities(
     deviceID: string,
@@ -294,11 +311,26 @@ export class Devices extends APIResource {
   }
 
   /**
-   * 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.
+   * Returns the total number of the user's devices and counts grouped by current
+   * state and device type.
    */
-  terminate(deviceID: string, body: DeviceTerminateParams, options?: RequestOptions): APIPromise<void> {
+  summary(
+    query: DeviceSummaryParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<DeviceSummaryResponse> {
+    return this._client.get('/devices/summary', { query, ...options });
+  }
+
+  /**
+   * Terminates the device and releases its resources. The optional `terminateAt` and
+   * `previousDeviceId` body fields are not available to API-key callers; requests
+   * that set them are rejected with 401.
+   */
+  terminate(
+    deviceID: string,
+    body: DeviceTerminateParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<void> {
     return this._client.delete(path`/devices/${deviceID}`, {
       body,
       ...options,
@@ -639,6 +671,19 @@ export interface DeviceSetNameResponse {
   userId?: string;
 }
 
+export interface DeviceSummaryResponse {
+  byState: { [key: string]: number };
+
+  byType: { [key: string]: number };
+
+  total: number;
+
+  /**
+   * A URL to the JSON Schema for this object.
+   */
+  $schema?: string;
+}
+
 export interface DeviceWaitReadyResponse {
   id: string;
 
@@ -692,10 +737,13 @@ export interface DeviceWaitReadyResponse {
 
 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.
+   * Query param: Billing mode. 'auto' tries subscription first, then minute billing
+   * if no subscription entitlement exists or all subscription slots are in use,
+   * provided minute billing is enabled. When subscription billing is disabled, auto
+   * uses minutes directly. Billing-service failures never trigger fallback.
+   * 'subscription' requires an available subscription slot and never falls back.
+   * 'minute' uses minute billing only, subject to balance and concurrency checks.
+   * Modes depend on the device type's billing configuration.
    */
   billing?: 'auto' | 'subscription' | 'minute';
 
@@ -706,18 +754,12 @@ export interface DeviceCreateParams {
   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.
+   * Query param: Use android*cloud_phone for a cloud Android phone. Only canonical
+   * identifiers are accepted. Other backends are deployment-specific; recognized but
+   * unavailable types return DEVICE_TYPE_UNAVAILABLE (422). Retired dedicated*\*
+   * aliases are rejected with a canonical replacement.
    */
-  deviceType?:
-    | 'android_cloud_phone'
-    | 'dedicated_premium_device'
-    | 'dedicated_physical_device'
-    | 'dedicated_ios_device'
-    | 'dedicated_emulated_device';
+  deviceType?: string;
 
   /**
    * Query param: Profile ID to use as device spec
@@ -820,29 +862,56 @@ export namespace DeviceCreateParams {
 export interface DeviceListParams {
   country?: string;
 
+  /**
+   * Include devices created at or after this RFC3339 timestamp.
+   */
+  createdAfter?: string;
+
+  /**
+   * Include devices created before this RFC3339 timestamp (exclusive). Must be later
+   * than createdAfter when both are set.
+   */
+  createdBefore?: 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).
+   * When true, only return devices created by the authenticated caller.
    */
   mine?: boolean;
 
   name?: string;
 
-  orderBy?: 'id' | 'createdAt' | 'updatedAt' | 'assignedAt';
+  orderBy?: 'id' | 'createdAt' | 'updatedAt' | 'assignedAt' | 'gridPosition';
 
   orderByDirection?: 'asc' | 'desc';
 
+  /**
+   * Filter by owner IDs. Comma-separated or repeated parameters. Restricted to
+   * platform administrators.
+   */
+  ownerId?: Array<string> | null;
+
   page?: number;
 
   pageSize?: number;
 
+  /**
+   * Filter by the device's platform as served in the platform field (runtime,
+   * announced, else type-derived).
+   */
+  platform?: 'android' | 'ios';
+
   providerId?: string;
 
+  /**
+   * Filter by current device state. Comma-separated (state=ready,stopped). Defaults
+   * to every state except terminated and unknown, so stopped and maintenance devices
+   * are listed; pass state=terminated or state=unknown to see those.
+   */
   state?: Array<
     | 'creating'
     | 'assigned'
@@ -857,17 +926,16 @@ export interface DeviceListParams {
   > | 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.
+   * Canonical device type. Retired dedicated\_\* aliases are no longer accepted.
+   * Availability depends on the deployment.
    */
   type?:
     | 'android_cloud_phone'
-    | 'dedicated_premium_device'
-    | 'dedicated_physical_device'
-    | 'dedicated_ios_device'
-    | 'dedicated_emulated_device';
+    | 'android_physical_phone'
+    | 'ios_stealth_phone'
+    | 'android_emulator'
+    | 'ios_simulator'
+    | 'device_slot';
 }
 
 export interface DeviceFingerprintParams {
@@ -878,6 +946,21 @@ export interface DeviceSetNameParams {
   name: string;
 }
 
+export interface DeviceSummaryParams {
+  state?: Array<
+    | 'creating'
+    | 'assigned'
+    | 'ready'
+    | 'rebooting'
+    | 'migrating'
+    | 'resetting'
+    | 'terminated'
+    | 'maintenance'
+    | 'stopped'
+    | 'unknown'
+  > | null;
+}
+
 export interface DeviceTerminateParams {
   previousDeviceId?: string;
 
@@ -893,6 +976,7 @@ Devices.Location = Location;
 Devices.Packages = Packages;
 Devices.Profile = Profile;
 Devices.Proxy = ProxyAPIProxy;
+Devices.Screenshots = Screenshots;
 Devices.State = State;
 Devices.Tasks = Tasks;
 Devices.Clipboard = Clipboard;
@@ -914,11 +998,13 @@ export declare namespace Devices {
     type DeviceFingerprintResponse as DeviceFingerprintResponse,
     type DeviceRetrieveCapabilitiesResponse as DeviceRetrieveCapabilitiesResponse,
     type DeviceSetNameResponse as DeviceSetNameResponse,
+    type DeviceSummaryResponse as DeviceSummaryResponse,
     type DeviceWaitReadyResponse as DeviceWaitReadyResponse,
     type DeviceCreateParams as DeviceCreateParams,
     type DeviceListParams as DeviceListParams,
     type DeviceFingerprintParams as DeviceFingerprintParams,
     type DeviceSetNameParams as DeviceSetNameParams,
+    type DeviceSummaryParams as DeviceSummaryParams,
     type DeviceTerminateParams as DeviceTerminateParams,
   };
 
@@ -999,6 +1085,16 @@ export declare namespace Devices {
     type ProxyStatusParams as ProxyStatusParams,
   };
 
+  export {
+    Screenshots as Screenshots,
+    type ScreenshotListResponse as ScreenshotListResponse,
+    type ScreenshotCaptureResponse as ScreenshotCaptureResponse,
+    type ScreenshotListParams as ScreenshotListParams,
+    type ScreenshotDeleteParams as ScreenshotDeleteParams,
+    type ScreenshotCaptureParams as ScreenshotCaptureParams,
+    type ScreenshotImageParams as ScreenshotImageParams,
+  };
+
   export {
     State as State,
     type A11YNode as A11YNode,
@@ -1060,11 +1156,13 @@ export declare namespace Devices {
   export {
     Recordings as Recordings,
     type RecordingListResponse as RecordingListResponse,
+    type RecordingScreenshotsResponse as RecordingScreenshotsResponse,
     type RecordingStartResponse as RecordingStartResponse,
     type RecordingStatusResponse as RecordingStatusResponse,
     type RecordingStopResponse as RecordingStopResponse,
     type RecordingListParams as RecordingListParams,
     type RecordingDeleteParams as RecordingDeleteParams,
+    type RecordingScreenshotsParams as RecordingScreenshotsParams,
     type RecordingStartParams as RecordingStartParams,
     type RecordingStatusParams as RecordingStatusParams,
     type RecordingStopParams as RecordingStopParams,

package/src/resources/devices/index.ts

@@ -39,11 +39,13 @@ export {
   type DeviceFingerprintResponse,
   type DeviceRetrieveCapabilitiesResponse,
   type DeviceSetNameResponse,
+  type DeviceSummaryResponse,
   type DeviceWaitReadyResponse,
   type DeviceCreateParams,
   type DeviceListParams,
   type DeviceFingerprintParams,
   type DeviceSetNameParams,
+  type DeviceSummaryParams,
   type DeviceTerminateParams,
 } from './devices';
 export {
@@ -107,17 +109,28 @@ export {
 export {
   Recordings,
   type RecordingListResponse,
+  type RecordingScreenshotsResponse,
   type RecordingStartResponse,
   type RecordingStatusResponse,
   type RecordingStopResponse,
   type RecordingListParams,
   type RecordingDeleteParams,
+  type RecordingScreenshotsParams,
   type RecordingStartParams,
   type RecordingStatusParams,
   type RecordingStopParams,
   type RecordingTrajectoryParams,
   type RecordingVideoParams,
 } from './recordings';
+export {
+  Screenshots,
+  type ScreenshotListResponse,
+  type ScreenshotCaptureResponse,
+  type ScreenshotListParams,
+  type ScreenshotDeleteParams,
+  type ScreenshotCaptureParams,
+  type ScreenshotImageParams,
+} from './screenshots';
 export {
   State,
   type A11YNode,

package/src/resources/devices/keyboard.ts

@@ -114,12 +114,19 @@ export interface KeyboardWriteParams {
   errorRate?: number;
 
   /**
-   * Body param
+   * Body param: Request human-like input where supported by the device. Defaults to
+   * false.
+   */
+  humanize?: boolean;
+
+  /**
+   * @deprecated Body param: Deprecated: use humanize. Both names must agree when
+   * supplied together.
    */
   stealth?: boolean;
 
   /**
-   * Body param: Words per minute for stealth typing. 0 uses portal default.
+   * Body param: Words per minute for humanized typing. 0 uses the device default.
    */
   wpm?: number;
 

package/src/resources/devices/recordings.ts

@@ -29,6 +29,20 @@ export class Recordings extends APIResource {
     });
   }
 
+  /**
+   * Screenshots saved into the recording with
+   * `GET /devices/{deviceId}/screenshot?save=true`, oldest first, each with a
+   * presigned download URL.
+   */
+  screenshots(
+    recordingID: string,
+    params: RecordingScreenshotsParams,
+    options?: RequestOptions,
+  ): APIPromise<RecordingScreenshotsResponse | null> {
+    const { deviceId } = params;
+    return this._client.get(path`/devices/${deviceId}/recordings/${recordingID}/screenshots`, options);
+  }
+
   /**
    * Start a device recording
    */
@@ -148,6 +162,24 @@ export namespace RecordingListResponse {
   }
 }
 
+export type RecordingScreenshotsResponse =
+  Array<RecordingScreenshotsResponse.RecordingScreenshotsResponseItem>;
+
+export namespace RecordingScreenshotsResponse {
+  export interface RecordingScreenshotsResponseItem {
+    id: string;
+
+    capturedAt: string;
+
+    sizeBytes: number;
+
+    /**
+     * Presigned download URL, valid for 15 minutes.
+     */
+    url: string;
+  }
+}
+
 export interface RecordingStartResponse {
   id: string;
 
@@ -317,22 +349,28 @@ export interface RecordingDeleteParams {
   deviceId: string;
 }
 
+export interface RecordingScreenshotsParams {
+  deviceId: string;
+}
+
 export interface RecordingStartParams {
   name?: string;
 
   /**
    * Capture quality from 1 (lowest) to 10 (full stream quality). Defaults to the
-   * device's full quality. Honored by devices recording through the portal stream
-   * bridge.
+   * device's full quality. Honored only by devices that support adjustable capture
+   * quality.
    */
   quality?: number;
 
   retentionDays?: number;
 
   /**
-   * Artifacts to capture: trajectory (input actions), video, and audio (captured
-   * into the video artifact, so it requires video; honored by portal stream-bridge
-   * recorders). Defaults to trajectory and video.
+   * Artifacts to capture: trajectory (input actions; on some devices only when the
+   * device announces trajectory capture), video, and audio (captured into the video
+   * artifact, so it requires video; honored only by devices that support audio
+   * capture). Defaults to trajectory and video, narrowed to what the device
+   * produces.
    */
   types?: Array<string> | null;
 }
@@ -356,11 +394,13 @@ export interface RecordingVideoParams {
 export declare namespace Recordings {
   export {
     type RecordingListResponse as RecordingListResponse,
+    type RecordingScreenshotsResponse as RecordingScreenshotsResponse,
     type RecordingStartResponse as RecordingStartResponse,
     type RecordingStatusResponse as RecordingStatusResponse,
     type RecordingStopResponse as RecordingStopResponse,
     type RecordingListParams as RecordingListParams,
     type RecordingDeleteParams as RecordingDeleteParams,
+    type RecordingScreenshotsParams as RecordingScreenshotsParams,
     type RecordingStartParams as RecordingStartParams,
     type RecordingStatusParams as RecordingStatusParams,
     type RecordingStopParams as RecordingStopParams,

package/src/resources/devices/screenshots.ts

@@ -0,0 +1,140 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+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 Screenshots extends APIResource {
+  /**
+   * Saved screenshots, newest first. Pass nextCursor as cursor to retrieve the next
+   * page.
+   */
+  list(
+    deviceID: string,
+    query: ScreenshotListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ScreenshotListResponse> {
+    return this._client.get(path`/devices/${deviceID}/screenshots`, { query, ...options });
+  }
+
+  /**
+   * Delete a device screenshot
+   */
+  delete(screenshotID: string, params: ScreenshotDeleteParams, options?: RequestOptions): APIPromise<void> {
+    const { deviceId } = params;
+    return this._client.delete(path`/devices/${deviceId}/screenshots/${screenshotID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * Captures the device screen and returns it as a PNG image. Pass save=true to
+   * store it as device media.
+   */
+  capture(
+    deviceID: string,
+    params: ScreenshotCaptureParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<string> {
+    const { hideOverlay, save, 'X-Device-Display-ID': xDeviceDisplayID } = params ?? {};
+    return this._client.post(path`/devices/${deviceID}/screenshots`, {
+      query: { hideOverlay, save },
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(xDeviceDisplayID?.toString() != null ?
+            { 'X-Device-Display-ID': xDeviceDisplayID?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
+  /**
+   * Redirects to a presigned PNG URL valid for 15 minutes.
+   */
+  image(screenshotID: string, params: ScreenshotImageParams, options?: RequestOptions): APIPromise<void> {
+    const { deviceId } = params;
+    return this._client.get(path`/devices/${deviceId}/screenshots/${screenshotID}/image`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export interface ScreenshotListResponse {
+  items: Array<ScreenshotListResponse.Item> | null;
+
+  nextCursor: string;
+
+  /**
+   * A URL to the JSON Schema for this object.
+   */
+  $schema?: string;
+}
+
+export namespace ScreenshotListResponse {
+  export interface Item {
+    id: string;
+
+    capturedAt: string;
+
+    deviceId: string;
+
+    expiresAt: string;
+
+    recordingId: string | null;
+
+    sizeBytes: number;
+  }
+}
+
+export type ScreenshotCaptureResponse = string;
+
+export interface ScreenshotListParams {
+  cursor?: string;
+
+  limit?: number;
+}
+
+export interface ScreenshotDeleteParams {
+  deviceId: string;
+}
+
+export interface ScreenshotCaptureParams {
+  /**
+   * Query param
+   */
+  hideOverlay?: boolean;
+
+  /**
+   * Query param: Store the screenshot as device media: in the owner's active
+   * recording, or standalone for 7 days. Without save=true nothing is stored. The
+   * PNG response is unchanged; X-Screenshot-Saved reports whether it was stored.
+   */
+  save?: boolean;
+
+  /**
+   * Header param
+   */
+  'X-Device-Display-ID'?: number;
+}
+
+export interface ScreenshotImageParams {
+  deviceId: string;
+}
+
+export declare namespace Screenshots {
+  export {
+    type ScreenshotListResponse as ScreenshotListResponse,
+    type ScreenshotCaptureResponse as ScreenshotCaptureResponse,
+    type ScreenshotListParams as ScreenshotListParams,
+    type ScreenshotDeleteParams as ScreenshotDeleteParams,
+    type ScreenshotCaptureParams as ScreenshotCaptureParams,
+    type ScreenshotImageParams as ScreenshotImageParams,
+  };
+}

package/src/resources/devices/state.ts

@@ -8,8 +8,11 @@ import { path } from '../../internal/utils/path';
 
 export class State extends APIResource {
   /**
-   * Captures the device screen and returns it as a PNG image. An optional
-   * hideOverlay query parameter excludes the accessibility overlay from the capture.
+   * Deprecated: use POST /devices/{deviceId}/screenshots. Captures the device screen
+   * and returns it as a PNG image. An optional hideOverlay query parameter excludes
+   * the accessibility overlay from the capture.
+   *
+   * @deprecated
    */
   screenshot(
     deviceID: string,
@@ -214,6 +217,13 @@ export interface StateScreenshotParams {
    */
   hideOverlay?: boolean;
 
+  /**
+   * Query param: Store the screenshot as device media: in the owner's active
+   * recording, or standalone for 7 days. Without save=true nothing is stored. The
+   * PNG response is unchanged; X-Screenshot-Saved reports whether it was stored.
+   */
+  save?: boolean;
+
   /**
    * Header param
    */