;\n clearMessages: () => void;\n error: Error | null;\n}\n```\n\n**Example:**\n\n```tsx\nimport { useReactBridge } from 'reactbridge-sdk';\n\nfunction CustomChat() {\n const { messages, isLoading, sendChatQuery } = useReactBridge({\n onIntentDetected: handleAction,\n currentContext: interfaceState\n });\n\n return (\n \n {messages.map(msg => )}\n sendChatQuery(q)} disabled={isLoading} />\n
\n );\n}\n```\n\n## Analytics Suite\n\nThe SDK ships with DirectivSys analytics components for visualizing AI-generated metrics, observations, and directives and for executing recommended actions.\n\n### Components\n\n- `AnalyticsWidget` ā Floating entry point that opens a drawer of analytics configs; best for adding analytics everywhere in your admin UI.\n- `AnalyticsReport` ā Full report view for a single `analyticsType` (metrics, observations, directives) with optional back/close controls.\n- `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.\n\n```tsx\nimport {\n ReactBridgeProvider,\n AnalyticsWidget,\n AnalyticsReport,\n AnalyticsDashboard,\n} from 'reactbridge-sdk';\n\nconst handleDirectiveAction = async (directive, action) => {\n if (action === 'decline') return { success: true };\n\n // Execute the directive in your system\n const result = await api.executeDirective(directive);\n return { success: result.ok, error: result.error };\n};\n\nfunction Admin() {\n return (\n \n \n\n \n\n \n \n );\n}\n```\n\n**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).\n\n### Analytics Hooks\n\n- `useAnalyticsConfigs()` ā Fetches all analytics configs (`configs`, `isLoading`, `error`, `refetch`).\n- `useAnalyticsResult(analyticsType)` ā Fetches the latest result for a given analytics type (`result`, `isLoading`, `error`, `refetch`).\n- `useDirectiveAction(onDirectiveAction?)` ā Wraps your handler, updates directive status in the backend, and exposes `handleAction`, `isProcessing`, and `error`.\n\n```tsx\nimport { useAnalyticsConfigs, useAnalyticsResult, useDirectiveAction } from 'reactbridge-sdk';\n\nconst { configs } = useAnalyticsConfigs();\nconst { result, refetch } = useAnalyticsResult('InventoryHealth');\nconst { handleAction, isProcessing } = useDirectiveAction(handleDirectiveAction);\n```\n\n### Analytics API Client\n\n```tsx\nimport { AnalyticsAPI } from 'reactbridge-sdk';\n\nconst api = new AnalyticsAPI({ apiKey: 'your-api-key' });\nconst configs = await api.getConfigs();\nconst result = await api.getLatestResult('InventoryHealth');\nawait api.updateDirectiveStatus(directiveId, 'executed');\n```\n\n### More Docs\n\n- Detailed components and hooks: [ANALYTICS_README.md](ANALYTICS_README.md)\n- Full dashboard guide: [ANALYTICS_DASHBOARD_README.md](ANALYTICS_DASHBOARD_README.md)\n\n## Business Intelligence Reports\n\nThe SDK includes 5 comprehensive REST endpoints for investor-ready analytics with date range filtering and 1-hour caching.\n\n### Available Reports\n\n```tsx\nimport {\n ReactBridgeProvider,\n ExecutiveDashboard,\n SupplyChainRisk,\n ExecutionAuditTrail,\n PortfolioHealth,\n DataQualityAutomation\n} from 'reactbridge-sdk';\n\nfunction ReportsPage() {\n return (\n \n {/* High-level metrics and trends */}\n \n\n {/* Supply chain risk analysis */}\n \n\n {/* Execution history and audit */}\n \n\n {/* Portfolio metric health */}\n \n\n {/* Data quality & automation opportunities */}\n \n \n );\n}\n```\n\n### Reports via Hooks\n\n```tsx\nimport { useReactBridgeContext } from 'reactbridge-sdk';\n\nfunction CustomReport() {\n const { api } = useReactBridgeContext();\n\n // Fetch Executive Dashboard\n const dashboard = await api.getExecutiveDashboard({\n startDate: '2026-01-06',\n endDate: '2026-02-05'\n });\n\n // Fetch Supply Chain Risk\n const risk = await api.getSupplyChainRisk();\n\n // Fetch Execution Audit with filter\n const audit = await api.getExecutionAuditTrail({\n directiveType: 'inventory-rebalance'\n });\n\n // Fetch Portfolio Health\n const health = await api.getPortfolioHealth();\n\n // Fetch Data Quality Assessment\n const quality = await api.getDataQualityAutomation();\n}\n```\n\n### Reports Documentation\n\n- Full API reference: [REPORTS_API.md](REPORTS_API.md)\n- Provider pattern guide: [REPORTS_PROVIDER_PATTERN.md](REPORTS_PROVIDER_PATTERN.md)\n\n### Authentication\n\nAll reports use **X-API-Key** header authentication. Simply pass your API key to `ReactBridgeProvider` and it's automatically used by all endpoints:\n\n```tsx\n\n \n\n```\n\n## Voice Input/Output\n\nThe SDK supports voice input (Speech-to-Text) and voice output (Text-to-Speech) for a fully conversational experience.\n\n### Default Providers\n\nBy default, the SDK uses browser Web Speech APIs:\n- **STT**: `WebSpeechSTTProvider` (SpeechRecognition)\n- **TTS**: `WebSpeechTTSProvider` (speechSynthesis)\n\n### Custom Providers\n\nYou can swap providers for advanced implementations:\n\n```tsx\nimport { ReactBridgeProvider, WebSpeechSTTProvider, WebSpeechTTSProvider } from 'reactbridge-sdk';\n\n// Custom STT Provider\nclass MySTTProvider {\n startRecognition() { /* ... */ }\n stopRecognition() { /* ... */ }\n onResult(callback: (text: string) => void) { /* ... */ }\n}\n\n// Custom TTS Provider\nclass MyTTSProvider {\n speak(text: string) { /* ... */ }\n}\n\n\n \n\n```\n\n### Voice Events\n\n```tsx\nconst { startVoiceInput, stopVoiceInput, isListening } = useReactBridge({\n onIntentDetected: handleAction,\n currentContext: context,\n onSpeechStart: () => console.log('Voice input started'),\n onSpeechEnd: () => console.log('Voice input ended'),\n onTranscript: (text) => console.log('Transcribed:', text),\n onAgentResponse: (response) => console.log('Agent responded:', response),\n});\n```\n\n### Chatbox with Voice\n\nThe `ReactBridgeChatbox` includes a microphone button next to the text input:\n\n```tsx\n\n```\n\n- Click the mic button to start/stop voice recording\n- Transcribed text is automatically sent to the API\n- Agent responses are spoken aloud\n\n## Theming\n\n### Built-in Themes\n\n```tsx\nimport { lightTheme, darkTheme } from 'reactbridge-sdk';\n\n\n \n\n```\n\n### Custom Theme\n\n```tsx\nimport { createCustomTheme, lightTheme } from 'reactbridge-sdk';\n\nconst myTheme = createCustomTheme(lightTheme, {\n colors: {\n primary: '#ff6b6b',\n background: '#f8f9fa'\n },\n fontSizes: {\n md: '18px',\n lg: '22px'\n },\n spacing: {\n md: '20px'\n }\n});\n\n\n \n\n```\n\n### Theme Structure\n\n```typescript\ninterface Theme {\n name: string;\n colors: {\n primary: string;\n secondary: string;\n background: string;\n surface: string;\n text: string;\n textSecondary: string;\n border: string;\n error: string;\n success: string;\n };\n spacing: {\n xs: string;\n sm: string;\n md: string;\n lg: string;\n xl: string;\n };\n fontSizes: {\n xs: string;\n sm: string;\n md: string;\n lg: string;\n xl: string;\n };\n borderRadius: string;\n boxShadow: string;\n}\n```\n\n## Action Execution Contract\n\nThe `onIntentDetected` callback is where you implement your business logic.\n\n### Input: ToolCall\n\n```typescript\ninterface ToolCall {\n toolName: string; // e.g., \"searchProducts\"\n parameters: Record; // e.g., { category: \"t-shirts\" }\n}\n```\n\n### Output: ToolResult\n\n```typescript\ninterface ToolResult {\n status: 'success' | 'error' | 'partial';\n summary: string; // Natural language summary for LLM\n detailed_data?: any; // Optional data preview\n}\n```\n\n### Example Implementation\n\n```tsx\nconst onIntentDetected = async (toolCall) => {\n switch (toolCall.toolName) {\n case 'searchProducts':\n try {\n const results = await api.searchProducts(toolCall.parameters);\n return {\n status: 'success',\n summary: `Found ${results.length} products`,\n detailed_data: { total: results.length, preview: results.slice(0, 3) }\n };\n } catch (error) {\n return {\n status: 'error',\n summary: `Search failed: ${error.message}`\n };\n }\n\n case 'addToCart':\n const cart = await api.addToCart(\n toolCall.parameters.productId,\n toolCall.parameters.quantity\n );\n return {\n status: 'success',\n summary: `Added to cart. Total: $${cart.total}`\n };\n\n default:\n return {\n status: 'error',\n summary: `Unknown action: ${toolCall.tooName}`\n };\n }\n};\n```\n\n## Context Management\n\nThe SDK automatically manages context changes and injects them as system messages.\n\n```typescript\ninterface CurrentContext {\n userId: string;\n userName?: string;\n userPreferences?: string;\n userRecentActivity?: string;\n interfaceState: {\n currentPageName: string;\n currentPageUrl?: string;\n currentPageDescription?: string;\n viewingItems?: Array<{\n id: string;\n name: string;\n type: string;\n price: number;\n description?: string;\n characteristics?: string;\n }>;\n };\n}\n```\n\n**Example:**\n\n```tsx\nconst currentContext = {\n userId: 'user-123',\n userName: 'John Doe',\n userPreferences: 'Prefers eco-friendly products',\n interfaceState: {\n currentPageName: 'Products',\n currentPageUrl: '/products/t-shirts',\n viewingItems: [\n {\n id: 'SKU-001',\n name: 'Organic Cotton Tee',\n type: 't-shirt',\n price: 15.99,\n description: '100% organic cotton'\n }\n ]\n }\n};\n```\n\n## TypeScript Support\n\nThe SDK is written in TypeScript and provides full type definitions.\n\n```tsx\nimport type {\n ToolCall,\n ToolResult,\n InterfaceState,\n ChatMessage,\n Theme\n} from 'reactbridge-sdk';\n```\n\n## Examples\n\nSee the `/examples` directory for complete implementations:\n\n- **E-commerce Demo** - Full shopping experience with product search, filtering, and cart management\n- **Custom UI** - Building your own interface using the core hook\n- **Theming** - Examples of custom themes and styling\n\n## License\n\nMIT\n\n## Support\n\n- **Documentation**: [https://github.com/MrWest/react-bridge-sdk](https://github.com/MrWest/react-bridge-sdk)\n- **Issues**: [https://github.com/MrWest/react-bridge-sdk/issues](https://github.com/MrWest/react-bridge-sdk/issues)\n\n---\n\nBuilt with ā¤ļø by the ReactBridge team\n","readmeFilename":"README.md"}