@mobilerun/sdk 5.5.0 → 5.6.0

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>;
@@ -139,8 +143,9 @@ export namespace EventDryRunResponse {
         /**
          * Template-resolver semantics this flow runs under (MVA-23). 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,22 @@ export namespace EventDryRunResponse {
       }
 
       export namespace Flow {
+        export interface Delivery {
+          destination: 'one_drive' | 'google_drive';
+
+          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 +212,7 @@ export namespace EventDryRunResponse {
 
         ownerId: string;
 
-        scheduleRule: unknown;
+        scheduleRule: Trigger.ScheduleRule;
 
         timezone: string | null;
 
@@ -206,6 +227,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,514 @@
+// 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 });
+  }
+
+  /**
+   * Signals the worker to stop 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 read from step_progress; null for runs started before this
+     * feature.
+     */
+    progress: Data.Progress | null;
+
+    recordingDeviceId: string | null;
+
+    /**
+     * Device-recording id (devices-api) for this execution, set once the worker starts
+     * a recording. 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, 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. Table-backed steps (current
+     * executions) also carry a `status` string (e.g. success/failed/stopped, see
+     * deriveStepStatus); it is optional and absent on legacy blob-only executions, so
+     * clients must not assume its presence.
+     */
+    result?: unknown;
+  }
+
+  export namespace Data {
+    export interface Delivery {
+      artifact: 'recording' | 'file' | 'screenshot';
+
+      destination: '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 read from step_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';
+
+      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 (devices-api) for this execution, set once the worker starts
+     * a recording. 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. Table-backed steps (current
+     * executions) also carry a `status` string (e.g. success/failed/stopped, see
+     * deriveStepStatus); it is optional and absent on legacy blob-only 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 (devices-api) for this execution, set once the worker starts
+     * a recording. 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. Table-backed steps (current
+     * executions) also carry a `status` string (e.g. success/failed/stopped, see
+     * deriveStepStatus); it is optional and absent on legacy blob-only 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';

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

@@ -0,0 +1,34 @@
+// 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 {
+  /**
+   * Redirects (302) to a freshly signed, time-limited image URL for a screenshot
+   * captured during this execution. Owner-gated: 404 if the execution or the
+   * screenshot does not belong to the caller.
+   */
+  retrieve(
+    screenshotID: string,
+    params: ScreenshotRetrieveParams,
+    options?: RequestOptions,
+  ): APIPromise<void> {
+    const { executionId } = params;
+    return this._client.get(path`/executions/${executionId}/screenshots/${screenshotID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export interface ScreenshotRetrieveParams {
+  executionId: string;
+}
+
+export declare namespace Screenshots {
+  export { type ScreenshotRetrieveParams as ScreenshotRetrieveParams };
+}