Node.js SDK reference

import { Rayobrowse } from 'rayobrowse';

const client = new Rayobrowse({
  endpoint: 'https://browser.rayobyte.com',
  apiKey: 'rb_live_YOUR_KEY',
});

Constructor

Property	Type	Description
endpoint	string	Gateway base URL. Pass the cloud endpoint, 'https://browser.rayobyte.com'. Leaving it out throws a TypeError on construction
apiKey	string	Your rb_live_ key

connectUrl(options): Promise<string>

Creates a browser and resolves to its CDP WebSocket URL.

Option	Type	Description
proxy	string	Required by the gateway, though the type marks it optional. scheme://user:pass@host:port
os	string	windows, android, linux, macos. Defaults to windows
headless	boolean	Run without a window
vnc	boolean	Request a live-view URL
maxLifetime	number	Seconds. Omitted means 7200, clamped into 120 to 86400
browserLanguage	string	Accept-Language value
uiLanguage	string	UI locale
browserVersionMin	number	Lowest Chromium major version the profile may claim. Defaults to the running version
browserVersionMax	number	Highest Chromium major version the profile may claim. Defaults to the running version
screenWidthMin	number	Lowest screen width
screenHeightMin	number	Lowest screen height
forceVisibility	boolean	Keep a background tab reporting itself visible and focused
metadata	object	Stored on the session, JSON-stringified on the way out

reconnectUrl(sessionId): Promise<string>

The CDP URL of a running session. Creates nothing. Pass the sessionId value, not the br_ id inside a CDP URL, which returns 404.

close(sessionId?): Promise<void>

Closes a session, defaulting to the most recent one. Either id works: the sessionId value or the br_ id at the end of the CDP URL. Throws RayobrowseError when there is no id to use.

listBrowsers(): Promise<BrowserSession[]>

Your running sessions. Each carries browserId, cdpUrl, status, createdAt and expiresAt.

getHealth(): Promise<HealthStatus>

The gateway’s health response.

getSessionCount(): Promise<{ limit: number; remaining: number }>

Your concurrent browser limit and the slots free right now, the same numbers GET /user/api/limits reports as limit and remaining. It does not count against the per-minute limit.

Properties

Property	Type	Description
sessionId	string | null	br_ id from the last connectUrl()
vncUrl	string | null	Live-view URL, set only when vnc: true was passed and the browser came up with one

Types

interface ConnectOptions {
  proxy?: string;
  os?: string;
  headless?: boolean;
  vnc?: boolean;
  maxLifetime?: number;
  browserLanguage?: string;
  uiLanguage?: string;
  browserVersionMin?: number;
  browserVersionMax?: number;
  screenWidthMin?: number;
  screenHeightMin?: number;
  forceVisibility?: boolean;
  metadata?: Record<string, unknown>;
}

interface HealthStatus {
  status: string;
  uptime: number;
}

Error classes

Error	Status	Properties
RayobrowseError	any	statusCode, body
AuthError	401	statusCode. No body
ConcurrencyLimitError	429	limit, active, retryAfter. No body
RateLimitError	429	retryAfter. No body
BrowserCreateError	any other	statusCode, body

In 0.2.0 the two 429 classes do not reliably match the limit that was hit, and neither carries the response’s code. Catch both and wait retryAfter seconds: 5 for a full account, 60 for the rate limit. To tell the two limits apart, read code from the HTTP API directly. See Limits.

A missing or malformed proxy throws BrowserCreateError with statusCode 400, and a proxy the browser cannot get through throws it with statusCode 422. body is the plain-text message from /connect, a string, so there is no body.code to read. Match on the status. Neither is worth retrying.