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

# Javascript / TypeScript SDK

> Use the official B-Bot SDK to integrate AI capabilities into your Javascript/TypeScript applications.

The **B-Bot SDK** (`@beyond-bot-ai/sdk`) is the official way to interact with the B-Bot Platform. It provides a type-safe interface to manage Distribution Channels (Assistants), Threads, and Runs, built on top of the [LangGraph SDK](https://langchain-ai.github.io/langgraph/) but adapted for B-Bot's terminology.

<Card title="NPM Package" icon="npm" href="https://www.npmjs.com/package/@beyond-bot-ai/sdk">
  View on NPM
</Card>

## Installation

```bash theme={null}
npm install @beyond-bot-ai/sdk
```

## Quick Start

Initialize the client with your B-Bot API Key. The SDK is pre-configured to connect to the B-Bot API.

```typescript theme={null}
import { BBotClient } from "@beyond-bot-ai/sdk";

const client = new BBotClient({
  apiKey: "bbot_your_api_key_here" // Your B-Bot API Key
});
```

### Getting Your API Key

1. Go to [B-Bot Hub](https://hub.b-bot.space)
2. Navigate to **Settings** → **API Keys**
3. Click **Create New API Key**
4. Copy the key (starts with `bbot_`)
5. Store it securely (treat it like a password!)

<Warning>
  Never commit your API key to version control. Use environment variables:

  ```typescript theme={null}
  const client = new BBotClient({
    apiKey: process.env.BBOT_API_KEY
  });
  ```
</Warning>

## Core Concepts

### 1. Distribution Channels

In B-Bot, AI Assistants are exposed as **Distribution Channels**. You can search, retrieve, and manage them using the `client.distributionChannels` property.

```typescript theme={null}
// Search for available channels
const channels = await client.distributionChannels.search({
  limit: 10,
  offset: 0
});

// Get a specific channel by assistant_id
const channel = await client.distributionChannels.get("assistant-id");

// Extract entity_id from channel config (required for runs)
const entityId = channel.config?.configurable?.entity_id;
```

### 2. Threads

Threads persist the state of a conversation. Every interaction happens within a thread.

```typescript theme={null}
// Create a new thread
const thread = await client.threads.create();

// Add initial messages to the thread state
await client.threads.updateState(thread.thread_id, {
  values: {
    messages: [
      { role: "user", content: "Hello, B-Bot!" }
    ]
  }
});
```

### 3. Streaming Runs (Recommended)

<Warning>
  **Important:** B-Bot sends **cumulative content** in `messages/partial` events (e.g., "Hello", "Hello!", "Hello! How"), not individual tokens. Your `onMessage` callback should **replace** the content, not append it.
</Warning>

The SDK includes a powerful **Streaming Handler** (`client.streamRun`) that simplifies processing real-time events like token streaming, tool execution, and state updates.

```typescript theme={null}
// Get the channel first to extract entity_id
const channel = await client.distributionChannels.get("assistant-id");
const entityId = channel.config?.configurable?.entity_id;

// Stream a run (this waits until the stream completes)
await client.streamRun(
  "thread-id",
  channel.assistant_id, // Use assistant_id from the channel
  {
    messages: [
      { role: "user", content: "Write a short poem about AI." }
    ]
  },
  {
    // Handle real-time token streaming
    // isCumulative=true means REPLACE content, don't append
    onMessage: (content, isCumulative) => {
      if (isCumulative) {
        // Replace the entire message content
        setStreamingContent(content);
      } else {
        // Append (rare case)
        setStreamingContent(prev => prev + content);
      }
    },
    // Handle tool execution events
    onToolEvent: (event) => {
      console.log("\n[Tool Running]:", event.tool_name);
    },
    // Handle completion
    onUpdate: (messages) => {
      console.log("\n[Done]");
    },
    onError: (err) => console.error("Error:", err)
  },
  { entity_id: entityId } // Pass entity_id from channel config
);
```

### Manual Streaming (Advanced)

If you need lower-level control over the stream:

```typescript theme={null}
const stream = await client.runs.stream(
  threadId,
  assistantId, // Note: Use assistant_id, not channel_id
  {
    input: {
      messages: [
        { role: "user", content: "Help me with marketing." }
      ],
      entity_id: entityId // Required by B-Bot graph
    },
    streamMode: ["values", "messages"]
  }
);

// This blocks until the stream completes
for await (const chunk of stream) {
  console.log(chunk.event, chunk.data);
}
```

## State Management (Todos & Files)

The SDK automatically extracts structured data like **Todos** and **Files** generated by the AI.

```typescript theme={null}
await client.streamRun(
  threadId, 
  assistantId, 
  { messages: [...] }, 
  {
    // Called when the AI creates or updates todos
    onTodosUpdate: (todos) => {
      console.log("Active Todos:", todos);
    },
    // Called when the AI generates files
    onFilesUpdate: (files) => {
      // files is a map of { filename: content }
      for (const [name, content] of Object.entries(files)) {
        saveFile(name, content);
      }
    }
  },
  { entity_id: entityId }
);
```

## Debugging

If `onMessage` is not being called or you're not receiving events, enable debug mode:

```typescript theme={null}
await client.streamRun(
  threadId,
  assistantId,
  { messages: [...] },
  {
    onMessage: (content, isCumulative) => {
      console.log("Received:", content);
    }
  },
  { 
    entity_id: entityId,
    debug: true // Enable detailed logging
  }
);
```

This will log:

* Every chunk received from the stream
* Event types and data structures
* Content extraction process
* Total chunks processed

## Common Pitfalls

### 1. Missing `entity_id`

B-Bot requires `entity_id` in the initial state. Always extract it from the channel config:

```typescript theme={null}
const channel = await client.distributionChannels.get(assistantId);
const entityId = channel.config?.configurable?.entity_id;
```

### 2. Using `channel_id` instead of `assistant_id`

The API returns `assistant_id`, not `channel_id`. Use `channel.assistant_id`.

### 3. Appending cumulative content

B-Bot sends the full message so far in each chunk. Always **replace** content when `isCumulative=true`.

## Features

* **Native Terminology**: Uses `client.distributionChannels` instead of `client.assistants`.
* **Streaming Handler**: Built-in `streamRun` helper for easy real-time UI updates.
* **State Extraction**: Automatically extracts Todos and Files from stream events.
* **Auto-Configuration**: Pre-configured for `api.b-bot.space`.
* **Type Safety**: Full TypeScript support.
* **Cumulative Streaming**: Properly handles B-Bot's cumulative content streaming.

## License

MIT