flow_chat 0.8.2 → 0.9.0

data/lib/flow_chat/http/renderer.rb

@@ -24,18 +24,18 @@ module FlowChat
       def format_choices
         return unless choices.present?
 
-        choices.map { |key, value| { key: key, value: value } }
+        choices.map { |key, value| {key: key, value: value} }
       end
 
       def format_media
         return unless media.present?
 
         {
-          url: media[:url] || media[:path],
+          url: media[:url],
           type: media[:type] || :image,
           caption: media[:caption]
         }.compact
       end
     end
   end
-end 
+end

data/lib/flow_chat/instrumentation/setup.rb

@@ -2,7 +2,7 @@ module FlowChat
   module Instrumentation
     module Setup
       class << self
-        attr_accessor :log_subscriber, :metrics_collector
+        attr_accessor :log_subscriber
 
         # Initialize instrumentation with default subscribers
         def initialize!

data/lib/flow_chat/instrumentation.rb

@@ -35,6 +35,23 @@ module FlowChat
       ActiveSupport::Notifications.instrument(full_event_name, enriched_payload, &block)
     end
 
+    # Shared helper for reporting API errors with instrumentation and Rails.error
+    # @param message [String] Error message
+    # @param error [Exception, nil] Original exception if available
+    # @param context [Hash] Platform-specific error context (must include :platform)
+    def self.report_api_error(message, error: nil, **context)
+      error_context = context.compact
+
+      # Instrument for custom subscribers
+      instrument(Events::API_ERROR, error_context.merge(message: message))
+
+      # Report to Rails.error if available
+      if defined?(Rails) && Rails.respond_to?(:error) && Rails.error.respond_to?(:report)
+        exception = error || StandardError.new(message)
+        Rails.error.report(exception, handled: true, context: error_context)
+      end
+    end
+
     # Predefined event names for consistency
     module Events
       # Core framework events
@@ -61,12 +78,18 @@ module FlowChat
       WEBHOOK_FAILED = "webhook.failed"
       API_REQUEST = "api.request"
       MEDIA_UPLOAD = "media.upload"
+      API_ERROR = "api.error"
 
       PAGINATION_TRIGGERED = "pagination.triggered"
 
       # Middleware events
       MIDDLEWARE_BEFORE = "middleware.before"
       MIDDLEWARE_AFTER = "middleware.after"
+
+      # Conversation management events (for Intercom and similar platforms)
+      CONVERSATION_ASSIGNED = "conversation.assigned"
+      CONVERSATION_TAGGED = "conversation.tagged"
+      CONVERSATION_STATE_CHANGED = "conversation.state_changed"
     end
   end
 end

data/lib/flow_chat/intercom/client.rb

@@ -0,0 +1,155 @@
+require "intercom"
+require "json"
+require "reverse_markdown"
+
+module FlowChat
+  module Intercom
+    # Configuration-related errors
+    class ConfigurationError < StandardError; end
+
+    # Rate limiting error
+    class RateLimitError < StandardError
+      attr_reader :retry_after
+
+      def initialize(message, retry_after = nil)
+        super(message)
+        @retry_after = retry_after
+      end
+    end
+
+    class Client
+      include FlowChat::Instrumentation
+
+      attr_reader :intercom
+      attr_accessor :app_id
+
+      # Convert HTML from Intercom messages to Markdown
+      def self.parse_html(html)
+        ReverseMarkdown.convert(html.to_s).strip.presence || ""
+      end
+
+      def parse_message(html)
+        self.class.parse_html(html)
+      end
+
+      def initialize(config)
+        @config = config
+        @intercom = ::Intercom::Client.new(token: @config.access_token)
+        FlowChat.logger.info { "Intercom::Client: Initialized Intercom client" }
+        FlowChat.logger.debug { "Intercom::Client: API base URL: #{@config.api_base_url}" }
+      end
+
+      # Send a reply to a conversation
+      # @param conversation_id [String] Conversation ID
+      # @param response [Array] FlowChat response array [type, content, options]
+      # @return [Hash] API response or nil on error
+      def send_message(conversation_id, prompt, choices: nil, media: nil)
+        FlowChat.logger.info { "Intercom::Client: Sending message to conversation #{conversation_id}" }
+        FlowChat.logger.debug { "Intercom::Client: Message content: '#{prompt.to_s.truncate(100)}'" }
+
+        # Use renderer to convert to structured response
+        response = FlowChat::Intercom::Renderer.new(prompt, choices: choices, media: media).render
+        type, content, _ = response
+
+        result = instrument(Events::MESSAGE_SENT, {
+          to: conversation_id,
+          message_type: type.to_s,
+          content_length: content.to_s.length,
+          platform: :intercom
+        }) do
+          # Determine message type based on response type
+          message_type = case type
+          when :note
+            "note"
+          else
+            "comment"
+          end
+
+          # Send using official gem
+          reply = intercom.conversations.reply(
+            id: conversation_id,
+            type: "admin",
+            admin_id: @config.admin_id.to_s,
+            message_type: message_type,
+            body: content.to_s
+          )
+
+          reply.to_hash
+        end
+
+        if result
+          message_id = result["id"]
+          FlowChat.logger.debug { "Intercom::Client: Message sent successfully to conversation #{conversation_id}, message_id: #{message_id}" }
+        else
+          FlowChat.logger.error { "Intercom::Client: Failed to send message to conversation #{conversation_id}" }
+        end
+
+        result
+      rescue ::Intercom::ResourceNotFound => e
+        FlowChat.logger.error { "Intercom::Client: Conversation not found: #{e.message}" }
+        report_api_error("Intercom conversation not found", error: e, conversation_id: conversation_id)
+        nil
+      rescue ::Intercom::AuthenticationError => e
+        FlowChat.logger.error { "Intercom::Client: Authentication failed - check access token" }
+        report_api_error("Intercom authentication failed", error: e, conversation_id: conversation_id)
+        raise ConfigurationError, "Invalid Intercom access token"
+      rescue ::Intercom::RateLimitExceeded
+        retry_after = 60
+        FlowChat.logger.warn { "Intercom::Client: Rate limit exceeded - retry after #{retry_after}s" }
+        raise RateLimitError.new("Intercom API rate limit exceeded", retry_after)
+      rescue ::Intercom::ServerError => e
+        FlowChat.logger.error { "Intercom::Client: Server error: #{e.message}" }
+        report_api_error("Intercom server error", error: e, conversation_id: conversation_id)
+        nil
+      rescue => e
+        FlowChat.logger.error { "Intercom::Client: API request exception: #{e.class.name}: #{e.message}" }
+        report_api_error("Intercom API request exception: #{e.class.name}", error: e, conversation_id: conversation_id)
+        nil
+      end
+
+      # Build reply payload for Intercom API
+      # This method is exposed so the gateway can use it for simulator mode
+      def build_reply_payload(response, conversation_id)
+        type, content, _ = response
+
+        case type
+        when :text
+          {
+            message_type: "comment",
+            type: "admin",
+            admin_id: @config.admin_id.to_s,
+            body: content.to_s
+          }
+        when :note
+          {
+            message_type: "note",
+            type: "admin",
+            admin_id: @config.admin_id.to_s,
+            body: content.to_s
+          }
+        else
+          # Default to comment
+          {
+            message_type: "comment",
+            type: "admin",
+            admin_id: @config.admin_id.to_s,
+            body: content.to_s
+          }
+        end
+      end
+
+      private
+
+      def report_api_error(message, error: nil, conversation_id: nil)
+        FlowChat::Instrumentation.report_api_error(
+          message,
+          error: error,
+          platform: :intercom,
+          app_id: @app_id,
+          conversation_id: conversation_id,
+          admin_id: @config.admin_id
+        )
+      end
+    end
+  end
+end

data/lib/flow_chat/intercom/configuration.rb

@@ -0,0 +1,149 @@
+module FlowChat
+  module Intercom
+    class Configuration
+      attr_accessor :access_token, :client_secret, :admin_id, :name, :skip_signature_validation
+
+      # Class-level storage for named configurations
+      @@configurations = {}
+
+      def initialize(name)
+        @name = name
+        @access_token = nil
+        @client_secret = nil
+        @admin_id = nil
+        @skip_signature_validation = false
+
+        FlowChat.logger.debug { "Intercom::Configuration: Initialized configuration with name: #{name || "anonymous"}" }
+
+        register_as(name) if name.present?
+      end
+
+      # Load configuration from Rails credentials or environment variables
+      def self.from_credentials
+        FlowChat.logger.info { "Intercom::Configuration: Loading configuration from credentials/environment" }
+
+        config = new(nil)
+
+        if defined?(Rails) && Rails.application.credentials.intercom
+          FlowChat.logger.debug { "Intercom::Configuration: Loading from Rails credentials" }
+          credentials = Rails.application.credentials.intercom
+          config.access_token = credentials[:access_token]
+          config.client_secret = credentials[:client_secret]
+          config.admin_id = credentials[:admin_id]
+          config.skip_signature_validation = credentials[:skip_signature_validation] || false
+        else
+          FlowChat.logger.debug { "Intercom::Configuration: Loading from environment variables" }
+          # Fallback to environment variables
+          config.access_token = ENV["INTERCOM_ACCESS_TOKEN"]
+          config.client_secret = ENV["INTERCOM_CLIENT_SECRET"]
+          config.admin_id = ENV["INTERCOM_ADMIN_ID"]
+          config.skip_signature_validation = ENV["INTERCOM_SKIP_SIGNATURE_VALIDATION"] == "true"
+        end
+
+        if config.valid?
+          FlowChat.logger.info { "Intercom::Configuration: Configuration loaded successfully" }
+        else
+          FlowChat.logger.warn { "Intercom::Configuration: Incomplete configuration loaded - missing required fields" }
+        end
+
+        config
+      end
+
+      # Register a named configuration
+      def self.register(name, config)
+        FlowChat.logger.debug { "Intercom::Configuration: Registering configuration '#{name}'" }
+        @@configurations[name.to_sym] = config
+      end
+
+      # Get a named configuration
+      def self.get(name)
+        config = @@configurations[name.to_sym]
+        if config
+          FlowChat.logger.debug { "Intercom::Configuration: Retrieved configuration '#{name}'" }
+          config
+        else
+          FlowChat.logger.error { "Intercom::Configuration: Configuration '#{name}' not found" }
+          raise ArgumentError, "Intercom configuration '#{name}' not found"
+        end
+      end
+
+      # Check if a named configuration exists
+      def self.exists?(name)
+        exists = @@configurations.key?(name.to_sym)
+        FlowChat.logger.debug { "Intercom::Configuration: Configuration '#{name}' exists: #{exists}" }
+        exists
+      end
+
+      # Get all configuration names
+      def self.configuration_names
+        names = @@configurations.keys
+        FlowChat.logger.debug { "Intercom::Configuration: Available configurations: #{names}" }
+        names
+      end
+
+      # Clear all registered configurations (useful for testing)
+      def self.clear_all!
+        FlowChat.logger.debug { "Intercom::Configuration: Clearing all registered configurations" }
+        @@configurations.clear
+      end
+
+      # Register this configuration with a name
+      def register_as(name)
+        FlowChat.logger.debug { "Intercom::Configuration: Registering configuration as '#{name}'" }
+        @name = name.to_sym
+        self.class.register(@name, self)
+        self
+      end
+
+      def valid?
+        is_valid = !!(access_token && !access_token.to_s.empty? && admin_id && !admin_id.to_s.empty?)
+
+        FlowChat.logger.debug { "Intercom::Configuration: Configuration valid: #{is_valid}" }
+        is_valid
+      end
+
+      # API endpoints
+      def api_base_url
+        "https://api.intercom.io"
+      end
+
+      def conversations_url(conversation_id = nil)
+        if conversation_id
+          "#{api_base_url}/conversations/#{conversation_id}"
+        else
+          "#{api_base_url}/conversations"
+        end
+      end
+
+      def conversation_reply_url(conversation_id)
+        "#{conversations_url(conversation_id)}/reply"
+      end
+
+      def conversation_parts_url(conversation_id)
+        "#{conversations_url(conversation_id)}/parts"
+      end
+
+      def conversation_tags_url(conversation_id, tag_id = nil)
+        if tag_id
+          "#{conversations_url(conversation_id)}/tags/#{tag_id}"
+        else
+          "#{conversations_url(conversation_id)}/tags"
+        end
+      end
+
+      def admins_url
+        "#{api_base_url}/admins"
+      end
+
+      # Headers for API requests
+      def api_headers
+        {
+          "Authorization" => "Bearer #{access_token}",
+          "Content-Type" => "application/json",
+          "Accept" => "application/json",
+          "Intercom-Version" => "2.11"
+        }
+      end
+    end
+  end
+end