@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.
Files changed (58) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +603 -0
  3. package/dist/astermind-chatbot.css +1 -0
  4. package/dist/astermind-chatbot.esm.js +891 -0
  5. package/dist/astermind-chatbot.esm.js.map +1 -0
  6. package/dist/astermind-chatbot.min.js +21 -0
  7. package/dist/astermind-chatbot.min.js.map +1 -0
  8. package/dist/astermind-chatbot.umd.js +915 -0
  9. package/dist/astermind-chatbot.umd.js.map +1 -0
  10. package/dist/components/ActionCard.d.ts +12 -0
  11. package/dist/components/ActionCard.d.ts.map +1 -0
  12. package/dist/components/ChatBubble.d.ts +12 -0
  13. package/dist/components/ChatBubble.d.ts.map +1 -0
  14. package/dist/components/ChatHeader.d.ts +13 -0
  15. package/dist/components/ChatHeader.d.ts.map +1 -0
  16. package/dist/components/ChatInput.d.ts +11 -0
  17. package/dist/components/ChatInput.d.ts.map +1 -0
  18. package/dist/components/ChatWindow.d.ts +21 -0
  19. package/dist/components/ChatWindow.d.ts.map +1 -0
  20. package/dist/components/ChatbotWidget.d.ts +9 -0
  21. package/dist/components/ChatbotWidget.d.ts.map +1 -0
  22. package/dist/components/MessageBubble.d.ts +10 -0
  23. package/dist/components/MessageBubble.d.ts.map +1 -0
  24. package/dist/components/MessageList.d.ts +11 -0
  25. package/dist/components/MessageList.d.ts.map +1 -0
  26. package/dist/components/SourceCitation.d.ts +10 -0
  27. package/dist/components/SourceCitation.d.ts.map +1 -0
  28. package/dist/components/StatusIndicator.d.ts +10 -0
  29. package/dist/components/StatusIndicator.d.ts.map +1 -0
  30. package/dist/components/TypingIndicator.d.ts +5 -0
  31. package/dist/components/TypingIndicator.d.ts.map +1 -0
  32. package/dist/components/index.d.ts +12 -0
  33. package/dist/components/index.d.ts.map +1 -0
  34. package/dist/context/ChatContext.d.ts +24 -0
  35. package/dist/context/ChatContext.d.ts.map +1 -0
  36. package/dist/context/ThemeContext.d.ts +20 -0
  37. package/dist/context/ThemeContext.d.ts.map +1 -0
  38. package/dist/hooks/index.d.ts +5 -0
  39. package/dist/hooks/index.d.ts.map +1 -0
  40. package/dist/hooks/useChat.d.ts +21 -0
  41. package/dist/hooks/useChat.d.ts.map +1 -0
  42. package/dist/hooks/useOmega.d.ts +27 -0
  43. package/dist/hooks/useOmega.d.ts.map +1 -0
  44. package/dist/hooks/useScrollToBottom.d.ts +15 -0
  45. package/dist/hooks/useScrollToBottom.d.ts.map +1 -0
  46. package/dist/hooks/useTheme.d.ts +47 -0
  47. package/dist/hooks/useTheme.d.ts.map +1 -0
  48. package/dist/index.d.ts +20 -0
  49. package/dist/index.d.ts.map +1 -0
  50. package/dist/init.d.ts +11 -0
  51. package/dist/init.d.ts.map +1 -0
  52. package/dist/types.d.ts +229 -0
  53. package/dist/types.d.ts.map +1 -0
  54. package/dist/utils/markdown.d.ts +7 -0
  55. package/dist/utils/markdown.d.ts.map +1 -0
  56. package/dist/utils/time.d.ts +5 -0
  57. package/dist/utils/time.d.ts.map +1 -0
  58. 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
+ [![npm version](https://img.shields.io/npm/v/@astermind/chatbot-template.svg)](https://www.npmjs.com/package/@astermind/chatbot-template)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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}}