@peopl-health/nexus 1.2.0 → 1.3.0

package/MIGRATION_GUIDE.md

@@ -1,388 +1,80 @@
-# 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
+# Migration Guide
+
+This guide summarizes changes introduced in the current Nexus library refresh to help you migrate quickly with minimal breakage.
+
+## TL;DR
+- Twilio remains first‑class; Baileys is supported for messaging but not for templates/flows (returns clear errors).
+- Message sends accept both `to` (preferred) and legacy `code` (normalized internally).
+- Templates and flows are supported through Twilio Content API; provider is auto‑injected into template controllers on `Nexus.initialize()` when Twilio is active.
+- New event bus + middleware model; existing handlers continue to work.
+- Storage adapter registry; use built‑in `mongo`/`noop` or plug your own adapter or instance.
+- Interactive/flows now have a provider‑agnostic API with Twilio mapping and event‑driven routing.
+- Assistant registry with optional override for `getAssistantById`.
+
+## Messaging API
+- BREAKING (soft): Prefer `to` over `code` in `sendMessage`. Legacy `code` is still accepted and normalized internally.
+
+Before:
+```js
+await nexus.sendMessage({ code: 'whatsapp:+521555...', message: 'Hi' });
+```
+After (preferred):
+```js
+await nexus.sendMessage({ to: '+521555...', message: 'Hi' });
+```
+
+## Templates & Flows (Twilio)
+- Twilio provider now implements content operations: `listTemplates`, `getTemplate`, `createTemplate`, `deleteTemplate`, `submitForApproval`, `checkApprovalStatus`.
+- On `Nexus.initialize()` with Twilio, the provider is auto‑injected into template controllers — default routes under `/api/template` work immediately.
+- Baileys: content/template operations are not supported; a clear error is thrown if called.
+
+## Interactive & Flows (Provider‑agnostic)
+- New helper APIs:
+  - `registerFlow(id, spec)`, `sendInteractive(nexus, { to, id | spec, variables })`.
+  - Twilio: spec is converted to Content API payload and sent; if `spec.contentSid` is provided, it is used directly.
+  - Baileys: currently unsupported.
+- Event‑driven routing:
+  - `registerInteractiveHandler(match, handler)` and `attachInteractiveRouter(nexus)`; handlers are called when interactive messages are received.
+
+## Middleware & Events
+- New event bus on `NexusMessaging`: subscribe to `*:received` and `*:handled` (message, media, interactive, command, keyword, flow).
+- New middleware: `nexus.getMessaging().use(type?, async (msg, nexus, next) => { ... })`.
+- Existing `setHandlers` and `onMessage`/`onInteractive`/etc. continue to work.
+
+## Storage
+- Storage is now pluggable via a registry:
+  - Built‑ins: `mongo` (default), `noop`.
+  - Register your adapter: `registerStorage('src', MyStorageClass)` then `storage: 'src'`.
+  - Or pass an instance: `storage: new MyStorageClass()`.
+- If the adapter has `connect()`, Nexus calls it automatically.
+- Controllers that rely on your Mongo models can continue to do so — no change required.
+
+## Assistants
+- Register assistant classes at init:
+```js
 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
-    }
+  llm: 'openai', llmConfig: { apiKey: process.env.OPENAI_API_KEY },
+  assistants: {
+    registry: { SUPPORT: SupportAssistantClass, SALES: SalesAssistantClass },
+    getAssistantById: (id, thread) => null // optional override
   }
 });
 ```
+- An internal override for `getAssistantById` is supported; if provided, it is tried first, then fallback to registry.
 
-## 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
+## Utilities & Fixes
+- Utils index corrected to export existing files: `{ DefaultLLMProvider, MessageParser, logger }`.
+- Default OpenAI import fixed for CommonJS: `const OpenAI = require('openai');`.
+- Message model helpers unified; `LegacyMessage` references replaced with `Message` and a new exported `insertMessage`.
+- Types `declare module` now matches package name: `@peopl-health/nexus`.
 
-## Support
+## Routes
+- Built‑in route bundles remain available and importable via `setupDefaultRoutes(app)` or per‑group via `routes` + `createRouter()`.
 
-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
+## Testing
+- If your environment restricts forking, run Jest in‑band: `jest --runInBand`.
 
-The migration should significantly reduce your codebase size while maintaining all functionality and adding new capabilities for future development.
+## Notes
+- Twilio approvals data shape varies by account/region. The provider looks up `content.links` and falls back to the documented REST path; data is normalized where possible.
+- Baileys: templates/flows remain unsupported; messaging and media send/receive are supported.