Node.js / TypeScript SDK

@scrapering/sdk is a lightweight TypeScript client for all Scrapering parsing endpoints. Submit tasks, poll for results, or get the final data in a single awaited call — with full static typing for every parser. Available on npm.

Why use the SDK

• One dependency. The only runtime dependency is zod. No HTTP clients, no framework, no polyfills — runs on the native fetch in Node 18+ and modern browsers.
• Fully typed. Request and response types are derived from the same Zod schemas the API validates against, so every parser's contract is always in sync. You get autocomplete and compile-time errors, not guesses.
• Validates before it sends. Outgoing payloads are validated locally with the API's own schemas, so malformed requests fail immediately with a clear error instead of wasting a round-trip and credits.
• Two flows, one client. Use createTask + getResult for manual polling, or parse for a single submit-and-wait call that handles polling automatically.
• Tiny. 12.4 kB packed, 52.1 kB unpacked, ESM-only, tree-shakeable.

Install

npm install @scrapering/sdk

Requires Node 18+ (or any runtime with a global fetch).

Initialize the client

import { ScraperingClient } from '@scrapering/sdk'

const client = new ScraperingClient({
  apiKey: process.env.SCRAPERING_API_KEY!, // required
  // baseUrl: 'https://app.scrapering.com', // optional, this is the default
  // validateRequests: false,               // optional, skip local Zod validation
})

Supported parsers

Two flows

Submit-and-wait (parse)

The simplest option. parse submits the task, polls until it is ready, and returns the parsed data directly. Use this when you want results with minimal code.

// URL scraper
const data = await client.parsers.url.parse({
  url: 'https://example.com',
  output: { markdown: true },
})
// data.contentMarkdown — the page as Markdown

// Google SERP
const serp = await client.parsers.googleSerp.parse({
  q: 'buy pizza',
  count: 10,
  gl: 'US',
  hl: 'en',
})
// serp.data.organic — ranked results

// Yandex SERP
const yandex = await client.parsers.yandexSerp.parse({
  q: 'buy pizza',
  count: 10,
  region: 213, // Moscow
})

// Google News (search feed)
const news = await client.parsers.googleNews.parse({
  feed: 'search',
  q: 'AI news',
  gl: 'US',
  hl: 'en',
  timeframe: '1d',
  limit: 10,
})

// Galaxy Store reviews
const reviews = await client.parsers.galaxyStoreReviews.parse({
  url: 'https://galaxystore.samsung.com/detail/com.netflix.mediaclient',
})
// reviews.data — array of { date, text, user, stars }

If you need the full response envelope (requestId, respondedAt, etc.) alongside the data, use parseFull:

const full = await client.parsers.url.parseFull({
  url: 'https://example.com',
  output: { markdown: true },
})
// full.status === 'ready'
// full.requestId, full.respondedAt, full.data

Manual polling (submit + getResult)

Submit a task and get back its id, then poll the result endpoint yourself. Useful when you want to fan out many tasks at once, or need fine-grained control over retries and timing.

// 1. Submit
const task = await client.parsers.googleSerp.submit({
  q: 'buy pizza',
  count: 10,
  gl: 'US',
})
// task.id — use this to poll

// 2. Poll until ready
let result
do {
  await new Promise((r) => setTimeout(r, 2000))
  result = await client.parsers.googleSerp.getResult(task.id)
} while (result.status === 'parsing')

// result.status === 'ready'
// result.data.organic — ranked results

You can also use the generic methods with the parser slug directly:

const task = await client.createTask('serp-google', { q: 'buy pizza', count: 10 })
const result = await client.getResult('serp-google', task.id)

Polling options

parse and parseFull accept a third argument to control polling behaviour:

const data = await client.parsers.url.parse(
  { url: 'https://example.com' },
  {
    intervalMs: 2000,           // how often to poll (default: 2000 ms)
    timeoutMs: 120000,          // give up after this many ms (default: 120 000 ms)
    maxAttempts: 60,            // alternative to timeoutMs
    signal: controller.signal,  // AbortSignal to cancel mid-poll
  }
)

If the task does not finish within the timeout, a ScraperingTimeoutError is thrown. Aborting the signal rejects the promise immediately.

Error handling

All SDK errors extend ScraperingError. Each failure mode has its own class:

import {
  ScraperingApiError,        // non-2xx API response
  ScraperingNetworkError,    // fetch / network failure
  ScraperingTimeoutError,    // polling timed out
  ScraperingValidationError, // outgoing payload failed local validation
} from '@scrapering/sdk'

try {
  await client.parsers.url.parse({ url: 'https://example.com' })
} catch (err) {
  if (err instanceof ScraperingApiError) {
    console.log(err.status)           // HTTP status code
    console.log(err.endpoint)         // route path that failed
    console.log(err.requestId)        // task id if present in the response
    console.log(err.isMissingScope()) // true for 403 — key lacks the required scope
    console.log(err.isUnknownParser()) // true for 404 — unrecognised parser slug
  } else if (err instanceof ScraperingNetworkError) {
    // transient network failure — safe to retry
  } else if (err instanceof ScraperingTimeoutError) {
    console.log(err.requestId) // id of the task that timed out
  } else if (err instanceof ScraperingValidationError) {
    console.log(err.issues)    // Zod issue list with field-level details
  }
}

Runtime validation

By default the SDK validates every outgoing payload before sending it. This surfaces malformed requests as ScraperingValidationError locally, before any network call is made. To skip validation in a hot path you fully trust:

new ScraperingClient({ apiKey, validateRequests: false })

The Zod schemas are also available as a named export if you want to reuse them in your own code:

import { urlDtoSchema, PARSER_DTO_SCHEMAS } from '@scrapering/sdk/schemas'

const result = urlDtoSchema.safeParse(payload)

Next steps

• Authentication — create an API key and assign the required scopes
• URL Scraper — full parameter reference for the url parser
• Google SERP Scraper — full parameter reference for serp-google
• Google News Scraper — full parameter reference for google-news
• Galaxy Store Reviews — full parameter reference for galaxy-store-reviews
• Pricing — each SDK call costs the same as the equivalent REST request