@bliggy/chat-runtime 0.0.0-stage → 0.3.0

package/src/twilio.js

@@ -0,0 +1,176 @@
+'use strict';
+
+const crypto = require('crypto');
+const { EnvelopeValidationError } = require('./runtime');
+
+function loadTwilio(injected) {
+  if (injected) return injected;
+  return require('twilio');
+}
+
+function signatureFrom(context) {
+  const headers = context.headers || {};
+  const key = Object.keys(headers).find(name => name.toLowerCase() === 'x-twilio-signature');
+  return key ? headers[key] : null;
+}
+
+function addTurnKey(url, turnKey) {
+  const parsed = new URL(url);
+  parsed.searchParams.set('turnKey', turnKey);
+  return parsed.toString();
+}
+
+function nextVoiceTurnKey(turn) {
+  if (!turn?.id) throw new EnvelopeValidationError('Voice response requires a persisted turn');
+  return crypto.createHash('sha256').update(String(turn.id)).digest('hex').slice(0, 32);
+}
+
+function voiceInput(body) {
+  if (typeof body.SpeechResult === 'string') return body.SpeechResult;
+  if (typeof body.Digits === 'string') return body.Digits;
+  return '';
+}
+
+function createTwilioChannels({
+  authToken,
+  accountSid = null,
+  twilio: injectedTwilio = null,
+  client: injectedClient = null,
+  messagingServiceSid = null,
+  smsFrom = null,
+  voiceFrom = null,
+  voiceActionUrl = null,
+  voice = 'Polly.Joanna',
+  language = 'en-US',
+  gatherPrompt = 'How else can I help?'
+} = {}) {
+  if (typeof authToken !== 'string' || authToken === '') {
+    throw new TypeError('Twilio authToken is required');
+  }
+  const twilio = loadTwilio(injectedTwilio);
+
+  async function authenticate(envelope, context) {
+    const signature = signatureFrom(context);
+    const url = context.url;
+    if (!signature || typeof url !== 'string' || url === '') {
+      return { allowed: false, provider: 'twilio', reason: 'Missing Twilio signature context' };
+    }
+    const allowed = twilio.validateRequest(authToken, signature, url, context.params || {});
+    return {
+      allowed,
+      method: 'twilio-signature',
+      provider: 'twilio',
+      accountKey: envelope.providerAccountKey,
+      ...(allowed ? {} : { reason: 'Invalid Twilio signature' })
+    };
+  }
+
+  const sms = {
+    async normalize(payload) {
+      const mediaCount = Number.parseInt(payload?.NumMedia || '0', 10) || 0;
+      const attachments = Array.from({ length: mediaCount }, (_, index) => ({
+        url: payload[`MediaUrl${index}`],
+        contentType: payload[`MediaContentType${index}`] || null
+      }));
+      return {
+        channel: 'sms',
+        sourceKey: payload?.MessageSid || payload?.SmsSid || '',
+        threadKey: payload?.From && payload?.To ? `${payload.From}:${payload.To}` : '',
+        sender: payload?.From || null,
+        recipient: payload?.To || null,
+        text: payload?.Body || '',
+        attachments,
+        providerAccountKey: payload?.AccountSid || null,
+        metadata: {
+          messagingServiceSid: payload?.MessagingServiceSid || null,
+          numSegments: payload?.NumSegments || null
+        }
+      };
+    },
+    authenticate,
+    async format(output) {
+      const response = new twilio.twiml.MessagingResponse();
+      response.message(output.content || '');
+      return { contentType: 'text/xml', body: response.toString() };
+    }
+  };
+
+  const voiceChannel = {
+    async normalize(payload, context) {
+      const text = voiceInput(payload || {});
+      const turnKey = context.turnKey || payload?.EventSid || payload?.SequenceNumber;
+      if (text && !turnKey) {
+        throw new EnvelopeValidationError('Twilio Voice speech callbacks require a turnKey');
+      }
+      return {
+        channel: 'voice',
+        sourceKey: payload?.CallSid ? `${payload.CallSid}:${turnKey || 'initial'}` : '',
+        threadKey: payload?.CallSid || '',
+        sender: payload?.From || null,
+        recipient: payload?.To || null,
+        text,
+        attachments: [],
+        providerAccountKey: payload?.AccountSid || null,
+        metadata: {
+          callStatus: payload?.CallStatus || null,
+          confidence: payload?.Confidence ?? null
+        }
+      };
+    },
+    authenticate,
+    async format(output, { envelope, turn, context }) {
+      const response = new twilio.twiml.VoiceResponse();
+      if (output.content) response.say({ voice, language }, output.content);
+      if (output.endConversation) {
+        response.hangup();
+      } else {
+        const baseActionUrl = typeof voiceActionUrl === 'function'
+          ? await voiceActionUrl({ envelope, context })
+          : voiceActionUrl;
+        if (!baseActionUrl) throw new EnvelopeValidationError('voiceActionUrl is required');
+        const gather = response.gather({
+          input: 'speech dtmf',
+          action: addTurnKey(baseActionUrl, nextVoiceTurnKey(turn)),
+          method: 'POST',
+          actionOnEmptyResult: true,
+          speechTimeout: 'auto'
+        });
+        gather.say({ voice, language }, gatherPrompt);
+      }
+      return { contentType: 'text/xml', body: response.toString() };
+    }
+  };
+
+  function getClient() {
+    if (injectedClient) return injectedClient;
+    if (!accountSid) throw new TypeError('Twilio accountSid is required for outbound calls');
+    return twilio(accountSid, authToken);
+  }
+
+  async function sendSms({ to, body, from = smsFrom, statusCallback = null }) {
+    if (!to || !body) throw new TypeError('SMS to and body are required');
+    if (!from && !messagingServiceSid) {
+      throw new TypeError('smsFrom or messagingServiceSid is required');
+    }
+    return await getClient().messages.create({
+      to,
+      body,
+      ...(messagingServiceSid ? { messagingServiceSid } : { from }),
+      ...(statusCallback ? { statusCallback } : {})
+    });
+  }
+
+  async function startCall({ to, url, from = voiceFrom, statusCallback = null }) {
+    if (!to || !from || !url) throw new TypeError('Voice to, from, and url are required');
+    return await getClient().calls.create({
+      to,
+      from,
+      url,
+      ...(statusCallback ? { statusCallback } : {})
+    });
+  }
+
+  return { sms, voice: voiceChannel, sendSms, startCall };
+}
+
+module.exports = { createTwilioChannels };