@roveapi/browser

Browser automation SDK for AI agents. Wraps the Rove API — Playwright-as-a-Service with accessibility trees for 77% fewer tokens.

Install

npm install @roveapi/browser

Quickstart

import { BrowserClient } from '@roveapi/browser'

const client = new BrowserClient({ apiKey: 'rvp_live_...' })

// One-shot screenshot
const screenshot = await client.screenshot({ url: 'https://example.com' })
console.log(screenshot.url) // signed S3 URL

// Session-based workflow
const session = await client.session()
await session.navigate('https://example.com')
const tree = await session.getA11yTree()
console.log(tree.result.tree) // accessibility tree (~26K tokens vs ~114K for screenshot)
await session.click({ label: 'Get Started' })
await session.fill({ selector: '#email', value: '[email protected]' })
await session.close()

Supervised sessions

Supervised mode is explicit; ordinary sessions are unchanged. It requires an rvp_live_ API key because test-mode keys do not allocate a streamable browser. The viewer grant is one-time and bound to the exact viewer origin.

const session = await client.session({ supervised: true })
const grant = await client.createViewerGrant(session.id)
// Give grant.admissionCode to that operator and open grant.viewerUrl there.
// Viewer control is exclusive. After handback, the agent must observe again.
// The hosted viewer performs admission, takeover, and explicit handback at grant.origin.
await session.getA11yTree()
await session.close()

Error Handling

import { BrowserClient, InsufficientCreditsError, RateLimitError } from '@roveapi/browser'

try {
  const session = await client.session()
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    // nextStep: 'buy_credits' (buy one of err.packsWithinLimits) or 'ask_owner' (give a person err.ownerActionUrl)
    console.log(err.nextStep, err.packsWithinLimits, err.ownerActionUrl)
  }
  if (err instanceof RateLimitError) {
    console.log(`Retry after ${err.retryAfter} seconds`)
  }
}

Credits and purchases

An API key can read its balance and the catalogue, and buy credit packs when the account owner has allowed it.

import { BrowserClient, formatCredits, PurchaseNotPermittedError, SpendLimitExceededError } from '@roveapi/browser'

const balance = await client.balance()
console.log(formatCredits(balance.credits_remaining_millicredits)) // "1.75" (integer arithmetic)

if (balance.purchasing.allowed && balance.purchasing.packs_within_limits.length > 0) {
  const purchase = await client.purchaseCredits({ itemId: balance.purchasing.packs_within_limits[0] })
  if (purchase.next_action) console.log(purchase.next_action.instruction, purchase.next_action.url) // a person pays here
  // Poll every 5 s or slower until it is paid:
  const latest = await client.getPurchase(purchase.id)
}

• purchaseCredits generates an Idempotency-Key when you pass none, reuses it on its own retries (network errors, 409 idempotency-in-progress, 429, 503; at most 3 attempts, honouring Retry-After up to 60 seconds), returns it as purchase.idempotencyKey, and sets err.idempotencyKey on every error it throws. Retry with that key to never buy twice; use a new key when the error's retry is new_key.
• Errors: PurchaseNotPermittedError (reason, suggestedPayment), SpendLimitExceededError (limit, limitCents, committedCents, requestedCents, resetsAt, packsWithinLimits), PaymentFailedError (purchaseId, failureCode), IdempotencyKeyReusedError, BillingUnavailableError (retryAfter). Every RoveError carries the problem's retry and ownerActionUrl when the API sent them, and the raw body as problem. Problems are matched by the last path segment of their type.
• With a test key (rvp_test_), purchases are simulated: client.simulatePurchase(id, 'paid' | 'expired' | 'failed' | 'authentication_required').

API

BrowserClient

new BrowserClient({ apiKey, baseUrl?, retries?, retryDelay? })

• client.session(options?) → Session
• client.screenshot({ url, selector?, fullPage?, format? }) → ScreenshotResponse
• client.extract({ url, schema, waitForSelector? }) → ExtractResponse
• client.usage() → UsageResponse (its api_key field is deprecated: the masked prefix rvp_live_…/rvp_test_…, never the token; exact *_millicredits fields alongside the whole credits)
• client.balance() → BalanceView
• client.catalogue() → Catalogue
• client.purchaseCredits({ itemId, payment?, idempotencyKey? }) → Purchase (PurchaseView plus idempotencyKey); payment is 'auto' (default), 'checkout' or 'saved_method'
• client.getPurchase(id) → PurchaseView
• client.listPurchases({ limit?, cursor? }) → { data: PurchaseView[], nextCursor }
• client.cancelPurchase(id) → PurchaseView
• client.simulatePurchase(id, outcome) → PurchaseView (test keys only)
• formatCredits(millicredits) → string

BalanceView, Catalogue and PurchaseView are generated from the API's OpenAPI document.

Session

• session.navigate(url, options?) — load URL, return title + status
• session.getA11yTree(options?) — accessibility tree (primary tool for LLMs)
• session.click({ selector?, label? }) — click element
• session.fill({ selector?, label?, value }) — type into input
• session.select({ selector?, value? }) — select dropdown option
• session.scroll({ direction?, amount? }) — scroll page
• session.waitFor({ type, value }) — wait for condition
• session.screenshot({ fullPage?, format? }) — capture page
• session.getText(selector) — extract text
• session.getAttribute(selector, attribute) — get attribute
• session.evaluate(expression) — run JavaScript
• session.close() — close session, finalize artifacts

Auto-retry on 503 (pool exhausted, browser crash) with exponential backoff. No retry on 402 (insufficient credits) or 410 (session expired).