@aivue/chatbot-server

Backend utilities and database integration for @aivue/chatbot.

Note: This is an optional package that provides server-side functionality for storing and managing chatbot conversations. It is not required for using the @aivue/chatbot package, but it provides additional features for applications that need to store conversation history.

Features

• Database storage for chatbot conversations
• Support for multiple databases and ORMs:
  • PostgreSQL, MySQL, SQLite, MongoDB
  • Sequelize, Mongoose, Drizzle, Prisma
• Admin API for conversation management
• Easy integration with Express.js applications
• Flexible configuration options

Installation

npm install @aivue/chatbot-server

You'll also need to install the ORM of your choice:

# For Sequelize
npm install sequelize

# For Mongoose
npm install mongoose

# For Drizzle
npm install drizzle-orm

# For Prisma
npm install prisma @prisma/client

Quick Start

const express = require('express');
const { createChatbotServer } = require('@aivue/chatbot-server');

async function start() {
  // Create Express app
  const app = express();

  // Create chatbot server
  const chatbotServer = await createChatbotServer({
    database: {
      type: 'postgres',
      orm: 'sequelize',
      connectionString: process.env.DATABASE_URL
    },
    auth: {
      adminApiKey: process.env.ADMIN_API_KEY
    }
  });

  // Mount chatbot server middleware
  app.use('/api', chatbotServer.middleware);

  // Start server
  app.listen(3000, () => {
    console.log('Server running on port 3000');
  });
}

start().catch(console.error);

Configuration

The createChatbotServer function accepts a configuration object with the following options:

interface ChatbotServerConfig {
  // Required: Database configuration
  database: {
    type: 'postgres' | 'mysql' | 'sqlite' | 'mongodb';
    orm: 'sequelize' | 'mongoose' | 'drizzle' | 'prisma';
    connectionString?: string;
    host?: string;
    port?: number;
    username?: string;
    password?: string;
    database?: string;
    file?: string; // For SQLite
    options?: Record<string, any>;
  };

  // Optional: Authentication configuration
  auth?: {
    adminApiKey?: string;
    apiKeyHeader?: string;
    jwtSecret?: string;
    jwtExpiresIn?: string;
  };

  // Optional: API configuration
  api?: {
    basePath?: string;
    adminPath?: string;
    enableCors?: boolean;
    corsOptions?: Record<string, any>;
  };

  // Optional: Storage configuration
  storage?: {
    messageLimit?: number;
    enableArchiving?: boolean;
    archiveAfterDays?: number;
    deleteAfterDays?: number;
  };

  // Optional: Logging configuration
  logging?: {
    level?: 'error' | 'warn' | 'info' | 'debug';
    format?: 'json' | 'text';
    file?: string;
  };
}

API Endpoints

Chat Endpoints

• POST /api/chat - Process a chat message and store it in the database
• GET /api/user/:userId/conversations - Get conversations for a specific user

Admin Endpoints

All admin endpoints require authentication using the X-Admin-API-Key header.

• GET /api/admin/conversations - List all conversations with pagination and filtering
• GET /api/admin/conversations/:id - Get a specific conversation with all messages
• POST /api/admin/conversations/:id/status - Update a conversation's status
• GET /api/admin/stats - Get conversation statistics

Integration with @aivue/chatbot

This package is designed to work seamlessly with the @aivue/chatbot package. The @aivue/chatbot package has been enhanced to support server-side persistence through the serverPersistence option.

Client-Side Configuration

To use this server with the @aivue/chatbot package, configure the chatbot to use the server for persistence:

import { useChatEngine } from '@aivue/chatbot';

const {
  messages,
  isLoading,
  error,
  conversationId,
  sendMessage
} = useChatEngine({
  provider: 'openai',
  apiKey: process.env.OPENAI_API_KEY,

  // Enable server persistence
  serverPersistence: true,
  userId: 123, // Optional user ID

  useProxy: true,
  proxyUrl: '/api/chat'
});

How It Works

1. The @aivue/chatbot package sends chat messages to the server endpoint
2. The server stores the messages in the database
3. The server returns the AI response along with a conversation ID
4. The client stores the conversation ID for future messages
5. Subsequent messages are associated with the same conversation

This allows you to:

• Store conversation history for later retrieval
• Build admin interfaces to view and manage conversations
• Analyze conversation data
• Implement user-specific conversation history

Advanced Usage

Standalone Server

You can run the chatbot server as a standalone Express application:

const { createChatbotServer } = require('@aivue/chatbot-server');

async function start() {
  const server = await createChatbotServer({
    database: {
      type: 'postgres',
      orm: 'sequelize',
      connectionString: process.env.DATABASE_URL
    }
  });

  // Start the server on port 3000
  await server.start(3000);
}

start().catch(console.error);

Using Individual Components

You can also use the individual components of the package:

const express = require('express');
const {
  createDatabaseConnection,
  getModels,
  createChatRoutes,
  createAdminRoutes,
  adminAuthMiddleware
} = require('@aivue/chatbot-server');

async function start() {
  // Create database connection
  const db = await createDatabaseConnection({
    type: 'postgres',
    orm: 'sequelize',
    connectionString: process.env.DATABASE_URL
  });

  // Get models
  const models = await getModels('sequelize', db);

  // Create Express app
  const app = express();
  app.use(express.json());

  // Create chat routes
  const chatRoutes = createChatRoutes({
    db,
    orm: 'sequelize',
    models
  });

  // Create admin routes
  const adminRoutes = createAdminRoutes({
    db,
    orm: 'sequelize',
    models,
    auth: {
      adminApiKey: process.env.ADMIN_API_KEY
    }
  });

  // Mount routes
  app.use('/api', chatRoutes);
  app.use('/api/admin', adminRoutes);

  // Start server
  app.listen(3000, () => {
    console.log('Server running on port 3000');
  });
}

start().catch(console.error);

License

MIT