@run-cloud/sdk 0.19.0 → 0.21.0

package/dist/index.js

@@ -1,5 +1,7 @@
 import WebSocket from "ws";
 import { createHash, randomUUID } from "node:crypto";
+import { RemotionClient } from "./remotion.js";
+export * from "./remotion.js";
 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",
@@ -74,7 +76,18 @@ export const SIMULATOR_SCREENSHOT_ERROR_CODES = [
     "screenshot_invalid_response",
     "screenshot_failed",
 ];
+export const SIMULATOR_ACCESSIBILITY_ERROR_CODES = [
+    "active_session_not_found",
+    "simulator_capacity_unavailable",
+    "simulator_session_ended",
+    "accessibility_unavailable",
+    "accessibility_cancelled",
+    "accessibility_timeout",
+    "accessibility_transport_error",
+    "accessibility_invalid_response",
+];
 export const DEFAULT_SIMULATOR_INTERACTION_TIMEOUT_MS = 15_000;
+export const DEFAULT_SIMULATOR_ACCESSIBILITY_TIMEOUT_MS = 20_000;
 const SIMULATOR_RESPONSE_MARGIN_MS = 250;
 const REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
 function assertNormalizedPoint(point, name) {
@@ -235,6 +248,188 @@ export function validateSimulatorInteraction(interaction, timeoutMs = DEFAULT_SI
             return;
     }
 }
+const simulatorAccessibilityRoleSet = new Set([
+    "application", "window", "dialog", "alert", "group", "scroll-view", "list",
+    "list-item", "text", "heading", "button", "link", "image", "text-field",
+    "checkbox", "switch", "radio-button", "slider", "progress-indicator", "tab",
+    "tab-bar", "toolbar", "menu", "menu-item", "web-view", "keyboard", "other",
+]);
+function accessibilityRecord(value, field) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError(`${field} must be an object`);
+    }
+    return value;
+}
+function accessibilityString(value, field) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 16_384) {
+        throw new TypeError(`${field} must be a non-empty bounded string`);
+    }
+    return value;
+}
+function accessibilityNullableString(value, field) {
+    if (value === null)
+        return null;
+    if (typeof value !== "string" || value.length > 16_384) {
+        throw new TypeError(`${field} must be null or a bounded string`);
+    }
+    return value;
+}
+function accessibilityBoolean(value, field) {
+    if (typeof value !== "boolean")
+        throw new TypeError(`${field} must be a boolean`);
+    return value;
+}
+function accessibilityNullableBoolean(value, field) {
+    if (value !== null && typeof value !== "boolean") {
+        throw new TypeError(`${field} must be a boolean or null`);
+    }
+    return value;
+}
+function accessibilityNumber(value, field, nonNegative = false) {
+    if (typeof value !== "number" || !Number.isFinite(value) || (nonNegative && value < 0)) {
+        throw new TypeError(`${field} must be a${nonNegative ? " non-negative" : ""} finite number`);
+    }
+    return value;
+}
+function parseAccessibilityBounds(value, field) {
+    if (value === null)
+        return null;
+    const input = accessibilityRecord(value, field);
+    return {
+        x: accessibilityNumber(input.x, `${field}.x`),
+        y: accessibilityNumber(input.y, `${field}.y`),
+        width: accessibilityNumber(input.width, `${field}.width`, true),
+        height: accessibilityNumber(input.height, `${field}.height`, true),
+    };
+}
+function parseAccessibilityStates(value, field) {
+    const input = accessibilityRecord(value, field);
+    if (input.checked !== null && typeof input.checked !== "boolean" && input.checked !== "mixed") {
+        throw new TypeError(`${field}.checked must be a boolean, mixed, or null`);
+    }
+    return {
+        enabled: accessibilityBoolean(input.enabled, `${field}.enabled`),
+        focused: accessibilityNullableBoolean(input.focused, `${field}.focused`),
+        selected: accessibilityNullableBoolean(input.selected, `${field}.selected`),
+        checked: input.checked,
+        expanded: accessibilityNullableBoolean(input.expanded, `${field}.expanded`),
+        focusable: accessibilityNullableBoolean(input.focusable, `${field}.focusable`),
+        clickable: accessibilityNullableBoolean(input.clickable, `${field}.clickable`),
+        scrollable: accessibilityNullableBoolean(input.scrollable, `${field}.scrollable`),
+        editable: accessibilityBoolean(input.editable, `${field}.editable`),
+        secure: accessibilityBoolean(input.secure, `${field}.secure`),
+    };
+}
+function parseAccessibilityNative(value, platform, field) {
+    const input = accessibilityRecord(value, field);
+    if (input.platform !== platform)
+        throw new TypeError(`${field}.platform must match the snapshot`);
+    if (platform === "ios") {
+        return {
+            platform,
+            type: accessibilityNullableString(input.type, `${field}.type`),
+            roleDescription: accessibilityNullableString(input.roleDescription, `${field}.roleDescription`),
+            subrole: accessibilityNullableString(input.subrole, `${field}.subrole`),
+            title: accessibilityNullableString(input.title, `${field}.title`),
+            help: accessibilityNullableString(input.help, `${field}.help`),
+        };
+    }
+    return {
+        platform,
+        className: accessibilityNullableString(input.className, `${field}.className`),
+        packageName: accessibilityNullableString(input.packageName, `${field}.packageName`),
+        resourceId: accessibilityNullableString(input.resourceId, `${field}.resourceId`),
+        contentDescription: accessibilityNullableString(input.contentDescription, `${field}.contentDescription`),
+        checkable: accessibilityBoolean(input.checkable, `${field}.checkable`),
+        longClickable: accessibilityBoolean(input.longClickable, `${field}.longClickable`),
+        password: accessibilityBoolean(input.password, `${field}.password`),
+    };
+}
+function parseAccessibilityNode(value, expectedPath, depth, context) {
+    if (depth > 80 || context.count >= 500) {
+        throw new TypeError("accessibility tree exceeds its declared bounds");
+    }
+    const field = `accessibility node ${expectedPath}`;
+    const input = accessibilityRecord(value, field);
+    const id = accessibilityString(input.id, `${field}.id`);
+    const path = accessibilityString(input.path, `${field}.path`);
+    if (path !== expectedPath)
+        throw new TypeError(`${field}.path must be ${expectedPath}`);
+    if (context.ids.has(id))
+        throw new TypeError(`duplicate accessibility node id: ${id}`);
+    context.ids.add(id);
+    context.count += 1;
+    if (typeof input.role !== "string"
+        || !simulatorAccessibilityRoleSet.has(input.role))
+        throw new TypeError(`${field}.role is not supported`);
+    const role = input.role;
+    const states = parseAccessibilityStates(input.states, `${field}.states`);
+    const native = parseAccessibilityNative(input.native, context.platform, `${field}.native`);
+    if (!Array.isArray(input.children))
+        throw new TypeError(`${field}.children must be an array`);
+    const secure = states.secure
+        || (native.platform === "android" && native.password)
+        || (native.platform === "ios" && /(?:secure|password)/iu.test([
+            native.type,
+            native.roleDescription,
+            native.subrole,
+        ].filter(Boolean).join(" ")));
+    return {
+        id,
+        path,
+        role,
+        label: accessibilityNullableString(input.label, `${field}.label`),
+        value: secure ? null : accessibilityNullableString(input.value, `${field}.value`),
+        identifier: accessibilityNullableString(input.identifier, `${field}.identifier`),
+        bounds: parseAccessibilityBounds(input.bounds, `${field}.bounds`),
+        states: { ...states, secure },
+        native,
+        children: input.children.map((child, index) => (parseAccessibilityNode(child, `${expectedPath}.${index}`, depth + 1, context))),
+    };
+}
+/** Validate an API response and remove any secure value defensively. */
+export function validateSimulatorAccessibilitySnapshot(value, expectedPlatform) {
+    const input = accessibilityRecord(value, "accessibility snapshot");
+    if (input.schemaVersion !== 1)
+        throw new TypeError("accessibility schemaVersion must be 1");
+    if (input.platform !== expectedPlatform)
+        throw new TypeError("accessibility platform mismatch");
+    const capturedAt = accessibilityString(input.capturedAt, "accessibility capturedAt");
+    if (!Number.isFinite(Date.parse(capturedAt))) {
+        throw new TypeError("accessibility capturedAt must be an ISO date-time string");
+    }
+    const screenInput = accessibilityRecord(input.screen, "accessibility screen");
+    const unit = expectedPlatform === "ios" ? "points" : "pixels";
+    if (screenInput.unit !== unit)
+        throw new TypeError(`accessibility screen.unit must be ${unit}`);
+    const nodeCount = accessibilityNumber(input.nodeCount, "accessibility nodeCount", true);
+    if (!Number.isInteger(nodeCount) || nodeCount > 500) {
+        throw new TypeError("accessibility nodeCount must be an integer from 0 to 500");
+    }
+    if (!Array.isArray(input.roots))
+        throw new TypeError("accessibility roots must be an array");
+    const context = {
+        platform: expectedPlatform,
+        ids: new Set(),
+        count: 0,
+    };
+    const roots = input.roots.map((root, index) => (parseAccessibilityNode(root, String(index), 0, context)));
+    if (context.count !== nodeCount)
+        throw new TypeError("accessibility nodeCount does not match tree");
+    return {
+        schemaVersion: 1,
+        platform: expectedPlatform,
+        capturedAt,
+        screen: {
+            width: accessibilityNumber(screenInput.width, "accessibility screen.width", true),
+            height: accessibilityNumber(screenInput.height, "accessibility screen.height", true),
+            unit,
+        },
+        nodeCount,
+        truncated: accessibilityBoolean(input.truncated, "accessibility truncated"),
+        roots,
+    };
+}
 function requestAbort(options) {
     const { signal, timeoutMs } = options;
     if (timeoutMs === undefined && !signal) {
@@ -372,6 +567,7 @@ function optionalFiniteNumber(value) {
 }
 const simulatorInteractionErrorCodeSet = new Set(SIMULATOR_INTERACTION_ERROR_CODES);
 const simulatorScreenshotErrorCodeSet = new Set(SIMULATOR_SCREENSHOT_ERROR_CODES);
+const simulatorAccessibilityErrorCodeSet = new Set(SIMULATOR_ACCESSIBILITY_ERROR_CODES);
 function normalizedInteractionErrorCode(value) {
     if (typeof value === "string" && simulatorInteractionErrorCodeSet.has(value)) {
         return value;
@@ -402,6 +598,11 @@ function normalizedScreenshotErrorCode(value) {
         ? value
         : "screenshot_failed";
 }
+function normalizedAccessibilityErrorCode(value) {
+    return typeof value === "string" && simulatorAccessibilityErrorCodeSet.has(value)
+        ? value
+        : "accessibility_unavailable";
+}
 async function parseApiError(response) {
     const text = await response.text();
     try {
@@ -428,9 +629,11 @@ async function parseApiError(response) {
         const rawCode = nested?.code ?? parsed.code;
         const code = action === "screenshot"
             ? normalizedScreenshotErrorCode(rawCode)
-            : action !== "open-url" && (action !== undefined || interactionStatus !== undefined)
-                ? normalizedInteractionErrorCode(rawCode)
-                : optionalString(rawCode);
+            : action === "accessibility"
+                ? normalizedAccessibilityErrorCode(rawCode)
+                : action !== "open-url" && (action !== undefined || interactionStatus !== undefined)
+                    ? normalizedInteractionErrorCode(rawCode)
+                    : optionalString(rawCode);
         return {
             detail,
             code,
@@ -498,6 +701,7 @@ export class Client {
     secrets;
     ci;
     images;
+    remotion;
     apiKey;
     apiUrl;
     fetchImpl;
@@ -523,6 +727,7 @@ export class Client {
         this.secrets = new SecretsClient(this);
         this.ci = new CiClient(this);
         this.images = new ImageClient(this);
+        this.remotion = new RemotionClient(this.sandboxes);
     }
     async usage(options = {}) {
         const query = options.orgId ? `?orgId=${encodeURIComponent(options.orgId)}` : "";
@@ -946,6 +1151,39 @@ export class SimulatorClient {
     async setRenderDebug(id, option, enabled, options = {}) {
         return await this.interact(id, { action: "setRenderDebug", option, enabled }, options);
     }
+    async accessibilityTree(id, options = {}) {
+        const timeoutMs = options.timeoutMs ?? DEFAULT_SIMULATOR_ACCESSIBILITY_TIMEOUT_MS;
+        assertIntegerRange(timeoutMs, 100, 60_000, "timeoutMs");
+        const context = {
+            sessionId: id,
+            platform: this.platform,
+            action: "accessibility",
+        };
+        const value = await this.client.request("GET", `/run-cloud/${this.platform}/${encodeURIComponent(id)}/accessibility`, undefined, undefined, {
+            signal: options.signal,
+            timeoutMs: timeoutMs + SIMULATOR_RESPONSE_MARGIN_MS,
+            timeoutMessage: `simulator accessibility capture did not complete within ${timeoutMs} ms`,
+            timeoutCode: "accessibility_timeout",
+            transportErrorCode: "accessibility_transport_error",
+            transportErrorMessage: "simulator accessibility could not reach the run.cloud API",
+            timeoutContext: context,
+            errorContext: {
+                ...context,
+                code: "accessibility_unavailable",
+            },
+        });
+        try {
+            return validateSimulatorAccessibilitySnapshot(value, this.platform);
+        }
+        catch (error) {
+            throw new RunCloudError(502, "simulator accessibility returned an invalid tree", {
+                ...context,
+                code: "accessibility_invalid_response",
+                retryable: true,
+                details: { reason: error instanceof Error ? error.message : "unknown" },
+            });
+        }
+    }
     async screenshot(id, options = {}) {
         const timeoutMs = options.timeoutMs ?? DEFAULT_SIMULATOR_INTERACTION_TIMEOUT_MS;
         const requestId = options.requestId ?? `screenshot_${randomUUID()}`;
@@ -1197,6 +1435,10 @@ export class SimulatorsClient {
         const { platform = "ios", ...requestOptions } = options;
         return await new SimulatorClient(this.client, platform).screenshot(id, requestOptions);
     }
+    async accessibilityTree(id, options = {}) {
+        const { platform = "ios", ...requestOptions } = options;
+        return await new SimulatorClient(this.client, platform).accessibilityTree(id, requestOptions);
+    }
     async startRecording(id, options = {}) {
         const { platform = "ios", ...requestOptions } = options;
         return await new SimulatorClient(this.client, platform).startRecording(id, requestOptions);