Transactional

Quickstart

Open your first browser session — navigate, click, screenshot, extract data, and close.

Install the SDK

npm install @usetransactional/node

Create a Browser Session

import Transactional from '@usetransactional/node';
 
const tx = new Transactional({
  apiKey: process.env.TRANSACTIONAL_API_KEY,
});
 
const session = await tx.browsers.create();
 
console.log('Session ID:', session.id);
console.log('Status:', session.status); // 'ready'

Navigate to a Page

await tx.browsers.navigate(session.id, {
  url: 'https://news.ycombinator.com',
});

Take a Screenshot

Capture what the browser sees:

const screenshot = await tx.browsers.screenshot(session.id, {
  fullPage: false, // viewport only
});
 
// screenshot.data is a base64-encoded PNG
console.log('Screenshot size:', screenshot.data.length, 'bytes');

Extract Text

Pull text content from specific elements:

const headlines = await tx.browsers.extractText(session.id, {
  selector: '.titleline > a',
});
 
console.log('Headlines:', headlines.text);

Extract Structured Data

Extract data into a typed structure:

const stories = await tx.browsers.extractStructured(session.id, {
  selector: '.athing',
  schema: {
    title: { selector: '.titleline > a', attribute: 'textContent' },
    url: { selector: '.titleline > a', attribute: 'href' },
    rank: { selector: '.rank', attribute: 'textContent' },
  },
});
 
for (const story of stories.items) {
  console.log(`${story.rank} ${story.title} (${story.url})`);
}

Click an Element

await tx.browsers.click(session.id, {
  selector: '.morelink', // "More" link at the bottom
});
 
// Page navigates to next page of results

Type into an Input

await tx.browsers.navigate(session.id, {
  url: 'https://www.google.com',
});
 
await tx.browsers.type(session.id, {
  selector: 'textarea[name="q"]',
  text: 'transactional email API',
});
 
await tx.browsers.click(session.id, {
  selector: 'input[name="btnK"]',
});

Wait for Elements

Wait for dynamic content to appear:

await tx.browsers.waitFor(session.id, {
  selector: '#search-results',
  timeout: 10000, // 10 seconds
});
 
const results = await tx.browsers.extractText(session.id, {
  selector: '#search-results',
});

Close the Session

Always close sessions when done to free resources:

await tx.browsers.close(session.id);
console.log('Session closed');

Full Example

import Transactional from '@usetransactional/node';
 
const tx = new Transactional({
  apiKey: process.env.TRANSACTIONAL_API_KEY,
});
 
async function scrapeProductInfo(url: string) {
  const session = await tx.browsers.create();
 
  try {
    await tx.browsers.navigate(session.id, { url });
 
    // Wait for content to load
    await tx.browsers.waitFor(session.id, {
      selector: '.product-details',
      timeout: 10000,
    });
 
    // Take a visual snapshot
    const screenshot = await tx.browsers.screenshot(session.id, {
      fullPage: true,
    });
 
    // Extract structured product data
    const product = await tx.browsers.extractStructured(session.id, {
      selector: '.product-details',
      schema: {
        name: { selector: 'h1', attribute: 'textContent' },
        price: { selector: '.price', attribute: 'textContent' },
        description: { selector: '.description', attribute: 'textContent' },
      },
    });
 
    return {
      screenshot: screenshot.data,
      product: product.items[0],
    };
  } finally {
    await tx.browsers.close(session.id);
  }
}

Next Steps