@peopl-health/nexus 1.5.8 → 1.5.10

package/examples/assistants/BaseAssistant.js

@@ -1,242 +1 @@
-/**
- * Base Assistant class for consumer server extensions
- * Provides common functionality for AI assistant implementations
- */
-class BaseAssistant {
-  constructor(config = {}) {
-    this.assistantId = config.assistantId;
-    this.llmClient = config.llmClient;
-    this.storage = config.storage;
-    this.nexus = config.nexus;
-    this.functions = new Map();
-  }
-
-  /**
-   * Register a function that can be called by the assistant
-   * @param {string} name - Function name
-   * @param {Function} handler - Function handler
-   * @param {Object} schema - Function schema for LLM
-   */
-  registerFunction(name, handler, schema) {
-    this.functions.set(name, { handler, schema });
-  }
-
-  /**
-   * Get all registered function schemas for LLM
-   * @returns {Array} Function schemas
-   */
-  getFunctionSchemas() {
-    return Array.from(this.functions.values()).map(f => f.schema);
-  }
-
-  /**
-   * Execute a function call from the assistant
-   * @param {string} name - Function name
-   * @param {Object} args - Function arguments
-   * @returns {Promise<any>} Function result
-   */
-  async executeFunction(name, args) {
-    const func = this.functions.get(name);
-    if (!func) {
-      throw new Error(`Unknown function: ${name}`);
-    }
-    return await func.handler(args);
-  }
-
-  /**
-   * Create a new thread for this assistant
-   * @param {string} userId - User identifier
-   * @param {Array} initialMessages - Initial messages
-   * @returns {Promise<Object>} Thread data
-   */
-  async createThread(userId, initialMessages = []) {
-    if (!this.llmClient) {
-      throw new Error('LLM client not configured');
-    }
-
-    const thread = await this.llmClient.beta.threads.create();
-    
-    // Add initial messages if provided
-    for (const message of initialMessages) {
-      await this.llmClient.beta.threads.messages.create(
-        thread.id, 
-        { role: "assistant", content: message }
-      );
-    }
-
-    const threadData = {
-      code: userId,
-      assistantId: this.assistantId,
-      threadId: thread.id,
-      active: true,
-      createdAt: new Date()
-    };
-
-    // Save to storage if available
-    if (this.storage) {
-      await this.storage.createThread(threadData);
-    }
-
-    return threadData;
-  }
-
-  /**
-   * Send message to assistant and handle response
-   * @param {string} userId - User identifier
-   * @param {string} message - User message
-   * @param {Object} options - Additional options
-   * @returns {Promise<string>} Assistant response
-   */
-  async sendMessage(userId, message, options = {}) {
-    if (!this.llmClient) {
-      throw new Error('LLM client not configured');
-    }
-
-    // Get or create thread
-    let threadData = null;
-    if (this.storage) {
-      threadData = await this.storage.getThread(userId);
-    }
-
-    if (!threadData) {
-      threadData = await this.createThread(userId);
-    }
-
-    // Add user message to thread
-    await this.llmClient.beta.threads.messages.create(
-      threadData.threadId,
-      { role: "user", content: message }
-    );
-
-    // Create run with function schemas if available
-    const runConfig = {
-      assistant_id: this.assistantId,
-      ...options
-    };
-
-    const functionSchemas = this.getFunctionSchemas();
-    if (functionSchemas.length > 0) {
-      runConfig.tools = functionSchemas;
-    }
-
-    const run = await this.llmClient.beta.threads.runs.create(
-      threadData.threadId,
-      runConfig
-    );
-
-    // Wait for completion and handle function calls
-    const result = await this.waitForCompletion(threadData.threadId, run.id);
-    
-    if (result.status === 'completed') {
-      const messages = await this.llmClient.beta.threads.messages.list(
-        threadData.threadId, 
-        { run_id: run.id }
-      );
-      return messages.data[0]?.content[0]?.text?.value || "";
-    }
-
-    return null;
-  }
-
-  /**
-   * Wait for run completion and handle function calls
-   * @param {string} threadId - Thread ID
-   * @param {string} runId - Run ID
-   * @returns {Promise<Object>} Run result
-   */
-  async waitForCompletion(threadId, runId) {
-    const maxAttempts = 30;
-    let attempts = 0;
-
-    while (attempts < maxAttempts) {
-      const run = await this.llmClient.beta.threads.runs.retrieve(threadId, runId);
-      
-      if (run.status === 'completed') {
-        return { status: 'completed', run };
-      } else if (run.status === 'requires_action') {
-        // Handle function calls
-        const toolOutputs = await this.handleRequiredActions(run);
-        
-        if (toolOutputs.length > 0) {
-          await this.llmClient.beta.threads.runs.submitToolOutputs(
-            threadId,
-            runId,
-            { tool_outputs: toolOutputs }
-          );
-          
-          // Continue waiting for completion
-          attempts = 0; // Reset attempts after submitting outputs
-          await this.delay(2000);
-          continue;
-        }
-      } else if (run.status === 'failed' || run.status === 'cancelled' || run.status === 'expired') {
-        return { status: 'failed', run };
-      }
-
-      await this.delay(2000);
-      attempts++;
-    }
-
-    throw new Error('Assistant run timeout');
-  }
-
-  /**
-   * Handle required actions (function calls)
-   * @param {Object} run - Run object with required actions
-   * @returns {Promise<Array>} Tool outputs
-   */
-  async handleRequiredActions(run) {
-    const toolCalls = run.required_action?.submit_tool_outputs?.tool_calls || [];
-    const toolOutputs = [];
-
-    for (const toolCall of toolCalls) {
-      try {
-        const functionName = toolCall.function.name;
-        const args = JSON.parse(toolCall.function.arguments);
-        
-        const result = await this.executeFunction(functionName, args);
-        
-        toolOutputs.push({
-          tool_call_id: toolCall.id,
-          output: JSON.stringify(result)
-        });
-      } catch (error) {
-        console.error(`Error executing function ${toolCall.function.name}:`, error);
-        toolOutputs.push({
-          tool_call_id: toolCall.id,
-          output: JSON.stringify({ error: error.message })
-        });
-      }
-    }
-
-    return toolOutputs;
-  }
-
-  /**
-   * Send a message through Nexus
-   * @param {string} to - Recipient
-   * @param {string} message - Message text
-   * @param {Object} options - Additional options
-   */
-  async sendNexusMessage(to, message, options = {}) {
-    if (!this.nexus) {
-      throw new Error('Nexus instance not provided');
-    }
-
-    return await this.nexus.sendMessage({
-      to,
-      message,
-      ...options
-    });
-  }
-
-  /**
-   * Utility delay function
-   * @param {number} ms - Milliseconds to delay
-   */
-  delay(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
-  }
-}
-
-module.exports = { BaseAssistant };
+module.exports = require('../../lib/assistants/BaseAssistant');

package/examples/assistants/DoctorScheduleAssistant.js

@@ -0,0 +1,83 @@
+const { BaseAssistant } = require('../../lib/assistants/BaseAssistant');
+
+class DoctorScheduleAssistant extends BaseAssistant {
+  constructor(thread) {
+    super({ assistantId: 'doctor_schedule', thread });
+
+    this.registerTool({
+      name: 'storePatientAppointment',
+      description: 'Stores a requested appointment so that an operator can follow up with the patient.',
+      parameters: {
+        type: 'object',
+        required: ['contact_number', 'appointment_type'],
+        properties: {
+          contact_number: {
+            type: 'string',
+            description: 'WhatsApp phone number of the patient in international format (e.g. +521234567890).'
+          },
+          appointment_type: {
+            type: 'string',
+            description: 'Type of medical appointment requested by the patient.'
+          },
+          patient_name: {
+            type: 'string',
+            description: 'Full name of the patient if provided.'
+          },
+          preferred_date: {
+            type: 'string',
+            description: 'Preferred appointment date in ISO format (YYYY-MM-DD).'
+          },
+          preferred_time: {
+            type: 'string',
+            description: 'Preferred appointment time in HH:mm format.'
+          },
+          notes: {
+            type: 'string',
+            description: 'Any extra notes supplied by the patient.'
+          }
+        }
+      },
+      handler: async (payload = {}) => {
+        console.log('[DoctorScheduleAssistant] storePatientAppointment', payload);
+
+        if (!payload.contact_number || !payload.appointment_type) {
+          return JSON.stringify({
+            success: false,
+            message: 'Falta el número de contacto o el tipo de cita. Pide esa información al paciente.'
+          });
+        }
+
+        const normalizedNumber = String(payload.contact_number).replace(/[^0-9+]/g, '');
+
+        const appointment = {
+          contact_number: normalizedNumber,
+          appointment_type: payload.appointment_type,
+          patient_name: payload.patient_name || null,
+          preferred_date: payload.preferred_date || null,
+          preferred_time: payload.preferred_time || null,
+          notes: payload.notes || null
+        };
+
+        console.log('[DoctorScheduleAssistant] Appointment captured', appointment);
+
+        return JSON.stringify({ success: true, appointment });
+      }
+    });
+  }
+
+  async create(code, curRow) {
+    await super.create(code, curRow);
+
+    const summary = this.lastMessages
+      ? [{ role: 'assistant', content: `Últimos mensajes:
+${this.lastMessages}` }]
+      : [];
+
+    const client = this.client;
+    if (!client) throw new Error('OpenAI client not configured');
+
+    return await client.beta.threads.create({ messages: summary });
+  }
+}
+
+module.exports = { DoctorScheduleAssistant };

package/examples/assistants/index.js

@@ -1,7 +1,9 @@
 const { BaseAssistant } = require('./BaseAssistant');
 const { ExampleAssistant } = require('./ExampleAssistant');
+const { DoctorScheduleAssistant } = require('./DoctorScheduleAssistant');
 
 module.exports = {
   BaseAssistant,
-  ExampleAssistant
+  ExampleAssistant,
+  DoctorScheduleAssistant
 };

package/examples/basic-usage.js

@@ -1,12 +1,13 @@
 const express = require('express');
-const { NexusMessaging, setupDefaultRoutes } = require('@peopl-health/nexus');
+require('dotenv').config();
+const { Nexus, setupDefaultRoutes } = require('@peopl-health/nexus');
 
 const app = express();
 app.use(express.json());
 
 async function startServer() {
   // Initialize Nexus with all services
-  const nexus = new NexusMessaging();
+  const nexus = new Nexus();
   
   await nexus.initialize({
     // MongoDB connection
@@ -17,7 +18,7 @@ async function startServer() {
     providerConfig: {
       accountSid: process.env.TWILIO_ACCOUNT_SID,
       authToken: process.env.TWILIO_AUTH_TOKEN,
-      phoneNumber: process.env.TWILIO_PHONE_NUMBER
+      whatsappNumber: process.env.TWILIO_WHATSAPP_NUMBER
     }
   });
 
@@ -27,7 +28,7 @@ async function startServer() {
   // Add webhook endpoint for incoming messages
   app.post('/webhook', async (req, res) => {
     try {
-      await nexus.processIncomingMessage(req.body);
+      await nexus.messaging.processIncomingMessage(req.body);
       res.status(200).send('OK');
     } catch (error) {
       console.error('Webhook error:', error);
@@ -38,10 +39,10 @@ async function startServer() {
   // Custom endpoint example
   app.get('/status', (req, res) => {
     res.json({
-      connected: nexus.isConnected(),
+      connected: nexus.messaging.isConnected(),
       provider: 'twilio',
-      mongodb: nexus.mongodb?.readyState === 1,
-      airtable: !!nexus.airtable
+      mongodb: nexus.messaging.mongodb?.readyState === 1,
+      airtable: !!nexus.messaging.airtable
     });
   });
 

package/lib/adapters/TwilioProvider.js

@@ -44,10 +44,11 @@ class TwilioProvider extends MessageProvider {
       throw new Error('Twilio provider not initialized');
     }
 
-    const { to, message, fileUrl, fileType, variables, contentSid } = messageData;
+    const { code, message, fileUrl, fileType, variables, contentSid } = messageData;
 
     const formattedFrom = this.ensureWhatsAppFormat(this.whatsappNumber);
-    const formattedTo = this.ensureWhatsAppFormat(to);
+    const formattedTo = this.ensureWhatsAppFormat(code);
+
 
     if (!formattedFrom || !formattedTo) {
       throw new Error('Invalid sender or recipient number');
@@ -60,6 +61,12 @@ class TwilioProvider extends MessageProvider {
 
     // Handle template messages
     if (contentSid) {
+      // Render template and add to messageData for storage
+      const renderedMessage = await this.renderTemplate(contentSid, variables);
+      if (renderedMessage) {
+        messageData.body = renderedMessage; // Add rendered content for storage
+      }
+      
       messageParams.contentSid = contentSid;
       if (variables && Object.keys(variables).length > 0) {
         const formattedVariables = {};
@@ -140,17 +147,18 @@ class TwilioProvider extends MessageProvider {
       : async (payload) => await this.sendMessage(payload);
 
     console.log('[TwilioProvider] Scheduled message created', {
-      to: scheduledMessage.to || scheduledMessage.code,
+      to: scheduledMessage.code,
       delay,
       hasContentSid: Boolean(scheduledMessage.contentSid)
     });
 
     setTimeout(async () => {
       try {
-        const payload = { ...scheduledMessage };
+        // Convert Mongoose document to plain object if needed
+        const payload = scheduledMessage.toObject ? scheduledMessage.toObject() : { ...scheduledMessage };
         delete payload.__nexusSend;
         console.log('[TwilioProvider] Timer fired', {
-          to: payload.to || payload.code,
+          to: payload.code,
           hasMessage: Boolean(payload.message || payload.body),
           hasMedia: Boolean(payload.fileUrl)
         });
@@ -311,6 +319,170 @@ class TwilioProvider extends MessageProvider {
     }
   }
 
+  /**
+   * Render template content with variables
+   * @param {string} contentSid - The Twilio content SID
+   * @param {Object} variables - The variables object with keys like "1", "2"
+   * @returns {Promise<string|null>} The rendered message content or null if not found
+   */
+  async renderTemplate(contentSid, variables) {
+    try {
+      if (!contentSid) return null;
+
+      const template = await this.getTemplate(contentSid);
+      
+      if (!template || !template.types) {
+        console.warn('[TwilioProvider] Template not found or has no types:', contentSid);
+        return null;
+      }
+
+      // Extract text content from different template types
+      let textContent = this.extractTextFromTemplate(template);
+
+      if (!textContent) {
+        console.warn('[TwilioProvider] No text content found in template:', contentSid);
+        return null;
+      }
+
+      // Render variables if provided
+      if (variables && typeof variables === 'object' && Object.keys(variables).length > 0) {
+        return this.renderTemplateWithVariables(textContent, variables);
+      }
+
+      return textContent.trim();
+    } catch (error) {
+      console.error('[TwilioProvider] Error rendering template:', error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Extract text content from different template types
+   * @param {Object} template - The Twilio template object
+   * @returns {string} The extracted text content
+   */
+  extractTextFromTemplate(template) {
+    const types = template.types || {};
+    
+    // Handle plain text templates
+    if (types['twilio/text']) {
+      return types['twilio/text'].body || '';
+    }
+    
+    // Handle quick reply templates
+    if (types['twilio/quick-reply']) {
+      const quickReply = types['twilio/quick-reply'];
+      let text = quickReply.body || '';
+      
+      // Add quick reply options
+      if (quickReply.actions && Array.isArray(quickReply.actions)) {
+        const options = quickReply.actions
+          .filter(action => action.title)
+          .map(action => `• ${action.title}`)
+          .join('\n');
+        if (options) {
+          text += (text ? '\n\n' : '') + options;
+        }
+      }
+      
+      return text;
+    }
+    
+    // Handle list templates
+    if (types['twilio/list']) {
+      const list = types['twilio/list'];
+      let text = list.body || '';
+      
+      // Add list items
+      if (list.items && Array.isArray(list.items)) {
+        const items = list.items
+          .filter(item => item.title)
+          .map((item, index) => `${index + 1}. ${item.title}`)
+          .join('\n');
+        if (items) {
+          text += (text ? '\n\n' : '') + items;
+        }
+      }
+      
+      return text;
+    }
+    
+    // Handle button templates
+    if (types['twilio/button']) {
+      const button = types['twilio/button'];
+      let text = button.body || '';
+      
+      // Add button options
+      if (button.actions && Array.isArray(button.actions)) {
+        const buttons = button.actions
+          .filter(action => action.title)
+          .map(action => `[${action.title}]`)
+          .join(' ');
+        if (buttons) {
+          text += (text ? '\n\n' : '') + buttons;
+        }
+      }
+      
+      return text;
+    }
+    
+    // Handle flow templates (fallback to body)
+    if (types['twilio/flows']) {
+      return types['twilio/flows'].body || '';
+    }
+    
+    // Handle media templates (extract caption)
+    if (types['twilio/media']) {
+      return types['twilio/media'].caption || '';
+    }
+    
+    // Fallback: try to find any body content
+    for (const typeKey of Object.keys(types)) {
+      const type = types[typeKey];
+      if (type && typeof type === 'object' && type.body) {
+        return type.body;
+      }
+    }
+    
+    return '';
+  }
+
+  /**
+   * Render template content with variables
+   * @param {string} templateBody - The template body with placeholders like {{1}}, {{2}}
+   * @param {Object} variables - The variables object with keys like "1", "2"
+   * @returns {string} The rendered message content
+   */
+  renderTemplateWithVariables(templateBody, variables) {
+    if (!templateBody || typeof templateBody !== 'string') {
+      return '';
+    }
+
+    if (!variables || typeof variables !== 'object') {
+      return templateBody;
+    }
+
+    try {
+      let rendered = templateBody;
+      
+      // Replace placeholders like {{1}}, {{2}}, etc. with variable values
+      Object.keys(variables).forEach(key => {
+        const placeholder = `{{${key}}}`;
+        const value = variables[key] || '';
+        
+        // Simple string replacement - more reliable than regex for this use case
+        if (rendered.includes(placeholder)) {
+          rendered = rendered.replace(new RegExp(placeholder.replace(/[{}]/g, '\\$&'), 'g'), value);
+        }
+      });
+
+      return rendered.trim();
+    } catch (error) {
+      console.warn('[TwilioProvider] Error rendering template variables:', error.message);
+      return templateBody; // Return original template if rendering fails
+    }
+  }
+
   /**
    * Check template approval status using Twilio Content API helpers
    */