flow_chat 0.9.0 → 0.10.0

data/lib/flow_chat/prompt.rb

@@ -3,13 +3,15 @@ module FlowChat
     attr_reader :user_input
 
     def initialize(input)
-      @user_input = input
+      # Always work with a FlowChat::Input so `submitted?` (text OR attachment)
+      # gates the turn, and validate/transform receive the rich turn. A bare
+      # string (or nil) is wrapped as text.
+      @user_input = input.is_a?(FlowChat::Input) ? input : FlowChat::Input.new(text: input)
     end
 
     def ask(msg, choices: nil, transform: nil, validate: nil, media: nil)
-      if user_input.present?
-        input = user_input
-        validation_error = validate.call(input) if validate.present?
+      if user_input.submitted?
+        validation_error = validate.call(user_input) if validate.present?
 
         if validation_error.present?
           # Use config to determine whether to combine validation error with original message
@@ -21,8 +23,7 @@ module FlowChat
           prompt!(message, choices: choices, media: media)
         end
 
-        input = transform.call(input) if transform.present?
-        return input
+        return transform.present? ? transform.call(user_input) : user_input.to_s
       end
 
       # Pass raw message and media separately to the renderer
@@ -56,14 +57,6 @@ module FlowChat
 
     private
 
-    def validate_media_choices_compatibility(media, choices)
-      return unless media && choices
-
-      if choices.length > 3
-        raise ArgumentError, "Media with more than 3 choices is not supported. Please use either media OR choices for more than 3 options."
-      end
-    end
-
     def normalize_choices(choices)
       case choices
       when nil
@@ -78,8 +71,12 @@ module FlowChat
     end
 
     def prompt!(msg, choices: nil, media: nil)
-      validate_media_choices_compatibility(media, choices)
-
+      # Media plus any number of choices is a supported combination: every
+      # renderer either carries the media as its own message ahead of the
+      # choice surface, or (WhatsApp, <=3 choices) as a header on the same
+      # message. There is no platform-level reason to cap the choice count
+      # here - that decision, if one is ever needed, belongs to a specific
+      # renderer, not to this shared entry point.
       choices = normalize_choices(choices)
       raise FlowChat::Interrupt::Prompt.new(msg, choices: choices, media: media)
     end

data/lib/flow_chat/renderers/markdown_support.rb

@@ -21,6 +21,16 @@ module FlowChat
         post_process_html(sanitized)
       end
 
+      # Markdown rendered as plain text, for platforms with no rich text at all.
+      # Messenger and Instagram both fall here: they display exactly the
+      # characters sent, so any leftover markup is noise the user reads.
+      def to_plain_text(text)
+        return "" if text.nil?
+
+        html = Kramdown::Document.new(text.to_s, **kramdown_options).to_html.strip
+        html_to_plain_text(html)
+      end
+
       def self.included(base)
         base.extend(ClassMethods)
       end
@@ -53,6 +63,105 @@ module FlowChat
       def post_process_html(html)
         html
       end
+
+      # A list whose items hold no further list, which is the only kind that
+      # can be turned into text without looking inside itself first.
+      INNERMOST_UNORDERED = %r{<ul[^>]*>((?:(?!<[uo]l\b).)*?)</ul>}m
+      INNERMOST_ORDERED = %r{<ol[^>]*>((?:(?!<[uo]l\b).)*?)</ol>}m
+
+      # Renders lists from the inside out.
+      #
+      # A single non-greedy pass over <ul>(.*?)</ul> pairs an outer opening tag
+      # with the *inner* list's closing tag, so on a nested list only the first
+      # item kept its bullet and the leftover </li></ul> was later stripped as
+      # a bare tag - leaving stray indented lines, and on some inputs raw
+      # markup, in a message a user reads.
+      #
+      # Innermost lists are replaced first and the loop repeats, so by the time
+      # an outer list is matched its children are already plain text and it
+      # contains no list markup to mispair with. Continuation lines are
+      # indented, which is what makes the nesting legible once the tags are
+      # gone.
+      def replace_lists(html)
+        # The markdown's own indentation survives into the HTML as whitespace
+        # around the list tags. Removed once, up front, so that from here on the
+        # only indentation in play is the kind this method adds - otherwise the
+        # two compound and each level steps further right than the last.
+        result = html.gsub(%r{\s*(</?(?:ul|ol|li)\b[^>]*>)\s*}m) { $1 }
+
+        loop do
+          changed = false
+
+          # Each rendered list opens on its own line. Without it, a nested list
+          # would run straight on from the text of the item holding it, and the
+          # parent pass would see one line where there are two.
+          result = result.gsub(INNERMOST_UNORDERED) do
+            changed = true
+            "\n" + list_items($1) { |item, _index| "• #{item}" }
+          end
+
+          result = result.gsub(INNERMOST_ORDERED) do
+            changed = true
+            "\n" + list_items($1) { |item, index| "#{index}. #{item}" }
+          end
+
+          break unless changed
+        end
+
+        result
+      end
+
+      def list_items(html)
+        html.scan(%r{<li[^>]*>(.*?)</li>}m).flatten.map.with_index(1) do |item, index|
+          # Continuation lines are left exactly as they are: they were produced
+          # by an earlier pass over a nested list and already carry that level's
+          # indentation, which stripping would flatten. Source whitespace is
+          # gone by now - replace_lists removes it around the list tags before
+          # any of this runs.
+          lines = item.strip.split("\n").reject { |line| line.strip.empty? }
+          marked = yield(lines.shift.to_s.strip, index)
+
+          # Anything after the first line is an already-rendered nested list.
+          [marked, *lines.map { |line| "  #{line}" }].join("\n")
+        end.join("\n")
+      end
+
+      def html_to_plain_text(html)
+        result = html.dup
+
+        # Code blocks and inline code keep their content, lose their markers.
+        result.gsub!(%r{<pre[^>]*><code[^>]*>(.*?)</code></pre>}m) { $1.strip }
+        result.gsub!(%r{<code[^>]*>(.*?)</code>}m) { $1 }
+
+        # Links first: the anchor text is needed before tags are stripped.
+        result.gsub!(%r{<a[^>]*href=["']([^"']+)["'][^>]*>(.*?)</a>}m) do
+          url, text = $1, $2
+          (text == url) ? url : "#{text} (#{url})"
+        end
+
+        result = replace_lists(result)
+
+        result.gsub!(%r{<blockquote[^>]*>(.*?)</blockquote>}m) do
+          $1.lines.map { |line| "> #{line.strip}" }.join("\n")
+        end
+
+        result.gsub!(%r{<p[^>]*>(.*?)</p>}m) { "#{$1}\n\n" }
+        result.gsub!(/<br\s*\/?>/, "\n")
+
+        # Every remaining tag, emphasis included, goes without replacement.
+        result.gsub!(/<[^>]+>/, "")
+
+        result.gsub!("&amp;", "&")
+        result.gsub!("&lt;", "<")
+        result.gsub!("&gt;", ">")
+        result.gsub!("&quot;", '"')
+        result.gsub!("&#39;", "'")
+        result.gsub!("&nbsp;", " ")
+
+        result.gsub!(/\n{3,}/, "\n\n")
+
+        result.strip
+      end
     end
   end
 end

data/lib/flow_chat/security.rb

@@ -0,0 +1,76 @@
+require "openssl"
+
+begin
+  require "active_support/security_utils"
+rescue LoadError
+  # Older Active Support, or an install without it. secure_compare falls back
+  # to its own implementation below.
+end
+
+module FlowChat
+  # Shared security helpers: constant-time comparison for webhook secrets and
+  # signatures, and the signed cookie that authorizes simulator mode.
+  module Security
+    SIMULATOR_COOKIE_NAME = "flowchat_simulator"
+
+    # How long a simulator cookie stays valid.
+    SIMULATOR_COOKIE_TTL = 24 * 60 * 60
+
+    class << self
+      # Compare two strings without leaking their contents through timing.
+      def secure_compare(a, b)
+        a = a.to_s
+        b = b.to_s
+
+        if defined?(ActiveSupport::SecurityUtils)
+          ActiveSupport::SecurityUtils.secure_compare(a, b)
+        else
+          fallback_secure_compare(a, b)
+        end
+      end
+
+      # The value to store in the simulator cookie: "timestamp:signature".
+      def simulator_cookie(timestamp = Time.now.to_i)
+        "#{timestamp}:#{simulator_signature(timestamp)}"
+      end
+
+      # A simulator cookie is valid when it carries a recent timestamp signed
+      # with the configured simulator secret.
+      def valid_simulator_cookie?(cookie)
+        return false if FlowChat::Config.simulator_secret.blank? || cookie.blank?
+
+        timestamp_str, signature = cookie.to_s.split(":", 2)
+        return false unless timestamp_str && signature
+
+        timestamp = timestamp_str.to_i
+        return false if timestamp <= 0
+        return false if (Time.now.to_i - timestamp).abs > SIMULATOR_COOKIE_TTL
+
+        secure_compare(signature, simulator_signature(timestamp_str))
+      end
+
+      def simulator_signature(timestamp)
+        OpenSSL::HMAC.hexdigest(
+          OpenSSL::Digest.new("sha256"),
+          FlowChat::Config.simulator_secret,
+          "simulator:#{timestamp}"
+        )
+      end
+
+      private
+
+      # What Active Support does, for installs that do not have it: compare
+      # digests rather than the inputs, so the comparison runs over a fixed
+      # length and times neither the contents nor the length of a secret. The
+      # equality check afterwards is what makes a digest collision harmless.
+      def fallback_secure_compare(a, b)
+        digest_a = OpenSSL::Digest.digest("SHA256", a)
+        digest_b = OpenSSL::Digest.digest("SHA256", b)
+
+        result = 0
+        digest_a.bytes.zip(digest_b.bytes) { |byte_a, byte_b| result |= byte_a ^ byte_b }
+        result == 0 && a == b
+      end
+    end
+  end
+end

data/lib/flow_chat/session/middleware.rb

@@ -96,6 +96,10 @@ module FlowChat
         case platform
         when :whatsapp
           :msisdn
+        when :messenger, :instagram
+          # Neither platform exposes a phone number. The sender id is scoped to
+          # the app and the account, and is stable per user.
+          :user_id
         else
           :request_id
         end
@@ -161,8 +165,13 @@ module FlowChat
       end
 
       def hash_identifier(identifier)
-        # Use SHA256 but only take first 8 characters for reasonable session IDs
-        Digest::SHA256.hexdigest(identifier.to_s)[0, 8]
+        # First 32 hex chars of SHA256 = 128 bits. The old 8-char (32-bit)
+        # truncation was far too short: distinct users started colliding
+        # (birthday bound) around ~77k identifiers, and a collision means two
+        # users share a session. 128 bits pushes that boundary past ~2^64
+        # identifiers (collision-safe in practice) at half the length of the
+        # full 64-char digest.
+        Digest::SHA256.hexdigest(identifier.to_s)[0, 32]
       end
     end
   end

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