@limrun/api 0.28.3 → 0.28.5

package/src/ios-client.ts

@@ -4,7 +4,7 @@ import path from 'path';
 import fs from 'fs';
 import { WebSocket, Data } from 'ws';
 import { EventEmitter } from 'events';
-import { isNonRetryableError } from './tunnel';
+import { assertPort, isNonRetryableError, startReverseTcpTunnel, type ReverseTunnel } from './tunnel';
 import { type SyncFolderResult, type FolderSyncOptions, syncFolder } from './folder-sync';
 import { createIgnoreFn } from './folder-sync-ignore';
 import { downloadFileToLocalPath } from './internal/download-file';
@@ -21,11 +21,31 @@ export type ConnectionState = 'connecting' | 'connected' | 'disconnected' | 'rec
 export type ConnectionStateCallback = (state: ConnectionState) => void;
 
 const ACTIVE_RECORDING_FILENAME = 'recording.mp4';
+export const REVERSE_TUNNEL_REMOTE_PORT_MIN = 57090;
+export const REVERSE_TUNNEL_REMOTE_PORT_MAX = 57099;
 
 function buildDownloadUrl(apiUrl: string): string {
   return `${apiUrl}/files?name=${encodeURIComponent(ACTIVE_RECORDING_FILENAME)}`;
 }
 
+export function deriveReverseTunnelUrl(apiUrl: string, remotePort: number): string {
+  const url = new URL(apiUrl);
+  if (url.protocol === 'https:') {
+    url.protocol = 'wss:';
+  } else if (url.protocol === 'http:') {
+    url.protocol = 'ws:';
+  } else {
+    throw new Error(`Unsupported apiUrl protocol for reverse tunnel: ${url.protocol}`);
+  }
+  url.pathname = `${url.pathname.replace(/\/+$/, '')}/reverse-tunnel`;
+  url.search = '';
+  url.hash = '';
+  url.searchParams.set('remotePort', String(remotePort));
+  return url.toString();
+}
+
+export type { ReverseTunnel } from './tunnel';
+
 /**
  * Events emitted by a simctl execution
  */
@@ -227,6 +247,35 @@ export type SoftResetOptions = {
   strategy?: SoftResetStrategy;
 };
 
+export type LaunchAppMode = 'ForegroundIfRunning' | 'RelaunchIfRunning';
+
+export type DetoxLaunchRuntime = {
+  kind: 'detox';
+  serverUrl: string;
+  sessionId: string;
+  version?: string;
+};
+
+export type LaunchAppRuntime = DetoxLaunchRuntime;
+
+type StandardLaunchAppOptions = {
+  /**
+   * Launch behavior when the app may already be running.
+   * Defaults to `ForegroundIfRunning` server-side.
+   */
+  mode?: LaunchAppMode;
+  runtime?: undefined;
+};
+
+type RuntimeLaunchAppOptions = {
+  /** Runtime launches must relaunch so runtime injection is applied. */
+  mode?: Extract<LaunchAppMode, 'RelaunchIfRunning'>;
+  /** Optional app runtime to attach during launch. */
+  runtime: LaunchAppRuntime;
+};
+
+export type LaunchAppOptions = StandardLaunchAppOptions | RuntimeLaunchAppOptions;
+
 /**
  * Result of a {@link InstanceClient.softReset} call.
  */
@@ -244,6 +293,17 @@ export type SoftResetResult = {
   durationMs: number;
 };
 
+export type ReverseTunnelOptions = {
+  /** Port to listen on near the simulator. Must be in 57090-57099. */
+  remotePort: number;
+  /** Local port for a client-first service on the user's machine. Defaults to remotePort. */
+  localPort?: number;
+  /** Local host on the user's machine. Defaults to 127.0.0.1. */
+  localHost?: string;
+  /** Controls tunnel logging verbosity. Defaults to the instance client's log level. */
+  logLevel?: LogLevel;
+};
+
 /**
  * Result from a command execution (xcrun, xcodebuild, etc.)
  */
@@ -259,6 +319,8 @@ export type CommandResult = {
 export type AppInstallationOptions = {
   /** MD5 hash for caching - if provided and matches cached version, skips download */
   md5?: string;
+  /** Client-side timeout for app installation. Defaults to 120 seconds. */
+  timeoutMs?: number;
   /**
    * Launch mode after installation:
    * - 'ForegroundIfRunning': Bring to foreground if already running, otherwise launch
@@ -429,8 +491,12 @@ export type InstanceClient = {
    * @param mode Optional launch mode:
    *   - 'ForegroundIfRunning' (default): bring to foreground if already running
    *   - 'RelaunchIfRunning': terminate and relaunch if already running
+   *   Or a launch options object with optional mode and launch runtime.
    */
-  launchApp: (bundleId: string, mode?: 'ForegroundIfRunning' | 'RelaunchIfRunning') => Promise<void>;
+  launchApp: {
+    (bundleId: string, mode?: LaunchAppMode): Promise<void>;
+    (bundleId: string, options: LaunchAppOptions): Promise<void>;
+  };
 
   /**
    * Terminate a running app by bundle identifier.
@@ -623,6 +689,12 @@ export type InstanceClient = {
    */
   softReset: (bundleId: string, options?: SoftResetOptions) => Promise<SoftResetResult>;
 
+  /**
+   * Start a reverse tunnel from the simulator-facing LISTEN_IP:remotePort
+   * to a user-local client-first TCP service, such as HTTP or WebSocket.
+   */
+  startReverseTunnel: (options: ReverseTunnelOptions) => Promise<ReverseTunnel>;
+
   /**
    * Disconnect from the Limrun instance
    */
@@ -1289,6 +1361,21 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return `ts-client-${Date.now()}-${Math.random().toString(36).substring(7)}`;
     };
 
+    const redactRequestForDebug = (request: Record<string, unknown>): Record<string, unknown> => {
+      if (request['type'] !== 'launchApp') {
+        return request;
+      }
+
+      const runtime = request['runtime'] as LaunchAppRuntime | undefined;
+      return {
+        type: request['type'],
+        id: request['id'],
+        bundleId: request['bundleId'],
+        mode: request['mode'],
+        runtime: runtime ? { kind: runtime.kind, version: runtime.version } : undefined,
+      };
+    };
+
     // Generic request sender with timeout and response handling
     const sendRequest = <T>(
       type: string,
@@ -1314,7 +1401,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
         );
 
         const request = { type, id, ...params };
-        logger.debug('Sending request:', request);
+        logger.debug('Sending request:', redactRequestForDebug(request));
 
         ws.send(JSON.stringify(request), (err?: Error) => {
           if (err) {
@@ -1550,6 +1637,7 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             clearStoreKitConfig,
             discoverStoreKitConfig,
             softReset,
+            startReverseTunnel,
             disconnect,
             getConnectionState,
             onConnectionStateChange,
@@ -1634,11 +1722,24 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return sendRequest<void>('toggleKeyboard');
     };
 
-    const launchApp = (
-      bundleId: string,
-      mode?: 'ForegroundIfRunning' | 'RelaunchIfRunning',
-    ): Promise<void> => {
-      return sendRequest<void>('launchApp', { bundleId, mode });
+    const launchApp = (bundleId: string, modeOrOptions?: LaunchAppMode | LaunchAppOptions): Promise<void> => {
+      const launchOptions: LaunchAppOptions =
+        typeof modeOrOptions === 'string' ? { mode: modeOrOptions } : modeOrOptions ?? {};
+      const requestedMode =
+        typeof modeOrOptions === 'object' ?
+          (modeOrOptions as { mode?: LaunchAppMode }).mode
+        : launchOptions.mode;
+      if (launchOptions.runtime && requestedMode === 'ForegroundIfRunning') {
+        return Promise.reject(
+          new Error('launchApp runtime launches require RelaunchIfRunning so runtime injection is applied.'),
+        );
+      }
+      const mode = launchOptions.runtime ? 'RelaunchIfRunning' : launchOptions.mode;
+      return sendRequest<void>('launchApp', {
+        bundleId,
+        mode,
+        runtime: launchOptions.runtime,
+      });
     };
 
     const terminateApp = (bundleId: string): Promise<void> => {
@@ -1670,11 +1771,16 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
     };
 
     const installApp = (url: string, options?: AppInstallationOptions): Promise<AppInstallationResult> => {
-      return sendRequest<AppInstallationResult>('appInstallation', {
-        url,
-        md5: options?.md5,
-        launchMode: options?.launchMode,
-      });
+      return sendRequest<AppInstallationResult>(
+        'appInstallation',
+        {
+          url,
+          md5: options?.md5,
+          launchMode: options?.launchMode,
+        },
+        undefined,
+        options?.timeoutMs ?? 120_000,
+      );
     };
 
     const setOrientation = (orientation: 'Portrait' | 'Landscape'): Promise<void> => {
@@ -2011,6 +2117,24 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return out;
     };
 
+    const startReverseTunnel = async (tunnelOptions: ReverseTunnelOptions): Promise<ReverseTunnel> => {
+      assertPort(
+        tunnelOptions.remotePort,
+        'remotePort',
+        REVERSE_TUNNEL_REMOTE_PORT_MIN,
+        REVERSE_TUNNEL_REMOTE_PORT_MAX,
+      );
+      const localPort = tunnelOptions.localPort ?? tunnelOptions.remotePort;
+      assertPort(localPort, 'localPort', 1, 65535);
+
+      const remoteURL = deriveReverseTunnelUrl(options.apiUrl, tunnelOptions.remotePort);
+      return startReverseTcpTunnel(remoteURL, options.token, {
+        localHost: tunnelOptions.localHost ?? '127.0.0.1',
+        localPort,
+        logLevel: tunnelOptions.logLevel ?? logLevel,
+      });
+    };
+
     const disconnect = (): void => {
       intentionalDisconnect = true;
       cleanup();

package/src/resources/xcode-instances-helpers.ts

@@ -51,11 +51,18 @@ export type XcodeProjectConfig = {
   workspace?: string;
   project?: string;
   scheme?: string;
-  sdk?: 'iphonesimulator' | 'iphoneos';
+  sdk?: 'iphonesimulator' | 'iphoneos' | 'watchsimulator' | 'watchos';
+};
+
+export type XcodeSigningConfig = {
+  certificateP12Base64?: string;
+  certificatePassword?: string;
+  provisioningProfileBase64?: string;
 };
 
 export type XcodeBuildOptions = {
-  upload?: { assetName: string } | { signedUploadUrl: string; signedDownloadUrl: string };
+  upload?: { assetName: string } | { signedUploadUrl: string };
+  signing?: XcodeSigningConfig;
 };
 
 export type XcodeClient = {
@@ -228,6 +235,7 @@ export class XcodeInstances extends GeneratedXcodeInstances {
         const request: ExecRequest = {
           command: 'xcodebuild',
           ...(settings && { xcodebuild: settings }),
+          ...(options?.signing && { signing: options.signing }),
         };
 
         if (options?.upload && 'assetName' in options.upload) {
@@ -249,9 +257,8 @@ export class XcodeInstances extends GeneratedXcodeInstances {
           return exec(requestPromise, { apiUrl, token, log });
         }
 
-        if (options?.upload && 'signedUploadUrl' in options.upload && 'signedDownloadUrl' in options.upload) {
+        if (options?.upload && 'signedUploadUrl' in options.upload) {
           request.signedUploadUrl = options.upload.signedUploadUrl;
-          request.additionalMetadata = { signedDownloadUrl: options.upload.signedDownloadUrl };
         }
 
         return exec(request, { apiUrl, token, log });