@hivebrowser/sdk

Official JavaScript SDK for Hivebrowser cloud browser sessions.

This package manages Hivebrowser platform resources such as sessions, profiles, artifacts, live bootstrap URLs, typed API errors, and WS-first gateway URLs. Browser automation remains in Playwright or Puppeteer.

Install

npm install @hivebrowser/sdk playwright-core

Quickstart

import { Hivebrowser } from '@hivebrowser/sdk';
import { chromium } from 'playwright-core';

const hive = new Hivebrowser({
  apiKey: process.env.HIVEBROWSER_API_KEY!,
});

const session = await hive.sessions.createAndWait({
  timeoutSec: 300,
});

const browser = await chromium.connectOverCDP(session.connectUrl!);
const context = browser.contexts()[0] ?? (await browser.newContext());
const page = context.pages()[0] ?? (await context.newPage());

await page.goto('https://example.com');

const screenshot = await hive.artifacts.screenshot({
  sessionId: session.id,
  fullPage: true,
});

console.log(screenshot.downloadUrl);

await browser.close();
await hive.sessions.stop(session.id);

Playground Runs (0.2.0)

Version 0.2.0 can start a Playground run and wait for its terminal result:

const run = await hive.sessions.startPlaygroundRunAndWait('sess_123', {
  templateKey: 'browser-custom',
  script: `export default async function run({ page }) {
    await page.goto('https://example.com');
    return { title: await page.title() };
  }`,
});

console.log(run.output);

The waiter locks to the started run, returns only on SUCCEEDED, and throws a typed HivebrowserError for failed, stopped, replaced, or timed-out runs.

WS-First Gateway URL

const wsEndpoint = hive.browser.wsEndpoint({
  timeoutSec: 300,
  keepAlive: true,
  profile: {
    profileId: 'prof_123',
    mode: 'READ_WRITE',
    persistChanges: true,
  },
});

const browser = await chromium.connectOverCDP(wsEndpoint);

Errors

import { HivebrowserError, isHivebrowserError } from '@hivebrowser/sdk';

try {
  await hive.sessions.get('missing');
} catch (error) {
  if (isHivebrowserError(error)) {
    console.error(error.status, error.code, error.requestId);
  }
}

Release Checklist

Before publishing a new version:

pnpm --filter @hivebrowser/sdk typecheck
pnpm --filter @hivebrowser/sdk test
pnpm --filter @hivebrowser/sdk lint
pnpm --filter @hivebrowser/sdk pack:dry-run

For the full release process, including npm organization setup, 2FA/token handling, publish commands, verification, and token cleanup, see ../../docs/runbooks/sdk-npm-publish.md.