TopK JavaScript SDK

The TopK JavaScript library provides convenient access to the TopK API from Node.js environments with full TypeScript support.

Documentation

The full documentation can be found at docs.topk.io.

The JavaScript SDK reference can be found at docs.topk.io/sdk/topk-js.

Installation

npm install topk-js
# or
yarn add topk-js
# or
pnpm install topk-js

Prerequisites

• API key — sign in to console.topk.io and generate an API key.
• Region — available regions are listed at docs.topk.io/regions.

Usage

import { Client } from "topk-js";

const client = new Client({
  apiKey: process.env.TOPK_API_KEY,
  region: "aws-us-east-1-elastica",
});

// Create a dataset
await client.datasets().create("my-dataset");

// Upload a file
const handle = await client.dataset("my-dataset").upsertFile(
  "doc-1",
  { path: "/path/to/document.pdf" },
  { kind: "report", department: "finance" }, // optional metadata
);

// Wait for the file to process (optional)
await client.dataset("my-dataset").waitForHandle(handle);

// Ask a question
for await (const message of client.ask(
  "What was the total net income of Bank of America in 2024?",
  ["my-dataset"],
)) {
  console.log(message);
}

Handling errors

The SDK throws plain Error objects. Check err.message to identify the error:

try {
  for await (const message of client.ask(
    "What was the total net income of Bank of America in 2024?",
    ["my-dataset"],
  )) {
    console.log(message);
  }
} catch (err) {
  if (err instanceof Error) {
    if (err.message === "dataset not found") console.error("Dataset does not exist");
    else if (err.message === "permission denied") console.error("Check your API key");
    else console.error("Unexpected error:", err.message);
  }
}

| err.message | Description | | --- | --- | | "collection not found" | Collection does not exist | | "collection already exists" | Collection with this name already exists | | "dataset not found" | Dataset does not exist | | "dataset already exists" | Dataset with this name already exists | | "permission denied" | Invalid or missing API key | | starts with "request too large:" | Request payload too large |

Retries

The client automatically retries on slow-down and LSN consistency timeouts. Retry behaviour can be configured via retryConfig:

import { Client } from "topk-js";

const client = new Client({
  apiKey: process.env.TOPK_API_KEY,
  region: "aws-us-east-1-elastica",
  retryConfig: {
    maxRetries: 5,       // default: 3
    timeout: 60_000,     // total retry chain timeout in ms, default: 30,000
    backoff: {
      initBackoff: 200,  // default: 100 ms
      maxBackoff: 5_000, // default: 10,000 ms
    },
  },
});

Requirements

Node.js 18 or higher.