@blumessage/react-chat 1.0.0 → 1.0.3

package/README.md

@@ -1,182 +1,289 @@
-# @blumessage/react-chat
+# Blumessage React Chat Component
 
-A beautiful, customizable React chat component with BlueMessage AI integration built with TypeScript and Tailwind CSS.
+A React TypeScript chat widget component with floating button, theming, and Blumessage API integration. Features real-time messaging, conversation persistence, error handling, and a modern UI built with Tailwind CSS.
 
-## Features
+## ✨ Features
 
-- 💬 Real-time messaging interface with AI responses
-- 👤 User avatars and names
-- ⏰ Timestamps and message status
-- 📱 Responsive design
-- 🎨 Highly customizable styling
-- 📝 TypeScript support
-- ✨ Smooth animations and transitions
-- 🤖 BlueMessage AI integration
-- 🔧 Extensive customization options
+- 🎈 **Floating Chat Widget** - Appears as a button, expands to full chat
+- 🎨 **Light/Dark Themes** - Built-in theme support
+- 💾 **Persistent Storage** - Save conversations to localStorage or sessionStorage
+- 🔄 **Real-time Messaging** - Instant API integration with Blumessage
+- 📱 **Responsive Design** - Works on desktop and mobile
+- 🎯 **Flexible Icons** - Supports various icon patterns
+- ⚡ **Error Handling** - Comprehensive error callbacks
+- 🔧 **Highly Customizable** - Extensive prop options
 
 ## Installation
 
 ```bash
-npm install @blumessage/react-chat
+npm i @blumessage/react-chat
 ```
 
 ## Quick Start
 
+### Floating Chat Widget (Default)
+
 ```tsx
 import React from 'react';
 import { BlumessageChat } from '@blumessage/react-chat';
 
 function App() {
   return (
-    <div style={{ height: '500px' }}>
-      <BlumessageChat
-        apiKey="your-blumessage-api-key"
-        headerTitle="Support Chat"
-        primaryColor="#3b82f6"
-      />
-    </div>
+    <BlumessageChat 
+      apiKey="your-blumessage-api-key"
+    />
   );
 }
-
-export default App;
 ```
 
-## API Key Setup
-
-1. Sign up for a BlueMessage API key at [blumessage.com](https://blumessage.com)
-2. Pass your API key to the `apiKey` prop
-3. For testing purposes, you can use `apiKey="test"` to enable demo mode
+### Embedded Chat
 
-**Note:** Without a valid API key, the chat component will be disabled and an error will be logged to the console.
+```tsx
+import React from 'react';
+import { BlumessageChat } from '@blumessage/react-chat';
 
-## Props
+function App() {
+  return (
+    <BlumessageChat 
+      apiKey="your-blumessage-api-key"
+      floating={false}
+      width="400px"
+      height="600px"
+    />
+  );
+}
+```
 
-### Core Props
+## Complete Props Reference
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `apiKey` | `string` | `undefined` | **Required** - BlueMessage API key for chat functionality. Use `"test"` for demo purposes |
-| `messages` | `Message[]` | `[]` | Array of messages to display |
-| `onSendMessage` | `(message: string) => void` | `undefined` | Callback when user sends a message |
-| `currentUser` | `User` | `{ id: 'user1', name: 'You' }` | Current user information |
-| `inputPlaceholder` | `string` | `'Type a message...'` | Input placeholder text |
-| `className` | `string` | `''` | Additional CSS classes |
+| **Required** |
+| `apiKey` | `string` | - | Your Blumessage API key |
+| **Display & Content** |
+| `name` | `string` | `"Blumessage AI"` | Display name for the AI assistant |
+| `subtitle` | `string` | `"Online • Instant responses"` | Subtitle shown under the name |
+| `placeholder` | `string` | `"Type your message..."` | Input placeholder text |
+| `theme` | `'light' \| 'dark'` | `'light'` | Chat widget theme |
+| `primaryColor` | `string` | `"linear-gradient(to right, #3b82f6,rgb(8, 98, 242))"` | Primary color/gradient |
+| **Layout & Sizing** |
+| `floating` | `boolean` | `true` | Show as floating widget vs embedded |
+| `width` | `string` | `'380px'` (medium) | Custom width (overrides size) |
+| `height` | `string` | `'500px'` (medium) | Custom height (overrides size) |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Predefined size preset |
+| `fullScreen` | `boolean` | `false` | Force full screen mode |
+| **Floating Widget Options** |
+| `buttonText` | `string` | `"Chat with us"` | Text on floating button |
+| `buttonPosition` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Button position |
+| `buttonStyle` | `React.CSSProperties` | - | Custom button styles |
+| `defaultOpen` | `boolean` | `false` | Start with chat open |
+| `maximizeToggleButton` | `boolean` | `true` | Show maximize/minimize button |
+| `icon` | `string` | `'message-circle'` | Icon for button (flexible naming) |
+| **Messages & Data** |
+| `initialMessages` | `Message[]` | `[]` | Pre-populate with messages |
+| `conversationId` | `string` | - | Continue specific conversation |
+| `persistent` | `boolean` | `false` | Use localStorage vs sessionStorage |
+| **Event Callbacks** |
+| `onUserMessage` | `(message: Message) => void` | - | Called when user sends message |
+| `onAssistantMessage` | `(message: Message) => void` | - | Called when assistant responds |
+| `onConversationIdChange` | `(id: string \| null) => void` | - | Called when conversation ID changes |
+| `onChatWidgetOpen` | `() => void` | - | Called when floating chat opens |
+| `onChatWidgetClosed` | `() => void` | - | Called when floating chat closes |
+| `onError` | `(error: string, context?: string) => void` | - | Called on any error |
+
+## Advanced Usage Examples
+
+### Dark Theme with Callbacks
 
-### Header Customization
+```tsx
+<BlumessageChat 
+  apiKey="your-api-key"
+  theme="dark"
+  name="Support Bot"
+  onUserMessage={(message) => console.log('User:', message.content)}
+  onAssistantMessage={(message) => console.log('Bot:', message.content)}
+  onError={(error, context) => console.error(`Error in ${context}:`, error)}
+/>
+```
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `headerTitle` | `string` | `'BlueMessage AI'` | Chat header title |
-| `headerDescription` | `string` | `'Online • Instant responses'` | Subtitle text in header |
-| `headerColor` | `string` | `undefined` | Header background color (uses primaryColor if not set) |
-| `headerIcon` | `string` | `'mdi:message-text'` | Iconify icon name for header |
-| `headerIconColor` | `string` | `'white'` | Header icon color |
-| `headerIconHide` | `boolean` | `false` | Hide header icon |
-| `headerAvatarColor` | `string` | `'rgba(255, 255, 255, 0.2)'` | Header avatar background color |
+### Persistent Storage
 
-### Layout & Behavior
+```tsx
+<BlumessageChat 
+  apiKey="your-api-key"
+  persistent={true}  // Saves to localStorage instead of sessionStorage
+  onConversationIdChange={(id) => {
+    // Optionally save ID to your own storage
+    if (id) localStorage.setItem('my-chat-id', id);
+  }}
+/>
+```
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `size` | `'xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` | Chat window size |
-| `floatingButtonPosition` | `'top-right' \| 'top-left' \| 'bottom-left' \| 'bottom-right'` | `'bottom-right'` | Position of floating chat button |
-| `autoOpen` | `boolean` | `false` | Auto-open chat on load |
-| `forceOpen` | `boolean` | `false` | Force chat to stay open (removes close button) |
-| `maximize` | `boolean` | `false` | Start maximized |
-| `maximizeToggle` | `boolean` | `true` | Show maximize/minimize button |
+### Custom Styling & Size
 
-### Colors & Styling
+```tsx
+<BlumessageChat 
+  apiKey="your-api-key"
+  size="large"
+  primaryColor="linear-gradient(45deg, #ff6b6b, #4ecdc4)"
+  buttonPosition="bottom-left"
+  buttonText="Need Help?"
+  icon="headphones"
+  maximizeToggleButton={true}
+/>
+```
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `primaryColor` | `string` | `'#3b82f6'` | Main theme color |
-| `secondaryColor` | `string` | `'#2563eb'` | Secondary theme color |
-| `messageUserColor` | `string` | `undefined` | User message background (uses gradient if not set) |
-| `messageAssistantColor` | `string` | `'#f3f4f6'` | Assistant message background |
-| `sendButtonColor` | `string` | `undefined` | Send button color (uses gradient if not set) |
-| `inputOutlineColor` | `string` | `'#3b82f6'` | Input focus border color |
-| `floatingButtonBackgroundColor` | `string` | `undefined` | Floating button background |
-| `floatingButtonIcon` | `string` | `undefined` | Floating button icon (uses headerIcon if not set) |
-| `floatingButtonIconColor` | `string` | `'white'` | Floating button icon color |
-
-### Message Customization
+### Embedded with Initial Messages
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `messageTimestamps` | `boolean` | `true` | Show message timestamps |
-| `messageUserAvatarVisibility` | `boolean` | `false` | Show user avatars |
-| `messageUserAvatarIcon` | `string` | `'mdi:account'` | User avatar icon |
-| `messageUserAvatarColor` | `string` | `'#3b82f6'` | User avatar background color |
-| `messageAssistantAvatarVisibility` | `boolean` | `false` | Show assistant avatars |
-| `messageAssistantAvatarIcon` | `string` | `'mdi:robot'` | Assistant avatar icon |
-| `messageAssistantAvatarColor` | `string` | `'#6b7280'` | Assistant avatar background color |
-| `messageUserName` | `string \| null` | `null` | Display name for user messages |
-| `messageAssistantName` | `string \| null` | `null` | Display name for assistant messages |
-| `sendButtonIcon` | `string` | `'mdi:send'` | Send button icon |
-
-## Types
+```tsx
+const initialMessages = [
+  {
+    id: '1',
+    role: 'assistant' as const,
+    content: 'Hello! How can I help you today?',
+    timestamp: Date.now()
+  }
+];
+
+<BlumessageChat 
+  apiKey="your-api-key"
+  floating={false}
+  width="100%"
+  height="500px"
+  initialMessages={initialMessages}
+  placeholder="Ask me anything..."
+/>
+```
+
+## Icon Options
+
+The `icon` prop accepts **any lucide-react icon name** with flexible naming patterns. The component intelligently matches your input to the appropriate lucide-react icon:
 
 ```tsx
-interface User {
-  id: string;
-  name: string;
-  avatar?: string;
-}
+// ✅ Any lucide-react icon works:
+icon="message-circle"    // MessageCircle
+icon="phone"             // Phone
+icon="mail"              // Mail
+icon="headphones"        // Headphones
+icon="bot"               // Bot
+icon="users"             // Users
+icon="heart"             // Heart
+icon="star"              // Star
+icon="zap"               // Zap
+icon="settings"          // Settings
+icon="help-circle"       // HelpCircle
+icon="info"              // Info
+icon="alert-triangle"    // AlertTriangle
+
+// ✅ Flexible naming patterns (case-insensitive, ignores hyphens/underscores):
+icon="MessageCircle"     // → MessageCircle
+icon="message_circle"    // → MessageCircle
+icon="message circle"    // → MessageCircle
+icon="chat"              // → MessageCircle (smart matching)
+icon="messaging"         // → MessageCircle (smart matching)
+icon="support"           // → Headphones (smart matching)
+icon="email"             // → Mail (smart matching)
+icon="call"              // → Phone (smart matching)
+
+// ✅ Default fallback: MessageCircle (if no match found)
+icon="unknown-icon"      // → MessageCircle
+```
+
+**Browse all available icons at:** [lucide.dev/icons](https://lucide.dev/icons)
+
+Simply use the icon name from lucide-react, and the component will handle the rest!
+
+## Error Handling
+
+The `onError` callback provides detailed error context:
+
+```tsx
+<BlumessageChat 
+  apiKey="your-api-key"
+  onError={(error, context) => {
+    switch(context) {
+      case 'missing_api_key':
+        // Handle missing API key
+        break;
+      case 'api_key_validation':
+        // Handle invalid API key
+        break;
+      case 'network_error':
+        // Handle network issues
+        break;
+      case 'conversation_history':
+        // Handle history fetch errors
+        break;
+      case 'message_send':
+        // Handle message sending errors
+        break;
+    }
+  }}
+/>
+```
+
+## TypeScript Support
+
+Full TypeScript definitions included:
+
+```typescript
+import { BlumessageChat, Message, BlumessageChatProps } from '@blumessage/react-chat';
 
 interface Message {
   id: string;
-  text: string;
-  sender: User;
-  timestamp: Date;
-  isOwn: boolean;
+  role: 'user' | 'assistant';
+  content: string;
+  timestamp: number;
 }
 ```
 
-## Advanced Usage
+## API Integration
 
-### Custom Styling
+### Message Sending
+```
+POST https://api.blumessage.com/api/v1/conversations
+Content-Type: application/json
+Authorization: Bearer {API_KEY}
 
-```tsx
-<BlumessageChat
-  apiKey="your-api-key"
-  primaryColor="#10b981"
-  secondaryColor="#059669"
-  headerTitle="Customer Support"
-  headerDescription="We're here to help!"
-  size="large"
-  messageTimestamps={true}
-  messageAssistantAvatarVisibility={true}
-/>
+{
+  "message": "user input",
+  "conversationId": "optional-existing-id"
+}
 ```
 
-### Event Handling
+### Conversation History
+```
+GET https://api.blumessage.com/api/v1/conversations/session/{conversationId}
+Authorization: {API_KEY}
+```
 
-```tsx
-const handleSendMessage = (message: string) => {
-  console.log('User sent:', message);
-  // Add your custom logic here
-};
+### API Key Validation
+```
+POST https://api.blumessage.com/api/v1/api-keys/validate
+Content-Type: application/json
 
-<BlumessageChat
-  apiKey="your-api-key"
-  onSendMessage={handleSendMessage}
-  currentUser={{
-    id: 'user123',
-    name: 'John Doe',
-    avatar: '👤'
-  }}
-/>
+{
+  "apiKey": "your-api-key"
+}
 ```
 
-## Requirements
+## Storage Behavior
+
+- **SessionStorage (default)**: Conversations persist until browser tab closes
+- **LocalStorage (persistent=true)**: Conversations persist across browser sessions
+- **Automatic cleanup**: Invalid conversation IDs are automatically cleared
+- **History restoration**: Previous conversations load automatically on component mount
+
+## Browser Support
 
+- Modern browsers with ES2017+ support
 - React 18+
-- TypeScript (recommended)
+- TypeScript 4.5+
 
 ## License
 
-MIT © BlueMessage
+ISC
 
 ## Support
 
-For support and questions, visit [blumessage.com](https://blumessage.com) or create an issue on GitHub.
+For issues and feature requests, please visit the [GitHub repository](https://github.com/Blumessage/react-chat).