flow_chat 0.8.2 → 0.10.0

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

@@ -0,0 +1,420 @@
+require "json"
+require "openssl"
+
+module FlowChat
+  module Intercom
+    module Gateway
+      class IntercomApi
+        include FlowChat::Instrumentation
+        include FlowChat::GatewayAsyncSupport
+
+        attr_reader :client
+
+        # 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
+          @client = FlowChat::Intercom::Client.new(@config)
+          # Always include default topics, plus any additional ones
+          @allowed_webhook_topics = DEFAULT_WEBHOOK_TOPICS + Array(additional_webhook_topics)
+
+          FlowChat.logger.info { "IntercomApi: Initialized Intercom API gateway" }
+          FlowChat.logger.debug { "IntercomApi: Gateway configuration - API base URL: #{@config.api_base_url}" }
+          FlowChat.logger.debug { "IntercomApi: Allowed webhook topics: #{@allowed_webhook_topics.inspect}" }
+        end
+
+        def call(context)
+          @context = context
+          @controller = context.controller
+          request = @controller.request
+
+          FlowChat.logger.debug { "IntercomApi: Processing #{request.request_method} request to #{request.path}" }
+
+          # Skip webhook-specific handling in background mode
+          unless in_background?
+            # Handle webhook URL validation (HEAD request)
+            if request.head?
+              FlowChat.logger.info { "IntercomApi: Handling webhook URL validation request" }
+              return @controller.head :ok
+            end
+          end
+
+          # Handle webhook notifications (POST request)
+          if request.post?
+            FlowChat.logger.info { "IntercomApi: Handling webhook notification (background: #{in_background?})" }
+            return handle_webhook(context)
+          end
+
+          FlowChat.logger.warn { "IntercomApi: Invalid request method or parameters - returning bad request" }
+          @controller.head :bad_request
+        end
+
+        private
+
+        def handle_webhook(context)
+          # Parse body
+          begin
+            parse_request_body(@controller.request)
+            @client.app_id = @body["app_id"]
+            FlowChat.logger.debug { "IntercomApi: Successfully parsed webhook request body" }
+          rescue JSON::ParserError => e
+            FlowChat.logger.error { "IntercomApi: Failed to parse webhook body: #{e.message}" }
+            return @controller.head :bad_request
+          end
+
+          # Check for simulator mode parameter in request (before validation)
+          # But only enable if valid simulator token is provided
+          is_simulator_mode = simulate?(context)
+          if is_simulator_mode
+            FlowChat.logger.info { "IntercomApi: Simulator mode enabled for this request" }
+            context["simulator_mode"] = true
+          end
+
+          # Validate webhook signature for security (skip for simulator mode and background)
+          # Return 200 OK even for invalid signatures to prevent Intercom from retrying
+          unless in_background? || is_simulator_mode || valid_webhook_signature?(@controller.request)
+            FlowChat.logger.warn { "IntercomApi: Invalid webhook signature - dropping request" }
+            return @controller.head :ok
+          end
+
+          FlowChat.logger.debug { "IntercomApi: Webhook signature validation passed" }
+
+          # Extract event data from Intercom webhook
+          event_type = @body["topic"]
+          unless event_type
+            FlowChat.logger.debug { "IntercomApi: No topic found in webhook body - returning OK" }
+            return @controller.head :ok
+          end
+
+          # Only process conversation events we care about
+          unless @allowed_webhook_topics.include?(event_type)
+            FlowChat.logger.debug { "IntercomApi: Ignoring event type '#{event_type}' (not in allowed topics) - returning OK" }
+            return @controller.head :ok
+          end
+
+          # Extract conversation data
+          data_item = @body.dig("data", "item")
+          unless data_item
+            FlowChat.logger.debug { "IntercomApi: No data.item found in webhook body - returning OK" }
+            return @controller.head :ok
+          end
+
+          # Process conversation event
+          if data_item["type"] == "conversation"
+            conversation = data_item
+            conversation_id = conversation["id"]
+
+            # Get the user ID from contacts (always the actual user/contact)
+            # contacts.contacts[0] contains the actual user, not the admin
+            contact = conversation.dig("contacts", "contacts", 0)
+            unless contact
+              FlowChat.logger.error { "IntercomApi: No contact found in conversation" }
+              return @controller.head :ok
+            end
+
+            # Get user ID, name, email, and phone from contact (most reliable)
+            user_id = contact["id"]
+            user_name = contact["name"]
+            user_email = contact["email"]
+            user_phone = contact["phone"]
+
+            context["request.id"] = conversation_id
+            context["request.user_id"] = user_id
+            context["request.user_name"] = user_name if user_name
+            context["request.email"] = user_email if user_email
+            context["request.msisdn"] = user_phone if user_phone
+            context["request.gateway"] = :intercom_api
+            context["request.platform"] = :intercom
+            context["request.timestamp"] = Time.now.iso8601
+            context["request.body"] = @body
+
+            context["intercom.client"] = @client
+            context["intercom.topic"] = event_type
+
+            # Try to extract latest message for user events
+            latest_message = extract_latest_user_message(conversation, event_type)
+
+            if latest_message
+              context["request.message_id"] = latest_message[:id]
+              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
+              FlowChat.logger.debug { "IntercomApi: Processing #{event_type} event without user message" }
+            else
+              # No message and event not in allowed topics - skip
+              # (This case shouldn't happen as we already filtered above, but safety check)
+              FlowChat.logger.error { "IntercomApi: No message found for unexpected event type '#{event_type}'" }
+              return @controller.head :ok
+            end
+
+            # Instrument message received (with or without message content)
+            instrument(Events::MESSAGE_RECEIVED, {
+              from: user_id,
+              conversation_id: conversation_id,
+              message: context.input,
+              event_type: event_type
+            })
+
+            # Determine routing: async enqueue, background execute, or inline
+            if should_enqueue_async?
+              # Webhook with async enabled → enqueue job and return immediately
+              enqueue_async_job
+              return @controller.head :ok
+            else
+              # Background OR inline → process message
+              # Determine message handling mode (simulator vs inline)
+              handler_mode = determine_message_handler(context)
+
+              # Process the message based on handling mode
+              case handler_mode
+              when :inline
+                handle_message_inline(context, @controller)
+              when :simulator
+                # Return early from simulator mode to preserve the JSON response
+                return handle_message_simulator(context, @controller)
+              end
+            end
+          end
+
+          @controller.head :ok
+        end
+
+        def determine_message_handler(context)
+          # Use simulator mode if enabled, otherwise always use inline
+          if context["simulator_mode"]
+            FlowChat.logger.debug { "IntercomApi: Using simulator message handler" }
+            :simulator
+          else
+            FlowChat.logger.debug { "IntercomApi: Using inline message handler" }
+            :inline
+          end
+        end
+
+        # Validate webhook signature to ensure request comes from Intercom
+        def valid_webhook_signature?(request)
+          # Check if signature validation is explicitly disabled
+          if @config.skip_signature_validation
+            FlowChat.logger.debug { "IntercomApi: Webhook signature validation is disabled" }
+            return true
+          end
+
+          # Require client_secret for signature validation
+          unless @config.client_secret && !@config.client_secret.empty?
+            error_msg = "Intercom client_secret is required for webhook signature validation. " \
+                       "Either configure client_secret or set skip_signature_validation=true to explicitly disable validation."
+            FlowChat.logger.error { "IntercomApi: #{error_msg}" }
+            raise FlowChat::Intercom::ConfigurationError, error_msg
+          end
+
+          signature_header = request.headers["X-Hub-Signature"]
+          unless signature_header
+            FlowChat.logger.warn { "IntercomApi: No X-Hub-Signature header found in request" }
+            return false
+          end
+
+          # Extract signature from header (format: "sha1=<signature>")
+          expected_signature = signature_header.sub("sha1=", "")
+
+          # Get raw request body
+          request.body.rewind
+          body = request.body.read
+          request.body.rewind
+
+          # Calculate HMAC signature using SHA1 (Intercom uses SHA1, not SHA256)
+          calculated_signature = OpenSSL::HMAC.hexdigest(
+            OpenSSL::Digest.new("sha1"),
+            @config.client_secret,
+            body
+          )
+
+          # Compare signatures using secure comparison to prevent timing attacks
+          signature_valid = FlowChat::Security.secure_compare(expected_signature, calculated_signature)
+
+          if signature_valid
+            FlowChat.logger.debug { "IntercomApi: Webhook signature validation successful" }
+          else
+            FlowChat.logger.warn { "IntercomApi: Webhook signature validation failed - signatures do not match" }
+          end
+
+          signature_valid
+        rescue FlowChat::Intercom::ConfigurationError
+          raise
+        rescue => e
+          FlowChat.logger.error { "IntercomApi: Error validating webhook signature: #{e.class.name}: #{e.message}" }
+          false
+        end
+
+        def extract_latest_user_message(conversation, event_type)
+          FlowChat.logger.debug { "IntercomApi: Extracting latest user message from #{event_type} event" }
+
+          case event_type
+          when "conversation.user.created"
+            # For new conversations, get the initial message from source
+            source = conversation["source"]
+            if source && (source["body"] || source["attachments"]&.any?)
+              {
+                id: source["id"],
+                body: source["body"],
+                media: extract_attachments(source)
+              }.compact
+            end
+          when "conversation.user.replied"
+            # For replies, get the latest user message from conversation_parts
+            parts = conversation.dig("conversation_parts", "conversation_parts") || []
+
+            # Find the most recent part from a user (not admin)
+            # Note: user type can be "user", "lead", or "contact"
+            user_parts = parts.select do |part|
+              part["part_type"] == "comment" &&
+                %w[user lead contact].include?(part.dig("author", "type"))
+            end
+
+            if user_parts.any?
+              latest_part = user_parts.last
+              {
+                id: latest_part["id"],
+                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 = 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"],
+              conversation_id: context["request.id"],
+              message: prompt,
+              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)
+
+          if response
+            _type, prompt, choices, media = response
+            rendered_message = render_response(prompt, choices, media)
+
+            # For simulator mode, return the response data in the HTTP response
+            # instead of actually sending via Intercom API
+            message_payload = @client.build_reply_payload(rendered_message, context["request.id"])
+
+            simulator_response = {
+              mode: "simulator",
+              webhook_processed: true,
+              would_send: message_payload,
+              message_info: {
+                to: context["request.id"],
+                user_id: context["request.user_id"],
+                timestamp: Time.now.iso8601
+              }
+            }
+
+            @controller.render json: simulator_response
+            nil
+          end
+        end
+
+        def simulate?(context)
+          # Check if simulator mode is enabled for this processor
+          return false unless context["enable_simulator"]
+
+          # 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)
+          @body ||= JSON.parse(request.body.read)
+        end
+
+        def render_response(prompt, choices, media)
+          FlowChat::Intercom::Renderer.new(prompt, choices: choices, media: media).render
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,123 @@
+require "flow_chat/renderers/markdown_support"
+
+module FlowChat
+  module Intercom
+    class Renderer
+      include FlowChat::Renderers::MarkdownSupport
+
+      attr_reader :message, :choices, :media
+
+      def initialize(message, choices: nil, media: nil)
+        @message = message
+        @choices = choices
+        @media = media
+      end
+
+      def render
+        if choices
+          build_selection_message
+        else
+          build_text_message
+        end
+      end
+
+      private
+
+      def build_text_message
+        link, options = render_media
+        [:text, to_html(message.to_s + link), options]
+      end
+
+      def build_selection_message
+        if choices.is_a?(Hash)
+          build_interactive_message(choices)
+        else
+          raise ArgumentError, "choices must be a Hash"
+        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)
+        formatted_message = message.to_s
+
+        unless formatted_message.empty?
+          formatted_message += "\n\n"
+        end
+
+        # Add numbered choices
+        formatted_message += "Please choose:\n"
+        choice_hash.each_with_index do |(key, value), index|
+          formatted_message += "#{index + 1}. #{value}\n"
+        end
+
+        formatted_message += "\nReply with the number of your choice."
+
+        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
+
+      def allowed_tags
+        # Tags supported by Intercom messenger
+        %w[p br b strong i em a ul ol li h1 h2 h3 h4 h5 h6]
+      end
+
+      def allowed_attributes
+        %w[href target]
+      end
+    end
+  end
+end