@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);

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

Publishing requires an authenticated npm account with access to the @hivebrowser scope:

cd packages/sdk-js
npm publish --access public