flow_chat 0.8.2 → 0.9.0

data/lib/flow_chat/processor.rb

@@ -0,0 +1,188 @@
+require "middleware"
+
+module FlowChat
+  class Processor
+    include FlowChat::Instrumentation
+
+    attr_reader :custom_middleware_builder, :context, :async_job_class, :async_job_params
+
+    def initialize(controller, enable_simulator: nil)
+      FlowChat.logger.debug { "Processor: Initializing processor for controller #{controller.class.name}" }
+
+      @context = FlowChat::Context.new
+      @context["controller"] = controller
+      @context["enable_simulator"] = enable_simulator.nil? ? (defined?(Rails) && Rails.env.local?) : enable_simulator
+      @custom_middleware_builder = ::Middleware::Builder.new(name: "processor.custom_middleware_builder")
+      @session_options = FlowChat::Config.session
+      @async_job_class = nil
+      @async_job_params = {}
+
+      FlowChat.logger.debug { "Processor: Simulator mode #{@context["enable_simulator"] ? "enabled" : "disabled"}" }
+
+      yield self if block_given?
+
+      FlowChat.logger.debug { "Processor: Initialized #{self.class.name} successfully" }
+    end
+
+    def use_gateway(gateway_class, *args)
+      FlowChat.logger.debug { "Processor: Configuring gateway #{gateway_class.name} with args: #{args.inspect}" }
+      @gateway_class = gateway_class
+      @gateway_args = args
+      self
+    end
+
+    def use_session_store(session_store)
+      raise "Session store must be a class" unless session_store.is_a?(Class)
+      FlowChat.logger.debug { "Processor: Configuring session store #{session_store.name}" }
+      @context["session.store"] = session_store
+      self
+    end
+
+    def use_session_config(boundaries: nil, hash_identifiers: nil, identifier: nil, &block)
+      if block_given?
+        FlowChat.logger.debug { "Processor: Configuring session config with custom proc" }
+        @session_options = @session_options.dup
+        @session_options.session_id_proc = block
+      else
+        FlowChat.logger.debug { "Processor: Configuring session config: boundaries=#{boundaries.inspect}, hash_identifiers=#{hash_identifiers}, identifier=#{identifier}" }
+
+        # Update the session options directly
+        @session_options = @session_options.dup
+        @session_options.boundaries = Array(boundaries) unless boundaries.nil?
+        @session_options.hash_identifiers = hash_identifiers unless hash_identifiers.nil?
+        @session_options.identifier = identifier unless identifier.nil?
+      end
+
+      self
+    end
+
+    def use_middleware(middleware)
+      if block_given?
+        yield custom_middleware_builder
+        return self
+      end
+
+      raise "Middleware must be a class" unless middleware.is_a?(Class)
+      FlowChat.logger.debug { "Processor: Adding custom middleware: #{middleware.name}" }
+      custom_middleware_builder.use middleware
+      self
+    end
+
+    def use_cross_platform_sessions
+      FlowChat.logger.debug { "Processor: Enabling cross-platform sessions via session configuration" }
+      use_session_config(
+        boundaries: [:flow]
+      )
+    end
+
+    def use_url_isolation
+      FlowChat.logger.debug { "Processor: Enabling URL-based session isolation" }
+      current_boundaries = @session_options.boundaries.dup
+      current_boundaries << :url unless current_boundaries.include?(:url)
+      use_session_config(boundaries: current_boundaries)
+    end
+
+    def use_durable_sessions(cross_gateway: false)
+      FlowChat.logger.debug { "Processor: Enabling durable sessions via session configuration" }
+      use_session_config(
+        identifier: :user_id
+      )
+    end
+
+    def use_async(job_class = nil, **job_params)
+      # If no job class provided, use GenericAsyncJob with factory param
+      if job_class.nil?
+        unless job_params.key?(:factory)
+          raise ArgumentError, "When use_async is called without a job class, factory: parameter is required"
+        end
+
+        FlowChat.logger.debug { "Processor: Configuring async processing with GenericAsyncJob for factory '#{job_params[:factory]}'" }
+        @async_job_class = FlowChat::GenericAsyncJob
+      else
+        FlowChat.logger.debug { "Processor: Configuring async processing with job class #{job_class.name} and params: #{job_params.inspect}" }
+        @async_job_class = job_class
+      end
+      @async_job_params = job_params
+
+      self
+    end
+
+    def async_enabled?
+      !@async_job_class.nil?
+    end
+
+    def run(flow_class, action, **options)
+      # Instrument flow execution (this will log via LogSubscriber)
+      instrument(Events::FLOW_EXECUTION_START, {
+        flow_name: flow_class.name.underscore,
+        action: action.to_s,
+        processor_type: self.class.name
+      })
+
+      @context["processor"] = self
+      @context["flow.name"] = flow_class.name.underscore
+      @context["flow.class"] = flow_class
+      @context["flow.action"] = action
+      @context["flow.options"] = options
+
+      FlowChat.logger.debug { "Processor: Context prepared for flow #{flow_class.name}" }
+
+      stack = create_middleware_stack
+      yield stack if block_given?
+
+      FlowChat.logger.debug { "Processor: Executing middleware stack for #{flow_class.name}##{action}" }
+
+      # Instrument flow execution with timing (this will log completion via LogSubscriber)
+      instrument(Events::FLOW_EXECUTION_END, {
+        flow_name: flow_class.name.underscore,
+        action: action.to_s
+      }) do
+        stack.call(@context)
+      end
+    rescue => error
+      FlowChat.logger.error { "Processor: Flow execution failed - #{flow_class.name}##{action}, Error: #{error.class.name}: #{error.message}" }
+      FlowChat.logger.debug { "Processor: Stack trace: #{error.backtrace.join("\n")}" }
+
+      # Instrument flow execution error (this will log error via LogSubscriber)
+      instrument(Events::FLOW_EXECUTION_ERROR, {
+        flow_name: flow_class.name.underscore,
+        action: action.to_s,
+        error_class: error.class.name,
+        error_message: error.message,
+        backtrace: error.backtrace&.first(10)
+      })
+
+      raise
+    end
+
+    protected
+
+    # Helper method for building stacks
+    def create_middleware_stack
+      raise ArgumentError, "Gateway is required. Call use_gateway(gateway_class, *args) before running." unless @gateway_class
+
+      middleware_stack = ::Middleware::Builder.new(name: @gateway_class.name) do |b|
+        # Gateway always comes first
+        b.use @gateway_class, *@gateway_args
+        # Session middleware next. We need to setup our session identifiers
+        b.use FlowChat::Session::Middleware, @session_options
+
+        if @gateway_class.respond_to?(:configure_middleware_stack)
+          FlowChat.logger.debug { "Processor: Using platform specific middleware configuration" }
+          @gateway_class.configure_middleware_stack(b, custom_middleware_builder)
+        else
+          b.use custom_middleware_builder
+          FlowChat.logger.debug { "Processor: Added custom middleware" }
+        end
+
+        # Executor always goes last.
+        # Nothing can execute after it.
+        b.use FlowChat::Executor
+      end
+
+      middleware_stack.inject_logger(FlowChat.logger) if FlowChat::Config.inject_middleware_logger
+
+      middleware_stack
+    end
+  end
+end

data/lib/flow_chat/renderers/markdown_support.rb

@@ -0,0 +1,58 @@
+require "kramdown"
+require "rails-html-sanitizer"
+
+module FlowChat
+  module Renderers
+    module MarkdownSupport
+      def to_html(text)
+        return "" if text.nil?
+
+        html = Kramdown::Document.new(text.to_s, **kramdown_options).to_html.strip
+        sanitize_html(html)
+      end
+
+      def sanitize_html(html)
+        sanitized = self.class.sanitizer.sanitize(
+          html,
+          tags: allowed_tags,
+          attributes: allowed_attributes
+        )
+
+        post_process_html(sanitized)
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def sanitizer
+          @sanitizer ||= Rails::Html::SafeListSanitizer.new
+        end
+      end
+
+      private
+
+      # Override in subclasses to customize Kramdown options
+      # Default uses straight quotes (ASCII 39/34) instead of curly smart quotes
+      def kramdown_options
+        {smart_quotes: [39, 39, 34, 34]}
+      end
+
+      # Override in subclasses to specify allowed HTML tags
+      def allowed_tags
+        %w[b strong i em a code pre]
+      end
+
+      # Override in subclasses to specify allowed HTML attributes
+      def allowed_attributes
+        %w[href]
+      end
+
+      # Override in subclasses to post-process sanitized HTML
+      def post_process_html(html)
+        html
+      end
+    end
+  end
+end

data/lib/flow_chat/session/middleware.rb

@@ -1,3 +1,5 @@
+require "digest"
+
 module FlowChat
   module Session
     class Middleware
@@ -52,6 +54,14 @@ module FlowChat
           return session_id
         end
 
+        # Check for custom session ID proc
+        if @session_options.session_id_proc
+          FlowChat.logger.debug { "Session::Middleware: Using custom session ID proc" }
+          session_id = @session_options.session_id_proc.call(context)
+          FlowChat.logger.debug { "Session::Middleware: Generated custom session ID: #{session_id}" }
+          return session_id
+        end
+
         FlowChat.logger.debug { "Session::Middleware: Building session ID for platform=#{platform}, gateway=#{gateway}, flow=#{flow_name}" }
 
         # Get identifier based on configuration
@@ -65,7 +75,7 @@ module FlowChat
 
       def get_session_identifier(context)
         identifier_type = @session_options.identifier || platform_default_identifier(context)
-        
+
         case identifier_type
         when :request_id
           context["request.id"]
@@ -82,7 +92,7 @@ module FlowChat
 
       def platform_default_identifier(context)
         platform = context["request.platform"]
-        
+
         case platform
         when :whatsapp
           :msisdn
@@ -121,19 +131,26 @@ module FlowChat
         return nil unless request
 
         # Extract host and path for URL boundary
-        host = request.host rescue nil
-        path = request.path rescue nil
+        host = begin
+          request.host
+        rescue
+          nil
+        end
+        path = begin
+          request.path
+        rescue
+          nil
+        end
 
-        # Create a normalized URL identifier: host + path 
+        # Create a normalized URL identifier: host + path
         # e.g., "example.com/api/v1/ussd" or "tenant1.example.com/ussd"
         url_parts = []
         url_parts << host if host.present?
-        url_parts << path.sub(/^\//, '') if path.present? && path != '/'
+        url_parts << path.sub(/^\//, "") if path.present? && path != "/"
 
         # For long URLs, use first part + hash suffix instead of full hash
-        url_identifier = url_parts.join('/').gsub(/[^a-zA-Z0-9._-]/, '_')
+        url_identifier = url_parts.join("/").gsub(/[^a-zA-Z0-9._-]/, "_")
         if url_identifier.length > 50
-          require 'digest'
           # Take first 41 chars + hash suffix to keep it manageable but recognizable
           first_part = url_identifier[0, 41]
           hash_suffix = Digest::SHA256.hexdigest(url_identifier)[0, 8]
@@ -145,7 +162,6 @@ module FlowChat
 
       def hash_identifier(identifier)
         # Use SHA256 but only take first 8 characters for reasonable session IDs
-        require 'digest'
         Digest::SHA256.hexdigest(identifier.to_s)[0, 8]
       end
     end

data/lib/flow_chat/telegram/client.rb

@@ -0,0 +1,240 @@
+require "net/http"
+require "json"
+require "uri"
+
+module FlowChat
+  module Telegram
+    class Client
+      include FlowChat::Instrumentation
+
+      def initialize(config)
+        @config = config
+        FlowChat.logger.info { "Telegram::Client: Initialized Telegram client" }
+      end
+
+      # Main send_message method matching FlowChat pattern
+      def send_message(chat_id, prompt, choices: nil, media: nil)
+        FlowChat.logger.info { "Telegram::Client: Sending message to chat #{chat_id}" }
+
+        response = FlowChat::Telegram::Renderer.new(prompt, choices: choices, media: media).render
+        type, content, options = response
+
+        case type
+        when :text
+          send_text(chat_id, content)
+        when :inline_keyboard
+          send_text_with_keyboard(chat_id, content, options[:keyboard])
+        when :photo
+          send_photo(chat_id, options[:url], caption: content)
+        when :photo_with_keyboard
+          send_photo_with_keyboard(chat_id, options[:url], caption: content, keyboard: options[:keyboard])
+        when :document
+          send_document(chat_id, options[:url], caption: content)
+        when :video
+          send_video(chat_id, options[:url], caption: content)
+        when :audio
+          send_audio(chat_id, options[:url], caption: content)
+        when :voice
+          send_voice(chat_id, options[:url])
+        else
+          send_text(chat_id, content.to_s)
+        end
+      end
+
+      def send_text(chat_id, text, parse_mode: "HTML")
+        api_request("sendMessage", {
+          chat_id: chat_id,
+          text: text,
+          parse_mode: parse_mode
+        }.compact)
+      end
+
+      def send_text_with_keyboard(chat_id, text, keyboard, parse_mode: "HTML")
+        api_request("sendMessage", {
+          chat_id: chat_id,
+          text: text,
+          parse_mode: parse_mode,
+          reply_markup: {inline_keyboard: keyboard}
+        }.compact)
+      end
+
+      def send_photo(chat_id, photo_url_or_id, caption: nil)
+        api_request("sendPhoto", {
+          chat_id: chat_id,
+          photo: photo_url_or_id,
+          caption: caption
+        }.compact)
+      end
+
+      def send_photo_with_keyboard(chat_id, photo_url_or_id, caption: nil, keyboard: nil)
+        api_request("sendPhoto", {
+          chat_id: chat_id,
+          photo: photo_url_or_id,
+          caption: caption,
+          reply_markup: keyboard ? {inline_keyboard: keyboard} : nil
+        }.compact)
+      end
+
+      def send_document(chat_id, document_url_or_id, caption: nil)
+        api_request("sendDocument", {
+          chat_id: chat_id,
+          document: document_url_or_id,
+          caption: caption
+        }.compact)
+      end
+
+      def send_video(chat_id, video_url_or_id, caption: nil)
+        api_request("sendVideo", {
+          chat_id: chat_id,
+          video: video_url_or_id,
+          caption: caption
+        }.compact)
+      end
+
+      def send_audio(chat_id, audio_url_or_id, caption: nil)
+        api_request("sendAudio", {
+          chat_id: chat_id,
+          audio: audio_url_or_id,
+          caption: caption
+        }.compact)
+      end
+
+      def send_voice(chat_id, voice_url_or_id)
+        api_request("sendVoice", {
+          chat_id: chat_id,
+          voice: voice_url_or_id
+        })
+      end
+
+      def answer_callback_query(callback_query_id, text: nil, show_alert: false)
+        api_request("answerCallbackQuery", {
+          callback_query_id: callback_query_id,
+          text: text,
+          show_alert: show_alert
+        }.compact)
+      end
+
+      def edit_message_text(chat_id, message_id, text, keyboard: nil, parse_mode: "HTML")
+        api_request("editMessageText", {
+          chat_id: chat_id,
+          message_id: message_id,
+          text: text,
+          parse_mode: parse_mode,
+          reply_markup: keyboard ? {inline_keyboard: keyboard} : nil
+        }.compact)
+      end
+
+      def delete_message(chat_id, message_id)
+        api_request("deleteMessage", {
+          chat_id: chat_id,
+          message_id: message_id
+        })
+      end
+
+      # Send a chat action (e.g. typing indicator) to a Telegram chat.
+      #
+      # The action lasts ~5 seconds or until the next outbound message.
+      # Valid actions per Telegram Bot API: "typing", "upload_photo",
+      # "record_video", "upload_video", "record_voice", "upload_voice",
+      # "upload_document", "choose_sticker", "find_location",
+      # "record_video_note", "upload_video_note".
+      #
+      # @param chat_id [Integer, String] the target chat id
+      # @param action [String] the chat action to broadcast (default: "typing")
+      # @return [Hash] parsed Telegram API response
+      def send_chat_action(chat_id, action: "typing")
+        api_request("sendChatAction", chat_id: chat_id, action: action)
+      end
+
+      # Show a typing indicator in a Telegram chat.
+      #
+      # Convenience wrapper around `send_chat_action(chat_id, action: "typing")`.
+      # The indicator lasts ~5 seconds or until the next outbound message;
+      # there is no stop-typing call.
+      #
+      # @param chat_id [Integer, String] the target chat id
+      # @return [Hash] parsed Telegram API response
+      def indicate_typing(chat_id)
+        send_chat_action(chat_id, action: "typing")
+      end
+
+      # Webhook management
+      def set_webhook(url, secret_token: nil, allowed_updates: nil)
+        api_request("setWebhook", {
+          url: url,
+          secret_token: secret_token,
+          allowed_updates: allowed_updates || ["message", "callback_query"]
+        }.compact)
+      end
+
+      def delete_webhook
+        api_request("deleteWebhook")
+      end
+
+      def get_webhook_info
+        api_request("getWebhookInfo")
+      end
+
+      def get_me
+        api_request("getMe")
+      end
+
+      private
+
+      def api_request(method, params = {})
+        uri = URI("#{@config.api_base_url}/#{method}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request.body = params.to_json
+
+        FlowChat.logger.debug { "Telegram::Client: API request to #{method}" }
+
+        response = http.request(request)
+        result = JSON.parse(response.body)
+
+        if result["ok"]
+          FlowChat.logger.debug { "Telegram::Client: API request successful" }
+        else
+          FlowChat.logger.error { "Telegram::Client: API error - #{result["description"]}" }
+          report_api_error(
+            "Telegram API error: #{result["description"]}",
+            api_method: method,
+            error_code: result["error_code"],
+            error_description: result["description"],
+            chat_id: params[:chat_id]
+          )
+        end
+
+        result
+      rescue Net::OpenTimeout, Net::ReadTimeout => network_error
+        FlowChat.logger.error { "Telegram::Client: Network timeout: #{network_error.class.name}: #{network_error.message}" }
+        raise network_error
+      rescue => error
+        FlowChat.logger.error { "Telegram::Client: API request exception: #{error.class.name}: #{error.message}" }
+        report_api_error(
+          "Telegram API request exception: #{error.class.name}",
+          api_method: method,
+          error: error,
+          chat_id: params[:chat_id]
+        )
+        {"ok" => false, "description" => error.message}
+      end
+
+      def report_api_error(message, api_method: nil, error_code: nil, error_description: nil, error: nil, chat_id: nil)
+        FlowChat::Instrumentation.report_api_error(
+          message,
+          error: error,
+          platform: :telegram,
+          bot_id: @config.bot_id,
+          api_method: api_method,
+          error_code: error_code,
+          error_description: error_description,
+          chat_id: chat_id
+        )
+      end
+    end
+  end
+end

data/lib/flow_chat/telegram/configuration.rb

@@ -0,0 +1,118 @@
+module FlowChat
+  module Telegram
+    class Configuration
+      attr_accessor :bot_token, :secret_token, :name, :skip_signature_validation
+
+      @@configurations = {}
+
+      def initialize(name)
+        @name = name
+        @bot_token = nil
+        @secret_token = nil
+        @skip_signature_validation = false
+
+        FlowChat.logger.debug { "Telegram::Configuration: Initialized configuration with name: #{name || "anonymous"}" }
+
+        register_as(name) if name.present?
+      end
+
+      def self.from_credentials
+        FlowChat.logger.info { "Telegram::Configuration: Loading configuration from credentials/environment" }
+
+        config = new(nil)
+
+        if defined?(Rails) && Rails.respond_to?(:application) && Rails.application.credentials.telegram
+          FlowChat.logger.debug { "Telegram::Configuration: Loading from Rails credentials" }
+          credentials = Rails.application.credentials.telegram
+          config.bot_token = credentials[:bot_token]
+          config.secret_token = credentials[:secret_token]
+          config.skip_signature_validation = credentials[:skip_signature_validation] || false
+        else
+          FlowChat.logger.debug { "Telegram::Configuration: Loading from environment variables" }
+          config.bot_token = ENV["TELEGRAM_BOT_TOKEN"]
+          config.secret_token = ENV["TELEGRAM_SECRET_TOKEN"]
+          config.skip_signature_validation = ENV["TELEGRAM_SKIP_SIGNATURE_VALIDATION"] == "true"
+        end
+
+        if config.valid?
+          FlowChat.logger.info { "Telegram::Configuration: Configuration loaded successfully" }
+        else
+          FlowChat.logger.warn { "Telegram::Configuration: Incomplete configuration loaded - missing required fields" }
+        end
+
+        config
+      end
+
+      def self.register(name, config)
+        FlowChat.logger.debug { "Telegram::Configuration: Registering configuration '#{name}'" }
+        @@configurations[name.to_sym] = config
+      end
+
+      def self.get(name)
+        config = @@configurations[name.to_sym]
+        if config
+          FlowChat.logger.debug { "Telegram::Configuration: Retrieved configuration '#{name}'" }
+          config
+        else
+          FlowChat.logger.error { "Telegram::Configuration: Configuration '#{name}' not found" }
+          raise ArgumentError, "Telegram configuration '#{name}' not found"
+        end
+      end
+
+      def self.exists?(name)
+        exists = @@configurations.key?(name.to_sym)
+        FlowChat.logger.debug { "Telegram::Configuration: Configuration '#{name}' exists: #{exists}" }
+        exists
+      end
+
+      def self.configuration_names
+        names = @@configurations.keys
+        FlowChat.logger.debug { "Telegram::Configuration: Available configurations: #{names}" }
+        names
+      end
+
+      def self.clear_all!
+        FlowChat.logger.debug { "Telegram::Configuration: Clearing all registered configurations" }
+        @@configurations.clear
+      end
+
+      def register_as(name)
+        FlowChat.logger.debug { "Telegram::Configuration: Registering configuration as '#{name}'" }
+        @name = name.to_sym
+        self.class.register(@name, self)
+        self
+      end
+
+      def valid?
+        is_valid = !!(bot_token && !bot_token.to_s.empty?)
+        FlowChat.logger.debug { "Telegram::Configuration: Configuration valid: #{is_valid}" }
+        is_valid
+      end
+
+      def api_base_url
+        return nil unless bot_token
+        "https://api.telegram.org/bot#{bot_token}"
+      end
+
+      def bot_id
+        bot_token&.split(":")&.first
+      end
+
+      def send_message_url
+        "#{api_base_url}/sendMessage"
+      end
+
+      def set_webhook_url
+        "#{api_base_url}/setWebhook"
+      end
+
+      def get_webhook_info_url
+        "#{api_base_url}/getWebhookInfo"
+      end
+
+      def delete_webhook_url
+        "#{api_base_url}/deleteWebhook"
+      end
+    end
+  end
+end