@run-cloud/sdk 0.12.1 → 0.13.0

package/README.md

@@ -15,14 +15,70 @@ const cloud = new Client();
 
 const ios = await cloud.ios.create({ displayName: "CI smoke" });
 await cloud.ios.openUrl(ios.id, "https://example.com");
-await new Promise((resolve) => setTimeout(resolve, 3000));
+await cloud.ios.tap(ios.id, { x: 0.5, y: 0.75 });
+await cloud.ios.typeText(ios.id, "Hello from iOS!");
 await writeFile("ios-screenshot.png", await cloud.ios.screenshot(ios.id));
 await cloud.ios.delete(ios.id);
 
 const android = await cloud.android.create({ displayName: "Android smoke" });
+await cloud.android.swipe(
+  android.id,
+  { x: 0.5, y: 0.8 },
+  { x: 0.5, y: 0.2 },
+  { durationMs: 250 },
+);
+await cloud.android.pressKey(android.id, "enter");
+await writeFile("android-screenshot.png", await cloud.android.screenshot(android.id));
 await cloud.android.delete(android.id);
 ```
 
+## Simulator interactions
+
+Both `cloud.ios` and `cloud.android` expose the same interaction methods:
+`tap`, `swipe`, `gesture`, `typeText`, `pressKey`, `pressButton`, `rotate`,
+`reload`, `scroll`, `toggleSoftwareKeyboard`, `simulateMemoryWarning`,
+`rotateDigitalCrown`, and `setRenderDebug`. Coordinates use inclusive normalized
+display space: `(0, 0)` is the top-left corner and `(1, 1)` is the bottom-right.
+`typeText` uses a US keyboard and accepts tabs, line feeds, and printable ASCII.
+On iOS, `home`, `appSwitcher`, and `recents` are momentary navigation actions;
+physical buttons honor `durationMs`.
+Digital Crown input is not supported by current iOS Simulator or Android
+Emulator sessions; the typed method returns an actionable API error.
+Android Emulator sessions also report `capsLock`, `numLock`, and `scrollLock`
+as unsupported semantic keys.
+
+Every method returns a correlated, action-narrowed acknowledgement. Use
+`interact` when the action is assembled dynamically:
+
+```ts
+const result = await cloud.simulators.interact(
+  ios.id,
+  { action: "tap", x: 0.5, y: 0.5 },
+  { platform: "ios", requestId: "open-settings", timeoutMs: 15_000 },
+);
+console.log(result.requestId, result.action, result.status, result.result.pointCount);
+```
+
+Pass an `AbortSignal` to stop waiting without releasing the session. The SDK
+sends the requested timeout to run.cloud and leaves a short response margin so
+the server's completion or timeout acknowledgement can arrive.
+
+```ts
+const controller = new AbortController();
+process.once("SIGINT", () => controller.abort());
+await cloud.android.typeText(android.id, "cancel-safe", {
+  signal: controller.signal,
+  timeoutMs: 15_000,
+});
+```
+
+API failures throw `RunCloudError`. In addition to `status` and `detail`,
+interaction failures preserve `code`, `retryable`, `details`, `requestId`,
+`action`, and the accepted/completed timing fields when the API provides them.
+Screenshot options also accept `requestId`; screenshot timeout, transport, and
+invalid-image failures retain the same correlation fields with stable
+`screenshot_*` codes.
+
 ## Linux sandboxes
 
 Firecracker microVMs. The default reservation is 0.125 vCPU / 128 MiB — CPU
@@ -162,7 +218,8 @@ For multipart archives, `cloud.assets.uploadBatch(parts, { uploadBatchId,
 uploadRunId })` numbers the parts, records per-part transfer telemetry, and
 limits direct storage transfers to six at a time.
 
-`cloud.ios.screenshot(sessionId)` returns PNG bytes as a `Uint8Array`. Save the
+`cloud.ios.screenshot(sessionId)` and `cloud.android.screenshot(sessionId)`
+return PNG bytes as a `Uint8Array`. Save the
 bytes directly with `node:fs/promises.writeFile`, attach them to test artifacts,
 or pass them to an image-processing library.
 

package/dist/index.d.ts

@@ -1,5 +1,205 @@
 import WebSocket from "ws";
 export type SimulatorPlatform = "ios" | "android";
+export interface SimulatorPoint {
+    /** Normalized display-space coordinate, inclusive from 0 (left) to 1 (right). */
+    x: number;
+    /** Normalized display-space coordinate, inclusive from 0 (top) to 1 (bottom). */
+    y: number;
+}
+export type SimulatorOrientation = "portrait" | "portrait_upside_down" | "landscape_left" | "landscape_right";
+export declare const SIMULATOR_KEYS: readonly ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "enter", "escape", "backspace", "tab", "space", "minus", "equal", "bracketLeft", "bracketRight", "backslash", "semicolon", "quote", "backquote", "comma", "period", "slash", "capsLock", "f1", "f2", "f3", "f4", "f5", "f6", "f7", "f8", "f9", "f10", "f11", "f12", "printScreen", "scrollLock", "pause", "insert", "home", "pageUp", "delete", "end", "pageDown", "arrowRight", "arrowLeft", "arrowDown", "arrowUp", "numLock", "numpadDivide", "numpadMultiply", "numpadSubtract", "numpadAdd", "numpadEnter", "numpad0", "numpad1", "numpad2", "numpad3", "numpad4", "numpad5", "numpad6", "numpad7", "numpad8", "numpad9", "numpadDecimal"];
+export type SimulatorKey = (typeof SIMULATOR_KEYS)[number];
+export type SimulatorKeyModifier = "shift" | "control" | "alt" | "meta";
+export declare const SIMULATOR_BUTTONS: readonly ["home", "back", "appSwitcher", "recents", "power", "volumeUp", "volumeDown", "menu", "sideButton", "actionButton", "digitalCrown"];
+export type SimulatorButton = (typeof SIMULATOR_BUTTONS)[number];
+export declare const SIMULATOR_RENDER_DEBUG_OPTIONS: readonly ["colorBlendedLayers", "colorCopiedImages", "colorMisalignedImages", "colorOffscreenRendered", "slowAnimations"];
+export type SimulatorRenderDebugOption = (typeof SIMULATOR_RENDER_DEBUG_OPTIONS)[number];
+export interface SimulatorGestureStep {
+    phase: "begin" | "move" | "end";
+    points: [SimulatorPoint] | [SimulatorPoint, SimulatorPoint];
+    /** Milliseconds to wait before the next step. The final end step must omit this or use 0. */
+    delayMs?: number;
+}
+export type SimulatorInteraction = {
+    action: "tap";
+    x: number;
+    y: number;
+} | {
+    action: "swipe";
+    from: SimulatorPoint;
+    to: SimulatorPoint;
+    durationMs?: number;
+} | {
+    action: "gesture";
+    steps: SimulatorGestureStep[];
+} | {
+    action: "typeText";
+    text: string;
+} | {
+    action: "pressKey";
+    key: SimulatorKey;
+    modifiers?: SimulatorKeyModifier[];
+    durationMs?: number;
+} | {
+    action: "pressButton";
+    button: SimulatorButton;
+    durationMs?: number;
+} | {
+    action: "rotate";
+    orientation: SimulatorOrientation;
+} | {
+    action: "reload";
+} | {
+    action: "scroll";
+    deltaX: number;
+    deltaY: number;
+    x?: number;
+    y?: number;
+} | {
+    action: "toggleSoftwareKeyboard";
+} | {
+    action: "simulateMemoryWarning";
+} | {
+    action: "rotateDigitalCrown";
+    delta: number;
+} | {
+    action: "setRenderDebug";
+    option: SimulatorRenderDebugOption;
+    enabled: boolean;
+};
+export type SimulatorInteractionAction = SimulatorInteraction["action"];
+export type SimulatorOperation = SimulatorInteractionAction | "screenshot";
+export declare const SIMULATOR_INTERACTION_ERROR_CODES: readonly ["invalid_interaction", "active_session_not_found", "simulator_capacity_unavailable", "unsupported_action", "duplicate_request", "interaction_cancelled", "interaction_timeout", "interaction_transport_error", "interaction_invalid_response", "interaction_failed"];
+export type SimulatorInteractionErrorCode = (typeof SIMULATOR_INTERACTION_ERROR_CODES)[number];
+export declare const SIMULATOR_SCREENSHOT_ERROR_CODES: readonly ["invalid_screenshot_request", "active_session_not_found", "simulator_capacity_unavailable", "screenshot_cancelled", "screenshot_timeout", "screenshot_transport_error", "screenshot_invalid_response", "screenshot_failed"];
+export type SimulatorScreenshotErrorCode = (typeof SIMULATOR_SCREENSHOT_ERROR_CODES)[number];
+export interface SimulatorInteractionOptions {
+    /** Correlates this request with logs and the returned acknowledgement. */
+    requestId?: string;
+    /** Cancels the request without cancelling or releasing the simulator session. */
+    signal?: AbortSignal;
+    /** Maximum time to wait for the simulator acknowledgement. Defaults to 15 seconds. */
+    timeoutMs?: number;
+}
+export interface SimulatorInteractionResultMap {
+    tap: {
+        pointCount: 1;
+    };
+    swipe: {
+        pointCount: 1;
+        durationMs: number;
+    };
+    gesture: {
+        pointCount: number;
+        stepCount: number;
+    };
+    typeText: {
+        characterCount: number;
+    };
+    pressKey: {
+        key: SimulatorKey;
+        modifierCount: number;
+    };
+    pressButton: {
+        button: SimulatorButton;
+    };
+    rotate: {
+        orientation: SimulatorOrientation;
+    };
+    reload: undefined;
+    scroll: {
+        deltaX: number;
+        deltaY: number;
+    };
+    toggleSoftwareKeyboard: undefined;
+    simulateMemoryWarning: undefined;
+    rotateDigitalCrown: {
+        delta: number;
+    };
+    setRenderDebug: {
+        option: SimulatorRenderDebugOption;
+        enabled: boolean;
+    };
+}
+type SimulatorInteractionResultField<Action extends SimulatorInteractionAction> = Action extends SimulatorInteractionAction ? SimulatorInteractionResultMap[Action] extends undefined ? {
+    result?: undefined;
+} : {
+    result: SimulatorInteractionResultMap[Action];
+} : never;
+export type SimulatorInteractionResult<Action extends SimulatorInteractionAction = SimulatorInteractionAction> = {
+    ok: true;
+    requestId: string;
+    sessionId: string;
+    platform: SimulatorPlatform;
+    action: Action;
+    status: "completed";
+    acceptedAt: string;
+    completedAt: string;
+    durationMs: number;
+} & SimulatorInteractionResultField<Action>;
+export interface SimulatorInteractionFailure {
+    ok: false;
+    requestId?: string;
+    sessionId?: string;
+    platform?: SimulatorPlatform;
+    action?: SimulatorInteractionAction;
+    status?: "failed" | "cancelled" | "timed_out";
+    acceptedAt?: string;
+    completedAt?: string;
+    durationMs?: number;
+    error: {
+        code: SimulatorInteractionErrorCode;
+        message: string;
+        retryable: boolean;
+        details?: unknown;
+    };
+}
+export type SimulatorInteractionResultFor<Interaction extends SimulatorInteraction> = SimulatorInteractionResult<Interaction["action"]>;
+export interface SimulatorScreenshotOptions {
+    /** Correlates this capture with API errors and logs. */
+    requestId?: string;
+    signal?: AbortSignal;
+    /** Maximum time to wait for image capture. Defaults to 15 seconds. */
+    timeoutMs?: number;
+}
+export interface SimulatorSwipeOptions extends SimulatorInteractionOptions {
+    durationMs?: number;
+}
+export interface SimulatorPressKeyOptions extends SimulatorInteractionOptions {
+    modifiers?: SimulatorKeyModifier[];
+    durationMs?: number;
+}
+export interface SimulatorPressButtonOptions extends SimulatorInteractionOptions {
+    durationMs?: number;
+}
+export interface AggregateSimulatorInteractionOptions extends SimulatorInteractionOptions {
+    platform?: SimulatorPlatform;
+}
+export interface AggregateSimulatorSwipeOptions extends SimulatorSwipeOptions {
+    platform?: SimulatorPlatform;
+}
+export interface AggregateSimulatorPressKeyOptions extends SimulatorPressKeyOptions {
+    platform?: SimulatorPlatform;
+}
+export interface AggregateSimulatorPressButtonOptions extends SimulatorPressButtonOptions {
+    platform?: SimulatorPlatform;
+}
+export interface AggregateSimulatorScreenshotOptions extends SimulatorScreenshotOptions {
+    platform?: SimulatorPlatform;
+}
+export declare const DEFAULT_SIMULATOR_INTERACTION_TIMEOUT_MS = 15000;
+export declare function validateSimulatorInteraction(interaction: SimulatorInteraction, timeoutMs?: number): void;
+interface RequestAbortOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    timeoutMessage?: string;
+    timeoutCode?: string;
+    transportErrorCode?: string;
+    transportErrorMessage?: string;
+    headers?: Record<string, string>;
+    timeoutContext?: RunCloudErrorOptions;
+    errorContext?: RunCloudErrorOptions;
+}
 export interface ClientOptions {
     apiKey?: string;
     apiUrl?: string;
@@ -227,10 +427,34 @@ export interface Snapshot {
     state?: "pending" | "ready" | "failed" | string;
     [key: string]: unknown;
 }
+interface RunCloudErrorOptions {
+    code?: string;
+    retryable?: boolean;
+    details?: unknown;
+    requestId?: string;
+    sessionId?: string;
+    platform?: SimulatorPlatform;
+    action?: SimulatorOperation;
+    interactionStatus?: SimulatorInteractionFailure["status"];
+    acceptedAt?: string;
+    completedAt?: string;
+    durationMs?: number;
+}
 export declare class RunCloudError extends Error {
     readonly status: number;
     readonly detail: string;
-    constructor(status: number, detail: string);
+    readonly code?: string;
+    readonly retryable?: boolean;
+    readonly details?: unknown;
+    readonly requestId?: string;
+    readonly sessionId?: string;
+    readonly platform?: SimulatorPlatform;
+    readonly action?: SimulatorOperation;
+    readonly interactionStatus?: SimulatorInteractionFailure["status"];
+    readonly acceptedAt?: string;
+    readonly completedAt?: string;
+    readonly durationMs?: number;
+    constructor(status: number, detail: string, options?: RunCloudErrorOptions);
 }
 export declare class Client {
     readonly ios: IosSimulatorClient;
@@ -248,9 +472,9 @@ export declare class Client {
         orgId?: string;
     }): Promise<UsageReport>;
     account(): Promise<Account>;
-    request<T>(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    request<T>(method: string, path: string, body?: unknown, headers?: Record<string, string>, abortOptions?: RequestAbortOptions): Promise<T>;
     uploadForm<T>(path: string, form: FormData): Promise<T>;
-    requestBytes(path: string): Promise<Uint8Array>;
+    requestBytes(path: string, abortOptions?: RequestAbortOptions): Promise<Uint8Array>;
     requestTextStream(path: string, signal?: AbortSignal): AsyncGenerator<string>;
     putSigned(url: string, body: Blob, headers: Record<string, string>): Promise<void>;
     execStream(path: string, request: Record<string, unknown>, callbacks?: Pick<ExecOptions, "onStdout" | "onStderr" | "signal">): Promise<ExecResult>;
@@ -271,6 +495,26 @@ export declare class SimulatorClient {
     get(id: string): Promise<SimulatorSession>;
     delete(id: string): Promise<SimulatorSession>;
     openUrl(id: string, url: string): Promise<Record<string, unknown>>;
+    interact<Interaction extends SimulatorInteraction>(id: string, interaction: Interaction, options?: SimulatorInteractionOptions): Promise<SimulatorInteractionResultFor<Interaction>>;
+    tap(id: string, point: SimulatorPoint, options?: SimulatorInteractionOptions): Promise<SimulatorInteractionResult<"tap">>;
+    swipe(id: string, from: SimulatorPoint, to: SimulatorPoint, options?: SimulatorSwipeOptions): Promise<SimulatorInteractionResult<"swipe">>;
+    gesture(id: string, steps: SimulatorGestureStep[], options?: SimulatorInteractionOptions): Promise<SimulatorInteractionResult<"gesture">>;
+    typeText(id: string, text: string, options?: SimulatorInteractionOptions): Promise<SimulatorInteractionResult<"typeText">>;
+    pressKey(id: string, key: SimulatorKey, options?: SimulatorPressKeyOptions): Promise<SimulatorInteractionResult<"pressKey">>;
+    pressButton(id: string, button: SimulatorButton, options?: SimulatorPressButtonOptions): Promise<SimulatorInteractionResult<"pressButton">>;
+    rotate(id: string, orientation: SimulatorOrientation, options?: SimulatorInteractionOptions): Promise<SimulatorInteractionResult<"rotate">>;
+    reload(id: string, options?: SimulatorInteractionOptions): Promise<SimulatorInteractionResult<"reload">>;
+    scroll(id: string, input: {
+        deltaX: number;
+        deltaY: number;
+        x?: number;
+        y?: number;
+    }, options?: SimulatorInteractionOptions): Promise<SimulatorInteractionResult<"scroll">>;
+    toggleSoftwareKeyboard(id: string, options?: SimulatorInteractionOptions): Promise<SimulatorInteractionResult<"toggleSoftwareKeyboard">>;
+    simulateMemoryWarning(id: string, options?: SimulatorInteractionOptions): Promise<SimulatorInteractionResult<"simulateMemoryWarning">>;
+    rotateDigitalCrown(id: string, delta: number, options?: SimulatorInteractionOptions): Promise<SimulatorInteractionResult<"rotateDigitalCrown">>;
+    setRenderDebug(id: string, option: SimulatorRenderDebugOption, enabled: boolean, options?: SimulatorInteractionOptions): Promise<SimulatorInteractionResult<"setRenderDebug">>;
+    screenshot(id: string, options?: SimulatorScreenshotOptions): Promise<Uint8Array>;
     logs(id: string, options?: {
         tail?: number;
     }): Promise<SimulatorLogSnapshot>;
@@ -280,7 +524,6 @@ export declare class SimulatorClient {
 }
 export declare class IosSimulatorClient extends SimulatorClient {
     constructor(client: Client);
-    screenshot(id: string): Promise<Uint8Array>;
     uploadVideo(id: string, video: Blob, options?: {
         filename?: string;
         name?: string;
@@ -313,6 +556,26 @@ export declare class SimulatorsClient {
     openUrl(id: string, url: string, options?: {
         platform?: SimulatorPlatform;
     }): Promise<Record<string, unknown>>;
+    interact<Interaction extends SimulatorInteraction>(id: string, interaction: Interaction, options?: AggregateSimulatorInteractionOptions): Promise<SimulatorInteractionResultFor<Interaction>>;
+    tap(id: string, point: SimulatorPoint, options?: AggregateSimulatorInteractionOptions): Promise<SimulatorInteractionResult<"tap">>;
+    swipe(id: string, from: SimulatorPoint, to: SimulatorPoint, options?: AggregateSimulatorSwipeOptions): Promise<SimulatorInteractionResult<"swipe">>;
+    gesture(id: string, steps: SimulatorGestureStep[], options?: AggregateSimulatorInteractionOptions): Promise<SimulatorInteractionResult<"gesture">>;
+    typeText(id: string, text: string, options?: AggregateSimulatorInteractionOptions): Promise<SimulatorInteractionResult<"typeText">>;
+    pressKey(id: string, key: SimulatorKey, options?: AggregateSimulatorPressKeyOptions): Promise<SimulatorInteractionResult<"pressKey">>;
+    pressButton(id: string, button: SimulatorButton, options?: AggregateSimulatorPressButtonOptions): Promise<SimulatorInteractionResult<"pressButton">>;
+    rotate(id: string, orientation: SimulatorOrientation, options?: AggregateSimulatorInteractionOptions): Promise<SimulatorInteractionResult<"rotate">>;
+    reload(id: string, options?: AggregateSimulatorInteractionOptions): Promise<SimulatorInteractionResult<"reload">>;
+    scroll(id: string, input: {
+        deltaX: number;
+        deltaY: number;
+        x?: number;
+        y?: number;
+    }, options?: AggregateSimulatorInteractionOptions): Promise<SimulatorInteractionResult<"scroll">>;
+    toggleSoftwareKeyboard(id: string, options?: AggregateSimulatorInteractionOptions): Promise<SimulatorInteractionResult<"toggleSoftwareKeyboard">>;
+    simulateMemoryWarning(id: string, options?: AggregateSimulatorInteractionOptions): Promise<SimulatorInteractionResult<"simulateMemoryWarning">>;
+    rotateDigitalCrown(id: string, delta: number, options?: AggregateSimulatorInteractionOptions): Promise<SimulatorInteractionResult<"rotateDigitalCrown">>;
+    setRenderDebug(id: string, option: SimulatorRenderDebugOption, enabled: boolean, options?: AggregateSimulatorInteractionOptions): Promise<SimulatorInteractionResult<"setRenderDebug">>;
+    screenshot(id: string, options?: AggregateSimulatorScreenshotOptions): Promise<Uint8Array>;
 }
 export declare class SandboxClient {
     private readonly client;
@@ -416,3 +679,4 @@ export declare class AssetsClient {
         deleted: boolean;
     }>;
 }
+export {};