Types

Promise Types

APIPromise

A subclass of Promise providing additional helper methods for interacting with the SDK.

asResponse

() => Promise<Response>

Gets the raw Response instance instead of parsing the response data.

withResponse

() => Promise<{ data: T; response: Response }>

Gets both the parsed response data and the raw Response instance.

Example:

import { Limrun } from 'limrun';

const client = new Limrun();

// Get parsed data
const instance = await client.androidInstances.retrieve('inst_123');

// Get raw response
const response = await client.androidInstances.retrieve('inst_123').asResponse();

// Get both
const { data, response } = await client.androidInstances.retrieve('inst_123').withResponse();

PagePromise

A specialized promise for paginated API responses. Extends APIPromise and implements AsyncIterable to support auto-pagination. Type Signature:

class PagePromise<PageClass, Item> extends APIPromise<PageClass>
  implements AsyncIterable<Item>

Example:

// Auto-paginate through all items
for await (const instance of client.androidInstances.list()) {
  console.log(instance.metadata.id);
}

// Or await the first page
const page = await client.androidInstances.list();
for (const instance of page.items) {
  console.log(instance.metadata.id);
}

Upload Types

Uploadable

Represents data that can be uploaded to the API. Typically a native File class instance. Type Definition:

type Uploadable = File | Response | FsReadStream | BunFile;

File

Native browser or Node.js File object

Response

Fetch API Response object

FsReadStream

AsyncIterable<Uint8Array>

Node.js fs.createReadStream() result

BunFile

Blob

Bun-specific File type

ToFileInput

Input types accepted by the toFile() utility function. Type Definition:

type ToFileInput =
  | FileLike
  | ResponseLike
  | Exclude<BlobLikePart, string>
  | AsyncIterable<BlobLikePart>;

Example:

import { toFile } from 'limrun';

// From a buffer
const file = await toFile(buffer, 'app.apk', { type: 'application/vnd.android.package-archive' });

// From a fetch response
const response = await fetch('https://example.com/app.apk');
const file = await toFile(response);

// From a stream
import fs from 'fs';
const stream = fs.createReadStream('./app.apk');
const file = await toFile(stream, 'app.apk');

Pagination Types

ItemsParams

Parameters for paginated list requests.

startingAfter

string

ID of the item to start after (for forward pagination)

endingBefore

string

ID of the item to end before (for backward pagination)

limit

number

Maximum number of items to return per page

Example:

// Get first 10 items
const page1 = await client.androidInstances.list({ limit: 10 });

// Get next 10 items
const lastId = page1.items[page1.items.length - 1].metadata.id;
const page2 = await client.androidInstances.list({ limit: 10, startingAfter: lastId });

AbstractPage

Base class for paginated responses. Implements AsyncIterable for easy iteration.

hasNextPage

() => boolean

Check if there are more pages available

getNextPage

() => Promise<this>

Fetch the next page of results

iterPages

() => AsyncGenerator<this>

Iterate through all pages

Example:

const page = await client.androidInstances.list();

// Check for next page
if (page.hasNextPage()) {
  const nextPage = await page.getNextPage();
}

// Iterate all pages
for await (const page of page.iterPages()) {
  console.log(`Page has ${page.items.length} items`);
}

Instance Types

ConnectionState

Represents the connection state of an instance client. Type Definition:

type ConnectionState = 'connecting' | 'connected' | 'disconnected' | 'reconnecting';

connecting

string

Initial connection is being established

connected

string

Successfully connected to the instance

disconnected

string

Connection has been closed

reconnecting

string

Attempting to reconnect after a disconnection

LogLevel

Controls the verbosity of logging in clients. Type Definition:

type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug';

none

string

No logging output

error

string

Only log errors

warn

string

Log warnings and errors

info

string

Log informational messages, warnings, and errors (default)

debug

string

Log all messages including debug information

InstanceClientOptions

Configuration options for creating an instance client.

adbUrl

string

required

The URL of the ADB WebSocket endpoint

endpointUrl

string

required

The URL of the main endpoint WebSocket

token

string

required

Authentication token for WebSocket connections

adbPath

string

default:"'adb'"

Path to the ADB executable

logLevel

LogLevel

default:"'info'"

Controls logging verbosity

maxReconnectAttempts

number

default:"6"

Maximum number of reconnection attempts

reconnectDelay

number

default:"1000"

Initial reconnection delay in milliseconds

maxReconnectDelay

number

default:"30000"

Maximum reconnection delay in milliseconds

iOS-Specific Types

AccessibilitySelector

Selector criteria for finding accessibility elements on iOS.

accessibilityId

string

Match by AXUniqueId (accessibilityIdentifier) - exact match

label

string

Match by AXLabel - exact match

labelContains

string

Match by AXLabel - contains (case-insensitive)

elementType

string

Match by element type/role (e.g., “Button”, “TextField”) - case-insensitive

title

string

Match by title - exact match

titleContains

string

Match by title - contains (case-insensitive)

value

string

Match by AXValue - exact match

Example:

import * as Ios from 'limrun/ios';

const client = await Ios.createInstanceClient({
  adbUrl: instance.adbWsUrl,
  endpointUrl: instance.endpointWsUrl,
  token: instance.token,
});

// Tap a button by accessibility ID
await client.tapElement({ accessibilityId: 'login-button' });

// Tap a button by label
await client.tapElement({ label: 'Submit', elementType: 'Button' });

ScreenshotData

Result from taking a screenshot.

base64

string

Base64-encoded JPEG image data

width

number

Width in points (for tap coordinates)

height

number

Height in points (for tap coordinates)

Example:

const screenshot = await client.screenshot();

// Save to file
import fs from 'fs';
const buffer = Buffer.from(screenshot.base64, 'base64');
fs.writeFileSync('screenshot.jpg', buffer);

console.log(`Screenshot size: ${screenshot.width}x${screenshot.height}`);

InstalledApp

Information about an installed iOS app.

bundleId

string

The app’s bundle identifier

name

string

The app’s display name

installType

string

How the app was installed (e.g., “User”, “System”)

Sandbox Types

XcodeBuildConfig

Build configuration for xcodebuild command.

workspace

string

Path to the .xcworkspace file

project

string

Path to the .xcodeproj file

scheme

string

Build scheme to use

Example:

import { createXCodeSandboxClient } from 'limrun';

const sandbox = await createXCodeSandboxClient({
  apiUrl: 'https://sandbox.example.com',
  token: 'your-token',
});

const build = sandbox.xcodebuild({
  workspace: 'MyApp.xcworkspace',
  scheme: 'MyApp',
});

build.stdout.on('data', (line) => console.log(line));
const { exitCode } = await build;

SyncOptions

Options for syncing source code to the sandbox.

cacheKey

string

default:"'xcode-sandbox'"

Cache scoping key for delta basis caching

basisCacheDir

string

Directory for storing delta sync cache

maxPatchBytes

number

Maximum patch size before falling back to full upload

watch

boolean

default:"false"

If true, watch the folder and re-sync on changes

filter

(relativePath: string) => boolean

Filter function to include/exclude files and directories

Example:

const result = await sandbox.sync('./MyApp', {
  watch: true,
  filter: (path) => !path.startsWith('build/'),
});

// Stop watching when done
if (result.stopWatching) {
  result.stopWatching();
}

SimulatorConfig

Simulator connection details for configuring the sandbox.

apiUrl

string

required

The API URL of the simulator (limulator)

token

string

Auth token for the simulator. If not provided, uses the sandbox token

Tunnel Types

Tunnel

Represents an active TCP tunnel.

address

{ address: string; port: number }

Local address and port of the tunnel

() => void

Close the tunnel

getConnectionState

() => TunnelConnectionState

Get current WebSocket connection state

onConnectionStateChange

(callback) => () => void

Example:

const tunnel = await client.startAdbTunnel();

console.log(`ADB tunnel: ${tunnel.address.address}:${tunnel.address.port}`);

// Monitor connection state
const unsubscribe = tunnel.onConnectionStateChange((state) => {
  console.log(`Tunnel state: ${state}`);
});

// Close when done
tunnel.close();
unsubscribe();

TunnelConnectionState

Connection state of a tunnel. Type Definition:

type TunnelConnectionState = 'connecting' | 'connected' | 'disconnected' | 'reconnecting';

TunnelMode

Tunnel mode for TCP connections. Type Definition:

type TunnelMode = 'singleton' | 'multiplexed';

singleton

string

Single TCP connection forwarded to WebSocket (default)

multiplexed

string

Multiple TCP connections multiplexed over a single WebSocket

Execution Types

ExecRequest

Request parameters for executing commands.

command

'xcodebuild'

required

The command to execute

xcodebuild

XcodeBuildConfig

Configuration for xcodebuild command

ExecResult

Result of a command execution.

exitCode

number

Process exit code

execId

string

Unique execution identifier

status

'SUCCEEDED' | 'FAILED' | 'CANCELLED'

Execution status

Example:

import { exec } from 'limrun';

const process = exec(
  { command: 'xcodebuild', xcodebuild: { scheme: 'MyApp' } },
  { apiUrl: 'https://sandbox.example.com', token: 'your-token' }
);

process.stdout.on('data', (line) => console.log(line));

const result = await process;
console.log(`Exit code: ${result.exitCode}`);
console.log(`Status: ${result.status}`);

Client Options

ClientOptions

Configuration options for the main Limrun client.

apiKey

string

API key for authentication. Defaults to process.env['LIM_API_KEY']

baseURL

string

Override the default base URL. Defaults to process.env['LIMRUN_BASE_URL']

timeout

number

Maximum time in milliseconds to wait for a response

maxRetries

number

default:"2"

Maximum number of retry attempts for failed requests

fetch

Fetch

Custom fetch function implementation

fetchOptions

RequestInit

Additional options passed to fetch calls

logger

Logger

Custom logger instance

logLevel

LogLevel

Controls SDK logging verbosity

Example:

import { Limrun } from 'limrun';

const client = new Limrun({
  apiKey: 'your-api-key',
  timeout: 60000, // 60 seconds
  maxRetries: 3,
  logLevel: 'debug',
});

Client

Resources

Instance Clients

Utilities

Types & Errors

Promise Types

APIPromise

PagePromise

Upload Types

Uploadable

ToFileInput

ItemsParams

AbstractPage

Instance Types

ConnectionState

LogLevel

InstanceClientOptions

iOS-Specific Types

AccessibilitySelector

ScreenshotData

InstalledApp

Sandbox Types

XcodeBuildConfig

SyncOptions

SimulatorConfig

Tunnel Types

Tunnel

TunnelConnectionState

TunnelMode

Execution Types

ExecRequest

ExecResult

Client Options

ClientOptions

Build docs developers (and LLMs) love

Client

Resources

Instance Clients

Utilities

Types & Errors

​Promise Types

​APIPromise

​PagePromise

​Upload Types

​Uploadable

​ToFileInput

​Pagination Types

​ItemsParams

​AbstractPage

​Instance Types

​ConnectionState

​LogLevel

​InstanceClientOptions

​iOS-Specific Types

​AccessibilitySelector

​ScreenshotData

​InstalledApp

​Sandbox Types

​XcodeBuildConfig

​SyncOptions

​SimulatorConfig

​Tunnel Types

​Tunnel

​TunnelConnectionState

​TunnelMode

​Execution Types

​ExecRequest

​ExecResult

​Client Options

​ClientOptions

Build docs developers (and LLMs) love

Promise Types

APIPromise

PagePromise

Upload Types

Uploadable

ToFileInput

Pagination Types

ItemsParams

AbstractPage

Instance Types

ConnectionState

LogLevel

InstanceClientOptions

iOS-Specific Types

AccessibilitySelector

ScreenshotData

InstalledApp

Sandbox Types

XcodeBuildConfig

SyncOptions

SimulatorConfig

Tunnel Types

Tunnel

TunnelConnectionState

TunnelMode

Execution Types

ExecRequest

ExecResult

Client Options

ClientOptions