@arifdroid/enhanced-chat/README.md

Enhanced chat widget combining modern n8n styling with advanced voice features and alert mode

# Enhanced Chat Widget 🚀

A modern, feature-rich chat widget that combines the elegant styling of n8n chat with advanced voice capabilities. Perfect for AI chatbots, customer support, and interactive applications.

## ✨ Features

- 🎤 **Voice Recording & Playback** - Record and send voice messages
- 🔊 **Text-to-Speech** - Play back user messages using browser TTS
- 🎵 **Auto-play Audio Responses** - Automatically play bot audio responses
- 🚨 **Alert Mode Toggle** - Switch to voice-only mode for emergency scenarios
- 📢 **Real-time Alerts** - Success/error notifications with auto-hide
- 🔔 **Welcome Notifications** - User-friendly onboarding alerts
- 🎨 **Modern Styling** - Clean, customizable design inspired by n8n chat
- 📱 **Responsive Design** - Works perfectly on desktop and mobile
- ♿ **Accessibility** - Full ARIA support and keyboard navigation
- 🌙 **Theming Support** - Customizable colors and styling
- ⚡ **Optimized Performance** - Lightweight and fast
- 🔗 **CDN Ready** - Easy deployment via CDN
- 🛠️ **Simple API** - Easy to integrate and configure

## 🚀 Quick Start

### CDN Usage

```html
<script src="https://cdn.jsdelivr.net/npm/@yourorg/enhanced-chat@latest/dist/enhanced-chat.bundle.js"></script>
<script>
  createChat({
    webhookUrl: 'https://your-webhook-url.com/webhook/...',
    initialMessages: [
      'Hi there! Welcome to our chat!',
      'I can handle both text and voice messages. How can I help you?'
    ]
  });
</script>
```

### NPM Installation

```bash
npm install @yourorg/enhanced-chat
```

```javascript
import { createChat } from '@yourorg/enhanced-chat';

createChat({
  webhookUrl: 'https://your-webhook-url.com/webhook/...',
  // ... other options
});
```

## 📚 API Reference

### createChat(options)

Creates and initializes a new chat widget.

#### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `webhookUrl` | `string` | **required** | Your webhook endpoint URL |
| `target` | `string\|Element` | `'body'` | Target element to attach the chat widget |
| `mode` | `'window'\|'fullscreen'` | `'window'` | Display mode of the chat |
| `theme` | `object` | `{}` | Theme customization options |
| `initialMessages` | `string[]` | `[]` | Initial messages to display |
| `voiceEnabled` | `boolean` | `true` | Enable voice recording feature |
| `textToSpeechEnabled` | `boolean` | `true` | Enable text-to-speech for user messages |
| `autoPlayResponses` | `boolean` | `true` | Auto-play audio responses from bot |
| `placeholder` | `string` | `'Type your message...'` | Input placeholder text |
| `showWindowCloseButton` | `boolean` | `true` | Show close button in window mode |

#### Theme Options

```javascript
theme: {
  primaryColor: '#007bff',      // Primary theme color
  secondaryColor: '#28a745',    // Secondary color (voice buttons)
  backgroundColor: '#ffffff',   // Background color
  textColor: '#333333',         // Text color
  borderRadius: '12px',         // Border radius for elements
  boxShadow: '0 8px 32px rgba(0,0,0,0.1)' // Box shadow
}
```

### Widget Methods

The `createChat()` function returns a widget instance with the following methods:

```javascript
const chatWidget = createChat({ /* options */ });

// Control visibility
chatWidget.open();        // Show the chat widget
chatWidget.close();       // Hide the chat widget
chatWidget.toggle();      // Toggle visibility

// Window state
chatWidget.minimize();    // Minimize to toggle button
chatWidget.maximize();    // Restore from minimized state

// Programmatic messaging
chatWidget.addMessage('Hello!', false);  // Add bot message
chatWidget.addMessage('Hi there!', true); // Add user message

// Voice features
chatWidget.playUserMessage('Text to speak'); // Play text using TTS

// Alert system
chatWidget.showAlert('Success!', 'success', 3000); // Show alert
chatWidget.hideAlert();                            // Hide current alert
chatWidget.toggleAlertMode();                      // Toggle voice-only mode

// Utility
chatWidget.scrollToBottom(); // Scroll messages to bottom
chatWidget.destroy();         // Clean up and remove widget
```

## 🎨 Customization Examples

### Custom Theme

```javascript
createChat({
  webhookUrl: 'https://your-webhook.com/...',
  theme: {
    primaryColor: '#6c5ce7',
    secondaryColor: '#00b894',
    backgroundColor: '#2d3436',
    textColor: '#ddd',
    borderRadius: '8px'
  }
});
```

### Fullscreen Mode

```javascript
createChat({
  webhookUrl: 'https://your-webhook.com/...',
  mode: 'fullscreen',
  initialMessages: ['Welcome to fullscreen chat!']
});
```

### Custom Target Element

```javascript
createChat({
  webhookUrl: 'https://your-webhook.com/...',
  target: '#my-chat-container'
});
```

## 🎤 Voice Features

### Voice Recording
- Click the microphone button to start recording
- Click the stop button to send the voice message
- Supports WebRTC for high-quality audio recording

### Audio Playback
- Bot audio responses auto-play (if enabled)
- Click play buttons to replay any audio message
- Supports multiple audio formats (MP3, WAV, etc.)

### Text-to-Speech
- User messages can be played back using browser TTS
- Click the speaker icon next to user messages
- Automatically selects best available voice

### Alert Mode
- 🚨 **Emergency Mode**: Click "Alert Mode" button to enable voice-only communication
- **Text Disabled**: In alert mode, text input is disabled for urgent voice-only scenarios
- **Visual Feedback**: Input field changes color and shows warning when text is attempted
- **Automatic Flagging**: Voice messages sent in alert mode include `alertMode: true` flag in webhook payload
- **Easy Toggle**: One-click to enable/disable alert mode with clear visual indicators

## 🔧 Development

### Setup

```bash
git clone <repository-url>
cd enhanced-chat
npm install
```

### Build

```bash
# Development build with watching
npm run dev

# Production build
npm run build

# Clean build artifacts
npm run clean
```

### Testing

```bash
# Serve demo locally
npm run serve

# Open demo.html in browser
open http://localhost:3000/demo.html
```

## 📦 Build Output

The build process creates several optimized bundles:

- `dist/enhanced-chat.bundle.js` - UMD bundle for browsers
- `dist/enhanced-chat.esm.js` - ES Module bundle
- `dist/enhanced-chat.min.js` - Minified UMD bundle for production

## 🌐 Browser Support

- Chrome 60+
- Firefox 55+
- Safari 11+
- Edge 79+

### Required APIs
- **WebRTC** - For voice recording
- **Web Audio API** - For audio playback
- **Speech Synthesis API** - For text-to-speech (optional)

## 🔒 Privacy & Security

- Voice data is sent to your specified webhook only
- No data is stored or transmitted to third parties
- Uses secure HTTPS connections
- Respects browser security policies

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## 📄 License

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

## 🆘 Support

- 📧 Email: support@yourorg.com
- 🐛 Issues: [GitHub Issues](https://github.com/yourusername/enhanced-chat/issues)
- 📖 Documentation: [Full Docs](https://yourdocs.com)

## 🙏 Acknowledgments

- Inspired by [n8n chat widget](https://www.npmjs.com/package/@n8n/chat)
- Built with modern web standards
- Designed for accessibility and performance

---

**Made with ❤️ for the developer community**