@tiledesk/tiledesk-voice-twilio-connector 0.1.28 → 0.2.0-rc6

package/src/services/SessionService.js

@@ -0,0 +1,143 @@
+const logger = require('../utils/logger');
+const { CHANNEL_NAME, VOICE_LANGUAGE, VOICE_NAME } = require('../utils/constants');
+
+/**
+ * Service responsible for managing voice call session lifecycle.
+ * Handles session creation, retrieval, and cleanup.
+ */
+class SessionService {
+  constructor({ voiceChannel, integrationService, tdChannel, config }) {
+    if (!voiceChannel) throw new Error('[SessionService] voiceChannel is required');
+    if (!integrationService) throw new Error('[SessionService] integrationService is required');
+    if (!tdChannel) throw new Error('[SessionService] tdChannel is required');
+    if (!config) throw new Error('[SessionService] config is required');
+
+    this.voiceChannel = voiceChannel;
+    this.integrationService = integrationService;
+    this.tdChannel = tdChannel;
+    this.config = config;
+  }
+
+  /**
+   * Retrieve integration keys (OpenAI, ElevenLabs) for a project.
+   * @param {string} projectId - The project ID
+   * @param {string} token - Authorization token
+   * @returns {Promise<Array>} Array of integration objects
+   */
+  async getIntegrationKeys(projectId, token) {
+    const integrations = [];
+
+    // Retrieve OpenAI key with fallback chain
+    const openaiKey = await this._getOpenAIKey(projectId, token);
+    if (openaiKey) {
+      integrations.push(openaiKey);
+    }
+
+    // Retrieve ElevenLabs key
+    const elevenLabsKey = await this._getElevenLabsKey(projectId, token);
+    if (elevenLabsKey) {
+      integrations.push(elevenLabsKey);
+    }
+
+    return integrations;
+  }
+
+  /**
+   * Get OpenAI key with fallback: Integrations -> KB Settings -> Public Key
+   */
+  async _getOpenAIKey(projectId, token) {
+    try {
+      let key = await this.integrationService.getKeyFromIntegrations(projectId, 'openai', token);
+      
+      if (!key) {
+        // logger.debug('[SessionService] OpenAI key not in Integrations, checking KB settings...');
+        key = await this.integrationService.getKeyFromKbSettings(projectId, token);
+      }
+
+      if (!key) {
+        // logger.debug('[SessionService] Using public GPT key');
+        return { type: 'openai', key: this.config.GPT_KEY, publicKey: true };
+      }
+
+      return { type: 'openai', key, publicKey: false };
+    } catch (error) {
+      logger.error('[SessionService] Error retrieving OpenAI key:', error);
+      return { type: 'openai', key: this.config.GPT_KEY, publicKey: true };
+    }
+  }
+
+  /**
+   * Get ElevenLabs key from integrations
+   */
+  async _getElevenLabsKey(projectId, token) {
+    try {
+      const key = await this.integrationService.getKeyFromIntegrations(projectId, 'elevenlabs', token);
+      if (key) {
+        // logger.debug('[SessionService] ElevenLabs key found');
+        return { type: 'elevenlabs', key, publicKey: false };
+      }
+      return null;
+    } catch (error) {
+      logger.error('[SessionService] Error retrieving ElevenLabs key:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Create and store a new call session.
+   * @param {Object} params - Session parameters
+   * @returns {Promise<Object>} The created session data
+   */
+  async createSession({ callSid, from, to, projectId, user, conversationId, integrations }) {
+    const sessionData = {
+      from,
+      to,
+      callSid,
+      project_id: projectId,
+      user,
+      conversation_id: conversationId,
+      integrations
+    };
+
+    await this.voiceChannel.setSessionForCallId(callSid, sessionData);
+    // logger.debug(`[SessionService] Session created for callSid: ${callSid}`);
+    
+    return sessionData;
+  }
+
+  /**
+   * Retrieve session context for a call.
+   * @param {string} callSid - The call session ID
+   * @returns {Promise<Object>} Session context with vxmlAttributes
+   */
+  async getSessionContext(callSid) {
+    const sessionInfo = await this.voiceChannel.getSessionForCallId(callSid);
+    
+    if (!sessionInfo) {
+      throw new Error(`[SessionService] No session found for callSid: ${callSid}`);
+    }
+
+    const { project_id, from, conversation_id, user } = sessionInfo;
+
+    const vxmlAttributes = {
+      TTS_VOICE_LANGUAGE: VOICE_LANGUAGE,
+      TTS_VOICE_NAME: VOICE_NAME,
+      callSid
+    };
+
+    return { sessionInfo, project_id, from, conversation_id, user, vxmlAttributes };
+  }
+
+  /**
+   * Clean up session data for a completed call.
+   * @param {string} callSid - The call session ID
+   * @param {string} conversationId - The conversation ID
+   */
+  async cleanupSession(callSid, conversationId) {
+    await this.voiceChannel.deleteCallKeys(callSid);
+    await this.tdChannel.clearQueue(conversationId);
+    // logger.debug(`[SessionService] Session cleaned up for callSid: ${callSid}`);
+  }
+}
+
+module.exports = { SessionService };

package/src/services/SpeechService.js

@@ -0,0 +1,134 @@
+const logger = require('../utils/logger');
+const { CHANNEL_NAME, VOICE_PROVIDER } = require('../utils/constants');
+
+/**
+ * Service responsible for Speech-to-Text operations.
+ * Encapsulates provider-specific logic for OpenAI and ElevenLabs.
+ */
+class SpeechService {
+  constructor({ aiService, voiceChannel }) {
+    if (!aiService) throw new Error('[SpeechService] aiService is required');
+    if (!voiceChannel) throw new Error('[SpeechService] voiceChannel is required');
+
+    this.aiService = aiService;
+    this.voiceChannel = voiceChannel;
+  }
+
+  /**
+   * Convert audio recording to text using configured provider.
+   * 
+   * @param {string} audioFileUrl - URL of the audio recording
+   * @param {string} callSid - The call session ID
+   * @param {Object} sessionInfo - Session information including integrations
+   * @param {Object} settings - Project settings
+   * @returns {Promise<Object|null>} Tiledesk message object or null if STT failed
+   */
+  async transcribeAudio(audioFileUrl, callSid, sessionInfo, settings) {
+    const attributes = await this.voiceChannel.getSettingsForCallId(callSid);
+    // logger.debug(`[SpeechService] Transcribing audio: ${audioFileUrl}, provider: ${attributes.VOICE_PROVIDER}`);
+
+    try {
+      const text = await this._performSTT(audioFileUrl, attributes, sessionInfo, settings);
+
+      if (!text) {
+        // logger.debug('[SpeechService] STT returned empty text');
+        return null;
+      }
+
+      return this._buildTextMessage(text, sessionInfo.from);
+
+    } catch (error) {
+      logger.error('[SpeechService] Transcription error:', error);
+      
+      if (error.code === 'QUOTA_EXCEEDED') {
+        return this._buildCloseMessage(sessionInfo.from, 'quota_exceeded');
+      }
+
+      return null;
+    }
+  }
+
+  /**
+   * Perform STT based on configured provider.
+   */
+  async _performSTT(audioFileUrl, attributes, sessionInfo, settings) {
+    const provider = attributes.VOICE_PROVIDER;
+
+    switch (provider) {
+      case VOICE_PROVIDER.OPENAI:
+        return this._transcribeWithOpenAI(audioFileUrl, attributes, sessionInfo, settings);
+
+      case VOICE_PROVIDER.ELEVENLABS:
+        return this._transcribeWithElevenLabs(audioFileUrl, attributes, sessionInfo);
+
+      default:
+        throw new Error(`[SpeechService] Unsupported provider: ${provider}`);
+    }
+  }
+
+  /**
+   * Transcribe audio using OpenAI Whisper.
+   */
+  async _transcribeWithOpenAI(audioFileUrl, attributes, sessionInfo, settings) {
+    const integration = sessionInfo.integrations.find(i => i.type === VOICE_PROVIDER.OPENAI);
+    const apiKey = integration?.key;
+    const isPublicKey = integration?.publicKey;
+
+    // Check quota for public keys
+    if (isPublicKey) {
+      const hasQuota = await this.aiService.checkQuoteAvailability(sessionInfo.project_id, settings.token);
+      // logger.debug(`[SpeechService] Quota check: ${hasQuota}`);
+
+      if (!hasQuota) {
+        const error = new Error('No quota available');
+        error.code = 'QUOTA_EXCEEDED';
+        throw error;
+      }
+    }
+
+    return this.aiService.speechToText(audioFileUrl, attributes.STT_MODEL, apiKey);
+  }
+
+  /**
+   * Transcribe audio using ElevenLabs.
+   */
+  async _transcribeWithElevenLabs(audioFileUrl, attributes, sessionInfo) {
+    const integration = sessionInfo.integrations.find(i => i.type === VOICE_PROVIDER.ELEVENLABS);
+    const apiKey = integration?.key;
+    const language = attributes.TTS_LANGUAGE || 'en';
+
+    return this.aiService.speechToTextElevenLabs(audioFileUrl, attributes.STT_MODEL, language, apiKey);
+  }
+
+  /**
+   * Build a standard text message.
+   */
+  _buildTextMessage(text, senderFullname) {
+    return {
+      text,
+      senderFullname,
+      type: 'text',
+      channel: { name: CHANNEL_NAME }
+    };
+  }
+
+  /**
+   * Build a close/event message.
+   */
+  _buildCloseMessage(senderFullname, event) {
+    return {
+      text: '/close',
+      senderFullname,
+      type: 'text',
+      channel: { name: CHANNEL_NAME },
+      attributes: {
+        subtype: 'info',
+        action: `close${JSON.stringify({ event })}`,
+        payload: { catchEvent: event },
+        timestamp: Date.now()
+      }
+    };
+  }
+}
+
+module.exports = { SpeechService };

package/src/services/TiledeskMessageBuilder.js

@@ -0,0 +1,135 @@
+const { CHANNEL_NAME } = require('../utils/constants');
+
+/**
+ * Factory for building Tiledesk message objects.
+ * Centralizes message construction to ensure consistency.
+ */
+class TiledeskMessageBuilder {
+  /**
+   * Build a start message for initiating a conversation.
+   * @param {string} from - Sender identifier
+   * @param {string} departmentId - Department ID
+   * @param {Object} payload - Additional payload data
+   * @returns {Object} Tiledesk message object
+   */
+  static buildStartMessage(from, departmentId, payload = {}) {
+    return {
+      text: '/start',
+      senderFullname: from,
+      type: 'text',
+      attributes: {
+        subtype: 'info',
+        payload
+      },
+      channel: { name: CHANNEL_NAME },
+      departmentid: departmentId
+    };
+  }
+
+  /**
+   * Build a standard text message.
+   * @param {string} text - Message text
+   * @param {string} from - Sender identifier
+   * @param {Object} attributes - Optional attributes
+   * @returns {Object} Tiledesk message object
+   */
+  static buildTextMessage(text, from, attributes = {}) {
+    return {
+      text,
+      senderFullname: from,
+      type: 'text',
+      channel: { name: CHANNEL_NAME },
+      attributes
+    };
+  }
+
+  /**
+   * Build an event message (e.g., no_input, close).
+   * @param {string} event - Event name
+   * @param {string} from - Sender identifier
+   * @param {Object} options - Event options
+   * @returns {Object} Tiledesk message object
+   */
+  static buildEventMessage(event, from, { action = '', payload = {} } = {}) {
+    return {
+      text: `/${event}`,
+      senderFullname: from,
+      type: 'text',
+      channel: { name: CHANNEL_NAME },
+      attributes: {
+        type: 'info',
+        action,
+        payload
+      }
+    };
+  }
+
+  /**
+   * Build a close message.
+   * @param {string} from - Sender identifier
+   * @param {string} event - The close event type
+   * @returns {Object} Tiledesk message object
+   */
+  static buildCloseMessage(from, event) {
+    return {
+      text: '/close',
+      senderFullname: from,
+      type: 'text',
+      channel: { name: CHANNEL_NAME },
+      attributes: {
+        subtype: 'info',
+        action: `close${JSON.stringify({ event })}`,
+        payload: { catchEvent: event },
+        timestamp: Date.now()
+      }
+    };
+  }
+
+  /**
+   * Build a transfer event message.
+   * @param {string} from - Sender identifier
+   * @param {string} event - Event name
+   * @param {Object} options - Transfer options
+   * @returns {Object} Tiledesk message object
+   */
+  static buildTransferMessage(from, event, { action, intentName, timestamp }) {
+    return {
+      text: `/${event}`,
+      senderFullname: from,
+      type: 'text',
+      channel: { name: CHANNEL_NAME },
+      attributes: {
+        subtype: 'info',
+        action,
+        payload: {
+          event,
+          lastBlock: intentName,
+          lastTimestamp: timestamp
+        }
+      }
+    };
+  }
+
+  /**
+   * Build a no-input fallback message.
+   * @param {string} from - Sender identifier
+   * @param {string} buttonAction - The fallback action
+   * @param {Object} payload - Event payload
+   * @returns {Object} Tiledesk message object
+   */
+  static buildNoInputMessage(from, buttonAction, payload = {}) {
+    return {
+      text: '/no_input',
+      senderFullname: from,
+      type: 'text',
+      channel: { name: CHANNEL_NAME },
+      attributes: {
+        type: 'info',
+        action: buttonAction,
+        payload
+      }
+    };
+  }
+}
+
+module.exports = { TiledeskMessageBuilder };

package/src/services/TwilioService.js

@@ -0,0 +1,129 @@
+const { twiml } = require('twilio');
+const logger = require('../utils/logger');
+
+/**
+ * Service responsible for Twilio API operations.
+ * Encapsulates call management and redirects.
+ */
+class TwilioService {
+  constructor({ db, config }) {
+    if (!db) throw new Error('[TwilioService] db is required');
+    if (!config) throw new Error('[TwilioService] config is required');
+
+    this.db = db;
+    this.config = config;
+    this._twilioClients = new Map(); // Cache clients per account
+  }
+
+  /**
+   * Get or create a Twilio client for the given credentials.
+   * @param {string} accountSid - Twilio account SID
+   * @param {string} authToken - Twilio auth token
+   * @returns {Object} Twilio client instance
+   */
+  _getClient(accountSid, authToken) {
+    if (!this._twilioClients.has(accountSid)) {
+      const twilio = require('twilio')(accountSid, authToken);
+      this._twilioClients.set(accountSid, twilio);
+    }
+    return this._twilioClients.get(accountSid);
+  }
+
+  /**
+   * Redirect an active call to a new URL.
+   * @param {string} callSid - The call SID to redirect
+   * @param {string} url - The URL to redirect to
+   * @param {Object} settings - Project settings containing Twilio credentials
+   * @returns {Promise<boolean>} True if redirect succeeded
+   */
+  async redirectCall(callSid, url, settings) {
+    try {
+      const client = this._getClient(settings.account_sid, settings.auth_token);
+      
+      await client.calls(callSid).update({
+        url,
+        method: 'POST'
+      });
+
+      // logger.debug(`[TwilioService] Call ${callSid} redirected to ${url}`);
+      return true;
+    } catch (error) {
+      logger.error(`[TwilioService] Error redirecting call ${callSid}:`, error);
+      return false;
+    }
+  }
+
+  /**
+   * Build a nextblock redirect URL with query parameters.
+   * @param {string} callSid - The call SID
+   * @param {string} intentName - The intent name
+   * @returns {string} The complete redirect URL
+   */
+  buildNextBlockUrl(callSid, intentName) {
+    const querystring = require('querystring');
+    const queryParams = `?intentName=${querystring.encode(intentName)}&previousIntentTimestamp=${Date.now()}`;
+    return `${this.config.BASE_URL}/nextblock/${callSid}${queryParams}`;
+  }
+
+  /**
+   * Handle play verb redirect logic.
+   * Redirects call to nextblock when a 'play' verb completes.
+   * @param {Object} tiledeskMessage - The Tiledesk message
+   * @param {string} projectId - The project ID
+   * @param {string} contentKey - The settings key
+   * @param {Object} lastCallSidVerb - Map of callSid to last verb
+   * @returns {Promise<boolean>} True if redirect was performed
+   */
+  async handlePlayRedirect(tiledeskMessage, projectId, contentKey, lastCallSidVerb) {
+    const flowAttrs = tiledeskMessage.attributes?.flowAttributes;
+    const callSid = flowAttrs?.CallSid;
+
+    if (!callSid || lastCallSidVerb[callSid] !== 'play_loop') {
+      return false;
+    }
+
+    const settings = await this.db.get(contentKey);
+    if (!settings) {
+      logger.warn(`[TwilioService] No settings found for ${contentKey}`);
+      return false;
+    }
+
+    const intentName = tiledeskMessage.attributes?.intentName || '';
+    const redirectUrl = this.buildNextBlockUrl(callSid, intentName);
+
+    return this.redirectCall(callSid, redirectUrl, settings);
+  }
+  
+  generateRedirectTwiML(callSid, intentName) {
+    const response = new twiml.VoiceResponse();
+    response.redirect({ method: 'POST' }, this.buildNextBlockUrl(callSid, intentName));
+    return response.toString();
+  }
+
+  /**
+   * Get call information.
+   * @param {string} callSid - The call SID
+   * @param {Object} settings - Project settings
+   * @returns {Promise<Object|null>} Call info or null
+   */
+  async getCallInfo(callSid, settings) {
+    try {
+      const client = this._getClient(settings.account_sid, settings.auth_token);
+      const call = await client.calls(callSid).fetch();
+      return call;
+    } catch (error) {
+      logger.error(`[TwilioService] Error fetching call ${callSid}:`, error);
+      return null;
+    }
+  }
+
+  /**
+   * Clear cached Twilio client for an account.
+   * @param {string} accountSid - The account SID to clear
+   */
+  clearClient(accountSid) {
+    this._twilioClients.delete(accountSid);
+  }
+}
+
+module.exports = { TwilioService };

package/src/services/UploadService.js

@@ -0,0 +1,78 @@
+const winston = require('../utils/logger');
+const axios = require("axios").default;
+const FormData = require('form-data');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { ServiceError } = require('../utils/errors');
+
+class UploadService {
+  
+  constructor(config) {
+    
+    if (!config) {
+      throw new Error("[UploadService] config is mandatory");
+    }
+    if (!config.API_URL) {
+      throw new Error("[UploadService] config.API_URL is mandatory");
+    }
+    
+    if (config.user) {
+      this.user = config.user
+    }
+
+    this.API_URL = config.API_URL;
+        
+  }
+  
+  async upload(id, file, user) {
+    // logger.debug(`[UploadService] upload for id ${id} and user ${user._id}`);
+
+    const tempFilePath = path.join(os.tmpdir(), `speech_${user._id}_${id}.wav`);
+    
+    try {
+      // Step 2: Save file locally (temporarily)
+      fs.writeFileSync(tempFilePath, file);
+
+      // Step 3: Upload file to server
+      const formData = new FormData();
+      formData.append('file', fs.createReadStream(tempFilePath), {
+        filename: `audiofile_${user._id}_${id}.wav`,
+        contentType: 'audio/mpeg'
+      });
+
+      const response = await axios({
+        url: this.API_URL + "/files/users",
+        headers: {
+          ...formData.getHeaders(),
+          "Authorization": user.token
+        },
+        data: formData,
+        method: 'POST'
+      });
+
+      if (response.data) {
+        let fileUrl = this.API_URL + "/files?path=" + response.data.filename;
+        return fileUrl;
+      } else {
+        throw new Error("No data in response");
+      }
+
+    } catch (err) {
+      winston.error('[UploadService] upload error', err);
+      throw new ServiceError('UPLOADSERVICE_FAILED', 'UploadService /files/users API failed with err:', err);
+    } finally {
+      // Step 4: Clean up temporary file
+      if (fs.existsSync(tempFilePath)) {
+        try {
+          fs.unlinkSync(tempFilePath);
+        } catch (e) {
+          winston.error("[UploadService] Error deleting temp file:", e);
+        }
+      }
+    }
+  }  
+  
+}
+
+module.exports = { UploadService };