ReactBridge SDK

A flexible React SDK for building intelligent conversational interfaces with LLM-powered agents.

Features

✨ Easy Integration - Get started in minutes with high-level components
🎨 Customizable Theming - Light, dark, and custom themes with full control
🔧 Flexible Architecture - Use pre-built components or build your own with hooks
🤖 Intelligent Context - Automatic context diffing and injection
⚡ Two-Step Orchestration - Seamless action execution and feedback loop
📦 TypeScript First - Full type safety and IntelliSense support
📈 Analytics Admin UI - Widgets, reports, and dashboards for AI-generated insights
📊 Business Intelligence Reports - 5 comprehensive REST endpoints for analytics (Executive Dashboard, Supply Chain Risk, Execution Audit Trail, Portfolio Health, Data Quality & Automation)

Installation

npm install reactbridge-sdk
# or
yarn add reactbridge-sdk

Quick Start

1. Wrap your app with the Provider

import { ReactBridgeProvider } from 'reactbridge-sdk';

function App() {
  return (
    <ReactBridgeProvider apiKey="your-api-key">
      <YourApp />
    </ReactBridgeProvider>
  );
}

2. Use the Chatbox Component

import { ReactBridgeChatbox } from 'reactbridge-sdk';

function ChatPage() {
  const handleAction = async (toolCall) => {
    // Execute your business logic
    const results = await yourAPI.search(toolCall.parameters);
    
    return {
      status: 'success',
      summary: `Found ${results.length} items`,
      detailed_data: results
    };
  };

  const interfaceState = {
    userId: 'user-123',
    currentContext: {
      currentPageName: 'Products',
      viewingItems: products
    }
  };

  return (
    <ReactBridgeChatbox
      onIntentDetected={handleAction}
      currentContext={interfaceState}
    />
  );
}

API Reference

<ReactBridgeProvider />

Wraps your application and provides configuration.

Props:

| Prop | Type | Required | Description | |------|------|----------|-------------| | apiKey | string | Yes | Your ReactBridge API key | | config | object | No | Additional configuration (baseURL, timeout, headers) | | theme | Theme | No | Custom theme object | | sttProvider | STTProvider | No | Custom speech-to-text provider | | ttsProvider | TTSProvider | No | Custom text-to-speech provider |

Example:

<ReactBridgeProvider
  apiKey="your-key"
  config={{
    baseURL: 'https://your-api.com',
    timeout: 30000
  }}
  theme={darkTheme}
>
  <App />
</ReactBridgeProvider>

<ReactBridgeChatbox />

Full-featured chat interface component.

Props:

| Prop | Type | Required | Description | |------|------|----------|-------------| | onIntentDetected | function | Yes | Callback when LLM detects an action | | currentContext | InterfaceState | Yes | Current user and page context | | placeholder | string | No | Input placeholder text | | height | string | No | Component height (default: '500px') | | width | string | No | Component width (default: '100%') | | theme | Partial<Theme> | No | Theme overrides | | renderMessage | function | No | Custom message renderer | | onError | function | No | Error handler | | onSpeechStart | function | No | Called when voice input starts | | onSpeechEnd | function | No | Called when voice input ends | | onTranscript | function | No | Called with transcribed text | | onAgentResponse | function | No | Called with agent response text |

<ReactBridgeSearch />

Compact search bar component.

Props:

| Prop | Type | Required | Description | |------|------|----------|-------------| | onIntentDetected | function | Yes | Callback when LLM detects an action | | currentContext | InterfaceState | Yes | Current user and page context | | placeholder | string | No | Input placeholder text | | width | string | No | Component width (default: '100%') | | maxResults | number | No | Maximum results to show (default: 5) | | theme | Partial<Theme> | No | Theme overrides | | onError | function | No | Error handler | | onSpeechStart | function | No | Called when voice input starts | | onSpeechEnd | function | No | Called when voice input ends | | onTranscript | function | No | Called with transcribed text | | onAgentResponse | function | No | Called with agent response text |

useReactBridge(options)

Core hook for building custom interfaces.

Parameters:

interface UseReactBridgeOptions {
  onIntentDetected: (toolCall: ToolCall) => Promise<ToolResult>;
  currentContext: InterfaceState;
  onError?: (error: Error) => void;
}

Returns:

interface UseReactBridgeReturn {
  messages: ChatMessage[];
  isLoading: boolean;
  sendChatQuery: (query: string) => Promise<void>;
  clearMessages: () => void;
  error: Error | null;
}

Example:

import { useReactBridge } from 'reactbridge-sdk';

function CustomChat() {
  const { messages, isLoading, sendChatQuery } = useReactBridge({
    onIntentDetected: handleAction,
    currentContext: interfaceState
  });

  return (
    <div>
      {messages.map(msg => <Message key={msg.id} {...msg} />)}
      <input onSubmit={(q) => sendChatQuery(q)} disabled={isLoading} />
    </div>
  );
}

Analytics Suite

The SDK ships with DirectivSys analytics components for visualizing AI-generated metrics, observations, and directives and for executing recommended actions.

Components

• AnalyticsWidget — Floating entry point that opens a drawer of analytics configs; best for adding analytics everywhere in your admin UI.
• AnalyticsReport — Full report view for a single analyticsType (metrics, observations, directives) with optional back/close controls.
• AnalyticsDashboard — Full-width dashboard that lists all analytics configs on the left and shows the selected report on the right. Supports manual refresh, optional autoRefreshInterval, and directive status filtering.

import {
  ReactBridgeProvider,
  AnalyticsWidget,
  AnalyticsReport,
  AnalyticsDashboard,
} from 'reactbridge-sdk';

const handleDirectiveAction = async (directive, action) => {
  if (action === 'decline') return { success: true };

  // Execute the directive in your system
  const result = await api.executeDirective(directive);
  return { success: result.ok, error: result.error };
};

function Admin() {
  return (
    <ReactBridgeProvider apiKey="your-api-key">
      <AnalyticsWidget onDirectiveAction={handleDirectiveAction} />

      <AnalyticsReport
        analyticsType="InventoryHealth"
        onDirectiveAction={handleDirectiveAction}
      />

      <AnalyticsDashboard
        onDirectiveAction={handleDirectiveAction}
        autoRefreshInterval={300}
      />
    </ReactBridgeProvider>
  );
}

Directive actions: The callback receives the directive plus the requested action (execute or decline) and should return { success: boolean, error?: string }. On success, directive status becomes executed; failures become failed; declines become declined. Directive statuses are proposed, executed, declined, and failed. Priorities are numeric (higher = more urgent).

Analytics Hooks

• useAnalyticsConfigs() — Fetches all analytics configs (configs, isLoading, error, refetch).
• useAnalyticsResult(analyticsType) — Fetches the latest result for a given analytics type (result, isLoading, error, refetch).
• useDirectiveAction(onDirectiveAction?) — Wraps your handler, updates directive status in the backend, and exposes handleAction, isProcessing, and error.

import { useAnalyticsConfigs, useAnalyticsResult, useDirectiveAction } from 'reactbridge-sdk';

const { configs } = useAnalyticsConfigs();
const { result, refetch } = useAnalyticsResult('InventoryHealth');
const { handleAction, isProcessing } = useDirectiveAction(handleDirectiveAction);

Analytics API Client

import { AnalyticsAPI } from 'reactbridge-sdk';

const api = new AnalyticsAPI({ apiKey: 'your-api-key' });
const configs = await api.getConfigs();
const result = await api.getLatestResult('InventoryHealth');
await api.updateDirectiveStatus(directiveId, 'executed');

More Docs

• Detailed components and hooks: ANALYTICS_README.md
• Full dashboard guide: ANALYTICS_DASHBOARD_README.md

Business Intelligence Reports

The SDK includes 5 comprehensive REST endpoints for investor-ready analytics with date range filtering and 1-hour caching.

Available Reports

import {
  ReactBridgeProvider,
  ExecutiveDashboard,
  SupplyChainRisk,
  ExecutionAuditTrail,
  PortfolioHealth,
  DataQualityAutomation
} from 'reactbridge-sdk';

function ReportsPage() {
  return (
    <ReactBridgeProvider apiKey="your-api-key">
      {/* High-level metrics and trends */}
      <ExecutiveDashboard />

      {/* Supply chain risk analysis */}
      <SupplyChainRisk />

      {/* Execution history and audit */}
      <ExecutionAuditTrail />

      {/* Portfolio metric health */}
      <PortfolioHealth />

      {/* Data quality & automation opportunities */}
      <DataQualityAutomation />
    </ReactBridgeProvider>
  );
}

Reports via Hooks

import { useReactBridgeContext } from 'reactbridge-sdk';

function CustomReport() {
  const { api } = useReactBridgeContext();

  // Fetch Executive Dashboard
  const dashboard = await api.getExecutiveDashboard({
    startDate: '2026-01-06',
    endDate: '2026-02-05'
  });

  // Fetch Supply Chain Risk
  const risk = await api.getSupplyChainRisk();

  // Fetch Execution Audit with filter
  const audit = await api.getExecutionAuditTrail({
    directiveType: 'inventory-rebalance'
  });

  // Fetch Portfolio Health
  const health = await api.getPortfolioHealth();

  // Fetch Data Quality Assessment
  const quality = await api.getDataQualityAutomation();
}

Reports Documentation

• Full API reference: REPORTS_API.md
• Provider pattern guide: REPORTS_PROVIDER_PATTERN.md

Authentication

All reports use X-API-Key header authentication. Simply pass your API key to ReactBridgeProvider and it's automatically used by all endpoints:

<ReactBridgeProvider apiKey="your-api-key-here">
  <YourReportsApp />
</ReactBridgeProvider>

Voice Input/Output

The SDK supports voice input (Speech-to-Text) and voice output (Text-to-Speech) for a fully conversational experience.

Default Providers

By default, the SDK uses browser Web Speech APIs:

• STT: WebSpeechSTTProvider (SpeechRecognition)
• TTS: WebSpeechTTSProvider (speechSynthesis)

Custom Providers

You can swap providers for advanced implementations:

import { ReactBridgeProvider, WebSpeechSTTProvider, WebSpeechTTSProvider } from 'reactbridge-sdk';

// Custom STT Provider
class MySTTProvider {
  startRecognition() { /* ... */ }
  stopRecognition() { /* ... */ }
  onResult(callback: (text: string) => void) { /* ... */ }
}

// Custom TTS Provider
class MyTTSProvider {
  speak(text: string) { /* ... */ }
}

<ReactBridgeProvider
  apiKey="your-key"
  sttProvider={new MySTTProvider()}
  ttsProvider={new MyTTSProvider()}
>
  <App />
</ReactBridgeProvider>

Voice Events

const { startVoiceInput, stopVoiceInput, isListening } = useReactBridge({
  onIntentDetected: handleAction,
  currentContext: context,
  onSpeechStart: () => console.log('Voice input started'),
  onSpeechEnd: () => console.log('Voice input ended'),
  onTranscript: (text) => console.log('Transcribed:', text),
  onAgentResponse: (response) => console.log('Agent responded:', response),
});

Chatbox with Voice

The ReactBridgeChatbox includes a microphone button next to the text input:

<ReactBridgeChatbox
  onIntentDetected={handleAction}
  currentContext={context}
/>

• Click the mic button to start/stop voice recording
• Transcribed text is automatically sent to the API
• Agent responses are spoken aloud

Theming

Built-in Themes

import { lightTheme, darkTheme } from 'reactbridge-sdk';

<ReactBridgeProvider theme={darkTheme}>
  <App />
</ReactBridgeProvider>

Custom Theme

import { createCustomTheme, lightTheme } from 'reactbridge-sdk';

const myTheme = createCustomTheme(lightTheme, {
  colors: {
    primary: '#ff6b6b',
    background: '#f8f9fa'
  },
  fontSizes: {
    md: '18px',
    lg: '22px'
  },
  spacing: {
    md: '20px'
  }
});

<ReactBridgeProvider theme={myTheme}>
  <App />
</ReactBridgeProvider>

Theme Structure

interface Theme {
  name: string;
  colors: {
    primary: string;
    secondary: string;
    background: string;
    surface: string;
    text: string;
    textSecondary: string;
    border: string;
    error: string;
    success: string;
  };
  spacing: {
    xs: string;
    sm: string;
    md: string;
    lg: string;
    xl: string;
  };
  fontSizes: {
    xs: string;
    sm: string;
    md: string;
    lg: string;
    xl: string;
  };
  borderRadius: string;
  boxShadow: string;
}

Action Execution Contract

The onIntentDetected callback is where you implement your business logic.

Input: ToolCall

interface ToolCall {
  toolName: string;              // e.g., "searchProducts"
  parameters: Record<string, any>;  // e.g., { category: "t-shirts" }
}

Output: ToolResult

interface ToolResult {
  status: 'success' | 'error' | 'partial';
  summary: string;           // Natural language summary for LLM
  detailed_data?: any;       // Optional data preview
}

Example Implementation

const onIntentDetected = async (toolCall) => {
  switch (toolCall.toolName) {
    case 'searchProducts':
      try {
        const results = await api.searchProducts(toolCall.parameters);
        return {
          status: 'success',
          summary: `Found ${results.length} products`,
          detailed_data: { total: results.length, preview: results.slice(0, 3) }
        };
      } catch (error) {
        return {
          status: 'error',
          summary: `Search failed: ${error.message}`
        };
      }

    case 'addToCart':
      const cart = await api.addToCart(
        toolCall.parameters.productId,
        toolCall.parameters.quantity
      );
      return {
        status: 'success',
        summary: `Added to cart. Total: $${cart.total}`
      };

    default:
      return {
        status: 'error',
        summary: `Unknown action: ${toolCall.tooName}`
      };
  }
};

Context Management

The SDK automatically manages context changes and injects them as system messages.

interface CurrentContext {
  userId: string;
  userName?: string;
  userPreferences?: string;
  userRecentActivity?: string;
  interfaceState: {
    currentPageName: string;
    currentPageUrl?: string;
    currentPageDescription?: string;
    viewingItems?: Array<{
      id: string;
      name: string;
      type: string;
      price: number;
      description?: string;
      characteristics?: string;
    }>;
  };
}

Example:

const currentContext = {
  userId: 'user-123',
  userName: 'John Doe',
  userPreferences: 'Prefers eco-friendly products',
  interfaceState: {
    currentPageName: 'Products',
    currentPageUrl: '/products/t-shirts',
    viewingItems: [
      {
        id: 'SKU-001',
        name: 'Organic Cotton Tee',
        type: 't-shirt',
        price: 15.99,
        description: '100% organic cotton'
      }
    ]
  }
};

TypeScript Support

The SDK is written in TypeScript and provides full type definitions.

import type {
  ToolCall,
  ToolResult,
  InterfaceState,
  ChatMessage,
  Theme
} from 'reactbridge-sdk';

Examples

See the /examples directory for complete implementations:

• E-commerce Demo - Full shopping experience with product search, filtering, and cart management
• Custom UI - Building your own interface using the core hook
• Theming - Examples of custom themes and styling

License

MIT

Support

• Documentation: https://github.com/MrWest/react-bridge-sdk
• Issues: https://github.com/MrWest/react-bridge-sdk/issues

Built with ❤️ by the ReactBridge team