@peopl-health/nexus 1.1.8 → 1.3.0

package/README.md

@@ -1,611 +1,132 @@
-# nexus
+# @peopl-health/nexus
 
-Core messaging and assistant library for WhatsApp communication platforms.
+A concise, configurable messaging and assistant toolkit for WhatsApp. It supports Twilio (production‑ready) and Baileys (limited), optional Mongo storage, OpenAI assistants, templates/flows via Twilio Content API, and an event/middleware model so apps can customize behavior.
 
-## 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
+## Install
 
 ```bash
 npm install @peopl-health/nexus
+# Providers / AI
+npm install twilio baileys openai
 ```
 
-### Peer Dependencies
-
-Install the providers you need:
-
-```bash
-# For Twilio WhatsApp
-npm install twilio
-
-# For Baileys (direct WhatsApp connection)
-npm install baileys
+## Quick Start (Twilio)
 
-# For AI features
-npm install openai
-```
-
-## Quick Start
-
-### Basic Messaging (Twilio)
-
-```javascript
-const { Nexus } = require('nexus-messaging');
+```js
+const express = require('express');
+const { Nexus, setupDefaultRoutes } = require('@peopl-health/nexus');
 
 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
-  }
+    accountSid: process.env.TWILIO_ACCOUNT_SID,
+    authToken: process.env.TWILIO_AUTH_TOKEN,
+    phoneNumber: process.env.TWILIO_PHONE_NUMBER
+  },
+  storage: 'mongo',                 // or 'noop', or your custom adapter/instance
+  storageConfig: { mongoUri: process.env.MONGODB_URI }
 });
 
-// Set up message handler with AI
-nexus.setHandlers({
-  message: async (messageData) => {
-    const assistant = new BaseAssistant();
-    return await assistant.processMessage(messageData);
-  }
-});
+// Built‑in routes (assistant, conversation, media, message, template)
+const app = express();
+app.use(express.json());
+setupDefaultRoutes(app);
 
-// Process incoming webhook
+// Incoming webhooks
 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
+## Templates & Approvals (Twilio)
 
-### Providers
+Nexus auto‑injects the active Twilio provider into the template controllers during `initialize`. Default routes under `/api/template` work immediately:
+- `GET /api/template` list templates
+- `GET /api/template/:id` get one
+- `POST /api/template/text` create text template
+- `POST /api/template/approval` submit for approval
+- `GET /api/template/status/:sid` check status
+- `DELETE /api/template/:id` delete
 
-#### 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'
-  }
+Programmatic use:
+```js
+const provider = nexus.getMessaging().getProvider();
+const content = await provider.createTemplate({
+  friendly_name: 'hello_' + Date.now(),
+  language: 'es',
+  variables: { '1': 'Nombre' },
+  types: { 'twilio/text': { body: 'Hola {{1}}' } }
 });
+await provider.submitForApproval(content.sid, 'hello', 'UTILITY');
+const status = await provider.checkApprovalStatus(content.sid);
 ```
 
-### 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
-});
-```
-
-## Routes for Consumer Servers
-
-The library exports pre-built route definitions that consumer servers can use with minimal code:
-
-### Option 1: Setup All Default Routes (Minimal Code)
+## Interactive & Flows
 
-```javascript
-const express = require('express');
-const { setupDefaultRoutes } = require('@peopl-health/nexus');
-
-const app = express();
-
-// Setup all default routes with built-in controllers (one line!)
-setupDefaultRoutes(app);
-
-// Add your custom routes
-app.get('/api/custom', myCustomController);
-app.post('/api/special', mySpecialController);
-```
-
-### Option 2: Individual Route Control
-
-```javascript
-const express = require('express');
-const { routes, createRouter } = require('@peopl-health/nexus');
+Provider‑agnostic APIs with Twilio mapping (Baileys: not supported):
+```js
+const { registerFlow, sendInteractive, registerInteractiveHandler, attachInteractiveRouter } = require('@peopl-health/nexus');
 
-const app = express();
-
-// Setup only specific route groups
-app.use('/api/assistant', createRouter(routes.assistantRoutes, myControllers));
-app.use('/api/message', createRouter(routes.messageRoutes, myControllers));
-app.use('/api/template', createRouter(routes.templateRoutes, myControllers));
-```
-
-### Available Default Route Groups
-
-The `setupDefaultRoutes()` function sets up these 5 route groups:
-
-#### **Assistant Routes** (`/api/assistant`)
-- `POST /active` - Set active assistant
-- `POST /add-instruction` - Add instruction to assistant
-- `POST /add-msg` - Add message to assistant
-- `POST /create` - Create new assistant
-- `POST /get-info` - Get assistant information
-- `GET /list` - List all assistants
-- `POST /switch` - Switch between assistants
-- `POST /stop` - Stop assistant
-
-#### **Conversation Routes** (`/api/conversation`)
-- `GET /` - Get conversations
-- `GET /search` - Search conversations
-- `GET /by-name` - Get conversations by name
-- `GET /:phoneNumber` - Get conversation messages
-- `GET /:phoneNumber/new` - Get new messages
-- `POST /reply` - Send conversation reply
-- `POST /send-template` - Send template to new number
-- `POST /:phoneNumber/read` - Mark messages as read
-
-#### **Media Routes** (`/api/media`)
-- `GET /:key(*)` - Get media file
-- `POST /upload` - Upload media file
-
-#### **Message Routes** (`/api/message`)
-- `POST /send` - Send single message
-- `POST /send-bulk` - Send bulk messages
-- `POST /send-bulk-airtable` - Send bulk messages from Airtable
-
-#### **Template Routes** (`/api/template`)
-- `POST /text` - Create text template
-- `GET /` - List templates
-- `GET /predefined` - Get predefined templates
-- `GET /:id` - Get specific template
-- `GET /complete/:sid` - Get complete template
-- `POST /flow` - Create flow template
-- `DELETE /flow/:sid` - Delete flow template
-- `POST /approval` - Submit template for approval
-- `GET /status/:sid` - Check approval status
-- `DELETE /:id` - Delete template
-
-## 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);
-  }
+registerFlow('greeting_qr', {
+  type: 'quick-reply', language: 'es', body: 'Hola {{1}}', variables: { '1': 'Nombre' },
+  buttons: [{ text: 'Sí' }, { text: 'No' }]
 });
-```
+await sendInteractive(nexus, { to: '+521555...', id: 'greeting_qr' });
 
-### 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'
-    ]
-  }
+registerInteractiveHandler({ type: 'button', id: /sí|si/i }, async (msg, messaging) => {
+  await messaging.sendMessage({ to: msg.from, message: '¡Confirmado!' });
 });
+attachInteractiveRouter(nexus);
 ```
 
-### 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
-        );
-      }
-    }
-  }
-});
+## Storage (Adapters)
 
-// 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');
+- Built‑in: `mongo` (default), `noop`.
+- Register your adapter or pass an instance directly.
+```js
+const { registerStorage } = require('@peopl-health/nexus/lib/storage/registry');
+registerStorage('src', MyStorageClass);
+await nexus.initialize({ storage: 'src', storageConfig: { /* ... */ } });
+// OR
+await nexus.initialize({ storage: new MyStorageClass(/* ... */) });
 ```
 
-## API Reference
-
-### Nexus Class
-
-#### `initialize(options)`
-Initialize Nexus with providers and configuration.
+## Middleware & Events
 
-#### `sendMessage(messageData)`
-Send a message through the active provider.
+Add middleware per type or global; subscribe to events.
+```js
+const bus = nexus.getMessaging().getEventBus();
+bus.on('message:received', (m) => console.log('rx', m.id));
 
-```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
+nexus.getMessaging().use('message', async (msg, nx, next) => {
+  // sanitize/annotate
+  return next();
 });
 ```
 
-#### `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();
+## Assistants (Optional)
 
+Register assistant classes and (optionally) a custom resolver. OpenAI is supported via `llm: 'openai'`.
+```js
 await nexus.initialize({
   provider: 'twilio',
-  providerConfig: { /* twilio config */ }
-});
-
-nexus.setHandlers({
-  onMessage: async (messageData, nexus) => {
-    await nexus.sendMessage({
-      to: messageData.from,
-      message: `Echo: ${messageData.message}`
-    });
+  llm: 'openai', llmConfig: { apiKey: process.env.OPENAI_API_KEY },
+  assistants: {
+    registry: { SUPPORT: SupportAssistantClass, SALES: SalesAssistantClass },
+    getAssistantById: (id, thread) => null // optional override
   }
 });
 ```
 
-### 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;
-    }
-  }
-});
-```
+## Routes (Importable)
 
-### 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');
-    }
-  }
-});
-```
+Use `setupDefaultRoutes(app)` to mount everything, or pick from `routes` + `createRouter()` to mount subsets.
+
+## Examples
 
-## License
+See:
+- examples/basic-usage.js
+- examples/assistants/
 
-MIT