# Vezlo Assistant Chat

[![npm version](https://img.shields.io/npm/v/@vezlo/assistant-chat.svg)](https://www.npmjs.com/package/@vezlo/assistant-chat) [![license](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](https://opensource.org/licenses/AGPL-3.0)

A complete chat widget solution with both a React component library and standalone admin application for AI-powered customer support.

**📋 [Changelog](./CHANGELOG.md)** | **🐛 [Report Issue](https://github.com/vezlo/assistant-chat/issues)**

## What's Included

### 📦 NPM Package
- **Reusable React Widget**: Install via `npm install @vezlo/assistant-chat`
- **TypeScript Support**: Full type definitions included
- **Customizable**: Themes, colors, positioning, and behavior
- **Real-time Streaming**: Live AI responses with Server-Sent Events (SSE) streaming support
- **Style Isolation**: Shadow DOM support for conflict-free integration
- **📖 [Complete Package Documentation](PACKAGE_README.md)**

### 🖥️ Standalone Application
- **Admin Dashboard**: Configure widgets with live preview
- **Playground**: Test widgets in isolated environment
- **Embed Code Generator**: Get ready-to-use embed codes
- **Docker Support**: Easy deployment with Docker Compose
- **Vercel Ready**: One-click deployment to Vercel
- **Shared Layout**: `MainLayout` + `Header` provide a consistent, Vercel-style shell across every page
- **Auth-Ready Context**: `AppProvider` exposes user/workspace state, token helpers, and `ProtectedRoute` support for future login flows

## Quick Start

### For Developers (NPM Package)

```bash
npm install @vezlo/assistant-chat
```

```tsx
import { Widget } from '@vezlo/assistant-chat';

function App() {
  const config = {
    uuid: 'your-widget-uuid',
    apiUrl: 'http://localhost:3000',
    apiKey: 'your-api-key',
    title: 'AI Assistant',
    themeColor: '#10b981',
    // ... other config
  };
  
  return <Widget config={config} />;
}
```

**📖 [Complete NPM Package Documentation](PACKAGE_README.md)**

### For Administrators (Standalone App)

This repository also contains a standalone admin application for configuring and managing widgets.

```bash
# Clone and run the standalone app
git clone https://github.com/vezlo/assistant-chat.git
cd assistant-chat
npm install
npm run dev
```

**Features:**
- Admin dashboard for widget configuration
- Live preview and playground
- Embed code generation
- Docker and Vercel deployment support
- Theme + widget matrices: see [`docs/THEME_WIDGET_CONFIG.md`](docs/THEME_WIDGET_CONFIG.md) for every field, color mapping tips, and widget overrides

## Prerequisites

- **Assistant Server**: Both components require a running Assistant Server
- Node.js 18+ and npm
- React 18+ (for package usage)
- **Realtime Updates** (Optional): For agent handoff + live message sync, provide Supabase Realtime credentials
  - `VITE_SUPABASE_URL`: Supabase project URL
  - `VITE_SUPABASE_ANON_KEY`: Supabase anon/public key
  - Without these, the widget works normally but won’t receive realtime updates

## Features

### Package Features
- ✅ React component library
- ✅ TypeScript support
- ✅ Tailwind CSS styling
- ✅ Real-time streaming (SSE-based backend streaming)
- ✅ **Realtime updates** (agent handoff, live message sync)
- ✅ Customizable themes
- ✅ Shadow DOM support
- ✅ API integration included

### App Features
- ✅ Admin dashboard
- ✅ Live widget preview
- ✅ Playground testing
- ✅ Embed code generation
- ✅ Multiple widget management
- ✅ **Human agent support** (conversation management, agent handoff)
- ✅ **Realtime updates** (live message synchronization)
- ✅ **Database tools** (connect external databases for natural language queries - [docs](./docs/DATABASE_TOOLS.md))
- ✅ **AI Settings** (customize AI behavior, model, temperature, and prompts per company)
- ✅ Docker support
- ✅ Vercel deployment

## Deployment Options

### Package (NPM)
```bash
npm run build
npm pack  # Test locally
npm publish  # Publish to NPM
```

### App (Vercel)

#### Deploy via Vercel Marketplace (Recommended)
[![Install on Vercel](https://vercel.com/button)](https://vercel.com/marketplace/vezlo-assistant-chat)

The marketplace app deploys the frontend automatically, prompts you for the **Assistant Server URL** and optional **API key**, and ships both the chat UI and embeddable widget without any manual environment setup. After connecting your Vercel project you can immediately visit:

- Chat UI: `https://your-project.vercel.app/`

#### One-Click Deploy (GitHub Clone)
[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/vezlo/assistant-chat&integration-ids=oac_ZKcos500xraYgL9hH2d3Bs3A)

This clones the repo into your GitHub account, spins up a new Vercel project using the default `main` branch, and links the same Vezlo integration so the Assistant Chat deployment can gather its Assistant Server URL and API key during setup.

#### Manual Vercel CLI Deployment
```bash
# Install Vercel CLI
npm i -g vercel

# Deploy from local directory
vercel

# Set environment variables (required)
vercel env add VITE_ASSISTANT_SERVER_URL
vercel env add VITE_ASSISTANT_SERVER_API_KEY
# Optional: For realtime updates
vercel env add VITE_SUPABASE_URL
vercel env add VITE_SUPABASE_ANON_KEY

# Deploy to production
vercel --prod
```

### App (Docker)
```bash
docker-compose up
```

## Repository Structure

This repository contains both the NPM package and standalone application:

```
assistant-chat/
├── src/
│   ├── components/Widget.tsx    # Main widget component (used by both)
│   ├── api/                     # API services
│   ├── types/                   # TypeScript definitions
│   ├── utils/                   # Utility functions
│   ├── config/                  # Configuration
│   └── routes/                  # Standalone app pages
├── public/
│   └── widget.js               # Embed script
├── docs/                       # Documentation
├── README.md                   # This file (project overview)
├── PACKAGE_README.md           # NPM package documentation
└── package.json                # Package configuration
```

### How It Works

- **Same Widget Code**: Both the NPM package and standalone app use the same `Widget.tsx` component
- **Embed & Playground**: `WidgetPage.tsx` powers the iframe, embed script, and playground preview using that same component
- **NPM Package**: Publishes the widget component as a reusable library
- **Standalone App**: Uses the widget component directly for admin interface and playground
- **No Duplication**: Single source of truth for the widget component

## Layout & Auth Architecture

- `AppProvider` manages `user`, `workspace`, auth token, and exposes `login/logout` helpers plus `ProtectedRoute` for future API integration.
- `Header` & `MainLayout` deliver the new full-width, two-row dashboard shell (logo, workspace switcher, company badge, primary nav, profile dropdown).
- `ConfigPage` (dashboard) and every other route render inside `MainLayout`, so all future pages automatically inherit the header and spacing.
- `LoginPage` lives outside the layout and is already wired to `AppProvider`, making it ready for real authentication APIs.

## Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Codebase      │───▶│   src-to-kb     │───▶│ Knowledge Base  │
│   (Your Code)   │    │   (Analysis)    │    │   (Vector DB)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                        │
                                                        ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Chat Widget    │◄───│ Assistant Server│◀───│   AI Queries    │
│  (This Package) │    │   (Backend)     │    │   (RAG System)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

## Knowledge Base Integration

To enable AI-powered code analysis and intelligent responses, integrate with [@vezlo/src-to-kb](https://www.npmjs.com/package/@vezlo/src-to-kb):

```bash
npm install -g @vezlo/src-to-kb
src-to-kb /path/to/your/codebase --output ./knowledge-base
```

The Assistant Server will automatically use this knowledge base to provide intelligent answers about your codebase.

## API Integration

For detailed API integration documentation, see [API Integration Guide](docs/API_INTEGRATION.md).

## Related Projects

- [@vezlo/assistant-server](https://www.npmjs.com/package/@vezlo/assistant-server) - Backend API server
- [@vezlo/src-to-kb](https://www.npmjs.com/package/@vezlo/src-to-kb) - NPM package for code analysis
- [@vezlo/ai-validator](https://www.npmjs.com/package/@vezlo/ai-validator) - AI validation tools

## Contributing

We welcome contributions! Please see our contributing guidelines:

1. **Fork the repository**
2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
3. **Commit your changes**: `git commit -m 'Add amazing feature'`
4. **Push to the branch**: `git push origin feature/amazing-feature`
5. **Open a Pull Request**

### Development Setup

```bash
# Clone the repository
git clone https://github.com/vezlo/assistant-chat.git
cd assistant-chat

# Install dependencies
npm install

# Start development server
npm run dev

# Build the package
npm run build
```

## Issues & Support

- **Package Issues**: [Assistant Chat Issues](https://github.com/vezlo/assistant-chat/issues)
- **Server Issues**: [Assistant Server Issues](https://github.com/vezlo/assistant-server/issues)
- **General Questions**: [Assistant Server Discussions](https://github.com/vezlo/assistant-server/discussions)

## 📄 License

This project is dual-licensed:

- **Non-Commercial Use**: Free under AGPL-3.0 license
- **Commercial Use**: Requires a commercial license - contact us for details

---

Made with Love by [Vezlo](https://www.vezlo.org/)