BabelWrap JavaScript/TypeScript SDK

The official JavaScript/TypeScript SDK for BabelWrap — the web, as an API, for your agents.

Installation

npm install babelwrap

Quick Start

import { BabelWrap } from "babelwrap";

const bw = new BabelWrap({ apiKey: process.env.BABELWRAP_API_KEY! });
const session = await bw.createSession();

try {
  // Navigate to a page
  const snap = await session.navigate("https://news.ycombinator.com");
  console.log(snap.title); // "Hacker News"

  // Extract structured data
  const stories = await session.extract("top 5 story titles and their URLs");
  console.log(stories);
} finally {
  await session.close();
}

With TypeScript using (auto-cleanup)

import { BabelWrap } from "babelwrap";

const bw = new BabelWrap({ apiKey: process.env.BABELWRAP_API_KEY! });
await using session = await bw.createSession();

await session.navigate("https://example.com");
await session.fill("Email field", "user@example.com");
await session.fill("Password field", "secret");
await session.submit();

const data = await session.extract("the user profile information");

API Reference

BabelWrap

const bw = new BabelWrap({
  apiKey: "bw_...",          // Required
  baseUrl: "https://...",    // Default: https://api.babelwrap.com
  timeout: 60000,            // Default: 60s
  maxRetries: 3,             // Default: 3
});

Methods:

• createSession(options?) — Create a new browser session
• usage() — Get current usage stats
• health() — Health check
• mapSite(url, cookies?) — Map a website and generate typed tools
• listSites() — List mapped sites
• siteTools(siteId) — Get tools for a mapped site
• executeTool(siteId, toolName, params?) — Execute a site tool

Session

All methods return a Snapshot (attribute-accessible page state) unless noted.

• navigate(url) — Navigate to URL
• click(target) — Click element by description
• fill(target, value) — Fill form field
• submit(target?) — Submit form
• extract(query) — Extract structured data (returns object[] | object)
• press(key) — Press keyboard key
• scroll(direction?, amount?) — Scroll page
• hover(target) — Hover over element
• screenshot() — Take screenshot (returns base64 string)
• upload(target, file, filename?) — Upload file
• back() / forward() — Browser history
• snapshot() — Read current page state
• waitFor(options) — Wait for condition
• history() — Get action history
• batch(actions, continueOnError?) — Execute multiple actions
• close() — Close session

Snapshot

Attribute-accessible wrapper for page state:

const snap = await session.navigate("https://example.com");
snap.url;                // "https://example.com"
snap.title;              // "Example Domain"
snap.inputs;             // Snapshot[] of form inputs
snap.inputs[0].label;    // "Email address"
snap.get("missing", "default"); // "default"
snap.toDict();           // Plain object

Requirements

• Node.js 18+ (uses global fetch)
• Zero runtime dependencies