@astermind/chatbot-template 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +603 -0
- package/dist/astermind-chatbot.css +1 -0
- package/dist/astermind-chatbot.esm.js +891 -0
- package/dist/astermind-chatbot.esm.js.map +1 -0
- package/dist/astermind-chatbot.min.js +21 -0
- package/dist/astermind-chatbot.min.js.map +1 -0
- package/dist/astermind-chatbot.umd.js +915 -0
- package/dist/astermind-chatbot.umd.js.map +1 -0
- package/dist/components/ActionCard.d.ts +12 -0
- package/dist/components/ActionCard.d.ts.map +1 -0
- package/dist/components/ChatBubble.d.ts +12 -0
- package/dist/components/ChatBubble.d.ts.map +1 -0
- package/dist/components/ChatHeader.d.ts +13 -0
- package/dist/components/ChatHeader.d.ts.map +1 -0
- package/dist/components/ChatInput.d.ts +11 -0
- package/dist/components/ChatInput.d.ts.map +1 -0
- package/dist/components/ChatWindow.d.ts +21 -0
- package/dist/components/ChatWindow.d.ts.map +1 -0
- package/dist/components/ChatbotWidget.d.ts +9 -0
- package/dist/components/ChatbotWidget.d.ts.map +1 -0
- package/dist/components/MessageBubble.d.ts +10 -0
- package/dist/components/MessageBubble.d.ts.map +1 -0
- package/dist/components/MessageList.d.ts +11 -0
- package/dist/components/MessageList.d.ts.map +1 -0
- package/dist/components/SourceCitation.d.ts +10 -0
- package/dist/components/SourceCitation.d.ts.map +1 -0
- package/dist/components/StatusIndicator.d.ts +10 -0
- package/dist/components/StatusIndicator.d.ts.map +1 -0
- package/dist/components/TypingIndicator.d.ts +5 -0
- package/dist/components/TypingIndicator.d.ts.map +1 -0
- package/dist/components/index.d.ts +12 -0
- package/dist/components/index.d.ts.map +1 -0
- package/dist/context/ChatContext.d.ts +24 -0
- package/dist/context/ChatContext.d.ts.map +1 -0
- package/dist/context/ThemeContext.d.ts +20 -0
- package/dist/context/ThemeContext.d.ts.map +1 -0
- package/dist/hooks/index.d.ts +5 -0
- package/dist/hooks/index.d.ts.map +1 -0
- package/dist/hooks/useChat.d.ts +21 -0
- package/dist/hooks/useChat.d.ts.map +1 -0
- package/dist/hooks/useOmega.d.ts +27 -0
- package/dist/hooks/useOmega.d.ts.map +1 -0
- package/dist/hooks/useScrollToBottom.d.ts +15 -0
- package/dist/hooks/useScrollToBottom.d.ts.map +1 -0
- package/dist/hooks/useTheme.d.ts +47 -0
- package/dist/hooks/useTheme.d.ts.map +1 -0
- package/dist/index.d.ts +20 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/init.d.ts +11 -0
- package/dist/init.d.ts.map +1 -0
- package/dist/types.d.ts +229 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/utils/markdown.d.ts +7 -0
- package/dist/utils/markdown.d.ts.map +1 -0
- package/dist/utils/time.d.ts +5 -0
- package/dist/utils/time.d.ts.map +1 -0
- package/package.json +99 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 AsterMind Team
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,603 @@
|
|
|
1
|
+
# @astermind/chatbot-template
|
|
2
|
+
|
|
3
|
+
Embeddable AI chatbot widget for [AsterMind](https://astermind.ai) RAG - a drop-in chat UI that connects to your AsterMind backend with full agentic capabilities.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@astermind/chatbot-template)
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Table of Contents
|
|
11
|
+
|
|
12
|
+
- [Features](#features)
|
|
13
|
+
- [Installation](#installation)
|
|
14
|
+
- [Quick Start](#quick-start)
|
|
15
|
+
- [Configuration Reference](#configuration-reference)
|
|
16
|
+
- [Cybernetic Chatbot Integration](#cybernetic-chatbot-integration)
|
|
17
|
+
- [Theming](#theming)
|
|
18
|
+
- [React Hooks API](#react-hooks-api)
|
|
19
|
+
- [Components API](#components-api)
|
|
20
|
+
- [TypeScript Support](#typescript-support)
|
|
21
|
+
- [Troubleshooting](#troubleshooting)
|
|
22
|
+
- [Browser Support](#browser-support)
|
|
23
|
+
- [License](#license)
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Features
|
|
28
|
+
|
|
29
|
+
### Core Widget Features
|
|
30
|
+
|
|
31
|
+
- **Embeddable Floating Chat Bubble** - Position anywhere on the page (4 corners)
|
|
32
|
+
- **React Components Library** - 11 fully customizable components
|
|
33
|
+
- **Vanilla JS Standalone Bundle** - IIFE format with React bundled for non-React sites
|
|
34
|
+
- **Full TypeScript Support** - Complete type definitions exported
|
|
35
|
+
|
|
36
|
+
### RAG Integration
|
|
37
|
+
|
|
38
|
+
- **AsterMind Backend Integration** - Connects to `/api/external/chat` endpoints
|
|
39
|
+
- **Streaming Responses** - SSE-based token-by-token message display
|
|
40
|
+
- **Source Citations** - Collapsible source references with confidence levels
|
|
41
|
+
- **Session Management** - Automatic sessionId handling across conversations
|
|
42
|
+
- **Confidence Indicators** - Visual display of high/medium/low/none confidence
|
|
43
|
+
|
|
44
|
+
### Agentic Capabilities
|
|
45
|
+
|
|
46
|
+
- **Navigation Actions** - Navigate users to specific pages
|
|
47
|
+
- **Form Filling** - Auto-fill form fields with suggested values
|
|
48
|
+
- **Element Clicking** - Programmatically click buttons and links
|
|
49
|
+
- **Modal Triggering** - Open dialogs and modals
|
|
50
|
+
- **Scrolling** - Scroll to specific elements
|
|
51
|
+
- **Element Highlighting** - Draw attention to page elements
|
|
52
|
+
- **Custom Action Handlers** - Define your own action types
|
|
53
|
+
- **Action Cards UI** - Confirm/cancel interface for proposed actions
|
|
54
|
+
- **Confidence Thresholds** - Auto-execute high-confidence actions
|
|
55
|
+
- **Site Map Configuration** - Define navigable pages for the agent
|
|
56
|
+
|
|
57
|
+
### Offline & Fallback
|
|
58
|
+
|
|
59
|
+
- **Graceful Degradation** - Works when connection is lost
|
|
60
|
+
- **Custom Offline Message** - Configure what users see offline
|
|
61
|
+
- **Connection Status Indicator** - Shows online/offline/connecting/error states
|
|
62
|
+
- **Optional Local RAG Fallback** - Use Cybernetic RAG locally when offline
|
|
63
|
+
|
|
64
|
+
### Theming & Customization
|
|
65
|
+
|
|
66
|
+
- **20+ CSS Custom Properties** - Full visual customization via CSS variables
|
|
67
|
+
- **JavaScript Theme Object** - Configure themes programmatically
|
|
68
|
+
- **4 Position Options** - bottom-right, bottom-left, top-right, top-left
|
|
69
|
+
- **Configurable Dimensions** - Width, height, bubble size
|
|
70
|
+
- **Full Color Customization** - Every color is customizable
|
|
71
|
+
- **Typography Settings** - Font family and size
|
|
72
|
+
- **Border Radius & Shadows** - Visual effects customization
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## Installation
|
|
77
|
+
|
|
78
|
+
### NPM (React Projects)
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
npm install @astermind/chatbot-template
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### CDN (Vanilla JS)
|
|
85
|
+
|
|
86
|
+
```html
|
|
87
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@astermind/chatbot-template/dist/astermind-chatbot.css">
|
|
88
|
+
<script src="https://cdn.jsdelivr.net/npm/@astermind/chatbot-template/dist/astermind-chatbot.min.js"></script>
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## Quick Start
|
|
94
|
+
|
|
95
|
+
### React Usage
|
|
96
|
+
|
|
97
|
+
```tsx
|
|
98
|
+
import { ChatbotWidget } from '@astermind/chatbot-template';
|
|
99
|
+
import '@astermind/chatbot-template/styles';
|
|
100
|
+
|
|
101
|
+
function App() {
|
|
102
|
+
return (
|
|
103
|
+
<ChatbotWidget
|
|
104
|
+
apiUrl="https://your-api-url.com"
|
|
105
|
+
apiKey="am_your-api-key"
|
|
106
|
+
position="bottom-right"
|
|
107
|
+
greeting="Hi! How can I help you today?"
|
|
108
|
+
/>
|
|
109
|
+
);
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Vanilla JS Usage
|
|
114
|
+
|
|
115
|
+
```html
|
|
116
|
+
<!DOCTYPE html>
|
|
117
|
+
<html>
|
|
118
|
+
<head>
|
|
119
|
+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@astermind/chatbot-template/dist/astermind-chatbot.css">
|
|
120
|
+
</head>
|
|
121
|
+
<body>
|
|
122
|
+
<script src="https://cdn.jsdelivr.net/npm/@astermind/chatbot-template/dist/astermind-chatbot.min.js"></script>
|
|
123
|
+
<script>
|
|
124
|
+
AsterMindChatbot.init({
|
|
125
|
+
apiUrl: 'https://your-api-url.com',
|
|
126
|
+
apiKey: 'am_your-api-key',
|
|
127
|
+
position: 'bottom-right',
|
|
128
|
+
greeting: 'Hi! How can I help you today?'
|
|
129
|
+
});
|
|
130
|
+
</script>
|
|
131
|
+
</body>
|
|
132
|
+
</html>
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## Configuration Reference
|
|
138
|
+
|
|
139
|
+
### Required Options
|
|
140
|
+
|
|
141
|
+
| Option | Type | Description |
|
|
142
|
+
|--------|------|-------------|
|
|
143
|
+
| `apiKey` | `string` | Your AsterMind API key (starts with `am_`) |
|
|
144
|
+
| `apiUrl` | `string` | Backend API URL (e.g., `https://api.example.com`) |
|
|
145
|
+
|
|
146
|
+
### Widget Options
|
|
147
|
+
|
|
148
|
+
| Option | Type | Default | Description |
|
|
149
|
+
|--------|------|---------|-------------|
|
|
150
|
+
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Widget position on screen |
|
|
151
|
+
| `greeting` | `string` | `'Hi! How can I help you today?'` | Initial greeting message |
|
|
152
|
+
| `placeholder` | `string` | `'Type your message...'` | Input placeholder text |
|
|
153
|
+
| `headerTitle` | `string` | `'AsterMind'` | Chat window header title |
|
|
154
|
+
| `headerSubtitle` | `string` | `'AI Assistant'` | Chat window header subtitle |
|
|
155
|
+
| `defaultOpen` | `boolean` | `false` | Start with chat window open |
|
|
156
|
+
| `showPoweredBy` | `boolean` | `true` | Show "Powered by AsterMind" badge |
|
|
157
|
+
| `zIndex` | `number` | `9999` | Z-index for the widget |
|
|
158
|
+
|
|
159
|
+
### Theme Options
|
|
160
|
+
|
|
161
|
+
Customize appearance via the `theme` object:
|
|
162
|
+
|
|
163
|
+
```javascript
|
|
164
|
+
{
|
|
165
|
+
theme: {
|
|
166
|
+
primaryColor: '#4F46E5', // Primary brand color
|
|
167
|
+
primaryHover: '#4338CA', // Primary color on hover
|
|
168
|
+
backgroundColor: '#ffffff', // Background color
|
|
169
|
+
surfaceColor: '#f3f4f6', // Surface/card background
|
|
170
|
+
textColor: '#1f2937', // Primary text color
|
|
171
|
+
textMuted: '#6b7280', // Muted/secondary text
|
|
172
|
+
borderColor: '#e5e7eb', // Border color
|
|
173
|
+
userBubbleBackground: '#4F46E5', // User message background
|
|
174
|
+
userBubbleText: '#ffffff', // User message text
|
|
175
|
+
botBubbleBackground: '#f3f4f6', // Bot message background
|
|
176
|
+
botBubbleText: '#1f2937', // Bot message text
|
|
177
|
+
widgetWidth: '380px', // Widget width
|
|
178
|
+
widgetHeight: '520px', // Widget height
|
|
179
|
+
bubbleSize: '60px', // Trigger bubble size
|
|
180
|
+
borderRadius: '12px', // Border radius
|
|
181
|
+
fontFamily: "'Inter', system-ui, sans-serif",
|
|
182
|
+
fontSize: '14px',
|
|
183
|
+
shadow: '0 4px 20px rgba(0, 0, 0, 0.15)'
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
### Agent Configuration
|
|
189
|
+
|
|
190
|
+
Enable agentic capabilities:
|
|
191
|
+
|
|
192
|
+
```javascript
|
|
193
|
+
{
|
|
194
|
+
agent: {
|
|
195
|
+
enabled: true,
|
|
196
|
+
confidenceThreshold: 0.8, // Minimum confidence for auto-execution
|
|
197
|
+
siteMap: [
|
|
198
|
+
{ path: '/products', name: 'Products', description: 'View products' },
|
|
199
|
+
{ path: '/contact', name: 'Contact', description: 'Contact us' },
|
|
200
|
+
{ path: '/pricing', name: 'Pricing', description: 'View pricing plans' }
|
|
201
|
+
],
|
|
202
|
+
customActions: {
|
|
203
|
+
openModal: async (params) => {
|
|
204
|
+
// Custom action handler - open a modal
|
|
205
|
+
document.getElementById(params.modalId).showModal();
|
|
206
|
+
},
|
|
207
|
+
trackEvent: async (params) => {
|
|
208
|
+
// Custom analytics tracking
|
|
209
|
+
analytics.track(params.eventName, params.data);
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
### Fallback Configuration
|
|
217
|
+
|
|
218
|
+
Configure offline behavior:
|
|
219
|
+
|
|
220
|
+
```javascript
|
|
221
|
+
{
|
|
222
|
+
fallback: {
|
|
223
|
+
enabled: true,
|
|
224
|
+
message: 'Working in offline mode. Some features may be limited.'
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
### Event Callbacks
|
|
230
|
+
|
|
231
|
+
| Callback | Parameters | Description |
|
|
232
|
+
|----------|------------|-------------|
|
|
233
|
+
| `onReady` | `()` | Called when widget is ready |
|
|
234
|
+
| `onMessage` | `(message: ChatMessage)` | Called on each message sent/received |
|
|
235
|
+
| `onAction` | `(action: AgentAction)` | Called when an agentic action occurs |
|
|
236
|
+
| `onError` | `(error: Error)` | Called when an error occurs |
|
|
237
|
+
| `onToggle` | `(isOpen: boolean)` | Called when widget opens/closes |
|
|
238
|
+
|
|
239
|
+
---
|
|
240
|
+
|
|
241
|
+
## Cybernetic Chatbot Integration
|
|
242
|
+
|
|
243
|
+
This widget is designed to work seamlessly with the `@astermind/cybernetic-chatbot-client` for advanced RAG capabilities.
|
|
244
|
+
|
|
245
|
+
### How It Works
|
|
246
|
+
|
|
247
|
+
1. **Widget sends messages** to your AsterMind backend via the configured `apiUrl`
|
|
248
|
+
2. **Backend processes queries** using your RAG pipeline and returns responses
|
|
249
|
+
3. **Streaming responses** arrive via Server-Sent Events (SSE) for real-time display
|
|
250
|
+
4. **Agentic actions** are proposed by the AI and confirmed via Action Cards
|
|
251
|
+
|
|
252
|
+
### API Endpoints
|
|
253
|
+
|
|
254
|
+
The widget connects to these backend endpoints:
|
|
255
|
+
|
|
256
|
+
| Endpoint | Method | Description |
|
|
257
|
+
|----------|--------|-------------|
|
|
258
|
+
| `/api/external/health` | GET | Health check, verifies connection |
|
|
259
|
+
| `/api/external/chat` | POST | Non-streaming chat endpoint |
|
|
260
|
+
| `/api/external/chat/stream` | POST | Streaming chat endpoint (SSE) |
|
|
261
|
+
|
|
262
|
+
### SSE Event Format
|
|
263
|
+
|
|
264
|
+
```
|
|
265
|
+
data: {"type": "chunk", "content": "Hello"}
|
|
266
|
+
data: {"type": "chunk", "content": " there!"}
|
|
267
|
+
data: {"type": "sources", "sources": [{"title": "Doc", "url": "..."}]}
|
|
268
|
+
data: {"type": "action", "action": {"type": "navigate", "path": "/products"}}
|
|
269
|
+
data: {"type": "done", "sessionId": "sess_xxx"}
|
|
270
|
+
data: {"type": "error", "error": "Error message"}
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
### Offline Fallback
|
|
274
|
+
|
|
275
|
+
When offline or disconnected:
|
|
276
|
+
|
|
277
|
+
1. Widget shows connection status indicator
|
|
278
|
+
2. Custom offline message is displayed
|
|
279
|
+
3. If `@astermind/cybernetic-chatbot-client` is installed with local RAG enabled, queries can still be processed locally
|
|
280
|
+
|
|
281
|
+
---
|
|
282
|
+
|
|
283
|
+
## Theming
|
|
284
|
+
|
|
285
|
+
### CSS Variables
|
|
286
|
+
|
|
287
|
+
Override CSS variables in your stylesheet for quick customization:
|
|
288
|
+
|
|
289
|
+
```css
|
|
290
|
+
:root {
|
|
291
|
+
/* Colors */
|
|
292
|
+
--astermind-primary: #10B981;
|
|
293
|
+
--astermind-primary-hover: #059669;
|
|
294
|
+
--astermind-background: #ffffff;
|
|
295
|
+
--astermind-surface: #f3f4f6;
|
|
296
|
+
--astermind-text: #1f2937;
|
|
297
|
+
--astermind-text-muted: #6b7280;
|
|
298
|
+
--astermind-border: #e5e7eb;
|
|
299
|
+
|
|
300
|
+
/* User messages */
|
|
301
|
+
--astermind-user-bubble-bg: #10B981;
|
|
302
|
+
--astermind-user-bubble-text: #ffffff;
|
|
303
|
+
|
|
304
|
+
/* Bot messages */
|
|
305
|
+
--astermind-bot-bubble-bg: #f3f4f6;
|
|
306
|
+
--astermind-bot-bubble-text: #1f2937;
|
|
307
|
+
|
|
308
|
+
/* Dimensions */
|
|
309
|
+
--astermind-widget-width: 400px;
|
|
310
|
+
--astermind-widget-height: 600px;
|
|
311
|
+
--astermind-bubble-size: 64px;
|
|
312
|
+
|
|
313
|
+
/* Effects */
|
|
314
|
+
--astermind-border-radius: 16px;
|
|
315
|
+
--astermind-shadow: 0 8px 32px rgba(0, 0, 0, 0.12);
|
|
316
|
+
|
|
317
|
+
/* Typography */
|
|
318
|
+
--astermind-font-family: 'Inter', system-ui, sans-serif;
|
|
319
|
+
--astermind-font-size: 14px;
|
|
320
|
+
}
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
### CSS Classes
|
|
324
|
+
|
|
325
|
+
All elements use the `astermind-` prefix for easy targeting:
|
|
326
|
+
|
|
327
|
+
| Class | Element |
|
|
328
|
+
|-------|---------|
|
|
329
|
+
| `.astermind-chatbot` | Main container |
|
|
330
|
+
| `.astermind-bubble` | Floating trigger button |
|
|
331
|
+
| `.astermind-window` | Chat window |
|
|
332
|
+
| `.astermind-header` | Window header |
|
|
333
|
+
| `.astermind-messages` | Message list container |
|
|
334
|
+
| `.astermind-message` | Individual message |
|
|
335
|
+
| `.astermind-message--user` | User message modifier |
|
|
336
|
+
| `.astermind-message--bot` | Bot message modifier |
|
|
337
|
+
| `.astermind-input` | Input area |
|
|
338
|
+
| `.astermind-status` | Status indicator |
|
|
339
|
+
| `.astermind-action-card` | Action confirmation card |
|
|
340
|
+
| `.astermind-sources` | Source citations container |
|
|
341
|
+
|
|
342
|
+
---
|
|
343
|
+
|
|
344
|
+
## React Hooks API
|
|
345
|
+
|
|
346
|
+
### useOmega
|
|
347
|
+
|
|
348
|
+
Direct API client access for custom implementations:
|
|
349
|
+
|
|
350
|
+
```tsx
|
|
351
|
+
import { useOmega } from '@astermind/chatbot-template';
|
|
352
|
+
|
|
353
|
+
function MyComponent() {
|
|
354
|
+
const {
|
|
355
|
+
sendMessage, // Send a message (non-streaming)
|
|
356
|
+
sendMessageStream, // Send a message (streaming)
|
|
357
|
+
connectionStatus, // 'online' | 'offline' | 'connecting' | 'error'
|
|
358
|
+
isProcessing, // Whether a request is in progress
|
|
359
|
+
lastError, // Last error that occurred
|
|
360
|
+
sessionId, // Current session ID
|
|
361
|
+
clearSession // Clear the current session
|
|
362
|
+
} = useOmega({
|
|
363
|
+
apiUrl: 'https://api.example.com',
|
|
364
|
+
apiKey: 'am_your-api-key'
|
|
365
|
+
});
|
|
366
|
+
|
|
367
|
+
const handleSend = async () => {
|
|
368
|
+
const response = await sendMessage('Hello!');
|
|
369
|
+
console.log(response.reply, response.sources);
|
|
370
|
+
};
|
|
371
|
+
|
|
372
|
+
const handleStreamingSend = () => {
|
|
373
|
+
sendMessageStream('Tell me about...', {
|
|
374
|
+
onChunk: (chunk) => console.log('Chunk:', chunk),
|
|
375
|
+
onSources: (sources) => console.log('Sources:', sources),
|
|
376
|
+
onDone: (sessionId) => console.log('Done:', sessionId),
|
|
377
|
+
onError: (error) => console.error('Error:', error)
|
|
378
|
+
});
|
|
379
|
+
};
|
|
380
|
+
}
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
### useChat
|
|
384
|
+
|
|
385
|
+
Chat state management:
|
|
386
|
+
|
|
387
|
+
```tsx
|
|
388
|
+
import { useChat } from '@astermind/chatbot-template';
|
|
389
|
+
|
|
390
|
+
function MyComponent() {
|
|
391
|
+
const {
|
|
392
|
+
messages, // Array of chat messages
|
|
393
|
+
addMessage, // Add a new message
|
|
394
|
+
updateMessage, // Update an existing message
|
|
395
|
+
clearMessages, // Clear all messages
|
|
396
|
+
pendingAction, // Currently pending agent action
|
|
397
|
+
setPendingAction // Set pending action
|
|
398
|
+
} = useChat();
|
|
399
|
+
}
|
|
400
|
+
```
|
|
401
|
+
|
|
402
|
+
### useTheme
|
|
403
|
+
|
|
404
|
+
Theme customization hook:
|
|
405
|
+
|
|
406
|
+
```tsx
|
|
407
|
+
import { useTheme } from '@astermind/chatbot-template';
|
|
408
|
+
|
|
409
|
+
function MyComponent() {
|
|
410
|
+
const { theme, cssVariables } = useTheme({
|
|
411
|
+
primaryColor: '#10B981',
|
|
412
|
+
borderRadius: '16px'
|
|
413
|
+
});
|
|
414
|
+
|
|
415
|
+
// cssVariables contains the CSS custom property declarations
|
|
416
|
+
return <div style={cssVariables}>...</div>;
|
|
417
|
+
}
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
### useScrollToBottom
|
|
421
|
+
|
|
422
|
+
Auto-scroll behavior for message lists:
|
|
423
|
+
|
|
424
|
+
```tsx
|
|
425
|
+
import { useScrollToBottom } from '@astermind/chatbot-template';
|
|
426
|
+
|
|
427
|
+
function MessageList({ messages }) {
|
|
428
|
+
const { containerRef, scrollToBottom } = useScrollToBottom();
|
|
429
|
+
|
|
430
|
+
return (
|
|
431
|
+
<div ref={containerRef}>
|
|
432
|
+
{messages.map(msg => <Message key={msg.id} {...msg} />)}
|
|
433
|
+
</div>
|
|
434
|
+
);
|
|
435
|
+
}
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
---
|
|
439
|
+
|
|
440
|
+
## Components API
|
|
441
|
+
|
|
442
|
+
All components are exported for custom compositions:
|
|
443
|
+
|
|
444
|
+
```tsx
|
|
445
|
+
import {
|
|
446
|
+
ChatbotWidget, // Main widget (includes bubble + window)
|
|
447
|
+
ChatBubble, // Floating trigger button
|
|
448
|
+
ChatWindow, // Chat window container
|
|
449
|
+
ChatHeader, // Window header with title/subtitle
|
|
450
|
+
ChatInput, // Message input with send button
|
|
451
|
+
MessageList, // Scrollable message container
|
|
452
|
+
MessageBubble, // Individual message bubble
|
|
453
|
+
ActionCard, // Agentic action confirmation card
|
|
454
|
+
SourceCitation, // Source reference component
|
|
455
|
+
StatusIndicator, // Connection status display
|
|
456
|
+
TypingIndicator // Typing/loading animation
|
|
457
|
+
} from '@astermind/chatbot-template';
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
### Component Example
|
|
461
|
+
|
|
462
|
+
Build a custom chat interface:
|
|
463
|
+
|
|
464
|
+
```tsx
|
|
465
|
+
import {
|
|
466
|
+
ChatWindow,
|
|
467
|
+
ChatHeader,
|
|
468
|
+
MessageList,
|
|
469
|
+
MessageBubble,
|
|
470
|
+
ChatInput,
|
|
471
|
+
StatusIndicator
|
|
472
|
+
} from '@astermind/chatbot-template';
|
|
473
|
+
import '@astermind/chatbot-template/styles';
|
|
474
|
+
|
|
475
|
+
function CustomChat({ messages, onSend, status }) {
|
|
476
|
+
return (
|
|
477
|
+
<ChatWindow>
|
|
478
|
+
<ChatHeader
|
|
479
|
+
title="Support Bot"
|
|
480
|
+
subtitle="Always here to help"
|
|
481
|
+
/>
|
|
482
|
+
<StatusIndicator status={status} />
|
|
483
|
+
<MessageList>
|
|
484
|
+
{messages.map(msg => (
|
|
485
|
+
<MessageBubble
|
|
486
|
+
key={msg.id}
|
|
487
|
+
content={msg.content}
|
|
488
|
+
role={msg.role}
|
|
489
|
+
timestamp={msg.timestamp}
|
|
490
|
+
/>
|
|
491
|
+
))}
|
|
492
|
+
</MessageList>
|
|
493
|
+
<ChatInput
|
|
494
|
+
onSend={onSend}
|
|
495
|
+
placeholder="Ask a question..."
|
|
496
|
+
/>
|
|
497
|
+
</ChatWindow>
|
|
498
|
+
);
|
|
499
|
+
}
|
|
500
|
+
```
|
|
501
|
+
|
|
502
|
+
---
|
|
503
|
+
|
|
504
|
+
## TypeScript Support
|
|
505
|
+
|
|
506
|
+
Full TypeScript support with exported types:
|
|
507
|
+
|
|
508
|
+
```typescript
|
|
509
|
+
import type {
|
|
510
|
+
// Configuration
|
|
511
|
+
ChatbotConfig,
|
|
512
|
+
ThemeConfig,
|
|
513
|
+
AgentConfig,
|
|
514
|
+
FallbackConfig,
|
|
515
|
+
|
|
516
|
+
// Messages
|
|
517
|
+
ChatMessage,
|
|
518
|
+
MessageRole,
|
|
519
|
+
|
|
520
|
+
// Actions
|
|
521
|
+
AgentAction,
|
|
522
|
+
ActionType,
|
|
523
|
+
NavigateAction,
|
|
524
|
+
FormFillAction,
|
|
525
|
+
ClickAction,
|
|
526
|
+
|
|
527
|
+
// Sources
|
|
528
|
+
Source,
|
|
529
|
+
SourceCitation,
|
|
530
|
+
|
|
531
|
+
// Status
|
|
532
|
+
ConnectionStatus,
|
|
533
|
+
|
|
534
|
+
// Events
|
|
535
|
+
ChatbotCallbacks
|
|
536
|
+
} from '@astermind/chatbot-template';
|
|
537
|
+
```
|
|
538
|
+
|
|
539
|
+
---
|
|
540
|
+
|
|
541
|
+
## Troubleshooting
|
|
542
|
+
|
|
543
|
+
### Widget not appearing
|
|
544
|
+
|
|
545
|
+
1. Ensure styles are imported: `import '@astermind/chatbot-template/styles'`
|
|
546
|
+
2. Check that `apiUrl` and `apiKey` are provided
|
|
547
|
+
3. Verify the widget container has `position: relative` or is in the document flow
|
|
548
|
+
|
|
549
|
+
### Connection errors
|
|
550
|
+
|
|
551
|
+
1. Check that your `apiUrl` is correct and accessible
|
|
552
|
+
2. Verify your API key is valid and has the correct permissions
|
|
553
|
+
3. Check browser console for CORS errors - ensure your backend allows the origin
|
|
554
|
+
|
|
555
|
+
### Streaming not working
|
|
556
|
+
|
|
557
|
+
1. Verify your backend supports the `/api/external/chat/stream` endpoint
|
|
558
|
+
2. Check that SSE is not being blocked by proxies or firewalls
|
|
559
|
+
3. Ensure `Content-Type: text/event-stream` header is set on responses
|
|
560
|
+
|
|
561
|
+
### Actions not executing
|
|
562
|
+
|
|
563
|
+
1. Confirm `agent.enabled` is set to `true`
|
|
564
|
+
2. Check that actions meet the `confidenceThreshold`
|
|
565
|
+
3. Verify custom action handlers are properly defined
|
|
566
|
+
|
|
567
|
+
### Styles not applying
|
|
568
|
+
|
|
569
|
+
1. Ensure the CSS file is loaded before the JS
|
|
570
|
+
2. Check for CSS specificity conflicts with your existing styles
|
|
571
|
+
3. Use `!important` or increase specificity if needed
|
|
572
|
+
|
|
573
|
+
---
|
|
574
|
+
|
|
575
|
+
## Browser Support
|
|
576
|
+
|
|
577
|
+
| Browser | Version |
|
|
578
|
+
|---------|---------|
|
|
579
|
+
| Chrome | 80+ |
|
|
580
|
+
| Firefox | 75+ |
|
|
581
|
+
| Safari | 13+ |
|
|
582
|
+
| Edge | 80+ |
|
|
583
|
+
|
|
584
|
+
The standalone bundle includes necessary polyfills for broader compatibility.
|
|
585
|
+
|
|
586
|
+
---
|
|
587
|
+
|
|
588
|
+
## Build Outputs
|
|
589
|
+
|
|
590
|
+
| File | Format | Description |
|
|
591
|
+
|------|--------|-------------|
|
|
592
|
+
| `astermind-chatbot.esm.js` | ESM | ES Module for bundlers (tree-shakeable) |
|
|
593
|
+
| `astermind-chatbot.umd.js` | UMD | Universal Module Definition |
|
|
594
|
+
| `astermind-chatbot.min.js` | IIFE | Standalone bundle with React included |
|
|
595
|
+
| `astermind-chatbot.css` | CSS | Compiled and minified styles |
|
|
596
|
+
|
|
597
|
+
---
|
|
598
|
+
|
|
599
|
+
## License
|
|
600
|
+
|
|
601
|
+
MIT License - see [LICENSE](LICENSE) for details.
|
|
602
|
+
|
|
603
|
+
Built with care by the [AsterMind](https://astermind.ai) team.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
:root{--astermind-primary:#4f46e5;--astermind-primary-hover:#4338ca;--astermind-background:#fff;--astermind-surface:#f3f4f6;--astermind-text:#1f2937;--astermind-text-muted:#6b7280;--astermind-border:#e5e7eb;--astermind-user-bg:#4f46e5;--astermind-user-text:#fff;--astermind-bot-bg:#f3f4f6;--astermind-bot-text:#1f2937;--astermind-widget-width:380px;--astermind-widget-height:520px;--astermind-bubble-size:60px;--astermind-border-radius:12px;--astermind-font-family:"Inter",system-ui,-apple-system,sans-serif;--astermind-font-size:14px;--astermind-shadow:0 4px 20px rgba(0,0,0,.15)}.astermind-chatbot,.astermind-chatbot *{box-sizing:border-box;margin:0;padding:0}.astermind-chatbot{font-family:var(--astermind-font-family);font-size:var(--astermind-font-size);position:fixed;z-index:9999}.astermind-chatbot--bottom-right{bottom:20px;right:20px}.astermind-chatbot--bottom-left{bottom:20px;left:20px}.astermind-chatbot--top-right{right:20px;top:20px}.astermind-chatbot--top-left{left:20px;top:20px}.astermind-bubble{align-items:center;background:var(--astermind-primary);border:none;border-radius:50%;box-shadow:var(--astermind-shadow);color:#fff;cursor:pointer;display:flex;height:var(--astermind-bubble-size);justify-content:center;transition:transform .2s,background-color .2s;width:var(--astermind-bubble-size)}.astermind-bubble:hover{background:var(--astermind-primary-hover);transform:scale(1.05)}.astermind-bubble__icon{height:28px;width:28px}.astermind-bubble__badge{align-items:center;background:#ef4444;border-radius:10px;color:#fff;display:flex;font-size:12px;font-weight:600;height:20px;justify-content:center;min-width:20px;padding:0 6px;position:absolute;right:-4px;top:-4px}.astermind-window{animation:astermind-slide-up .3s ease-out;background:var(--astermind-background);border-radius:var(--astermind-border-radius);box-shadow:var(--astermind-shadow);display:flex;flex-direction:column;height:var(--astermind-widget-height);overflow:hidden;width:var(--astermind-widget-width)}@keyframes astermind-slide-up{0%{opacity:0;transform:translateY(20px)}to{opacity:1;transform:translateY(0)}}.astermind-header{align-items:center;background:var(--astermind-primary);color:#fff;display:flex;justify-content:space-between;padding:16px}.astermind-header__info{flex:1}.astermind-header__title{font-size:16px;font-weight:600;margin:0}.astermind-header__subtitle{font-size:12px;margin:2px 0 0;opacity:.9}.astermind-header__actions{align-items:center;display:flex;gap:8px}.astermind-header__close{align-items:center;background:hsla(0,0%,100%,.2);border:none;border-radius:50%;color:#fff;cursor:pointer;display:flex;height:32px;justify-content:center;transition:background-color .2s;width:32px}.astermind-header__close:hover{background:hsla(0,0%,100%,.3)}.astermind-header__close svg{height:18px;width:18px}.astermind-window__body{display:flex;flex:1;flex-direction:column;overflow:hidden}.astermind-messages{display:flex;flex:1;flex-direction:column;gap:12px;overflow-y:auto;padding:16px}.astermind-message{display:flex;flex-direction:column;max-width:85%}.astermind-message--user{align-items:flex-end;align-self:flex-end}.astermind-message--assistant{align-items:flex-start;align-self:flex-start}.astermind-message__bubble{border-radius:16px;padding:10px 14px;word-wrap:break-word}.astermind-message--user .astermind-message__bubble{background:var(--astermind-user-bg);border-bottom-right-radius:4px;color:var(--astermind-user-text)}.astermind-message--assistant .astermind-message__bubble{background:var(--astermind-bot-bg);border-bottom-left-radius:4px;color:var(--astermind-bot-text)}.astermind-message__content{line-height:1.5}.astermind-message__content a{color:inherit;text-decoration:underline}.astermind-message__content code{background:rgba(0,0,0,.1);border-radius:4px;font-family:monospace;font-size:.9em;padding:2px 6px}.astermind-message__meta{color:var(--astermind-text-muted);display:flex;font-size:11px;gap:8px;margin-top:4px}.astermind-message__confidence,.astermind-message__offline{border-radius:4px;font-size:10px;font-weight:500;padding:2px 6px;text-transform:uppercase}.astermind-message__confidence--medium,.astermind-message__offline{background:#fef3c7;color:#92400e}.astermind-message__confidence--low{background:#fee2e2;color:#991b1b}.astermind-message__sources-toggle{background:none;border:none;color:var(--astermind-primary);cursor:pointer;font-size:12px;padding:4px 0}.astermind-message__sources-toggle:hover{text-decoration:underline}.astermind-message__typing,.astermind-typing{display:flex;gap:4px;padding:8px 0}.astermind-message__typing span,.astermind-typing span{animation:astermind-typing 1.4s ease-in-out infinite;background:var(--astermind-text-muted);border-radius:50%;height:8px;width:8px}.astermind-message__typing span:nth-child(2),.astermind-typing span:nth-child(2){animation-delay:.2s}.astermind-message__typing span:nth-child(3),.astermind-typing span:nth-child(3){animation-delay:.4s}@keyframes astermind-typing{0%,80%,to{opacity:.6;transform:scale(.6)}40%{opacity:1;transform:scale(1)}}.astermind-sources{display:flex;flex-direction:column;gap:8px;margin-top:8px}.astermind-source{background:var(--astermind-surface);border-radius:8px;font-size:12px;padding:10px}.astermind-source__header{align-items:center;display:flex;justify-content:space-between;margin-bottom:4px}.astermind-source__title{color:var(--astermind-text);font-weight:600}.astermind-source__relevance{color:var(--astermind-primary);font-weight:500}.astermind-source__snippet{color:var(--astermind-text-muted);line-height:1.4}.astermind-status{align-items:center;background:hsla(0,0%,100%,.2);border-radius:12px;display:flex;font-size:12px;gap:6px;padding:4px 10px}.astermind-status__dot{border-radius:50%;height:8px;width:8px}.astermind-status--online .astermind-status__dot{background:#10b981}.astermind-status--offline .astermind-status__dot{background:#f59e0b}.astermind-status--connecting .astermind-status__dot{animation:astermind-pulse 1.5s infinite;background:#3b82f6}.astermind-status--error .astermind-status__dot{background:#ef4444}@keyframes astermind-pulse{0%,to{opacity:1}50%{opacity:.4}}.astermind-window__footer{border-top:1px solid var(--astermind-border);padding:12px 16px}.astermind-input{align-items:flex-end;display:flex;gap:8px}.astermind-input__textarea{border:1px solid var(--astermind-border);border-radius:20px;flex:1;font-family:inherit;font-size:inherit;line-height:1.4;max-height:120px;min-height:40px;outline:none;padding:10px 16px;resize:none;transition:border-color .2s}.astermind-input__textarea:focus{border-color:var(--astermind-primary)}.astermind-input__textarea::-moz-placeholder{color:var(--astermind-text-muted)}.astermind-input__textarea::placeholder{color:var(--astermind-text-muted)}.astermind-input__send{align-items:center;background:var(--astermind-primary);border:none;border-radius:50%;color:#fff;cursor:pointer;display:flex;flex-shrink:0;height:40px;justify-content:center;transition:background-color .2s,opacity .2s;width:40px}.astermind-input__send:hover:not(:disabled){background:var(--astermind-primary-hover)}.astermind-input__send:disabled{cursor:not-allowed;opacity:.5}.astermind-input__send svg{height:18px;width:18px}.astermind-powered-by{color:var(--astermind-text-muted);font-size:11px;margin-top:8px;text-align:center}.astermind-powered-by a{color:var(--astermind-primary);text-decoration:none}.astermind-powered-by a:hover{text-decoration:underline}.astermind-action-card{background:var(--astermind-surface);border:1px solid var(--astermind-border);border-radius:12px;margin:8px 16px;padding:16px}.astermind-action-card__header{align-items:center;display:flex;gap:12px;margin-bottom:12px}.astermind-action-card__icon{align-items:center;background:var(--astermind-primary);border-radius:10px;color:#fff;display:flex;height:40px;justify-content:center;width:40px}.astermind-action-card__icon svg{height:20px;width:20px}.astermind-action-card__title{flex:1}.astermind-action-card__label{color:var(--astermind-text-muted);display:block;font-size:12px}.astermind-action-card__target{color:var(--astermind-text);display:block;font-weight:600}.astermind-action-card__explanation{color:var(--astermind-text-muted);font-size:13px;line-height:1.4;margin-bottom:12px}.astermind-action-card__confidence{background:var(--astermind-background);border-radius:8px;color:var(--astermind-text-muted);font-size:12px;margin-bottom:12px;overflow:hidden;padding:8px;position:relative}.astermind-action-card__confidence-bar{background:rgba(79,70,229,.2);height:100%;left:0;position:absolute;top:0;z-index:0}.astermind-action-card__confidence span{position:relative;z-index:1}.astermind-action-card__actions{display:flex;gap:8px}.astermind-action-card__cancel,.astermind-action-card__confirm{border-radius:8px;cursor:pointer;flex:1;font-weight:500;padding:10px;transition:background-color .2s}.astermind-action-card__cancel{background:var(--astermind-background);border:1px solid var(--astermind-border);color:var(--astermind-text)}.astermind-action-card__cancel:hover{background:var(--astermind-surface)}.astermind-action-card__confirm{background:var(--astermind-primary);border:none;color:#fff}.astermind-action-card__confirm:hover{background:var(--astermind-primary-hover)}@keyframes astermind-highlight-pulse{0%,to{box-shadow:0 0 0 0 rgba(79,70,229,.4)}50%{box-shadow:0 0 0 10px rgba(79,70,229,0)}}.astermind-highlight-overlay{animation:astermind-highlight-pulse 1s ease-in-out 3}@media (max-width:480px){.astermind-window{border-radius:0;height:100vh;left:0;position:fixed;top:0;width:100vw}.astermind-chatbot--bottom-left,.astermind-chatbot--bottom-right,.astermind-chatbot--top-left,.astermind-chatbot--top-right{bottom:20px;left:auto;right:20px;top:auto}}
|