@limrun/api 0.18.2 → 0.19.0

package/src/ios-client.ts

@@ -2,6 +2,7 @@ import { WebSocket, Data } from 'ws';
 import fs from 'fs';
 import { EventEmitter } from 'events';
 import { isNonRetryableError } from './tunnel';
+import { syncApp as syncAppImpl, type SyncFolderResult, type FolderSyncOptions } from './folder-sync';
 
 /**
  * Connection state of the instance client
@@ -91,6 +92,17 @@ export type LsofEntry = {
   path: string;
 };
 
+export type DeviceInfo = {
+  /** Device UDID */
+  udid: string;
+  /** Screen width in points (Swift Double) */
+  screenWidth: number;
+  /** Screen height in points (Swift Double) */
+  screenHeight: number;
+  /** Device model name */
+  model: string;
+};
+
 export type AppInstallationResult = {
   /** The URL the app was installed from */
   url: string;
@@ -98,6 +110,18 @@ export type AppInstallationResult = {
   bundleId: string;
 };
 
+/**
+ * Result from a command execution (xcrun, xcodebuild, etc.)
+ */
+export type CommandResult = {
+  /** Standard output from the command */
+  stdout: string;
+  /** Standard error from the command */
+  stderr: string;
+  /** Exit code of the command */
+  exitCode: number;
+};
+
 export type AppInstallationOptions = {
   /** MD5 hash for caching - if provided and matches cached version, skips download */
   md5?: string;
@@ -212,6 +236,33 @@ export type InstanceClient = {
    */
   setOrientation: (orientation: 'Portrait' | 'Landscape') => Promise<void>;
 
+  /**
+   * Scroll in a direction by a specified number of pixels
+   * @param direction Direction content moves: "up", "down", "left", "right"
+   * @param pixels Total pixels to scroll (finger movement distance)
+   * @param options Optional scroll options
+   * @param options.coordinate Starting coordinate [x, y]. Defaults to screen center.
+   * @param options.momentum 0.0-1.0 controlling scroll speed and inertia. 0 (default) = slow scroll, no momentum. 1 = fastest with max inertia.
+   */
+  scroll: (
+    direction: 'up' | 'down' | 'left' | 'right',
+    pixels: number,
+    options?: { coordinate?: [number, number]; momentum?: number },
+  ) => Promise<void>;
+
+  /**
+   * Sync an iOS app bundle folder to the server and (optionally) install/launch it.
+   */
+  syncApp: (
+    localAppBundlePath: string,
+    opts?: {
+      install?: boolean;
+      maxPatchBytes?: number;
+      launchMode?: 'ForegroundIfRunning' | 'RelaunchIfRunning' | 'FailIfRunning';
+      watch?: boolean;
+    },
+  ) => Promise<SyncFolderResult>;
+
   /**
    * Disconnect from the Limrun instance
    */
@@ -278,12 +329,68 @@ export type InstanceClient = {
    */
   cp: (name: string, path: string) => Promise<string>;
 
+  /**
+   * Run `xcrun` command with the given arguments.
+   * Unlike simctl, this returns the complete output once the command finishes (non-streaming).
+   *
+   * Only the following flags are allowed:
+   * - `--sdk <value>`: Specify the SDK (e.g., 'iphonesimulator', 'iphoneos')
+   * - `--show-sdk-version`: Show the SDK version
+   * - `--show-sdk-build-version`: Show the SDK build version
+   * - `--show-sdk-platform-version`: Show the SDK platform version
+   *
+   * @param args Arguments to pass to xcrun
+   * @returns A promise that resolves to the command result with stdout, stderr, and exit code
+   *
+   * @example
+   * ```typescript
+   * // Get the SDK version for iphonesimulator
+   * const result = await client.xcrun(['--sdk', 'iphonesimulator', '--show-sdk-version']);
+   * console.log('SDK version:', result.stdout.trim());
+   *
+   * // Get the SDK build version (default SDK)
+   * const buildResult = await client.xcrun(['--show-sdk-build-version']);
+   * console.log('Build version:', buildResult.stdout.trim());
+   *
+   * // Get the SDK platform version for iphoneos
+   * const platformResult = await client.xcrun(['--sdk', 'iphoneos', '--show-sdk-platform-version']);
+   * console.log('Platform version:', platformResult.stdout.trim());
+   * ```
+   */
+  xcrun: (args: string[]) => Promise<CommandResult>;
+
+  /**
+   * Run `xcodebuild` command with the given arguments.
+   * Returns the complete output once the command finishes (non-streaming).
+   *
+   * Only `-version` is allowed (validated server-side).
+   *
+   * @param args Arguments to pass to xcodebuild
+   * @returns A promise that resolves to the command result with stdout, stderr, and exit code
+   *
+   * @example
+   * ```typescript
+   * // Get the Xcode version
+   * const result = await client.xcodebuild(['-version']);
+   * console.log('Xcode version:', result.stdout);
+   * // Output: Xcode 16.0
+   * //         Build version 16A242d
+   * ```
+   */
+  xcodebuild: (args: string[]) => Promise<CommandResult>;
+
   /**
    * List all open files on the instance. Useful to start tunnel to the
    * UNIX sockets listed here.
    * @returns A promise that resolves to a list of open files.
    */
   lsof: () => Promise<LsofEntry[]>;
+
+  /**
+   * Device information fetched during client initialization.
+   * Contains id, udid, screen dimensions, and model.
+   */
+  deviceInfo: DeviceInfo;
 };
 
 /**
@@ -363,6 +470,11 @@ type ServerResponse = {
   url?: string;
   bundleId?: string;
   files?: LsofEntry[];
+  // Device info fields
+  udid?: string;
+  screenWidth?: number;
+  screenHeight?: number;
+  model?: string;
   // Simctl streaming fields
   stdout?: string;
   stderr?: string;
@@ -725,12 +837,29 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       launchAppResult: () => undefined,
       listAppsResult: (msg) => JSON.parse(msg.apps || '[]') as InstalledApp[],
       listOpenFilesResult: (msg) => msg.files || [],
+      deviceInfoResult: (msg) => ({
+        udid: msg.udid!,
+        screenWidth: msg.screenWidth!,
+        screenHeight: msg.screenHeight!,
+        model: msg.model!,
+      }),
       openUrlResult: () => undefined,
       appInstallationResult: (msg) => ({
         url: msg.url || '',
         bundleId: msg.bundleId || '',
       }),
       setOrientationResult: () => undefined,
+      scrollResult: () => undefined,
+      xcrunResult: (msg): CommandResult => ({
+        stdout: msg.stdout ? Buffer.from(msg.stdout, 'base64').toString('utf-8') : '',
+        stderr: msg.stderr ? Buffer.from(msg.stderr, 'base64').toString('utf-8') : '',
+        exitCode: msg.exitCode ?? -1,
+      }),
+      xcodebuildResult: (msg): CommandResult => ({
+        stdout: msg.stdout ? Buffer.from(msg.stdout, 'base64').toString('utf-8') : '',
+        stderr: msg.stderr ? Buffer.from(msg.stderr, 'base64').toString('utf-8') : '',
+        exitCode: msg.exitCode ?? -1,
+      }),
     };
 
     const setupWebSocket = (): void => {
@@ -846,7 +975,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
         }
       });
 
-      ws.on('open', () => {
+      ws.on('open', async () => {
         logger.debug(`Connected to ${endpointWebSocketUrl}`);
         reconnectAttempts = 0;
         lastError = undefined;
@@ -859,6 +988,16 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
         }, 30_000);
 
         if (!hasResolved) {
+          try {
+            // Fetch device info before resolving connection
+            cachedDeviceInfo = await fetchDeviceInfo();
+            logger.debug('Device info fetched:', cachedDeviceInfo);
+          } catch (err) {
+            logger.error('Failed to fetch device info:', err);
+            rejectConnection(err as Error);
+            return;
+          }
+
           hasResolved = true;
           resolveConnection({
             screenshot,
@@ -875,12 +1014,17 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             openUrl,
             installApp,
             setOrientation,
+            scroll,
+            syncApp,
             disconnect,
             getConnectionState,
             onConnectionStateChange,
             simctl,
+            xcrun,
+            xcodebuild,
             cp,
             lsof,
+            deviceInfo: cachedDeviceInfo,
           });
         }
       });
@@ -950,10 +1094,81 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return sendRequest<void>('setOrientation', { orientation });
     };
 
+    const scroll = (
+      direction: 'up' | 'down' | 'left' | 'right',
+      pixels: number,
+      options?: { coordinate?: [number, number]; momentum?: number },
+    ): Promise<void> => {
+      return sendRequest<void>('scroll', {
+        direction,
+        pixels,
+        coordinate: options?.coordinate,
+        momentum: options?.momentum,
+      });
+    };
+
+    const syncApp = async (
+      localAppBundlePath: string,
+      opts?: {
+        install?: boolean;
+        maxPatchBytes?: number;
+        launchMode?: 'ForegroundIfRunning' | 'RelaunchIfRunning' | 'FailIfRunning';
+        watch?: boolean;
+      },
+    ): Promise<SyncFolderResult> => {
+      if (!cachedDeviceInfo) {
+        throw new Error('Device info not available yet; wait for client connection to be established.');
+      }
+      const appSyncOpts: FolderSyncOptions = {
+        apiUrl: options.apiUrl,
+        token: options.token,
+        udid: cachedDeviceInfo.udid,
+        log: (level, msg) => {
+          switch (level) {
+            case 'debug':
+              logger.debug(msg);
+              break;
+            case 'info':
+              logger.info(msg);
+              break;
+            case 'warn':
+              logger.warn(msg);
+              break;
+            case 'error':
+              logger.error(msg);
+              break;
+            default:
+              logger.info(msg);
+              break;
+          }
+        },
+        ...(opts?.install !== undefined ? { install: opts.install } : {}),
+        ...(opts?.maxPatchBytes !== undefined ? { maxPatchBytes: opts.maxPatchBytes } : {}),
+        ...(opts?.launchMode !== undefined ? { launchMode: opts.launchMode } : {}),
+        ...(opts?.watch !== undefined ? { watch: opts.watch } : {}),
+      };
+      return await syncAppImpl(localAppBundlePath, appSyncOpts);
+    };
+
     const lsof = (): Promise<LsofEntry[]> => {
       return sendRequest<LsofEntry[]>('listOpenFiles', { kind: 'unix' });
     };
 
+    const xcrun = (args: string[]): Promise<CommandResult> => {
+      return sendRequest<CommandResult>('xcrun', { args });
+    };
+
+    const xcodebuild = (args: string[]): Promise<CommandResult> => {
+      return sendRequest<CommandResult>('xcodebuild', { args });
+    };
+
+    const fetchDeviceInfo = (): Promise<DeviceInfo> => {
+      return sendRequest<DeviceInfo>('deviceInfo');
+    };
+
+    // Cached device info, populated during connection
+    let cachedDeviceInfo: DeviceInfo;
+
     const simctl = (args: string[], opts: { disconnectOnExit?: boolean } = {}): SimctlExecution => {
       const id = generateId();
 
@@ -1014,6 +1229,8 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       const fileStream = fs.createReadStream(filePath);
       const uploadUrl = `${options.apiUrl}/files?name=${encodeURIComponent(name)}`;
       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, {
           method: 'PUT',
           headers: {
@@ -1021,9 +1238,9 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             'Content-Length': fs.statSync(filePath).size.toString(),
             Authorization: `Bearer ${options.token}`,
           },
-          body: fileStream,
-          duplex: 'half',
-        });
+          body: fileStream as any,
+          duplex: 'half' as any,
+        } as any);
         if (!response.ok) {
           const errorBody = await response.text();
           logger.debug(`Upload failed: ${response.status} ${errorBody}`);

package/src/resources/android-instances.ts

@@ -132,12 +132,12 @@ export interface AndroidInstanceCreateParams {
   wait?: boolean;
 
   /**
-   * Body param:
+   * Body param
    */
   metadata?: AndroidInstanceCreateParams.Metadata;
 
   /**
-   * Body param:
+   * Body param
    */
   spec?: AndroidInstanceCreateParams.Spec;
 }

package/src/resources/assets.ts

@@ -56,11 +56,22 @@ export interface Asset {
 
   name: string;
 
+  /**
+   * Human-readable display name for the asset. If not set, the name should be used.
+   */
+  displayName?: string;
+
   /**
    * Returned only if there is a corresponding file uploaded already.
    */
   md5?: string;
 
+  /**
+   * The operating system this asset is for. If not set, the asset is available for
+   * all platforms.
+   */
+  os?: 'ios' | 'android';
+
   signedDownloadUrl?: string;
 
   signedUploadUrl?: string;

package/src/resources/ios-instances.ts

@@ -120,12 +120,12 @@ export interface IosInstanceCreateParams {
   wait?: boolean;
 
   /**
-   * Body param:
+   * Body param
    */
   metadata?: IosInstanceCreateParams.Metadata;
 
   /**
-   * Body param:
+   * Body param
    */
   spec?: IosInstanceCreateParams.Spec;
 }

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.18.2'; // x-release-please-version
+export const VERSION = '0.19.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.18.2";
+export declare const VERSION = "0.19.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.18.2";
+export declare const VERSION = "0.19.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.18.2'; // x-release-please-version
+exports.VERSION = '0.19.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.18.2'; // x-release-please-version
+export const VERSION = '0.19.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map