@sentra/chat-widget

A reusable React chat widget for integrating Sentra Platform's AI chat interface into your applications. This package provides a complete chat interface that handles both regular conversations and workflow UI nodes with full-screen visualization.

Features

• 🚀 Easy Integration: Just pass sentraUrl, userId, and projectId
• 💬 Full Chat Interface: Complete chat UI with message history, typing indicators, and error handling
• 🎨 Rich Response Rendering: Automatically renders tables, cards, lists, markdown, HTML, and JSON
• ⚙️ Workflow Visualization: Full-screen modal for workflow UI nodes
• 🔒 Type-Safe: Built with TypeScript for better developer experience
• 🎯 Zero Configuration: Works out of the box with minimal setup

Installation

npm install @sentra/chat-widget
# or
yarn add @sentra/chat-widget
# or
pnpm add @sentra/chat-widget

Quick Start

import React from 'react';
import { ChatWidget } from '@sentra/chat-widget';

function App() {
  return (
    <div style={{ height: '100vh' }}>
      <ChatWidget
        sentraUrl="http://localhost:3002"
        userId="user-123"
        projectId="project-456"
        sessionId="session-789"
      />
    </div>
  );
}

Props

ChatWidget

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | sentraUrl | string | Yes | - | Base URL of your Sentra Platform instance | | userId | string | Yes | - | Unique identifier for the user | | projectId | string | Yes | - | Project ID in Sentra Platform | | sessionId | string | No | sess_${Date.now()} | Session identifier for conversation grouping | | className | string | No | '' | Additional CSS classes for the widget container | | onError | (error: Error) => void | No | - | Callback function for error handling |

Usage Examples

Basic Usage

import { ChatWidget } from '@sentra/chat-widget';

function MyApp() {
  return (
    <div style={{ height: '600px', width: '800px' }}>
      <ChatWidget
        sentraUrl="https://api.sentra.example.com"
        userId="user-123"
        projectId="project-456"
      />
    </div>
  );
}

With Error Handling

import { ChatWidget } from '@sentra/chat-widget';

function MyApp() {
  const handleError = (error: Error) => {
    console.error('Chat error:', error);
    // Send to error tracking service
  };

  return (
    <ChatWidget
      sentraUrl="https://api.sentra.example.com"
      userId="user-123"
      projectId="project-456"
      onError={handleError}
    />
  );
}

Custom Styling

import { ChatWidget } from '@sentra/chat-widget';

function MyApp() {
  return (
    <div className="my-custom-container">
      <ChatWidget
        sentraUrl="https://api.sentra.example.com"
        userId="user-123"
        projectId="project-456"
        className="custom-chat-widget"
      />
    </div>
  );
}

How It Works

Normal Chat Messages

Regular chat messages (text, markdown, structured data) are displayed in the chat panel using the MessageList component. The widget automatically detects and renders:

• Text: Plain text messages
• Markdown: Formatted markdown with syntax highlighting
• HTML: Sanitized HTML content
• JSON: Formatted JSON with syntax highlighting
• Structured Responses: Tables, cards, and lists

Workflow UI Nodes

When a workflow UI node is detected in the response, the widget automatically:

1. Extracts the UI node data from the message
2. Opens a full-screen modal (WorkflowFullScreenModal)
3. Renders the workflow visualization using UINodeRenderer
4. Allows users to close the modal and return to chat

The workflow modal provides a full-screen experience optimized for viewing complex workflow visualizations.

Response Types

The widget supports various response types:

Structured Responses

{
  "type": "table",
  "content": [
    { "name": "John", "age": 30 },
    { "name": "Jane", "age": 25 }
  ],
  "metadata": {
    "title": "Users"
  }
}

Table Response

{
  "type": "table",
  "content": [
    { "column1": "value1", "column2": "value2" }
  ]
}

Card Response

{
  "type": "card",
  "content": {
    "title": "Product",
    "description": "Product description",
    "price": 99.99
  }
}

List Response

{
  "type": "list",
  "content": ["Item 1", "Item 2", "Item 3"]
}

Advanced Usage

Using Individual Components

You can also use individual components if you need more control:

import {
  MessageList,
  MessageBubble,
  ResponseRenderer,
  UINodeRenderer,
  WorkflowFullScreenModal
} from '@sentra/chat-widget';

function CustomChat() {
  // Use individual components to build custom UI
  return (
    <div>
      <MessageList messages={messages} />
      {/* Your custom implementation */}
    </div>
  );
}

Using the Service Directly

import { SentraChatService } from '@sentra/chat-widget';

const service = new SentraChatService('https://api.sentra.example.com');

// Send a query
const result = await service.sendQuery(
  'Hello, how can you help?',
  'user-123',
  'project-456'
);

// Get messages
const messages = await service.getMessages(conversationId);

Styling

The widget uses Tailwind CSS classes. If you're not using Tailwind in your project, you'll need to include it:

npm install tailwindcss

Or you can customize the styles by overriding the classes. The widget uses standard Tailwind utility classes that can be customized.

TypeScript Support

Full TypeScript support is included. Import types as needed:

import type {
  ChatWidgetProps,
  ChatMessage,
  Conversation,
  WorkflowData
} from '@sentra/chat-widget';

Requirements

• React 18.0.0 or higher
• React DOM 18.0.0 or higher
• A running Sentra Platform instance

API Endpoints

The widget expects the following API endpoints to be available:

• POST /api/v1/query - Send a query
• GET /api/v1/chat/conversations - List conversations
• POST /api/v1/chat/conversations - Create conversation
• GET /api/v1/chat/conversations/:id/messages - Get messages
• POST /api/v1/chat/conversations/:id/end - End conversation

Error Handling

Errors are handled gracefully:

• Network errors show user-friendly messages
• API errors are displayed in the chat interface
• The onError callback is called for all errors
• Error messages are added to the chat history

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Development mode with watch
pnpm dev

# Type check
pnpm type-check

# Lint
pnpm lint

License

MIT

Support

For issues and questions, please visit the Sentra Platform repository.

Contributing

Contributions are welcome! Please see the main repository for contributing guidelines.