Node.js SDK | BuildE2E

SDKsNode.js

Node.js SDK

The official Node.js SDK for BuildE2E. Scrape, search, extract, crawl, screenshot, generate PDFs, and run browser sessions with just a few lines of code.

Installation

Install the SDK using npm, yarn, or pnpm:

bash

npm install @builde2e/sdk

Or with yarn:

bash

yarn add @builde2e/sdk

Quick Start

Set your API key globally and start making requests:

javascript

import BuildE2E from '@builde2e/sdk';

// Set API key globally (no 'new' keyword needed)
BuildE2E.setApiKey('uc-YOUR-API-KEY');

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

console.log(result.markdown);

Keep your API key secure

Never expose your API key in client-side code. Use environment variables to store your API key securely.

Named Imports

You can also use named imports if you prefer:

javascript

import {
  setApiKey, fetch, batchFetch,
  sequence, map, extract, crawl, screenshot,
  generatePdf, executeCode
} from '@builde2e/sdk';

setApiKey('uc-YOUR-API-KEY');

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

API Methods

All methods are available on the default BuildE2E export or as named imports. Click a method to see its full documentation.

Method	Returns	Description
`fetch(options)`	Promise<FetchResponse>	Fetch a single URL
`batchFetch(options)`	Promise<BatchFetchResponse>	Fetch multiple URLs in one request
`sequence(options)`	Promise<SequenceScrapeResponse>	Multi-step browser workflow
`map(options)`	Promise<MapResponse>	Discover URLs from a site
`extract(options)`	Promise<ExtractResponse>	Extract structured data with LLM
`crawl(options)`	Promise<CrawlResponse>	Recursively crawl a website
`screenshot(options)`	Promise<ScreenshotResponse>	Capture page screenshot
`generatePdf(options)`	Promise<PdfResponse>	Generate PDF from HTML
`generatePdfFromUrl(options)`	Promise<PdfResponse>	Generate PDF from URL
`executeCode(options)`	Promise<ExecuteCodeResponse>	Run code in sandbox
`browser.create(options)`	Promise<BrowserSession>	Create browser session
`browser.get(sessionId)`	Promise<BrowserSessionDetails>	Get session details
`browser.close(sessionId)`	Promise<void>	Close browser session
`browser.resume(sessionId)`	Promise<BrowserSession>	Resume closed session
`asyncFetch(options)`	Promise<AsyncJobStartResponse>	Start async fetch job
`asyncBatchFetch(options)`	Promise<AsyncJobStartResponse>	Start async batch fetch job
`asyncSequence(options)`	Promise<AsyncJobStartResponse>	Start async sequence job
`asyncSequenceBatch(options)`	Promise<AsyncJobStartResponse>	Start async sequence batch job
`asyncSearchBatch(options)`	Promise<AsyncJobStartResponse>	Start async search batch job
`listJobs(options?)`	Promise<AsyncJobListResponse>	List async jobs
`getJobStatus(jobId)`	Promise<AsyncJobStatusResponse>	Get job status & results
`cancelJob(jobId)`	Promise<AsyncJobCancelResponse>	Cancel a running job
`waitForJob(jobId)`	Promise<AsyncJobStatusResponse>	Poll until job completes
`setApiKey(key)`	void	Set the API key globally
`setBaseUrl(url)`	void	Set custom base URL
`setTimeout(ms)`	void	Set request timeout
`configure(config)`	void	Configure multiple options
`getConfig()`	object	Get current configuration
`resetConfig()`	void	Reset to defaults

Configuration

Configure the SDK before making requests. All configuration is global — set once and used by all methods.

javascript

import BuildE2E from '@builde2e/sdk';

// Set API key (required)
BuildE2E.setApiKey('uc-YOUR-API-KEY');

// Or configure everything at once
BuildE2E.configure({
  apiKey: 'uc-YOUR-API-KEY',
  baseUrl: 'https://api.builde2e.com/api/v1',
  timeout: 60000
});

// Check current config
const config = BuildE2E.getConfig();
console.log(config);
// { apiKeySet: true, baseUrl: '...', timeout: 60000 }

// Reset to defaults
BuildE2E.resetConfig();

Method	Type	Description
`setApiKey(key)`	void	Set the API key globally (required before making requests)
`setBaseUrl(url)`	void	Set custom base URL (for self-hosted instances)
`setTimeout(ms)`	void	Set request timeout in milliseconds (minimum 1000)
`configure(config)`	void	Configure multiple options at once (apiKey, baseUrl, timeout)
`getConfig()`	object	Get current config (apiKeySet, baseUrl, timeout)
`resetConfig()`	void	Reset all configuration to defaults

Error Handling

The SDK throws SdkError for API errors. It extends the native Error class with additional fields.

typescript

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

BuildE2E.setApiKey('uc-YOUR-API-KEY');

try {
  const result = await BuildE2E.fetch({
    url: 'https://example.com'
  });
  console.log(result.markdown);
} catch (error) {
  if (error instanceof SdkError) {
    console.error(`HTTP ${error.status}: ${error.message}`);
    console.error(`Code: ${error.code}`);
    // error.status  — HTTP status code (e.g., 401, 429, 500)
    // error.code    — Error code string (e.g., 'UNAUTHORIZED')
    // error.message — Human-readable error description
  }
}

Property	Type	Description
`message`	string	Human-readable error description
`status`	number	HTTP status code (401, 429, 500, etc.)
`code`	string	Machine-readable error code

TypeScript Types

The SDK includes full TypeScript definitions. Import types directly from the package.

typescript

import BuildE2E, {
  FetchOptions,
  FetchResponse,
  FetchAction,
  WebSearchOptions,
  WebSearchResponse,
  SequenceScrapeOptions,
  MapOptions,
  ExtractOptions,
  CrawlOptions,
  ScreenshotOptions,
  GeneratePdfOptions,
  ExecuteCodeOptions,
  CreateBrowserSessionOptions,
  SdkError,
  SdkConfig
} from '@builde2e/sdk';

// Full type safety
async function fetchWithTypes(): Promise<FetchResponse> {
  const options: FetchOptions = {
    url: 'https://example.com',
    type: 'markdown',
    extractMetadata: true
  };
  return BuildE2E.fetch(options);
}

Available Types

Export	Kind	Description
`FetchOptions`	type	Options for fetch()
`FetchResponse`	type	Response from fetch()
`FetchAction`	type	Browser action definition
`BatchFetchOptions`	type	Options for batchFetch()
`BatchFetchResponse`	type	Response from batchFetch()
`SequenceScrapeOptions`	type	Options for sequence()
`SequenceScrapeResponse`	type	Response from sequence()
`MapOptions`	type	Options for map()
`MapResponse`	type	Response from map()
`ExtractOptions`	type	Options for extract()
`ExtractResponse`	type	Response from extract()
`CrawlOptions`	type	Options for crawl()
`CrawlResponse`	type	Response from crawl()
`ScreenshotOptions`	type	Options for screenshot()
`ScreenshotResponse`	type	Response from screenshot()
`GeneratePdfOptions`	type	Options for generatePdf()
`GeneratePdfFromUrlOptions`	type	Options for generatePdfFromUrl()
`ExecuteCodeOptions`	type	Options for executeCode()
`ExecuteCodeResponse`	type	Response from executeCode()
`CreateBrowserSessionOptions`	type	Options for browser.create()
`SdkError`	class	Error class thrown on API failures
`SdkConfig`	type	Configuration object type

Constants

Exported constants for pricing, locations, and country data.

javascript

import { COST_MODEL } from '@builde2e/sdk/cost';
import { SEARCH_LOCATIONS, COUNTRY_CODE_TO_NAME } from '@builde2e/sdk';

// Calculate cost for a batch fetch
const urls = 10;
const cost = urls * COST_MODEL.scrape.perUrl.our;
console.log(`Estimated cost: $${cost.toFixed(3)}`);

// List all supported search locations
SEARCH_LOCATIONS.forEach(loc => {
  console.log(`${loc.flag} ${loc.label} (${loc.value})`);
});

// Look up country name
console.log(COUNTRY_CODE_TO_NAME['US']); // "United States"

Export	Type	Description
`COST_MODEL`	object	Pricing model with per-operation costs (from @builde2e/sdk/cost)
`SEARCH_LOCATIONS`	SearchLocation[]	190+ countries with codes, flags, languages, and domains
`COUNTRY_CODE_TO_NAME`	Record<string, string>	Map of country codes to full names
`COUNTRY_TO_LANGUAGE`	Record<string, string>	Map of country codes to language codes

Location Utilities

Helper functions for working with country codes and domains.

javascript

import {
  countryCodeToFlag,
  countryToDomain,
  domainToCountry
} from '@builde2e/sdk';

countryCodeToFlag('US');                    // "🇺🇸"
countryCodeToFlag('IN');                    // "🇮🇳"

countryToDomain('IN', 'google');            // "google.co.in"
countryToDomain('GB', 'amazon');            // "amazon.co.uk"

domainToCountry('google.co.uk', 'google');  // "GB"
domainToCountry('amazon.de', 'amazon');     // "DE"

Function	Returns	Description
`countryCodeToFlag(code)`	string	Convert country code to flag emoji (e.g., "US" → "🇺🇸")
`countryToDomain(country, brand)`	string \| undefined	Get domain for a country and brand (e.g., "IN", "google" → "google.co.in")
`domainToCountry(domain, brand)`	string \| undefined	Get country code from a domain (e.g., "google.co.uk", "google" → "GB")