wexa-chat 0.1.0

package/README.md

@@ -0,0 +1,210 @@
+# @yourorg/chat-core
+
+A TypeScript library for building real-time chat functionality with MongoDB and optional Redis support.
+
+## Features
+
+- Real-time messaging with Redis pub/sub
+- MongoDB-backed conversation and message storage
+- Socket.IO integration
+- Thread support
+- Read receipts
+- Typing indicators
+- Presence tracking
+- Text search capabilities
+
+## Installation
+
+```bash
+npm install @yourorg/chat-core mongoose ioredis socket.io
+```
+
+## Quick Start
+
+```typescript
+import mongoose from 'mongoose';
+import { createServer } from 'http';
+import { initChat } from '@yourorg/chat-core';
+
+async function setup() {
+  // Create HTTP server (for Socket.IO)
+  const server = createServer();
+
+  // Initialize chat services
+  const chat = await initChat(mongoose, {
+    // Required
+    participantModels: ['User'],
+    memberRoles: ['member'],
+    mongoUri: 'mongodb://localhost:27017/your-database',
+
+    // Redis Configuration (optional)
+    redis: {
+      // Option 1: Use URL
+      url: 'redis://localhost:6379',
+      
+      // Option 2: Use individual settings (used if url is not set)
+      host: 'localhost',
+      port: 6379,
+      password: 'optional-password',
+      db: 0,
+      socketConnectTimeout: 10000,
+      keepAlive: 5000
+    },
+
+    // Socket.IO Configuration (optional)
+    socket: {
+      path: '/socket.io',
+      cors: {
+        origin: 'http://localhost:3000',
+        methods: ['GET', 'POST']
+      }
+    },
+
+    // Optional Features
+    enableTextSearch: true,
+    presence: {
+      enabled: true,
+      heartbeatSec: 30
+    },
+    rateLimit: {
+      sendPerMin: 60,
+      typingPerMin: 10
+    }
+  }, server); // Pass the HTTP server for Socket.IO
+
+  // Start the server
+  server.listen(3000);
+
+  return chat;
+}
+```
+
+## Configuration
+
+### Required Options
+
+```typescript
+{
+  // Models that can participate in conversations (e.g., ['User', 'Bot'])
+  participantModels: string[];
+
+  // Valid roles for conversation participants (e.g., ['member', 'admin'])
+  memberRoles: string[];
+
+  // MongoDB connection URI
+  mongoUri: string;
+}
+```
+
+### Redis Configuration (Optional)
+
+```typescript
+{
+  redis?: {
+    // Option 1: Use URL
+    url?: string;
+
+    // Option 2: Use individual settings
+    host?: string;
+    port?: number;
+    password?: string;
+    db?: number;
+    socketConnectTimeout?: number;
+    keepAlive?: number;
+  }
+}
+```
+
+### Socket.IO Configuration (Optional)
+
+```typescript
+{
+  socket?: {
+    path?: string;
+    cors?: {
+      origin?: string | string[];
+      methods?: string[];
+    }
+  }
+}
+```
+
+## Services
+
+### Conversations
+
+```typescript
+// Create or find conversation
+const conversation = await services.conversations.createOrFindConversation({
+  organizationId: string;
+  a: { model: string; id: string };
+  b: { model: string; id: string };
+});
+```
+
+### Messages
+
+```typescript
+// Send message
+const message = await services.messages.sendMessage({
+  organizationId: string;
+  conversationId: string;
+  senderModel: string;
+  senderId: string;
+  text: string;
+  kind?: 'text' | 'system';
+  parentMessageId?: string; // For threading
+});
+
+// List messages
+const { items, nextCursor } = await services.messages.listMessages({
+  organizationId: string;
+  conversationId: string;
+  limit?: number;
+  cursor?: string;
+});
+```
+
+## Client Integration
+
+```typescript
+import { io } from 'socket.io-client';
+
+const socket = io('http://localhost:3000', {
+  path: '/socket.io',
+  auth: {
+    userId: 'user-123',
+    userModel: 'User'
+  }
+});
+
+// Join a conversation
+socket.emit('join-conversation', conversationId);
+
+// Listen for events
+socket.on('chat-event', (event) => {
+  switch (event.type) {
+    case 'message:created':
+      console.log('New message:', event.message);
+      break;
+    case 'typing':
+      console.log('Typing status:', event.state);
+      break;
+    // ... handle other events
+  }
+});
+
+// Send typing indicator
+socket.emit('typing', { 
+  conversationId: 'conv-123',
+  isTyping: true 
+});
+```
+
+## Example Project
+
+Check out our [demo project](./chat-demo) for a complete example using Next.js.
+
+## License
+
+MIT