@peopl-health/nexus 1.6.2 → 1.6.4

package/MIGRATION_GUIDE.md

@@ -20,7 +20,7 @@ await nexus.sendMessage({ code: 'whatsapp:+521555...', message: 'Hi' });
 ```
 After (preferred):
 ```js
-await nexus.sendMessage({ to: '+521555...', message: 'Hi' });
+await nexus.sendMessage({ code: '+521555...', message: 'Hi' });
 ```
 
 ## Templates & Flows (Twilio)

package/README.md

@@ -88,10 +88,10 @@ 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' });
+await sendInteractive(nexus, { code: '+521555...', id: 'greeting_qr' });
 
 registerInteractiveHandler({ type: 'button', id: /sí|si/i }, async (msg, messaging) => {
-  await messaging.sendMessage({ to: msg.from, message: '¡Confirmado!' });
+  await messaging.sendMessage({ code: msg.from, message: '¡Confirmado!' });
 });
 attachInteractiveRouter(nexus);
 ```

package/examples/consumer-server.js

@@ -51,7 +51,7 @@ async function initializeNexus() {
       const response = await processTextMessage(messageData);
       if (response) {
         await nexus.sendMessage({
-          to: messageData.from,
+          code: messageData.from,
           message: response
         });
       }
@@ -64,7 +64,7 @@ async function initializeNexus() {
     switch (command) {
       case 'help':
         await nexus.sendMessage({
-          to: messageData.from,
+          code: messageData.from,
           message: `🤖 Available Commands:
 /help - Show this help
 /support - Connect to support assistant
@@ -78,7 +78,7 @@ async function initializeNexus() {
         const supportResponse = await assistants.support.handleMessage(messageData.from, 'Hello, I need support.');
         if (supportResponse) {
           await nexus.sendMessage({
-            to: messageData.from,
+            code: messageData.from,
             message: supportResponse
           });
         }
@@ -88,7 +88,7 @@ async function initializeNexus() {
         const salesResponse = await assistants.sales.handleMessage(messageData.from, 'Hello, I\'m interested in your products.');
         if (salesResponse) {
           await nexus.sendMessage({
-            to: messageData.from,
+            code: messageData.from,
             message: salesResponse
           });
         }
@@ -96,7 +96,7 @@ async function initializeNexus() {
         
       case 'status':
         await nexus.sendMessage({
-          to: messageData.from,
+          code: messageData.from,
           message: `System Status: ${nexus.isConnected() ? '✅ Connected' : '❌ Disconnected'}`
         });
         break;
@@ -106,14 +106,14 @@ async function initializeNexus() {
           await nexus.getStorage().clearThread(messageData.from);
         }
         await nexus.sendMessage({
-          to: messageData.from,
+          code: messageData.from,
           message: 'Conversation reset! You can start fresh now.'
         });
         break;
         
       default:
         await nexus.sendMessage({
-          to: messageData.from,
+          code: messageData.from,
           message: `Unknown command: /${command}. Type /help for available commands.`
         });
     }
@@ -136,10 +136,10 @@ app.post('/webhook', async (req, res) => {
 // API endpoints
 app.post('/api/send-message', async (req, res) => {
   try {
-    const { to, message, fileUrl, fileType } = req.body;
+    const { code, message, fileUrl, fileType } = req.body;
     
     const result = await nexus.sendMessage({
-      to,
+      code,
       message,
       fileUrl,
       fileType
@@ -153,10 +153,10 @@ app.post('/api/send-message', async (req, res) => {
 
 app.post('/api/send-template', async (req, res) => {
   try {
-    const { to, contentSid, variables } = req.body;
+    const { code, contentSid, variables } = req.body;
     
     const result = await nexus.sendMessage({
-      to,
+      code,
       contentSid,
       variables
     });

package/lib/adapters/BaileysProvider.js

@@ -84,9 +84,9 @@ class BaileysProvider extends MessageProvider {
       throw new Error('Baileys provider not connected');
     }
 
-    const { to, message, fileUrl, fileType, hidePreview = false } = messageData;
+    const { code, message, fileUrl, fileType, hidePreview = false } = messageData;
     
-    if (!to) {
+    if (!code) {
       throw new Error('Recipient is required');
     }
 
@@ -94,7 +94,7 @@ class BaileysProvider extends MessageProvider {
       throw new Error('Message or file URL is required');
     }
 
-    const code = this.formatCode(to);
+    const formattedCode = this.formatCode(code);
     let sendOptions = {};
     let formattedMessage = this.formatMessage(message || '');
 
@@ -135,7 +135,7 @@ class BaileysProvider extends MessageProvider {
     }
 
     try {
-      const result = await this.waSocket.sendMessage(code, sendOptions);
+      const result = await this.waSocket.sendMessage(formattedCode, sendOptions);
       return {
         success: true,
         messageId: result?.key?.id,
@@ -156,7 +156,7 @@ class BaileysProvider extends MessageProvider {
       : async (payload) => await this.sendMessage(payload);
 
     console.log('[BaileysProvider] Scheduled message created', {
-      to: scheduledMessage.to || scheduledMessage.code,
+      code: scheduledMessage.code,
       delay,
       hasMedia: Boolean(scheduledMessage.fileUrl)
     });
@@ -166,7 +166,7 @@ class BaileysProvider extends MessageProvider {
         const payload = { ...scheduledMessage };
         delete payload.__nexusSend;
         console.log('[BaileysProvider] Timer fired', {
-          to: payload.to || payload.code,
+          code: payload.to || payload.code,
           hasMessage: Boolean(payload.message || payload.body),
           hasMedia: Boolean(payload.fileUrl)
         });

package/lib/adapters/TwilioProvider.js

@@ -47,16 +47,16 @@ class TwilioProvider extends MessageProvider {
     const { code, message, fileUrl, fileType, variables, contentSid } = messageData;
 
     const formattedFrom = this.ensureWhatsAppFormat(this.whatsappNumber);
-    const formattedTo = this.ensureWhatsAppFormat(code);
+    const formattedCode = this.ensureWhatsAppFormat(code);
 
 
-    if (!formattedFrom || !formattedTo) {
+    if (!formattedFrom || !formattedCode) {
       throw new Error('Invalid sender or recipient number');
     }
 
     const messageParams = {
       from: formattedFrom,
-      to: formattedTo
+      to: formattedCode
     };
 
     // Handle template messages
@@ -83,7 +83,7 @@ class TwilioProvider extends MessageProvider {
 
     // Handle media messages
     if (fileUrl && fileType !== 'text') {
-      const mediaPrep = await this.prepareOutboundMedia(messageData, formattedTo);
+      const mediaPrep = await this.prepareOutboundMedia(messageData, formattedCode);
       const outboundMediaUrl = mediaPrep.mediaUrl || fileUrl;
       messageParams.mediaUrl = [outboundMediaUrl];
       if (!messageParams.body || messageParams.body.trim() === '') {
@@ -91,7 +91,7 @@ class TwilioProvider extends MessageProvider {
       }
       if (mediaPrep.uploaded) {
         console.log('[TwilioProvider] Outbound media uploaded to S3', {
-          to: formattedTo,
+          code: formattedCode,
           bucket: mediaPrep.bucketName,
           key: mediaPrep.key
         });
@@ -108,14 +108,14 @@ class TwilioProvider extends MessageProvider {
       if (this.messageStorage && typeof this.messageStorage.saveMessage === 'function') {
         try {
           console.log('[TwilioProvider] Persisting outbound message', {
-            to: formattedTo,
+            code: formattedCode,
             from: formattedFrom,
             hasMedia: Boolean(messageParams.mediaUrl && messageParams.mediaUrl.length),
             hasTemplate: Boolean(messageParams.contentSid)
           });
           await this.messageStorage.saveMessage({
             ...messageData,
-            to: formattedTo,
+            code: formattedCode,
             from: formattedFrom,
             messageId: result.sid,
             provider: 'twilio',
@@ -147,7 +147,7 @@ class TwilioProvider extends MessageProvider {
       : async (payload) => await this.sendMessage(payload);
 
     console.log('[TwilioProvider] Scheduled message created', {
-      to: scheduledMessage.code,
+      code: scheduledMessage.code,
       delay,
       hasContentSid: Boolean(scheduledMessage.contentSid)
     });
@@ -158,7 +158,7 @@ class TwilioProvider extends MessageProvider {
         const payload = scheduledMessage.toObject ? scheduledMessage.toObject() : { ...scheduledMessage };
         delete payload.__nexusSend;
         console.log('[TwilioProvider] Timer fired', {
-          to: payload.code,
+          code: payload.code,
           hasMessage: Boolean(payload.message || payload.body),
           hasMedia: Boolean(payload.fileUrl)
         });
@@ -176,7 +176,7 @@ class TwilioProvider extends MessageProvider {
     return true;
   }
 
-  async prepareOutboundMedia(messageData, formattedTo) {
+  async prepareOutboundMedia(messageData, formattedCode) {
     const bucketName = runtimeConfig.get('AWS_S3_BUCKET_NAME') || process.env.AWS_S3_BUCKET_NAME;
     const fileUrl = messageData.fileUrl;
 
@@ -221,7 +221,7 @@ class TwilioProvider extends MessageProvider {
 
       if (!validation.valid) {
         console.warn('[TwilioProvider] Outbound media validation warning', {
-          to: formattedTo,
+          code: formattedCode,
           message: validation.message
         });
       }
@@ -270,7 +270,7 @@ class TwilioProvider extends MessageProvider {
       };
     } catch (error) {
       console.error('[TwilioProvider] Failed to upload outbound media to S3. Using original URL.', {
-        to: formattedTo,
+        code: formattedCode,
         error: error?.message || error
       });
 

package/lib/assistants/BaseAssistant.js

@@ -17,7 +17,27 @@ class BaseAssistant {
     this.lastMessages = null;
     this.createdAt = new Date();
 
-    this.client = options.client || llmConfig.openaiClient || null;
+    const existingProvider = llmConfig.getOpenAIProvider({ instantiate: false });
+    this.provider = options.provider || existingProvider || null;
+    this.client = options.client
+      || (this.provider && this.provider.getClient ? this.provider.getClient() : null)
+      || llmConfig.openaiClient
+      || null;
+
+    if (!this.provider && this.client) {
+      try {
+        const { OpenAIProvider } = require('../providers/OpenAIProvider');
+        const provider = new OpenAIProvider({ client: this.client });
+        this.provider = provider;
+        if (typeof llmConfig.setOpenAIProvider === 'function') {
+          llmConfig.setOpenAIProvider(provider);
+        }
+      } catch (err) {
+        if (process.env.NODE_ENV !== 'production') {
+          console.warn('[BaseAssistant] Failed to initialise OpenAIProvider from client:', err?.message || err);
+        }
+      }
+    }
     this.tools = new Map();
 
     if (Array.isArray(options.tools)) {
@@ -67,7 +87,7 @@ class BaseAssistant {
     this.thread = thread;
   }
 
-  set_replies(replies) {
+  setReplies(replies) {
     this.replies = replies;
   }
 

package/lib/config/llmConfig.js

@@ -1,6 +1,53 @@
 const runtimeConfig = require('./runtimeConfig');
+const { OpenAIProvider } = require('../providers/OpenAIProvider');
 
 let anthropicClient = null;
+let openaiClient = null;
+let openaiProviderInstance = null;
+
+const setOpenAIClient = (client) => {
+  openaiClient = client || null;
+  module.exports.openaiClient = openaiClient;
+  if (!client) {
+    openaiProviderInstance = null;
+    module.exports.openaiProvider = null;
+  }
+};
+
+const setOpenAIProvider = (provider) => {
+  openaiProviderInstance = provider || null;
+  module.exports.openaiProvider = openaiProviderInstance;
+
+  if (!provider) {
+    setOpenAIClient(null);
+    return;
+  }
+
+  const client = typeof provider.getClient === 'function'
+    ? provider.getClient()
+    : provider.client;
+
+  if (client) {
+    setOpenAIClient(client);
+  }
+};
+
+const getOpenAIProvider = ({ instantiate = true } = {}) => {
+  if (openaiProviderInstance) return openaiProviderInstance;
+  if (!instantiate) return null;
+  if (!openaiClient) return null;
+  const provider = new OpenAIProvider({ client: openaiClient });
+  setOpenAIProvider(provider);
+  return provider;
+};
+
+const requireOpenAIProvider = (options) => {
+  const provider = getOpenAIProvider(options);
+  if (!provider) {
+    throw new Error('OpenAI provider not configured. Call configureLLMProvider first.');
+  }
+  return provider;
+};
 
 const resolveAnthropicClient = () => {
   if (anthropicClient) return anthropicClient;
@@ -21,7 +68,12 @@ const resolveAnthropicClient = () => {
 };
 
 module.exports = {
-  openaiClient: null,
+  openaiClient,
+  openaiProvider: openaiProviderInstance,
+  setOpenAIClient,
+  setOpenAIProvider,
+  getOpenAIProvider,
+  requireOpenAIProvider,
   get anthropicClient() {
     return resolveAnthropicClient();
   }

package/lib/core/MessageProvider.js

@@ -27,7 +27,7 @@ class MessageProvider {
   /**
    * Send a message
    * @param {Object} messageData - Message data
-   * @param {string} messageData.to - Recipient
+   * @param {string} messageData.code - Recipient
    * @param {string} messageData.message - Message text
    * @param {string} messageData.fileUrl - Optional file URL
    * @param {string} messageData.fileType - File type (text, image, document, audio)

package/lib/core/NexusMessaging.js

@@ -270,13 +270,7 @@ class NexusMessaging {
       throw new Error('No provider initialized');
     }
 
-    // Backward compatibility: accept `code` as destination
-    const normalized = { ...messageData };
-    if (!normalized.to && normalized.code) {
-      normalized.to = normalized.code;
-    }
-
-    const result = await this.provider.sendMessage(normalized);
+    const result = await this.provider.sendMessage(messageData);
 
     // Store message only if provider does not handle persistence itself
     const providerStoresMessage = typeof this.provider.supportsMessageStorage === 'function'
@@ -285,7 +279,7 @@ class NexusMessaging {
 
     if (this.messageStorage && !providerStoresMessage) {
       await this.messageStorage.saveMessage({
-        ...normalized,
+        ...messageData,
         messageId: result.messageId,
         provider: result.provider,
         timestamp: new Date(),
@@ -405,7 +399,7 @@ class NexusMessaging {
 
       if (response) {
         await this.sendMessage({
-          to: from,
+          code: from,
           message: response
         });
       }
@@ -455,7 +449,7 @@ class NexusMessaging {
 
       if (response) {
         await this.sendMessage({
-          to: from,
+          code: from,
           message: response
         });
       }

package/lib/helpers/assistantHelper.js

@@ -16,9 +16,8 @@ const mode = process.env.NODE_ENV || 'dev';
 
 async function checkRunStatus(assistant, thread_id, run_id, retryCount = 0, maxRetries = 30) {
   try {
-    const client = llmConfig.openaiClient;
-    if (!client) throw new Error('OpenAI client not configured');
-    const run = await client.beta.threads.runs.retrieve(thread_id, run_id);
+    const provider = llmConfig.requireOpenAIProvider();
+    const run = await provider.getRun({ conversationId: thread_id, runId: run_id });
     console.log(`Status: ${run.status} ${thread_id} ${run_id} (attempt ${retryCount + 1})`);
 
     if (run.status === 'failed' || run.status === 'expired' || run.status === 'incomplete') {
@@ -49,9 +48,8 @@ async function checkRunStatus(assistant, thread_id, run_id, retryCount = 0, maxR
 
 async function checkIfFinished(text) {
   try {
-    const client = llmConfig.openaiClient;
-    if (!client) throw new Error('OpenAI client not configured');
-    const completion = await client.chat.completions.create({
+    const provider = llmConfig.requireOpenAIProvider();
+    const completion = await provider.createChatCompletion({
       model: 'gpt-4o-mini',
       messages: [
         {
@@ -189,6 +187,7 @@ async function downloadMediaAndCreateFile(code, reply) {
 
 async function processMessage(code, reply, thread) {
   try {
+    const provider = llmConfig.requireOpenAIProvider();
     const formattedMessage = formatMessage(reply);
     const isNotAssistant = !reply.from_me;
     let messagesChat = [];
@@ -234,9 +233,7 @@ async function processMessage(code, reply, thread) {
             });
           } else {
             console.log('Add attachment');
-            const client = llmConfig.openaiClient;
-            if (!client) throw new Error('OpenAI client not configured');
-            const file = await client.files.create({
+            const file = await provider.uploadFile({
               file: fs.createReadStream(fileName),
               purpose: 'vision',
             });
@@ -246,18 +243,16 @@ async function processMessage(code, reply, thread) {
             });
           }
         } else if (fileName.includes('audio')) {
-          const client = llmConfig.openaiClient;
-          if (!client) throw new Error('OpenAI client not configured');
-          const audioTranscript = await client.audio.transcriptions.create({
-            model: 'whisper-1',
+          const audioTranscript = await provider.transcribeAudio({
             file: fs.createReadStream(fileName),
-            response_format: 'text',
+            responseFormat: 'text',
             language: 'es'
           });
-          console.log('Inside AUDIO', audioTranscript);
+          const transcriptText = audioTranscript?.text || audioTranscript;
+          console.log('Inside AUDIO', transcriptText);
           messagesChat.push({
             type: 'text',
-            text: audioTranscript,
+            text: transcriptText,
           });
         }
       }
@@ -266,9 +261,8 @@ async function processMessage(code, reply, thread) {
     console.log('messagesChat', messagesChat);
     console.log('attachments', attachments);
 
-    const client = llmConfig.openaiClient;
-    if (!client) throw new Error('OpenAI client not configured');
-    await client.beta.threads.messages.create(thread.thread_id, {
+    await provider.addMessage({
+      conversationId: thread.thread_id,
       role: 'user',
       content: messagesChat,
       attachments: attachments

package/lib/index.d.ts

@@ -6,7 +6,7 @@ declare module '@peopl-health/nexus' {
   export interface MessageData {
     id?: string;
     from: string;
-    to?: string;
+    code?: string;
     message?: string;
     fileUrl?: string;
     fileType?: 'text' | 'image' | 'document' | 'audio' | 'video';

package/lib/index.js

@@ -131,11 +131,17 @@ class Nexus {
     if (llm === 'openai') {
       this.llmProvider = new DefaultLLMProvider(llmConfig);
       try {
-        if (typeof this.llmProvider.getClient === 'function') {
-          llmConfigModule.openaiClient = this.llmProvider.getClient();
+        const providerInstance = typeof this.llmProvider.getProvider === 'function'
+          ? this.llmProvider.getProvider()
+          : null;
+
+        if (providerInstance && typeof llmConfigModule.setOpenAIProvider === 'function') {
+          llmConfigModule.setOpenAIProvider(providerInstance);
+        } else if (typeof this.llmProvider.getClient === 'function' && typeof llmConfigModule.setOpenAIClient === 'function') {
+          llmConfigModule.setOpenAIClient(this.llmProvider.getClient());
         }
       } catch (err) {
-        console.warn('[Nexus] Failed to expose OpenAI client:', err?.message || err);
+        console.warn('[Nexus] Failed to expose OpenAI provider:', err?.message || err);
       }
     }
 
@@ -163,9 +169,16 @@ class Nexus {
     // Configure Assistants (registry + overrides)
     const assistantsConfig = assistantsOpt || assistantOpt;
     try {
-      if (this.llmProvider && typeof configureAssistantsLLM === 'function' && typeof this.llmProvider.getClient === 'function') {
-        // Provide the raw OpenAI client to the assistant service
-        configureAssistantsLLM(this.llmProvider.getClient());
+      if (this.llmProvider && typeof configureAssistantsLLM === 'function') {
+        const providerInstance = typeof this.llmProvider.getProvider === 'function'
+          ? this.llmProvider.getProvider()
+          : null;
+
+        if (providerInstance) {
+          configureAssistantsLLM(providerInstance);
+        } else if (typeof this.llmProvider.getClient === 'function') {
+          configureAssistantsLLM(this.llmProvider.getClient());
+        }
       }
       if (assistantsConfig) {
         if (assistantsConfig.registry && typeof assistantsConfig.registry === 'object') {
@@ -198,7 +211,7 @@ class Nexus {
   /**
    * Send a message
    * @param {Object} messageData - Message data
-   * @param {string} messageData.to - Recipient phone number
+   * @param {string} messageData.code - Recipient phone number
    * @param {string} messageData.message - Message text
    * @param {string} [messageData.fileUrl] - Optional file URL
    * @param {string} [messageData.fileType] - File type
@@ -216,7 +229,7 @@ class Nexus {
   /**
    * Send a scheduled message
    * @param {Object} scheduledMessage - Scheduled message data
-   * @param {string} scheduledMessage.to - Recipient phone number
+   * @param {string} scheduledMessage.code - Recipient phone number
    * @param {string} scheduledMessage.message - Message text
    * @param {Date|string} scheduledMessage.sendAt - When to send the message
    * @returns {Promise<Object>} Scheduled message result
@@ -313,6 +326,7 @@ module.exports = {
   MongoStorage,
   MessageParser,
   DefaultLLMProvider,
+  OpenAIProvider: require('./providers/OpenAIProvider').OpenAIProvider,
   BaseAssistant: CoreBaseAssistant,
   registerAssistant,
   configureAssistantsLLM,

package/lib/interactive/index.js

@@ -3,7 +3,7 @@ const { toTwilioContent } = require('./twilioMapper');
 const { registerFlow, getFlow, listFlows, registerInteractiveHandler, listInteractiveHandlers } = require('./registry');
 
 async function sendInteractive(nexusOrMessaging, params) {
-  const { to, spec, id, variables } = params || {};
+  const { code, spec, id, variables } = params || {};
   if (!nexusOrMessaging) throw new Error('sendInteractive requires a Nexus or NexusMessaging instance');
   const messaging = typeof nexusOrMessaging.getMessaging === 'function' ? nexusOrMessaging.getMessaging() : nexusOrMessaging;
   const provider = typeof messaging.getProvider === 'function' ? messaging.getProvider() : null;
@@ -14,14 +14,14 @@ async function sendInteractive(nexusOrMessaging, params) {
 
   // If user supplied a contentSid directly in spec, just send it
   if (useSpec.contentSid) {
-    return await provider.sendMessage({ to, contentSid: useSpec.contentSid, variables });
+    return await provider.sendMessage({ code, contentSid: useSpec.contentSid, variables });
   }
 
   // Twilio mapping
   if (provider.constructor && provider.constructor.name === 'TwilioProvider') {
     const content = toTwilioContent(useSpec);
     const created = await provider.createTemplate(content);
-    return await provider.sendMessage({ to, contentSid: created.sid, variables });
+    return await provider.sendMessage({ code, contentSid: created.sid, variables });
   }
 
   // Baileys or others: not supported yet

package/lib/providers/OpenAIProvider.js

@@ -0,0 +1,297 @@
+const { OpenAI } = require('openai');
+
+/**
+ * Wrapper around the OpenAI SDK that exposes a higher level interface for
+ * common operations while remaining compatible with existing callers that
+ * expect the raw SDK surface (e.g. `.beta`).
+ */
+class OpenAIProvider {
+  constructor(options = {}) {
+    const {
+      apiKey = process.env.OPENAI_API_KEY,
+      organization,
+      client,
+      defaultModels = {},
+    } = options;
+
+    if (!client && !apiKey) {
+      throw new Error('OpenAIProvider requires an API key or a preconfigured client');
+    }
+
+    this.client = client || new OpenAI({ apiKey, organization });
+    this.defaults = {
+      responseModel: 'o4-mini',
+      chatModel: 'gpt-4o-mini',
+      transcriptionModel: 'whisper-1',
+      reasoningEffort: 'medium',
+      ...defaultModels,
+    };
+
+    // Expose raw SDK sub-clients for backward compatibility
+    this.beta = this.client.beta;
+    this.responses = this.client.responses;
+    this.chat = this.client.chat;
+    this.audio = this.client.audio;
+    this.files = this.client.files;
+  }
+
+  getClient() {
+    return this.client;
+  }
+
+  async createConversation({ metadata, messages = [], toolResources } = {}) {
+    const thread = await this.client.beta.threads.create({
+      metadata,
+      tool_resources: toolResources,
+    });
+
+    if (Array.isArray(messages) && messages.length > 0) {
+      for (const message of messages) {
+        await this.addMessage({ conversationId: thread.id, ...message });
+      }
+    }
+
+    return thread;
+  }
+
+  async deleteConversation(conversationId) {
+    await this.client.beta.threads.del(this._ensureId(conversationId));
+  }
+
+  async addMessage({ conversationId, role = 'user', content, attachments = [], metadata }) {
+    const formattedContent = this._normalizeContent(content);
+
+    const payload = {
+      role,
+      content: formattedContent,
+      attachments,
+      metadata,
+    };
+
+    if (payload.metadata && Object.keys(payload.metadata).length === 0) {
+      delete payload.metadata;
+    }
+
+    if (!payload.attachments || payload.attachments.length === 0) {
+      delete payload.attachments;
+    }
+
+    return this.client.beta.threads.messages.create(this._ensureId(conversationId), payload);
+  }
+
+  async listMessages({ conversationId, runId, order = 'desc', limit } = {}) {
+    return this.client.beta.threads.messages.list(this._ensureId(conversationId), {
+      run_id: runId,
+      order,
+      limit,
+    });
+  }
+
+  async getRunText({
+    conversationId,
+    runId,
+    messageIndex = 0,
+    contentIndex = 0,
+    fallback = '',
+  } = {}) {
+    const messages = await this.listMessages({ conversationId, runId });
+    const message = messages?.data?.[messageIndex];
+    const content = message?.content?.[contentIndex];
+
+    if (!content) {
+      return fallback;
+    }
+
+    if (content?.text?.value) {
+      return content.text.value;
+    }
+
+    if (content?.text && typeof content.text === 'string') {
+      return content.text;
+    }
+
+    return fallback;
+  }
+
+  async runConversation({
+    conversationId,
+    assistantId,
+    instructions,
+    additionalMessages = [],
+    additionalInstructions,
+    metadata,
+    topP,
+    temperature,
+    maxOutputTokens,
+    truncationStrategy,
+    tools = [],
+  } = {}) {
+    const payload = {
+      assistant_id: assistantId,
+      instructions,
+      additional_messages: additionalMessages,
+      additional_instructions: additionalInstructions,
+      metadata,
+      top_p: topP,
+      temperature,
+      max_output_tokens: maxOutputTokens,
+      truncation_strategy: truncationStrategy,
+      tools,
+    };
+
+    if (Array.isArray(payload.additional_messages) && payload.additional_messages.length === 0) {
+      delete payload.additional_messages;
+    }
+
+    if (Array.isArray(payload.tools) && payload.tools.length === 0) {
+      delete payload.tools;
+    }
+
+    if (payload.metadata && Object.keys(payload.metadata).length === 0) {
+      delete payload.metadata;
+    }
+
+    Object.keys(payload).forEach((key) => {
+      if (payload[key] === undefined || payload[key] === null) {
+        delete payload[key];
+      }
+    });
+
+    return this.client.beta.threads.runs.create(this._ensureId(conversationId), payload);
+  }
+
+  async getRun({ conversationId, runId }) {
+    return this.client.beta.threads.runs.retrieve(this._ensureId(conversationId), this._ensureId(runId));
+  }
+
+  async listRuns({ conversationId, limit, order = 'desc' } = {}) {
+    return this.client.beta.threads.runs.list(this._ensureId(conversationId), {
+      limit,
+      order,
+    });
+  }
+
+  async submitToolOutputs({ conversationId, runId, toolOutputs }) {
+    return this.client.beta.threads.runs.submitToolOutputs(
+      this._ensureId(conversationId),
+      this._ensureId(runId),
+      { tool_outputs: toolOutputs }
+    );
+  }
+
+  async cancelRun({ conversationId, runId }) {
+    return this.client.beta.threads.runs.cancel(
+      this._ensureId(conversationId),
+      this._ensureId(runId)
+    );
+  }
+
+  async runPrompt({
+    model,
+    input,
+    instructions,
+    reasoningEffort = this.defaults.reasoningEffort,
+    responseFormat,
+    metadata,
+    temperature,
+    maxOutputTokens,
+    tools,
+  } = {}) {
+    const payload = {
+      model: model || this.defaults.responseModel,
+      input,
+      instructions,
+      reasoning: reasoningEffort ? { effort: reasoningEffort } : undefined,
+      text: responseFormat ? { format: responseFormat } : undefined,
+      metadata,
+      temperature,
+      max_output_tokens: maxOutputTokens,
+      tools,
+    };
+
+    if (Array.isArray(payload.tools) && payload.tools.length === 0) {
+      delete payload.tools;
+    }
+
+    if (payload.metadata && Object.keys(payload.metadata).length === 0) {
+      delete payload.metadata;
+    }
+
+    Object.keys(payload).forEach((key) => {
+      if (payload[key] === undefined || payload[key] === null) {
+        delete payload[key];
+      }
+    });
+
+    return this.client.responses.create(payload);
+  }
+
+  async createChatCompletion({ model, messages, temperature, maxTokens, topP, metadata, responseFormat } = {}) {
+    return this.client.chat.completions.create({
+      model: model || this.defaults.chatModel,
+      messages,
+      temperature,
+      max_tokens: maxTokens,
+      top_p: topP,
+      metadata,
+      response_format: responseFormat,
+    });
+  }
+
+  async uploadFile({ file, purpose }) {
+    if (!file) {
+      throw new Error('uploadFile requires a readable file stream or object');
+    }
+
+    return this.client.files.create({ file, purpose: purpose || 'assistants' });
+  }
+
+  async transcribeAudio({ file, model, language, responseFormat, temperature, prompt } = {}) {
+    return this.client.audio.transcriptions.create({
+      model: model || this.defaults.transcriptionModel,
+      file,
+      language,
+      response_format: responseFormat,
+      temperature,
+      prompt,
+    });
+  }
+
+  _normalizeContent(content) {
+    if (content === undefined || content === null) {
+      return [{ type: 'text', text: '' }];
+    }
+
+    if (Array.isArray(content)) {
+      return content.map((item) => {
+        if (typeof item === 'string') {
+          return { type: 'text', text: item };
+        }
+        return item;
+      });
+    }
+
+    if (typeof content === 'string') {
+      return [{ type: 'text', text: content }];
+    }
+
+    return [content];
+  }
+
+  _ensureId(value) {
+    if (!value) {
+      throw new Error('Identifier value is required');
+    }
+    if (typeof value === 'string') {
+      return value;
+    }
+    if (typeof value === 'object' && value.id) {
+      return value.id;
+    }
+    throw new Error('Unable to resolve identifier value');
+  }
+}
+
+module.exports = {
+  OpenAIProvider,
+};

package/lib/services/assistantService.js

@@ -5,10 +5,21 @@ const { addRecord } = require('../services/airtableService.js');
 const runtimeConfig = require('../config/runtimeConfig');
 const llmConfig = require('../config/llmConfig');
 const { BaseAssistant } = require('../assistants/BaseAssistant');
+const { OpenAIProvider } = require('../providers/OpenAIProvider');
 
-let llmProvider = null;
 const configureLLMProvider = (provider) => {
-  llmProvider = provider;
+  if (!provider) {
+    throw new Error('configureLLMProvider requires an OpenAI provider or raw client');
+  }
+
+  if (provider instanceof OpenAIProvider || typeof provider.runConversation === 'function') {
+    llmConfig.setOpenAIProvider(provider);
+    return provider;
+  }
+
+  const wrappedProvider = new OpenAIProvider({ client: provider });
+  llmConfig.setOpenAIProvider(wrappedProvider);
+  return wrappedProvider;
 };
 
 let assistantConfig = null;
@@ -29,6 +40,60 @@ const configureAssistants = (config) => {
   assistantConfig = config;
 };
 
+const runAssistantAndWait = async ({
+  thread,
+  assistant,
+  runConfig = {}
+}) => {
+  if (!thread || !thread.thread_id) {
+    throw new Error('runAssistantAndWait requires a thread with a valid thread_id');
+  }
+
+  if (!assistant) {
+    throw new Error('runAssistantAndWait requires an assistant instance');
+  }
+
+  const provider = llmConfig.requireOpenAIProvider();
+  const { polling, ...conversationConfig } = runConfig || {};
+
+  const run = await provider.runConversation({
+    conversationId: thread.thread_id,
+    assistantId: thread.assistant_id,
+    ...conversationConfig,
+  });
+
+  const filter = thread.code ? { code: thread.code, active: true } : null;
+  if (filter) {
+    await Thread.updateOne(filter, { $set: { run_id: run.id } });
+  }
+
+  const maxRetries = polling?.maxRetries ?? 30;
+  let completed = false;
+
+  try {
+    completed = await checkRunStatus(assistant, run.thread_id, run.id, 0, maxRetries);
+  } finally {
+    if (filter) {
+      await Thread.updateOne(filter, { $set: { run_id: null } });
+    }
+  }
+
+  let finalRun = run;
+  try {
+    finalRun = await provider.getRun({ conversationId: run.thread_id, runId: run.id });
+  } catch (error) {
+    console.warn('Warning: unable to retrieve final run state:', error?.message || error);
+  }
+
+  if (!completed) {
+    return { run: finalRun, completed: false, output: '' };
+  }
+
+  const output = await provider.getRunText({ conversationId: run.thread_id, runId: run.id, fallback: '' });
+
+  return { run: finalRun, completed: true, output };
+};
+
 const registerAssistant = (assistantId, definition) => {
   if (!assistantId || typeof assistantId !== 'string') {
     throw new Error('registerAssistant requires a string assistantId');
@@ -49,10 +114,17 @@ const registerAssistant = (assistantId, definition) => {
 
     class ConfiguredAssistant extends ParentClass {
       constructor(options = {}) {
+        const provider = options.provider || llmConfig.getOpenAIProvider({ instantiate: false });
+        const sharedClient = options.client
+          || provider?.getClient?.()
+          || llmConfig.openaiClient
+          || null;
+
         super({
           ...options,
           assistantId,
-          client: options.client || llmProvider || llmConfig.openaiClient || null,
+          client: sharedClient,
+          provider,
           tools: [...tools, ...(options.tools || [])]
         });
 
@@ -100,20 +172,27 @@ const getAssistantById = (assistant_id, thread) => {
     throw new Error(`Assistant '${assistant_id}' not found. Available assistants: ${Object.keys(assistantRegistry).join(', ')}`);
   }
 
-  const sharedClient = llmProvider || llmConfig.openaiClient || null;
+  const provider = llmConfig.getOpenAIProvider({ instantiate: false });
+  const sharedClient = provider?.getClient?.() || llmConfig.openaiClient || null;
 
   if (AssistantClass.prototype instanceof BaseAssistant) {
     return new AssistantClass({
       assistantId: assistant_id,
       thread,
-      client: sharedClient
+      client: sharedClient,
+      provider
     });
   }
 
   try {
     return new AssistantClass(thread);
   } catch (error) {
-    return new AssistantClass({ thread, assistantId: assistant_id, client: sharedClient });
+    return new AssistantClass({
+      thread,
+      assistantId: assistant_id,
+      client: sharedClient,
+      provider
+    });
   }
 };
 
@@ -135,10 +214,13 @@ const createAssistant = async (code, assistant_id, messages=[], prevThread=null)
   const initialThread = await assistant.create(code, curRow[0]);
 
   // Add new messages to memory
+  const provider = llmConfig.requireOpenAIProvider();
   for (const message of messages) {
-    await llmProvider.beta.threads.messages.create(
-      initialThread.id, { role: 'assistant', content: message }
-    );
+    await provider.addMessage({
+      conversationId: initialThread.id,
+      role: 'assistant',
+      content: message
+    });
   }
     
   // Define new thread data
@@ -159,7 +241,7 @@ const createAssistant = async (code, assistant_id, messages=[], prevThread=null)
 
   // Delete previous thread
   if (prevThread) {
-    await llmProvider.beta.threads.del(prevThread.thread_id);
+    await provider.deleteConversation(prevThread.thread_id);
   }
 
   return thread;
@@ -171,32 +253,24 @@ const addMsgAssistant = async (code, inMessages, reply = false) => {
     console.log(thread);
     if (thread === null) return null;
 
+    const provider = llmConfig.requireOpenAIProvider();
+
     for (const message of inMessages) {
       console.log(message);
-      await llmProvider.beta.threads.messages.create(
-        thread.thread_id, { role: 'assistant', content: message }
-      );
+      await provider.addMessage({
+        conversationId: thread.thread_id,
+        role: 'assistant',
+        content: message
+      });
     }
 
     if (!reply) return null;
 
     const assistant = getAssistantById(thread.assistant_id, thread);
-    const run = await llmProvider.beta.threads.runs.create(
-      thread.thread_id, 
-      { 
-        assistant_id: thread.assistant_id
-      }
-    );
-
-    await Thread.updateOne({ code: thread.code, active: true }, { $set: { run_id: run.id } });  
-    await checkRunStatus(assistant, run.thread_id, run.id);
-    await Thread.updateOne({ code: thread.code, active: true }, { $set: { run_id: null } });  
+    const { output } = await runAssistantAndWait({ thread, assistant });
+    console.log('THE ANS IS', output);
 
-    const messages = await llmProvider.beta.threads.messages.list(run.thread_id, { run_id: run.id });
-    const ans = messages.data[0].content[0].text.value;
-    console.log('THE ANS IS', ans);
-        
-    return ans;
+    return output;
   } catch (error) {
     console.log(error);
     return null;
@@ -210,25 +284,19 @@ const addInsAssistant = async (code, instruction) => {
     if (thread === null) return null;
 
     const assistant = getAssistantById(thread.assistant_id, thread);
-    const run = await llmProvider.beta.threads.runs.create(
-      thread.thread_id, { 
-        assistant_id: thread.assistant_id,
-        additional_instructions: instruction,
-        additional_messages: [
+    const { output } = await runAssistantAndWait({
+      thread,
+      assistant,
+      runConfig: {
+        additionalInstructions: instruction,
+        additionalMessages: [
           { role: 'user', content: instruction }
         ]
       }
-    );
-
-    await Thread.updateOne({ code: thread.code, active: true }, { $set: { run_id: run.id } });  
-    await checkRunStatus(assistant, run.thread_id, run.id);
-    await Thread.updateOne({ code: thread.code, active: true }, { $set: { run_id: null } });  
+    });
+    console.log('RUN RESPONSE', output);
 
-    const messages = await llmProvider.beta.threads.messages.list(run.thread_id, { run_id: run.id });
-    console.log(messages.data[0].content);
-    const ans = messages.data[0].content[0].text.value;
-        
-    return ans;
+    return output;
   } catch (error) {
     console.log(error);
     return null;
@@ -250,9 +318,11 @@ const getThread = async (code, message = null) => {
       return null;
     }
 
+    const provider = llmConfig.getOpenAIProvider({ instantiate: false });
     while (thread && thread.run_id) {
       console.log(`Wait for ${thread.run_id} to be executed`);
-      const run = await llmProvider.beta.threads.runs.retrieve(thread.thread_id, thread.run_id);
+      const activeProvider = provider || llmConfig.requireOpenAIProvider();
+      const run = await activeProvider.getRun({ conversationId: thread.thread_id, runId: thread.run_id });
       if (run.status === 'cancelled' || run.status === 'expired' || run.status === 'completed') {
         await Thread.updateOne({ code: code }, { $set: { run_id: null } });
       }
@@ -283,18 +353,22 @@ const replyAssistant = async function (code, message_ = null, thread_ = null, ru
     console.log('THREAD STOPPED', code, thread?.active);
     if (!thread || !thread.active) return null;
 
-    const patientReply = await getLastMessages(code);
+    const patientReply = message_ ? [message_] : await getLastMessages(code);
     console.log('UNREAD DATA', patientReply);
     if (!patientReply) {
       console.log('No relevant data found for this assistant.');
       return null;
     }
 
-    let activeRuns = await llmProvider.beta.threads.runs.list(thread.thread_id);
-    console.log('ACTIVE RUNS:', activeRuns.length);
-    while (activeRuns.length > 0) {
+    const provider = llmConfig.requireOpenAIProvider();
+
+    let activeRuns = await provider.listRuns({ conversationId: thread.thread_id });
+    let activeRunsCount = activeRuns?.data?.length || 0;
+    console.log('ACTIVE RUNS:', activeRunsCount);
+    while (activeRunsCount > 0) {
       console.log(`ACTIVE RUNS ${thread.thread_id}`);
-      activeRuns = await llmProvider.beta.threads.runs.list(thread.thread_id);
+      activeRuns = await provider.listRuns({ conversationId: thread.thread_id });
+      activeRunsCount = activeRuns?.data?.length || 0;
       await delay(5000);
     }
 
@@ -335,27 +409,18 @@ const replyAssistant = async function (code, message_ = null, thread_ = null, ru
     if (!patientMsg || !thread || thread?.stopped) return null;
 
     const assistant = getAssistantById(thread.assistant_id, thread);
-    const run = await llmProvider.beta.threads.runs.create(
-      thread.thread_id, 
-      { 
-        assistant_id: thread.assistant_id,
-        ...runOptions
-      }
-    );
-    console.log('RUN LAST ERROR:', run.last_error);
-
-    assistant.set_replies(patientReply);
-        
-    await Thread.updateOne({ code: thread.code, active: true }, { $set: { run_id: run.id } });  
-    const runStatus = await checkRunStatus(assistant, run.thread_id, run.id);
-    console.log('RUN STATUS', runStatus);
-    await Thread.updateOne({ code: thread.code, active: true }, { $set: { run_id: null } });  
+    assistant.setReplies(patientReply);
 
-    const messages = await llmProvider.beta.threads.messages.list(run.thread_id, { run_id: run.id });
-    const reply = messages.data?.[0]?.content?.[0]?.text?.value || '';
-    console.log(reply);
+    const { run, output, completed } = await runAssistantAndWait({
+      thread,
+      assistant,
+      runConfig: runOptions
+    });
+    console.log('RUN LAST ERROR:', run?.last_error);
+    console.log('RUN STATUS', completed);
+    console.log(output);
 
-    return reply;
+    return output;
   } catch (err) {
     console.log(`Error inside reply assistant ${err} ${code}`);
   }
@@ -386,5 +451,6 @@ module.exports = {
   configureAssistants,
   registerAssistant,
   configureLLMProvider,
-  overrideGetAssistantById
+  overrideGetAssistantById,
+  runAssistantAndWait
 };

package/lib/storage/MongoStorage.js

@@ -62,7 +62,7 @@ class MongoStorage {
   async saveMessage(messageData) {
     try {
       console.log('[MongoStorage] saveMessage called', {
-        to: messageData?.to || messageData?.code || messageData?.numero,
+        code: messageData?.to || messageData?.code || messageData?.numero,
         from: messageData?.from,
         provider: messageData?.provider || 'unknown',
         hasRaw: Boolean(messageData?.raw),

package/lib/utils/defaultLLMProvider.js

@@ -1,21 +1,19 @@
-const OpenAI = require('openai');
+const { OpenAIProvider } = require('../providers/OpenAIProvider');
 
 /**
  * Default LLM Provider using OpenAI
  */
 class DefaultLLMProvider {
   constructor(config = {}) {
-    const apiKey = config.apiKey || process.env.OPENAI_API_KEY;
-    
-    if (!apiKey) {
-      throw new Error('OpenAI API key is required. Set OPENAI_API_KEY environment variable or pass apiKey in config.');
-    }
+    this.provider = new OpenAIProvider(config);
+  }
 
-    this.client = new OpenAI({ apiKey });
+  getProvider() {
+    return this.provider;
   }
 
   getClient() {
-    return this.client;
+    return this.provider.getClient();
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peopl-health/nexus",
-  "version": "1.6.2",
+  "version": "1.6.4",
   "description": "Core messaging and assistant library for WhatsApp communication platforms",
   "keywords": [
     "whatsapp",