# How to Install and Use the WeKnora TypeScript Client SDK

> Install and use the WeKnora TypeScript client SDK with npm or Yarn. Instantiate WeKnoraClient for typed requests to the WeKnora REST API.

- Repository: [Tencent/WeKnora](https://github.com/tencent/WeKnora)
- Tags: how-to-guide
- Published: 2026-09-13

---

**Install the `@weknora/dsh-weknora` package via npm or Yarn, then instantiate `WeKnoraClient` with your base URL and optional API key to begin making typed requests to the WeKnora REST API.**

The **WeKnora TypeScript Client SDK** provides a lightweight, ergonomic wrapper around the WeKnora knowledge‑base platform. Located in the `packages/dsh‑weknora` directory of the Tencent/WeKnora monorepo, this SDK exposes strongly‑typed methods for hybrid search, chat streaming, and document retrieval while handling authentication, JSON encoding, and Server‑Sent Events (SSE) parsing automatically.

## Installing the WeKnora TypeScript SDK

The SDK is distributed as a standard NPM package with pre‑compiled TypeScript definitions. No additional build configuration is required.

```bash

# Using npm

npm install @weknora/dsh-weknora

# Or with Yarn

yarn add @weknora/dsh-weknora

```

After installation, import the `WeKnoraClient` class from the package entry point defined in `packages/dsh‑weknora/src/index.ts`.

## Configuring the WeKnora Client

Configuration is handled by the `ClientConfig` interface in `packages/dsh‑weknora/src/config.ts`. The client accepts a **base URL** (optionally suffixed with `/api/v1`) and an optional **API token** for authenticated endpoints.

```typescript
import { WeKnoraClient } from '@weknora/dsh-weknora';

const client = new WeKnoraClient({
  // The WeKnora deployment URL
  baseUrl: 'https://weknora.example.com/api/v1',
  // Optional: bearer token for privileged operations
  apiKey: process.env.WEKNORA_API_KEY,
});

```

The [`config.ts`](https://github.com/Tencent/WeKnora/blob/main/config.ts) module normalizes the URL and validates the `/api/v1` suffix before any request is dispatched.

## Core SDK Operations

The `WeKnoraClient` class in `packages/dsh‑weknora/src/client.ts` maps each public method directly to a WeKnora REST endpoint, returning strongly‑typed objects such as `SearchResult`, `AskResult`, and `KnowledgeBase`.

### Listing Knowledge Bases

Retrieve all available knowledge bases using the `listKnowledgeBases()` method.

```typescript
async function listKBs() {
  const kbs = await client.listKnowledgeBases();
  console.log('Available knowledge bases:', kbs);
}

```

### Performing Hybrid Search

Execute vector‑plus‑keyword searches against a specific knowledge base via the `search()` method.

```typescript
async function hybridSearch(query: string) {
  const results = await client.search({
    knowledgeBaseId: 'default',
    query,
    topK: 5, // Restrict to top‑k results
  });
  console.log('Search hits:', results.hits);
}

```

### Streaming Answers with Chat

The `ask()` and `chat()` methods support **Server‑Sent Events (SSE)** for real‑time streaming. Enable streaming by setting `stream: true`; the client yields incremental message parts until the `complete` event signals the end of the answer.

```typescript
async function streamAnswer(query: string) {
  const stream = client.ask({
    knowledgeBaseId: 'default',
    query,
    stream: true, // Enable SSE streaming
  });

  for await (const part of stream) {
    process.stdout.write(part.delta); // Incremental text chunk
    if (part.complete) break;         // Final completion signal
  }
}

```

The SSE parser logic resides directly in `packages/dsh‑weknora/src/client.ts`, ensuring robust handling of partial data chunks and connection errors.

### Retrieving Documents

Fetch a complete document (reassembled from passages) using the `retrieve()` method.

```typescript
async function getDocument(docId: string) {
  const doc = await client.retrieve({
    knowledgeBaseId: 'default',
    documentId: docId,
  });
  console.log('Full text:', doc.text);
}

```

## Error Handling and Streaming Architecture

All HTTP requests route through a centralized fetch wrapper in `packages/dsh‑weknora/src/client.ts`. When the WeKnora API returns an error status, the client wraps the response in a **`WeknoraApiError`** that extracts the human‑readable `reason` field from the API’s error envelope.

For streaming operations, the client maintains an internal SSE parser that:
- Buffers incoming text streams
- Parses event boundaries according to the SSE specification
- Yields typed `StreamPart` objects containing `delta` text and the `complete` flag

This architecture ensures that consumers receive type‑safe data without manually handling raw `fetch` responses or SSE formatting.

## Key Source Files in the SDK

Understanding the repository structure helps when debugging or extending the client:

- **`packages/dsh‑weknora/src/client.ts`** – Contains the core `WeKnoraClient` class, request helpers, SSE streaming parser, and `WeknoraApiError` implementation.
- **`packages/dsh‑weknora/src/config.ts`** – Normalizes base URLs, validates the `/api/v1` suffix, and defines the `ClientConfig` interface.
- **`packages/dsh‑weknora/src/index.ts`** – Public entry point that re‑exports `WeKnoraClient` and related types for library consumers.
- **`packages/dsh‑weknora/src/types.ts`** – Generated TypeScript definitions for API payloads including `SearchResult`, `AskResult`, and `KnowledgeBase`.
- **`packages/dsh‑weknora/test/client.test.ts`** – Unit tests covering request construction, error handling scenarios, and streaming logic against a mock WeKnora server.

## Summary

- Install the WeKnora TypeScript SDK via `npm install @weknora/dsh-weknora` or Yarn.
- Instantiate `WeKnoraClient` with a `baseUrl` and optional `apiKey` as defined in [`config.ts`](https://github.com/Tencent/WeKnora/blob/main/config.ts).
- Use `listKnowledgeBases()`, `search()`, `ask()`, and `retrieve()` for typed access to WeKnora endpoints.
- Enable real‑time streaming by passing `stream: true` to `ask()` or `chat()`; the SDK handles SSE parsing internally.
- Errors are normalized into `WeknoraApiError` instances with accessible `reason` fields.

## Frequently Asked Questions

### How do I install the WeKnora TypeScript SDK?

Add the package `@weknora/dsh-weknora` to your project using npm (`npm install @weknora/dsh-weknora`) or Yarn (`yarn add @weknora/dsh-weknora`). The package ships with pre‑compiled TypeScript definitions and requires no additional build tools.

### What authentication methods does the SDK support?

The SDK supports bearer token authentication via the `apiKey` configuration option passed to the `WeKnoraClient` constructor. This token is automatically attached to outgoing requests when provided, as implemented in `packages/dsh‑weknora/src/client.ts`.

### How does streaming work in the WeKnora client?

When you set `stream: true` in the `ask()` or `chat()` methods, the client initiates an SSE connection to the WeKnora API. The client parses incoming Server‑Sent Events incrementally, yielding `StreamPart` objects containing text deltas until the final `complete` event marks the end of the response.

### Where are the TypeScript types defined?

All TypeScript interfaces and type definitions for API responses—such as `SearchResult`, `AskResult`, and `KnowledgeBase`—are located in `packages/dsh‑weknora/src/types.ts`. These types are re‑exported through `packages/dsh‑weknora/src/index.ts` for convenient consumer access.