●Node.js SDK

docs/SDKs/Node.js SDK

Node.js SDK

Official TypeScript/JavaScript SDK.

Node.js SDK

The official KnowledgeSDK TypeScript/JavaScript SDK. Built with full type safety, async/await support, automatic retries, and intelligent rate limit handling.

Installation

terminal>_bash

npm install @knowledgesdk/node

Or with your preferred package manager:

Quick start

typescript snippetTStypescript

import { KnowledgeSDK } from "@knowledgesdk/node";

const ks = new KnowledgeSDK("sk_ks_your_api_key");

// Extract structured knowledge from any website
const extraction = await ks.extract.run("https://competitor.com");
console.log(extraction.business.businessName);
console.log(extraction.knowledgeItems);

// Search across your extracted knowledge
const results = await ks.search.run("pricing plans");
console.log(results.hits);

Configuration

The KnowledgeSDK constructor accepts an optional configuration object:

typescript snippetTStypescript

const ks = new KnowledgeSDK("sk_ks_your_api_key", {
  baseUrl: "https://api.knowledgesdk.com",  // Default
  maxRetries: 5,                            // Default
  timeout: 30000,                           // Default (30 seconds)
  apiVersion: "v1",                         // Default
});

Option	Type	Default	Description
`baseUrl`	`string`	`https://api.knowledgesdk.com`	Base URL for the API
`maxRetries`	`number`	`5`	Maximum number of retries for failed requests
`timeout`	`number`	`30000`	Request timeout in milliseconds
`apiVersion`	`string`	`v1`	API version string

Methods

`ks.extract.run(url, options?)`

Run a synchronous extraction pipeline. Scrapes the site, classifies the business, and returns structured knowledge items.

typescript snippetTStypescript

const result = await ks.extract.run("https://example.com", {
  maxPages: 20,  // Optional: limit pages to scrape
});

// result.business — BusinessProfile with classification
// result.knowledgeItems — Array of structured knowledge items
// result.pagesScraped — Number of pages processed
// result.urlsDiscovered — Number of URLs discovered

`ks.extract.runAsync(url, options?)`

Start an asynchronous extraction and receive a job ID. Use this for long-running extractions or when you want to receive results via a webhook callback.

typescript snippetTStypescript

const job = await ks.extract.runAsync("https://example.com", {
  maxPages: 50,
  callbackUrl: "https://myapp.com/webhooks/knowledgesdk",
});

console.log(job.jobId);   // "job_abc123"
console.log(job.status);  // "PENDING"

`ks.extract.run(url)` (single page)

Scrape a single URL and return clean markdown with metadata.

typescript snippetTStypescript

const page = await ks.extract.run("https://docs.example.com/getting-started");

console.log(page.markdown);     // Clean markdown content
console.log(page.title);        // Page title
console.log(page.description);  // Meta description
console.log(page.links);        // Extracted links

`ks.business.run(url)`

Classify a website's business type, industry, and competitive positioning.

typescript snippetTStypescript

const biz = await ks.business.run("https://stripe.com");

console.log(biz.businessName);     // "Stripe"
console.log(biz.businessType);     // "B2B_SAAS"
console.log(biz.industrySector);   // "FINANCE"
console.log(biz.painPoints);       // ["Complex payment integration...", ...]
console.log(biz.confidenceScore);  // 95

`ks.screenshot.run(url)`

Capture a full-page screenshot as a base64-encoded PNG.

typescript snippetTStypescript

import fs from "fs";

const shot = await ks.screenshot.run("https://example.com");

const buffer = Buffer.from(shot.screenshot, "base64");
fs.writeFileSync("screenshot.png", buffer);

`ks.sitemap.run(url)`

Discover all URLs on a website via its sitemap.

typescript snippetTStypescript

const sitemap = await ks.sitemap.run("https://example.com");

console.log(`Found ${sitemap.count} URLs`);
sitemap.urls.forEach((url) => console.log(url));

`ks.search.run(query, options?)`

Search across your indexed knowledge items using natural language.

typescript snippetTStypescript

const results = await ks.search.run("pricing plans", {
  limit: 10,  // Optional: max results to return
});

results.hits.forEach((hit) => {
  console.log(`${hit.title} (score: ${hit.score})`);
  console.log(hit.content);
});

`ks.webhooks.create(options)`

Register a webhook endpoint to receive real-time notifications.

typescript snippetTStypescript

const webhook = await ks.webhooks.create({
  url: "https://myapp.com/webhooks/knowledgesdk",
  events: ["EXTRACTION_COMPLETED", "EXTRACTION_FAILED"],
  displayName: "Production webhook",
});

console.log(webhook.id);     // Webhook ID
console.log(webhook.status); // "ACTIVE"

`ks.webhooks.list()`

List all registered webhooks.

typescript snippetTStypescript

const webhooks = await ks.webhooks.list();
webhooks.forEach((wh) => console.log(`${wh.displayName}: ${wh.status}`));

`ks.webhooks.delete(webhookId)`

Delete a webhook by ID.

typescript snippetTStypescript

await ks.webhooks.delete("wh_abc123");

`ks.webhooks.test(webhookId)`

Send a test event to verify a webhook is working.

typescript snippetTStypescript

await ks.webhooks.test("wh_abc123");

`ks.jobs.get(jobId)`

Retrieve the current status and result of an async job.

typescript snippetTStypescript

const job = await ks.jobs.get("job_abc123");

console.log(job.status);  // "PENDING" | "RUNNING" | "COMPLETED" | "FAILED"
if (job.status === "COMPLETED") {
  console.log(job.result);
}

`ks.jobs.poll(jobId, options?)`

Poll an async job until it completes or times out.

typescript snippetTStypescript

const completed = await ks.jobs.poll("job_abc123", {
  intervalMs: 5000,   // Poll every 5 seconds
  timeoutMs: 300000,  // Timeout after 5 minutes
});

console.log(completed.result);

Error handling

The SDK throws typed errors that you can catch and handle:

typescript snippetTStypescript

import {
  KnowledgeSDK,
  AuthenticationError,
  RateLimitError,
  APIError,
} from "@knowledgesdk/node";

try {
  const result = await ks.extract.run("https://example.com");
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Invalid API key");
  } else if (error instanceof RateLimitError) {
    console.error("Rate limited — retry after backoff");
  } else if (error instanceof APIError) {
    console.error(`API error: ${error.message}`);
  }
}

Error class	Description
`AuthenticationError`	Invalid or missing API key
`RateLimitError`	Rate limit exceeded (429 response)
`APIError`	General API error (4xx/5xx response)
`NetworkError`	Network connectivity issue
`TimeoutError`	Request exceeded the timeout

Debug mode

Enable debug mode to log all HTTP requests and responses to the console:

typescript snippetTStypescript

const ks = new KnowledgeSDK("sk_ks_your_api_key");
ks.setDebugMode(true);

// All subsequent requests will be logged
const result = await ks.extract.run("https://example.com");