@limrun/api 0.48.4 → 0.49.0

package/src/ios-client.ts

@@ -6,7 +6,7 @@ import { WebSocket, Data } from 'ws';
 import { EventEmitter } from 'events';
 import { assertPort, isNonRetryableError, startReverseTcpTunnel, type ReverseTunnel } from './tunnel';
 import { startDestinationTcpTunnel, type DestinationTcpTunnel } from './destination-tunnel-dialer';
-import type { DestinationTunnelRoute } from './destination-tunnel';
+import { disabledDestinationTunnelInspection, type DestinationTunnelSelectors } from './destination-tunnel';
 import { type SyncFolderResult, type FolderSyncOptions, syncFolder } from './folder-sync';
 import { createIgnoreFn } from './folder-sync-ignore';
 import { prepareAppBundlePath, watchAppArchive } from './app-archive';
@@ -25,6 +25,11 @@ import {
   type StartForwardHttpProxyOptions,
 } from './http-proxy';
 import { startXcrunShim as startClientXcrunShim } from './ios-shim';
+import { persistFields, type PersistOption } from './internal/persist-option';
+import { streamSessionEntries } from './internal/session-stream';
+import type { SessionLogLine, SessionEvent } from './resources/session-artifacts';
+
+export { type PersistOption } from './internal/persist-option';
 
 /**
  * Connection state of the instance client
@@ -65,8 +70,8 @@ export function deriveReverseTunnelUrl(apiUrl: string, remotePort: number): stri
 export type { ReverseTunnel } from './tunnel';
 export type Tunnel = DestinationTcpTunnel;
 export type TunnelOptions = {
-  /** Exact localhost or literal-IP TCP destinations that the server may ask this client to dial. */
-  routes: DestinationTunnelRoute[];
+  /** Exact endpoint selector values that the server may ask this client to dial. */
+  selectors: DestinationTunnelSelectors;
   /** Controls tunnel logging verbosity. Defaults to the instance client's log level. */
   logLevel?: LogLevel;
 };
@@ -236,6 +241,8 @@ export type InstalledApp = {
   bundleId: string;
   name: string;
   installType: string;
+  /** App icon as a base64-encoded 64px PNG; absent when the runtime could not extract one. */
+  icon?: string;
 };
 
 export type LsofEntry = {
@@ -677,7 +684,8 @@ export type InstanceClient = {
 
   /**
    * List installed apps on the simulator
-   * @returns Array of installed apps with bundleId, name, and installType
+   * @returns Array of installed apps with bundleId, name, installType, and,
+   *   when available, a small base64 PNG icon
    */
   listApps: () => Promise<InstalledApp[]>;
 
@@ -758,8 +766,11 @@ export type InstanceClient = {
    * Start recording simulator video. Use stopRecording() to stop the recording.
    * When provided, `quality` must be one of `5`, `6`, `7`, `8`, `9`, or `10`.
    * The server default is `5`.
+   * With `persist`, the completed recording is uploaded to Limrun's bucket
+   * when the recording stops or the instance terminates; list it with
+   * `iosInstances.listRecordings`.
    */
-  startRecording: (options?: { quality?: RecordingQuality }) => Promise<void>;
+  startRecording: (options?: { quality?: RecordingQuality; persist?: PersistOption }) => Promise<void>;
 
   /**
    * Stop the active server-side recording.
@@ -771,6 +782,54 @@ export type InstanceClient = {
    */
   stopRecording: (saveTo: { presignedUrl?: string; localPath?: string }) => Promise<string>;
 
+  /**
+   * Start capturing an app's logs (one JSONL object per line) for the given
+   * bundle id. One app log capture runs at a time; the server rejects a
+   * second start. With `persist`, the capture is uploaded to Limrun's bucket
+   * when it stops or the instance terminates; list it with
+   * `iosInstances.listAppLogs`.
+   */
+  startAppLogCapture: (options: { bundleId: string; persist?: PersistOption }) => Promise<void>;
+
+  /** Stop the active app log capture. */
+  stopAppLogCapture: () => Promise<void>;
+
+  /**
+   * Start capturing the coalesced event log of user and agent actions (one
+   * JSONL object per line). One event capture runs at a time; the server
+   * rejects a second start. With `persist`, the capture is uploaded to
+   * Limrun's bucket when it stops or the instance terminates; list it with
+   * `iosInstances.listEvents`.
+   */
+  startEventCapture: (options?: { persist?: PersistOption }) => Promise<void>;
+
+  /** Stop the active event capture. */
+  stopEventCapture: () => Promise<void>;
+
+  /**
+   * Tail the live app log stream fed by {@link startAppLogCapture}. On
+   * connect the instance replays its recent buffer (up to 1000 lines), then
+   * delivers lines as they are captured; a dropped connection reconnects
+   * and resumes exactly where it left off, so every line is delivered once.
+   * The stream is independent of this client's websocket and survives
+   * {@link disconnect}; `onError` fires at most once, after the stream has
+   * kept failing for several minutes (e.g. the instance was deleted), and
+   * the stream is closed. Returns a function that closes the stream.
+   */
+  streamAppLogCapture: (handlers: {
+    onLine: (line: SessionLogLine) => void;
+    onError?: (error: Error) => void;
+  }) => () => void;
+
+  /**
+   * Tail the live coalesced event log fed by {@link startEventCapture}.
+   * Same delivery and lifecycle semantics as {@link streamAppLogCapture}.
+   */
+  streamEventCapture: (handlers: {
+    onEvent: (event: SessionEvent) => void;
+    onError?: (error: Error) => void;
+  }) => () => void;
+
   /**
    * Play an audio file as the simulator's microphone input. Stage the file on
    * the instance first with `pushFile` (no bundle ID); `path` is the same
@@ -1861,6 +1920,10 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       }),
       startVideoRecordingResult: () => undefined,
       stopVideoRecordingResult: () => undefined,
+      startAppLogCaptureResult: () => undefined,
+      stopAppLogCaptureResult: () => undefined,
+      startEventCaptureResult: () => undefined,
+      stopEventCaptureResult: () => undefined,
       cameraControlResult: () => undefined,
       playOnMicrophoneResult: (msg): IosPlayOnMicrophoneResult => ({
         duration: msg.duration ?? 0,
@@ -2055,6 +2118,12 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
             performActions,
             startRecording,
             stopRecording,
+            startAppLogCapture,
+            stopAppLogCapture,
+            startEventCapture,
+            stopEventCapture,
+            streamAppLogCapture,
+            streamEventCapture,
             playOnMicrophone,
             stopMicrophonePlayback,
             microphoneStatus,
@@ -2390,8 +2459,13 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       return sendRequest<PerformActionsResult>('performActions', { actions }, undefined, timeoutMs);
     };
 
-    const startRecording = async (opts?: { quality?: RecordingQuality }): Promise<void> => {
-      const request: { quality?: RecordingQuality } = {};
+    const startRecording = async (opts?: {
+      quality?: RecordingQuality;
+      persist?: PersistOption;
+    }): Promise<void> => {
+      const request: { quality?: RecordingQuality; persist?: boolean; ttlSeconds?: number } = {
+        ...persistFields(opts?.persist),
+      };
       if (opts?.quality !== undefined) {
         if (!Number.isInteger(opts.quality) || opts.quality < 5 || opts.quality > 10) {
           throw new Error('quality must be one of: 5, 6, 7, 8, 9, 10');
@@ -2401,6 +2475,50 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
       await sendRequest<void>('startVideoRecording', request);
     };
 
+    const startAppLogCapture = async (opts: { bundleId: string; persist?: PersistOption }): Promise<void> => {
+      if (!opts.bundleId) {
+        throw new Error('bundleId must be a non-empty string');
+      }
+      await sendRequest<void>('startAppLogCapture', {
+        bundleId: opts.bundleId,
+        ...persistFields(opts.persist),
+      });
+    };
+
+    const stopAppLogCapture = async (): Promise<void> => {
+      await sendRequest<void>('stopAppLogCapture');
+    };
+
+    const startEventCapture = async (opts?: { persist?: PersistOption }): Promise<void> => {
+      await sendRequest<void>('startEventCapture', { ...persistFields(opts?.persist) });
+    };
+
+    const stopEventCapture = async (): Promise<void> => {
+      await sendRequest<void>('stopEventCapture');
+    };
+
+    const streamAppLogCapture = (handlers: {
+      onLine: (line: SessionLogLine) => void;
+      onError?: (error: Error) => void;
+    }): (() => void) =>
+      streamSessionEntries<SessionLogLine>({
+        url: `${options.apiUrl}/session/applogs/events`,
+        token: options.token,
+        onEntry: handlers.onLine,
+        onError: handlers.onError,
+      });
+
+    const streamEventCapture = (handlers: {
+      onEvent: (event: SessionEvent) => void;
+      onError?: (error: Error) => void;
+    }): (() => void) =>
+      streamSessionEntries<SessionEvent>({
+        url: `${options.apiUrl}/session/events/events`,
+        token: options.token,
+        onEntry: handlers.onEvent,
+        onError: handlers.onError,
+      });
+
     const stopRecording = async (saveTo: { presignedUrl?: string; localPath?: string }): Promise<string> => {
       await sendRequest<void>('stopVideoRecording', {
         upload: saveTo.presignedUrl ? { presignedUrl: saveTo.presignedUrl } : undefined,
@@ -2858,7 +2976,8 @@ export async function createInstanceClient(options: InstanceClientOptions): Prom
 
     const startTunnel = async (tunnelOptions: TunnelOptions): Promise<Tunnel> => {
       return startDestinationTcpTunnel(deriveDestinationTunnelURL(options.apiUrl), options.token, {
-        routes: tunnelOptions.routes,
+        selectors: tunnelOptions.selectors,
+        inspection: disabledDestinationTunnelInspection(),
         logLevel: tunnelOptions.logLevel ?? logLevel,
       });
     };

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

@@ -0,0 +1,45 @@
+import { AndroidInstances as GeneratedAndroidInstances } from './android-instances';
+import { type SessionArtifact, type SessionArtifactKind } from './session-artifacts';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export type { SessionArtifact, SessionArtifactKind } from './session-artifacts';
+
+export class AndroidInstances extends GeneratedAndroidInstances {
+  /**
+   * List the instance's persisted session artifacts, optionally narrowed to
+   * one kind.
+   */
+  listSessionArtifacts(
+    id: string,
+    kind?: SessionArtifactKind,
+    options?: RequestOptions,
+  ): APIPromise<SessionArtifact[]> {
+    return this._client.get(path`/v1/android_instances/${id}/session_artifacts`, {
+      query: kind ? { kind } : undefined,
+      ...options,
+    });
+  }
+
+  /**
+   * List the instance's persisted session recordings.
+   */
+  listRecordings(id: string, options?: RequestOptions): APIPromise<SessionArtifact[]> {
+    return this.listSessionArtifacts(id, 'recording', options);
+  }
+
+  /**
+   * List the instance's persisted app log captures.
+   */
+  listAppLogs(id: string, options?: RequestOptions): APIPromise<SessionArtifact[]> {
+    return this.listSessionArtifacts(id, 'appLog', options);
+  }
+
+  /**
+   * List the instance's persisted event log captures.
+   */
+  listEvents(id: string, options?: RequestOptions): APIPromise<SessionArtifact[]> {
+    return this.listSessionArtifacts(id, 'eventLog', options);
+  }
+}

package/src/resources/index.ts

@@ -8,7 +8,6 @@ export {
   type AnalyticsGetInstancesParams,
 } from './analytics';
 export {
-  AndroidInstances,
   type AndroidInstance,
   type AndroidInstanceCreateParams,
   type AndroidInstanceListParams,
@@ -32,7 +31,6 @@ export {
   type GradleInstancesItems,
 } from './gradle-instances';
 export {
-  IosInstances,
   type IosInstance,
   type IosInstanceCreateParams,
   type IosInstanceListParams,
@@ -46,6 +44,15 @@ export {
   type XcodeInstancesItems,
 } from './xcode-instances';
 export { Assets, AssetGetOrUploadParams, AssetGetOrUploadResponse } from './assets-helpers';
+export { IosInstances } from './ios-instances-helpers';
+export { AndroidInstances } from './android-instances-helpers';
+export {
+  type SessionArtifact,
+  type SessionArtifactKind,
+  type SessionLogLine,
+  type SessionEvent,
+  type SessionEventType,
+} from './session-artifacts';
 export {
   XcodeInstances,
   RbeUnsupportedError,

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

@@ -0,0 +1,45 @@
+import { IosInstances as GeneratedIosInstances } from './ios-instances';
+import { type SessionArtifact, type SessionArtifactKind } from './session-artifacts';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export type { SessionArtifact, SessionArtifactKind } from './session-artifacts';
+
+export class IosInstances extends GeneratedIosInstances {
+  /**
+   * List the instance's persisted session artifacts, optionally narrowed to
+   * one kind.
+   */
+  listSessionArtifacts(
+    id: string,
+    kind?: SessionArtifactKind,
+    options?: RequestOptions,
+  ): APIPromise<SessionArtifact[]> {
+    return this._client.get(path`/v1/ios_instances/${id}/session_artifacts`, {
+      query: kind ? { kind } : undefined,
+      ...options,
+    });
+  }
+
+  /**
+   * List the instance's persisted session recordings.
+   */
+  listRecordings(id: string, options?: RequestOptions): APIPromise<SessionArtifact[]> {
+    return this.listSessionArtifacts(id, 'recording', options);
+  }
+
+  /**
+   * List the instance's persisted app log captures.
+   */
+  listAppLogs(id: string, options?: RequestOptions): APIPromise<SessionArtifact[]> {
+    return this.listSessionArtifacts(id, 'appLog', options);
+  }
+
+  /**
+   * List the instance's persisted event log captures.
+   */
+  listEvents(id: string, options?: RequestOptions): APIPromise<SessionArtifact[]> {
+    return this.listSessionArtifacts(id, 'eventLog', options);
+  }
+}

package/src/resources/session-artifacts.ts

@@ -0,0 +1,95 @@
+// Hand-written: the session-artifact list endpoint is not in the generated
+// OpenAPI surface yet. Shared by the iOS and Android instance helpers.
+// SessionLogLine and SessionEvent mirror pkg/artifacts/contract.go in the
+// limrun repo; the runtimes emit the same JSON over live SSE and into the
+// persisted JSONL artifacts.
+
+/** The kind of a persisted session capture. */
+export type SessionArtifactKind = 'recording' | 'appLog' | 'eventLog' | 'networkLog';
+
+/**
+ * One persisted session capture of an instance: a video recording, an app log
+ * capture, a coalesced event log, or a HAR network log. Returned by the
+ * director's GET /v1/{ios,android}_instances/{id}/session_artifacts endpoint,
+ * optionally narrowed with its kind query parameter.
+ */
+export interface SessionArtifact {
+  id: string;
+
+  kind: SessionArtifactKind;
+
+  /** Bundle id (iOS) or package name (Android) for app log captures. */
+  bundleId?: string;
+
+  /** Destination tunnel that produced a networkLog artifact. */
+  tunnelId?: string;
+
+  /** Canonical selectors captured by a networkLog artifact. */
+  selectors?: string[];
+
+  startedAt?: string;
+
+  stoppedAt?: string;
+
+  /** When the artifact is deleted from storage. */
+  expiresAt?: string;
+
+  sizeBytes?: number;
+
+  /**
+   * Short-lived presigned GET URL for the raw artifact: MP4 for recordings,
+   * JSONL for app logs and event logs, HAR for network logs.
+   */
+  downloadUrl: string;
+}
+
+/**
+ * One captured app log line, delivered live by `streamAppLogCapture` and stored
+ * one-per-line in `appLog` artifacts.
+ */
+export interface SessionLogLine {
+  /**
+   * Epoch milliseconds: logcat's own timestamp on Android, receipt time on
+   * iOS. Shares the clock of the recording artifact's `startedAt`, so lines
+   * can be aligned with video playback offsets.
+   */
+  ts: number;
+
+  line: string;
+}
+
+export type SessionEventType = 'tap' | 'drag' | 'scroll' | 'key' | 'text' | 'command';
+
+/**
+ * One coalesced user or agent action, delivered live by `streamEventCapture` and
+ * stored one-per-line in `eventLog` artifacts. The runtime logs semantic
+ * actions, never raw HID frames: a pointer sequence becomes one tap or drag,
+ * scroll and keystroke bursts merge into one event, and typed text is never
+ * included.
+ */
+export interface SessionEvent {
+  /** The action's start in epoch milliseconds, same clock as SessionLogLine. */
+  ts: number;
+
+  type: SessionEventType;
+
+  /** Touch point for tap, start point for drag, anchor for scroll. */
+  x?: number;
+  y?: number;
+
+  /** Drag end point; for scroll they carry the burst's summed deltas instead. */
+  toX?: number;
+  toY?: number;
+
+  /** Duration of the whole gesture or burst. */
+  durationMs?: number;
+
+  /** Number of merged actions in a scroll or text burst. */
+  count?: number;
+
+  /**
+   * Short human-readable label, e.g. "launchApp com.example". Never carries
+   * typed text or request payloads.
+   */
+  summary?: string;
+}

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.48.4'; // x-release-please-version
+export const VERSION = '0.49.0'; // x-release-please-version

package/version.d.mts

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

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.48.4";
+export declare const VERSION = "0.49.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.48.4'; // x-release-please-version
+exports.VERSION = '0.49.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

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