@limrun/api 0.23.2 → 0.24.0

package/src/exec-client.ts

@@ -6,6 +6,7 @@
  */
 
 import { createEventSource, type EventSourceClient, type EventSourceMessage } from 'eventsource-client';
+import { nodeProxyTransport } from './internal/proxy-transport';
 
 // =============================================================================
 // Types
@@ -153,7 +154,7 @@ export class ExecChildProcess implements PromiseLike<ExecResult> {
       return;
     }
     try {
-      await fetch(`${this.options.apiUrl}/exec/${this.execId}/cancel`, {
+      await nodeProxyTransport.fetch(`${this.options.apiUrl}/exec/${this.execId}/cancel`, {
         method: 'POST',
         headers: {
           Authorization: `Bearer ${this.options.token}`,
@@ -172,7 +173,7 @@ export class ExecChildProcess implements PromiseLike<ExecResult> {
     // 1. Trigger the build via POST /exec
     let execRes: Response;
     try {
-      execRes = await fetch(`${apiUrl}/exec`, {
+      execRes = await nodeProxyTransport.fetch(`${apiUrl}/exec`, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
@@ -273,6 +274,7 @@ export class ExecChildProcess implements PromiseLike<ExecResult> {
       try {
         const eventSource = createEventSource({
           url: eventsUrl,
+          fetch: nodeProxyTransport.fetch,
           headers: { Authorization: `Bearer ${this.options.token}` },
           onMessage: (message: EventSourceMessage) => {
             const data = typeof message.data === 'string' ? message.data : String(message.data ?? '');

package/src/folder-sync.ts

@@ -7,6 +7,7 @@ import { watchFolderTree } from './folder-sync-watcher';
 import { type IgnoreFn } from './folder-sync-ignore';
 import { Readable } from 'stream';
 import * as zlib from 'zlib';
+import { nodeProxyTransport } from './internal/proxy-transport';
 
 // =============================================================================
 // Folder Sync (HTTP batch)
@@ -218,18 +219,20 @@ async function httpFolderSyncBatch(
   };
   sourceStream.on('error', onStreamError);
   bodyStream.on('error', onStreamError);
-  const res = await fetch(url, {
-    method: 'POST',
-    headers,
-    body: bodyStream as any,
-    duplex: 'half' as any,
-    signal: controller.signal,
-  } as any).catch((err) => {
-    if (streamError) {
-      throw streamError;
-    }
-    throw err;
-  });
+  const res = await nodeProxyTransport
+    .fetch(url, {
+      method: 'POST',
+      headers,
+      body: bodyStream as any,
+      duplex: 'half' as any,
+      signal: controller.signal,
+    } as any)
+    .catch((err) => {
+      if (streamError) {
+        throw streamError;
+      }
+      throw err;
+    });
   const text = await res.text();
   if (!res.ok) {
     throw new Error(`folder-sync http failed: ${res.status} ${text}`);

package/src/instance-client.ts

@@ -1,9 +1,14 @@
 import { WebSocket, Data } from 'ws';
 import { exec } from 'node:child_process';
 
+import { downloadFileToLocalPath } from './internal/download-file';
+import { nodeProxyTransport } from './internal/proxy-transport';
 import { startTcpTunnel, isNonRetryableError } from './tunnel';
 import type { Tunnel } from './tunnel';
 
+const ANDROID_RECORDING_PATH = '/data/local/tmp/recordings/video_recording.mp4';
+const ANDROID_SIGNALING_PATH = '/ws';
+
 /**
  * Connection state of the instance client
  */
@@ -14,6 +19,19 @@ export type ConnectionState = 'connecting' | 'connected' | 'disconnected' | 'rec
  */
 export type ConnectionStateCallback = (state: ConnectionState) => void;
 
+function deriveEndpointWebSocketUrl(apiUrl: string): string {
+  const parsed = new URL(apiUrl);
+  parsed.protocol = parsed.protocol === 'https:' ? 'wss:' : 'ws:';
+  parsed.search = '';
+  parsed.hash = '';
+  parsed.pathname = `${parsed.pathname.replace(/\/$/, '')}${ANDROID_SIGNALING_PATH}`;
+  return parsed.toString().replace(/\/$/, '');
+}
+
+function buildDownloadUrl(apiUrl: string): string {
+  return `${apiUrl}/files?path=${encodeURIComponent(ANDROID_RECORDING_PATH)}`;
+}
+
 /**
  * A client for interacting with a Limbar instance
  */
@@ -64,6 +82,17 @@ export type InstanceClient = {
    * Open a URL/deeplink on Android.
    */
   openUrl: (url: string) => Promise<OpenUrlResult>;
+  /**
+   * Start recording device video. Use stopRecording() to finish the recording.
+   */
+  startRecording: () => Promise<void>;
+  /**
+   * Stop the active server-side recording.
+   * If `saveTo.presignedUrl` is provided, the server uploads the completed file there before resolving.
+   * If `saveTo.localPath` is provided, the client downloads the completed file to that path.
+   * Returns a download URL for the completed recording.
+   */
+  stopRecording: (saveTo: { presignedUrl?: string; localPath?: string }) => Promise<string>;
   /**
    * Disconnect from the Limbar instance
    */
@@ -151,13 +180,14 @@ export type AndroidElementNode = {
  */
 export type InstanceClientOptions = {
   /**
-   * The URL of the ADB WebSocket endpoint.
+   * HTTP base URL for the Android daemon. WebSocket control is derived from it
+   * using the `/ws` path, and recording downloads use the same base URL.
    */
-  adbUrl: string;
+  apiUrl: string;
   /**
-   * The URL of the main endpoint WebSocket.
+   * The URL of the ADB WebSocket endpoint.
    */
-  endpointUrl: string;
+  adbUrl?: string;
   /**
    * The token to use for the WebSocket connections.
    */
@@ -234,6 +264,8 @@ export type OpenUrlResult = {
   url: string;
 };
 
+type EmptyCommandResult = Record<string, never>;
+
 type ScreenshotErrorResponse = {
   type: 'screenshotError';
   message: string;
@@ -321,6 +353,20 @@ type OpenUrlResultMessage = {
   error?: CommandError;
 };
 
+type StartVideoRecordingResultMessage = {
+  type: 'startRecordingResult';
+  id: string;
+  payload?: EmptyCommandResult;
+  error?: CommandError;
+};
+
+type StopVideoRecordingResultMessage = {
+  type: 'stopRecordingResult';
+  id: string;
+  payload?: EmptyCommandResult;
+  error?: CommandError;
+};
+
 type KnownCommandResultMessage =
   | ScreenshotResultMessage
   | GetElementTreeResultMessage
@@ -330,7 +376,9 @@ type KnownCommandResultMessage =
   | PressKeyResultMessage
   | ScrollScreenResultMessage
   | ScrollElementResultMessage
-  | OpenUrlResultMessage;
+  | OpenUrlResultMessage
+  | StartVideoRecordingResultMessage
+  | StopVideoRecordingResultMessage;
 
 type ServerMessage =
   | ScreenshotResponse
@@ -349,6 +397,8 @@ type CommandRequestMap = {
   scrollScreen: { direction: ScrollDirection; amount?: number };
   scrollElement: AndroidElementTarget & { direction: ScrollDirection; amount?: number };
   openUrl: { url: string };
+  startRecording: Record<string, never>;
+  stopRecording: { upload?: { presignedUrl: string } };
 };
 
 type CommandResultMap = {
@@ -361,6 +411,8 @@ type CommandResultMap = {
   scrollScreen: ScrollResult;
   scrollElement: ScrollResult;
   openUrl: OpenUrlResult;
+  startRecording: EmptyCommandResult;
+  stopRecording: EmptyCommandResult;
 };
 
 type PendingRequest<T> = {
@@ -375,7 +427,9 @@ type PendingRequest<T> = {
  * @returns An InstanceClient for controlling the instance
  */
 export async function createInstanceClient(options: InstanceClientOptions): Promise<InstanceClient> {
-  const serverAddress = `${options.endpointUrl}?token=${options.token}`;
+  const endpointWebSocketUrl = deriveEndpointWebSocketUrl(options.apiUrl);
+  const serverAddress = `${endpointWebSocketUrl}?token=${options.token}`;
+  const recordingApiUrl = options.apiUrl;
   const logLevel = options.logLevel ?? 'info';
   const maxReconnectAttempts = options.maxReconnectAttempts ?? 6;
   const reconnectDelay = options.reconnectDelay ?? 1000;
@@ -387,7 +441,6 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
   let reconnectTimeout: NodeJS.Timeout | undefined;
   let intentionalDisconnect = false;
   let lastError: string | undefined;
-
   const pendingRequests: Map<string, PendingRequest<unknown>> = new Map();
   const pendingAssetRequestsByUrl: Map<string, Array<PendingRequest<void>>> = new Map();
 
@@ -521,6 +574,8 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
         case 'scrollScreenResult':
         case 'scrollElementResult':
         case 'openUrlResult':
+        case 'startRecordingResult':
+        case 'stopRecordingResult':
           return 'id' in message && typeof message.id === 'string';
         default:
           return false;
@@ -597,7 +652,8 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       cleanup();
       updateConnectionState('connecting');
 
-      ws = new WebSocket(serverAddress);
+      const proxyAgent = nodeProxyTransport.getWebSocketAgent(serverAddress);
+      ws = new WebSocket(serverAddress, proxyAgent ? { agent: proxyAgent } : {});
 
       ws.on('message', (data: Data) => {
         let message: ServerMessage;
@@ -757,6 +813,8 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             scrollScreen,
             scrollElement,
             openUrl,
+            startRecording,
+            stopRecording,
             disconnect,
             startAdbTunnel,
             sendAsset,
@@ -846,6 +904,23 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       };
     };
 
+    const startRecording = async (): Promise<void> => {
+      await sendRequest('startRecording', {});
+    };
+
+    const stopRecording = async (saveTo: { presignedUrl?: string; localPath?: string }): Promise<string> => {
+      const request: CommandRequestMap['stopRecording'] = {};
+      if (saveTo.presignedUrl) {
+        request.upload = { presignedUrl: saveTo.presignedUrl };
+      }
+      await sendRequest('stopRecording', request);
+      const downloadUrl = buildDownloadUrl(recordingApiUrl);
+      if (saveTo.localPath) {
+        await downloadFileToLocalPath(downloadUrl, options.token, saveTo.localPath);
+      }
+      return downloadUrl;
+    };
+
     const disconnect = (): void => {
       intentionalDisconnect = true;
       cleanup();
@@ -870,6 +945,9 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
      * client to it.
      */
     const startAdbTunnel = async (): Promise<Tunnel> => {
+      if (!options.adbUrl) {
+        throw new Error('adbUrl is required to start an ADB tunnel.');
+      }
       const tunnel = await startTcpTunnel(options.adbUrl, options.token, '127.0.0.1', 0, {
         maxReconnectAttempts,
         reconnectDelay,

package/src/internal/download-file.ts

@@ -0,0 +1,33 @@
+import fs from 'fs';
+import path from 'path';
+import { Readable } from 'stream';
+import { pipeline } from 'stream/promises';
+
+import { nodeProxyTransport } from './proxy-transport';
+
+export async function downloadFileToLocalPath(url: string, token: string, localPath: string): Promise<void> {
+  const maxRetries = 3;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const response = await nodeProxyTransport.fetch(url, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+      },
+    });
+    if (!response.ok) {
+      const errorBody = await response.text();
+      const isRetriable = response.status >= 500 && response.status < 600;
+      if (isRetriable && attempt < maxRetries) {
+        continue;
+      }
+      throw new Error(`Download failed: ${response.status} ${errorBody}`);
+    }
+    if (!response.body) {
+      throw new Error('Download failed: response body is missing');
+    }
+    await fs.promises.mkdir(path.dirname(localPath), { recursive: true });
+    await pipeline(Readable.fromWeb(response.body as any), fs.createWriteStream(localPath));
+    return;
+  }
+}

package/src/internal/proxy-transport.ts

@@ -0,0 +1,69 @@
+import type { Agent as HttpAgent } from 'http';
+
+import { HttpsProxyAgent } from 'https-proxy-agent';
+import { getProxyForUrl } from 'proxy-from-env';
+import { EnvHttpProxyAgent } from 'undici';
+
+import type { Fetch } from './builtin-types';
+
+class NodeProxyTransport {
+  private envHttpProxyAgent: EnvHttpProxyAgent | undefined;
+  private websocketAgents = new Map<string, HttpAgent>();
+
+  fetch: Fetch = async (input, init) => {
+    if (!this.hasProxyEnv()) {
+      return fetch(input, init);
+    }
+
+    return (fetch as any)(input, {
+      ...(init ?? {}),
+      dispatcher: this.getEnvHttpProxyAgent(),
+    });
+  };
+
+  getWebSocketAgent(url: string): HttpAgent | undefined {
+    if (!this.hasProxyEnv()) {
+      return undefined;
+    }
+
+    const proxyUrl = getProxyForUrl(this.getWebSocketProxyLookupUrl(url));
+    if (!proxyUrl) {
+      return undefined;
+    }
+
+    let agent = this.websocketAgents.get(proxyUrl);
+    if (!agent) {
+      const createdAgent = new HttpsProxyAgent(proxyUrl);
+      this.websocketAgents.set(proxyUrl, createdAgent);
+      agent = createdAgent;
+    }
+
+    return agent;
+  }
+
+  private getEnvHttpProxyAgent(): EnvHttpProxyAgent {
+    this.envHttpProxyAgent ??= new EnvHttpProxyAgent();
+    return this.envHttpProxyAgent;
+  }
+
+  private hasProxyEnv(): boolean {
+    if (typeof process === 'undefined' || !process.versions?.node) {
+      return false;
+    }
+
+    const env = process.env;
+    return !!(env['http_proxy'] || env['HTTP_PROXY'] || env['https_proxy'] || env['HTTPS_PROXY']);
+  }
+
+  private getWebSocketProxyLookupUrl(url: string): string {
+    const lookupUrl = new URL(url);
+    if (lookupUrl.protocol === 'ws:') {
+      lookupUrl.protocol = 'http:';
+    } else if (lookupUrl.protocol === 'wss:') {
+      lookupUrl.protocol = 'https:';
+    }
+    return lookupUrl.toString();
+  }
+}
+
+export const nodeProxyTransport = new NodeProxyTransport();

package/src/internal/shims.ts

@@ -8,11 +8,12 @@
  */
 
 import type { Fetch } from './builtin-types';
+import { nodeProxyTransport } from './proxy-transport';
 import type { ReadableStream } from './shim-types';
 
 export function getDefaultFetch(): Fetch {
   if (typeof fetch !== 'undefined') {
-    return fetch as any;
+    return nodeProxyTransport.fetch;
   }
 
   throw new Error(

package/src/internal/utils/env.ts

@@ -9,10 +9,10 @@
  */
 export const readEnv = (env: string): string | undefined => {
   if (typeof (globalThis as any).process !== 'undefined') {
-    return (globalThis as any).process.env?.[env]?.trim() ?? undefined;
+    return (globalThis as any).process.env?.[env]?.trim() || undefined;
   }
   if (typeof (globalThis as any).Deno !== 'undefined') {
-    return (globalThis as any).Deno.env?.get?.(env)?.trim();
+    return (globalThis as any).Deno.env?.get?.(env)?.trim() || undefined;
   }
   return undefined;
 };

package/src/ios-client.ts

@@ -1,14 +1,14 @@
-import { WebSocket, Data } from 'ws';
-import fs from 'fs';
 import os from 'os';
-import path from 'path';
 import crypto from 'crypto';
+import path from 'path';
+import fs from 'fs';
+import { WebSocket, Data } from 'ws';
 import { EventEmitter } from 'events';
-import { Readable } from 'stream';
-import { pipeline } from 'stream/promises';
 import { isNonRetryableError } from './tunnel';
 import { type SyncFolderResult, type FolderSyncOptions, syncFolder } from './folder-sync';
 import { createIgnoreFn } from './folder-sync-ignore';
+import { downloadFileToLocalPath } from './internal/download-file';
+import { nodeProxyTransport } from './internal/proxy-transport';
 
 /**
  * Connection state of the instance client
@@ -29,33 +29,6 @@ function generateRecordingFilename(): string {
   return `ios_video_${formattedDate}_${rand}.mp4`;
 }
 
-async function downloadFileToLocalPath(url: string, token: string, localPath: string): Promise<void> {
-  const maxRetries = 3;
-
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    const response = await fetch(url, {
-      method: 'GET',
-      headers: {
-        Authorization: `Bearer ${token}`,
-      },
-    });
-    if (!response.ok) {
-      const errorBody = await response.text();
-      const isRetriable = response.status >= 500 && response.status < 600;
-      if (isRetriable && attempt < maxRetries) {
-        continue;
-      }
-      throw new Error(`Download failed: ${response.status} ${errorBody}`);
-    }
-    if (!response.body) {
-      throw new Error('Download failed: response body is missing');
-    }
-    await fs.promises.mkdir(path.dirname(localPath), { recursive: true });
-    await pipeline(Readable.fromWeb(response.body as any), fs.createWriteStream(localPath));
-    return;
-  }
-}
-
 function buildDownloadUrl(apiUrl: string, filename: string): string {
   return `${apiUrl}/files?name=${encodeURIComponent(filename)}`;
 }
@@ -849,7 +822,8 @@ export class LogStream extends EventEmitter {
 
   /** @internal - Establish the dedicated WebSocket connection */
   private _connect(): void {
-    this.ws = new WebSocket(this.wsUrl);
+    const proxyAgent = nodeProxyTransport.getWebSocketAgent(this.wsUrl);
+    this.ws = new WebSocket(this.wsUrl, proxyAgent ? { agent: proxyAgent } : {});
 
     this.ws.on('open', () => {
       if (this.stopped) {
@@ -1121,7 +1095,8 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       cleanup();
       updateConnectionState('connecting');
 
-      ws = new WebSocket(endpointWebSocketUrl);
+      const proxyAgent = nodeProxyTransport.getWebSocketAgent(endpointWebSocketUrl);
+      ws = new WebSocket(endpointWebSocketUrl, proxyAgent ? { agent: proxyAgent } : {});
 
       ws.on('message', (data: Data) => {
         let message: ServerResponse;
@@ -1594,7 +1569,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       try {
         // Node's fetch (undici) supports streaming request bodies but TS DOM types may not include
         // `duplex` and may not accept Node ReadStreams as BodyInit in some configs.
-        const response = await fetch(uploadUrl, {
+        const response = await nodeProxyTransport.fetch(uploadUrl, {
           method: 'PUT',
           headers: {
             'Content-Type': 'application/octet-stream',

package/src/resources/android-instances.ts

@@ -72,8 +72,8 @@ export namespace AndroidInstance {
   export interface Spec {
     /**
      * After how many minutes of inactivity should the instance be terminated. Example
-     * values 1m, 10m, 3h. Default is 3m. Providing "0" disables inactivity checks
-     * altogether.
+     * values 1m, 10m, 3h. Default is 3m. Providing "0" uses the organization's default
+     * inactivity timeout.
      */
     inactivityTimeout: string;
 
@@ -97,6 +97,8 @@ export namespace AndroidInstance {
 
     adbWebSocketUrl?: string;
 
+    apiUrl?: string;
+
     endpointWebSocketUrl?: string;
 
     errorMessage?: string;
@@ -162,8 +164,8 @@ export namespace AndroidInstanceCreateParams {
 
     /**
      * After how many minutes of inactivity should the instance be terminated. Example
-     * values 1m, 10m, 3h. Default is 3m. Providing "0" disables inactivity checks
-     * altogether.
+     * values 1m, 10m, 3h. Default is 3m. Providing "0" uses the organization's default
+     * inactivity timeout.
      */
     inactivityTimeout?: string;
 

package/src/resources/assets-helpers.ts

@@ -3,6 +3,7 @@ import { createHash } from 'crypto';
 import { promises as fs } from 'fs';
 
 import { RequestOptions } from '../internal/request-options';
+import { nodeProxyTransport } from '../internal/proxy-transport';
 import { Assets as GeneratedAssets } from './assets';
 
 export interface AssetGetOrUploadParams {
@@ -45,7 +46,7 @@ export class Assets extends GeneratedAssets {
         md5: creationResponse.md5,
       };
     }
-    const uploadResponse = await fetch(creationResponse.signedUploadUrl, {
+    const uploadResponse = await nodeProxyTransport.fetch(creationResponse.signedUploadUrl, {
       headers: {
         'Content-Length': data.length.toString(),
         'Content-Type': 'application/octet-stream',

package/src/resources/index.ts

@@ -22,5 +22,12 @@ export {
   type IosInstanceListParams,
   type IosInstancesItems,
 } from './ios-instances';
+export {
+  XcodeInstances,
+  type XcodeInstance,
+  type XcodeInstanceCreateParams,
+  type XcodeInstanceListParams,
+  type XcodeInstancesItems,
+} from './xcode-instances';
 
 export { Assets, AssetGetOrUploadParams, AssetGetOrUploadResponse } from './assets-helpers';

package/src/resources/ios-instances.ts

@@ -72,8 +72,8 @@ export namespace IosInstance {
   export interface Spec {
     /**
      * After how many minutes of inactivity should the instance be terminated. Example
-     * values 1m, 10m, 3h. Default is 3m. Providing "0" disables inactivity checks
-     * altogether.
+     * values 1m, 10m, 3h. Default is 3m. Providing "0" uses the organization's default
+     * inactivity timeout.
      */
     inactivityTimeout: string;
 
@@ -162,8 +162,8 @@ export namespace IosInstanceCreateParams {
 
     /**
      * After how many minutes of inactivity should the instance be terminated. Example
-     * values 1m, 10m, 3h. Default is 3m. Providing "0" disables inactivity checks
-     * altogether.
+     * values 1m, 10m, 3h. Default is 3m. Providing "0" uses the organization's default
+     * inactivity timeout.
      */
     inactivityTimeout?: string;