@optima-chat/agentic-sdk

React SDK for the Optima agentic chat gateway. Provides a <ChatProvider>, a set of hooks for reading/writing chat state, a Zustand store, a WebSocket client, and a workspace-file integration. Pluggable auth (works with @optima-chat/agentic-auth or any custom tokenProvider).

Install

pnpm add @optima-chat/agentic-sdk

Peer dependencies: react@^19, zustand@^5.

Usage

1. Wrap your app in ChatProvider

import { ChatProvider, createDefaultWorkspaceProvider } from '@optima-chat/agentic-sdk';

<ChatProvider
  gatewayUrl="wss://gateway.optima.chat/ws"
  tokenProvider={async () => currentAccessToken}
  authenticatedFetch={fetchWithAuth}                    // optional
  workspaceProvider={createDefaultWorkspaceProvider(    // optional
    'https://gateway.optima.chat',
    fetchWithAuth,
  )}
  onFinish={({ conversationId, finish }) => { /* … */ }}
  onToolCall={({ toolName, args }) => { /* … */ }}
  onError={(error) => { /* … */ }}
  onNotification={(event) => { /* … */ }}
  onRawEvent={(event) => { /* intercept gateway events before store mutation */ }}
>
  {children}
</ChatProvider>

2. Consume via hooks

All hooks must be called inside a <ChatProvider> descendant.

| Hook | Returns | |---|---| | useConnectionState() | { connectionState, error, reconnectAttempt, reconnect } | | useSession() | { sessionId, userId, provider, model } | | useConversations() | { conversations, currentConversationId, createConversation, deleteConversation, renameConversation, switchConversation, isLoading, error } | | useCurrentChat() | { messages, isStreaming, isThinking, error, sendMessage, abort, resetConversation, loadHistory, hasMoreHistory, isLoadingHistory } | | useQuestion() | { pendingQuestion, answerQuestion, dismissQuestion } | | useApproval() | { pendingApprovals, approve, reject, modify } | | useSwitchConfig() | { switchConfig } | | useProcessingConversations() | string[] — conversation ids with active streams (for sidebar spinners) |

Example: send a message, stream response

import { useConversations, useCurrentChat } from '@optima-chat/agentic-sdk';

function ChatInput() {
  const { currentConversationId, createConversation, switchConversation } = useConversations();
  const { sendMessage, isStreaming } = useCurrentChat();

  async function send(text: string) {
    if (!currentConversationId) {
      const conv = await createConversation();
      switchConversation(conv.id);
    }
    await sendMessage(text);
  }

  return /* … */;
}

ChatProvider props — callback summary

• onFinish — assistant turn completed. Receives { conversationId, finish: FinishInfo }.
• onToolCall — tool invocation started. Receives { toolName, args, toolCallId }. Useful for opening side panels when specific tools run.
• onError — mapped chat error with { code, message, details }. For billing-category errors, error.code is the BillingError.reason and error.details is the full BillingError.
• onNotification — in-band notifications ({ type: 'error' | 'warning' | 'info', message }), typically rendered as toasts.
• onRawEvent — raw gateway event before store mutation. Use this to extract out-of-band data (progress events, custom info events, tool-result payloads) into your own store.

Impersonation / reconnect

<ChatProvider> reads tokenProvider on every WebSocket connect. To switch users (e.g., admin impersonation) or force a reconnect with different credentials, remount the provider with a key:

<ChatProvider key={impersonationId ?? 'normal'} tokenProvider={…} … />

Workspace integration

workspaceProvider is optional. If you need file attachments on messages or skill-backed file access, wire up createDefaultWorkspaceProvider(gatewayHttpBase, authenticatedFetch) or implement the WorkspaceProvider interface yourself.

Type exports

import type {
  ChatProviderProps,
  ConnectionState, MessageStatus, ToolCallStatus,
  ChatError, Conversation, Message, MessageAttachment, ToolCall,
  QuestionRequest, ApprovalRequestWithId,
  SendMessageOptions, UploadResult,
  WorkspaceProvider,
  // re-exports from @optima-chat/gateway-protocol
  ServerEvent, ClientEvent, FinishInfo, Question, ApprovalRequest,
  ApprovalResponse, TokenProgress, BillingError,
} from '@optima-chat/agentic-sdk';

Relation to agentic-auth

agentic-sdk does not depend on agentic-auth. You can pair them for the standard OAuth 2.0 / email-OTP flow, or provide any other tokenProvider: () => Promise<string> implementation.

Development

pnpm --filter @optima-chat/agentic-sdk test
pnpm --filter @optima-chat/agentic-sdk typecheck
pnpm --filter @optima-chat/agentic-sdk build

Tests run under vitest with jsdom.