runcloud 0.1.108 → 0.1.110

package/README.md

@@ -64,12 +64,22 @@ runcloud ios create --model iphone --install ./MyApp.app   # boot a simulator an
 runcloud ios list                                          # list active sessions
 runcloud ios get <id>                                      # inspect a session (viewer URL, status)
 runcloud ios open-url myapp://path --id <id>               # open a URL or deep link
+runcloud ios tap <id> 0.5 0.75                             # normalized top-left display coordinates
+runcloud ios type-text <id> "Hello from iOS!"              # printable US ASCII, tab, and line feed
+runcloud ios screenshot <id> --output ios.png              # save a PNG without exposing the viewer URL
+runcloud ios recording start <id> --json                   # start an idempotent MP4 screen recording
+runcloud ios recording stop <id> <recording-id> --json     # stop and finalize it
+runcloud ios recording download <id> <recording-id> \
+  --output ios.mp4 --json                                  # download through the authenticated API
 runcloud ios logs <id> --tail 200                          # read logs from this lease
 runcloud ios logs <id> --follow                            # follow new log entries
 runcloud ios delete <id>                                   # release the session
 
 # Android works the same under `runcloud android …`
 runcloud android create --model pixel
+runcloud android swipe <id> 0.5 0.8 0.5 0.2 --duration 250
+runcloud android press-key <id> enter
+runcloud android screenshot <id> --output android.png --json
 ```
 
 Useful `create` flags: `--region`, `--display-name`, `--inactivity-timeout 3m`,
@@ -80,6 +90,29 @@ The same `logs` commands work for Android. Snapshots are limited to the active
 lease and accept 1 to 1,000 lines. In follow mode, `--json` emits one JSON object
 per line.
 
+Both platforms also expose `gesture`, `press-button`, `rotate`, `reload`,
+`scroll`, `toggle-software-keyboard`, `simulate-memory-warning`,
+`rotate-digital-crown`, and `set-render-debug`. Run `runcloud ios --help` or
+`runcloud android --help` for the full surface and per-command input choices.
+Current mobile sessions return an unsupported-action error for Digital Crown
+input; render-debug controls are iOS-only. Android Emulator sessions also
+report `capsLock`, `numLock`, and `scrollLock` as unsupported keys.
+Coordinates are inclusive normalized display coordinates: `(0, 0)` is the
+top-left and `(1, 1)` is the bottom-right.
+
+The `recording` group is shared by iOS and Android. It provides `start`,
+`list`, `status` (`get` alias), `stop`, and `download`. Pass a stable
+`--idempotency-key` to retry `start` without creating a second recording.
+`download --output <path>` validates the MP4 and reports its byte size and
+SHA-256 digest without printing a signed storage URL.
+
+Interaction commands wait for a correlated simulator acknowledgement. They
+accept `--timeout <milliseconds>` (15 seconds by default), `--request-id <id>`,
+and `--json`. Successful JSON is the API's typed completion envelope. Failures
+write a stable `{ ok: false, error: { code, message, retryable } }` envelope to
+stderr and exit non-zero. Ctrl-C cancels only the in-flight command, leaves the
+session active, and exits with code 130.
+
 ### Tunnel a local dev server into a simulator
 
 ```bash

package/dist/api.js

@@ -3,28 +3,84 @@ export class ApiError extends Error {
     status;
     detail;
     path;
-    constructor(status, detail, path) {
+    code;
+    retryable;
+    details;
+    requestId;
+    sessionId;
+    platform;
+    action;
+    interactionStatus;
+    acceptedAt;
+    completedAt;
+    durationMs;
+    constructor(status, detail, path, context = {}) {
         super(`API ${status}: ${detail}`);
         this.status = status;
         this.detail = detail;
         this.path = path;
+        this.name = 'ApiError';
+        Object.assign(this, context);
     }
 }
-function parsedErrorDetail(body) {
+export class ApiTransportError extends Error {
+    path;
+    originalError;
+    constructor(path, originalError) {
+        super('Could not reach the run.cloud API');
+        this.path = path;
+        this.originalError = originalError;
+        this.name = 'ApiTransportError';
+    }
+}
+function parsedError(body) {
     try {
         const parsed = JSON.parse(body);
-        const detail = parsed.detail ?? parsed.error ?? parsed.message;
-        if (typeof detail === 'string')
-            return detail;
-        if (detail !== undefined)
-            return JSON.stringify(detail);
+        const nested = parsed.error && typeof parsed.error === 'object'
+            ? parsed.error
+            : undefined;
+        const rawDetail = nested?.message ?? parsed.detail ?? parsed.error ?? parsed.message;
+        const detail = typeof rawDetail === 'string'
+            ? rawDetail
+            : rawDetail === undefined ? '' : JSON.stringify(rawDetail);
+        const retryable = nested?.retryable ?? parsed.retryable;
+        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;
+        return {
+            detail,
+            ...(typeof (nested?.code ?? parsed.code) === 'string'
+                ? { code: (nested?.code ?? parsed.code) }
+                : {}),
+            ...(typeof retryable === 'boolean' ? { retryable } : {}),
+            ...((nested?.details ?? parsed.details) === undefined
+                ? {}
+                : { details: nested?.details ?? parsed.details }),
+            ...(typeof parsed.requestId === 'string' ? { requestId: parsed.requestId } : {}),
+            ...(typeof parsed.sessionId === 'string' ? { sessionId: parsed.sessionId } : {}),
+            ...(platform ? { platform } : {}),
+            ...(typeof parsed.action === 'string' ? { action: parsed.action } : {}),
+            ...(interactionStatus ? { interactionStatus } : {}),
+            ...(typeof parsed.acceptedAt === 'string' ? { acceptedAt: parsed.acceptedAt } : {}),
+            ...(typeof parsed.completedAt === 'string' ? { completedAt: parsed.completedAt } : {}),
+            ...(typeof parsed.durationMs === 'number' && Number.isFinite(parsed.durationMs)
+                ? { durationMs: parsed.durationMs }
+                : {}),
+        };
     }
     catch {
     }
     if (/<(?:!doctype|html)\b/i.test(body)) {
-        return 'the API edge returned an HTML error page; retry the request or use the streaming/direct-transfer command';
+        return {
+            detail: 'the API edge returned an HTML error page; retry the request or use the streaming/direct-transfer command',
+        };
     }
-    return body;
+    return { detail: body };
 }
 export class ApiClient {
     baseUrl;
@@ -33,18 +89,27 @@ export class ApiClient {
         this.baseUrl = baseUrl;
         this.token = token;
     }
-    async request(method, path, body) {
-        const res = await fetch(`${this.baseUrl}${path}`, {
-            method,
-            headers: {
-                Authorization: `Bearer ${this.token}`,
-                ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
-            },
-            body: body !== undefined ? JSON.stringify(body) : undefined,
-        });
+    async request(method, path, body, options = {}) {
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}${path}`, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.token}`,
+                    ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+                },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: options.signal,
+            });
+        }
+        catch (error) {
+            if (options.signal?.aborted)
+                throw options.signal.reason ?? error;
+            throw new ApiTransportError(path, error);
+        }
         if (!res.ok) {
-            const detail = parsedErrorDetail(await res.text());
-            throw new ApiError(res.status, detail, path);
+            const { detail, ...context } = parsedError(await res.text());
+            throw new ApiError(res.status, detail, path, context);
         }
         const contentType = res.headers.get('content-type') ?? '';
         return contentType.includes('application/json') ? res.json() : res;
@@ -56,8 +121,8 @@ export class ApiClient {
         const response = await this.request('GET', path);
         return response.text();
     }
-    post(path, body) {
-        return this.request('POST', path, body);
+    post(path, body, options = {}) {
+        return this.request('POST', path, body, options);
     }
     async postWithHeaders(path, body, headers) {
         const res = await fetch(`${this.baseUrl}${path}`, {
@@ -70,8 +135,8 @@ export class ApiClient {
             body: JSON.stringify(body),
         });
         if (!res.ok) {
-            const detail = parsedErrorDetail(await res.text());
-            throw new ApiError(res.status, detail, path);
+            const { detail, ...context } = parsedError(await res.text());
+            throw new ApiError(res.status, detail, path, context);
         }
         const contentType = res.headers.get('content-type') ?? '';
         return contentType.includes('application/json') ? res.json() : res;
@@ -95,8 +160,8 @@ export class ApiClient {
             body: body,
         });
         if (!res.ok) {
-            const detail = parsedErrorDetail(await res.text());
-            throw new ApiError(res.status, detail, path);
+            const { detail, ...context } = parsedError(await res.text());
+            throw new ApiError(res.status, detail, path, context);
         }
         const contentType_ = res.headers.get('content-type') ?? '';
         return contentType_.includes('application/json') ? res.json() : res;
@@ -110,20 +175,29 @@ export class ApiClient {
             body: form,
         });
         if (!res.ok) {
-            const detail = parsedErrorDetail(await res.text());
-            throw new ApiError(res.status, detail, path);
+            const { detail, ...context } = parsedError(await res.text());
+            throw new ApiError(res.status, detail, path, context);
         }
         const contentType = res.headers.get('content-type') ?? '';
         return contentType.includes('application/json') ? res.json() : res;
     }
-    async getBinary(path) {
-        const res = await fetch(`${this.baseUrl}${path}`, {
-            method: 'GET',
-            headers: { Authorization: `Bearer ${this.token}` },
-        });
+    async getBinary(path, options = {}) {
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}${path}`, {
+                method: 'GET',
+                headers: { Authorization: `Bearer ${this.token}`, ...options.headers },
+                signal: options.signal,
+            });
+        }
+        catch (error) {
+            if (options.signal?.aborted)
+                throw options.signal.reason ?? error;
+            throw new ApiTransportError(path, error);
+        }
         if (!res.ok) {
-            const detail = await res.text().catch(() => '');
-            throw new ApiError(res.status, detail || res.statusText, path);
+            const { detail, ...context } = parsedError(await res.text().catch(() => ''));
+            throw new ApiError(res.status, detail || res.statusText, path, context);
         }
         return Buffer.from(await res.arrayBuffer());
     }
@@ -133,8 +207,8 @@ export class ApiClient {
             headers: { Authorization: `Bearer ${this.token}`, Accept: 'text/event-stream' },
         });
         if (!res.ok) {
-            const detail = parsedErrorDetail(await res.text().catch(() => ''));
-            throw new ApiError(res.status, detail || res.statusText, path);
+            const { detail, ...context } = parsedError(await res.text().catch(() => ''));
+            throw new ApiError(res.status, detail || res.statusText, path, context);
         }
         const decoder = new TextDecoder();
         for await (const chunk of res.body) {