ultra-chat-bot/README.md

made with ❤️ by Mohamed Majri

# Ultra Chat Bot

A modern, highly optimized React ChatBot component with Socket.IO support. Built with pure CSS (no framework dependencies) and TypeScript for maximum performance and compatibility.

## Features

✨ **Modern & Clean Design** - Sleek UI with auto-loaded Geist font  
⚡ **High Performance** - Pure CSS, no external CSS framework dependencies  
🔄 **Real-time Communication** - Socket.IO integration for instant messaging  
📱 **Responsive Design** - Works perfectly on all devices  
🎨 **Fully Customizable** - Colors, positioning, dimensions, and more  
🔒 **Session Management** - Automatic session persistence and reconnection  
⌨️ **Typing Indicators** - Real-time typing status  
👁️ **Message Status** - Read receipts and message status tracking  
🧩 **TypeScript Ready** - Full TypeScript support with comprehensive types  
🎯 **Zero Dependencies** - No CSS framework required (Tailwind, Bootstrap, etc.)
🔤 **Auto Font Loading** - Geist font automatically loaded from CDN
🔊 **Notification Sounds** - Configurable audio notifications for new messages

## Installation

```bash
npm install ultra-chat-bot
```

## Basic Usage

```tsx
import React from 'react';
import { ChatBot } from 'ultra-chat-bot';

function App() {
  return (
    <div>
      <ChatBot 
        UID="your-bot-id"
      />
    </div>
  );
}
```

### With User Authentication

```tsx
<ChatBot 
  UID="your-bot-id"
  config={{
   
    firstname: "John",
    lastname: "Doe", 
    email: "john.doe@example.com",
    // ... other config options
  }}
/>
```

### With Custom Notification Sound

```tsx
<ChatBot 
  UID="your-bot-id"
  config={{
    audioUrl: "https://your-domain.com/notification.mp3", // Optional: uses default sound if not provided
    enableNotificationSound: true, // Optional: true by default
    // ... other config options
  }}
/>
```

**Note:** Notification sounds are **enabled by default** with a built-in sound. You only need to configure `audioUrl` if you want to use a custom notification sound.

### Configuration Options

- `audioUrl` - **Optional:** URL to a custom notification sound file (mp3, wav, etc.). Uses built-in sound if not provided.
- `enableNotificationSound` - **Optional:** Enable/disable notification sounds (default: true)
- `companyName` - Company name displayed in the chat
- `botName` - Bot name displayed in chat header
- `primaryColor` - Primary color for the chat interface
- `secondaryColor` - Secondary color for accents
- `position` - Chat widget position (`"bottom-right"`, `"bottom-left"`, `"top-right"`, `"top-left"`)
- `height` - Chat window height
- `width` - Chat window width
- `welcomeMessage` - Initial welcome message
- `placeholder` - Input placeholder text
- `firstname`, `lastname`, `email` - User authentication details

## Server Integration

This component expects a Socket.IO server with the following events:

### Client Events (sent by the component):
- `guest:join` - Join chat session
- `guest:message` - Send message
- `guest:startTyping` - Start typing indicator
- `guest:stopTyping` - Stop typing indicator
- `guest:markSeen` - Mark messages as seen
- `guest:getChatHistory` - Request chat history
- `guest:pathUpdate` - Update navigation path

### Server Events (received by the component):
- `guest:joined` - Confirmation of join with session info
- `message` - Incoming message
- `message:sent` - Message sent confirmation
- `admin:startTyping` / `admin:stopTyping` - Admin typing indicators
- `messages:seenByAdmin` - Messages marked as seen by admin
- `guest:chatHistory` - Chat history response

## Styling

The component uses pure CSS with inline styles and includes:

- **Geist** font family with fallbacks (automatically loaded from CDN)
- **Responsive design** that works on all screen sizes  
- **Smooth animations** for opening/closing and interactions
- **Customizable colors** via the config props
- **CSS-in-JS** approach for maximum compatibility

### Font Loading

The component automatically loads the **Geist** font from Google Fonts CDN when it mounts. This ensures a consistent typography experience across all applications without requiring users to manually include the font. 

**How it works:**
- Automatically injects preconnect and `<link>` tags for Geist from Google Fonts
- Includes comprehensive font-family fallbacks to system fonts
- Only loads once per page (checks for existing font links)
- No additional setup required by developers
- Uses Google Fonts with optimized loading (`&display=swap`)

**Fallback chain:**
```css
font-family: "Geist", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif
```

## TypeScript Support

Full TypeScript support with exported types:

```tsx
import { ChatBot, ChatbotConfig, ChatbotProps, Message } from 'ultra-chat-bot';
```

## Browser Support

- Chrome 80+
- Firefox 74+
- Safari 13+
- Edge 80+

## Dependencies

### Runtime Dependencies:
- `lucide-react` - Icons
- `socket.io-client` - Real-time communication

### Peer Dependencies:
- `react` >= 16.8.0
- `react-dom` >= 16.8.0

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

## Troubleshooting

### Import Issues

If you encounter `Export ChatBot doesn't exist in target module` error:

1. **Check your import syntax:**
   ```tsx
   // ✅ Correct
   import { ChatBot } from 'ultra-chat-bot';
   
   // ❌ Incorrect
   import ChatBot from 'ultra-chat-bot';
   ```

2. **For Next.js projects**, the component automatically uses the correct build (ES modules or CommonJS) based on your project configuration.

3. **For TypeScript projects**, make sure you have the latest version and proper type imports:
   ```tsx
   import { ChatBot, type ChatbotConfig } from 'ultra-chat-bot';
   ```

4. **Clear your node_modules and reinstall:**
   ```bash
   rm -rf node_modules package-lock.json
   npm install
   ```

### Common Issues

- **CORS Font Loading**: The component automatically handles Geist font loading. If you see CORS errors, they are usually resolved automatically by the fallback system.
- **Socket Connection**: Make sure your Socket.IO server is running and accessible at the configured URL.
- **Build Errors**: Ensure you have React 16.8+ and the required peer dependencies installed.

## Support

For support, please open an issue on our GitHub repository or contact our support team.

---

**Ultra Chat Bot** - The fastest, most lightweight chat component for React applications. No CSS framework required! 🚀