JavaScript SDK

@vakra-dev/reader-js is the official TypeScript/JavaScript SDK for the Reader API. It wraps the HTTP contract, parses the response envelope into a discriminated result type, polls async jobs to completion, throws typed errors, and retries transient failures with exponential backoff.

Installation

npm install @vakra-dev/reader-js

Current version: 0.2.0. Works in Node 18+, Deno, Bun, Cloudflare Workers, and any modern browser.

Quick start

import { ReaderClient } from "@vakra-dev/reader-js";

const reader = new ReaderClient({ apiKey: process.env.READER_KEY! });

const result = await reader.read({ url: "https://example.com" });
if (result.kind === "scrape") {
  console.log(result.data.markdown);
  console.log("scraped in", result.data.metadata.duration, "ms");
}

Do not ship your API key in browser code. The SDK works in the browser, but exposing apiKey client-side means anyone can read and reuse it. Proxy requests through your own backend that holds the key server-side.

Configuration

const reader = new ReaderClient({
  apiKey: "rdr_your_key",              // required
  baseUrl: "https://api.reader.dev",   // optional, override for self-hosted
  timeout: 60_000,                     // per-request timeout in ms (default 60s)
  maxRetries: 2,                       // retries on transient failures (default 2)
});

Scraping

Single URL, synchronous

Single-URL requests return immediately with { kind: "scrape", data: ScrapeResult }.

const result = await reader.read({
  url: "https://example.com",
  formats: ["markdown"],
  onlyMainContent: true,
});

if (result.kind === "scrape") {
  console.log(result.data.url);                     // canonical URL after redirects
  console.log(result.data.markdown);                // clean markdown
  console.log(result.data.metadata.title);          // page title
  console.log(result.data.metadata.statusCode);     // 200
  console.log(result.data.metadata.duration);       // ms
  console.log(result.data.metadata.cached);         // true if served from cache
  console.log(result.data.metadata.proxyMode);      // "standard" | "premium"
}

Screenshots

Request a screenshot alongside content:

const result = await reader.read({
  url: "https://example.com",
  formats: ["markdown", "screenshot"],
});

if (result.kind === "scrape" && result.data.screenshot) {
  // screenshot is a base64-encoded PNG
  const buffer = Buffer.from(result.data.screenshot, "base64");
  fs.writeFileSync("screenshot.png", buffer);
}

Multiple URLs (batch)

Passing urls creates an async job. The SDK auto-polls until the job terminates and returns { kind: "job", data: Job } with all results collected across pagination.

const result = await reader.read({
  urls: [
    "https://example.com/page-1",
    "https://example.com/page-2",
    "https://example.com/page-3",
  ],
});

if (result.kind === "job") {
  console.log(`completed ${result.data.completed} / ${result.data.total}`);
  for (const page of result.data.results) {
    if (page.error) {
      console.error(`${page.url}: ${page.error}`);
    } else {
      console.log(page.url, page.markdown?.length, "chars");
    }
  }
}

Crawl

Same shape as batch, but with maxDepth or maxPages:

const result = await reader.read({
  url: "https://docs.example.com",
  maxDepth: 3,
  maxPages: 100,
});

Proxy mode

Control how aggressively Reader bypasses bot walls with proxyMode:

// Default: standard. Fast and affordable, works for most sites
await reader.read({ url });

// Explicit standard: force the cheaper tier (error if blocked)
await reader.read({ url, proxyMode: "standard" });

// Explicit premium: residential proxies, bypasses bot walls (3x credits)
await reader.read({ url, proxyMode: "premium" });

See Proxy modes for the full picture.

Job management

The SDK’s read() method auto-polls batches and crawls, so most callers never need to touch job APIs directly. When you do, these methods are available:

// Fetch a single page of a job's results
const { job, hasMore, next } = await reader.getJob(jobId, { skip: 0, limit: 20 });

// Collect every page automatically
const allPages = await reader.getAllJobResults(jobId);

// Poll a job by ID until it terminates (collects all results on completion)
const job = await reader.waitForJob(jobId, {
  pollInterval: 2000,
  timeout: 300_000,
});

// Cancel a queued or processing job
await reader.cancelJob(jobId);

// Retry failed URLs in a completed job
const retryInfo = await reader.retryJob(jobId);
console.log(`retrying ${retryInfo.retrying} failed URLs`);

Streaming

For real-time progress updates on a job, use reader.stream(jobId), an async generator that yields events as the job makes progress.

for await (const event of reader.stream(jobId)) {
  switch (event.type) {
    case "progress":
      console.log(`${event.completed} / ${event.total}`);
      break;
    case "page":
      console.log("page done:", event.data.url);
      break;
    case "error":
      console.error("page failed:", event.url, event.error);
      break;
    case "done":
      console.log("job finished:", event.status);
      return;
  }
}

The generator closes automatically when the job terminates.

Credits

const credits = await reader.getCredits();
console.log(`${credits.balance} / ${credits.limit}, tier: ${credits.tier}`);
console.log(`resets at: ${credits.resetAt}`);

if (credits.balance < 100) {
  // Warn, pause workers, upgrade tier, etc.
}

Error handling

Every error response from the API is parsed into a specific ReaderApiError subclass. Branch on instanceof rather than HTTP status codes.

import {
  ReaderApiError,
  InvalidRequestError,
  UnauthenticatedError,
  InsufficientCreditsError,
  UrlBlockedError,
  NotFoundError,
  ConflictError,
  RateLimitedError,
  ConcurrencyLimitedError,
  InternalServerError,
  UpstreamUnavailableError,
  ScrapeTimeoutError,
} from "@vakra-dev/reader-js";

try {
  const result = await reader.read({ url });
  // ...
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    console.error(`Need ${err.required} credits, have ${err.available}`);
    console.error(`Resets at ${err.resetAt}`);
  } else if (err instanceof RateLimitedError) {
    console.error(`Rate limited. Retry after ${err.retryAfterSeconds}s`);
  } else if (err instanceof UrlBlockedError) {
    console.error(`URL blocked: ${err.reason}`);
  } else if (err instanceof ScrapeTimeoutError) {
    console.error(`Scrape exceeded ${err.timeoutMs}ms`);
  } else if (err instanceof ReaderApiError) {
    // Catch-all for known API errors
    console.error(`[${err.code}] ${err.message} (see ${err.docsUrl})`);
    console.error(`Request ID: ${err.requestId}`);
  } else {
    throw err;
  }
}

Every error has:

code: one of 11 stable codes (e.g. "insufficient_credits", "rate_limited")
message: human-readable description
httpStatus: the HTTP status code
details: typed payload specific to the error (e.g. required/available for insufficient_credits)
docsUrl: deep link to the error’s documentation
requestId: the x-request-id header from the response, for support tickets

The full catalog is at Errors.

Automatic retries

The SDK retries these codes automatically with exponential backoff before throwing: rate_limited (honors Retry-After), concurrency_limited, internal_error, upstream_unavailable, scrape_timeout. All other codes throw immediately.

Webhooks per request

Every read() call can include an inline webhook config that fires on job lifecycle events, useful for fire-and-forget batches.

await reader.read({
  urls: manyUrls,
  webhook: {
    url: "https://your-app.example.com/hooks/reader",
    events: ["job.completed", "job.failed"],
    secret: process.env.READER_WEBHOOK_SECRET,
  },
});

See Webhooks for the full delivery contract and signature verification.

Types

All public types are re-exported from the package root:

import type {
  ReaderClientConfig,
  ReadParams,
  ReadResult,      // { kind: "scrape", data: ScrapeResult } | { kind: "job", data: Job }
  ScrapeResult,
  ScrapeMetadata,
  Job,
  JobStatus,
  JobMode,
  Page,
  ProxyMode,       // "standard" | "premium"
  Pagination,
  Credits,
  UsageEntry,
  StreamEvent,
} from "@vakra-dev/reader-js";

Browser Sessions

Create stealthed browser sessions for Playwright/Puppeteer automation:

import { ReaderClient } from "@vakra-dev/reader-js";
import { chromium } from "playwright-core";

const reader = new ReaderClient({ apiKey: "rdr_..." });

// Create a session
const session = await reader.sessions.create();
console.log(session.wsEndpoint);

// Connect Playwright
const browser = await chromium.connectOverCDP(session.wsEndpoint);
const page = await (await browser.newContext()).newPage();
await page.goto("https://example.com");
console.log(await page.title());

// Cleanup
await browser.close();
await reader.sessions.stop(session.sessionId);

Sessions API

Method	Description
`reader.sessions.create(params?)`	Create a session, returns `SessionInfo` with `wsEndpoint`
`reader.sessions.get(sessionId)`	Get session status
`reader.sessions.stop(sessionId)`	Stop a session, returns billing summary
`reader.sessions.list()`	List active sessions

Session Types

import type {
  SessionInfo,
  CreateSessionParams,
  StopSessionResult,
  SessionStatus,
} from "@vakra-dev/reader-js";

Python SDK: same features, Pythonic API
Browser Sessions: concept overview
Errors: full error code catalog
Proxy modes: when to override the default
API reference: the raw HTTP contract

SDKs

JavaScript SDK

Installation

Quick start

Configuration

Scraping

Single URL, synchronous

Screenshots

Multiple URLs (batch)

Crawl

Proxy mode

Job management

Streaming

Credits

Error handling

Automatic retries

Webhooks per request

Types

Browser Sessions

Sessions API

Session Types

Next

​Installation

​Quick start

​Configuration

​Scraping

​Single URL, synchronous

​Screenshots

​Multiple URLs (batch)

​Crawl

​Proxy mode

​Job management

​Streaming

​Credits

​Error handling

​Automatic retries

​Webhooks per request

​Types

​Browser Sessions

​Sessions API

​Session Types

​Next

Installation

Quick start

Configuration

Scraping

Single URL, synchronous

Screenshots

Multiple URLs (batch)

Crawl

Proxy mode

Job management

Streaming

Credits

Error handling

Automatic retries

Webhooks per request

Types

Browser Sessions

Sessions API

Session Types

Next