flow_chat 0.8.2 → 0.10.0

data/lib/flow_chat/simulator/controller.rb

@@ -54,6 +54,32 @@ module FlowChat
               contact_name: default_contact_name
             }
           },
+          messenger: {
+            name: "Messenger (Send API)",
+            description: "Facebook Messenger integration using the Send API",
+            processor_type: "messenger",
+            gateway: "send_api",
+            endpoint: "/messenger/webhook",
+            icon: "💬",
+            color: "#0084FF",
+            settings: {
+              user_id: default_phone_number,
+              contact_name: default_contact_name
+            }
+          },
+          instagram: {
+            name: "Instagram (Send API)",
+            description: "Instagram DM integration using the Send API",
+            processor_type: "instagram",
+            gateway: "send_api",
+            endpoint: "/instagram/webhook",
+            icon: "📷",
+            color: "#E1306C",
+            settings: {
+              user_id: default_phone_number,
+              contact_name: default_contact_name
+            }
+          },
           http: {
             name: "HTTP API",
             description: "HTTP integration with JSON request/response",
@@ -88,24 +114,14 @@ module FlowChat
       end
 
       def set_simulator_cookie
-        # Get global simulator secret
-        simulator_secret = FlowChat::Config.simulator_secret
-
-        unless simulator_secret && !simulator_secret.empty?
+        if FlowChat::Config.simulator_secret.blank?
           raise StandardError, "Simulator secret not configured. Please set FlowChat::Config.simulator_secret to enable simulator mode."
         end
 
-        # Generate timestamp-based signed cookie
-        timestamp = Time.now.to_i
-        message = "simulator:#{timestamp}"
-        signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), simulator_secret, message)
-
-        cookie_value = "#{timestamp}:#{signature}"
-
-        # Set secure cookie (valid for 24 hours)
-        cookies[:flowchat_simulator] = {
-          value: cookie_value,
-          expires: 24.hours.from_now,
+        # Set secure cookie (valid for as long as the gateways will accept it)
+        cookies[FlowChat::Security::SIMULATOR_COOKIE_NAME] = {
+          value: FlowChat::Security.simulator_cookie,
+          expires: FlowChat::Security::SIMULATOR_COOKIE_TTL.seconds.from_now,
           secure: request.ssl?, # Only send over HTTPS in production
           httponly: true,       # Prevent XSS access
           same_site: :lax      # CSRF protection while allowing normal navigation

data/lib/flow_chat/simulator/views/simulator.html.erb

@@ -1019,6 +1019,14 @@
       // Configuration Data
       const configurations = <%= configurations.to_json.html_safe %>;
 
+      // Platforms that render as chat bubbles, sharing the WhatsApp screen
+      // chrome rather than each growing its own copy of it.
+      const CHAT_PLATFORMS = ['whatsapp', 'messenger', 'instagram']
+
+      function isChatPlatform(processorType) {
+        return CHAT_PLATFORMS.includes(processorType)
+      }
+
       // DOM Elements
       const elements = {
         configSelect: document.getElementById('config-select'),
@@ -1106,7 +1114,7 @@
       }
 
       function updateUserSettings() {
-        if (state.currentConfig && state.currentConfig.processor_type === 'whatsapp') {
+        if (state.currentConfig && isChatPlatform(state.currentConfig.processor_type)) {
           updateContactInfo()
         }
       }
@@ -1127,19 +1135,20 @@
         if (!state.currentConfig) return
         
         const processorType = state.currentConfig.processor_type
-        const isWhatsApp = processorType === 'whatsapp'
+        const isChat = isChatPlatform(processorType)
         const isHttp = processorType === 'http'
-        
-        // Show/hide platform-specific elements
-        elements.contactNameGroup.style.display = isWhatsApp ? 'block' : 'none'
-        elements.ussdScreen.classList.toggle('hidden', isWhatsApp || isHttp)
-        elements.whatsappScreen.classList.toggle('hidden', !isWhatsApp)
+
+        // Show/hide platform-specific elements. The chat screen is shared by
+        // every chat platform rather than each growing its own copy of it.
+        elements.contactNameGroup.style.display = isChat ? 'block' : 'none'
+        elements.ussdScreen.classList.toggle('hidden', isChat || isHttp)
+        elements.whatsappScreen.classList.toggle('hidden', !isChat)
         elements.httpScreen.classList.toggle('hidden', !isHttp)
-        
+
         // Update input placeholder
         let placeholder = 'Enter USSD input...'
-        if (isWhatsApp) {
-          placeholder = 'Type your WhatsApp message...'
+        if (isChat) {
+          placeholder = `Type your ${state.currentConfig.name} message...`
         } else if (isHttp) {
           placeholder = 'Type your HTTP message...'
         }
@@ -1186,12 +1195,12 @@
           
           if (state.currentConfig.processor_type === 'ussd') {
             await makeUSSDRequest()
-          } else if (state.currentConfig.processor_type === 'whatsapp') {
-            await makeWhatsAppRequest()
+          } else if (isChatPlatform(state.currentConfig.processor_type)) {
+            await makeChatPlatformRequest()
           } else if (state.currentConfig.processor_type === 'http') {
             await makeHTTPRequest()
           }
-          
+
           updateStatus('Connected', 'connected')
           
         } catch (error) {
@@ -1209,19 +1218,19 @@
           updateStatus('Sending...', 'connecting')
           
           // Add outgoing message to appropriate chat
-          if (state.currentConfig.processor_type === 'whatsapp') {
+          if (isChatPlatform(state.currentConfig.processor_type)) {
             addMessage(message, true)
           } else if (state.currentConfig.processor_type === 'http') {
             addHttpMessage(message, true)
           }
-          
+
           elements.messageInput.value = ''
           updateCharCount()
-          
+
           if (state.currentConfig.processor_type === 'ussd') {
             await makeUSSDRequest(message)
-          } else if (state.currentConfig.processor_type === 'whatsapp') {
-            await makeWhatsAppRequest(message)
+          } else if (isChatPlatform(state.currentConfig.processor_type)) {
+            await makeChatPlatformRequest(message)
           } else if (state.currentConfig.processor_type === 'http') {
             await makeHTTPRequest(message)
           }
@@ -1565,6 +1574,131 @@
         }
       }
 
+      // Dispatches to the request builder for whichever chat platform is
+      // selected. WhatsApp keeps its own Cloud API envelope; Messenger and
+      // Instagram share the Messenger Platform envelope instead.
+      async function makeChatPlatformRequest(userInput = null) {
+        if (state.currentConfig.processor_type === 'whatsapp') {
+          await makeWhatsAppRequest(userInput)
+        } else {
+          await makeMessagingRequest(userInput)
+        }
+      }
+
+      // Messenger and Instagram request handler: builds the entry[].messaging[]
+      // envelope both gateways parse, with simulator_mode enabled.
+      async function makeMessagingRequest(userInput = null) {
+        const config = state.currentConfig
+        const userId = elements.phoneNumber.value
+
+        let isInitialMessage = false
+        if (userInput === null) {
+          userInput = 'hi'
+          isInitialMessage = true
+        }
+
+        if (isInitialMessage) {
+          addMessage(userInput, true)
+        }
+
+        const webhookData = {
+          object: config.processor_type === 'instagram' ? 'instagram' : 'page',
+          entry: [{
+            id: config.settings.page_id || 'page_1',
+            messaging: [{
+              sender: {id: userId},
+              recipient: {id: config.settings.page_id || 'page_1'},
+              timestamp: Date.now(),
+              message: {mid: 'mid.' + Date.now(), text: userInput}
+            }]
+          }],
+          simulator_mode: true
+        }
+
+        try {
+          const response = await fetch(config.endpoint, {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify(webhookData),
+            credentials: 'include'
+          })
+
+          const responseText = await response.text()
+          let responseData = null
+
+          if (response.headers.get('content-type')?.includes('application/json')) {
+            try {
+              responseData = JSON.parse(responseText)
+
+              if (responseData.mode === 'simulator') {
+                displaySimulatorResponse(responseData)
+                addRequestLog('POST', config.endpoint, webhookData, responseData, response.status)
+                return
+              }
+            } catch (jsonError) {
+              console.warn('Failed to parse JSON response:', jsonError)
+              console.warn('Response text:', responseText)
+              responseData = responseText
+            }
+          } else {
+            responseData = responseText
+          }
+
+          addRequestLog('POST', config.endpoint, webhookData, responseData, response.status)
+
+          if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`)
+          }
+
+          setTimeout(() => {
+            addInfoMessage(
+              `✅ Webhook delivered successfully (${response.status})\n\n` +
+              `📱 In a real ${config.name} integration:\n` +
+              `• Your endpoint processes this webhook\n` +
+              `• Response messages are sent via the Send API\n` +
+              `• Messages appear in the actual ${config.name} chat\n\n` +
+              `💡 This simulator shows the webhook delivery only.\n` +
+              `To enable full simulator mode, configure your endpoint\n` +
+              `to handle simulator_mode parameter and return JSON responses.`
+            )
+          }, 500)
+        } catch (error) {
+          addRequestLog('POST', config.endpoint, webhookData, null, 0, error.message)
+
+          let errorMessage = error.message
+          if (error.message.includes('Failed to fetch')) {
+            errorMessage = 'Cannot connect to endpoint. Please check:\n' +
+                          '• Endpoint URL is correct\n' +
+                          '• Server is running\n' +
+                          '• CORS is configured if cross-origin\n' +
+                          '• SSL certificate is valid (for HTTPS)'
+          } else if (error.message.includes('404')) {
+            errorMessage = 'Endpoint not found (404). Please verify:\n' +
+                          '• The webhook URL is correct\n' +
+                          '• The route is properly configured\n' +
+                          '• The controller/handler exists'
+          } else if (error.message.includes('500')) {
+            errorMessage = 'Server error (500). Check server logs for:\n' +
+                          '• Application errors\n' +
+                          '• Missing dependencies\n' +
+                          '• Configuration issues'
+          }
+
+          setTimeout(() => {
+            addInfoMessage(
+              `❌ Request Failed\n\n` +
+              `Error: ${errorMessage}\n\n` +
+              `💡 For simulator mode support, ensure your endpoint:\n` +
+              `• Accepts POST requests with simulator_mode parameter\n` +
+              `• Returns JSON with mode: "simulator" for simulator requests\n` +
+              `• Handles webhook verification (if required by your setup)`
+            )
+          }, 500)
+
+          throw error
+        }
+      }
+
       // HTTP API request handler
       async function makeHTTPRequest(userInput = null) {
         const config = state.currentConfig
@@ -1640,15 +1774,45 @@
         updateCharCount()
       }
 
+      // Renders a Messenger/Instagram [type, content, options] tuple as a chat
+      // bubble, with quick replies and carousel buttons tappable the same way
+      // a WhatsApp interactive button is.
+      function displayMessagingPlatformResponse(messagePayload) {
+        const [type, content, options] = messagePayload
+        let interactive = null
+
+        if (type === 'quick_replies' && options && options.quick_replies) {
+          interactive = {
+            buttons: options.quick_replies.map(reply => ({id: reply.payload, title: reply.title}))
+          }
+        } else if (type === 'carousel' && options && options.elements) {
+          interactive = {
+            buttons: options.elements.flatMap(element =>
+              (element.buttons || []).map(button => ({id: button.payload, title: button.title}))
+            )
+          }
+        }
+
+        addMessage(content, false, type, interactive, null)
+      }
+
       function displaySimulatorResponse(simulatorData) {
         const messagePayload = simulatorData.would_send
+
+        // Messenger and Instagram render [type, content, options], not the
+        // WhatsApp Cloud API envelope this function otherwise expects.
+        if (Array.isArray(messagePayload)) {
+          displayMessagingPlatformResponse(messagePayload)
+          return
+        }
+
         const messageInfo = simulatorData.message_info
-        
+
         // Extract message content based on type
         let messageText = ''
         let interactive = null
         let mediaContent = null
-        
+
         switch (messagePayload.type) {
           case 'text':
             messageText = messagePayload.text.body

data/lib/flow_chat/telegram/client.rb

@@ -0,0 +1,283 @@
+require "net/http"
+require "json"
+require "uri"
+
+module FlowChat
+  module Telegram
+    class Client
+      include FlowChat::Instrumentation
+
+      def initialize(config)
+        @config = config
+        FlowChat.logger.info { "Telegram::Client: Initialized Telegram client" }
+      end
+
+      # Main send_message method matching FlowChat pattern
+      def send_message(chat_id, prompt, choices: nil, media: nil)
+        FlowChat.logger.info { "Telegram::Client: Sending message to chat #{chat_id}" }
+
+        response = FlowChat::Telegram::Renderer.new(prompt, choices: choices, media: media).render
+        type, content, options = response
+
+        case type
+        when :text
+          send_text(chat_id, content)
+        when :inline_keyboard
+          send_text_with_keyboard(chat_id, content, options[:keyboard])
+        when :photo
+          send_photo(chat_id, options[:url], caption: content)
+        when :photo_with_keyboard
+          send_photo_with_keyboard(chat_id, options[:url], caption: content, keyboard: options[:keyboard])
+        when :document
+          send_document(chat_id, options[:url], caption: content)
+        when :video
+          send_video(chat_id, options[:url], caption: content)
+        when :audio
+          send_audio(chat_id, options[:url], caption: content)
+        when :voice
+          send_voice(chat_id, options[:url])
+        else
+          send_text(chat_id, content.to_s)
+        end
+      end
+
+      def send_text(chat_id, text, parse_mode: "HTML")
+        api_request("sendMessage", {
+          chat_id: chat_id,
+          text: text,
+          parse_mode: parse_mode
+        }.compact)
+      end
+
+      def send_text_with_keyboard(chat_id, text, keyboard, parse_mode: "HTML")
+        api_request("sendMessage", {
+          chat_id: chat_id,
+          text: text,
+          parse_mode: parse_mode,
+          reply_markup: {inline_keyboard: keyboard}
+        }.compact)
+      end
+
+      def send_photo(chat_id, photo_url_or_id, caption: nil)
+        api_request("sendPhoto", {
+          chat_id: chat_id,
+          photo: photo_url_or_id,
+          caption: caption
+        }.compact)
+      end
+
+      def send_photo_with_keyboard(chat_id, photo_url_or_id, caption: nil, keyboard: nil)
+        api_request("sendPhoto", {
+          chat_id: chat_id,
+          photo: photo_url_or_id,
+          caption: caption,
+          reply_markup: keyboard ? {inline_keyboard: keyboard} : nil
+        }.compact)
+      end
+
+      def send_document(chat_id, document_url_or_id, caption: nil)
+        api_request("sendDocument", {
+          chat_id: chat_id,
+          document: document_url_or_id,
+          caption: caption
+        }.compact)
+      end
+
+      def send_video(chat_id, video_url_or_id, caption: nil)
+        api_request("sendVideo", {
+          chat_id: chat_id,
+          video: video_url_or_id,
+          caption: caption
+        }.compact)
+      end
+
+      def send_audio(chat_id, audio_url_or_id, caption: nil)
+        api_request("sendAudio", {
+          chat_id: chat_id,
+          audio: audio_url_or_id,
+          caption: caption
+        }.compact)
+      end
+
+      def send_voice(chat_id, voice_url_or_id)
+        api_request("sendVoice", {
+          chat_id: chat_id,
+          voice: voice_url_or_id
+        })
+      end
+
+      def answer_callback_query(callback_query_id, text: nil, show_alert: false)
+        api_request("answerCallbackQuery", {
+          callback_query_id: callback_query_id,
+          text: text,
+          show_alert: show_alert
+        }.compact)
+      end
+
+      def edit_message_text(chat_id, message_id, text, keyboard: nil, parse_mode: "HTML")
+        api_request("editMessageText", {
+          chat_id: chat_id,
+          message_id: message_id,
+          text: text,
+          parse_mode: parse_mode,
+          reply_markup: keyboard ? {inline_keyboard: keyboard} : nil
+        }.compact)
+      end
+
+      def delete_message(chat_id, message_id)
+        api_request("deleteMessage", {
+          chat_id: chat_id,
+          message_id: message_id
+        })
+      end
+
+      # Send a chat action (e.g. typing indicator) to a Telegram chat.
+      #
+      # The action lasts ~5 seconds or until the next outbound message.
+      # Valid actions per Telegram Bot API: "typing", "upload_photo",
+      # "record_video", "upload_video", "record_voice", "upload_voice",
+      # "upload_document", "choose_sticker", "find_location",
+      # "record_video_note", "upload_video_note".
+      #
+      # @param chat_id [Integer, String] the target chat id
+      # @param action [String] the chat action to broadcast (default: "typing")
+      # @return [Hash] parsed Telegram API response
+      def send_chat_action(chat_id, action: "typing")
+        api_request("sendChatAction", chat_id: chat_id, action: action)
+      end
+
+      # Show a typing indicator in a Telegram chat.
+      #
+      # Convenience wrapper around `send_chat_action(chat_id, action: "typing")`.
+      # The indicator lasts ~5 seconds or until the next outbound message;
+      # there is no stop-typing call.
+      #
+      # @param chat_id [Integer, String] the target chat id
+      # @return [Hash] parsed Telegram API response
+      def indicate_typing(chat_id)
+        send_chat_action(chat_id, action: "typing")
+      end
+
+      # Webhook management
+      def set_webhook(url, secret_token: nil, allowed_updates: nil)
+        api_request("setWebhook", {
+          url: url,
+          secret_token: secret_token,
+          allowed_updates: allowed_updates || ["message", "callback_query"]
+        }.compact)
+      end
+
+      def delete_webhook
+        api_request("deleteWebhook")
+      end
+
+      def get_webhook_info
+        api_request("getWebhookInfo")
+      end
+
+      def get_me
+        api_request("getMe")
+      end
+
+      # Get file metadata (including file_path) for an inbound file_id
+      def get_file(file_id)
+        api_request("getFile", {file_id: file_id})
+      end
+
+      # Build the download URL for an inbound file_id
+      def file_url(file_id)
+        # get_file answers nil when the API refused, so this cannot assume a
+        # hash back the way it did while every request returned its envelope.
+        file_path = get_file(file_id)&.dig("result", "file_path")
+        return nil unless file_path
+
+        "https://api.telegram.org/file/bot#{@config.bot_token}/#{file_path}"
+      end
+
+      # Download the raw bytes for an inbound file_id
+      def download_file(file_id)
+        url = file_url(file_id)
+        return nil unless url
+
+        uri = URI(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        response = http.get(uri.request_uri)
+
+        if response.is_a?(Net::HTTPSuccess)
+          response.body
+        else
+          FlowChat.logger.error { "Telegram::Client: File download error: #{response.code}" }
+          nil
+        end
+      end
+
+      private
+
+      def api_request(method, params = {})
+        uri = URI("#{@config.api_base_url}/#{method}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request.body = params.to_json
+
+        FlowChat.logger.debug { "Telegram::Client: API request to #{method}" }
+
+        response = http.request(request)
+        result = JSON.parse(response.body)
+
+        unless result["ok"]
+          FlowChat.logger.error { "Telegram::Client: API error - #{result["description"]}" }
+          report_api_error(
+            "Telegram API error: #{result["description"]}",
+            api_method: method,
+            error_code: result["error_code"],
+            error_description: result["description"],
+            chat_id: params[:chat_id]
+          )
+
+          # nil on a refused send, the contract every other client here keeps.
+          # Answering with the parsed error envelope instead made the failure
+          # indistinguishable from a success to anything upstream:
+          # report_delivery_failure tests the result for nil, so a Telegram
+          # send that Meta refused was reported as delivered and could never
+          # reach on_delivery_failure.
+          return nil
+        end
+
+        FlowChat.logger.debug { "Telegram::Client: API request successful" }
+        result
+      rescue Net::OpenTimeout, Net::ReadTimeout => network_error
+        FlowChat.logger.error { "Telegram::Client: Network timeout: #{network_error.class.name}: #{network_error.message}" }
+        raise network_error
+      rescue => error
+        FlowChat.logger.error { "Telegram::Client: API request exception: #{error.class.name}: #{error.message}" }
+        report_api_error(
+          "Telegram API request exception: #{error.class.name}",
+          api_method: method,
+          error: error,
+          chat_id: params[:chat_id]
+        )
+
+        # nil for the same reason a refused send answers nil above: an
+        # envelope here reads as a delivery to everything upstream.
+        nil
+      end
+
+      def report_api_error(message, api_method: nil, error_code: nil, error_description: nil, error: nil, chat_id: nil)
+        FlowChat::Instrumentation.report_api_error(
+          message,
+          error: error,
+          platform: :telegram,
+          bot_id: @config.bot_id,
+          api_method: api_method,
+          error_code: error_code,
+          error_description: error_description,
+          chat_id: chat_id
+        )
+      end
+    end
+  end
+end

data/lib/flow_chat/telegram/configuration.rb

@@ -0,0 +1,78 @@
+module FlowChat
+  module Telegram
+    class Configuration
+      include FlowChat::NamedConfiguration
+
+      attr_accessor :bot_token, :secret_token, :name, :skip_signature_validation
+
+      def initialize(name)
+        @name = name
+        @bot_token = nil
+        @secret_token = nil
+        @skip_signature_validation = false
+
+        FlowChat.logger.debug { "Telegram::Configuration: Initialized configuration with name: #{name || "anonymous"}" }
+
+        register_as(name) if name.present?
+      end
+
+      def self.from_credentials
+        FlowChat.logger.info { "Telegram::Configuration: Loading configuration from credentials/environment" }
+
+        config = new(nil)
+
+        if defined?(Rails) && Rails.respond_to?(:application) && Rails.application.credentials.telegram
+          FlowChat.logger.debug { "Telegram::Configuration: Loading from Rails credentials" }
+          credentials = Rails.application.credentials.telegram
+          config.bot_token = credentials[:bot_token]
+          config.secret_token = credentials[:secret_token]
+          config.skip_signature_validation = credentials[:skip_signature_validation] || false
+        else
+          FlowChat.logger.debug { "Telegram::Configuration: Loading from environment variables" }
+          config.bot_token = ENV["TELEGRAM_BOT_TOKEN"]
+          config.secret_token = ENV["TELEGRAM_SECRET_TOKEN"]
+          config.skip_signature_validation = ENV["TELEGRAM_SKIP_SIGNATURE_VALIDATION"] == "true"
+        end
+
+        if config.valid?
+          FlowChat.logger.info { "Telegram::Configuration: Configuration loaded successfully" }
+        else
+          FlowChat.logger.warn { "Telegram::Configuration: Incomplete configuration loaded - missing required fields" }
+        end
+
+        config
+      end
+
+      def valid?
+        is_valid = !!(bot_token && !bot_token.to_s.empty?)
+        FlowChat.logger.debug { "Telegram::Configuration: Configuration valid: #{is_valid}" }
+        is_valid
+      end
+
+      def api_base_url
+        return nil unless bot_token
+        "https://api.telegram.org/bot#{bot_token}"
+      end
+
+      def bot_id
+        bot_token&.split(":")&.first
+      end
+
+      def send_message_url
+        "#{api_base_url}/sendMessage"
+      end
+
+      def set_webhook_url
+        "#{api_base_url}/setWebhook"
+      end
+
+      def get_webhook_info_url
+        "#{api_base_url}/getWebhookInfo"
+      end
+
+      def delete_webhook_url
+        "#{api_base_url}/deleteWebhook"
+      end
+    end
+  end
+end