Package Exports

roxy-browser-api

Readme

Roxy Browser API Client

A TypeScript client library for the Roxy Browser API that provides programmatic control over browser windows with advanced fingerprint management and proxy support.

Features

🎭 Fingerprint Management - Create and manage browser fingerprints for privacy and automation
🌐 Proxy Support - Configure proxies for each browser window
🚀 Browser Automation - Full control over browser window lifecycle
📦 TypeScript First - Complete type definitions for all API operations
🔄 Multiple Formats - Supports both CommonJS and ES Modules
⚡ Modern Runtime - Built with Bun, works with Node.js

Installation

npm install roxy-browser-api

or with your preferred package manager:

# Using pnpm
pnpm add roxy-browser-api

# Using yarn
yarn add roxy-browser-api

# Using bun
bun add roxy-browser-api

Quick Start

1. Get Your API Token

First, obtain your API token from the Roxy Browser dashboard.

2. Configure Environment Variables

Create a .env file in your project root:

ROXY_API_TOKEN=your_api_token_here
ROXY_API_BASE_URL=http://127.0.0.1:50000

3. Basic Usage

import { RoxyBrowserClient } from "roxy-browser-api";

async function main() {
  // Initialize the client (automatically reads from environment variables)
  const client = new RoxyBrowserClient();

  // Get list of workspaces
  const workspaceData = await client.getWorkspace({
    page_index: 1,
    page_size: 10,
  });

  console.log(`Found \${workspaceData.total} workspaces`);

  // Create a new browser window
  const browserWindow = await client.createBrowser({
    workspaceId: workspaceData.rows[0].id,
    windowName: "My Test Browser",
    fingerInfo: {
      language: "en-US",
      timeZone: "America/New_York",
    },
  });

  console.log(`Created browser window: \${browserWindow.windowId}`);

  // Open the browser and get automation endpoints
  const openResult = await client.openBrowser({
    workspaceId: workspaceData.rows[0].id,
    dirId: browserWindow.dirId,
  });

  console.log(`WebSocket endpoint: \${openResult.ws}`);
  console.log(`HTTP endpoint: \${openResult.http}`);
}

main().catch(console.error);

API Reference

Client Initialization

// Using environment variables
const client = new RoxyBrowserClient();

// Or provide credentials directly
const client = new RoxyBrowserClient("your_api_token", "http://127.0.0.1:50000");

Workspace Management

Get Workspaces

const workspaces = await client.getWorkspace({
  page_index: 1,
  page_size: 10,
});

Browser Window Operations

Create Browser Window

const browserWindow = await client.createBrowser({
  workspaceId: 123,
  windowName: "My Browser",
  fingerInfo: {
    language: "en-US",
    timeZone: "America/New_York",
    isLanguageBaseIp: false,
    isTimeZone: false,
  },
  proxyInfo: {
    // Optional proxy configuration
    proxyType: "http",
    proxyHost: "proxy.example.com",
    proxyPort: 8080,
  },
});

Open Browser Window

const connection = await client.openBrowser({
  workspaceId: 123,
  dirId: "window_dir_id",
  args: ["--remote-allow-origins=*"], // Optional browser launch arguments
});

// Use the WebSocket endpoint with Puppeteer or other automation tools
console.log(connection.ws); // WebSocket endpoint
console.log(connection.http); // HTTP endpoint
console.log(connection.driver); // ChromeDriver path

Get Browser List

const browsers = await client.getBrowserList({
  workspaceId: 123,
  page_index: 1,
  page_size: 20,
});

Update Browser Window

await client.updateBrowser({
  workspaceId: 123,
  dirId: "window_dir_id",
  windowName: "Updated Name",
  fingerInfo: {
    language: "es-ES",
  },
});

Close Browser Window

await client.closeBrowser({
  workspaceId: 123,
  dirIds: ["window_dir_id_1", "window_dir_id_2"],
});

Delete Browser Window

await client.deleteBrowser({
  workspaceId: 123,
  dirIds: ["window_dir_id"],
});

Fingerprint Management

Randomize Fingerprint

await client.randomizeFingerprint({
  workspaceId: 123,
  dirId: "window_dir_id",
});

Cache Management

Clear Local Cache

await client.clearLocalCache({
  workspaceId: 123,
  dirIds: ["window_dir_id"],
});

Clear Server Cache

await client.clearServerCache({
  workspaceId: 123,
  dirIds: ["window_dir_id"],
});

Account and Label Management

Get Accounts

const accounts = await client.getAccount({
  workspaceId: 123,
  page_index: 1,
  page_size: 10,
});

Get Labels

const labels = await client.getLabel({
  workspaceId: 123,
});

TypeScript Support

This library is written in TypeScript and provides complete type definitions for all API operations. All request and response types are exported for your convenience:

import type {
  RoxyBrowserClient,
  CreateBrowserRequest,
  CreateBrowserResponse,
  FingerInfo,
  ProxyInfo,
  // ... and many more
} from "roxy-browser-api";

Integration with Puppeteer

After opening a browser window, you can connect to it using Puppeteer:

import puppeteer from "puppeteer-core";
import { RoxyBrowserClient } from "roxy-browser-api";

const client = new RoxyBrowserClient();

// Create and open browser
const workspace = await client.getWorkspace();
const browser = await client.createBrowser({
  workspaceId: workspace.rows[0].id,
  windowName: "Puppeteer Test",
});

const connection = await client.openBrowser({
  workspaceId: workspace.rows[0].id,
  dirId: browser.dirId,
});

// Connect Puppeteer to the remote browser
const puppeteerBrowser = await puppeteer.connect({
  browserWSEndpoint: connection.ws,
});

const page = await puppeteerBrowser.newPage();
await page.goto("https://example.com");

// Your automation code here...

await puppeteerBrowser.disconnect();

Error Handling

The client throws errors for API failures. Always wrap your calls in try-catch blocks:

try {
  const result = await client.createBrowser({
    workspaceId: 123,
    windowName: "Test",
  });
} catch (error) {
  if (error instanceof Error) {
    console.error("API Error:", error.message);
  }
}

Environment Variables

ROXY_API_TOKEN (required) - Your Roxy Browser API authentication token
ROXY_API_BASE_URL (optional) - API base URL (defaults to http://127.0.0.1:50000)

Requirements

Node.js 18+ or Bun 1.0+
TypeScript 5.0+ (for TypeScript projects)

License

MIT

Support

For API documentation and support, visit Roxy Browser Documentation.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.