flow_chat 0.9.0 → 0.10.1

data/lib/flow_chat/intercom/gateway/intercom_api.rb

@@ -3,9 +3,6 @@ require "openssl"
 
 module FlowChat
   module Intercom
-    # Configuration-related errors
-    class ConfigurationError < StandardError; end
-
     module Gateway
       class IntercomApi
         include FlowChat::Instrumentation
@@ -16,6 +13,17 @@ module FlowChat
         # Default webhook topics to process
         DEFAULT_WEBHOOK_TOPICS = ["conversation.user.created", "conversation.user.replied"].freeze
 
+        # Configure Intercom specific middleware stack
+        def self.configure_middleware_stack(builder, custom_middleware)
+          FlowChat.logger.debug { "IntercomApi: Configuring Intercom middleware stack" }
+
+          builder.use custom_middleware
+          FlowChat.logger.debug { "IntercomApi: Added custom middleware" }
+
+          builder.use FlowChat::Intercom::Middleware::ChoiceMapper
+          FlowChat.logger.debug { "IntercomApi: Added Intercom::Middleware::ChoiceMapper" }
+        end
+
         def initialize(app, config = nil, additional_webhook_topics = nil)
           @app = app
           @config = config || FlowChat::Intercom::Configuration.from_credentials
@@ -141,10 +149,18 @@ module FlowChat
 
             if latest_message
               context["request.message_id"] = latest_message[:id]
-              # Convert HTML to markdown for message body
-              raw_body = latest_message[:body] || ""
-              context.input = @client.parse_message(raw_body)
-              FlowChat.logger.debug { "IntercomApi: Message content extracted - Event: #{event_type}, Input: '#{context.input}'" }
+              if latest_message[:media]
+                media = latest_message[:media]
+                body = latest_message[:body]
+                context["request.media"] = media
+                context.input = body.present? ? @client.parse_message(body) : ""
+                FlowChat.logger.debug { "IntercomApi: Media received - #{media.size} attachment(s)" }
+              else
+                # Convert HTML to markdown for message body
+                raw_body = latest_message[:body] || ""
+                context.input = @client.parse_message(raw_body)
+                FlowChat.logger.debug { "IntercomApi: Message content extracted - Event: #{event_type}, Input: '#{context.input}'" }
+              end
             elsif @allowed_webhook_topics.include?(event_type)
               # No message but event is explicitly allowed - process without message
               context.input = nil
@@ -237,7 +253,7 @@ module FlowChat
           )
 
           # Compare signatures using secure comparison to prevent timing attacks
-          signature_valid = secure_compare(expected_signature, calculated_signature)
+          signature_valid = FlowChat::Security.secure_compare(expected_signature, calculated_signature)
 
           if signature_valid
             FlowChat.logger.debug { "IntercomApi: Webhook signature validation successful" }
@@ -253,16 +269,6 @@ module FlowChat
           false
         end
 
-        # Secure string comparison to prevent timing attacks
-        def secure_compare(a, b)
-          return false unless a.bytesize == b.bytesize
-
-          l = a.unpack("C*")
-          res = 0
-          b.each_byte { |byte| res |= byte ^ l.shift }
-          res == 0
-        end
-
         def extract_latest_user_message(conversation, event_type)
           FlowChat.logger.debug { "IntercomApi: Extracting latest user message from #{event_type} event" }
 
@@ -270,11 +276,12 @@ module FlowChat
           when "conversation.user.created"
             # For new conversations, get the initial message from source
             source = conversation["source"]
-            if source && source["body"]
+            if source && (source["body"] || source["attachments"]&.any?)
               {
                 id: source["id"],
-                body: source["body"]
-              }
+                body: source["body"],
+                media: extract_attachments(source)
+              }.compact
             end
           when "conversation.user.replied"
             # For replies, get the latest user message from conversation_parts
@@ -291,19 +298,57 @@ module FlowChat
               latest_part = user_parts.last
               {
                 id: latest_part["id"],
-                body: latest_part["body"]
-              }
+                body: latest_part["body"],
+                media: extract_attachments(latest_part)
+              }.compact
             end
           end
         end
 
+        def extract_attachments(raw)
+          attachments = raw["attachments"] || []
+          return nil if attachments.empty?
+
+          attachments.map do |a|
+            {
+              type: intercom_media_type(a["content_type"]),
+              url: a["url"],
+              mime_type: a["content_type"],
+              filename: a["name"]
+            }
+          end
+        end
+
+        def intercom_media_type(content_type)
+          case content_type
+          when %r{\Aimage/} then :image
+          when %r{\Avideo/} then :video
+          when %r{\Aaudio/} then :audio
+          else :document
+          end
+        end
+
         def handle_message_inline(context, controller)
           response = @app.call(context)
           if response
             _type, prompt, choices, media = response
-            result = @client.send_message(context["request.id"], prompt, choices: choices, media: media)
+            result = report_delivery_failure(
+              context,
+              to: context["request.user_id"],
+              conversation_id: context["request.id"],
+              message: prompt,
+              gateway: :intercom_api,
+              platform: :intercom
+            ) do
+              @client.send_message(context["request.id"], prompt, choices: choices, media: media)
+            end
             context["intercom.message_result"] = result
 
+            # report_delivery_failure already reported this; a nil result
+            # means the platform did not accept the message, and instrumenting
+            # MESSAGE_SENT anyway counted a delivery that never happened.
+            return unless result
+
             # Instrument message sent
             instrument(Events::MESSAGE_SENT, {
               to: context["request.user_id"],
@@ -312,11 +357,20 @@ module FlowChat
               gateway: :intercom_api,
               platform: :intercom,
               content_length: prompt.to_s.length,
+              platform_message_id: platform_message_id_from(result),
+              duration_ms: context[FlowChat::Instrumentation::DELIVERY_DURATION_KEY],
               timestamp: context["request.timestamp"]
             })
           end
         end
 
+        # A reply comes back as the conversation part it created.
+        def platform_message_id_from(result)
+          return nil unless result.is_a?(Hash)
+
+          result["id"]
+        end
+
         def handle_message_simulator(context, controller)
           response = @app.call(context)
 
@@ -348,39 +402,9 @@ module FlowChat
           # Check if simulator mode is enabled for this processor
           return false unless context["enable_simulator"]
 
-          # Then check if simulator mode is requested and valid
-          @body.dig("simulator_mode") && valid_simulator_cookie?(context)
-        end
-
-        def valid_simulator_cookie?(context)
-          simulator_secret = FlowChat::Config.simulator_secret
-          return false unless simulator_secret && !simulator_secret.empty?
-
-          # Check for simulator cookie
-          simulator_cookie = @controller.request.cookies["flowchat_simulator"]
-          return false unless simulator_cookie
-
-          # Verify the cookie is a valid HMAC signature
-          # Cookie format: "timestamp:signature" where signature = HMAC(simulator_secret, "simulator:timestamp")
-          begin
-            timestamp_str, signature = simulator_cookie.split(":", 2)
-            return false unless timestamp_str && signature
-
-            # Check timestamp is recent (within 24 hours for reasonable session duration)
-            timestamp = timestamp_str.to_i
-            return false if timestamp <= 0
-            return false if (Time.now.to_i - timestamp).abs > 86400 # 24 hours
-
-            # Calculate expected signature
-            message = "simulator:#{timestamp_str}"
-            expected_signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), simulator_secret, message)
-
-            # Use secure comparison
-            secure_compare(signature, expected_signature)
-          rescue => e
-            Rails.logger.warn "Invalid simulator cookie format: #{e.message}"
-            false
-          end
+          # Then check if simulator mode is requested and authorized
+          @body.dig("simulator_mode") &&
+            FlowChat::Security.valid_simulator_cookie?(@controller.request.cookies[FlowChat::Security::SIMULATOR_COOKIE_NAME])
         end
 
         def parse_request_body(request)

data/lib/flow_chat/intercom/middleware/choice_mapper.rb

@@ -0,0 +1,101 @@
+module FlowChat
+  module Intercom
+    module Middleware
+      # Maps an Intercom reply back to the choice it belongs to.
+      #
+      # Intercom has no interactive buttons, so the renderer writes the options
+      # out as a numbered list and asks the reader to reply with a number. That
+      # number has to come back to the choice key the flow branches on, the same
+      # job USSD's mapper does for a handset.
+      #
+      # A number is the only thing that resolves, as on USSD, and that is what
+      # the message asks for in as many words. It is also what makes this
+      # mapper safe by construction rather than by care: positions are unique
+      # whatever the labels say, so there is no equivalence under which two
+      # choices could collapse and nothing to check them against.
+      #
+      # Labels were matched too, case insensitively. That is what needed the
+      # care - two choices reading the same, or differing only in case, folded
+      # onto one entry and the second could not be picked by name at all. On a
+      # screen that prints a number beside every option and asks for one, the
+      # number already does that job unambiguously.
+      #
+      # Flow:
+      # 1. Flow returns choices with their own keys (e.g. {"sales" => "Sales"})
+      # 2. This middleware numbers them and remembers what each number meant
+      # 3. The renderer writes "1. Sales" and asks for a number
+      # 4. The reader replies "1"
+      # 5. This middleware turns it back into "sales"
+      # 6. The flow sees its own key
+      class ChoiceMapper
+        SESSION_KEY = "intercom.choice_mapping"
+
+        def initialize(app)
+          @app = app
+          FlowChat.logger.debug { "Intercom::ChoiceMapper: Initialized Intercom choice mapping middleware" }
+        end
+
+        def call(context)
+          @context = context
+          @session = context.session
+
+          resolve_input
+
+          type, prompt, choices, media = @app.call(context)
+
+          choices = remember(choices)
+
+          [type, prompt, choices, media]
+        end
+
+        private
+
+        def resolve_input
+          return if @context.input.blank?
+
+          mapping = @session.get(SESSION_KEY) || {}
+          return if mapping.empty?
+
+          # Surrounding whitespace is trimmed off a chat message before the
+          # lookup. Unlike a fold over labels, this cannot merge two choices:
+          # trimming leaves "1" and "2" as distinct as it found them.
+          matched = mapping[@context.input.to_s.strip]
+          return unless matched
+
+          FlowChat.logger.info { "Intercom::ChoiceMapper: Resolving #{@context.input} to #{matched}" }
+          @context.input = matched
+        end
+
+        # Numbers the choices and stores what each number meant.
+        #
+        # The renderer is what prints the number beside each label, so nothing
+        # is prefixed here - doing both would read as "1. 1. Savings".
+        #
+        # Cleared when a screen carries no choices, so an answer typed into a
+        # later free-text question is never read as a choice from an earlier
+        # menu. WhatsApp and Messenger each had this same bug fixed twice.
+        #
+        # @return [Hash, nil] the choices to render
+        def remember(choices)
+          if choices.blank?
+            @session.delete(SESSION_KEY)
+            return choices
+          end
+
+          numbered = {}
+          mapping = {}
+
+          choices.each_with_index do |(key, label), index|
+            number = (index + 1).to_s
+            numbered[number] = label.to_s
+            mapping[number] = key.to_s
+          end
+
+          @session.set(SESSION_KEY, mapping)
+          FlowChat.logger.debug { "Intercom::ChoiceMapper: Created mapping: #{mapping}" }
+          numbered
+        end
+      end
+    end
+  end
+end

data/lib/flow_chat/intercom/renderer.rb

@@ -24,7 +24,8 @@ module FlowChat
       private
 
       def build_text_message
-        [:text, to_html(message), {}]
+        link, options = render_media
+        [:text, to_html(message.to_s + link), options]
       end
 
       def build_selection_message
@@ -35,10 +36,27 @@ module FlowChat
         end
       end
 
+      # Choices are a numbered list rather than Intercom's own quick replies,
+      # and that is a decision rather than an oversight. Intercom does document
+      # reply_options with message_type "quick_reply" on an admin reply, and it
+      # was built here and reverted. Three reasons, in the order they matter:
+      #
+      # - The uuid of a clicked option comes back as quick_reply_option_uuid,
+      #   and only if the Intercom app is set to the *Unstable* API version.
+      #   Webhooks inherit that setting, so an app on a stable version receives
+      #   no metadata at all. Requiring an unstable API version for something as
+      #   basic as reading which option was chosen is not a thing a library can
+      #   ask of its users.
+      # - body is forbidden on a quick_reply, so a choice screen becomes two
+      #   conversation parts: one for the prompt, one for the buttons. In an
+      #   inbox a human reads, that doubles the length of every flow.
+      # - Intercom's own community reports the endpoint returning errors for
+      #   this shape.
+      #
+      # A numbered list needs none of that and works on every API version. If
+      # Intercom stabilises quick replies, the git history has the
+      # implementation; check those three things before restoring it.
       def build_interactive_message(choice_hash)
-        # For Intercom, we'll present choices as a formatted text message
-        # since Intercom doesn't have the same interactive elements as WhatsApp
-
         formatted_message = message.to_s
 
         unless formatted_message.empty?
@@ -53,7 +71,41 @@ module FlowChat
 
         formatted_message += "\nReply with the number of your choice."
 
-        [:text, to_html(formatted_message), {choices: choice_hash}]
+        link, options = render_media
+        [:text, to_html(formatted_message + link), options.merge(choices: choice_hash)]
+      end
+
+      # Intercom's admin reply only takes real attachments as image URLs
+      # (attachment_urls, documented specifically for images, max 10). Any
+      # other media type with a url - document, video, audio, sticker -
+      # becomes a markdown link in the body instead, since attachment_urls
+      # is documented for images and a non-image URL there may not render.
+      # An id with no url is another platform's upload handle (a WhatsApp
+      # media id, say) and means nothing to Intercom, so it is logged and
+      # dropped rather than raised: a multi-platform flow legitimately sets
+      # an id for whichever platform uploaded it, and one platform lacking
+      # the media should not fail the whole turn.
+      #
+      # Returns [markdown_suffix, options] - the suffix is appended to the
+      # message before markdown-to-HTML conversion so a link goes through
+      # the same sanitizer and allowed_tags as the rest of the body.
+      def render_media
+        return ["", {}] unless media
+
+        url = media[:url]
+        media_type = (media[:type] || :image).to_sym
+
+        unless url
+          FlowChat.logger.warn { "Intercom::Renderer: media id #{media[:id].inspect} is another platform's upload handle and means nothing to Intercom (no url given); sending the message without it" }
+          return ["", {}]
+        end
+
+        if media_type == :image
+          ["", {attachment_urls: [url]}]
+        else
+          label = media[:filename] || media_type.to_s.capitalize
+          ["\n\n[#{label}](#{url})", {}]
+        end
       end
 
       # MarkdownSupport overrides for Intercom-specific behavior

data/lib/flow_chat/media.rb

@@ -0,0 +1,121 @@
+require "net/http"
+require "uri"
+
+module FlowChat
+  # Value object wrapping a single inbound media item parsed by a gateway.
+  # Normalizes cross-platform differences (WhatsApp media-id, Telegram file_id,
+  # Intercom/HTTP direct URL) behind #url and #download.
+  class Media
+    # Maps platform-native media types to a canonical, cross-platform set.
+    # Telegram uses :photo/:voice where WhatsApp uses :image/:audio.
+    NORMALIZED_TYPES = {photo: :image, voice: :audio}.freeze
+
+    # The canonical media types FlowChat recognizes across platforms. Gateways
+    # that accept a caller-supplied type (e.g. HTTP) validate against this set.
+    CANONICAL_TYPES = %i[image video audio document sticker].freeze
+
+    attr_reader :platform, :client
+
+    def initialize(data, platform:, client: nil)
+      @data = data
+      @platform = platform
+      @client = client
+    end
+
+    # Canonical, cross-platform media type (:image, :video, :audio, :document, :sticker).
+    def type
+      NORMALIZED_TYPES.fetch(raw_type, raw_type)
+    end
+
+    # The platform-native type as parsed by the gateway (e.g. :photo, :voice on Telegram).
+    def raw_type
+      @data[:type]
+    end
+
+    def mime_type
+      @data[:mime_type]
+    end
+
+    def caption
+      @data[:caption]
+    end
+
+    def filename
+      @data[:filename] || @data[:file_name]
+    end
+
+    def id
+      @data[:id]
+    end
+
+    def file_id
+      @data[:file_id]
+    end
+
+    def [](key)
+      @data[key]
+    end
+
+    def to_h
+      @data.dup
+    end
+
+    # Serialize without the live platform client (a network object that may not
+    # marshal). This keeps a Media — and any FlowChat::Input holding it — safe to
+    # store in a session store. A deserialized Media has no client, so #url and
+    # #download degrade to nil rather than raising.
+    def marshal_dump
+      {data: @data, platform: @platform}
+    end
+
+    def marshal_load(state)
+      @data = state[:data]
+      @platform = state[:platform]
+      @client = nil
+    end
+
+    # Resolve a fetchable URL for the media. Memoized so repeated reads don't
+    # re-issue the platform lookup (WhatsApp get_media_url / Telegram getFile).
+    # Returns nil (rather than raising) if the lookup fails, matching #download.
+    def url
+      @url ||= case platform
+      when :whatsapp then client.get_media_url(id)
+      when :telegram then client.file_url(file_id)
+      else @data[:url]
+      end
+    rescue => e
+      FlowChat.logger.warn { "Media: url resolution failed: #{e.message}" }
+      nil
+    end
+
+    # Fetch the raw bytes of the media, or nil on failure (uniform across
+    # platforms). WhatsApp needs the client to attach auth headers; every other
+    # platform (Telegram, Intercom, HTTP) exposes a token-in-URL or public link,
+    # so we fetch the already-memoized #url directly — avoiding a second getFile
+    # round-trip on Telegram.
+    def download
+      case platform
+      when :whatsapp then client.download_media(id)
+      else fetch(url)
+      end
+    rescue => e
+      FlowChat.logger.warn { "Media: download failed: #{e.message}" }
+      nil
+    end
+
+    private
+
+    def fetch(resource_url)
+      return nil unless resource_url
+
+      uri = URI(resource_url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      response = http.get(uri.request_uri)
+      response.body if response.is_a?(Net::HTTPSuccess)
+    rescue => e
+      FlowChat.logger.warn { "Media: download failed for #{resource_url}: #{e.message}" }
+      nil
+    end
+  end
+end