@peopl-health/nexus 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to the @peopl/nexus library will be documented in this file.
+
+## [1.0.0] - 2024-01-19
+
+### Added
+- **Core Library Architecture**: Complete transformation from monolithic application to reusable library
+- **Provider Abstraction**: Support for both Twilio and Baileys WhatsApp providers with unified interface
+- **Configurable Message Handling**: Event-driven system for custom commands, keywords, flows, and interactions
+- **MongoDB Storage Interface**: Automatic message and interaction storage with customizable schemas
+- **AI Assistant Integration**: Built-in OpenAI assistant support with configurable architectures
+- **Message Parser**: Intelligent parsing of different message types (text, media, interactive, commands)
+- **Scheduled Messages**: Support for delayed message sending with timezone handling
+- **Event System**: Extensible handler system for custom business logic
+
+### Components
+- `Nexus`: Main orchestration class
+- `NexusMessaging`: Core messaging functionality
+- `TwilioProvider`: Twilio WhatsApp adapter
+- `BaileysProvider`: Baileys WhatsApp adapter  
+- `MongoStorage`: MongoDB storage interface
+- `AssistantManager`: AI assistant management
+- `MessageParser`: Message type detection and parsing
+
+### Utilities
+- `logger`: Configurable Winston logger
+- `whatsappHelper`: WhatsApp-specific utilities
+- `twilioHelper`: Twilio-specific utilities
+- `mongoAuthConfig`: MongoDB authentication for Baileys
+
+### Models
+- `Message`: MongoDB message schema
+- `Thread`: MongoDB thread schema for assistant conversations
+
+### Examples
+- `basic-usage.js`: Simple echo bot implementation
+- `consumer-server.js`: Complete Express.js server with AI assistants
+- `.env.example`: Environment configuration template
+
+### Documentation
+- Complete README with API reference and usage examples
+- Migration guide from original codebase
+- TypeScript definitions for better development experience
+
+### Breaking Changes
+- Complete API redesign from original monolithic structure
+- Environment variables now passed as configuration objects
+- Healthcare-specific logic removed and made configurable
+- Database models abstracted behind storage interface
+
+### Migration
+- See `MIGRATION_GUIDE.md` for detailed migration instructions
+- Original functionality maintained but with cleaner, more flexible API
+- Significant code reduction (~2000+ lines to ~200 lines for equivalent functionality)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 PEOPL Health Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATION_GUIDE.md

@@ -0,0 +1,388 @@
+# Migration Guide: From Original Codebase to @peopl/nexus
+
+This guide helps you migrate from the original WhatsApp messaging platform to the new `@peopl/nexus` library.
+
+## Overview
+
+The original codebase has been transformed into a reusable library that provides:
+- **Provider abstraction** (Twilio/Baileys)
+- **Configurable message handling**
+- **MongoDB storage interface**
+- **AI assistant integration**
+- **Event-driven architecture**
+
+## Migration Steps
+
+### 1. Install the Library
+
+```bash
+npm install @peopl/nexus
+```
+
+Install peer dependencies based on your needs:
+```bash
+# For Twilio
+npm install twilio
+
+# For Baileys  
+npm install baileys
+
+# For AI assistants
+npm install openai
+```
+
+### 2. Replace Original Server Code
+
+**Before (Original):**
+```javascript
+// src/index.js
+const express = require('express');
+const { initWhatsApp } = require('./adapters/baileys');
+const { initTwilio } = require('./adapters/twilio');
+// ... lots of setup code
+```
+
+**After (With @peopl/nexus):**
+```javascript
+const express = require('express');
+const { Nexus } = require('@peopl/nexus');
+
+const nexus = new Nexus();
+await nexus.initialize({
+  provider: 'twilio', // or 'baileys'
+  providerConfig: { /* your config */ }
+});
+```
+
+### 3. Migrate Message Handlers
+
+**Before:**
+```javascript
+// Scattered across multiple files
+async function processIncomingMessage(twilioClient, message) {
+  // Complex processing logic
+}
+```
+
+**After:**
+```javascript
+nexus.setHandlers({
+  onMessage: async (messageData, nexus) => {
+    // Your message logic here
+  },
+  onCommand: async (messageData, nexus) => {
+    // Your command logic here
+  }
+});
+```
+
+### 4. Migrate Assistant Integration
+
+**Before:**
+```javascript
+// src/services/assistantService.js
+const { replyAssistant } = require('./assistantService');
+// Complex assistant management
+```
+
+**After:**
+```javascript
+await nexus.initialize({
+  assistant: {
+    llmClient: openai,
+    assistants: {
+      'SUPPORT_ASST': 'asst_abc123'
+    }
+  }
+});
+
+// Use assistants
+const response = await nexus.sendToAssistant(userId, message);
+```
+
+### 5. Migrate Database Models
+
+**Before:**
+```javascript
+// src/models/messageModel.js
+const Message = mongoose.model('Message', messageSchema);
+```
+
+**After:**
+```javascript
+// Models are handled automatically by the library
+// Access via nexus.getStorage() if needed
+const storage = nexus.getStorage();
+const messages = await storage.getMessages(userId);
+```
+
+## Configuration Mapping
+
+### Environment Variables
+
+**Before:**
+```env
+TWILIO_ACCOUNT_SID=your_sid
+TWILIO_AUTH_TOKEN=your_token
+MONGO_URI=mongodb://localhost:27017/db
+```
+
+**After:**
+```javascript
+await nexus.initialize({
+  provider: 'twilio',
+  providerConfig: {
+    accountSid: process.env.TWILIO_ACCOUNT_SID,
+    authToken: process.env.TWILIO_AUTH_TOKEN,
+    whatsappNumber: process.env.TWILIO_WHATSAPP_NUMBER
+  },
+  storage: 'mongo',
+  storageConfig: {
+    mongoUri: process.env.MONGO_URI,
+    dbName: 'your_db_name'
+  }
+});
+```
+
+### Assistant Configuration
+
+**Before:**
+```javascript
+// src/config/assistantConfig.js
+module.exports = {
+  SALES_ASST: "asst_HjYiVBQ8ye1yl1Iu9mcqF83b",
+  DOCTOR_SCHEDULE_ASST: "asst_5cw2tRHI7ze6FHgtlId6ideH"
+};
+```
+
+**After:**
+```javascript
+await nexus.initialize({
+  assistant: {
+    llmClient: openai,
+    assistants: {
+      'SALES_ASST': process.env.SALES_ASSISTANT_ID,
+      'DOCTOR_SCHEDULE_ASST': process.env.DOCTOR_SCHEDULE_ASSISTANT_ID
+    }
+  }
+});
+```
+
+## Feature Migration
+
+### 1. Message Sending
+
+**Before:**
+```javascript
+const { sendMessage } = require('./messaging/messageService');
+await sendMessage(twilioClient, messageData);
+```
+
+**After:**
+```javascript
+await nexus.sendMessage({
+  to: '+1234567890',
+  message: 'Hello World!',
+  fileUrl: 'https://example.com/file.pdf',
+  fileType: 'document'
+});
+```
+
+### 2. Template Messages
+
+**Before:**
+```javascript
+await sendMessage(twilioClient, {
+  code: phoneNumber,
+  contentSid: templateId,
+  variables: { '1': 'John', '2': 'Doe' }
+});
+```
+
+**After:**
+```javascript
+await nexus.sendMessage({
+  to: phoneNumber,
+  contentSid: templateId,
+  variables: { '1': 'John', '2': 'Doe' }
+});
+```
+
+### 3. Interactive Messages
+
+**Before:**
+```javascript
+// src/adapters/interactive/processButton.js
+async function processButtonPayload(twilioClient, message) {
+  // Complex button handling
+}
+```
+
+**After:**
+```javascript
+nexus.setHandlers({
+  onInteractive: async (messageData, nexus) => {
+    const { type, payload } = messageData.interactive;
+    
+    if (type === 'button') {
+      // Handle button click
+      await nexus.sendMessage({
+        to: messageData.from,
+        message: `You clicked: ${payload}`
+      });
+    }
+  }
+});
+```
+
+### 4. Command Processing
+
+**Before:**
+```javascript
+// Hardcoded command processing in multiple files
+if (message.Body.startsWith('/help')) {
+  // Handle help command
+}
+```
+
+**After:**
+```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'
+        });
+        break;
+    }
+  }
+});
+```
+
+### 5. Keyword Detection
+
+**Before:**
+```javascript
+// Hardcoded keyword detection
+const keywords = ['hola', 'dr.', 'bienvenida'];
+if (keywords.some(k => message.Body.includes(k))) {
+  // Handle keywords
+}
+```
+
+**After:**
+```javascript
+await nexus.initialize({
+  parserConfig: {
+    keywords: ['hola', 'dr.', 'bienvenida', 'help', 'support']
+  }
+});
+
+nexus.setHandlers({
+  onKeyword: async (messageData, nexus) => {
+    const keyword = messageData.keyword;
+    // Handle keyword detection
+  }
+});
+```
+
+## Webhook Migration
+
+### Before (Express Routes)
+```javascript
+// src/routes/index.js
+app.post('/twilio/webhook', async (req, res) => {
+  await processIncomingMessage(twilioClient, req.body);
+  res.sendStatus(200);
+});
+```
+
+### After (Simplified)
+```javascript
+app.post('/webhook/twilio', async (req, res) => {
+  await nexus.processMessage(req.body);
+  res.sendStatus(200);
+});
+```
+
+## Benefits After Migration
+
+### ✅ Reduced Code Complexity
+- **Before**: ~2000+ lines across multiple files
+- **After**: ~200 lines for equivalent functionality
+
+### ✅ Better Maintainability
+- Centralized configuration
+- Clear separation of concerns
+- Standardized error handling
+
+### ✅ Enhanced Flexibility
+- Easy provider switching (Twilio ↔ Baileys)
+- Configurable message parsing
+- Pluggable storage backends
+
+### ✅ Improved Testing
+- Mockable components
+- Isolated business logic
+- Clear interfaces
+
+## Common Migration Issues
+
+### 1. **Missing Dependencies**
+```bash
+# Install missing peer dependencies
+npm install twilio baileys openai
+```
+
+### 2. **Configuration Errors**
+```javascript
+// Ensure all required config is provided
+await nexus.initialize({
+  provider: 'twilio',
+  providerConfig: {
+    accountSid: 'required',
+    authToken: 'required', 
+    whatsappNumber: 'required'
+  }
+});
+```
+
+### 3. **Handler Registration**
+```javascript
+// Set handlers AFTER initialization
+await nexus.initialize(config);
+nexus.setHandlers(handlers); // ✅ Correct order
+```
+
+### 4. **Database Connection**
+```javascript
+// Storage is handled automatically
+await nexus.initialize({
+  storage: 'mongo',
+  storageConfig: {
+    mongoUri: 'mongodb://localhost:27017/db',
+    dbName: 'your_db'
+  }
+});
+// No need to call connectMongoose() manually
+```
+
+## Next Steps
+
+1. **Start Small**: Migrate one feature at a time
+2. **Test Thoroughly**: Verify each migrated component works
+3. **Remove Old Code**: Clean up original files after successful migration
+4. **Optimize**: Use library features to simplify your code further
+
+## Support
+
+For migration assistance:
+- Check the [README.md](./README.md) for detailed API documentation
+- Review [examples/](./examples/) for complete implementations
+- Refer to the original codebase for complex business logic patterns
+
+The migration should significantly reduce your codebase size while maintaining all functionality and adding new capabilities for future development.