Node.js SDK

The official TypeScript and JavaScript SDK supports Node.js 20 and newer. Install it with npm:

npm install @isentro/runharvester-sdk

Submit a Data API requestCopy Anchor Link

Use a Data API key for scraping. Set RUNHARVESTER_API_KEY on your server, then submit a request:

import { randomUUID } from "node:crypto";
import { RunHarvesterClient } from "@isentro/runharvester-sdk";

const apiKey = process.env.RUNHARVESTER_API_KEY;
if (!apiKey) throw new Error("Set RUNHARVESTER_API_KEY");

const client = new RunHarvesterClient({
  baseUrl: "https://api.runharvester.com",
  auth: { type: "apiKey", token: apiKey },
});

const idempotencyKey = process.env.RUNHARVESTER_IDEMPOTENCY_KEY ?? randomUUID();
console.log("Idempotency-Key:", idempotencyKey);

const request = await client.api.postDataRequests({
  headers: { "Idempotency-Key": idempotencyKey },
  body: { url: "https://example.com", mode: "auto" },
});
console.log("Request ID:", request.id);

This submits work; it does not wait for a result. Poll client.api.getDataRequestsById({ path: { id: request.id } }) with a deadline, stop on failed or cancelled, and call client.api.getDataRequestsByIdResult({ path: { id: request.id } }) only after completed. The request lifecycle explains each state, and the JavaScript guide provides a complete polling example using fetch.

Keep the printed idempotency key and original body when retrying an uncertain submission. A new UUID creates new work.

Access your recipes with a user sessionCopy Anchor Link

Client/account routes use your verified account JWT. This is a different credential from the Data API key. Keep the token on a trusted server and out of browser bundles.

import { RunHarvesterClient } from "@isentro/runharvester-sdk";

const client = new RunHarvesterClient({
  baseUrl: "https://api.runharvester.com",
  auth: {
    type: "bearer",
    token: process.env.RUNHARVESTER_USER_JWT!,
  },
});

const page = await client.api.getClientRecipes({
  query: { limit: 20, offset: 0 },
});

for (const recipe of page.items) {
  console.log(recipe.id, recipe.name, recipe.status, recipe.sample_url);
  console.log("Updated:", recipe.updated_at);

  if (recipe.active_version) {
    console.log("Version:", recipe.active_version.version);
    console.log("Fields:", recipe.active_version.fields);
    console.log("Output schema:", recipe.active_version.output_schema);
  }
}

getClientRecipes returns only recipes owned by the authenticated user. The response is paginated with total, limit, offset, and has_more. Each item includes its active version and output schema; active_version is null when the recipe has no active version. The top-level fields value is the active version's simple field schema, or null when the output schema needs the advanced editor.

The SDK exports OpenAPI-generated operation functions and types from its package root. Non-2xx responses throw RunHarvesterApiError, which exposes the HTTP status, response body, and headers.