Browser

Browser automation for Node.js. Capture screenshots, generate PDFs, extract page content, monitor network requests, and more.

Features

Automatic Token Management - Tokens generated and cached automatically
Page Content Extraction - Extract HTML, text, or both from webpages
Screenshots - Full page or viewport screenshots in PNG/JPEG
PDF Generation - Convert webpages to PDF with custom formatting
Network Monitoring - Capture and analyze network requests
Console Logs - Get browser console output for debugging
Device Emulation - Emulate mobile devices and custom viewports
Proxy Support - Optional proxy routing

Installation

npm install oblien

Quick Start

import { OblienClient, OblienBrowser } from 'oblien';

const client = new OblienClient({
  clientId: process.env.OBLIEN_CLIENT_ID,
  clientSecret: process.env.OBLIEN_CLIENT_SECRET
});

const browser = new OblienBrowser(client);

// Get page content
const result = await browser.getPageContent({
  url: 'https://example.com',
  extract: 'both'
});

console.log(result.title);
console.log(result.text);

Authentication

Browser tokens are automatically generated and cached. Each token:

Expires in 1 minute (for security)
Grants full access to all browser operations
Is cached and reused within the expiration window

Manual Token Generation

// Generate token manually (optional)
const tokenData = await browser.generateToken();
console.log(tokenData.token); // eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Clear Token Cache

// Force fresh token generation
browser.clearTokenCache();

API Reference

Constructor

const browser = new OblienBrowser(client, config);

Parameters:

client - Oblien client instance
config (optional) - Configuration object
- browserURL - Custom browser server URL (default: https://browser.oblien.com)

Page Content

Extract HTML, text, or both from any webpage.

const result = await browser.getPageContent({
  url: 'https://example.com',
  extract: 'both',
  waitFor: 2000,
  selector: '.main-content',
  waitForFullLoad: true
});

console.log(result.title); // 'Example Domain'
console.log(result.text);  // Page text content
console.log(result.html);  // Full HTML

// 1. Generate browser token
const tokenRes = await fetch('https://api.oblien.com/browser/token', {
  method: 'POST',
  headers: {
    'x-client-id': 'your-client-id',
    'x-client-secret': 'your-client-secret',
    'Content-Type': 'application/json'
  }
});
const { token } = await tokenRes.json();

// 2. Get page content
const response = await fetch('https://browser.oblien.com/page-content', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com',
    extract: 'both'
  })
});

const result = await response.json();

# 1. Generate browser token
TOKEN=$(curl -X POST https://api.oblien.com/browser/token \
  -H "x-client-id: your-client-id" \
  -H "x-client-secret: your-client-secret" \
  | jq -r '.token')

# 2. Get page content
curl -X POST https://browser.oblien.com/page-content \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "extract": "both"
  }'

Options:

url (required) - URL to visit
extract - Content type: 'html', 'text', or 'both'
waitFor - Wait time in milliseconds
selector - CSS selector to wait for
waitForFullLoad - Wait for complete page load
proxy - Proxy server URL (e.g., 'http://proxy.example.com:8080')
proxyPort - Proxy port (optional if in URL)
proxyUsername - Proxy authentication username
proxyPassword - Proxy authentication password

Screenshots

Capture page screenshots in PNG or JPEG.

const result = await browser.screenshot({
  url: 'https://example.com',
  fullPage: true,
  format: 'png',
  viewport: { width: 1920, height: 1080 }
});

// Save to file
import fs from 'fs';
const imageData = result.screenshot.replace(/^data:image\/\w+;base64,/, '');
const buffer = Buffer.from(imageData, 'base64');
fs.writeFileSync('screenshot.png', buffer);

const response = await fetch('https://browser.oblien.com/screenshot', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${browserToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com',
    fullPage: true,
    format: 'png'
  })
});

const result = await response.json();
// result.screenshot contains base64 image data

curl -X POST https://browser.oblien.com/screenshot \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "fullPage": true,
    "format": "png"
  }' | jq -r '.screenshot' | base64 -d > screenshot.png

Options:

url (required) - URL to screenshot
fullPage - Capture full scrollable page (default: false)
format - 'png' or 'jpeg' (default: 'png')
quality - JPEG quality 0-100 (default: 80)
viewport - Viewport size { width, height }
device - Device preset name (e.g., 'iPhone 13')
proxy - Proxy server URL
proxyPort - Proxy port
proxyUsername - Proxy authentication username
proxyPassword - Proxy authentication password

PDF Generation

Convert webpages to PDF documents.

const result = await browser.pdf({
  url: 'https://example.com',
  format: 'A4',
  landscape: false,
  printBackground: true,
  margin: {
    top: '1cm',
    right: '1cm',
    bottom: '1cm',
    left: '1cm'
  }
});

// Save to file
import fs from 'fs';
const pdfBuffer = Buffer.from(result.pdf, 'base64');
fs.writeFileSync('page.pdf', pdfBuffer);

const response = await fetch('https://browser.oblien.com/pdf', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${browserToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com',
    format: 'A4',
    printBackground: true
  })
});

const result = await response.json();
// result.pdf contains base64 PDF data

curl -X POST https://browser.oblien.com/pdf \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "A4",
    "printBackground": true
  }' | jq -r '.pdf' | base64 -d > page.pdf

Options:

url (required) - URL to convert
format - Paper format: 'A4', 'Letter', 'Legal', etc.
landscape - Landscape orientation (default: false)
printBackground - Print background graphics (default: false)
margin - Page margins { top, right, bottom, left }
proxy - Proxy server URL
proxyPort - Proxy port
proxyUsername - Proxy authentication username
proxyPassword - Proxy authentication password

Network Monitoring

Capture and analyze network requests.

const result = await browser.monitorRequests({
  url: 'https://example.com',
  duration: 5000,
  filterTypes: ['xhr', 'fetch']
});

console.log('Total requests:', result.count);
console.log('API calls:', result.requests);

const response = await fetch('https://browser.oblien.com/monitor-requests', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${browserToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com',
    duration: 5000,
    filterTypes: ['xhr', 'fetch']
  })
});

const result = await response.json();

Options:

url (required) - URL to monitor
duration - Monitoring duration in ms (default: 3000)
filterTypes - Filter types: ['xhr', 'fetch', 'script', 'stylesheet', 'image']
proxy - Proxy server URL
proxyPort - Proxy port
proxyUsername - Proxy authentication username
proxyPassword - Proxy authentication password

Console Logs

Capture browser console output.

const result = await browser.getConsoleLogs({
  url: 'https://example.com',
  duration: 3000
});

const errors = result.logs.filter(log => log.type === 'error');
console.log('Errors found:', errors.length);

const response = await fetch('https://browser.oblien.com/console-logs', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${browserToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com',
    duration: 3000
  })
});

const result = await response.json();

Options:

url (required) - URL to monitor
duration - Monitoring duration in ms
proxy - Proxy server URL
proxyPort - Proxy port
proxyUsername - Proxy authentication username
proxyPassword - Proxy authentication password

Device Presets

Get available device emulation presets.

const devices = await browser.getDevicePresets();
console.log(devices.devices);
// {
//   'iPhone 13': { width: 390, height: 844, ... },
//   'iPad Pro': { width: 1024, height: 1366, ... },
//   ...
// }

Server Status

Check browser server status.

const status = await browser.getStatus();
console.log(status);
// {
//   status: 'running',
//   poolSize: 5,
//   activeBrowsers: 2
// }

Usage Examples

Web Scraping

// Extract content from dynamic pages
const result = await browser.getPageContent({
  url: 'https://example-shop.com/product/123',
  selector: '.product-info',
  waitFor: 2000,
  extract: 'both'
});

// Parse with cheerio or similar
import * as cheerio from 'cheerio';
const $ = cheerio.load(result.html);
const price = $('.price').text();
const title = $('.title').text();

Mobile Screenshots

// Screenshot as iPhone
const result = await browser.screenshot({
  url: 'https://example.com',
  device: 'iPhone 13',
  fullPage: true
});

Invoice PDFs

// Generate styled PDF
const result = await browser.pdf({
  url: 'https://example.com/invoice/456',
  format: 'A4',
  printBackground: true,
  margin: { top: '2cm', right: '2cm', bottom: '2cm', left: '2cm' }
});

// Send via email or save to storage

Debug API Calls

// Monitor XHR/Fetch requests
const result = await browser.monitorRequests({
  url: 'https://app.example.com',
  duration: 5000,
  filterTypes: ['xhr', 'fetch']
});

const apiCalls = result.requests.filter(r => r.url.includes('/api/'));
console.log('API calls:', apiCalls);

Integration Examples

Express.js

import express from 'express';
import { OblienClient, OblienBrowser } from 'oblien';

const app = express();
const client = new OblienClient({
  clientId: process.env.OBLIEN_CLIENT_ID,
  clientSecret: process.env.OBLIEN_CLIENT_SECRET
});
const browser = new OblienBrowser(client);

app.post('/api/screenshot', async (req, res) => {
  try {
    const { url } = req.body;
    const result = await browser.screenshot({
      url,
      fullPage: true,
      format: 'png'
    });
    res.json(result);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000);

Next.js API Route

import { OblienClient, OblienBrowser } from 'oblien';

const client = new OblienClient({
  clientId: process.env.OBLIEN_CLIENT_ID,
  clientSecret: process.env.OBLIEN_CLIENT_SECRET
});
const browser = new OblienBrowser(client);

export async function POST(request) {
  const { url } = await request.json();
  
  const result = await browser.pdf({
    url,
    format: 'A4'
  });
  
  return Response.json(result);
}

Best Practices

1. Token Management

Tokens are cached automatically - no manual management needed:

// These requests reuse the same cached token
const result1 = await browser.screenshot({ url: 'https://example.com' });
const result2 = await browser.pdf({ url: 'https://another.com' });

Clear cache only when needed:

browser.clearTokenCache();

2. Error Handling

Always use try-catch blocks:

try {
  const result = await browser.getPageContent({
    url: 'https://example.com'
  });
} catch (error) {
  if (error.message.includes('token_expired')) {
    browser.clearTokenCache();
    // Retry
  }
  console.error('Browser error:', error);
}

3. Wait for Dynamic Content

Use selectors or wait times for SPAs:

const result = await browser.getPageContent({
  url: 'https://spa-app.com',
  selector: '.main-content', // Wait for element
  waitFor: 3000 // Or fixed time
});

4. Optimize Performance

Use viewport screenshots for faster results:

// Faster - viewport only
const result = await browser.screenshot({
  url: 'https://example.com',
  fullPage: false,
  viewport: { width: 1920, height: 1080 }
});

Proxy Support

All browser operations support native network-layer proxy routing with authentication.

Quick Example

const result = await browser.getPageContent({
  url: 'https://example.com',
  proxy: 'http://proxy.example.com',
  proxyPort: 8080,
  proxyUsername: 'user',
  proxyPassword: 'pass',
  extract: 'both'
});

Configuration Options

Flexible proxy configuration:

// Option 1: Full URL with port
{ proxy: 'http://proxy.example.com:8080' }

// Option 2: Separate port parameter
{ proxy: 'http://proxy.example.com', proxyPort: 8080 }

// Option 3: Simple host + port (protocol auto-added)
{ proxy: 'proxy.example.com', proxyPort: 8080 }

// Option 4: With authentication
{
  proxy: 'proxy.example.com',
  proxyPort: 3128,
  proxyUsername: 'user',
  proxyPassword: 'pass'
}

Architecture

Dynamic Proxy Pools - Separate browser pools per proxy configuration
Efficient Reuse - Browsers with same proxy share a pool for fast response
Ultra-Clean - Each request gets fresh incognito context (complete isolation)
Performance - 1-2s response time after initial proxy warmup

All Methods Support Proxy

Proxy parameters work with all browser methods:

getPageContent() - Extract content through proxy
screenshot() - Capture screenshots through proxy
pdf() - Generate PDFs through proxy
monitorRequests() - Monitor network through proxy
getConsoleLogs() - Get console logs through proxy

Security & Limits

Authentication: Required for all operations
Token Expiration: 1 minute (no refresh)
Rate Limits: Varies by tier
Proxy Support: Native network-layer proxy with authentication

Browser

Features

Installation

Quick Start

Authentication

Manual Token Generation

Clear Token Cache

API Reference

Constructor

Page Content

Screenshots

PDF Generation

Network Monitoring

Console Logs

Device Presets

Server Status

Usage Examples

Web Scraping

Mobile Screenshots

Invoice PDFs

Debug API Calls

Integration Examples

Express.js

Next.js API Route

Best Practices

1. Token Management

2. Error Handling

3. Wait for Dynamic Content

4. Optimize Performance

Proxy Support

Quick Example

Configuration Options

Architecture

All Methods Support Proxy

Security & Limits

Next Steps

On this page