@run-cloud/sdk 0.12.1 → 0.14.0

package/dist/index.js

@@ -1,5 +1,255 @@
 import WebSocket from "ws";
 import { createHash, randomUUID } from "node:crypto";
+export const SIMULATOR_KEYS = [
+    "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 const SIMULATOR_BUTTONS = [
+    "home",
+    "back",
+    "appSwitcher",
+    "recents",
+    "power",
+    "volumeUp",
+    "volumeDown",
+    "menu",
+    "sideButton",
+    "actionButton",
+    "digitalCrown",
+];
+export const SIMULATOR_RENDER_DEBUG_OPTIONS = [
+    "colorBlendedLayers",
+    "colorCopiedImages",
+    "colorMisalignedImages",
+    "colorOffscreenRendered",
+    "slowAnimations",
+];
+export const SIMULATOR_INTERACTION_ERROR_CODES = [
+    "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 const SIMULATOR_SCREENSHOT_ERROR_CODES = [
+    "invalid_screenshot_request",
+    "active_session_not_found",
+    "simulator_capacity_unavailable",
+    "screenshot_cancelled",
+    "screenshot_timeout",
+    "screenshot_transport_error",
+    "screenshot_invalid_response",
+    "screenshot_failed",
+];
+export const DEFAULT_SIMULATOR_INTERACTION_TIMEOUT_MS = 15_000;
+const SIMULATOR_RESPONSE_MARGIN_MS = 250;
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+function assertNormalizedPoint(point, name) {
+    if (!Number.isFinite(point.x)
+        || point.x < 0
+        || point.x > 1
+        || !Number.isFinite(point.y)
+        || point.y < 0
+        || point.y > 1)
+        throw new RangeError(`${name} coordinates must be finite numbers from 0 to 1`);
+}
+function assertIntegerRange(value, min, max, name) {
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new RangeError(`${name} must be an integer from ${min} to ${max}`);
+    }
+}
+function validatedRecordingIdempotencyKey(value) {
+    if (value === undefined)
+        return undefined;
+    const key = value.trim();
+    const hasControlCharacter = [...key].some((character) => {
+        const code = character.charCodeAt(0);
+        return code <= 31 || code === 127;
+    });
+    if (!key || key.length > 200 || hasControlCharacter) {
+        throw new TypeError("idempotencyKey must contain 1-200 printable characters");
+    }
+    return key;
+}
+export function validateSimulatorInteraction(interaction, timeoutMs = DEFAULT_SIMULATOR_INTERACTION_TIMEOUT_MS) {
+    assertIntegerRange(timeoutMs, 100, 60_000, "timeoutMs");
+    switch (interaction.action) {
+        case "tap":
+            assertNormalizedPoint(interaction, "tap");
+            return;
+        case "swipe":
+            assertNormalizedPoint(interaction.from, "swipe from");
+            assertNormalizedPoint(interaction.to, "swipe to");
+            if (interaction.durationMs !== undefined) {
+                assertIntegerRange(interaction.durationMs, 50, 30_000, "swipe durationMs");
+            }
+            return;
+        case "gesture": {
+            if (interaction.steps.length < 2 || interaction.steps.length > 1_000) {
+                throw new RangeError("gesture steps must contain from 2 to 1000 entries");
+            }
+            let pointCount;
+            let delayTotal = 0;
+            for (const [index, step] of interaction.steps.entries()) {
+                const expectedPhase = index === 0
+                    ? "begin"
+                    : index === interaction.steps.length - 1
+                        ? "end"
+                        : "move";
+                if (step.phase !== expectedPhase) {
+                    throw new TypeError(`gesture step ${index} phase must be ${expectedPhase}`);
+                }
+                if ((index === 0) !== (step.phase === "begin")) {
+                    throw new TypeError("gesture must start with begin and contain no later begin phase");
+                }
+                if ((index === interaction.steps.length - 1) !== (step.phase === "end")) {
+                    throw new TypeError("gesture must end with end and contain no earlier end phase");
+                }
+                if (step.points.length !== 1 && step.points.length !== 2) {
+                    throw new RangeError("each gesture step must contain one or two points");
+                }
+                if (pointCount === undefined)
+                    pointCount = step.points.length;
+                else if (pointCount !== step.points.length) {
+                    throw new TypeError("every gesture step must use the same number of points");
+                }
+                for (const point of step.points)
+                    assertNormalizedPoint(point, "gesture");
+                if (step.delayMs !== undefined) {
+                    assertIntegerRange(step.delayMs, 0, 5_000, "gesture delayMs");
+                    if (index === interaction.steps.length - 1 && step.delayMs !== 0) {
+                        throw new RangeError("final gesture end step delayMs must be 0 because there is no next step");
+                    }
+                    delayTotal += step.delayMs;
+                }
+            }
+            if (delayTotal > timeoutMs)
+                throw new RangeError("gesture delays cannot exceed timeoutMs");
+            return;
+        }
+        case "typeText":
+            if (interaction.text.length < 1 || interaction.text.length > 10_000) {
+                throw new RangeError("text must contain from 1 to 10000 characters");
+            }
+            if (!/^[\x09\x0a\x20-\x7e]+$/.test(interaction.text)) {
+                throw new TypeError("text must contain only US ASCII characters, tabs, and line feeds");
+            }
+            return;
+        case "pressKey":
+            if (!SIMULATOR_KEYS.includes(interaction.key)) {
+                throw new TypeError(`unknown simulator key: ${interaction.key}`);
+            }
+            if (interaction.durationMs !== undefined) {
+                assertIntegerRange(interaction.durationMs, 20, 30_000, "key durationMs");
+            }
+            if (interaction.modifiers) {
+                const known = new Set(["shift", "control", "alt", "meta"]);
+                if (interaction.modifiers.some((modifier) => !known.has(modifier))) {
+                    throw new TypeError("key modifiers must be shift, control, alt, or meta");
+                }
+                if (new Set(interaction.modifiers).size !== interaction.modifiers.length) {
+                    throw new TypeError("key modifiers must be unique");
+                }
+            }
+            return;
+        case "pressButton":
+            if (!SIMULATOR_BUTTONS.includes(interaction.button)) {
+                throw new TypeError(`unknown simulator button: ${interaction.button}`);
+            }
+            if (interaction.durationMs !== undefined) {
+                assertIntegerRange(interaction.durationMs, 20, 30_000, "button durationMs");
+            }
+            return;
+        case "rotate":
+            if (!["portrait", "portrait_upside_down", "landscape_left", "landscape_right"].includes(interaction.orientation)) {
+                throw new TypeError(`unknown simulator orientation: ${interaction.orientation}`);
+            }
+            return;
+        case "reload":
+        case "toggleSoftwareKeyboard":
+        case "simulateMemoryWarning":
+            return;
+        case "scroll":
+            if (!Number.isFinite(interaction.deltaX)
+                || interaction.deltaX < -1
+                || interaction.deltaX > 1
+                || !Number.isFinite(interaction.deltaY)
+                || interaction.deltaY < -1
+                || interaction.deltaY > 1)
+                throw new RangeError("scroll deltaX and deltaY must be finite numbers from -1 to 1");
+            if (interaction.deltaX === 0 && interaction.deltaY === 0) {
+                throw new RangeError("at least one scroll delta must be nonzero");
+            }
+            if ((interaction.x === undefined) !== (interaction.y === undefined)) {
+                throw new TypeError("scroll x and y must be provided together");
+            }
+            if (interaction.x !== undefined && interaction.y !== undefined) {
+                assertNormalizedPoint({ x: interaction.x, y: interaction.y }, "scroll anchor");
+            }
+            return;
+        case "rotateDigitalCrown":
+            if (!Number.isFinite(interaction.delta) || interaction.delta === 0 || Math.abs(interaction.delta) > 10_000) {
+                throw new RangeError("digital crown delta must be nonzero and between -10000 and 10000");
+            }
+            return;
+        case "setRenderDebug":
+            if (!SIMULATOR_RENDER_DEBUG_OPTIONS.includes(interaction.option)) {
+                throw new TypeError(`unknown render debug option: ${interaction.option}`);
+            }
+            if (typeof interaction.enabled !== "boolean") {
+                throw new TypeError("render debug enabled must be a boolean");
+            }
+            return;
+    }
+}
+function requestAbort(options) {
+    const { signal, timeoutMs } = options;
+    if (timeoutMs === undefined && !signal) {
+        return { signal: undefined, timedOut: () => false, cleanup: () => undefined };
+    }
+    if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+        throw new RangeError("timeoutMs must be a positive finite number");
+    }
+    const controller = new AbortController();
+    let didTimeOut = false;
+    const abortFromCaller = () => {
+        controller.abort(signal?.reason ?? new DOMException("The operation was aborted", "AbortError"));
+    };
+    if (signal?.aborted)
+        abortFromCaller();
+    else
+        signal?.addEventListener("abort", abortFromCaller, { once: true });
+    const timer = timeoutMs === undefined
+        ? undefined
+        : setTimeout(() => {
+            didTimeOut = true;
+            controller.abort(new DOMException(options.timeoutMessage ?? "The operation timed out", "TimeoutError"));
+        }, timeoutMs);
+    return {
+        signal: controller.signal,
+        timedOut: () => didTimeOut,
+        cleanup: () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal?.removeEventListener("abort", abortFromCaller);
+        },
+    };
+}
 const FILE_CHUNK_BYTES = 512 * 1024;
 const MAX_CONCURRENT_ASSET_UPLOADS = 6;
 const MAX_ASSET_UPLOAD_ATTEMPTS = 3;
@@ -28,10 +278,33 @@ function normalizeSandbox(raw) {
 export class RunCloudError extends Error {
     status;
     detail;
-    constructor(status, detail) {
+    code;
+    retryable;
+    details;
+    requestId;
+    sessionId;
+    platform;
+    action;
+    interactionStatus;
+    acceptedAt;
+    completedAt;
+    durationMs;
+    constructor(status, detail, options = {}) {
         super(`run.cloud API ${status}: ${detail}`);
         this.status = status;
         this.detail = detail;
+        this.name = "RunCloudError";
+        this.code = options.code;
+        this.retryable = options.retryable;
+        this.details = options.details;
+        this.requestId = options.requestId;
+        this.sessionId = options.sessionId;
+        this.platform = options.platform;
+        this.action = options.action;
+        this.interactionStatus = options.interactionStatus;
+        this.acceptedAt = options.acceptedAt;
+        this.completedAt = options.completedAt;
+        this.durationMs = options.durationMs;
     }
 }
 function env(name) {
@@ -47,24 +320,108 @@ function apiKeyFromEnv() {
 function apiUrlFromEnv() {
     return (env("RUN_CLOUD_API_URL") ?? "https://api.run.cloud").replace(/\/+$/, "");
 }
-async function errorDetail(response) {
+function optionalString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function optionalFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+const simulatorInteractionErrorCodeSet = new Set(SIMULATOR_INTERACTION_ERROR_CODES);
+const simulatorScreenshotErrorCodeSet = new Set(SIMULATOR_SCREENSHOT_ERROR_CODES);
+function normalizedInteractionErrorCode(value) {
+    if (typeof value === "string" && simulatorInteractionErrorCodeSet.has(value)) {
+        return value;
+    }
+    switch (value) {
+        case "timeout":
+        case "timed_out":
+        case "interaction_transport_timeout":
+            return "interaction_timeout";
+        case "cancelled":
+            return "interaction_cancelled";
+        case "invalid_request":
+            return "invalid_interaction";
+        case "simulator_session_ended":
+            return "active_session_not_found";
+        case "unsupported_on_platform":
+            return "unsupported_action";
+        case "invalid_host_response":
+        case "invalid_interaction_result":
+        case "interaction_platform_mismatch":
+            return "interaction_invalid_response";
+        default:
+            return "interaction_failed";
+    }
+}
+function normalizedScreenshotErrorCode(value) {
+    return typeof value === "string" && simulatorScreenshotErrorCodeSet.has(value)
+        ? value
+        : "screenshot_failed";
+}
+async function parseApiError(response) {
     const text = await response.text();
     try {
         const parsed = JSON.parse(text);
-        for (const value of [parsed.detail, parsed.error, parsed.message]) {
-            if (typeof value === "string")
-                return value;
-            if (value !== undefined)
-                return JSON.stringify(value);
-        }
+        const nested = typeof parsed.error === "object" && parsed.error !== null
+            ? parsed.error
+            : undefined;
+        const message = nested?.message ?? parsed.detail ?? parsed.error ?? parsed.message;
+        const detail = typeof message === "string"
+            ? message
+            : message !== undefined
+                ? JSON.stringify(message)
+                : response.statusText;
+        const interactionStatus = parsed.status === "failed"
+            || parsed.status === "cancelled"
+            || parsed.status === "timed_out"
+            ? parsed.status
+            : undefined;
+        const platform = parsed.platform === "ios" || parsed.platform === "android"
+            ? parsed.platform
+            : undefined;
+        const retryable = nested?.retryable ?? parsed.retryable;
+        const action = optionalString(parsed.action);
+        const rawCode = nested?.code ?? parsed.code;
+        const code = action === "screenshot"
+            ? normalizedScreenshotErrorCode(rawCode)
+            : action !== undefined || interactionStatus !== undefined
+                ? normalizedInteractionErrorCode(rawCode)
+                : optionalString(rawCode);
+        return {
+            detail,
+            code,
+            retryable: typeof retryable === "boolean" ? retryable : undefined,
+            details: nested?.details ?? parsed.details,
+            requestId: optionalString(parsed.requestId),
+            sessionId: optionalString(parsed.sessionId),
+            platform,
+            action,
+            interactionStatus,
+            acceptedAt: optionalString(parsed.acceptedAt),
+            completedAt: optionalString(parsed.completedAt),
+            durationMs: optionalFiniteNumber(parsed.durationMs),
+        };
     }
     catch {
-        // plain text
+        if (/<(?:!doctype|html)\b/i.test(text)) {
+            return {
+                detail: "the API edge returned an HTML error page; retry the request or use the streaming/direct-transfer API",
+            };
+        }
+        return { detail: text || response.statusText };
     }
-    if (/<(?:!doctype|html)\b/i.test(text)) {
-        return "the API edge returned an HTML error page; retry the request or use the streaming/direct-transfer API";
+}
+async function apiError(response, fallback = {}) {
+    const { detail, ...options } = await parseApiError(response);
+    const merged = { ...fallback };
+    for (const [key, value] of Object.entries(options)) {
+        if (value !== undefined)
+            Object.assign(merged, { [key]: value });
     }
-    return text || response.statusText;
+    if (merged.action !== undefined && merged.retryable === undefined) {
+        merged.retryable = response.status === 408 || response.status === 429 || response.status >= 500;
+    }
+    return new RunCloudError(response.status, detail, merged);
 }
 async function md5Hex(blob) {
     const hash = createHash("md5");
@@ -126,24 +483,53 @@ export class Client {
             meteringStatus: account.meteringStatus ?? account.run_cloud_metering_status,
         };
     }
-    async request(method, path, body, headers) {
-        const response = await this.fetchImpl(`${this.apiUrl}${path}`, {
-            method,
-            headers: {
-                Authorization: `Bearer ${this.apiKey}`,
-                ...(body === undefined ? {} : { "Content-Type": "application/json" }),
-                ...headers,
-            },
-            body: body === undefined ? undefined : JSON.stringify(body),
-        });
-        if (!response.ok)
-            throw new RunCloudError(response.status, await errorDetail(response));
-        if (response.status === 204)
-            return undefined;
-        const contentType = response.headers.get("content-type") ?? "";
-        return contentType.includes("application/json")
-            ? (await response.json())
-            : (await response.text());
+    async request(method, path, body, headers, abortOptions = {}) {
+        const operation = requestAbort(abortOptions);
+        try {
+            const response = await this.fetchImpl(`${this.apiUrl}${path}`, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+                    ...headers,
+                },
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: operation.signal,
+            });
+            if (!response.ok)
+                throw await apiError(response, abortOptions.errorContext);
+            if (response.status === 204)
+                return undefined;
+            const contentType = response.headers.get("content-type") ?? "";
+            return contentType.includes("application/json")
+                ? (await response.json())
+                : (await response.text());
+        }
+        catch (error) {
+            if (operation.timedOut()) {
+                throw new RunCloudError(0, abortOptions.timeoutMessage ?? "the request timed out", {
+                    ...abortOptions.timeoutContext,
+                    code: abortOptions.timeoutCode ?? "interaction_timeout",
+                    retryable: true,
+                    interactionStatus: "timed_out",
+                });
+            }
+            if (abortOptions.errorContext
+                && !abortOptions.signal?.aborted
+                && error instanceof TypeError) {
+                throw new RunCloudError(0, abortOptions.transportErrorMessage
+                    ?? "simulator interaction could not reach the run.cloud API", {
+                    ...abortOptions.errorContext,
+                    code: abortOptions.transportErrorCode ?? "interaction_transport_error",
+                    retryable: true,
+                    interactionStatus: "failed",
+                });
+            }
+            throw error;
+        }
+        finally {
+            operation.cleanup();
+        }
     }
     async uploadForm(path, form) {
         const response = await this.fetchImpl(`${this.apiUrl}${path}`, {
@@ -152,17 +538,48 @@ export class Client {
             body: form,
         });
         if (!response.ok)
-            throw new RunCloudError(response.status, await errorDetail(response));
+            throw await apiError(response);
         return (await response.json());
     }
-    async requestBytes(path) {
-        const response = await this.fetchImpl(`${this.apiUrl}${path}`, {
-            method: "GET",
-            headers: { Authorization: `Bearer ${this.apiKey}` },
-        });
-        if (!response.ok)
-            throw new RunCloudError(response.status, await errorDetail(response));
-        return new Uint8Array(await response.arrayBuffer());
+    async requestBytes(path, abortOptions = {}) {
+        const operation = requestAbort(abortOptions);
+        try {
+            const response = await this.fetchImpl(`${this.apiUrl}${path}`, {
+                method: "GET",
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    ...abortOptions.headers,
+                },
+                signal: operation.signal,
+            });
+            if (!response.ok)
+                throw await apiError(response, abortOptions.errorContext);
+            return new Uint8Array(await response.arrayBuffer());
+        }
+        catch (error) {
+            if (operation.timedOut()) {
+                throw new RunCloudError(0, abortOptions.timeoutMessage ?? "the request timed out", {
+                    ...abortOptions.timeoutContext,
+                    code: abortOptions.timeoutCode ?? "screenshot_timeout",
+                    retryable: true,
+                    interactionStatus: "timed_out",
+                });
+            }
+            if (abortOptions.errorContext
+                && !abortOptions.signal?.aborted
+                && error instanceof TypeError) {
+                throw new RunCloudError(0, abortOptions.transportErrorMessage ?? "simulator screenshot could not reach the run.cloud API", {
+                    ...abortOptions.errorContext,
+                    code: abortOptions.transportErrorCode ?? "screenshot_transport_error",
+                    retryable: true,
+                    interactionStatus: "failed",
+                });
+            }
+            throw error;
+        }
+        finally {
+            operation.cleanup();
+        }
     }
     async *requestTextStream(path, signal) {
         const response = await this.fetchImpl(`${this.apiUrl}${path}`, {
@@ -174,7 +591,7 @@ export class Client {
             signal,
         });
         if (!response.ok)
-            throw new RunCloudError(response.status, await errorDetail(response));
+            throw await apiError(response);
         if (!response.body)
             throw new RunCloudError(0, "simulator log stream returned no body");
         const contentType = response.headers.get("content-type") ?? "";
@@ -205,7 +622,7 @@ export class Client {
     async putSigned(url, body, headers) {
         const response = await this.fetchImpl(url, { method: "PUT", headers, body });
         if (!response.ok)
-            throw new RunCloudError(response.status, await errorDetail(response));
+            throw await apiError(response);
     }
     async execStream(path, request, callbacks = {}) {
         const url = new URL(`${this.apiUrl}${path}`);
@@ -336,6 +753,150 @@ export class SimulatorClient {
     async openUrl(id, url) {
         return await this.client.request("POST", `/run-cloud/${this.platform}/${encodeURIComponent(id)}/open-url`, { url });
     }
+    async interact(id, interaction, options = {}) {
+        const timeoutMs = options.timeoutMs ?? DEFAULT_SIMULATOR_INTERACTION_TIMEOUT_MS;
+        const requestId = options.requestId ?? `interaction_${randomUUID()}`;
+        if (!REQUEST_ID_PATTERN.test(requestId)) {
+            throw new TypeError("requestId must match /^[A-Za-z0-9._:-]{1,128}$/");
+        }
+        validateSimulatorInteraction(interaction, timeoutMs);
+        return await this.client.request("POST", `/run-cloud/${this.platform}/${encodeURIComponent(id)}/interactions`, { ...interaction, requestId, timeoutMs }, undefined, {
+            signal: options.signal,
+            timeoutMs: timeoutMs + SIMULATOR_RESPONSE_MARGIN_MS,
+            timeoutMessage: `simulator ${interaction.action} did not complete within ${timeoutMs} ms`,
+            timeoutCode: "interaction_timeout",
+            transportErrorCode: "interaction_transport_error",
+            timeoutContext: {
+                requestId,
+                sessionId: id,
+                platform: this.platform,
+                action: interaction.action,
+            },
+            errorContext: {
+                requestId,
+                sessionId: id,
+                platform: this.platform,
+                action: interaction.action,
+                code: "interaction_failed",
+                interactionStatus: "failed",
+            },
+        });
+    }
+    async tap(id, point, options = {}) {
+        return await this.interact(id, { action: "tap", ...point }, options);
+    }
+    async swipe(id, from, to, options = {}) {
+        const { durationMs, ...requestOptions } = options;
+        return await this.interact(id, { action: "swipe", from, to, ...(durationMs === undefined ? {} : { durationMs }) }, requestOptions);
+    }
+    async gesture(id, steps, options = {}) {
+        return await this.interact(id, { action: "gesture", steps }, options);
+    }
+    async typeText(id, text, options = {}) {
+        return await this.interact(id, { action: "typeText", text }, options);
+    }
+    async pressKey(id, key, options = {}) {
+        const { modifiers, durationMs, ...requestOptions } = options;
+        return await this.interact(id, {
+            action: "pressKey",
+            key,
+            ...(modifiers?.length ? { modifiers } : {}),
+            ...(durationMs === undefined ? {} : { durationMs }),
+        }, requestOptions);
+    }
+    async pressButton(id, button, options = {}) {
+        const { durationMs, ...requestOptions } = options;
+        return await this.interact(id, {
+            action: "pressButton",
+            button,
+            ...(durationMs === undefined ? {} : { durationMs }),
+        }, requestOptions);
+    }
+    async rotate(id, orientation, options = {}) {
+        return await this.interact(id, { action: "rotate", orientation }, options);
+    }
+    async reload(id, options = {}) {
+        return await this.interact(id, { action: "reload" }, options);
+    }
+    async scroll(id, input, options = {}) {
+        return await this.interact(id, { action: "scroll", ...input }, options);
+    }
+    async toggleSoftwareKeyboard(id, options = {}) {
+        return await this.interact(id, { action: "toggleSoftwareKeyboard" }, options);
+    }
+    async simulateMemoryWarning(id, options = {}) {
+        return await this.interact(id, { action: "simulateMemoryWarning" }, options);
+    }
+    async rotateDigitalCrown(id, delta, options = {}) {
+        return await this.interact(id, { action: "rotateDigitalCrown", delta }, options);
+    }
+    async setRenderDebug(id, option, enabled, options = {}) {
+        return await this.interact(id, { action: "setRenderDebug", option, enabled }, options);
+    }
+    async screenshot(id, options = {}) {
+        const timeoutMs = options.timeoutMs ?? DEFAULT_SIMULATOR_INTERACTION_TIMEOUT_MS;
+        const requestId = options.requestId ?? `screenshot_${randomUUID()}`;
+        if (!REQUEST_ID_PATTERN.test(requestId)) {
+            throw new TypeError("requestId must match /^[A-Za-z0-9._:-]{1,128}$/");
+        }
+        assertIntegerRange(timeoutMs, 100, 60_000, "timeoutMs");
+        const context = {
+            requestId,
+            sessionId: id,
+            platform: this.platform,
+            action: "screenshot",
+        };
+        const bytes = await this.client.requestBytes(`/run-cloud/${this.platform}/${encodeURIComponent(id)}/screenshot`, {
+            signal: options.signal,
+            timeoutMs: timeoutMs + SIMULATOR_RESPONSE_MARGIN_MS,
+            timeoutMessage: `simulator screenshot did not complete within ${timeoutMs} ms`,
+            timeoutCode: "screenshot_timeout",
+            transportErrorCode: "screenshot_transport_error",
+            transportErrorMessage: "simulator screenshot could not reach the run.cloud API",
+            headers: { "X-Run-Cloud-Request-ID": requestId },
+            timeoutContext: context,
+            errorContext: {
+                ...context,
+                code: "screenshot_failed",
+                interactionStatus: "failed",
+            },
+        });
+        const pngSignature = [137, 80, 78, 71, 13, 10, 26, 10];
+        if (pngSignature.some((byte, index) => bytes[index] !== byte)) {
+            throw new RunCloudError(502, "simulator screenshot response was not a valid PNG image", {
+                ...context,
+                code: "screenshot_invalid_response",
+                retryable: true,
+                interactionStatus: "failed",
+            });
+        }
+        return bytes;
+    }
+    async startRecording(id, options = {}) {
+        const idempotencyKey = validatedRecordingIdempotencyKey(options.idempotencyKey);
+        return await this.client.request("POST", `/run-cloud/${this.platform}/${encodeURIComponent(id)}/recordings`, undefined, idempotencyKey ? { "Idempotency-Key": idempotencyKey } : undefined, { signal: options.signal });
+    }
+    async listRecordings(id, options = {}) {
+        return await this.client.request("GET", `/run-cloud/${this.platform}/${encodeURIComponent(id)}/recordings`, undefined, undefined, { signal: options.signal });
+    }
+    async getRecording(id, recordingId, options = {}) {
+        return await this.client.request("GET", `/run-cloud/${this.platform}/${encodeURIComponent(id)}/recordings/${encodeURIComponent(recordingId)}`, undefined, undefined, { signal: options.signal });
+    }
+    async stopRecording(id, recordingId, options = {}) {
+        return await this.client.request("POST", `/run-cloud/${this.platform}/${encodeURIComponent(id)}/recordings/${encodeURIComponent(recordingId)}/stop`, undefined, undefined, { signal: options.signal });
+    }
+    async downloadRecording(id, recordingId, options = {}) {
+        const bytes = await this.client.requestBytes(`/run-cloud/${this.platform}/${encodeURIComponent(id)}/recordings/${encodeURIComponent(recordingId)}/download`, { signal: options.signal });
+        if (bytes.length < 8 || String.fromCharCode(...bytes.subarray(4, 8)) !== "ftyp") {
+            throw new RunCloudError(502, "simulator recording response was not a valid MP4 file", {
+                code: "recording_invalid_response",
+                retryable: true,
+                sessionId: id,
+                platform: this.platform,
+            });
+        }
+        return bytes;
+    }
     async logs(id, options = {}) {
         const tail = options.tail ?? 200;
         if (!Number.isInteger(tail) || tail < 1 || tail > 1_000) {
@@ -385,9 +946,6 @@ export class IosSimulatorClient extends SimulatorClient {
     constructor(client) {
         super(client, "ios");
     }
-    async screenshot(id) {
-        return await this.client.requestBytes(`/run-cloud/ios/${encodeURIComponent(id)}/screenshot`);
-    }
     async uploadVideo(id, video, options = {}) {
         const contentType = video.type.toLowerCase();
         if (contentType !== "video/mp4" && contentType !== "video/quicktime") {
@@ -466,6 +1024,86 @@ export class SimulatorsClient {
     async openUrl(id, url, options = {}) {
         return await new SimulatorClient(this.client, options.platform ?? "ios").openUrl(id, url);
     }
+    async interact(id, interaction, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).interact(id, interaction, requestOptions);
+    }
+    async tap(id, point, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).tap(id, point, requestOptions);
+    }
+    async swipe(id, from, to, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).swipe(id, from, to, requestOptions);
+    }
+    async gesture(id, steps, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).gesture(id, steps, requestOptions);
+    }
+    async typeText(id, text, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).typeText(id, text, requestOptions);
+    }
+    async pressKey(id, key, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).pressKey(id, key, requestOptions);
+    }
+    async pressButton(id, button, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).pressButton(id, button, requestOptions);
+    }
+    async rotate(id, orientation, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).rotate(id, orientation, requestOptions);
+    }
+    async reload(id, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).reload(id, requestOptions);
+    }
+    async scroll(id, input, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).scroll(id, input, requestOptions);
+    }
+    async toggleSoftwareKeyboard(id, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).toggleSoftwareKeyboard(id, requestOptions);
+    }
+    async simulateMemoryWarning(id, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).simulateMemoryWarning(id, requestOptions);
+    }
+    async rotateDigitalCrown(id, delta, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).rotateDigitalCrown(id, delta, requestOptions);
+    }
+    async setRenderDebug(id, option, enabled, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).setRenderDebug(id, option, enabled, requestOptions);
+    }
+    async screenshot(id, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).screenshot(id, requestOptions);
+    }
+    async startRecording(id, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).startRecording(id, requestOptions);
+    }
+    async listRecordings(id, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).listRecordings(id, requestOptions);
+    }
+    async getRecording(id, recordingId, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).getRecording(id, recordingId, requestOptions);
+    }
+    async stopRecording(id, recordingId, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).stopRecording(id, recordingId, requestOptions);
+    }
+    async downloadRecording(id, recordingId, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).downloadRecording(id, recordingId, requestOptions);
+    }
 }
 export class SandboxClient {
     client;