TypeScript Types

Complete type definitions for @brander/sdk

Imports

import Brander, {
  // Components
  BranderChatWidget,
  // Types
  BranderProps,
  BranderChatWidgetProps,
  CustomerAIParams,
  CustomerAIResponse,
  // Multi-provider tools
  MultiProviderTools,
  AnthropicTool,
  OpenAITool,
  GeminiTool,
  // Conversations
  Conversation,
  ConversationsState,
  QueryHistoryItem,
  // AG-UI Streaming
  AGUIEvent,
  AGUIEventType,
  StreamingCallback,
  ToolCallStartEvent,
  ToolCallArgsEvent,
  ToolCallEndEvent,
  RunErrorEvent,
  // Stream adapters
  sseStream,
  anthropicStream,
  anthropicToAGUI,
  openaiStream,
  openaiToAGUI,
  geminiStream,
  geminiToAGUI,
} from "@brander/sdk";

AG-UI Streaming Types

AG-UI is the recommended approach for integrating with BranderUX. It provides progressive UI loading for the best user experience.

StreamingCallback

type StreamingCallback = (
  params: CustomerAIParams
) => AsyncIterable<AGUIEvent> | ReadableStream<AGUIEvent>;

AGUIEventType (Enum)

enum AGUIEventType {
  // Lifecycle Events
  RUN_STARTED = "RUN_STARTED",
  RUN_FINISHED = "RUN_FINISHED",
  RUN_ERROR = "RUN_ERROR",
  STEP_STARTED = "STEP_STARTED",
  STEP_FINISHED = "STEP_FINISHED",

  // Text Message Events
  TEXT_MESSAGE_START = "TEXT_MESSAGE_START",
  TEXT_MESSAGE_CONTENT = "TEXT_MESSAGE_CONTENT",
  TEXT_MESSAGE_END = "TEXT_MESSAGE_END",
  TEXT_MESSAGE_CHUNK = "TEXT_MESSAGE_CHUNK",

  // Tool Call Events (Most important for BranderUX)
  TOOL_CALL_START = "TOOL_CALL_START",
  TOOL_CALL_ARGS = "TOOL_CALL_ARGS",
  TOOL_CALL_END = "TOOL_CALL_END",
  TOOL_CALL_RESULT = "TOOL_CALL_RESULT",
  TOOL_CALL_CHUNK = "TOOL_CALL_CHUNK",

  // State Events
  STATE_SNAPSHOT = "STATE_SNAPSHOT",
  STATE_DELTA = "STATE_DELTA",
  MESSAGES_SNAPSHOT = "MESSAGES_SNAPSHOT",
}

AG-UI Event Types

// Base interface for all AG-UI events
interface BaseAGUIEvent {
  type: AGUIEventType;
  timestamp?: number;
  rawEvent?: unknown;
}

interface ToolCallStartEvent extends BaseAGUIEvent {
  type: AGUIEventType.TOOL_CALL_START;
  toolCallId: string;
  toolCallName: string;  // e.g. "generate_dashboard_data"
}

interface ToolCallArgsEvent extends BaseAGUIEvent {
  type: AGUIEventType.TOOL_CALL_ARGS;
  toolCallId: string;
  delta: string;  // Partial JSON arguments
}

interface ToolCallEndEvent extends BaseAGUIEvent {
  type: AGUIEventType.TOOL_CALL_END;
  toolCallId: string;
}

interface ToolCallResultEvent extends BaseAGUIEvent {
  type: AGUIEventType.TOOL_CALL_RESULT;
  toolCallId: string;
  result: unknown;
}

interface TextMessageStartEvent extends BaseAGUIEvent {
  type: AGUIEventType.TEXT_MESSAGE_START;
  messageId: string;
  role: "assistant" | "user" | "system";
}

interface TextMessageContentEvent extends BaseAGUIEvent {
  type: AGUIEventType.TEXT_MESSAGE_CONTENT;
  messageId: string;
  delta: string;  // Partial text content
}

interface TextMessageEndEvent extends BaseAGUIEvent {
  type: AGUIEventType.TEXT_MESSAGE_END;
  messageId: string;
}

interface RunStartedEvent extends BaseAGUIEvent {
  type: AGUIEventType.RUN_STARTED;
  threadId: string;
  runId: string;
}

interface RunFinishedEvent extends BaseAGUIEvent {
  type: AGUIEventType.RUN_FINISHED;
  threadId: string;
  runId: string;
}

interface RunErrorEvent extends BaseAGUIEvent {
  type: AGUIEventType.RUN_ERROR;
  message: string;
  code?: string;
}

// Union type for all events
type AGUIEvent =
  | ToolCallStartEvent
  | ToolCallArgsEvent
  | ToolCallEndEvent
  | ToolCallResultEvent
  | TextMessageStartEvent
  | TextMessageContentEvent
  | TextMessageEndEvent
  | RunStartedEvent
  | RunFinishedEvent
  | RunErrorEvent
  | /* + state & step events */;

Stream Adapters

sseStream (Most Common)

Connects to backend SSE endpoints that return AG-UI events.

function sseStream(
  url: string,
  options?: {
    params?: CustomerAIParams;
    headers?: Record<string, string>;
    method?: "GET" | "POST";
  }
): AsyncIterable<AGUIEvent>;

// Usage
onQueryStream={(params) => sseStream("/api/agent", { params })}

anthropicStream

Converts Anthropic SDK streams to AG-UI events.

async function* anthropicStream(
  stream: AsyncIterable<Anthropic.MessageStreamEvent>
): AsyncGenerator<AGUIEvent>;

// Usage
onQueryStream={async function*(params) {
  const stream = anthropic.messages.stream({...});
  yield* anthropicStream(stream);
}}

openaiStream

Converts OpenAI SDK streams to AG-UI events.

async function* openaiStream(
  stream: AsyncIterable<OpenAI.ChatCompletionChunk>
): AsyncGenerator<AGUIEvent>;

// Usage
onQueryStream={async function*(params) {
  const stream = await openai.chat.completions.create({ stream: true, ... });
  yield* openaiStream(stream);
}}

geminiStream

Converts Google Gemini SDK streams to AG-UI events.

async function* geminiStream(
  stream: AsyncIterable<GenerateContentResponse>
): AsyncGenerator<AGUIEvent>;

// Usage
onQueryStream={async function*(params) {
  const result = await model.generateContentStream({...});
  yield* geminiStream(result.stream);
}}

Per-Chunk Converters (Advanced)

For custom control over event conversion:

// Anthropic per-chunk
function* anthropicToAGUI(
  chunk: Anthropic.MessageStreamEvent,
  state?: { currentToolId?: string | null }
): Generator<AGUIEvent>;

// OpenAI per-chunk
function* openaiToAGUI(
  chunk: OpenAI.ChatCompletionChunk
): Generator<AGUIEvent>;

// Gemini per-chunk
function* geminiToAGUI(
  chunk: GenerateContentResponse
): Generator<AGUIEvent>;

Core Types

CustomerAIParams

interface CustomerAIParams {
  system?: string;             // System instructions (A2UI protocol in flexible mode)
  messages: Array<{
    role: "user" | "assistant";
    content: string;
  }>;
  tools?: MultiProviderTools;  // Tools in all 3 provider formats
  max_tokens?: number;         // Suggested max tokens
}

MultiProviderTools

interface MultiProviderTools {
  anthropic: AnthropicTool[];  // { name, description, input_schema }
  openai: OpenAITool[];        // { type: "function", function: { name, parameters } }
  gemini: GeminiTool[];        // { name, description, parameters }
}

OnQueryCallback (Non-Streaming)

type OnQueryCallback = (
  params: CustomerAIParams
) => Promise<CustomerAIResponse>;

CustomerAIResponse (Non-Streaming)

interface CustomerAIResponse {
  content: Array<{
    type: "text";
    text: string;
  }>;
}

Component Props

BranderProps

interface BranderProps {
  // Required props
  betaKey: string;
  projectId: string;

  // AI Handler (ONE required)
  onQueryStream?: StreamingCallback;  // Recommended
  onQuery?: OnQueryCallback;          // Alternative

  // Display
  variant?: "hybrid" | "classic" | "chat";
  defaultSidebarOpen?: boolean;

  // Conversations
  conversations?: Conversation[];
  activeConversationId?: string;
  onConversationsChange?: (state: ConversationsState) => void;

  // Styling
  width?: string;
  height?: string;
  className?: string;
  style?: CSSProperties;
}

BranderChatWidgetProps

interface BranderChatWidgetProps extends BranderProps {
  // Trigger element (required)
  children: React.ReactNode;

  // Position
  position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
  offset?: { top?: number; bottom?: number; left?: number; right?: number };
  widgetSize?: { width?: string; height?: string };

  // Behavior
  defaultOpen?: boolean;
  onOpen?: () => void;
  onClose?: () => void;

  // Backdrop
  showBackdrop?: boolean;
  backdropOpacity?: number;
  closeOnBackdropClick?: boolean;

  // Styling
  zIndex?: number;
  animationDuration?: number;
}

CustomPage

interface CustomPage {
  id: string;
  name: string;
  query: string;
}

Conversation Types

Conversation

interface Conversation {
  id: string;
  title: string;
  createdAt: number;
  updatedAt: number;
  queryHistory: QueryHistoryItem[];
}

interface QueryHistoryItem {
  id: string;
  rawQuery: string;
  query: string;
  response: Record<string, unknown>;
  screenId: string;
  timestamp: number;
}

ConversationsState

interface ConversationsState {
  conversations: Conversation[];
  activeConversationId: string | null;
}

Multi-Provider Tool Types

AnthropicTool

interface AnthropicTool {
  name: string;
  description: string;
  input_schema: {
    type: "object";
    properties: Record<string, any>;
    required?: string[];
  };
}

OpenAITool

interface OpenAITool {
  type: "function";
  function: {
    name: string;
    description: string;
    parameters: {
      type: "object";
      properties: Record<string, any>;
      required?: string[];
    };
  };
}

GeminiTool

interface GeminiTool {
  name: string;
  description: string;
  parameters: {
    type: "object";
    properties: Record<string, any>;
    required?: string[];
  };
}

Usage Example

App.tsx

import Brander, {
  sseStream,
  BranderProps,
  CustomerAIParams,
  AGUIEvent,
  AGUIEventType,
  StreamingCallback,
} from "@brander/sdk";

// Type your streaming handler
const handleQueryStream: StreamingCallback = (params: CustomerAIParams) => {
  return sseStream("/api/agent", { params });
};

// Type your component props
const props: BranderProps = {
  betaKey: "bux_your_token",
  projectId: "your_project_id",
  onQueryStream: handleQueryStream,
  variant: "classic",
  width: "100%",
  height: "600px",
};

function App() {
  return <Brander {...props} />;
}