> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript SDK

> Get started with TopK Context Engine using JavaScript SDK.

[![npm version](https://img.shields.io/npm/v/topk-js.svg)](https://www.npmjs.com/package/topk-js)

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

## Installation

```sh theme={null}
npm install topk-js
# or
yarn add topk-js
# or
pnpm install topk-js
```

## Prerequisites

* **API key** — sign in to [console.topk.io](https://console.topk.io) and generate an API key.
* **Region** — available regions are listed at [docs.topk.io/regions](https://docs.topk.io/regions).

## Usage

```typescript theme={null}
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:

```typescript theme={null}
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`:

```typescript theme={null}
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.