B-Bot SDK (JavaScript/TypeScript)

The official JavaScript/TypeScript SDK for the B-Bot Platform. This library allows developers to interact with the B-Bot API to manage Distribution Channels, Threads, and Runs.

Installation

npm install @beyond-bot-ai/sdk

Usage

Initialization

import { BBotClient } from "@beyond-bot-ai/sdk";

// Initialize with your B-Bot API key
// Get your API key from: https://hub.b-bot.space/settings/api-keys
const client = new BBotClient({
  apiKey: "bbot_your_api_key_here"  // Required: Your B-Bot API key
  // apiUrl: "https://api.b-bot.space/api/v2"  // Optional: defaults to this
});

Getting your API Key:

1. Go to B-Bot Hub
2. Navigate to Settings → API Keys
3. Create a new API key (starts with bbot_)
4. Copy and use it in your code

Managing Distribution Channels

In B-Bot, AI Assistants are referred to as Distribution Channels. This SDK provides a dedicated property for managing them.

// List all available distribution channels
const channels = await client.distributionChannels.search();

// 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;

Managing Conversations (Threads)

Threads persist the state of a conversation.

// Create a new thread
const thread = await client.threads.create();

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

// Get current state
const state = await client.threads.getState(thread.thread_id);

Running with Streaming (Recommended)

⚠️ Important: B-Bot sends cumulative content in streaming (e.g., "Hello", "Hello!", "Hello! How"), not individual tokens. Your onMessage callback should replace the content, not append it.

// 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 poem about AI." }
    ]
  },
  {
    // Handle real-time streaming
    // isCumulative=true means REPLACE content, don't append
    onMessage: (content, isCumulative) => {
      if (isCumulative) {
        setStreamingContent(content); // Replace
      }
    },
    onToolEvent: (event) => {
      console.log("Tool executing:", event.tool_name);
    },
    onTodosUpdate: (todos) => {
      console.log("Todos updated:", todos);
    },
    onFilesUpdate: (files) => {
      console.log("Files updated:", files);
    },
    onUpdate: (messages) => console.log("Chat updated"),
    onError: (err) => console.error("Error:", err)
  },
  { entity_id: entityId } // Pass entity_id from channel config
);

Manual Streaming (Advanced)

If you need lower-level control:

const stream = await client.runs.stream(
  threadId,
  assistantId, // Note: Use assistant_id, not channel_id
  {
    input: {
      messages: [...],
      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);
}

Debugging

If onMessage is not being called, enable debug mode:

await client.streamRun(
  threadId, assistantId, { messages: [...] },
  { onMessage: (content) => console.log(content) },
  { entity_id: entityId, debug: true } // Enable logging
);

Common Pitfalls

1. Missing entity_id: Always extract it from channel.config.configurable.entity_id
2. Using channel_id instead of assistant_id: The API returns assistant_id
3. Appending cumulative content: B-Bot sends full message each time - use replace, not append

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