@infomatebot/chatbot-widget/README.md

Build intelligent chatbots using pre-designed conversation flows with quick reply options. Upload documents for AI-powered, context-aware responses and reduce support costs by 80% with guided conversations

# InfoMate Chatbot Widget

Web component chatbot widget built with TypeScript and Vite. Embeddable widget for websites with conversation flows and AI-powered responses.

## 🚀 Quick Start

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build
```

## 📋 Prerequisites

- **Node.js**: 18.x or higher
- **Backend API**: InfoMate API running on http://localhost:3000

## 🏗️ Features

- **Web Components**: Custom element `<infomate-chatbot>`
- **TypeScript**: Full type safety
- **Conversation Flows**: Support for quick replies and input collectors
- **Theming**: Light/dark themes with custom colors
- **Responsive**: Works on desktop and mobile
- **Position Options**: bottom-right, bottom-left, top-right, top-left
- **Size Options**: small, medium, large, xl

## 🔧 Configuration

### HTML Attributes

```html
<infomate-chatbot 
  api-key="your-api-key-here"
  api-base-url="http://localhost:3000"
  bot-name="InfoMate Assistant"
  welcome-message="Hi! How can I help you today?"
  primary-color="#667eea"
  secondary-color="#764ba2"
  size="medium"
  position="bottom-right"
  theme="light"
  auto-open="false"
  show-powered-by="true">
</infomate-chatbot>
```

### Available Attributes

| Attribute | Type | Default | Options |
|-----------|------|---------|---------|
| `api-key` | string | **Required** | Your API key |
| `api-base-url` | string | `http://localhost:3000` | API base URL |
| `bot-name` | string | `InfoMate Assistant` | Bot display name |
| `welcome-message` | string | `Hi! How can I help you today?` | Initial message |
| `primary-color` | string | `#667eea` | Main theme color |
| `secondary-color` | string | `#764ba2` | Secondary color |
| `size` | string | `medium` | `small`, `medium`, `large`, `xl` |
| `position` | string | `bottom-right` | `bottom-right`, `bottom-left`, `top-right`, `top-left` |
| `theme` | string | `light` | `light`, `dark` |
| `auto-open` | boolean | `false` | Auto-open on load |
| `show-powered-by` | boolean | `true` | Show branding |

## 📡 API Integration

### Chat Endpoints Used

- **POST** `/api/chat/start` - Initialize chat session
- **POST** `/api/chat/send` - Send messages
- **POST** `/api/chat/session/validate` - Validate session (commented)
- **GET** `/api/chat/conversation/history` - Get history (commented)
- **POST** `/api/chat/feedback` - Send feedback (commented)

### Events

```javascript
const widget = document.querySelector('infomate-chatbot');

// Chat lifecycle events
widget.addEventListener('chatbot:opened', () => console.log('Chat opened'));
widget.addEventListener('chatbot:closed', () => console.log('Chat closed'));
widget.addEventListener('chatbot:message', (e) => console.log('Message:', e.detail));
widget.addEventListener('chatbot:error', (e) => console.error('Error:', e.detail));

// Typing events
widget.addEventListener('chatbot:typing-start', () => console.log('Bot typing...'));
widget.addEventListener('chatbot:typing-end', () => console.log('Bot stopped typing'));

// Action events (conversation flows)
widget.addEventListener('chatbot:action-executed', (e) => console.log('Action:', e.detail));
widget.addEventListener('chatbot:input-requested', (e) => console.log('Input requested'));
widget.addEventListener('chatbot:input-submitted', (e) => console.log('Input submitted'));
```

## 🔄 Conversation Features

### Quick Replies

Automatic rendering when API returns quick replies:

```json
{
  "message": "How can I help you?",
  "quickReplies": [
    { "id": "help", "label": "Help" },
    { "id": "services", "label": "Our Services" },
    { "id": "contact", "label": "Contact Us" }
  ]
}
```

### Input Collectors

Support for form-like data collection:

```json
{
  "inputCollector": {
    "fields": [
      {
        "name": "email",
        "type": "email",
        "label": "Email",
        "required": true,
        "validation": "email"
      },
      {
        "name": "message",
        "type": "textarea",
        "label": "Message",
        "required": true
      }
    ]
  }
}
```

## 🎨 Styling

### CSS Custom Properties

```css
infomate-chatbot {
  --chatbot-primary-color: #667eea;
  --chatbot-secondary-color: #764ba2;
  --chatbot-background-color: #ffffff;
  --chatbot-text-color: #111827;
  --chatbot-border-color: #e5e7eb;
  --chatbot-z-index: 999999;
}
```

### Size Configurations

- **small**: 320x450px
- **medium**: 380x520px  
- **large**: 450x600px
- **xl**: 520x680px

### Themes

- **light**: White background, dark text
- **dark**: Dark background, light text

## 🧪 Testing

```bash
# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

# Run tests with coverage
npm run test:coverage

# Integration tests
npm run test:integration
```

## 📦 Build & Distribution

### Development

```bash
# Start dev server
npm run dev

# Type checking
npm run typecheck

# Lint code
npm run lint

# Format code
npm run format
```

### Production

```bash
# Build for production
npm run build

# Test build
npm run test:build

# Check bundle size
npm run size
```

### Build Output

- `dist/index.umd.js` - UMD bundle
- `dist/index.esm.js` - ES modules
- `dist/index.d.ts` - TypeScript definitions

## 🔧 Development

### Project Structure

```
src/
├── constants/       # Configuration constants
├── types/          # TypeScript type definitions
├── ui/             # UI components and styling
├── utils/          # Utility functions
├── services/       # API and chat services
└── index.ts        # Main entry point
```

### Key Files

- `src/index.ts` - Web component registration
- `src/constants/defaults.ts` - Default configuration
- `src/types/internal.types.ts` - Type definitions
- `src/ui/` - UI components and styles
- `vite.config.js` - Build configuration

## 📄 License

Commercial license. All rights reserved.

## 🆘 Support

- **Documentation**: See `examples/` folder
- **Issue Tracking**: Internal issue tracker