BotBrigade SDK - TypeScript Client

TypeScript type definitions for BotBrigade SDK SSE streaming events.

Installation

# Copy this directory to your TypeScript project
cp -r clients/typescript ./src/botbrigade-sdk

Usage

Importing Types

import {
  SseEvent,
  MessageStartedData,
  BlockDeltaData,
  BlockCompletedData,
  isMessageStartedEvent,
  isBlockDeltaEvent,
  isBlockCompletedEvent,
} from "./botbrigade-sdk";

Processing SSE Events

// Example: Processing SSE stream from BotBrigade
async function processStream(response: Response) {
  const reader = response.body?.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    const lines = chunk.split("\n");

    let event: string | null = null;
    let data: string | null = null;

    for (const line of lines) {
      if (line.startsWith("event:")) {
        event = line.substring(6).trim();
      } else if (line.startsWith("data:")) {
        data = line.substring(5).trim();
      } else if (line === "" && event && data) {
        // Process complete event
        const sseEvent: SseEvent = {
          event,
          data: JSON.parse(data),
        };

        handleEvent(sseEvent);
        event = null;
        data = null;
      }
    }
  }
}

function handleEvent(event: SseEvent) {
  if (isMessageStartedEvent(event)) {
    console.log("Message started:", event.data.message_id);
    console.log("Model:", event.data.model);
  } else if (isBlockDeltaEvent(event)) {
    const { data } = event;

    if (data.block_type === "text") {
      console.log("Text delta:", data.delta.text);
    } else if (data.block_type === "thought") {
      if (data.delta.text) {
        console.log("Thought delta:", data.delta.text);
      }
      if (data.delta.signature) {
        console.log("Thought signature:", data.delta.signature);
      }
    } else if (data.block_type === "tool_call") {
      console.log("Tool call delta:", data.delta.arguments);
      console.log("Partial args:", data.partial_arguments);
    }
  } else if (isBlockCompletedEvent(event)) {
    const { data } = event;

    if (data.block_type === "text") {
      console.log("Text completed:", data.final_content);
    } else if (data.block_type === "thought") {
      console.log("Thought completed:", data.final_content);
      if (data.signature) {
        console.log("Signature:", data.signature);
      }
    } else if (data.block_type === "tool_call") {
      console.log("Tool call completed:", data.tool_name);
      console.log("Result:", data.result);
      console.log("Execution time:", data.execution_time_ms, "ms");
    }
  } else if (isMessageCompletedEvent(event)) {
    console.log("Message completed:", event.data.message_id);
    console.log("Total blocks:", event.data.total_blocks);
    console.log("Finish reason:", event.data.finish_reason);
  }
}

Building a Chat UI

interface ChatMessage {
  id: string;
  role: string;
  blocks: Array<{
    id: string;
    type: "text" | "thought" | "tool_call";
    content: string;
    isComplete: boolean;
  }>;
}

class ChatStreamHandler {
  private currentMessage: ChatMessage | null = null;
  private blockMap = new Map<string, any>();

  handleEvent(event: SseEvent) {
    if (isMessageStartedEvent(event)) {
      this.currentMessage = {
        id: event.data.message_id,
        role: event.data.role,
        blocks: [],
      };
    }

    if (isBlockCreatedEvent(event)) {
      const block = {
        id: event.data.block_id,
        type: event.data.block_type,
        content: "",
        isComplete: false,
      };
      this.currentMessage?.blocks.push(block);
      this.blockMap.set(event.data.block_id, block);
    }

    if (isBlockDeltaEvent(event)) {
      const block = this.blockMap.get(event.data.block_id);
      if (block) {
        if (event.data.block_type === "text") {
          block.content += event.data.delta.text;
        } else if (event.data.block_type === "thought") {
          if (event.data.delta.text) {
            block.content += event.data.delta.text;
          }
        } else if (event.data.block_type === "tool_call") {
          block.content = event.data.partial_arguments;
        }
        this.updateUI();
      }
    }

    if (isBlockCompletedEvent(event)) {
      const block = this.blockMap.get(event.data.block_id);
      if (block) {
        if (event.data.block_type === "text") {
          block.content = event.data.final_content;
        } else if (event.data.block_type === "thought") {
          block.content = event.data.final_content;
        } else if (event.data.block_type === "tool_call") {
          block.content = JSON.stringify({
            tool: event.data.tool_name,
            args: event.data.parsed_arguments,
            result: event.data.result,
          });
        }
        block.isComplete = true;
        this.updateUI();
      }
    }

    if (isMessageCompletedEvent(event)) {
      console.log("Message complete!");
      this.currentMessage = null;
      this.blockMap.clear();
    }
  }

  updateUI() {
    // Update your UI framework here (React, Vue, etc.)
    console.log("Current message:", this.currentMessage);
  }
}

Event Flow

Message Lifecycle

message.started
  → block.created (text/thought/tool_call)
    → block.delta (streaming content)
    → block.delta ...
    → block.completed
  → block.created (next block)
    → ...
  → message.usage
  → message.completed

Tool Execution Flow

block.created (tool_call)
  → block.delta (arguments streaming)
  → tool.execution_started
  → tool.execution_completed (or tool.execution_failed)
  → block.completed (includes result)

Event Types Reference

Message Events

• message.started - Message generation started
• message.usage - Token usage information
• message.completed - Message generation completed

Block Events

• block.created - New content block started
• block.delta - Incremental content update
• block.completed - Block finished
• block.error - Block-level error

Tool Events

• tool.execution_started - Tool execution began
• tool.execution_completed - Tool succeeded
• tool.execution_failed - Tool failed

Agent Events

• agent.delegation_started - Agent delegated to another agent
• agent.delegation_completed - Delegation completed

Error Events

• error - General error event

Block Types

Text Block

Plain text content from the assistant.

{
  block_type: "text",
  final_content: "This is the response text."
}

Thought Block

Internal reasoning/thinking content (extended thinking feature).

{
  block_type: "thought",
  final_content: "Let me think about this...",
  signature: "thinking"
}

Tool Call Block

Tool/function execution with results.

{
  block_type: "tool_call",
  tool_name: "get_weather",
  parsed_arguments: { "city": "Jakarta" },
  result: { "temp": 28, "condition": "sunny" },
  execution_time_ms: 150
}

TypeScript Support

All types are fully typed with TypeScript, providing:

• IntelliSense autocomplete
• Type checking at compile time
• Type guards for event discrimination
• Comprehensive JSDoc documentation

License

See main SDK license.