@peopl-health/nexus 1.0.2

package/README.md

@@ -0,0 +1,532 @@
+# nexus
+
+Core messaging and assistant library for WhatsApp communication platforms.
+
+## Features
+
+- **Multi-Provider Support**: Seamlessly switch between Twilio and Baileys
+- **Configurable Architecture**: Adapter pattern for messaging providers  
+- **AI Assistant Integration**: Built-in support for OpenAI and custom LLM providers
+- **MongoDB Storage**: Persistent message and thread storage
+- **Template Messaging**: Support for WhatsApp Business templates
+- **Scheduled Messages**: Queue and send messages at specific times
+- **Flow Management**: Create conversational flows and approval processes
+
+## Installation
+
+```bash
+npm install @peopl-health/nexus
+```
+
+### Peer Dependencies
+
+Install the providers you need:
+
+```bash
+# For Twilio WhatsApp
+npm install twilio
+
+# For Baileys (direct WhatsApp connection)
+npm install baileys
+
+# For AI features
+npm install openai
+```
+
+## Quick Start
+
+### Basic Messaging (Twilio)
+
+```javascript
+const { Nexus } = require('nexus-messaging');
+
+const nexus = new Nexus();
+
+await nexus.initialize({
+  provider: 'twilio',
+  providerConfig: {
+    accountSid: process.env.TWILIO_SID,
+    authToken: process.env.TWILIO_TOKEN,
+    phoneNumber: 'whatsapp:+1234567890'
+  }
+});
+
+// Send a message
+await nexus.sendMessage({
+  to: '+1234567890',
+  message: 'Hello from Nexus!'
+});
+```
+
+### With AI Assistant
+
+```javascript
+const { Nexus, BaseAssistant } = require('@peopl/nexus');
+
+const nexus = new Nexus();
+
+await nexus.initialize({
+  provider: 'twilio',
+  providerConfig: { /* twilio config */ },
+  llm: 'openai',
+  llmConfig: {
+    apiKey: process.env.OPENAI_API_KEY
+  }
+});
+
+// Set up message handler with AI
+nexus.setHandlers({
+  message: async (messageData) => {
+    const assistant = new BaseAssistant();
+    return await assistant.processMessage(messageData);
+  }
+});
+
+// Process incoming webhook
+app.post('/webhook', async (req, res) => {
+  await nexus.processMessage(req.body);
+  res.sendStatus(200);
+});
+```
+
+## Integration Patterns
+
+### Option 1: NPM Package (Recommended)
+
+```bash
+npm install nexus-messaging twilio openai
+```
+
+### Option 2: Git Dependency
+
+```json
+{
+  "dependencies": {
+    "@peopl/nexus": "git+https://github.com/peopl-health/nexus.git"
+  }
+}
+```
+
+### Option 3: Local Development
+
+```bash
+# Clone and link locally
+git clone https://github.com/peopl-health/nexus.git
+cd nexus
+npm link
+
+# In your project
+npm link @peopl/nexus
+```
+
+## Configuration Options
+
+### Providers
+
+#### Twilio (Production Ready)
+```javascript
+{
+  provider: 'twilio',
+  providerConfig: {
+    accountSid: 'your-twilio-sid',
+    authToken: 'your-twilio-token', 
+    phoneNumber: 'whatsapp:+1234567890'
+  }
+}
+```
+
+#### Baileys (Direct WhatsApp)
+```javascript
+{
+  provider: 'baileys',
+  providerConfig: {
+    printQRInTerminal: true,
+    // Additional Baileys options
+  }
+}
+```
+
+### Storage Options
+
+```javascript
+{
+  storage: 'mongo',  // Default
+  storageConfig: {
+    uri: process.env.MONGODB_URI || 'mongodb://localhost:27017/nexus'
+  }
+}
+
+// Or disable storage
+{ storage: false }
+```
+
+### LLM Integration
+
+```javascript
+{
+  llm: 'openai',
+  llmConfig: {
+    apiKey: process.env.OPENAI_API_KEY,
+    model: 'gpt-4',
+    temperature: 0.7
+  }
+}
+```
+
+## Advanced Usage
+
+### Custom Assistant
+
+```javascript
+const { BaseAssistant } = require('@peopl/nexus/utils');
+
+class CustomerServiceAssistant extends BaseAssistant {
+  async processMessage(messageData) {
+    // Custom business logic
+    if (messageData.message.includes('order')) {
+      return await this.handleOrderInquiry(messageData);
+    }
+    
+    return await super.processMessage(messageData);
+  }
+  
+  async handleOrderInquiry(messageData) {
+    // Custom order handling logic
+  }
+}
+```
+
+### Template Messages
+
+```javascript
+await nexus.sendMessage({
+  to: '+1234567890',
+  contentSid: 'HX1234567890abcdef',  // Twilio template SID
+  variables: {
+    '1': 'John',
+    '2': 'Tomorrow at 3 PM'
+  }
+});
+```
+
+### Scheduled Messages
+
+```javascript
+await nexus.sendScheduledMessage({
+  to: '+1234567890',
+  message: 'Reminder: Your appointment is tomorrow',
+  sendAt: new Date(Date.now() + 24 * 60 * 60 * 1000) // 24 hours from now
+});
+```
+
+## API Reference
+
+### Nexus Class
+
+#### `initialize(options)` → `Promise<void>`
+Initialize with providers and configuration.
+
+**Parameters:**
+- `provider` (string): 'twilio' or 'baileys'
+- `providerConfig` (object): Provider-specific configuration
+- `storage` (string|false): 'mongo' or false to disable
+- `storageConfig` (object): Storage configuration
+- `llm` (string): 'openai' for AI features
+- `llmConfig` (object): LLM configuration
+
+#### `sendMessage(messageData)` → `Promise<Object>`
+Send a message through the configured provider.
+
+**Parameters:**
+- `to` (string): Recipient phone number
+- `message` (string): Message text
+- `fileUrl` (string, optional): File URL for media
+- `contentSid` (string, optional): Template content SID
+- `variables` (object, optional): Template variables
+
+#### `processMessage(rawMessage)` → `Promise<void>`
+Process incoming webhook/event message.
+
+#### `setHandlers(handlers)` → `void`
+Set message and status handlers.
+
+#### `isConnected()` → `boolean`
+Check provider connection status.
+
+#### `disconnect()` → `Promise<void>`
+Clean shutdown of all services.
+
+## Examples
+
+Complete examples in `/examples`:
+
+- **`basic-usage.js`** - Pure messaging without AI
+- **`consumer-server.js`** - Full Express server with AI assistant
+- **`assistants/ExampleAssistant.js`** - Custom assistant implementation
+
+## Publishing to NPM
+
+```bash
+# Login to npm
+npm login
+
+# Publish (first time)
+npm publish
+
+# Update version and publish
+npm version patch  # or minor/major
+npm publish
+```
+
+## Environment Variables
+
+```bash
+# Twilio
+TWILIO_SID=your_account_sid
+TWILIO_TOKEN=your_auth_token
+TWILIO_PHONE=whatsapp:+1234567890
+
+# MongoDB
+MONGODB_URI=mongodb://localhost:27017/nexus
+
+# OpenAI
+OPENAI_API_KEY=your_openai_key
+```
+
+## Customization
+
+Define custom handlers for different message types:
+
+```javascript
+nexus.setHandlers({
+  onMessage: async (messageData, nexus) => {
+    // Handle regular text messages
+  },
+  
+  onInteractive: async (messageData, nexus) => {
+    // Handle button clicks, list selections, flow responses
+    const { type, payload } = messageData.interactive;
+    
+    if (type === 'button') {
+      console.log('Button clicked:', payload);
+    }
+  },
+  
+  onMedia: async (messageData, nexus) => {
+    // Handle image, document, audio messages
+    const { url, contentType } = messageData.media;
+  },
+  
+  onCommand: async (messageData, nexus) => {
+    // Handle commands like /help, /start
+    const { command, args } = messageData.command;
+  },
+  
+  onKeyword: async (messageData, nexus) => {
+    // Handle keyword triggers
+    console.log('Keyword matched:', messageData.keyword);
+  },
+  
+  onFlow: async (messageData, nexus) => {
+    // Handle flow triggers
+    console.log('Flow triggered:', messageData.flow);
+  }
+});
+```
+
+### Message Parser Configuration
+
+Customize how messages are parsed:
+
+```javascript
+await nexus.initialize({
+  // ... other config
+  parserConfig: {
+    commandPrefixes: ['/', '!', '#'],
+    keywords: [
+      'help',
+      'support',
+      { pattern: 'urgent.*issue', flags: 'i' }
+    ],
+    flowTriggers: [
+      'start onboarding',
+      'begin survey'
+    ]
+  }
+});
+```
+
+### AI Assistant Integration
+
+```javascript
+const { OpenAI } = require('openai');
+
+const openai = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY
+});
+
+await nexus.initialize({
+  // ... other config
+  assistant: {
+    llmClient: openai,
+    assistants: {
+      'SUPPORT_ASSISTANT': 'asst_abc123',
+      'SALES_ASSISTANT': 'asst_def456'
+    },
+    handlers: {
+      onRequiresAction: async (result, threadData) => {
+        // Handle function calls
+        const toolCalls = result.run.required_action.submit_tool_outputs.tool_calls;
+        const toolOutputs = [];
+        
+        for (const toolCall of toolCalls) {
+          if (toolCall.function.name === 'get_weather') {
+            const output = await getWeather(JSON.parse(toolCall.function.arguments));
+            toolOutputs.push({
+              tool_call_id: toolCall.id,
+              output: JSON.stringify(output)
+            });
+          }
+        }
+        
+        return await nexus.getAssistantManager().submitToolOutputs(
+          threadData.threadId,
+          result.run.id,
+          toolOutputs
+        );
+      }
+    }
+  }
+});
+
+// Create assistant thread
+await nexus.createAssistantThread('user123', 'SUPPORT_ASSISTANT');
+
+// Send message to assistant
+const response = await nexus.sendToAssistant('user123', 'I need help with my account');
+```
+
+## API Reference
+
+### Nexus Class
+
+#### `initialize(options)`
+Initialize Nexus with providers and configuration.
+
+#### `sendMessage(messageData)`
+Send a message through the active provider.
+
+```javascript
+await nexus.sendMessage({
+  to: '+1234567890',
+  message: 'Hello World!',
+  fileUrl: 'https://example.com/image.jpg', // optional
+  fileType: 'image', // optional
+  contentSid: 'template_sid', // optional for templates
+  variables: { '1': 'John', '2': 'Doe' } // optional for templates
+});
+```
+
+#### `sendScheduledMessage(scheduledMessage)`
+Schedule a message for future delivery.
+
+```javascript
+await nexus.sendScheduledMessage({
+  to: '+1234567890',
+  message: 'Reminder: Your appointment is tomorrow',
+  sendTime: '2024-01-15T10:00:00Z',
+  timeZone: 'America/Mexico_City'
+});
+```
+
+#### `processMessage(rawMessage)`
+Process incoming message from webhook.
+
+### Individual Components
+
+You can also use individual components for more control:
+
+```javascript
+const { TwilioProvider, MongoStorage, MessageParser } = require('@peopl/nexus');
+
+// Use components individually
+const provider = new TwilioProvider(config);
+await provider.initialize();
+
+const storage = new MongoStorage(config);
+await storage.connect();
+
+const parser = new MessageParser(config);
+const parsedMessage = parser.parseMessage(rawMessage);
+```
+
+## Examples
+
+### Basic Echo Bot
+```javascript
+const { Nexus } = require('nexus-messaging');
+
+const nexus = new Nexus();
+
+await nexus.initialize({
+  provider: 'twilio',
+  providerConfig: { /* twilio config */ }
+});
+
+nexus.setHandlers({
+  onMessage: async (messageData, nexus) => {
+    await nexus.sendMessage({
+      to: messageData.from,
+      message: `Echo: ${messageData.message}`
+    });
+  }
+});
+```
+
+### Command Handler
+```javascript
+nexus.setHandlers({
+  onCommand: async (messageData, nexus) => {
+    const { command, args } = messageData.command;
+    
+    switch (command) {
+      case 'help':
+        await nexus.sendMessage({
+          to: messageData.from,
+          message: 'Available commands: /help, /status, /info'
+        });
+        break;
+        
+      case 'status':
+        await nexus.sendMessage({
+          to: messageData.from,
+          message: `System status: ${nexus.isConnected() ? 'Online' : 'Offline'}`
+        });
+        break;
+    }
+  }
+});
+```
+
+### Interactive Messages
+```javascript
+nexus.setHandlers({
+  onInteractive: async (messageData, nexus) => {
+    const { type, payload } = messageData.interactive;
+    
+    if (type === 'button' && payload === 'get_support') {
+      await nexus.sendMessage({
+        to: messageData.from,
+        message: 'Connecting you to support...'
+      });
+      
+      // Create assistant thread for support
+      await nexus.createAssistantThread(messageData.from, 'SUPPORT_ASSISTANT');
+    }
+  }
+});
+```
+
+## License
+
+MIT

package/examples/.env.example

@@ -0,0 +1,24 @@
+# Database Configuration
+MONGO_URI=mongodb://localhost:27017/nexus
+DB_NAME=nexus_consumer
+USER_DB_MONGO=nexus_user
+
+# Messaging Provider (twilio or baileys)
+MESSAGING_PROVIDER=twilio
+
+# Twilio Configuration
+TWILIO_ACCOUNT_SID=your_twilio_account_sid
+TWILIO_AUTH_TOKEN=your_twilio_auth_token
+TWILIO_WHATSAPP_NUMBER=+14155238886
+
+# OpenAI Configuration
+OPENAI_API_KEY=your_openai_api_key
+
+# Assistant IDs
+SUPPORT_ASSISTANT_ID=asst_your_support_assistant_id
+SALES_ASSISTANT_ID=asst_your_sales_assistant_id
+GENERAL_ASSISTANT_ID=asst_your_general_assistant_id
+
+# Server Configuration
+PORT=3000
+NODE_ENV=development