Skip to content
Runbear Docs
GitHub

Web SDK types

The public values and TypeScript types @runbear-io/react exports — the client, the chat instance, session types, event payloads, messages and response components.

On this page
ValuesClient optionsChatSessionEventsMessagesResponse componentsAPI responsesRelated

@runbear-io/react ships its TypeScript declarations. This page lists the package's supported public exports, grouped by what you use it for. Exports used only by the SDK's own internals, such as ChatRequestOptions, are left out and may change without notice. "Since" is the first release that exports the name. The current release is 0.4.0; names marked 0.5.0 are not exported until 0.5.0 is released.

import Runbear, {
  SessionDeclinedError,
  type SessionCredentials,
} from "@runbear-io/react"

Values#

ExportSinceWhat it is
Runbear0.0.1The client class, also the default export. new Runbear(options) takes ClientOptions; createChat(threadId?) returns a Chat
RunBear0.0.1An alias of Runbear, kept for older code
SessionDeclinedError0.2.0Throw it from fetchSessionToken to end a session at once. See Declining a session
SessionCredentialError0.2.0Marks a session endpoint response the SDK can't use. The SDK throws it itself; a session that hits it fails with reason: "misconfigured"
isSessionDeclined(error)0.2.0true when error, or an error in its cause chain, is a SessionDeclinedError, including one from a second copy of the package
isSessionCredentialError(error)0.2.0The same test for SessionCredentialError
RunbearApiError0.2.0The error for a non-2xx API response, with status, code, body and retryAfterSeconds. See Errors

A Runbear client also has an api property. It is the widget's internal API client and isn't a supported public surface.

Client options#

TypeSinceWhat it is
ClientOptions0.0.1The constructor's argument: assistantId (required), auth, config, and the deprecated apiKey and baseUrl. See Configuration for config
RunbearAuth0.2.0The auth option: { mode: "session", fetchSessionToken, storage?, sessionKey? }, { mode: "proxy", baseUrl } or { mode: "direct", apiKey, baseUrl? }. See Authentication

Chat#

TypeSinceWhat it is
Chat0.5.0The widget instance createChat() returns, for keeping one in a variable or a ref. Create it with createChat(); it has no public constructor. Its methods are on Chat API

Session#

TypeSinceWhat it is
FetchSessionToken0.2.0(args: FetchSessionTokenArgs) => Promise<SessionCredentials>, the type of auth.fetchSessionToken
FetchSessionTokenArgs0.2.0{ resumeToken?, assistantId, threadId?, signal }. See What fetchSessionToken receives
SessionCredentials0.2.0{ pass, threadId, sessionId, expiresIn, resumeToken? }, what your endpoint returns. See SessionCredentials
SessionStorageMode0.2.0"session" | "local" | "memory", the type of auth.storage
SessionFailureReason0.2.0"declined" | "expired" | "network" | "misconfigured"

Events#

TypeSinceWhat it is
ChatEventType0.2.0The event names on() and off() accept: chatCreated, chatStarted, rendered, containerReady, messagesLoaded, sessionReady, sessionRenewed, sessionChanged, sessionFailed
ChatEventCreatedData0.5.0chatCreated payload: { threadId }
ChatEventContainerReadyData0.5.0containerReady payload: { threadId }
ChatEventMessagesLoadedData0.5.0messagesLoaded payload: { threadId, messageCount }
ChatEventSessionReadyData0.2.0sessionReady payload: { sessionId, threadId }
ChatEventSessionRenewedData0.2.0sessionRenewed payload: { sessionId }
ChatEventSessionChangedData0.2.0sessionChanged payload: { sessionId, threadId }
ChatEventSessionFailedData0.2.0sessionFailed payload: { reason: SessionFailureReason }

chatStarted and rendered carry no payload. Before 0.5.0, the chatCreated, containerReady and messagesLoaded payloads had the same shapes but no exported names.

Messages#

TypeSinceWhat it is
ChatMessage0.0.1One message in the widget: { id?, role, content, thinking?, toolCalls?, suggestions?, attachments?, components? }, where role is "user", "assistant" or "system"
Message0.0.1An alias of ChatMessage
ToolCallStatus0.0.1A tool call's progress: { toolUseId, toolName, toolDisplayName, status, message }, where status is "preparing", "running", "completed" or "failed"
Suggestions0.0.1Suggested follow-up questions: { title, options }
Attachment0.0.1An uploaded file attached to a message: { url, name, contentType }

Response components#

TypeSinceWhat it is
ChatComponent0.3.0A component on a message: { componentId, name, props, fallbackText }. name is an open string and props an open object; narrow props by name before reading it. See Response components
ChatComponentOption0.3.0One option of a confirm or select: { label, value, style? }, where style is "default", "primary" or "danger"
ConfirmProps0.3.0props of a confirm: { options: ChatComponentOption[] }
SelectProps0.3.0props of a select: { options: ChatComponentOption[] }
CardProps0.5.0props of a card: { title, subtitle?, fields? }, where fields is an array of { label, value }

API responses#

These describe what the widget reads from the REST API. They are exported for code that inspects the same data; the REST reference has the full shapes.

TypeSinceWhat it is
Thread0.0.1{ id, createdAt, title }
ListThreadsResponse0.0.1{ threads: Thread[] }
MessagesResponse0.0.1A thread's messages: { messages }, each { id, role, content, components? } (components from 0.3.0). See Chat
CreateRunResponse0.0.1A non-streaming run's reply: { message: { id, content } }
CreateRunStreamResponse0.0.1One line of a streaming run: the thread.message.delta, thread.message.thinking_delta, thread.message.completed, thread.message.component, thread.tool_call.progress, error and done events. See Streaming. 0.5.0 (not yet released) removes thread.message.created, which the API never sent
Assistant0.0.1{ id, created_at }
GetAssistantResponse0.0.1{ assistant: Assistant }