@vezlo/assistant-chat 1.0.0

package/PACKAGE_README.md

@@ -0,0 +1,255 @@
+# Vezlo Assistant Chat Widget - NPM Package
+
+[![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 React component library for integrating AI assistant chat functionality into web applications.
+
+> **📦 This is the NPM package documentation**  
+> **🏠 Repository**: [assistant-chat](https://github.com/vezlo/assistant-chat) - Contains both this NPM package and a standalone admin application  
+> **🖥️ Standalone App**: Want to run the admin dashboard? Visit the [main repository](https://github.com/vezlo/assistant-chat) for setup instructions
+
+## Installation
+
+```bash
+npm install @vezlo/assistant-chat
+```
+
+## Requirements
+
+- React 18 or higher
+- Tailwind CSS (for styling)
+- Assistant Server running (see [Assistant Server](https://github.com/vezlo/assistant-server))
+
+## Quick Start
+
+```tsx
+import { Widget } from '@vezlo/assistant-chat';
+
+function App() {
+  const widgetConfig = {
+    uuid: 'your-widget-uuid',
+    title: 'AI Assistant',
+    subtitle: 'How can I help you?',
+    placeholder: 'Type your message...',
+    welcomeMessage: 'Hello! How can I assist you today?',
+    themeColor: '#10b981',
+    position: 'bottom-right',
+    size: { width: 400, height: 600 },
+    defaultOpen: false
+  };
+
+  return <Widget config={widgetConfig} />;
+}
+```
+
+## Configuration
+
+The `WidgetConfig` interface includes:
+
+- `uuid`: Unique identifier for your widget
+- `title`: Header title
+- `subtitle`: Subtitle text
+- `placeholder`: Input placeholder text
+- `welcomeMessage`: Initial message shown to users
+- `themeColor`: Primary color for the widget
+- `position`: Widget position ('bottom-right', 'bottom-left', 'top-right', 'top-left')
+- `size`: Widget dimensions
+- `defaultOpen`: Whether widget opens by default
+
+### Configuration Options Table
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `uuid` | string | Required | Unique identifier for the widget |
+| `title` | string | `'AI Assistant'` | Widget header title |
+| `subtitle` | string | `'How can I help you today?'` | Widget header subtitle |
+| `placeholder` | string | `'Type your message...'` | Input placeholder text |
+| `welcomeMessage` | string | `'Hello! I\'m your AI assistant...'` | Initial message shown to users |
+| `themeColor` | string | `'#059669'` | Primary color for the widget |
+| `position` | string | `'bottom-right'` | Position: `bottom-right`, `bottom-left`, `top-right`, `top-left` |
+| `size` | object | `{ width: 420, height: 600 }` | Widget dimensions |
+| `defaultOpen` | boolean | `false` | Whether widget opens by default |
+| `apiUrl` | string | Required | Assistant Server API URL |
+| `apiKey` | string | Required | API key for authentication |
+
+## API Integration
+
+This widget requires a running Assistant Server instance. The widget will:
+
+1. Create conversations automatically
+2. Send user messages to the server
+3. Stream AI responses in real-time
+
+Configure your Assistant Server URL in your application:
+
+```tsx
+// The widget uses the API services included in this package
+import { createConversation, createUserMessage, generateAIResponse } from '@vezlo/assistant-chat';
+```
+
+For detailed API integration documentation, see [API Integration Guide](docs/API_INTEGRATION.md).
+
+## 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.
+
+## Styling
+
+The widget uses Tailwind CSS classes. Ensure your application has Tailwind CSS configured for proper styling.
+
+## Props
+
+### WidgetProps
+
+- `config`: WidgetConfig - Configuration object
+- `isPlayground?`: boolean - Internal use for playground mode
+- `onOpen?`: () => void - Callback when widget opens
+- `onClose?`: () => void - Callback when widget closes
+- `onMessage?`: (message: ChatMessage) => void - Callback for new messages
+- `onError?`: (error: string) => void - Callback for errors
+- `useShadowRoot?`: boolean - Use Shadow DOM for style isolation
+
+## Examples
+
+### Basic Usage
+
+```tsx
+import { Widget } from '@vezlo/assistant-chat';
+
+function MyApp() {
+  return (
+    <div>
+      <h1>My Website</h1>
+      <Widget config={{
+        uuid: 'my-widget-123',
+        title: 'Support Chat',
+        themeColor: '#3b82f6',
+        position: 'bottom-right',
+        defaultOpen: false
+      }} />
+    </div>
+  );
+}
+```
+
+### With Callbacks
+
+```tsx
+import { Widget, type ChatMessage } from '@vezlo/assistant-chat';
+
+function MyApp() {
+  const handleMessage = (message: ChatMessage) => {
+    console.log('New message:', message);
+  };
+
+  const handleError = (error: string) => {
+    console.error('Widget error:', error);
+  };
+
+  return (
+    <Widget 
+      config={{
+        uuid: 'my-widget-123',
+        title: 'Support Chat',
+        themeColor: '#3b82f6'
+      }}
+      onMessage={handleMessage}
+      onError={handleError}
+    />
+  );
+}
+```
+
+### Shadow DOM for Style Isolation
+
+```tsx
+import { Widget } from '@vezlo/assistant-chat';
+
+function MyApp() {
+  return (
+    <Widget 
+      config={{
+        uuid: 'my-widget-123',
+        title: 'Support Chat',
+        themeColor: '#3b82f6'
+      }}
+      useShadowRoot={true} // Isolates styles from host app
+    />
+  );
+}
+```
+
+## Troubleshooting
+
+### Widget Not Showing
+- Ensure Tailwind CSS is configured in your app
+- Check that the Assistant Server is running
+- Verify the `uuid` is unique
+
+### Style Conflicts
+- Use `useShadowRoot={true}` for style isolation
+- Ensure Tailwind CSS is properly configured
+- Check for conflicting CSS in your host application
+
+### API Errors
+- Verify Assistant Server is running and accessible
+- Check CORS settings on your Assistant Server
+- Ensure the server URL is correct
+
+## 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)
+
+## 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
+```
+
+### Code Style
+
+- Use TypeScript for all new code
+- Follow existing code patterns
+- Add tests for new features
+- Update documentation as needed
+
+## 📄 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/)

package/README.md

@@ -0,0 +1,241 @@
+# 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.
+
+## 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 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
+
+## 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',
+    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
+
+## Prerequisites
+
+- **Assistant Server**: Both components require a running Assistant Server
+- Node.js 18+ and npm
+- React 18+ (for package usage)
+
+## Features
+
+### Package Features
+- ✅ React component library
+- ✅ TypeScript support
+- ✅ Tailwind CSS styling
+- ✅ Real-time streaming
+- ✅ Customizable themes
+- ✅ Shadow DOM support
+- ✅ API integration included
+
+### App Features
+- ✅ Admin dashboard
+- ✅ Live widget preview
+- ✅ Playground testing
+- ✅ Embed code generation
+- ✅ Multiple widget management
+- ✅ Docker support
+- ✅ Vercel deployment
+
+## Deployment Options
+
+### Package (NPM)
+```bash
+npm run build
+npm pack  # Test locally
+npm publish  # Publish to NPM
+```
+
+### App (Vercel)
+
+#### One-Click Deploy
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/vezlo/assistant-chat)
+
+#### 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 environment variables
+vercel env add VITE_DEFAULT_USER_UUID
+vercel env add VITE_DEFAULT_COMPANY_UUID
+vercel env add VITE_WIDGET_DEFAULT_THEME
+vercel env add VITE_WIDGET_DEFAULT_POSITION
+vercel env add VITE_WIDGET_DEFAULT_SIZE
+
+# 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
+- **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
+
+## 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/)

package/lib/api/conversation.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Conversation API Service
+ * Handles conversation creation and management
+ */
+export interface CreateConversationRequest {
+    title: string;
+    user_uuid: string;
+    company_uuid: string;
+}
+export interface ConversationResponse {
+    uuid: string;
+    title: string;
+    user_uuid: string;
+    company_uuid: string;
+    message_count: number;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Create a new conversation
+ */
+export declare function createConversation(request: CreateConversationRequest): Promise<ConversationResponse>;
+/**
+ * Get conversation by UUID
+ */
+export declare function getConversation(uuid: string): Promise<ConversationResponse>;

package/lib/api/conversation.js

@@ -0,0 +1,52 @@
+/**
+ * Conversation API Service
+ * Handles conversation creation and management
+ */
+const API_BASE_URL = import.meta.env.VITE_ASSISTANT_SERVER_URL || 'http://localhost:3000';
+/**
+ * Create a new conversation
+ */
+export async function createConversation(request) {
+    try {
+        const response = await fetch(`${API_BASE_URL}/api/conversations`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Accept': 'application/json',
+            },
+            body: JSON.stringify(request),
+        });
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            throw new Error(errorData.message || `Failed to create conversation: ${response.status}`);
+        }
+        const data = await response.json();
+        return data;
+    }
+    catch (error) {
+        console.error('[Conversation API] Error creating conversation:', error);
+        throw error;
+    }
+}
+/**
+ * Get conversation by UUID
+ */
+export async function getConversation(uuid) {
+    try {
+        const response = await fetch(`${API_BASE_URL}/api/conversations/${uuid}`, {
+            method: 'GET',
+            headers: {
+                'Accept': 'application/json',
+            },
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to get conversation: ${response.status}`);
+        }
+        const data = await response.json();
+        return data;
+    }
+    catch (error) {
+        console.error('[Conversation API] Error getting conversation:', error);
+        throw error;
+    }
+}

package/lib/api/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * API Entry Point
+ * Central export for all API services
+ */
+export * from './conversation.js';
+export * from './message.js';

package/lib/api/index.js

@@ -0,0 +1,6 @@
+/**
+ * API Entry Point
+ * Central export for all API services
+ */
+export * from './conversation.js';
+export * from './message.js';

package/lib/api/message.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Message API Service
+ * Handles message creation and AI response generation
+ */
+export interface CreateMessageRequest {
+    content: string;
+}
+export interface MessageResponse {
+    uuid: string;
+    conversation_uuid: string;
+    type: 'user' | 'assistant';
+    content: string;
+    created_at: string;
+}
+export interface GenerateMessageResponse {
+    uuid: string;
+    parent_message_uuid: string;
+    type: 'assistant';
+    content: string;
+    status: 'completed' | 'pending' | 'error';
+    created_at: string;
+}
+/**
+ * Create a user message in a conversation
+ */
+export declare function createUserMessage(conversationUuid: string, request: CreateMessageRequest): Promise<MessageResponse>;
+/**
+ * Generate AI response for a user message
+ */
+export declare function generateAIResponse(userMessageUuid: string): Promise<GenerateMessageResponse>;

package/lib/api/message.js

@@ -0,0 +1,53 @@
+/**
+ * Message API Service
+ * Handles message creation and AI response generation
+ */
+const API_BASE_URL = import.meta.env.VITE_ASSISTANT_SERVER_URL || 'http://localhost:3000';
+/**
+ * Create a user message in a conversation
+ */
+export async function createUserMessage(conversationUuid, request) {
+    try {
+        const response = await fetch(`${API_BASE_URL}/api/conversations/${conversationUuid}/messages`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Accept': 'application/json',
+            },
+            body: JSON.stringify(request),
+        });
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            throw new Error(errorData.message || `Failed to create message: ${response.status}`);
+        }
+        const data = await response.json();
+        return data;
+    }
+    catch (error) {
+        console.error('[Message API] Error creating user message:', error);
+        throw error;
+    }
+}
+/**
+ * Generate AI response for a user message
+ */
+export async function generateAIResponse(userMessageUuid) {
+    try {
+        const response = await fetch(`${API_BASE_URL}/api/messages/${userMessageUuid}/generate`, {
+            method: 'POST',
+            headers: {
+                'Accept': 'application/json',
+            },
+        });
+        if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            throw new Error(errorData.message || `Failed to generate response: ${response.status}`);
+        }
+        const data = await response.json();
+        return data;
+    }
+    catch (error) {
+        console.error('[Message API] Error generating AI response:', error);
+        throw error;
+    }
+}

package/lib/components/Widget.d.ts

@@ -0,0 +1,11 @@
+import type { ChatMessage, WidgetConfig } from '../types/index.js';
+export interface WidgetProps {
+    config: WidgetConfig;
+    isPlayground?: boolean;
+    onOpen?: () => void;
+    onClose?: () => void;
+    onMessage?: (message: ChatMessage) => void;
+    onError?: (error: string) => void;
+    useShadowRoot?: boolean;
+}
+export declare function Widget({ config, isPlayground, onOpen, onClose, onMessage, onError, useShadowRoot, }: WidgetProps): import("react/jsx-runtime").JSX.Element;