🤖 npm-chatbot

A powerful, flexible, and type-safe AI chatbot library for TypeScript/JavaScript applications with support for OpenAI, Anthropic Claude, Google Gemini, Meta Llama, xAI Grok, DeepSeek, and Ollama (local models).

📦 Part of the Chatbot Family

This is the TypeScript/JavaScript implementation of our multi-language chatbot library:

📘 npm-chatbot - TypeScript/JavaScript (this package)
🐘 php-chatbot - PHP implementation
🔷 go-chatbot - Go implementation

All implementations share the same API design and features, making it easy to switch between languages or maintain consistency across polyglot projects.

✨ Features

AI Providers (7 Total)

🎯 OpenAI - GPT-4o, GPT-4 Turbo, o1, GPT-4o-mini
🤖 Anthropic - Claude Sonnet 4.5, Haiku 4.5, Opus 4.1
🔮 Google AI - Gemini 2.0 Flash, Gemini 1.5 Pro/Flash
🦙 Meta Llama - Llama 3.3 70B, Llama 3.2 90B Vision, Llama 3.1 405B
🚀 xAI Grok - Grok 2, Grok 2 Vision, Grok Beta
🧠 DeepSeek - DeepSeek Chat, DeepSeek Reasoner
🏠 Ollama - Any local model (llama3, mistral, codellama, etc.)

Core Features

📝 Type-Safe - Full TypeScript support with comprehensive type definitions
💾 Conversation Memory - Built-in conversation history management
⚡ Streaming Support - Real-time response streaming for all providers
🔄 Error Handling - Comprehensive error handling with retry logic
📊 Usage Tracking - Token usage and cost tracking

Safety & Security (NEW in v2.0.0)

🛡️ Message Filtering - Profanity, aggression, and link filtering
🔍 Content Moderation - AI-powered content safety with OpenAI API + custom rules
🚫 Violence Detection - Pattern-based harmful content detection
💬 Hate Speech Detection - Multi-pattern hate speech filtering
⚠️ Risk Assessment - Real-time content risk level analysis
💾 Caching & Rate Limiting - Efficient moderation with result caching

Developer Experience

🧪 Extensively Tested - 94% test coverage with 965+ tests
🌐 Universal - Works in Node.js and modern browsers
📦 Tree-Shakeable - Optimized bundle size with ESM support
📚 Comprehensive Examples - 10+ usage examples included

📦 Installation

# Using npm
npm install @rumenx/chatbot

# Using yarn
yarn add @rumenx/chatbot

# Using pnpm
pnpm add @rumenx/chatbot

Peer Dependencies

Install the AI provider SDK(s) you plan to use:

# For OpenAI (required for OpenAI provider and content moderation)
npm install openai

# For Anthropic Claude
npm install @anthropic-ai/sdk

# For Google Gemini
npm install @google/generative-ai

Note: Meta Llama, xAI Grok, DeepSeek, and Ollama providers use OpenAI-compatible APIs, so they only require the openai package (already installed above).

All provider dependencies are optional peer dependencies, so you only install what you need.

🚀 Quick Start

import { Chatbot } from '@rumenx/chatbot';

// Initialize chatbot with OpenAI
const chatbot = new Chatbot({
  provider: {
    provider: 'openai',
    apiKey: process.env.OPENAI_API_KEY!,
    model: 'gpt-4o', // Latest: 'gpt-4o', 'gpt-4-turbo', 'o1-preview'
  },
  temperature: 0.7,
  maxTokens: 150,
});

// Send a message
const response = await chatbot.chat({
  message: 'Hello! How are you?',
  metadata: {
    sessionId: 'user-123',
    userId: 'user-123',
  },
});

console.log(response.content);
// Output: "Hello! I'm doing well, thank you for asking. How can I help you today?"

💡 Usage Examples

OpenAI Example

import { Chatbot } from '@rumenx/chatbot';
import type { ChatbotConfig } from '@rumenx/chatbot';

const config: ChatbotConfig = {
  provider: {
    provider: 'openai',
    apiKey: process.env.OPENAI_API_KEY!,
    model: 'gpt-4o', // Latest: 'gpt-4o', 'gpt-4-turbo', 'o1-preview' (Note: gpt-3.5-turbo deprecated)
  },
  systemPrompt: 'You are a helpful AI assistant.',
  temperature: 0.7,
  maxTokens: 500,
  enableMemory: true,
  maxHistory: 20,
  security: {
    enableInputFilter: true,
    enableOutputFilter: true,
    maxInputLength: 4000,
  },
  rateLimit: {
    enabled: true,
    requestsPerMinute: 10,
    requestsPerHour: 100,
  },
};

const chatbot = new Chatbot(config);

// Simple chat
const response = await chatbot.chat({
  message: 'What is the capital of France?',
  metadata: {
    sessionId: 'session-1',
    userId: 'user-1',
  },
});

console.log(response.content); // "The capital of France is Paris."
console.log(response.metadata.usage); // { promptTokens: 15, completionTokens: 8, totalTokens: 23 }

Anthropic Claude Example

import { Chatbot } from '@rumenx/chatbot';

const chatbot = new Chatbot({
  provider: {
    provider: 'anthropic',
    apiKey: process.env.ANTHROPIC_API_KEY!,
    model: 'claude-sonnet-4-5-20250929', // Latest: Claude Sonnet 4.5 (Sep 2025), Opus 4.1, Haiku 4.5
  },
  temperature: 0.8,
  maxTokens: 1000,
});

const response = await chatbot.chat({
  message: 'Explain quantum computing in simple terms.',
  metadata: {
    sessionId: 'session-2',
    userId: 'user-2',
  },
});

console.log(response.content);

Google Gemini Example

import { Chatbot } from '@rumenx/chatbot';

const chatbot = new Chatbot({
  provider: {
    provider: 'google',
    apiKey: process.env.GOOGLE_API_KEY!,
    model: 'gemini-2.0-flash-exp', // Latest: 'gemini-2.0-flash-exp', 'gemini-1.5-pro', 'gemini-1.5-flash'
  },
  temperature: 0.9,
  maxTokens: 800,
});

const response = await chatbot.chat({
  message: 'Write a haiku about programming.',
  metadata: {
    sessionId: 'session-3',
    userId: 'user-3',
  },
});

console.log(response.content);

Meta Llama Example

import { Chatbot } from '@rumenx/chatbot';

const chatbot = new Chatbot({
  provider: {
    provider: 'meta',
    apiKey: process.env.TOGETHER_API_KEY!, // Together AI API key
    model: 'llama-3.3-70b-instruct', // Latest: 'llama-3.3-70b-instruct', 'llama-3.2-90b-vision-instruct', 'llama-3.1-405b-instruct'
    endpoint: 'https://api.together.xyz/v1', // Optional, defaults to Together AI
  },
  temperature: 0.7,
  maxTokens: 500,
});

const response = await chatbot.chat({
  message: 'Explain the concept of neural networks.',
  metadata: {
    sessionId: 'session-4',
    userId: 'user-4',
  },
});

console.log(response.content);

xAI Grok Example

import { Chatbot } from '@rumenx/chatbot';

const chatbot = new Chatbot({
  provider: {
    provider: 'xai',
    apiKey: process.env.XAI_API_KEY!,
    model: 'grok-2-latest', // Latest: 'grok-2-latest', 'grok-2-vision-latest', 'grok-beta'
  },
  temperature: 0.8,
  maxTokens: 800,
});

const response = await chatbot.chat({
  message: 'What are the latest trends in AI?',
  metadata: {
    sessionId: 'session-5',
    userId: 'user-5',
  },
});

console.log(response.content);

DeepSeek Example

import { Chatbot } from '@rumenx/chatbot';

const chatbot = new Chatbot({
  provider: {
    provider: 'deepseek',
    apiKey: process.env.DEEPSEEK_API_KEY!,
    model: 'deepseek-chat', // Options: 'deepseek-chat', 'deepseek-reasoner'
  },
  temperature: 0.7,
  maxTokens: 1000,
});

const response = await chatbot.chat({
  message: 'Write a function to calculate fibonacci numbers.',
  metadata: {
    sessionId: 'session-6',
    userId: 'user-6',
  },
});

console.log(response.content);

Ollama (Local Models) Example

import { Chatbot } from '@rumenx/chatbot';

const chatbot = new Chatbot({
  provider: {
    provider: 'ollama',
    model: 'llama3', // Any Ollama model: 'llama3', 'mistral', 'codellama', etc.
    endpoint: 'http://localhost:11434/v1', // Your Ollama server URL
  },
  temperature: 0.7,
  maxTokens: 500,
});

const response = await chatbot.chat({
  message: 'Hello! Tell me about yourself.',
  metadata: {
    sessionId: 'session-7',
    userId: 'user-7',
  },
});

console.log(response.content);

Message Filtering Example

Protect your application from inappropriate content:

import { Chatbot, MessageFilterMiddleware } from '@rumenx/chatbot';

// Create filter with custom configuration
const filter = new MessageFilterMiddleware({
  profanities: ['badword1', 'badword2'], // Custom word list
  aggressionPatterns: ['hate', 'kill', 'attack'], // Patterns to detect
  linkPattern: 'https?:\\/\\/[\\w\\.-]+', // URL detection
  enableRephrasing: true, // Rephrase instead of blocking
  replacementText: '[filtered]', // Replacement text
  instructions: [
    'You must maintain a respectful tone.',
    'Do not share external links.',
    'Use appropriate language at all times.',
  ],
});

const chatbot = new Chatbot({
  provider: {
    provider: 'openai',
    apiKey: process.env.OPENAI_API_KEY!,
    model: 'gpt-4o',
  },
});

// Filter user message before sending
const userMessage = 'This is a fucking great product!';
const filterResult = filter.filter(userMessage);

if (filterResult.shouldBlock) {
  console.log('Message blocked:', filterResult.filterReasons);
} else {
  console.log('Filtered message:', filterResult.message);
  // Output: "This is a [filtered] great product!"

  const response = await chatbot.chat({
    message: filterResult.message,
    context: filterResult.context, // Includes system instructions
  });
}

Content Moderation Example

AI-powered content safety with OpenAI's Moderation API:

import { ContentModerationService } from '@rumenx/chatbot';

// Create moderation service
const moderation = new ContentModerationService({
  apiKey: process.env.OPENAI_API_KEY, // For OpenAI moderation API
  useOpenAI: true, // Use OpenAI's moderation API
  useCustomRules: true, // Also use custom pattern matching
  threshold: 0.5, // Block threshold (0-1)
  enableCache: true, // Cache results
  cacheTTL: 300000, // 5 minutes
});

// Check content before processing
const message = 'I want to hurt someone';
const result = await moderation.moderate(message);

if (result.shouldBlock) {
  console.log('Content blocked!');
  console.log('Flagged categories:', result.categories);
  // Output: ['violence', 'violence/graphic']
  console.log('Scores:', result.scores);
} else {
  // Safe to process
  const response = await chatbot.chat({ message });
}

// Get risk statistics
const stats = await moderation.getStats(message);
console.log('Risk Level:', stats.riskLevel); // 'low', 'medium', 'high', or 'critical'
console.log('Is Safe:', stats.isSafe);
console.log('Highest Risk:', stats.highestCategory);

Combined Safety Approach

Use both filtering and moderation for maximum protection:

import {
  Chatbot,
  MessageFilterMiddleware,
  ContentModerationService,
} from '@rumenx/chatbot';

const chatbot = new Chatbot({
  provider: {
    provider: 'openai',
    apiKey: process.env.OPENAI_API_KEY!,
    model: 'gpt-4o',
  },
});

const filter = new MessageFilterMiddleware();
const moderation = new ContentModerationService({
  apiKey: process.env.OPENAI_API_KEY,
  useOpenAI: true,
  useCustomRules: true,
});

async function safeChat(userMessage: string) {
  // 1. Filter profanity and links
  const filterResult = filter.filter(userMessage);
  if (filterResult.shouldBlock) {
    return 'Your message contains inappropriate language.';
  }

  // 2. Check for harmful content
  if (await moderation.shouldBlock(filterResult.message)) {
    return 'Your message violates our content policy.';
  }

  // 3. Safe to send to AI
  const response = await chatbot.chat({
    message: filterResult.message,
    context: filterResult.context,
  });

  return response.content;
}

const reply = await safeChat('Tell me about AI safety');
console.log(reply);

Streaming Responses

Stream responses in real-time for better UX:

import { Chatbot } from '@rumenx/chatbot';

const chatbot = new Chatbot({
  provider: {
    provider: 'openai',
    apiKey: process.env.OPENAI_API_KEY!,
    model: 'gpt-4o',
  },
});

// Stream responses
const stream = chatbot.chatStream({
  message: 'Tell me a story about a robot.',
  metadata: {
    sessionId: 'session-4',
    userId: 'user-4',
  },
});

// Process the stream
for await (const chunk of stream) {
  process.stdout.write(chunk); // Print each chunk as it arrives
}

console.log('\n✅ Stream complete!');

Conversation Memory

The chatbot automatically maintains conversation history:

import { Chatbot } from '@rumenx/chatbot';

const chatbot = new Chatbot({
  provider: {
    provider: 'openai',
    apiKey: process.env.OPENAI_API_KEY!,
    model: 'gpt-4o-mini', // Cost-effective model for conversations
  },
  enableMemory: true,
  maxHistory: 10, // Keep last 10 messages
});

const sessionId = 'user-session-123';

// First message
await chatbot.chat({
  message: 'My name is Alice.',
  metadata: { sessionId, userId: 'alice' },
});

// Second message - chatbot remembers the context
const response = await chatbot.chat({
  message: 'What is my name?',
  metadata: { sessionId, userId: 'alice' },
});

console.log(response.content); // "Your name is Alice."

// Get conversation history
const history = chatbot.getConversationHistory(sessionId);
console.log(history); // Array of all messages in the session

Using with React

Here's an example of integrating the chatbot into a React application:

import React, { useState } from 'react';
import { Chatbot } from '@rumenx/chatbot';

const chatbot = new Chatbot({
  provider: {
    provider: 'openai',
    apiKey: process.env.OPENAI_API_KEY!,
    model: 'gpt-4o-mini',
  },
});

function ChatComponent() {
  const [messages, setMessages] = useState<
    Array<{ role: string; content: string }>
  >([]);
  const [input, setInput] = useState('');
  const [loading, setLoading] = useState(false);

  const sendMessage = async () => {
    if (!input.trim()) return;

    // Add user message
    setMessages((prev) => [...prev, { role: 'user', content: input }]);
    setLoading(true);

    try {
      const response = await chatbot.chat({
        message: input,
        metadata: {
          sessionId: 'react-session',
          userId: 'react-user',
        },
      });

      // Add assistant response
      setMessages((prev) => [
        ...prev,
        { role: 'assistant', content: response.content },
      ]);
    } catch (error) {
      console.error('Chat error:', error);
    } finally {
      setLoading(false);
      setInput('');
    }
  };

  return (
    <div className="chat-container">
      <div className="messages">
        {messages.map((msg, idx) => (
          <div key={idx} className={`message ${msg.role}`}>
            <strong>{msg.role}:</strong> {msg.content}
          </div>
        ))}
      </div>
      <div className="input-area">
        <input
          type="text"
          value={input}
          onChange={(e) => setInput(e.target.value)}
          onKeyPress={(e) => e.key === 'Enter' && sendMessage()}
          placeholder="Type a message..."
          disabled={loading}
        />
        <button onClick={sendMessage} disabled={loading}>
          {loading ? 'Sending...' : 'Send'}
        </button>
      </div>
    </div>
  );
}

export default ChatComponent;

Using with Express.js

Here's an example of using the chatbot in an Express.js API:

import express from 'express';
import { Chatbot } from '@rumenx/chatbot';

const app = express();
app.use(express.json());

const chatbot = new Chatbot({
  provider: {
    provider: 'openai',
    apiKey: process.env.OPENAI_API_KEY!,
    model: 'gpt-4o-mini',
  },
  enableMemory: true,
});

// Chat endpoint
app.post('/api/chat', async (req, res) => {
  try {
    const { message, sessionId, userId } = req.body;

    if (!message || !sessionId || !userId) {
      return res.status(400).json({ error: 'Missing required fields' });
    }

    const response = await chatbot.chat({
      message,
      metadata: { sessionId, userId },
    });

    res.json({
      content: response.content,
      metadata: response.metadata,
    });
  } catch (error) {
    console.error('Chat error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

// Streaming endpoint
app.post('/api/chat/stream', async (req, res) => {
  try {
    const { message, sessionId, userId } = req.body;

    res.setHeader('Content-Type', 'text/event-stream');
    res.setHeader('Cache-Control', 'no-cache');
    res.setHeader('Connection', 'keep-alive');

    const stream = chatbot.chatStream({
      message,
      metadata: { sessionId, userId },
    });

    for await (const chunk of stream) {
      res.write(`data: ${JSON.stringify({ chunk })}\n\n`);
    }

    res.write('data: [DONE]\n\n');
    res.end();
  } catch (error) {
    console.error('Stream error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

// Get conversation history
app.get('/api/chat/history/:sessionId', (req, res) => {
  try {
    const { sessionId } = req.params;
    const history = chatbot.getConversationHistory(sessionId);
    res.json({ history });
  } catch (error) {
    console.error('History error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

// Health check
app.get('/health', (req, res) => {
  res.json({ status: 'ok', version: '1.0.0' });
});

app.listen(3000, () => {
  console.log('🚀 Chatbot API running on http://localhost:3000');
});

⚙️ Configuration

Supported Models (October 2025)

OpenAI Models

Model	Status	Use Case
`gpt-4o`	✅ Recommended	Latest flagship model, best for complex tasks
`gpt-4o-mini`	✅ Recommended	Cost-effective, great for most use cases
`gpt-4-turbo`	✅ Supported	High performance, large context window
`o1-preview`	✅ Supported	Advanced reasoning model
`o1-mini`	✅ Supported	Faster reasoning model
`gpt-4`	⚠️ Legacy	Still supported, but consider upgrading
`gpt-3.5-turbo`	❌ Deprecated	Will be retired June 2025, use `gpt-4o-mini` instead

Anthropic Models

Model	Status	Use Case
`claude-sonnet-4-5-20250929`	✅ Recommended	Latest - smartest model for complex agents and coding
`claude-haiku-4-5-20251001`	✅ Recommended	Fastest model with near-frontier intelligence
`claude-opus-4-1-20250805`	✅ Recommended	Exceptional model for specialized reasoning
`claude-3-5-sonnet-20241022`	✅ Supported	Previous generation (legacy)
`claude-3-5-sonnet-20240620`	⚠️ Legacy	Consider upgrading to 4.5
`claude-3-opus-20240229`	⚠️ Legacy	Consider upgrading to 4.1

Google AI Models

Model	Status	Use Case
`gemini-2.0-flash-exp`	✅ Recommended	Latest experimental model
`gemini-1.5-pro`	✅ Recommended	Production-ready, 2M token context
`gemini-1.5-flash`	✅ Recommended	Fast and efficient
`gemini-1.5-flash-8b`	✅ Supported	Smallest, fastest, most affordable
`gemini-pro`	⚠️ Legacy	Consider upgrading to 1.5 or 2.0

Note: Model availability and naming may change. Check your provider's documentation for the latest model names.

Complete Configuration Options

import type { ChatbotConfig } from '@rumenx/chatbot';

const config: ChatbotConfig = {
  // Provider configuration (required)
  provider: {
    provider: 'openai', // 'openai' | 'anthropic' | 'google'
    apiKey: 'your-api-key',
    model: 'gpt-4',
    apiUrl: 'https://api.openai.com/v1', // Optional: custom API endpoint
    organizationId: 'org-123', // Optional: OpenAI organization ID
  },

  // Generation options
  temperature: 0.7, // 0.0 to 1.0 (higher = more creative)
  maxTokens: 500, // Maximum tokens in response
  topP: 0.9, // Optional: nucleus sampling
  frequencyPenalty: 0, // Optional: -2.0 to 2.0
  presencePenalty: 0, // Optional: -2.0 to 2.0
  stop: ['###'], // Optional: stop sequences

  // System configuration
  systemPrompt: 'You are a helpful AI assistant.', // Optional: system message
  enableMemory: true, // Enable conversation history
  maxHistory: 20, // Maximum messages to keep in memory
  timeout: 30000, // Request timeout in ms

  // Security settings
  security: {
    enableInputFilter: true, // Filter user input
    enableOutputFilter: true, // Filter AI responses
    maxInputLength: 4000, // Maximum input length
    blockedPatterns: [/password/i], // Regex patterns to block
  },

  // Rate limiting
  rateLimit: {
    enabled: true,
    requestsPerMinute: 10,
    requestsPerHour: 100,
    requestsPerDay: 1000,
  },

  // Logging
  logLevel: 'info', // 'debug' | 'info' | 'warn' | 'error'

  // Custom metadata
  metadata: {
    appName: 'My Chatbot App',
    version: '1.0.0',
  },
};

🤖 Supported AI Models

OpenAI

gpt-4o - Latest GPT-4 Omni model (Oct 2024)
gpt-4o-mini - Fast and cost-effective GPT-4 Omni mini
gpt-4-turbo - GPT-4 Turbo (Apr 2024)
o1-preview - Advanced reasoning model (preview)
o1-mini - Fast reasoning model

Anthropic Claude

claude-sonnet-4-5-20250929 - Claude Sonnet 4.5 (Sep 2025) - Latest
claude-haiku-4-5-20250929 - Claude Haiku 4.5 (Sep 2025) - Fast & efficient
claude-opus-4-1-20250929 - Claude Opus 4.1 (Sep 2025) - Most capable

Google Gemini

gemini-2.0-flash-exp - Gemini 2.0 Flash (Experimental) - Latest
gemini-1.5-pro - Gemini 1.5 Pro - High capability
gemini-1.5-flash - Gemini 1.5 Flash - Fast & efficient

Meta Llama (via Together AI)

llama-3.3-70b-instruct - Llama 3.3 70B (Latest)
llama-3.2-90b-vision-instruct - Llama 3.2 90B with vision
llama-3.1-405b-instruct - Llama 3.1 405B (Largest)

xAI Grok

grok-2-latest - Grok 2 (Latest)
grok-2-vision-latest - Grok 2 with vision capabilities
grok-beta - Grok Beta (Experimental features)

DeepSeek

deepseek-chat - DeepSeek Chat model
deepseek-reasoner - DeepSeek Reasoner (Advanced reasoning)

Ollama (Local Models)

llama3 - Llama 3 (8B, 70B variants)
mistral - Mistral 7B
codellama - Code Llama (7B, 13B, 34B, 70B)
phi3 - Microsoft Phi-3
gemma - Google Gemma
qwen - Alibaba Qwen
Any other Ollama model - See Ollama Model Library

Note: For Meta, xAI, DeepSeek, and Ollama, you need to provide the API endpoint URL in the configuration. See examples above.

📚 API Reference

Chatbot Class

Constructor

new Chatbot(config: ChatbotConfig)

Methods

`chat(options: ChatOptions): Promise<ChatResponse>`

Send a message and get a response.

const response = await chatbot.chat({
  message: 'Hello!',
  metadata: {
    sessionId: 'session-id',
    userId: 'user-id',
  },
});

`chatStream(options: ChatOptions): AsyncGenerator<string>`

Stream a response in real-time.

for await (const chunk of chatbot.chatStream({ message: 'Hello!' })) {
  console.log(chunk);
}

`getConversationHistory(sessionId: string): ChatMessage[]`

Get conversation history for a session.

const history = chatbot.getConversationHistory('session-id');

`clearConversationHistory(sessionId: string): void`

Clear conversation history for a session.

chatbot.clearConversationHistory('session-id');

`updateConfig(config: Partial<ChatbotConfig>): void`

Update chatbot configuration.

chatbot.updateConfig({
  temperature: 0.9,
  maxTokens: 1000,
});

`getProviderInfo(): ProviderInfo`

Get information about the current provider.

const info = chatbot.getProviderInfo();
console.log(info); // { name: 'openai', model: 'gpt-4', ... }

Types

interface ChatbotConfig {
  provider: AiProviderConfig;
  temperature?: number;
  maxTokens?: number;
  enableMemory?: boolean;
  maxHistory?: number;
  security?: SecurityConfig;
  rateLimit?: RateLimitConfig;
  // ... more options
}

interface ChatOptions {
  message: string;
  metadata?: {
    sessionId?: string;
    userId?: string;
    [key: string]: unknown;
  };
}

interface ChatResponse {
  content: string;
  metadata: {
    provider: string;
    model: string;
    usage?: {
      promptTokens: number;
      completionTokens: number;
      totalTokens: number;
    };
    responseTime?: number;
  };
}

🎨 Usage with Popular Frameworks

This library is framework-agnostic and can be used with any JavaScript framework or library. Here are examples for popular frameworks:

React

npm install @rumenx/chatbot react

See Using with React example above for a complete integration.

Vue 3

The library works seamlessly with Vue 3. Here's a basic example:

npm install @rumenx/chatbot vue

<template>
  <div class="chat-container">
    <div
      v-for="(msg, idx) in messages"
      :key="idx"
      :class="`message ${msg.role}`"
    >
      <strong>{{ msg.role }}:</strong> {{ msg.content }}
    </div>
    <input
      v-model="input"
      @keyup.enter="sendMessage"
      placeholder="Type a message..."
    />
    <button @click="sendMessage" :disabled="loading">
      {{ loading ? 'Sending...' : 'Send' }}
    </button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { Chatbot } from '@rumenx/chatbot';

const chatbot = new Chatbot({
  provider: {
    provider: 'openai',
    apiKey: import.meta.env.VITE_OPENAI_API_KEY,
    model: 'gpt-3.5-turbo',
  },
});

const messages = ref<Array<{ role: string; content: string }>>([]);
const input = ref('');
const loading = ref(false);

const sendMessage = async () => {
  if (!input.value.trim()) return;

  messages.value.push({ role: 'user', content: input.value });
  loading.value = true;

  try {
    const response = await chatbot.chat({
      message: input.value,
      metadata: { sessionId: 'vue-session', userId: 'vue-user' },
    });

    messages.value.push({ role: 'assistant', content: response.content });
  } catch (error) {
    console.error('Chat error:', error);
  } finally {
    loading.value = false;
    input.value = '';
  }
};
</script>

Next.js

npm install @rumenx/chatbot next

// app/api/chat/route.ts
import { Chatbot } from '@rumenx/chatbot';
import { NextRequest, NextResponse } from 'next/server';

const chatbot = new Chatbot({
  provider: {
    provider: 'openai',
    apiKey: process.env.OPENAI_API_KEY!,
    model: 'gpt-3.5-turbo',
  },
});

export async function POST(request: NextRequest) {
  const { message, sessionId, userId } = await request.json();

  try {
    const response = await chatbot.chat({
      message,
      metadata: { sessionId, userId },
    });

    return NextResponse.json(response);
  } catch (error) {
    return NextResponse.json({ error: 'Chat failed' }, { status: 500 });
  }
}

🛡️ Error Handling

The library provides comprehensive error handling:

import { Chatbot, ChatbotError } from '@rumenx/chatbot';

const chatbot = new Chatbot({
  provider: {
    provider: 'openai',
    apiKey: process.env.OPENAI_API_KEY!,
    model: 'gpt-4',
  },
});

try {
  const response = await chatbot.chat({
    message: 'Hello!',
    metadata: { sessionId: 'session-1', userId: 'user-1' },
  });
  console.log(response.content);
} catch (error) {
  if (error instanceof ChatbotError) {
    console.error('Error category:', error.category);
    console.error('Error severity:', error.severity);
    console.error('Is retryable:', error.isRetryable);
    console.error('Retry delay:', error.retryDelay);

    // Handle specific error types
    switch (error.category) {
      case 'authentication':
        console.error('Authentication failed. Check your API key.');
        break;
      case 'rate_limit':
        console.error('Rate limit exceeded. Retry after:', error.retryDelay);
        break;
      case 'validation':
        console.error('Invalid input:', error.userMessage);
        break;
      case 'network':
        console.error('Network error. Check your connection.');
        break;
      default:
        console.error('Unexpected error:', error.message);
    }
  } else {
    console.error('Unknown error:', error);
  }
}

Error Categories

authentication - API key or authentication issues
rate_limit - Rate limit exceeded
validation - Invalid input or configuration
network - Network connectivity issues
provider - Provider-specific errors
timeout - Request timeout
unknown - Unexpected errors

🔒 Security

Input/Output Filtering

const chatbot = new Chatbot({
  provider: {
    provider: 'openai',
    apiKey: process.env.OPENAI_API_KEY!,
    model: 'gpt-3.5-turbo',
  },
  security: {
    enableInputFilter: true, // Filter malicious input
    enableOutputFilter: true, // Filter inappropriate responses
    maxInputLength: 4000, // Prevent oversized inputs
    blockedPatterns: [/password/i, /credit card/i, /social security/i],
  },
});

Rate Limiting

const chatbot = new Chatbot({
  provider: {
    provider: 'openai',
    apiKey: process.env.OPENAI_API_KEY!,
    model: 'gpt-3.5-turbo',
  },
  rateLimit: {
    enabled: true,
    requestsPerMinute: 10,
    requestsPerHour: 100,
    requestsPerDay: 1000,
  },
});

For more details, see SECURITY.md.

🗺️ Roadmap

We're constantly working to improve and expand the library. Here's what's planned for future releases:

🔮 Planned Features (Not Yet Implemented)

Additional AI Providers

The following providers are planned but not yet implemented. Community contributions are welcome!

Provider	Status	Target Version	Notes
Meta Llama	📋 Planned	v2.x	Llama 3.3, 3.2, 3.1 support via Ollama or cloud APIs
xAI Grok	📋 Planned	v2.x	Grok-2, Grok-2-mini integration
DeepSeek	📋 Planned	v2.x	DeepSeek-V3 and DeepSeek-R1 support
Ollama	📋 Planned	v2.x	Local LLM support with Ollama
Mistral AI	📋 Planned	v2.x	Mistral Large, Medium, Small models
Cohere	📋 Planned	v2.x	Command R+, Command R models
Perplexity	📋 Planned	v3.x	pplx-7b-online, pplx-70b-online

Framework Integrations

Framework	Status	Target Version	Description
React Components	📋 Planned	v2.x	Pre-built `<ChatWidget />`, `<ChatInput />`, `<MessageList />`
Vue 3 Components	📋 Planned	v2.x	Composition API components
Angular Components	📋 Planned	v3.x	Standalone components for Angular 15+
Svelte Components	📋 Planned	v3.x	Svelte 5 components
Express Middleware	📋 Planned	v2.x	`app.use(chatbot.middleware())`
Next.js Integration	📋 Planned	v2.x	Server actions and route handlers
Fastify Plugin	📋 Planned	v2.x	`fastify.register(chatbotPlugin)`

Advanced Features

🔮 Function Calling / Tool Use - Support for OpenAI functions, Anthropic tools
🔮 Multi-Modal Support - Image, audio, and video inputs
🔮 RAG Integration - Vector database integration for retrieval-augmented generation
🔮 Prompt Templates - Pre-built templates for common use cases
🔮 Agent Framework - Build autonomous agents with planning and execution
🔮 Fine-tuning Support - Train and deploy custom models
🔮 Cost Optimization - Automatic model selection based on budget
🔮 A/B Testing - Test different models and prompts

✅ Currently Implemented

✅ OpenAI (GPT-4o, GPT-4 Turbo, o1, GPT-4o-mini)
✅ Anthropic (Claude Sonnet 4.5, Haiku 4.5, Opus 4.1)
✅ Google AI (Gemini 2.0, Gemini 1.5 Pro/Flash)
✅ Streaming support for all providers
✅ Conversation memory management
✅ Type-safe TypeScript APIs
✅ Error handling with retries
✅ Rate limiting and security
✅ Token usage tracking
✅ 94% test coverage

🤝 Contributing to Roadmap

Want to help implement these features? Check out our Contributing Guide and:

Pick a feature from the roadmap
Open an issue to discuss implementation
Submit a PR with your implementation
Get recognized as a contributor!

Priority is given to features with community interest. Open an issue to vote on features you'd like to see!

🧪 Testing

The library has 94% test coverage with 880+ tests.

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run fast tests only
npm run test:fast

Writing Tests

import { Chatbot } from '@rumenx/chatbot';

describe('Chatbot', () => {
  it('should send a message and receive a response', async () => {
    const chatbot = new Chatbot({
      provider: {
        provider: 'openai',
        apiKey: 'test-key',
        model: 'gpt-3.5-turbo',
      },
    });

    const response = await chatbot.chat({
      message: 'Hello!',
      metadata: { sessionId: 'test', userId: 'test' },
    });

    expect(response.content).toBeDefined();
    expect(response.metadata.provider).toBe('openai');
  });
});

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Development Setup

# Clone the repository
git clone https://github.com/RumenDamyanov/npm-chatbot.git
cd npm-chatbot

# Install dependencies
npm install

# Run tests
npm test

# Build the project
npm run build

# Run examples
npm run example:openai

Code of Conduct

Please read our Code of Conduct before contributing.

📄 License

This project is licensed under the MIT License - see the LICENSE.md file for details.

💖 Support

If you find this library helpful, please consider:

⭐ Starring the repository
🐛 Reporting bugs via GitHub Issues
💡 Suggesting new features
📖 Improving documentation
💰 Sponsoring the project

📊 Changelog

See CHANGELOG.md for version history and release notes.

Made with ❤️ by Rumen Damyanov

Name		Name	Last commit message	Last commit date
Latest commit History 111 Commits
.github		.github
examples		examples
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
FUNDING.md		FUNDING.md
LICENSE.md		LICENSE.md
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.cjs		eslint.config.cjs
jest.config.fast.js		jest.config.fast.js
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.cjs.json		tsconfig.cjs.json
tsconfig.json		tsconfig.json
tsconfig.lint.json		tsconfig.lint.json

Uh oh!

License

RumenDamyanov/npm-chatbot

Folders and files

Latest commit

History

Repository files navigation