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

package/src/services/translators/TiledeskTwilioTranslator.js

@@ -0,0 +1,509 @@
+/**
+ * TiledeskTwilioTranslator - Refactored Version
+ * 
+ * Uses Twilio's VoiceResponse for TwiML generation instead of manual XML.
+ * Benefits: Type safety, auto-validation, better error messages.
+ */
+
+const { twiml } = require('twilio');
+const querystring = require('querystring');
+
+const logger = require('../../utils/logger');
+const utils = require('../../utils/utils');
+const utilsMessage = require('../../utils/utils-message');
+
+const {
+  SETTING_MESSAGE,
+  WAIT_MESSAGE,
+  TEXT_MESSAGE,
+  VOICE_PROVIDER,
+  OPENAI_SETTINGS,
+  ELEVENLABS_SETTINGS,
+  TYPE_ACTION_VXML,
+  TYPE_MESSAGE,
+  INFO_MESSAGE_TYPE
+} = require('../../utils/constants');
+
+const voiceEventEmitter = require('../voiceEventEmitter');
+const { SttError } = require('../../utils/errors');
+
+class TiledeskTwilioTranslator {
+  constructor(config) {
+    if (!config.BASE_URL) {
+      throw new Error('[TiledeskTwilioTranslator] config.BASE_URL is mandatory');
+    }
+    
+    this.BASE_URL = config.BASE_URL;
+    this.aiService = config.aiService;
+    this.uploadService = config.uploadService;
+    this.lastCallSidVerb = {};
+    this.voiceProvider = VOICE_PROVIDER.TWILIO;
+  }
+
+  /**
+   * Main entry point: Convert Tiledesk message to TwiML
+   */
+  async toVXML(msg, id, vxmlAttributes, sessionInfo) {
+    vxmlAttributes.intentName = msg.attributes?.intentName || '';
+    vxmlAttributes = this._processVoiceAttributes(msg, vxmlAttributes);
+
+    // Handle close/hangup
+    if (this._shouldHangup(msg)) {
+      return this._createHangupResponse();
+    }
+
+    const commands = msg.attributes?.commands;
+    if (!commands?.length) {
+      return this._createEmptyResponse();
+    }
+
+    // Set VXML attributes from commands
+    this._setAttributesFromCommands(commands, vxmlAttributes);
+
+    // Route to appropriate converter based on message type
+    return this._routeToConverter(msg, vxmlAttributes, sessionInfo);
+  }
+
+  /**
+   * Route message to the appropriate TwiML converter
+   */
+  async _routeToConverter(msg, vxmlAttributes, sessionInfo) {
+    const converters = [
+      { check: () => this._isWaitMessage(msg), convert: () => this._convertDelay(msg, vxmlAttributes, sessionInfo) },
+      { check: () => this._hasSubType(msg, TYPE_ACTION_VXML.DTMF_FORM), convert: () => this._convertDtmfForm(msg, vxmlAttributes, sessionInfo) },
+      { check: () => this._hasSubType(msg, TYPE_ACTION_VXML.BLIND_TRANSFER), convert: () => this._convertBlindTransfer(msg, vxmlAttributes, sessionInfo) },
+      { check: () => this._hasSubType(msg, TYPE_ACTION_VXML.DTMF_MENU), convert: () => this._convertMenu(msg, vxmlAttributes, sessionInfo) },
+      { check: () => this._hasSubType(msg, TYPE_ACTION_VXML.SPEECH_FORM), convert: () => this._convertSpeechForm(msg, vxmlAttributes, sessionInfo) },
+    ];
+
+    for (const { check, convert } of converters) {
+      if (check()) {
+        return convert();
+      }
+    }
+
+    // Default: Play prompt
+    return this._convertPlayPrompt(msg, vxmlAttributes, sessionInfo);
+  }
+
+  // ==================== Message Type Checks ====================
+
+  _shouldHangup(msg) {
+    const isInfoSupport = utilsMessage.messageType(TYPE_MESSAGE.INFO_SUPPORT, msg);
+    return isInfoSupport && utilsMessage.infoMessageType(msg) === INFO_MESSAGE_TYPE.CHAT_CLOSED;
+  }
+
+  _hasSubType(msg, subType) {
+    const settings = msg.attributes?.commands?.find(cmd => cmd.type === SETTING_MESSAGE);
+    return settings?.subType === subType;
+  }
+
+  _isWaitMessage(msg) {
+    const commands = msg.attributes?.commands;
+    if (!commands) return false;
+    const hasWait = commands.some(cmd => cmd.type === WAIT_MESSAGE);
+    const hasMessage = commands.some(cmd => cmd.type === TEXT_MESSAGE);
+    return hasWait && !hasMessage;
+  }
+
+  // ==================== Voice Attributes Management ====================
+
+  _processVoiceAttributes(msg, vxmlAttributes) {
+    const flowAttrs = msg.attributes?.flowAttributes;
+    if (!flowAttrs) {
+      voiceEventEmitter.emit('saveSettings', vxmlAttributes);
+      return vxmlAttributes;
+    }
+
+    // Copy flow attributes to vxml attributes
+    Object.keys(vxmlAttributes).forEach(key => {
+      if (flowAttrs[key]) {
+        vxmlAttributes[key] = flowAttrs[key];
+      }
+    });
+
+    // Set voice provider with defaults
+    this.voiceProvider = flowAttrs.VOICE_PROVIDER || VOICE_PROVIDER.TWILIO;
+    vxmlAttributes.VOICE_PROVIDER = this.voiceProvider;
+
+    // Apply provider-specific defaults
+    this._applyProviderDefaults(vxmlAttributes, flowAttrs);
+
+    logger.debug('[TiledeskTwilioTranslator] Processed vxmlAttributes:', vxmlAttributes);
+    voiceEventEmitter.emit('saveSettings', vxmlAttributes);
+
+    return vxmlAttributes;
+  }
+
+  _applyProviderDefaults(attrs, flowAttrs) {
+    const providerDefaults = {
+      [VOICE_PROVIDER.OPENAI]: OPENAI_SETTINGS,
+      [VOICE_PROVIDER.ELEVENLABS]: ELEVENLABS_SETTINGS
+    };
+
+    const defaults = providerDefaults[this.voiceProvider];
+    if (!defaults) return;
+
+    attrs.TTS_VOICE_NAME = flowAttrs.TTS_VOICE_NAME || defaults.TTS_VOICE_NAME;
+    attrs.TTS_MODEL = flowAttrs.TTS_MODEL || defaults.TTS_MODEL;
+    attrs.STT_MODEL = flowAttrs.STT_MODEL || defaults.STT_MODEL;
+
+    if (this.voiceProvider === VOICE_PROVIDER.ELEVENLABS) {
+      attrs.TTS_VOICE_LANGUAGE = flowAttrs.TTS_VOICE_LANGUAGE || defaults.TTS_VOICE_LANGUAGE;
+    }
+  }
+
+  _setAttributesFromCommands(commands, attributes) {
+    const settingsCommand = commands.slice(-1)[0];
+    if (settingsCommand?.settings) {
+      Object.assign(attributes, settingsCommand.settings);
+    }
+  }
+
+  // ==================== TwiML Converters ====================
+
+  _createHangupResponse() {
+    const response = new twiml.VoiceResponse();
+    response.hangup();
+    return response.toString();
+  }
+
+  _createEmptyResponse() {
+    const response = new twiml.VoiceResponse();
+    return response.toString();
+  }
+
+  async _convertDelay(msg, attrs, sessionInfo) {
+    const response = new twiml.VoiceResponse();
+    await this._addPromptElements(response, msg, attrs, sessionInfo);
+    response.redirect({ method: 'POST' }, `${this.BASE_URL}/nextblock/${attrs.callSid}`);
+    return response.toString();
+  }
+
+  async _convertPlayPrompt(msg, attrs, sessionInfo) {
+    const response = new twiml.VoiceResponse();
+    const settings = msg.attributes?.commands?.find(cmd => cmd.type === SETTING_MESSAGE)?.settings;
+    const bargeIn = settings?.bargein === true;
+
+    if (bargeIn) {
+      // Wrap prompt in Gather to capture user input when barge-in occurs
+      const intentQuery = this._buildIntentQuery(attrs);
+      const bargeInInput = 'speech dtmf'; // Default to both
+      const noInputNoMatch = this._getNoInputNoMatchActions(msg);
+      const supportsSpeech = bargeInInput.includes('speech');
+
+      const gatherOptions = {
+        input: bargeInInput,
+        action: `${this.BASE_URL}/nextBlock/${attrs.callSid}?${intentQuery}&bargein=true`,
+        method: 'POST',
+        language: attrs.TTS_VOICE_LANGUAGE
+      };
+
+      // Apply speech-specific options only if speech is enabled
+      if (supportsSpeech) {
+        gatherOptions.speechTimeout = 'auto';
+        gatherOptions.enhanced = true;
+        if (attrs.incompleteSpeechTimeout) {
+          gatherOptions.speechTimeout = Math.round(attrs.incompleteSpeechTimeout / 1000);
+        }
+      }
+
+      // Apply timeout if specified (for DTMF or as fallback)
+      if (attrs.noInputTimeout) {
+        gatherOptions.timeout = Math.round(attrs.noInputTimeout / 1000);
+      }
+
+      const gather = response.gather(gatherOptions);
+      await this._addPromptElements(gather, msg, attrs, sessionInfo, true); // Pass bargeIn flag
+
+      // Handle no input/no match scenarios
+      if (noInputNoMatch?.queryNoInput) {
+        response.redirect({ method: 'POST' }, 
+          `${this.BASE_URL}/handle/${attrs.callSid}/no_input?${noInputNoMatch.queryNoInput}`);
+      }
+    } else {
+      // No barge-in: simple play prompt
+      await this._addPromptElements(response, msg, attrs, sessionInfo, false);
+      response.redirect({ method: 'POST' }, `${this.BASE_URL}/nextblock/${attrs.callSid}`);
+    }
+
+    return response.toString();
+  }
+
+  async _convertSpeechForm(msg, attrs, sessionInfo) {
+    const response = new twiml.VoiceResponse();
+    const intentQuery = this._buildIntentQuery(attrs);
+    const noInputNoMatch = this._getNoInputNoMatchActions(msg);
+
+    if (this.voiceProvider === VOICE_PROVIDER.TWILIO) {
+      const gatherOptions = {
+        input: 'speech',
+        action: `${this.BASE_URL}/nextBlock/${attrs.callSid}?${intentQuery}`,
+        method: 'POST',
+        language: attrs.TTS_VOICE_LANGUAGE,
+        speechTimeout: 'auto',
+        enhanced: true
+      };
+
+      if (attrs.incompleteSpeechTimeout) {
+        gatherOptions.speechTimeout = Math.round(attrs.incompleteSpeechTimeout / 1000);
+      }
+
+      const gather = response.gather(gatherOptions);
+      await this._addPromptElements(gather, msg, attrs, sessionInfo);
+
+      if (noInputNoMatch?.queryNoInput) {
+        response.redirect({ method: 'POST' }, 
+          `${this.BASE_URL}/handle/${attrs.callSid}/no_input?${noInputNoMatch.queryNoInput}`);
+      }
+    } else {
+      // OpenAI/ElevenLabs: Use Record
+      await this._addPromptElements(response, msg, attrs, sessionInfo);
+
+      let queryUrl = intentQuery;
+      if (noInputNoMatch?.queryNoInput) {
+        queryUrl += `&${noInputNoMatch.queryNoInput}`;
+      }
+
+      response.record({
+        action: `${this.BASE_URL}/record/action/${attrs.callSid}?${queryUrl}`,
+        method: 'POST',
+        playBeep: false,
+        trim: 'trim-silence',
+        timeout: 2,
+        recordingStatusCallback: `${this.BASE_URL}/record/callback/${attrs.callSid}?${queryUrl}`,
+        recordingStatusCallbackMethod: 'POST'
+      });
+    }
+
+    return response.toString();
+  }
+
+  async _convertMenu(msg, attrs, sessionInfo) {
+    const response = new twiml.VoiceResponse();
+    const options = this._getButtonsFromMessage(msg);
+    const menuOptions = options.map(o => `${o.value}:${o.action.substring(1)}`).join(';') + ';';
+    const noInputNoMatch = this._getNoInputNoMatchActions(msg);
+
+    let queryUrl = `${this._buildIntentQuery(attrs)}&menu_options=${menuOptions}`;
+    if (noInputNoMatch?.queryNoMatch) {
+      queryUrl += `&${noInputNoMatch.queryNoMatch}`;
+    }
+
+    const gather = response.gather({
+      input: 'dtmf',
+      timeout: Math.round(attrs.noInputTimeout / 1000),
+      numDigits: 1,
+      action: `${this.BASE_URL}/menublock/${attrs.callSid}?${queryUrl}`,
+      method: 'POST',
+      language: attrs.TTS_VOICE_LANGUAGE
+    });
+
+    await this._addPromptElements(gather, msg, attrs, sessionInfo);
+
+    if (noInputNoMatch?.queryNoInput) {
+      response.redirect({}, 
+        `${this.BASE_URL}/handle/${attrs.callSid}/no_input?${noInputNoMatch.queryNoInput}`);
+    }
+
+    return response.toString();
+  }
+
+  async _convertDtmfForm(msg, attrs, sessionInfo) {
+    const response = new twiml.VoiceResponse();
+    const noInputNoMatch = this._getNoInputNoMatchActions(msg);
+    const intentQuery = this._buildIntentQuery(attrs);
+
+    const gatherOptions = {
+      input: 'dtmf',
+      timeout: Math.round(attrs.noInputTimeout / 1000),
+      action: `${this.BASE_URL}/menublock/${attrs.callSid}?${intentQuery}`,
+      method: 'POST',
+      language: attrs.TTS_VOICE_LANGUAGE
+    };
+
+    // Apply DTMF-specific settings
+    this._applyDtmfSettings(msg, gatherOptions, attrs);
+
+    const gather = response.gather(gatherOptions);
+    await this._addPromptElements(gather, msg, attrs, sessionInfo);
+
+    if (noInputNoMatch?.queryNoInput) {
+      response.redirect({ method: 'POST' }, 
+        `${this.BASE_URL}/handle/${attrs.callSid}/no_input?${noInputNoMatch.queryNoInput}`);
+    }
+
+    return response.toString();
+  }
+
+  async _convertBlindTransfer(msg, attrs, sessionInfo) {
+    const response = new twiml.VoiceResponse();
+    await this._addPromptElements(response, msg, attrs, sessionInfo);
+
+    const lastCommand = msg.attributes.commands.slice(-1)[0];
+    const settings = lastCommand?.settings;
+
+    if (!settings?.transferTo) {
+      return response.toString();
+    }
+
+    const dial = response.dial();
+    let queryUrl = this._buildIntentQuery(attrs);
+
+    if (settings.trueIntent) {
+      queryUrl += `&button_success=${settings.trueIntent.substring(1)}`;
+    }
+    if (settings.falseIntent) {
+      queryUrl += `&button_failure=${settings.falseIntent.substring(1)}`;
+    }
+
+    const isPhoneNumber = /^.*\d.*$/.test(settings.transferTo);
+    if (isPhoneNumber) {
+      dial.number({
+        statusCallbackEvent: 'initiated ringing answered completed',
+        statusCallback: `${this.BASE_URL}/event/${attrs.callSid}/transfer?${queryUrl}`,
+        statusCallbackMethod: 'POST'
+      }, settings.transferTo);
+    } else {
+      dial.sip({}, `sip:${settings.transferTo}${attrs.uriTransferParameters || ''}`);
+    }
+
+    return response.toString();
+  }
+
+  // ==================== Prompt Elements ====================
+
+  async _addPromptElements(element, msg, attrs, sessionInfo, bargeIn = false) {
+    const commands = msg.attributes?.commands || [];
+
+    for (const command of commands) {
+      if (command.type === 'message') {
+        await this._addMessageElement(element, command, attrs, sessionInfo, bargeIn);
+      } else if (command.type === 'wait' && command.time > 0) {
+        element.pause({ length: command.time / 1000 });
+        this.lastCallSidVerb[attrs.callSid] = 'pause';
+      }
+    }
+  }
+
+  async _addMessageElement(element, command, attrs, sessionInfo, bargeIn = false) {
+    const { message } = command;
+    
+    if (message.type === 'text') {
+      const text = utils.markdownToTwilioSpeech(message.text);
+      
+      if (this.voiceProvider !== VOICE_PROVIDER.TWILIO) {
+        const audioUrl = await this._generateTTS(text, attrs, sessionInfo);
+        if (audioUrl) {
+          const playOptions = {};
+          if (bargeIn) {
+            playOptions.bargeIn = true;
+          }
+          element.play(playOptions, audioUrl);
+        }
+      } else {
+        const sayOptions = { voice: attrs.TTS_VOICE_NAME, language: attrs.TTS_VOICE_LANGUAGE };
+        if (bargeIn) {
+          sayOptions.bargeIn = true;
+        }
+        element.say(sayOptions, text);
+        this.lastCallSidVerb[attrs.callSid] = 'say';
+      }
+    } else if (message.type === 'frame' && message.metadata?.src) {
+
+      const playOptions = { loop: 0 };
+      if (bargeIn) {
+        playOptions.bargeIn = true;
+      }
+      element.play(playOptions, message.metadata.src);
+      this.lastCallSidVerb[attrs.callSid] = 'play';
+    }
+  }
+
+  // ==================== TTS Generation ====================
+
+  async _generateTTS(text, attrs, sessionInfo) {
+    try {
+      const audioData = await this._callTTSProvider(text, attrs, sessionInfo);
+      
+      if (!audioData) {
+        throw new SttError('TTS_FAILED', 'TTS returned no audio data');
+      }
+
+      const fileUrl = await this.uploadService.upload(attrs.callSid, audioData, sessionInfo.user);
+      logger.debug('[TiledeskTwilioTranslator] TTS audio URL:', fileUrl);
+      return fileUrl;
+    } catch (error) {
+      logger.error('[TiledeskTwilioTranslator] TTS generation error:', error);
+      return null;
+    }
+  }
+
+  async _callTTSProvider(text, attrs, sessionInfo) {
+    const providers = {
+      [VOICE_PROVIDER.OPENAI]: () => {
+        const key = sessionInfo.integrations.find(i => i.type === VOICE_PROVIDER.OPENAI)?.key;
+        return this.aiService.textToSpeech(text, attrs.TTS_VOICE_NAME, attrs.TTS_MODEL, key);
+      },
+      [VOICE_PROVIDER.ELEVENLABS]: () => {
+        const key = sessionInfo.integrations.find(i => i.type === VOICE_PROVIDER.ELEVENLABS)?.key;
+        return this.aiService.textToSpeechElevenLabs(
+          text, attrs.TTS_VOICE_NAME, attrs.TTS_MODEL, attrs.TTS_VOICE_LANGUAGE, key
+        );
+      }
+    };
+
+    const provider = providers[this.voiceProvider];
+    if (!provider) {
+      throw new SttError('TTS_FAILED', `Unsupported voice provider: ${this.voiceProvider}`);
+    }
+
+    return provider();
+  }
+
+  // ==================== Helpers ====================
+
+  _buildIntentQuery(attrs) {
+    return `intentName=${querystring.encode(attrs.intentName)}&previousIntentTimestamp=${Date.now()}`;
+  }
+
+  _getNoInputNoMatchActions(msg) {
+    const settings = msg.attributes?.commands?.find(cmd => cmd.type === SETTING_MESSAGE)?.settings;
+    if (!settings) return null;
+
+    const { noInputIntent, noMatchIntent } = settings;
+    return {
+      queryNoInput: noInputIntent ? `button_action=${noInputIntent.substring(1)}` : '',
+      queryNoMatch: noMatchIntent ? `button_action=${noMatchIntent.substring(1)}` : ''
+    };
+  }
+
+  _getButtonsFromMessage(msg) {
+    const command = msg.attributes?.commands?.find(cmd => 
+      cmd.type === 'message' && cmd.message?.attributes?.attachment?.buttons
+    );
+    const buttons = command?.message?.attributes?.attachment?.buttons || [];
+    return buttons.filter(b => b.type === 'action');
+  }
+
+  _applyDtmfSettings(msg, gatherOptions, attrs) {
+    const settings = msg.attributes?.commands?.find(cmd => cmd.type === SETTING_MESSAGE)?.settings;
+    if (!settings) return;
+
+    if (settings.maxDigits) {
+      gatherOptions.numDigits = settings.maxDigits;
+      attrs.maxDigits = settings.maxDigits;
+    }
+    if (settings.terminators) {
+      gatherOptions.finishOnKey = settings.terminators;
+      attrs.terminators = settings.terminators;
+    }
+  }
+
+  // Legacy method for backwards compatibility
+  toTiledesk(vxmlMessage) {
+    logger.debug('[TiledeskTwilioTranslator] toTiledesk:', vxmlMessage);
+  }
+}
+
+module.exports = { TiledeskTwilioTranslator };