flow_chat 0.8.1 → 0.9.0

data/lib/flow_chat/generic_async_job.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module FlowChat
+  # Generic background job that uses the Factory pattern
+  # Automatically used when use_async is called without a job class
+  #
+  # Example:
+  #   # In webhook controller
+  #   processor = FlowChat::Processor.new(self) do |config|
+  #     config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+  #     config.use_session_store FlowChat::Session::CacheSessionStore
+  #     config.use_async(factory: :whatsapp)  # No job class - uses GenericAsyncJob
+  #   end
+  #
+  #   # Background job executes:
+  #   FlowChat::Factory.execute(:whatsapp, controller: controller)
+  class GenericAsyncJob < AsyncJob
+    def execute(controller, factory:, **job_params)
+      FlowChat.logger.debug { "GenericAsyncJob: Executing factory '#{factory}' with params: #{job_params.inspect}" }
+
+      unless FlowChat::Factory.registered?(factory)
+        raise FlowChat::Factory::FactoryNotFoundError, "Factory '#{factory}' not registered"
+      end
+
+      FlowChat::Factory.execute(factory, controller: controller)
+
+      FlowChat.logger.debug { "GenericAsyncJob: Factory '#{factory}' executed successfully" }
+    end
+  end
+end

data/lib/flow_chat/http/gateway/simple.rb

@@ -0,0 +1,125 @@
+module FlowChat
+  module Http
+    class ConfigurationError < StandardError; end
+
+    module Gateway
+      class Simple
+        include FlowChat::Instrumentation
+        include FlowChat::GatewayAsyncSupport
+
+        attr_reader :context
+
+        def initialize(app, user_params)
+          @app = app
+          @user_params = user_params
+
+          validate_user_params!
+        end
+
+        def call(context)
+          @context = context
+          @controller = context.controller
+          params = @controller.request.params
+          request = @controller.request
+
+          # Validate request method
+          unless request.get? || request.post?
+            @controller.head :bad_request
+            return
+          end
+
+          # Set request information from user_params
+          context["request.id"] = @user_params[:session_id]
+          context["request.user_id"] = @user_params[:user_id]
+          context["request.user_name"] = @user_params[:name] if @user_params[:name]
+          context["request.msisdn"] = @user_params[:msisdn] if @user_params[:msisdn]
+          context["request.email"] = @user_params[:email] if @user_params[:email]
+          context["request.message_id"] = SecureRandom.uuid
+          context["request.timestamp"] = Time.current.iso8601
+          context["request.gateway"] = :http_simple
+          context["request.platform"] = :http
+          context["request.body"] = (params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params.to_h).transform_keys(&:to_s)
+
+          # HTTP-specific request metadata
+          context["http.method"] = request.method
+          context["http.path"] = request.path
+          context["http.user_agent"] = request.user_agent
+          context.input = params["input"].presence || ""
+
+          # Instrument message received when user provides input
+          if context.input.present?
+            instrument(Events::MESSAGE_RECEIVED, {
+              from: context["request.user_id"],
+              message: context.input,
+              timestamp: context["request.timestamp"]
+            })
+          end
+
+          # Determine routing: async enqueue, background execute, or inline
+          if should_enqueue_async?
+            # HTTP request with async enabled → enqueue job and return immediately
+            enqueue_async_job
+            @controller.render json: {status: "processing"}
+          else
+            # Background OR inline → process message
+            # Process the request
+            response = @app.call(context)
+
+            # Handle nil response (e.g., from middleware that handles the response itself)
+            unless response
+              return @controller.render json: {
+                type: :skip,
+                session_id: context["request.id"],
+                user_id: context["request.user_id"],
+                timestamp: context["request.timestamp"]
+              }
+            end
+
+            type, prompt, choices, media = response
+
+            # Instrument message sent
+            instrument(Events::MESSAGE_SENT, {
+              to: context["request.user_id"],
+              session_id: context["request.id"],
+              message: context.input || "",
+              message_type: (type == :prompt) ? "prompt" : "terminal",
+              gateway: :http_simple,
+              platform: :http,
+              content_length: prompt.to_s.length,
+              timestamp: context["request.timestamp"]
+            })
+
+            # Render response as JSON
+            response_data = render_response(type, prompt, choices, media)
+            @controller.render json: response_data
+          end
+        end
+
+        private
+
+        def validate_user_params!
+          required_keys = [:session_id, :user_id]
+
+          required_keys.each do |key|
+            unless @user_params.key?(key)
+              raise FlowChat::Http::ConfigurationError,
+                "HTTP Simple gateway requires :#{key} in user_params"
+            end
+          end
+        end
+
+        def render_response(type, prompt, choices, media)
+          rendered = FlowChat::Http::Renderer.new(prompt, choices: choices, media: media).render
+
+          {
+            type: type,
+            session_id: context["request.id"],
+            user_id: context["request.user_id"],
+            timestamp: context["request.timestamp"],
+            **rendered
+          }
+        end
+      end
+    end
+  end
+end

data/lib/flow_chat/http/renderer.rb

@@ -0,0 +1,41 @@
+module FlowChat
+  module Http
+    class Renderer
+      attr_reader :prompt, :choices, :media
+
+      def initialize(prompt, choices: nil, media: nil)
+        @prompt = prompt
+        @choices = choices
+        @media = media
+      end
+
+      def render = build_response
+
+      private
+
+      def build_response
+        {
+          message: prompt,
+          choices: format_choices,
+          media: format_media
+        }.compact
+      end
+
+      def format_choices
+        return unless choices.present?
+
+        choices.map { |key, value| {key: key, value: value} }
+      end
+
+      def format_media
+        return unless media.present?
+
+        {
+          url: media[:url],
+          type: media[:type] || :image,
+          caption: media[:caption]
+        }.compact
+      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

@@ -8,9 +8,11 @@ module FlowChat
     def instrument(event_name, payload = {}, &block)
       enriched_payload = payload&.dup || {}
       if respond_to?(:context) && context
+        enriched_payload[:request_id] = context["request.id"] if context["request.id"]
         enriched_payload[:session_id] = context["session.id"] if context["session.id"]
         enriched_payload[:flow_name] = context["flow.name"] if context["flow.name"]
         enriched_payload[:gateway] = context["request.gateway"] if context["request.gateway"]
+        enriched_payload[:platform] = context["request.platform"] if context["request.platform"]
       end
 
       self.class.instrument(event_name, enriched_payload, &block)
@@ -33,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
@@ -59,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