flow_chat 0.8.2 → 0.9.0

data/lib/flow_chat/telegram/gateway/bot_api.rb

@@ -0,0 +1,300 @@
+require "json"
+
+module FlowChat
+  module Telegram
+    class ConfigurationError < StandardError; end
+
+    module Gateway
+      class BotApi
+        include FlowChat::Instrumentation
+        include FlowChat::GatewayAsyncSupport
+
+        attr_reader :client, :context
+
+        def initialize(app, config = nil)
+          @app = app
+          @config = config || FlowChat::Telegram::Configuration.from_credentials
+          @client = FlowChat::Telegram::Client.new(@config)
+
+          FlowChat.logger.info { "BotApi: Initialized Telegram Bot API gateway" }
+        end
+
+        def call(context)
+          @context = context
+          @controller = context.controller
+          request = @controller.request
+
+          FlowChat.logger.debug {
+            "BotApi: Processing #{begin
+              request.request_method
+            rescue
+              "POST"
+            end} request"
+          }
+
+          # Handle POST webhooks only
+          if request.post?
+            return handle_webhook(context)
+          end
+
+          @controller.head :bad_request
+        end
+
+        # Platform-specific middleware configuration
+        def self.configure_middleware_stack(builder, custom_middleware)
+          FlowChat.logger.debug { "BotApi: Configuring Telegram middleware stack" }
+          builder.use custom_middleware
+          builder.use FlowChat::Telegram::Middleware::ChoiceMapper
+        end
+
+        private
+
+        def handle_webhook(context)
+          begin
+            parse_request_body(@controller.request)
+            FlowChat.logger.debug { "BotApi: Successfully parsed webhook request body" }
+          rescue JSON::ParserError => e
+            FlowChat.logger.error { "BotApi: Failed to parse webhook body: #{e.message}" }
+            return @controller.head :bad_request
+          end
+
+          # Validate webhook signature (skip in background)
+          # Return 200 OK even for invalid signatures to prevent Telegram from retrying
+          unless in_background? || valid_webhook_signature?(@controller.request)
+            FlowChat.logger.warn { "BotApi: Invalid webhook signature - dropping request" }
+            return @controller.head :ok
+          end
+
+          # Process update
+          if @body["message"]
+            process_message(@body["message"], context)
+          elsif @body["callback_query"]
+            process_callback_query(@body["callback_query"], context)
+          else
+            FlowChat.logger.debug { "BotApi: No message or callback_query in update - returning OK" }
+            return @controller.head :ok
+          end
+
+          # Routing: async or inline
+          if should_enqueue_async?
+            enqueue_async_job
+            return @controller.head :ok
+          end
+
+          handle_message_inline(context, @controller)
+          @controller.head :ok
+        end
+
+        def process_message(message, context)
+          chat = message["chat"]
+          from = message["from"]
+
+          context["request.id"] = chat["id"].to_s
+          context["request.user_id"] = from["id"].to_s
+          context["request.user_name"] = [from["first_name"], from["last_name"]].compact.join(" ")
+          context["request.username"] = from["username"]
+          context["request.gateway"] = :telegram_bot_api
+          context["request.platform"] = :telegram
+          context["request.message_id"] = message["message_id"].to_s
+          context["request.timestamp"] = Time.at(message["date"]).iso8601
+          context["request.body"] = @body
+
+          context["telegram.client"] = @client
+          context["telegram.chat_type"] = chat["type"]
+
+          extract_message_content!(message, context)
+
+          if context.input.present?
+            instrument(Events::MESSAGE_RECEIVED, {
+              from: from["id"].to_s,
+              message: context.input,
+              message_type: detect_message_type(message),
+              chat_type: chat["type"]
+            })
+          end
+        end
+
+        def process_callback_query(callback_query, context)
+          from = callback_query["from"]
+          message = callback_query["message"]
+          chat = message["chat"]
+
+          context["request.id"] = chat["id"].to_s
+          context["request.user_id"] = from["id"].to_s
+          context["request.user_name"] = [from["first_name"], from["last_name"]].compact.join(" ")
+          context["request.username"] = from["username"]
+          context["request.gateway"] = :telegram_bot_api
+          context["request.platform"] = :telegram
+          context["request.message_id"] = message["message_id"].to_s
+          context["request.timestamp"] = Time.current.iso8601
+          context["request.body"] = @body
+
+          context["telegram.client"] = @client
+          context["telegram.callback_query_id"] = callback_query["id"]
+          context["telegram.original_message_id"] = message["message_id"]
+          context["telegram.chat_type"] = chat["type"]
+
+          # Input is the callback_data
+          context.input = callback_query["data"]
+
+          # Auto-answer callback query to remove loading indicator
+          @client.answer_callback_query(callback_query["id"])
+
+          instrument(Events::MESSAGE_RECEIVED, {
+            from: from["id"].to_s,
+            message: context.input,
+            message_type: "callback_query"
+          })
+        end
+
+        def extract_message_content!(message, context)
+          if message["text"]
+            context.input = message["text"]
+          elsif message["location"]
+            context["request.location"] = {
+              "latitude" => message["location"]["latitude"],
+              "longitude" => message["location"]["longitude"]
+            }
+            context.input = FlowChat::Input::LOCATION
+          elsif message["photo"]
+            # Photos come as array, take highest resolution (last)
+            photo = message["photo"].last
+            context["request.media"] = {
+              type: :photo,
+              file_id: photo["file_id"],
+              file_unique_id: photo["file_unique_id"],
+              width: photo["width"],
+              height: photo["height"]
+            }
+            context.input = FlowChat::Input::MEDIA
+          elsif message["video"]
+            video = message["video"]
+            context["request.media"] = {
+              type: :video,
+              file_id: video["file_id"],
+              file_unique_id: video["file_unique_id"],
+              width: video["width"],
+              height: video["height"],
+              duration: video["duration"],
+              mime_type: video["mime_type"]
+            }
+            context.input = FlowChat::Input::MEDIA
+          elsif message["audio"]
+            audio = message["audio"]
+            context["request.media"] = {
+              type: :audio,
+              file_id: audio["file_id"],
+              file_unique_id: audio["file_unique_id"],
+              duration: audio["duration"],
+              mime_type: audio["mime_type"],
+              title: audio["title"],
+              performer: audio["performer"]
+            }
+            context.input = FlowChat::Input::MEDIA
+          elsif message["document"]
+            doc = message["document"]
+            context["request.media"] = {
+              type: :document,
+              file_id: doc["file_id"],
+              file_unique_id: doc["file_unique_id"],
+              file_name: doc["file_name"],
+              mime_type: doc["mime_type"]
+            }
+            context.input = FlowChat::Input::MEDIA
+          elsif message["voice"]
+            voice = message["voice"]
+            context["request.media"] = {
+              type: :voice,
+              file_id: voice["file_id"],
+              file_unique_id: voice["file_unique_id"],
+              duration: voice["duration"],
+              mime_type: voice["mime_type"]
+            }
+            context.input = FlowChat::Input::MEDIA
+          elsif message["sticker"]
+            sticker = message["sticker"]
+            context["request.media"] = {
+              type: :sticker,
+              file_id: sticker["file_id"],
+              file_unique_id: sticker["file_unique_id"],
+              width: sticker["width"],
+              height: sticker["height"],
+              is_animated: sticker["is_animated"],
+              is_video: sticker["is_video"],
+              emoji: sticker["emoji"],
+              set_name: sticker["set_name"]
+            }
+            context.input = FlowChat::Input::MEDIA
+          elsif message["contact"]
+            context["request.contact"] = {
+              phone_number: message["contact"]["phone_number"],
+              first_name: message["contact"]["first_name"],
+              last_name: message["contact"]["last_name"],
+              user_id: message["contact"]["user_id"]
+            }
+            context.input = FlowChat::Input::CONTACT
+          else
+            context.input = ""
+          end
+        end
+
+        def detect_message_type(message)
+          return "text" if message["text"]
+          return "location" if message["location"]
+          return "photo" if message["photo"]
+          return "video" if message["video"]
+          return "audio" if message["audio"]
+          return "document" if message["document"]
+          return "voice" if message["voice"]
+          return "sticker" if message["sticker"]
+          return "contact" if message["contact"]
+          "unknown"
+        end
+
+        def valid_webhook_signature?(request)
+          return true if @config.skip_signature_validation
+          return true unless @config.secret_token
+
+          provided_token = request.headers["X-Telegram-Bot-Api-Secret-Token"]
+          return false unless provided_token
+
+          secure_compare(@config.secret_token, provided_token.to_s)
+        end
+
+        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 handle_message_inline(context, controller)
+          response = @app.call(context)
+          return unless response
+
+          _type, prompt, choices, media = response
+          @client.send_message(context["request.id"], prompt, choices: choices, media: media)
+
+          instrument(Events::MESSAGE_SENT, {
+            to: context["request.id"],
+            message: prompt,
+            gateway: :telegram_bot_api,
+            platform: :telegram
+          })
+        end
+
+        def parse_request_body(request)
+          return @body if @body
+
+          if request.body.nil?
+            @body = {}
+          else
+            request.body.rewind if request.body.respond_to?(:rewind)
+            @body = JSON.parse(request.body.read)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+module FlowChat
+  module Telegram
+    module Middleware
+      class ChoiceMapper
+        def initialize(app)
+          @app = app
+        end
+
+        def call(context)
+          input = context.input
+
+          # Check if input matches a stored choice key (for validation/logging)
+          if context.session && input.present?
+            choices = context.session.get("telegram_choices")
+            if choices&.key?(input)
+              FlowChat.logger.debug { "ChoiceMapper: Input '#{input}' is a valid choice key" }
+            end
+          end
+
+          response = @app.call(context)
+
+          # Store choices in session for validation
+          if response
+            _, _, choices, _ = response
+            if choices.is_a?(Hash)
+              context.session&.set("telegram_choices", choices)
+            end
+          end
+
+          response
+        end
+      end
+    end
+  end
+end

data/lib/flow_chat/telegram/renderer.rb

@@ -0,0 +1,125 @@
+require "flow_chat/renderers/markdown_support"
+
+module FlowChat
+  module Telegram
+    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 media && choices
+          build_media_with_keyboard
+        elsif media
+          build_media_message
+        elsif choices
+          build_keyboard_message
+        else
+          build_text_message
+        end
+      end
+
+      private
+
+      def build_text_message
+        [:text, to_html(message), {}]
+      end
+
+      def build_keyboard_message
+        validate_choices!
+        keyboard = build_inline_keyboard(choices)
+        [:inline_keyboard, to_html(message), {keyboard: keyboard}]
+      end
+
+      def build_media_message
+        media_type = media[:type] || :photo
+        url = media[:url] || media[:file_id]
+
+        case media_type.to_sym
+        when :photo
+          [:photo, to_html(message), {url: url}]
+        when :document
+          [:document, to_html(message), {url: url, filename: media[:filename]}]
+        when :video
+          [:video, to_html(message), {url: url}]
+        when :audio
+          [:audio, to_html(message), {url: url}]
+        when :voice
+          [:voice, to_html(message), {url: url}]
+        else
+          # Fallback to text for unsupported types
+          [:text, to_html(message), {}]
+        end
+      end
+
+      def build_media_with_keyboard
+        validate_choices!
+        keyboard = build_inline_keyboard(choices)
+        media_type = media[:type] || :photo
+        url = media[:url] || media[:file_id]
+
+        [:photo_with_keyboard, to_html(message), {
+          url: url,
+          keyboard: keyboard,
+          media_type: media_type.to_sym
+        }]
+      end
+
+      def build_inline_keyboard(choice_hash)
+        buttons = choice_hash.map do |key, value|
+          {
+            text: truncate_text(value.to_s, 64),
+            callback_data: key.to_s[0, 64]
+          }
+        end
+
+        # Layout: 2 buttons per row for <=4 choices, 1 per row for >4
+        if buttons.length <= 4
+          buttons.each_slice(2).to_a
+        else
+          buttons.zip
+        end
+      end
+
+      def validate_choices!
+        unless choices.is_a?(Hash)
+          raise ArgumentError, "choices must be a Hash"
+        end
+      end
+
+      def truncate_text(text, length)
+        return text if text.length <= length
+        text[0, length - 3] + "..."
+      end
+
+      # MarkdownSupport overrides for Telegram-specific behavior
+
+      def allowed_tags
+        # Tags supported by Telegram Bot API HTML mode
+        # Note: p and br are allowed through sanitization but converted to newlines in post_process_html
+        %w[b strong i em u s strike del a code pre blockquote p br]
+      end
+
+      def allowed_attributes
+        %w[href]
+      end
+
+      def post_process_html(html)
+        # Convert <p> tags to text with double newlines (Telegram doesn't support <p>)
+        result = html.gsub(%r{<p>(.*?)</p>}m, '\1' + "\n\n")
+
+        # Convert <br> and <br/> to newlines (Telegram doesn't support <br>)
+        result = result.gsub(/<br\s*\/?>/, "\n")
+
+        # Clean up excessive newlines
+        result.gsub(/\n{3,}/, "\n\n").strip
+      end
+    end
+  end
+end

data/lib/flow_chat/telegram.rb

@@ -0,0 +1,7 @@
+# Telegram integration for FlowChat
+# All files are autoloaded by Zeitwerk based on file path conventions
+
+module FlowChat
+  module Telegram
+  end
+end

data/lib/flow_chat/ussd/gateway/nalo.rb

@@ -3,6 +3,7 @@ module FlowChat
     module Gateway
       class Nalo
         include FlowChat::Instrumentation
+        include FlowChat::GatewayAsyncSupport
 
         attr_reader :context
 
@@ -10,9 +11,15 @@ module FlowChat
           @app = app
         end
 
+        # USSD does not support async processing due to synchronous protocol requirements
+        def async_supported?
+          false
+        end
+
         def call(context)
           @context = context
-          params = context.controller.request.params
+          @controller = context.controller
+          params = @controller.request.params
 
           context["request.id"] = params["USERID"]
           context["request.msisdn"] = FlowChat::PhoneNumberUtil.to_e164(params["MSISDN"])
@@ -21,9 +28,9 @@ module FlowChat
           context["request.timestamp"] = Time.current.iso8601
           context["request.gateway"] = :nalo
           context["request.platform"] = :ussd
-          context["request.network"] = nil
+          context["request.body"] = (params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params.to_h).transform_keys(&:to_s)
           # context["request.type"] = params["MSGTYPE"] ? :initial : :response
-          context.input = params["USERDATA"].presence
+          context.input = params["USERDATA"].presence || ""
 
           # Instrument message received when user provides input using new scalable approach
           if context.input.present?
@@ -49,7 +56,7 @@ module FlowChat
             timestamp: context["request.timestamp"]
           })
 
-          context.controller.render json: {
+          @controller.render json: {
             USERID: params["USERID"],
             MSISDN: params["MSISDN"],
             MSG: render_prompt(prompt, choices, media),
@@ -57,6 +64,19 @@ module FlowChat
           }
         end
 
+        def self.configure_middleware_stack(builder, custom_middleware)
+          FlowChat.logger.debug { "FlowChat::Ussd::Gateway::Nalo: Configuring middleware stack" }
+
+          builder.use FlowChat::Ussd::Middleware::Pagination
+          FlowChat.logger.debug { "FlowChat::Ussd::Gateway::Nalo: Added Ussd::Middleware::Pagination" }
+
+          builder.use custom_middleware
+          FlowChat.logger.debug { "FlowChat::Ussd::Gateway::Nalo: Added custom middleware" }
+
+          builder.use FlowChat::Ussd::Middleware::ChoiceMapper
+          FlowChat.logger.debug { "FlowChat::Ussd::Gateway::Nalo: Added Ussd::Middleware::ChoiceMapper" }
+        end
+
         private
 
         def render_prompt(prompt, choices, media)

data/lib/flow_chat/ussd/middleware/pagination.rb

@@ -21,7 +21,6 @@ module FlowChat
           if intercept?
             FlowChat.logger.info { "Ussd::Pagination: Intercepting request for pagination handling - session #{session_id}" }
             type, prompt = handle_intercepted_request
-            [type, prompt, []]
           else
             # Clear pagination state for new flows
             if pagination_state.present?
@@ -41,8 +40,8 @@ module FlowChat
               end
             end
 
-            [type, prompt, []]
           end
+          [type, prompt, []]
         end
 
         private
@@ -61,15 +60,17 @@ module FlowChat
 
         def handle_intercepted_request
           FlowChat.logger.info { "Ussd::Pagination: Handling paginated request" }
-          start, finish, has_more = calculate_offsets
+          # Cache current_page to avoid multiple calculations
+          page = current_page
+          start, finish, has_more = calculate_offsets_for_page(page)
           type = (pagination_state["type"].to_sym == :terminal && !has_more) ? :terminal : :prompt
           prompt = pagination_state["prompt"][start..finish] + build_pagination_options(type, has_more)
-          set_pagination_state(current_page, start, finish)
+          set_pagination_state(page, start, finish)
 
           # Instrument pagination navigation
           instrument(Events::PAGINATION_TRIGGERED, {
             session_id: @context["session.id"],
-            current_page: current_page,
+            current_page: page,
             total_pages: calculate_total_pages,
             content_length: pagination_state["prompt"].length,
             page_limit: FlowChat::Config.ussd.pagination_page_size,
@@ -113,7 +114,10 @@ module FlowChat
 
         def calculate_offsets
           page = current_page
+          calculate_offsets_for_page(page)
+        end
 
+        def calculate_offsets_for_page(page)
           FlowChat.logger.debug { "Ussd::Pagination: Calculating offsets for page #{page}" }
 
           offset = pagination_state["offsets"][page.to_s]

data/lib/flow_chat/ussd/renderer.rb

@@ -27,7 +27,7 @@ module FlowChat
       def build_media
         return unless media.present?
 
-        media_url = media[:url] || media[:path]
+        media_url = media[:url]
         media_type = media[:type] || :image
 
         # For USSD, we append the media URL to the message

data/lib/flow_chat/version.rb

@@ -1,3 +1,3 @@
 module FlowChat
-  VERSION = "0.8.2"
+  VERSION = "0.9.0"
 end