Overview

Browser actions are the building blocks for web interaction. Each action operates on an active browser session and returns a typed result.

navigate

Navigate the browser to a URL.

await tx.browsers.navigate(session.id, {
  url: 'https://example.com',
  waitUntil: 'networkidle', // 'load' | 'domcontentloaded' | 'networkidle'
});

Parameter	Type	Default	Description
`url`	`string`	required	The URL to navigate to
`waitUntil`	`string`	`'load'`	When to consider navigation complete

Interaction

click

Click an element on the page.

await tx.browsers.click(session.id, {
  selector: 'button.submit',
  button: 'left', // 'left' | 'right' | 'middle'
  clickCount: 1,
});

Parameter	Type	Default	Description
`selector`	`string`	required	CSS selector for the target element
`button`	`string`	`'left'`	Mouse button to click
`clickCount`	`number`	`1`	Number of clicks (2 for double-click)

type

Type text into an input or textarea.

await tx.browsers.type(session.id, {
  selector: 'input[name="email"]',
  text: 'user@example.com',
  delay: 50, // milliseconds between keystrokes
});

Parameter	Type	Default	Description
`selector`	`string`	required	CSS selector for the input element
`text`	`string`	required	Text to type
`delay`	`number`	`0`	Delay between keystrokes in ms (simulates human typing)

scroll

Scroll the page or a specific element.

// Scroll the page down
await tx.browsers.scroll(session.id, {
  direction: 'down',
  amount: 500, // pixels
});
 
// Scroll to a specific element
await tx.browsers.scroll(session.id, {
  selector: '#footer',
  behavior: 'smooth',
});

Parameter	Type	Default	Description
`direction`	`string`	—	`'up'`, `'down'`, `'left'`, `'right'`
`amount`	`number`	`300`	Pixels to scroll
`selector`	`string`	—	Scroll until this element is visible
`behavior`	`string`	`'auto'`	`'auto'` or `'smooth'`

Data Extraction

extractText

Extract text content from elements matching a selector.

const result = await tx.browsers.extractText(session.id, {
  selector: '.article-body p',
});
 
console.log(result.text); // Combined text of all matching elements

Parameter	Type	Default	Description
`selector`	`string`	required	CSS selector for target elements

Returns: { text: string }

extractStructured

Extract structured data from repeating elements into typed objects.

const result = await tx.browsers.extractStructured(session.id, {
  selector: '.product-card',
  schema: {
    name: { selector: 'h3', attribute: 'textContent' },
    price: { selector: '.price', attribute: 'textContent' },
    image: { selector: 'img', attribute: 'src' },
    link: { selector: 'a', attribute: 'href' },
  },
});
 
// result.items is an array of objects matching the schema
for (const product of result.items) {
  console.log(product.name, product.price);
}

Parameter	Type	Default	Description
`selector`	`string`	required	CSS selector for the repeating container
`schema`	`object`	required	Field definitions with inner selectors and attributes

Schema field options:

selector — CSS selector relative to the container element
attribute — DOM attribute to extract (textContent, href, src, value, etc.)

Returns: { items: T[] }

Visual Capture

screenshot

Capture a screenshot of the current page.

const result = await tx.browsers.screenshot(session.id, {
  fullPage: true,
  format: 'png',
  quality: 90,
  selector: undefined, // or a CSS selector for element-level capture
});
 
// result.data is base64-encoded image data
const buffer = Buffer.from(result.data, 'base64');

Parameter	Type	Default	Description
`fullPage`	`boolean`	`false`	Capture entire scrollable page
`format`	`string`	`'png'`	`'png'` or `'jpeg'`
`quality`	`number`	`80`	JPEG quality (1-100), ignored for PNG
`selector`	`string`	—	Capture a specific element only

Returns: { data: string, width: number, height: number }

Synchronization

waitFor

Wait for an element to appear, disappear, or reach a specific state.

// Wait for element to appear
await tx.browsers.waitFor(session.id, {
  selector: '.results-loaded',
  state: 'visible',
  timeout: 10000,
});
 
// Wait for element to disappear (e.g., loading spinner)
await tx.browsers.waitFor(session.id, {
  selector: '.loading-spinner',
  state: 'hidden',
  timeout: 15000,
});

Parameter	Type	Default	Description
`selector`	`string`	required	CSS selector to watch
`state`	`string`	`'visible'`	`'visible'`, `'hidden'`, `'attached'`, `'detached'`
`timeout`	`number`	`30000`	Maximum wait time in ms

Error Handling

All actions throw typed errors when they fail:

import { BrowserError, BrowserTimeoutError } from '@usetransactional/node';
 
try {
  await tx.browsers.waitFor(session.id, {
    selector: '.nonexistent',
    timeout: 5000,
  });
} catch (error) {
  if (error instanceof BrowserTimeoutError) {
    console.log('Element did not appear within timeout');
  } else if (error instanceof BrowserError) {
    console.log('Browser action failed:', error.message);
  }
}

Action Chaining Pattern

Actions are designed to be composed sequentially for multi-step workflows:

// Login flow
await tx.browsers.navigate(session.id, { url: 'https://app.example.com/login' });
await tx.browsers.type(session.id, { selector: '#email', text: 'user@example.com' });
await tx.browsers.type(session.id, { selector: '#password', text: 'secret' });
await tx.browsers.click(session.id, { selector: 'button[type="submit"]' });
await tx.browsers.waitFor(session.id, { selector: '.dashboard', timeout: 10000 });
 
const data = await tx.browsers.extractText(session.id, {
  selector: '.welcome-message',
});

Next Steps

Browsers Quickstart — Get started with a hands-on example
Browsers Overview — Features, anti-detection, and pricing