@builde2e/sdk

v1.6.1

Published

a day ago

Official BuildE2E SDK - Extract data from any website with a single API call

0High
0Medium
0Low

testmint.ai

builde2e web-fetching web-data crawler web-crawler data-extraction ai llm markdown search api

@builde2e/sdk

Official Node.js/Browser SDK for the BuildE2E API. Extract data from any website with a single API call.

Installation

npm install @builde2e/sdk

Or with yarn:

yarn add @builde2e/sdk

Quick Start

import BuildE2E from '@builde2e/sdk';

// Set your API key (get one at https://builde2e.com)
BuildE2E.setApiKey('uc-your-api-key');

// Fetch a webpage
const result = await BuildE2E.fetch({
  url: 'https://example.com',
  type: 'markdown'
});

console.log(result.markdown);

Usage

Setting API Key

The API key must be set before making any requests:

import BuildE2E from '@builde2e/sdk';

BuildE2E.setApiKey('uc-your-api-key');

Or using named imports:

import { setApiKey } from '@builde2e/sdk';

setApiKey('uc-your-api-key');

Fetching a Single URL

import BuildE2E from '@builde2e/sdk';

BuildE2E.setApiKey('uc-your-api-key');

const result = await BuildE2E.fetch({
  url: 'https://example.com',
  type: 'markdown',          // 'markdown' or 'html'
  onlyMainContent: true,     // Remove nav, ads, footers
  extractMetadata: true      // Get title, description, etc.
});

console.log(result.markdown);
console.log(result.metadata?.title);

Batch Fetching

Fetch multiple URLs in a single request:

const result = await BuildE2E.batchFetch({
  urls: [
    'https://example.com/page1',
    'https://example.com/page2',
    // You can also pass detailed options per URL:
    { url: 'https://example.com/page3', type: 'html' }
  ],
  type: 'markdown'
});

console.log(`Fetched ${result.successful} of ${result.total} pages`);

result.results.forEach(page => {
  if (page.success) {
    console.log(`${page.url}: ${page.markdown?.length} chars`);
  } else {
    console.log(`${page.url}: Failed - ${page.error}`);
  }
});

Web Search

Search the web and get structured results:

const result = await BuildE2E.webSearch({
  queries: ['latest AI news 2025'],
  limit: 10,
  location: 'US'
});

result.results.forEach(queryResult => {
  console.log(`Query: ${queryResult.query}`);
  queryResult.results.forEach(item => {
    console.log(`- ${item.title}`);
    console.log(`  ${item.url}`);
  });
});

Generate PDF from HTML

Generate a PDF from HTML content:

const result = await BuildE2E.generatePdf({
  html: '<html><body><h1>Invoice</h1><p>Total: $500</p></body></html>',
  title: 'invoice-123',
  pageSize: 'A4',
  printBackground: true,
  margin: { top: '20mm', right: '20mm', bottom: '20mm', left: '20mm' }
});

console.log(result.url); // Download URL for the PDF

Generate PDF from URL

Generate a PDF from any webpage:

const result = await BuildE2E.generatePdfFromUrl({
  url: 'https://example.com/report',
  title: 'report',
  pageSize: 'Letter',
  landscape: true
});

console.log(result.url); // Download URL for the PDF

Execute Code

Run code in an isolated sandbox environment:

const result = await BuildE2E.executeCode({
  code: 'print("Hello, World!")',
  language: 'python'
});

console.log(result.stdout);          // "Hello, World!\n"
console.log(result.exitCode);        // 0
console.log(result.executionTimeMs); // 95.23
console.log(result.memoryUsageMb);   // 8.45

Each execution runs in its own isolated subprocess inside a Kata micro-VM with no network access. Code is cleaned up immediately after execution.

// Multi-line code with imports
const result = await BuildE2E.executeCode({
  code: `
import json
data = {"name": "BuildE2E", "version": 1}
print(json.dumps(data, indent=2))
  `,
  language: 'python'
});

console.log(result.stdout);
// {
//   "name": "BuildE2E",
//   "version": 1
// }

Browser Sessions

Create and manage remote browser sessions for automation with Playwright or Puppeteer:

import BuildE2E from '@builde2e/sdk';
import { chromium } from 'playwright-core';

BuildE2E.setApiKey('uc-your-api-key');

// Create a browser session
const session = await BuildE2E.browser.create({
  width: 1280,
  height: 720,
  headless: false
});

// Connect with Playwright
const browser = await chromium.connectOverCDP(session.wsEndpoint);
const page = browser.contexts()[0].pages()[0];
await page.goto('https://example.com');

Check session status and cost:

const details = await BuildE2E.browser.get(session.sessionId);
console.log(details.status);    // "active"
console.log(details.totalCost); // 0.02 (visible) or 0.004 (headless)

Close a session (browser state is saved automatically):

await BuildE2E.browser.close(session.sessionId);

Resume a previously closed session with saved cookies and localStorage:

const resumed = await BuildE2E.browser.resume(session.sessionId);
const browser2 = await chromium.connectOverCDP(resumed.wsEndpoint);
// Browser state (cookies, localStorage) is restored

Domain Filtering

Filter search results by domain:

// Only include specific domains
const result = await BuildE2E.webSearch({
  queries: ['machine learning tutorials'],
  includeDomains: ['medium.com', 'towardsdatascience.com']
});

// Or exclude domains
const result2 = await BuildE2E.webSearch({
  queries: ['javascript frameworks'],
  excludeDomains: ['pinterest.com', 'quora.com']
});

LLM Summarization

Ask the API to summarize fetched content:

const result = await BuildE2E.fetch({
  url: 'https://example.com/product',
  type: 'markdown',
  summary: {
    query: 'Extract the product name, price, and key features in JSON format'
  }
});

console.log(result.content); // Summarized content

LLM Tool Definitions

The SDK includes pre-built tool definitions that you can pass directly to LLMs. Available in two formats:

Vercel AI SDK — works with generateText, streamText from the ai package
OpenAI — works with chat.completions.create from the openai package

Install the peer dependency for whichever format you need:

npm install @builde2e/sdk ai          # for Vercel AI SDK
npm install @builde2e/sdk openai      # for OpenAI

Vercel AI SDK

import BuildE2E from '@builde2e/sdk';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

BuildE2E.setApiKey('uc-your-api-key');

// Pass all tools
const { text } = await generateText({
  model: openai('gpt-4.1'),
  tools: BuildE2E.tools.aiSdk.all,
  prompt: 'Find top AI startups and analyze their pricing',
});

// Or pick specific ones
const { text: text2 } = await generateText({
  model: openai('gpt-4.1'),
  tools: {
    webSearch: BuildE2E.tools.aiSdk.webSearch,
    fetch: BuildE2E.tools.aiSdk.fetch,
  },
  prompt: 'Search for and fetch the top 3 results',
});

OpenAI

import BuildE2E from '@builde2e/sdk';
import OpenAI from 'openai';

BuildE2E.setApiKey('uc-your-api-key');
const client = new OpenAI();

// Pass all tool definitions
const response = await client.chat.completions.create({
  model: 'gpt-4.1',
  messages: [{ role: 'user', content: 'Search for AI trends' }],
  tools: BuildE2E.tools.openai.all,
});

// Handle tool calls
for (const toolCall of response.choices[0].message.tool_calls ?? []) {
  const result = await BuildE2E.tools.openai.execute(
    toolCall.function.name,
    JSON.parse(toolCall.function.arguments),
  );
  console.log(result);
}

Available Tools

| Tool | Description | |------|-------------| | webSearch | Search the web and get results with URLs, titles, descriptions | | fetch | Fetch a URL and get clean markdown or HTML content | | executeCode | Execute Python or JavaScript code in an isolated sandbox |

Configuration

Custom Base URL

For self-hosted instances or testing:

BuildE2E.setBaseUrl('https://your-instance.com/v1');

Request Timeout

Set a custom timeout (in milliseconds):

BuildE2E.setTimeout(60000); // 60 seconds

Configure Multiple Options

BuildE2E.configure({
  apiKey: 'uc-your-api-key',
  baseUrl: 'https://api.builde2e.com/api/v1',
  timeout: 120000
});

Error Handling

The SDK throws SdkError for API errors:

import BuildE2E, { SdkError } from '@builde2e/sdk';

try {
  const result = await BuildE2E.fetch({ url: 'https://example.com' });
} catch (error) {
  if (error instanceof SdkError) {
    console.error(`Error ${error.status}: ${error.message}`);
    console.error(`Code: ${error.code}`);
  }
}

Common error codes:

| Status | Code | Description | |--------|------|-------------| | 401 | UNAUTHORIZED | Invalid or missing API key | | 403 | FORBIDDEN | Access forbidden | | 429 | RATE_LIMIT_EXCEEDED | Too many requests | | 500 | INTERNAL_ERROR | Server error |

TypeScript Support

The SDK includes full TypeScript definitions:

import BuildE2E, {
  FetchOptions,
  FetchResponse,
  WebSearchOptions,
  WebSearchResponse,
  BatchFetchOptions,
  BatchFetchResponse,
  GeneratePdfOptions,
  PdfResponse,
  ExecuteCodeOptions,
  ExecuteCodeResponse,
  CreateBrowserSessionOptions,
  BrowserSession,
  BrowserSessionDetails,
} from '@builde2e/sdk';

const options: FetchOptions = {
  url: 'https://example.com',
  type: 'markdown'
};

const result: FetchResponse = await BuildE2E.fetch(options);

Zod Schemas

Every type has a corresponding Zod schema exported for runtime validation:

import {
  FetchOptionsSchema,
  FetchResponseSchema,
  WebSearchOptionsSchema,
  WebSearchResponseSchema,
  BatchFetchOptionsSchema,
  BatchFetchResponseSchema,
  ExecuteCodeOptionsSchema,
  ExecuteCodeResponseSchema,
  CreateBrowserSessionOptionsSchema,
  BrowserSessionSchema,
  BrowserSessionDetailsSchema,
  // ... and more
} from '@builde2e/sdk';

// Validate user input at runtime
const parsed = FetchOptionsSchema.parse(userInput);

API Reference

Methods

| Method | Description | |--------|-------------| | BuildE2E.setApiKey(key) | Set the API key globally | | BuildE2E.setBaseUrl(url) | Set custom base URL | | BuildE2E.setTimeout(ms) | Set request timeout | | BuildE2E.configure(config) | Configure multiple options at once | | BuildE2E.getConfig() | Get current config ({ apiKeySet, baseUrl, timeout }) | | BuildE2E.resetConfig() | Reset configuration to defaults | | BuildE2E.fetch(options) | Fetch content from a single URL | | BuildE2E.batchFetch(options) | Fetch content from multiple URLs | | BuildE2E.webSearch(options) | Search the web | | BuildE2E.generatePdf(options) | Generate PDF from HTML | | BuildE2E.generatePdfFromUrl(options) | Generate PDF from a URL | | BuildE2E.executeCode(options) | Execute code in an isolated Code Sandbox | | BuildE2E.browser.create(options) | Create a remote Browser Sandbox session | | BuildE2E.browser.get(sessionId) | Get Browser Sandbox session details (status, cost) | | BuildE2E.browser.close(sessionId) | Close a Browser Sandbox session | | BuildE2E.browser.resume(sessionId) | Resume a closed Browser Sandbox session with saved state |

SdkConfig

| Field | Type | Required | Description | |-------|------|----------|-------------| | apiKey | string | No | Your API key | | baseUrl | string | No | Custom API base URL | | timeout | number | No | Request timeout in milliseconds |

SummaryQuery

| Field | Type | Required | Description | |-------|------|----------|-------------| | query | string | Yes | Query/instruction for content summarization |

FetchOptions

| Field | Type | Required | Description | |-------|------|----------|-------------| | url | string | Yes | URL to fetch (required) | | type | "html" | "markdown" | No | Output format: html or markdown. Defaults to "markdown" | | onlyMainContent | boolean | No | Extract only main content (removes nav, ads, footers). Defaults to true | | extractMetadata | boolean | No | Whether to extract page metadata | | summary | object | No | Summary query for LLM summarization | | timeoutMs | number | No | Custom timeout in milliseconds (1000-120000) | | waitUntil | "load" | "domcontentloaded" | "networkidle" | No | Wait strategy for page load | | actions | object | object | object | object | object | object[] | No | Sequence of browser actions to execute after page load, before content extraction. When provided, lightweight HTTP fetching is skipped. | | _provider | "auto" | "exa" | "firecrawl" | "internal" | No | Scraping provider to use. Defaults to "auto" |

FetchMetadata

| Field | Type | Required | Description | |-------|------|----------|-------------| | title | string | No | | | description | string | No | | | canonicalUrl | string | No | | | finalUrl | string | No | | | contentType | string | No | | | contentLength | number | No | |

FetchResponse

| Field | Type | Required | Description | |-------|------|----------|-------------| | url | string | Yes | Original URL that was fetched | | html | string | null | No | Rendered HTML content (when type is html) | | markdown | string | null | No | Content converted to Markdown (when type is markdown) | | statusCode | number | null | Yes | HTTP status code | | success | boolean | Yes | Whether fetching was successful | | error | string | No | Error message if fetching failed | | timestamp | string | Yes | ISO timestamp when fetching completed | | loadTimeMs | number | Yes | Time taken to load and render the page in milliseconds | | metadata | object | No | Additional page metadata | | retryCount | number | Yes | Number of retry attempts made | | cost | number | No | Cost in USD for this fetch operation | | content | string | null | No | Content after summarization (when summary query provided) |

BatchFetchOptions

| Field | Type | Required | Description | |-------|------|----------|-------------| | urls | string | object[] | Yes | Array of URLs to fetch (strings or detailed request objects) | | type | "html" | "markdown" | No | Output format: html or markdown | | onlyMainContent | boolean | No | Extract only main content (removes nav, ads, footers) | | summary | object | No | Summary query for LLM summarization | | batchTimeoutMs | number | No | Global timeout for entire batch operation in milliseconds (10000-600000) | | failFast | boolean | No | Whether to stop on first error | | _provider | "auto" | "exa" | "firecrawl" | "internal" | No | Scraping provider to use. Defaults to "auto" |

BatchFetchResponse

| Field | Type | Required | Description | |-------|------|----------|-------------| | results | object[] | Yes | Array of fetch results | | total | number | Yes | Total number of URLs processed | | successful | number | Yes | Number of successful fetches | | failed | number | Yes | Number of failed fetches | | totalTimeMs | number | Yes | Total time taken for batch operation in milliseconds | | timestamp | string | Yes | Timestamp when batch operation completed | | cost | number | No | Total cost in USD for all fetch operations |

WebSearchOptions

| Field | Type | Required | Description | |-------|------|----------|-------------| | queries | string[] | Yes | Array of search queries to execute (1-20) | | limit | number | No | Number of results per query (1-100). Defaults to 10 | | location | string | No | Location for search (e.g., "IN", "US") | | includeDomains | string[] | No | Domains to include (will add site: to query) | | excludeDomains | string[] | No | Domains to exclude (will add -site: to query) | | engine | "google" | "bing" | No | Search engine to use. Forces internal SERP scraping when set. |

WebSearchResultWeb

| Field | Type | Required | Description | |-------|------|----------|-------------| | url | string | Yes | URL of the search result | | title | string | Yes | Title of the search result | | description | string | Yes | Description/snippet of the search result |

WebSearchResultItem

| Field | Type | Required | Description | |-------|------|----------|-------------| | query | string | Yes | The search query | | success | boolean | Yes | Whether the search was successful | | results | object[] | Yes | Parsed search result links | | error | string | No | Error message if failed | | loadTimeMs | number | No | Time taken in milliseconds | | cost | number | No | Cost in USD for this query |

WebSearchResponse

| Field | Type | Required | Description | |-------|------|----------|-------------| | results | object[] | Yes | Array of search results per query | | total | number | Yes | Total number of queries | | successful | number | Yes | Number of successful searches | | failed | number | Yes | Number of failed searches | | totalTimeMs | number | Yes | Total time in milliseconds | | timestamp | string | Yes | ISO timestamp | | cost | number | No | Total cost in USD |

PdfMargin

| Field | Type | Required | Description | |-------|------|----------|-------------| | top | string | No | | | right | string | No | | | bottom | string | No | | | left | string | No | |

GeneratePdfOptions

| Field | Type | Required | Description | |-------|------|----------|-------------| | html | string | Yes | Complete HTML content to convert to PDF (required) | | title | string | No | Title used for the exported filename | | pageSize | "A4" | "Letter" | "Legal" | No | Page size. Defaults to "A4" | | landscape | boolean | No | Landscape orientation. Defaults to false | | margin | object | No | Page margins (e.g., { top: "20mm", right: "20mm", bottom: "20mm", left: "20mm" }) | | printBackground | boolean | No | Print background graphics and colors. Defaults to true | | skipChartWait | boolean | No | Skip waiting for chart rendering signal. Defaults to false | | timeoutMs | number | No | Timeout in milliseconds (5000-120000). Defaults to 30000 |

GeneratePdfFromUrlOptions

| Field | Type | Required | Description | |-------|------|----------|-------------| | url | string | Yes | URL to navigate to and convert to PDF (required) | | title | string | No | Title used for the exported filename | | pageSize | "A4" | "Letter" | "Legal" | No | Page size. Defaults to "A4" | | landscape | boolean | No | Landscape orientation. Defaults to false | | margin | object | No | Page margins | | printBackground | boolean | No | Print background graphics and colors. Defaults to true | | timeoutMs | number | No | Timeout in milliseconds (5000-120000). Defaults to 30000 |

PdfResponse

| Field | Type | Required | Description | |-------|------|----------|-------------| | success | boolean | Yes | Whether PDF generation succeeded | | url | string | No | Public URL of the generated PDF | | filename | string | No | Generated filename | | blobName | string | No | Blob storage path | | error | string | No | Error message on failure | | durationMs | number | Yes | Total time taken in milliseconds |

ExecuteCodeOptions

| Field | Type | Required | Description | |-------|------|----------|-------------| | code | string | Yes | Code to execute (required) | | language | "python" | "javascript" | Yes | Language runtime (required) |

ExecuteCodeResponse

| Field | Type | Required | Description | |-------|------|----------|-------------| | stdout | string | Yes | Standard output from the executed code | | stderr | string | Yes | Standard error from the executed code | | exitCode | number | Yes | Process exit code (0 = success, 124 = timeout) | | executionTimeMs | number | Yes | Execution time in milliseconds | | timedOut | boolean | Yes | Whether execution was killed due to timeout | | memoryUsageMb | number | No | Peak memory usage in megabytes | | error | string | No | Error message if execution infrastructure failed | | cost | number | No | Cost in USD for this execution |

ErrorResponse

| Field | Type | Required | Description | |-------|------|----------|-------------| | error | object | Yes | | | statusCode | number | No | |

CreateBrowserSessionOptions

| Field | Type | Required | Description | |-------|------|----------|-------------| | width | number | No | Browser viewport width (800-3840). Defaults to 1280 | | height | number | No | Browser viewport height (600-2160). Defaults to 720 | | headless | boolean | No | Run browser in headless mode. Defaults to true | | browser | "camoufox" | "lightpanda" | No | Browser engine. camoufox: full Firefox with VNC support. lightpanda: lightweight CDP headless browser. Defaults to camoufox |

BrowserSession

| Field | Type | Required | Description | |-------|------|----------|-------------| | sessionId | string | Yes | Unique session identifier | | wsEndpoint | string | Yes | WebSocket URL for connecting with Playwright/Puppeteer | | liveViewUrl | string | null | Yes | Live view URL for watching the browser in real time (if available) | | browser | "camoufox" | "lightpanda" | No | Browser engine used for this session | | affinityCookie | string | No | Affinity cookie for sticky session routing (format: SCRAPER_AFFINITY=xxx) - extracted from response headers | | createdAt | string | Yes | Session creation timestamp (ISO string) | | width | number | Yes | Browser viewport width | | height | number | Yes | Browser viewport height | | cost | number | No | Cost in USD for creating this session |

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@builde2e/sdk

Installation

Quick Start

Usage

Setting API Key

Fetching a Single URL

Batch Fetching

Web Search

Generate PDF from HTML

Generate PDF from URL

Execute Code

Browser Sessions

Domain Filtering

LLM Summarization

LLM Tool Definitions

Vercel AI SDK

OpenAI

Available Tools

Configuration

Custom Base URL

Request Timeout

Configure Multiple Options

Error Handling

TypeScript Support

Zod Schemas

API Reference

Methods

SdkConfig

SummaryQuery

FetchOptions

FetchMetadata

FetchResponse

BatchFetchOptions

BatchFetchResponse

WebSearchOptions

WebSearchResultWeb

WebSearchResultItem

WebSearchResponse

PdfMargin

GeneratePdfOptions

GeneratePdfFromUrlOptions

PdfResponse

ExecuteCodeOptions

ExecuteCodeResponse

ErrorResponse

CreateBrowserSessionOptions

BrowserSession

License