TypeScript Types

Key TypeScript interfaces and types for Agent Browser

TypeScript Types

Key TypeScript interfaces and types used throughout the Agent Browser SDK.

Command Types

LaunchCommand

Configuration for browser launch.

interface LaunchCommand extends BaseCommand {
  action: 'launch';
  headless?: boolean;
  viewport?: { width: number; height: number } | null;
  browser?: 'chromium' | 'firefox' | 'webkit';
  headers?: Record<string, string>;
  executablePath?: string;
  cdpPort?: number;
  cdpUrl?: string;
  autoConnect?: boolean;
  extensions?: string[];
  profile?: string;
  storageState?: string;
  proxy?: {
    server: string;
    bypass?: string;
    username?: string;
    password?: string;
  };
  args?: string[];
  userAgent?: string;
  provider?: string;
  ignoreHTTPSErrors?: boolean;
  allowFileAccess?: boolean;
  colorScheme?: 'light' | 'dark' | 'no-preference';
  downloadPath?: string;
  allowedDomains?: string[];
  autoStateFilePath?: string;
}

NavigateCommand

Navigation command.

interface NavigateCommand extends BaseCommand {
  action: 'navigate';
  url: string;
  waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
  headers?: Record<string, string>;
}

ClickCommand

Click interaction.

interface ClickCommand extends BaseCommand {
  action: 'click';
  selector: string;
  button?: 'left' | 'right' | 'middle';
  clickCount?: number;
  delay?: number;
  newTab?: boolean;
}

TypeCommand

Type text into an element.

interface TypeCommand extends BaseCommand {
  action: 'type';
  selector: string;
  text: string;
  delay?: number;
  clear?: boolean;
}

FillCommand

Fill an input field.

interface FillCommand extends BaseCommand {
  action: 'fill';
  selector: string;
  value: string;
}

ScreenshotCommand

Capture screenshot.

interface ScreenshotCommand extends BaseCommand {
  action: 'screenshot';
  path?: string;
  fullPage?: boolean;
  selector?: string;
  format?: 'png' | 'jpeg';
  quality?: number;
  annotate?: boolean;
}

SnapshotCommand

Get accessibility snapshot.

interface SnapshotCommand extends BaseCommand {
  action: 'snapshot';
}

EvaluateCommand

Execute JavaScript.

interface EvaluateCommand extends BaseCommand {
  action: 'evaluate';
  script: string;
  args?: unknown[];
}

WaitCommand

Wait for element or timeout.

interface WaitCommand extends BaseCommand {
  action: 'wait';
  selector?: string;
  timeout?: number;
  state?: 'attached' | 'detached' | 'visible' | 'hidden';
}

ScrollCommand

Scroll the page.

interface ScrollCommand extends BaseCommand {
  action: 'scroll';
  selector?: string;
  x?: number;
  y?: number;
  direction?: 'up' | 'down' | 'left' | 'right';
  amount?: number;
}

Snapshot Types

EnhancedSnapshot

Accessibility snapshot with refs.

interface EnhancedSnapshot {
  tree: string;
  refs: RefMap;
}

RefMap

Map of element refs to locator data.

interface RefMap {
  [ref: string]: {
    selector: string;
    role: string;
    name: string;
    nth?: number;
  };
}

SnapshotOptions

Configuration for snapshot generation.

interface SnapshotOptions {
  interactive?: boolean;
  cursor?: boolean;
  maxDepth?: number;
  compact?: boolean;
  selector?: string;
}

Response Types

SuccessResponse

Successful command response.

interface SuccessResponse<T = unknown> {
  id: string;
  success: true;
  data: T;
}

ErrorResponse

Error command response.

interface ErrorResponse {
  id: string;
  success: false;
  error: string;
}

Response

Union of success and error responses.

type Response<T = unknown> = SuccessResponse<T> | ErrorResponse;

NavigateData

Navigation result data.

interface NavigateData {
  url: string;
  title: string;
}

ScreenshotData

Screenshot result data.

interface ScreenshotData {
  path?: string;
  base64?: string;
  annotations?: Annotation[];
}

Annotation

Element annotation for screenshots.

interface Annotation {
  ref: string;
  number: number;
  role: string;
  name?: string;
  box: { x: number; y: number; width: number; height: number };
}

SnapshotData

Snapshot result data.

interface SnapshotData {
  snapshot: string;
  refs?: Record<string, { role: string; name?: string }>;
  origin?: string;
}

TabListData

Tab list information.

interface TabListData {
  tabs: TabInfo[];
  active: number;
}

interface TabInfo {
  index: number;
  url: string;
  title: string;
  active: boolean;
}

Screencast Types

ScreencastFrame

Screencast frame data from CDP.

interface ScreencastFrame {
  data: string; // base64 encoded image
  metadata: {
    offsetTop: number;
    pageScaleFactor: number;
    deviceWidth: number;
    deviceHeight: number;
    scrollOffsetX: number;
    scrollOffsetY: number;
    timestamp?: number;
  };
  sessionId: number;
}

ScreencastOptions

Screencast configuration.

interface ScreencastOptions {
  format?: 'jpeg' | 'png';
  quality?: number; // 0-100, only for jpeg
  maxWidth?: number;
  maxHeight?: number;
  everyNthFrame?: number;
}

Tracing Types

TraceEvent

Chrome trace event (CDP profiler format).

interface TraceEvent {
  cat?: string;
  name?: string;
  ph?: string;
  pid?: number;
  tid?: number;
  ts?: number;
  dur?: number;
  args?: Record<string, unknown>;
  [key: string]: unknown;
}

iOS Types

IOSDeviceInfo

iOS device information.

interface IOSDeviceInfo {
  name: string;
  udid: string;
  state: string;
  runtime: string;
  isAvailable: boolean;
  isRealDevice?: boolean;
}

IOSEnhancedSnapshot

iOS snapshot with refs.

interface IOSEnhancedSnapshot {
  tree: string;
  refs: IOSRefMap;
}

IOSRefMap

iOS ref map.

interface IOSRefMap {
  [ref: string]: {
    selector: string;
    role?: string;
    name?: string;
    xpath?: string;
  };
}

Diff Types

DiffSnapshotData

Snapshot diff result.

interface DiffSnapshotData {
  diff: string;
  additions: number;
  removals: number;
  unchanged: number;
  changed: boolean;
}

DiffScreenshotData

Screenshot diff result.

interface DiffScreenshotData {
  diffPath: string;
  totalPixels: number;
  differentPixels: number;
  mismatchPercentage: number;
  match: boolean;
  dimensionMismatch?: boolean;
}

DiffUrlData

URL comparison result.

interface DiffUrlData {
  snapshot: DiffSnapshotData;
  screenshot?: DiffScreenshotData;
}

Cookie & Storage Types

CookiesSetCommand

Set cookies command.

interface CookiesSetCommand extends BaseCommand {
  action: 'cookies_set';
  cookies: Array<{
    name: string;
    value: string;
    url?: string;
    domain?: string;
    path?: string;
    expires?: number;
    httpOnly?: boolean;
    secure?: boolean;
    sameSite?: 'Strict' | 'Lax' | 'None';
  }>;
}

StorageGetCommand

Get storage value.

interface StorageGetCommand extends BaseCommand {
  action: 'storage_get';
  key?: string;
  type: 'local' | 'session';
}

StorageSetCommand

Set storage value.

interface StorageSetCommand extends BaseCommand {
  action: 'storage_set';
  key: string;
  value: string;
  type: 'local' | 'session';
}

Route & Request Types

RouteCommand

Intercept and mock requests.

interface RouteCommand extends BaseCommand {
  action: 'route';
  url: string;
  response?: {
    status?: number;
    body?: string;
    contentType?: string;
    headers?: Record<string, string>;
  };
  abort?: boolean;
}

RequestsCommand

Get tracked requests.

interface RequestsCommand extends BaseCommand {
  action: 'requests';
  filter?: string;
  clear?: boolean;
}

State Management Types

StateListCommand

List saved session states.

interface StateListCommand extends BaseCommand {
  action: 'state_list';
}

StateClearCommand

Clear session states.

interface StateClearCommand extends BaseCommand {
  action: 'state_clear';
  sessionName?: string;
  all?: boolean;
}

AuthSaveCommand

Save authentication credentials.

interface AuthSaveCommand extends BaseCommand {
  action: 'auth_save';
  name: string;
  url: string;
  username: string;
  password: string;
  usernameSelector?: string;
  passwordSelector?: string;
  submitSelector?: string;
}

Input Types

InputMouseCommand

Mouse input event.

interface InputMouseCommand extends BaseCommand {
  action: 'input_mouse';
  type: 'mousePressed' | 'mouseReleased' | 'mouseMoved' | 'mouseWheel';
  x: number;
  y: number;
  button?: 'left' | 'right' | 'middle' | 'none';
  clickCount?: number;
  deltaX?: number;
  deltaY?: number;
  modifiers?: number;
}

InputKeyboardCommand

Keyboard input event.

interface InputKeyboardCommand extends BaseCommand {
  action: 'input_keyboard';
  type: 'keyDown' | 'keyUp' | 'char';
  key?: string;
  code?: string;
  text?: string;
  modifiers?: number;
}

InputTouchCommand

Touch input event.

interface InputTouchCommand extends BaseCommand {
  action: 'input_touch';
  type: 'touchStart' | 'touchEnd' | 'touchMove' | 'touchCancel';
  touchPoints: Array<{ x: number; y: number; id?: number }>;
  modifiers?: number;
}

Importing Types

Import types from the package:

import type {
  // Commands
  LaunchCommand,
  NavigateCommand,
  ClickCommand,
  ScreenshotCommand,
  SnapshotCommand,
  
  // Snapshot
  EnhancedSnapshot,
  RefMap,
  SnapshotOptions,
  
  // Responses
  Response,
  SuccessResponse,
  ErrorResponse,
  NavigateData,
  ScreenshotData,
  SnapshotData,
  
  // Screencast
  ScreencastFrame,
  ScreencastOptions,
  
  // iOS
  IOSDeviceInfo,
  IOSEnhancedSnapshot,
  IOSRefMap,
  
  // Tracing
  TraceEvent,
} from '@agentic-labs/browser';