Skip to main content

JavaScript SDK

The official JavaScript/TypeScript client for the Browsr cloud API.

Installation​

npm install @browsr/sdk

Setup​

import { BrowsrClient } from '@browsr/sdk';

const client = new BrowsrClient({
  apiKey: process.env.BROWSR_API_KEY,
});

Scrape​

const result = await client.scrape('https://example.com', {
  formats: ['markdown', 'links', 'screenshot'],
  onlyMainContent: true,
});

console.log(result.data.markdown);
console.log(result.data.links);

With JSON extraction​

const result = await client.scrape('https://example.com/pricing', {
  formats: ['json'],
  jsonOptions: {
    prompt: 'Extract all pricing plans',
    schema: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          name: { type: 'string' },
          price: { type: 'string' },
        },
      },
    },
  },
});

With pre-scrape actions​

const result = await client.scrape('https://example.com', {
  formats: ['markdown'],
  actions: [
    { type: 'click', selector: '#accept-cookies' },
    { type: 'wait', milliseconds: 1000 },
    { type: 'scroll', direction: 'down', amount: 3 },
  ],
});

Crawl​

const result = await client.crawl('https://docs.example.com', {
  limit: 20,
  maxDepth: 3,
  formats: ['markdown'],
  includePaths: ['/docs/**'],
});

for (const page of result.data) {
  console.log(page.metadata.sourceURL, page.markdown?.length);
}

Sessions​

// Create
const session = await client.sessions.create({
  headless: true,
  startUrl: 'https://example.com',
});

// List
const { sessions } = await client.sessions.list();

// Delete
await client.sessions.delete(session.sessionId);

Commands​

const result = await client.commands.execute({
  sessionId: session.sessionId,
  commands: [
    { command: 'navigate_to', data: { url: 'https://example.com' } },
    { command: 'wait_for_element', data: { selector: 'main' } },
    { command: 'get_content', data: { selector: 'main', kind: 'markdown' } },
  ],
});

Observe​

const observation = await client.observe({
  sessionId: session.sessionId,
  useImage: true,
  includeContent: true,
});

Browser step​

const step = await client.browserStep({
  sessionId: session.sessionId,
  commands: [
    { command: 'click', data: { selector: 'button.next' } },
  ],
});

Shell​

// Create shell session
const shell = await client.shell.create({
  memoryMb: 512,
  timeoutSecs: 300,
});

// Execute a command
const result = await client.shell.exec({
  sessionId: shell.sessionId,
  command: 'echo "Hello from Browsr"',
});
console.log(result.stdout);

// Cleanup
await client.shell.delete(shell.sessionId);

Scripts​

// Execute JavaScript in a browser session
const result = await client.scripts.execute({
  sessionId: session.sessionId,
  code: 'return document.querySelectorAll("a").length;',
  timeoutSecs: 30,
});

Profiles​

// Create a profile
const profile = await client.profiles.create({
  name: 'my-profile',
  data: {
    cookies: [{ name: 'session', value: 'abc', domain: '.example.com' }],
    userAgent: 'Mozilla/5.0 ...',
  },
});

// Use profile when creating session
const session = await client.sessions.create({
  profileId: profile.id,
});