@mobilerun/sdk 5.5.0 → 6.0.0

package/src/resources/workflows/actions/actions.ts

@@ -15,6 +15,10 @@ export class Actions extends APIResource {
    * Create a reusable action from a catalog entry (`catalogEntryId`), with an
    * optional `params` object supplying the values for that entry's service method.
    * Returns 400 if the params are invalid for the chosen catalog entry.
+   *
+   * Supports an optional `Idempotency-Key` header (1-255 printable ASCII
+   * characters). Replays with the same key and an identical body return the original
+   * 201; a changed body under the same key returns 422 `idempotency_key_reused`.
    */
   create(body: ActionCreateParams, options?: RequestOptions): APIPromise<ActionCreateResponse> {
     return this._client.post('/actions', { body, ...options });
@@ -81,7 +85,7 @@ export namespace ActionCreateResponse {
 
     ownerId: string;
 
-    service: 'tasks_api' | 'devices_api' | 'agents_api' | 'webhooks';
+    service: 'tasks_api' | 'devices_api' | 'agents_api' | 'webhooks' | 'integrations_api';
 
     updatedAt: string | null;
 
@@ -118,7 +122,7 @@ export namespace ActionRetrieveResponse {
 
     ownerId: string;
 
-    service: 'tasks_api' | 'devices_api' | 'agents_api' | 'webhooks';
+    service: 'tasks_api' | 'devices_api' | 'agents_api' | 'webhooks' | 'integrations_api';
 
     updatedAt: string | null;
 
@@ -155,7 +159,7 @@ export namespace ActionUpdateResponse {
 
     ownerId: string;
 
-    service: 'tasks_api' | 'devices_api' | 'agents_api' | 'webhooks';
+    service: 'tasks_api' | 'devices_api' | 'agents_api' | 'webhooks' | 'integrations_api';
 
     updatedAt: string | null;
 
@@ -194,7 +198,7 @@ export namespace ActionListResponse {
 
     ownerId: string;
 
-    service: 'tasks_api' | 'devices_api' | 'agents_api' | 'webhooks';
+    service: 'tasks_api' | 'devices_api' | 'agents_api' | 'webhooks' | 'integrations_api';
 
     updatedAt: string | null;
 
@@ -242,7 +246,7 @@ export interface ActionListParams {
 
   search?: string;
 
-  service?: 'tasks_api' | 'devices_api' | 'agents_api' | 'webhooks';
+  service?: 'tasks_api' | 'devices_api' | 'agents_api' | 'webhooks' | 'integrations_api';
 }
 
 Actions.Services = Services;

package/src/resources/workflows/events.ts

@@ -51,13 +51,15 @@ export namespace EventDryRunResponse {
 
         flowActionId: string;
 
+        key: string;
+
         method: string;
 
         name: string;
 
         recordingEnabled: boolean;
 
-        service: 'tasks_api' | 'devices_api' | 'agents_api' | 'webhooks';
+        service: 'tasks_api' | 'devices_api' | 'agents_api' | 'webhooks' | 'integrations_api';
 
         /**
          * Nested child actions (loop/branch bodies), each the same shape as a
@@ -85,6 +87,8 @@ export namespace EventDryRunResponse {
 
         createdBy: string | null;
 
+        delivery: Flow.Delivery | null;
+
         description: string | null;
 
         deviceIds: Array<string>;
@@ -137,10 +141,11 @@ export namespace EventDryRunResponse {
         status: 'healthy' | 'failing' | 'blocked';
 
         /**
-         * Template-resolver semantics this flow runs under (MVA-23). 1 = legacy
+         * Template-resolver semantics this flow runs under. 1 = legacy
          * (missing/forbidden/null all resolve to ''). 2 = typed (missing/forbidden throw,
-         * a whole-token null stays JSON null). Existing flows stay 1; new flows default
-         * to 2.
+         * a whole-token null stays JSON null). 3 = typed, key-based (steps are addressed
+         * as {{steps.<key>...}} instead of by name; trigger.payload is not available).
+         * Existing flows stay 1; new flows default to the current version.
          */
         templateResolutionVersion: number;
 
@@ -155,6 +160,25 @@ export namespace EventDryRunResponse {
       }
 
       export namespace Flow {
+        export interface Delivery {
+          destination: 'mobilerun' | 'one_drive' | 'google_drive';
+
+          /**
+           * not allowed when destination is mobilerun
+           */
+          folder?: string;
+
+          recording?: Delivery.Recording;
+
+          screenshots?: unknown;
+        }
+
+        export namespace Delivery {
+          export interface Recording {
+            filename: string;
+          }
+        }
+
         export interface RecordingPolicy {
           mode: 'off' | 'flow' | 'selected_steps';
         }
@@ -191,7 +215,7 @@ export namespace EventDryRunResponse {
 
         ownerId: string;
 
-        scheduleRule: unknown;
+        scheduleRule: Trigger.ScheduleRule;
 
         timezone: string | null;
 
@@ -206,6 +230,43 @@ export namespace EventDryRunResponse {
 
         nextFireTime?: string | null;
       }
+
+      export namespace Trigger {
+        export interface ScheduleRule {
+          type: 'once' | 'cron' | 'recurring';
+
+          /**
+           * ISO 8601 datetime (for type=once)
+           */
+          dateTime?: string;
+
+          /**
+           * Cron expression (for type=cron)
+           */
+          expression?: string;
+
+          /**
+           * Optional per-occurrence random window around the nominal schedule time
+           */
+          jitter?: ScheduleRule.Jitter;
+
+          /**
+           * RRULE string (for type=recurring)
+           */
+          rrule?: string;
+        }
+
+        export namespace ScheduleRule {
+          /**
+           * Optional per-occurrence random window around the nominal schedule time
+           */
+          export interface Jitter {
+            afterMinutes?: number;
+
+            beforeMinutes?: number;
+          }
+        }
+      }
     }
 
     export interface Validation {

package/src/resources/workflows/executions/executions.ts

@@ -0,0 +1,510 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as Shared from '../../shared';
+import * as ScreenshotsAPI from './screenshots';
+import { ScreenshotRetrieveParams, Screenshots } from './screenshots';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+export class Executions extends APIResource {
+  screenshots: ScreenshotsAPI.Screenshots = new ScreenshotsAPI.Screenshots(this._client);
+
+  /**
+   * Fetch a single flow execution by its ID, including its status, kind, result or
+   * error, and start/finish timestamps. Returns 404 if no execution matches.
+   */
+  retrieve(executionID: string, options?: RequestOptions): APIPromise<ExecutionRetrieveResponse> {
+    return this._client.get(path`/executions/${executionID}`, options);
+  }
+
+  /**
+   * Return a paginated history of flow executions. Supports filtering by `flowId`,
+   * `triggerId`, `invocationId` (the client/verify key), `status`, and a `from`/`to`
+   * time range, plus free-text `search` and ordering by startedAt, finishedAt, or
+   * status.
+   */
+  list(
+    query: ExecutionListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ExecutionListResponse> {
+    return this._client.get('/executions', { query, ...options });
+  }
+
+  /**
+   * Stops the execution between steps and marks it cancelled. Idempotent-ish:
+   * already-terminal executions return 409.
+   */
+  abort(executionID: string, options?: RequestOptions): APIPromise<ExecutionAbortResponse> {
+    return this._client.post(path`/executions/${executionID}/abort`, options);
+  }
+
+  /**
+   * Return aggregate execution metrics — total count, counts by status, average
+   * duration, and the last execution time. Can be scoped by `flowId`, `triggerId`,
+   * and a `from`/`to` time range.
+   */
+  getMetrics(
+    query: ExecutionGetMetricsParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ExecutionGetMetricsResponse> {
+    return this._client.get('/executions/metrics', { query, ...options });
+  }
+}
+
+export interface ExecutionRetrieveResponse {
+  data: ExecutionRetrieveResponse.Data;
+}
+
+export namespace ExecutionRetrieveResponse {
+  export interface Data {
+    id: string;
+
+    createdBy: string | null;
+
+    /**
+     * OneDrive/Google Drive delivery lifecycle for this run's recording, file, and
+     * screenshot uploads, ordered by startedAt. Empty when the flow has no delivery
+     * configured.
+     */
+    deliveries: Array<Data.Delivery>;
+
+    /**
+     * Device this execution targets (the job's deviceId). Null for device-less
+     * (event-only) runs.
+     */
+    deviceId: string | null;
+
+    error: string | null;
+
+    eventId: string | null;
+
+    /**
+     * Files produced by files.upload steps, plus files an agent.run step reported on
+     * its terminal response (agent-created output or a workflow upload minted during
+     * the turn); derived server-side at read time.
+     */
+    files: Array<Data.File>;
+
+    finishedAt: string | null;
+
+    flowId: string;
+
+    flowName: string | null;
+
+    /**
+     * Client/verify invocation key this row belongs to. Set on live custom fires (one
+     * row per device fan-out) and on verification runs; null for event/schedule live
+     * rows.
+     */
+    invocationId: string | null;
+
+    kind: 'live' | 'dry_run' | 'verification';
+
+    /**
+     * Live progress; null for runs started before this feature.
+     */
+    progress: Data.Progress | null;
+
+    recordingDeviceId: string | null;
+
+    /**
+     * Device recording id for this execution, set once recording starts. Null when the
+     * flow has recording disabled, no device is bound, or the recording failed to
+     * start.
+     */
+    recordingId: string | null;
+
+    /**
+     * Durable recording segments ordered by step/loop coordinate and retry attempt.
+     * Whole-flow recordings use -1 for every coordinate.
+     */
+    recordings: Array<Data.Recording>;
+
+    /**
+     * Screenshots captured by tasks.run/agent.run steps and saved by scripts into the
+     * flow screenshots recording (source recording), ordered by seq. Image bytes are
+     * never returned here — fetch a fresh signed URL via GET
+     * /executions/{id}/screenshots/{screenshotId}.
+     */
+    screenshots: Array<Data.Screenshot>;
+
+    startedAt: string | null;
+
+    status: 'pending' | 'running' | 'success' | 'failed' | 'cancelled' | 'skipped' | 'invalid' | null;
+
+    triggerId: string;
+
+    triggerName: string | null;
+
+    /**
+     * Opaque per-step result blob ({ steps: [...] }). Each step additionally carries a
+     * `verdict` field ({ outcome, summary, reason? } | null) when it is an agent.run
+     * step that opted into a verdict — null otherwise. Steps of current executions
+     * also carry a `status` string (e.g. success/failed/stopped); it is optional and
+     * absent on older executions, so clients must not assume its presence.
+     */
+    result?: unknown;
+  }
+
+  export namespace Data {
+    export interface Delivery {
+      artifact: 'recording' | 'file' | 'screenshot';
+
+      destination: 'mobilerun' | 'one_drive' | 'google_drive';
+
+      errorCode: string | null;
+
+      filename: string;
+
+      finishedAt: string | null;
+
+      folder: string | null;
+
+      startedAt: string | null;
+
+      status: 'waiting' | 'uploading' | 'succeeded' | 'failed' | 'unknown' | 'cancelled';
+
+      stepIndex: number | null;
+
+      webUrl: string | null;
+    }
+
+    export interface File {
+      fileId: string;
+
+      filename: string;
+
+      mimeType: string;
+
+      sizeBytes: number;
+    }
+
+    /**
+     * Live progress; null for runs started before this feature.
+     */
+    export interface Progress {
+      currentIndex: number | null;
+
+      steps: Array<Progress.Step>;
+
+      total: number;
+    }
+
+    export namespace Progress {
+      export interface Step {
+        finishedAt: string | null;
+
+        index: number;
+
+        method: string;
+
+        name: string;
+
+        service: string;
+
+        sessionId: string | null;
+
+        startedAt: string | null;
+
+        status: 'pending' | 'running' | 'success' | 'failed' | 'skipped' | 'cancelled';
+      }
+    }
+
+    export interface Recording {
+      id: string;
+
+      attempt: number;
+
+      childIndex: number;
+
+      flowActionId: string | null;
+
+      iterationIndex: number;
+
+      lastError: string | null;
+
+      parentIndex: number;
+
+      recordingDeviceId: string | null;
+
+      recordingId: string | null;
+
+      scope: 'flow' | 'step';
+
+      startedAt: string | null;
+
+      status: 'starting' | 'recording' | 'stopping' | 'stopped' | 'failed';
+
+      stepIndex: number;
+
+      stoppedAt: string | null;
+    }
+
+    export interface Screenshot {
+      id: string;
+
+      capturedAt: string | null;
+
+      iterationIndex: number;
+
+      mimeType: string;
+
+      seq: number;
+
+      source: 'task' | 'agent' | 'recording';
+
+      stepIndex: number;
+
+      stepName: string;
+    }
+  }
+}
+
+export interface ExecutionListResponse {
+  items: Array<ExecutionListResponse.Item>;
+
+  pagination: Shared.Pagination;
+}
+
+export namespace ExecutionListResponse {
+  export interface Item {
+    id: string;
+
+    createdBy: string | null;
+
+    /**
+     * Device this execution targets (the job's deviceId). Null for device-less
+     * (event-only) runs.
+     */
+    deviceId: string | null;
+
+    error: string | null;
+
+    eventId: string | null;
+
+    finishedAt: string | null;
+
+    flowId: string;
+
+    flowName: string | null;
+
+    /**
+     * Client/verify invocation key this row belongs to. Set on live custom fires (one
+     * row per device fan-out) and on verification runs; null for event/schedule live
+     * rows.
+     */
+    invocationId: string | null;
+
+    kind: 'live' | 'dry_run' | 'verification';
+
+    recordingDeviceId: string | null;
+
+    /**
+     * Device recording id for this execution, set once recording starts. Null when the
+     * flow has recording disabled, no device is bound, or the recording failed to
+     * start.
+     */
+    recordingId: string | null;
+
+    /**
+     * Durable recording segments ordered by step/loop coordinate and retry attempt.
+     * Whole-flow recordings use -1 for every coordinate.
+     */
+    recordings: Array<Item.Recording>;
+
+    startedAt: string | null;
+
+    status: 'pending' | 'running' | 'success' | 'failed' | 'cancelled' | 'skipped' | 'invalid' | null;
+
+    triggerId: string;
+
+    triggerName: string | null;
+
+    /**
+     * Opaque per-step result blob ({ steps: [...] }). Each step additionally carries a
+     * `verdict` field ({ outcome, summary, reason? } | null) when it is an agent.run
+     * step that opted into a verdict — null otherwise. Steps of current executions
+     * also carry a `status` string (e.g. success/failed/stopped); it is optional and
+     * absent on older executions, so clients must not assume its presence.
+     */
+    result?: unknown;
+  }
+
+  export namespace Item {
+    export interface Recording {
+      id: string;
+
+      attempt: number;
+
+      childIndex: number;
+
+      flowActionId: string | null;
+
+      iterationIndex: number;
+
+      lastError: string | null;
+
+      parentIndex: number;
+
+      recordingDeviceId: string | null;
+
+      recordingId: string | null;
+
+      scope: 'flow' | 'step';
+
+      startedAt: string | null;
+
+      status: 'starting' | 'recording' | 'stopping' | 'stopped' | 'failed';
+
+      stepIndex: number;
+
+      stoppedAt: string | null;
+    }
+  }
+}
+
+export interface ExecutionAbortResponse {
+  data: ExecutionAbortResponse.Data;
+}
+
+export namespace ExecutionAbortResponse {
+  export interface Data {
+    id: string;
+
+    /**
+     * Device this execution targets (the job's deviceId). Null for device-less
+     * (event-only) runs.
+     */
+    deviceId: string | null;
+
+    error: string | null;
+
+    eventId: string | null;
+
+    finishedAt: string | null;
+
+    flowId: string;
+
+    flowName: string | null;
+
+    /**
+     * Client/verify invocation key this row belongs to. Set on live custom fires (one
+     * row per device fan-out) and on verification runs; null for event/schedule live
+     * rows.
+     */
+    invocationId: string | null;
+
+    kind: 'live' | 'dry_run' | 'verification';
+
+    recordingDeviceId: string | null;
+
+    /**
+     * Device recording id for this execution, set once recording starts. Null when the
+     * flow has recording disabled, no device is bound, or the recording failed to
+     * start.
+     */
+    recordingId: string | null;
+
+    startedAt: string | null;
+
+    status: 'pending' | 'running' | 'success' | 'failed' | 'cancelled' | 'skipped' | 'invalid' | null;
+
+    triggerId: string;
+
+    triggerName: string | null;
+
+    /**
+     * Opaque per-step result blob ({ steps: [...] }). Each step additionally carries a
+     * `verdict` field ({ outcome, summary, reason? } | null) when it is an agent.run
+     * step that opted into a verdict — null otherwise. Steps of current executions
+     * also carry a `status` string (e.g. success/failed/stopped); it is optional and
+     * absent on older executions, so clients must not assume its presence.
+     */
+    result?: unknown;
+  }
+}
+
+export interface ExecutionGetMetricsResponse {
+  data: ExecutionGetMetricsResponse.Data;
+}
+
+export namespace ExecutionGetMetricsResponse {
+  export interface Data {
+    avgDurationMs: number | null;
+
+    byStatus: Data.ByStatus;
+
+    lastExecutionAt: string | null;
+
+    total: number;
+  }
+
+  export namespace Data {
+    export interface ByStatus {
+      cancelled: number;
+
+      failed: number;
+
+      invalid: number;
+
+      pending: number;
+
+      running: number;
+
+      skipped: number;
+
+      success: number;
+    }
+  }
+}
+
+export interface ExecutionListParams {
+  flowId?: string;
+
+  from?: string | null;
+
+  invocationId?: string;
+
+  orderBy?: 'startedAt' | 'finishedAt' | 'status';
+
+  orderByDirection?: 'asc' | 'desc';
+
+  page?: number;
+
+  pageSize?: number;
+
+  search?: string;
+
+  status?: 'pending' | 'running' | 'success' | 'failed' | 'cancelled' | 'skipped' | 'invalid';
+
+  to?: string | null;
+
+  triggerId?: string;
+}
+
+export interface ExecutionGetMetricsParams {
+  flowId?: string;
+
+  from?: string | null;
+
+  to?: string | null;
+
+  triggerId?: string;
+}
+
+Executions.Screenshots = Screenshots;
+
+export declare namespace Executions {
+  export {
+    type ExecutionRetrieveResponse as ExecutionRetrieveResponse,
+    type ExecutionListResponse as ExecutionListResponse,
+    type ExecutionAbortResponse as ExecutionAbortResponse,
+    type ExecutionGetMetricsResponse as ExecutionGetMetricsResponse,
+    type ExecutionListParams as ExecutionListParams,
+    type ExecutionGetMetricsParams as ExecutionGetMetricsParams,
+  };
+
+  export { Screenshots as Screenshots, type ScreenshotRetrieveParams as ScreenshotRetrieveParams };
+}

package/src/resources/workflows/executions/index.ts

@@ -0,0 +1,12 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Executions,
+  type ExecutionRetrieveResponse,
+  type ExecutionListResponse,
+  type ExecutionAbortResponse,
+  type ExecutionGetMetricsResponse,
+  type ExecutionListParams,
+  type ExecutionGetMetricsParams,
+} from './executions';
+export { Screenshots, type ScreenshotRetrieveParams } from './screenshots';