SDK Usage

The @waqi-browser/hyperscaler SDK provides a TypeScript client to provision, manage, and connect to cloud browser instances without manually handling WebSockets or HTTP handshakes.

Installation

Install the SDK alongside your preferred automation library (e.g., Puppeteer).

npm install @waqi-browser/hyperscaler puppeteer-core

Core Concepts

The SDK is built around two primary classes:

• BrowserHyperscaler: The main client used to authenticate and request new browser instances.
• BrowserInstance: Represents a running cloud browser. It handles the liveness connection and provisions CDP transports.

Both classes implement the Disposable interface ([Symbol.dispose]). You should always instantiate them with the using keyword to ensure cloud resources are immediately terminated and billed correctly when your function exits.

Initialization

Initialize the client with your API key.

import { BrowserHyperscaler } from "@waqi-browser/hyperscaler"

const client = new BrowserHyperscaler("YOUR_API_KEY")

Provisioning an Instance

Call newBrowser() to provision a new cloud browser. The returned BrowserInstance maintains the liveness connection to the server.

// Provision the instance (automatically cleaned up when out of scope)
using instance = await client.newBrowser()

console.log("Provisioned Browser ID:", instance.browser_id)

Establishing a Connection

To automate the browser, establish a DevTools transport connection by calling newConnection() on the instance.

The returned connection object implements a standard Transport interface that drops natively into Puppeteer.

import puppeteer from "puppeteer-core"

// Establish the DevTools WebSocket transport
using connection = await instance.newConnection()

// Attach Puppeteer to the cloud browser
const browser = await puppeteer.connect({
  transport: connection,
})

const page = await browser.newPage()
await page.goto("https://google.com")
await browser.close()

API Reference

BrowserHyperscaler

constructor(apiKey: string, baseURL?: string)

Initializes the client. baseURL defaults to https://api.browser.waqitech.com.

newBrowser(): Promise<BrowserInstance>

Provisions a new browser instance and establishes the liveness WebSocket.

BrowserInstance

browser_id: string

The unique identifier of the provisioned browser session.

newConnection(): Promise<Transport>

Retrieves the CDP debugger URL and establishes a DevTools WebSocket connection. Returns a standard Transport object.

[Symbol.dispose]()

Terminates the liveness connection, shutting down the cloud browser instance. Invoked automatically when declared with using.