flow_chat 0.8.2 → 0.10.0

data/lib/flow_chat/telegram/configuration_error.rb

@@ -0,0 +1,9 @@
+module FlowChat
+  module Telegram
+    # Its own file so Zeitwerk can resolve it by name. Declared inside
+    # gateway/bot_api.rb, which Zeitwerk maps to a different constant, it existed only
+    # once that file had loaded for some other reason, so an application
+    # rescuing it, or a test naming it first, got an uninitialized constant.
+    class ConfigurationError < StandardError; end
+  end
+end

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

@@ -0,0 +1,318 @@
+require "json"
+
+module FlowChat
+  module Telegram
+    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 inbound_message?(context)
+            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 = ""
+          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"],
+              caption: message["caption"]
+            }
+            context.input = message["caption"].presence || ""
+          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"],
+              caption: message["caption"]
+            }
+            context.input = message["caption"].presence || ""
+          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"],
+              caption: message["caption"]
+            }
+            context.input = message["caption"].presence || ""
+          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"],
+              caption: message["caption"]
+            }
+            context.input = message["caption"].presence || ""
+          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"],
+              caption: message["caption"]
+            }
+            context.input = message["caption"].presence || ""
+          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"],
+              caption: message["caption"]
+            }
+            context.input = message["caption"].presence || ""
+          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 = ""
+          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
+
+          FlowChat::Security.secure_compare(@config.secret_token, provided_token.to_s)
+        end
+
+        def handle_message_inline(context, controller)
+          response = @app.call(context)
+          return unless response
+
+          _type, prompt, choices, media = response
+          result = report_delivery_failure(
+            context,
+            to: context["request.id"],
+            message: prompt,
+            gateway: :telegram_bot_api,
+            platform: :telegram
+          ) do
+            @client.send_message(context["request.id"], prompt, choices: choices, media: media)
+          end
+
+          # 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(Events::MESSAGE_SENT, {
+            to: context["request.id"],
+            message: prompt,
+            gateway: :telegram_bot_api,
+            platform: :telegram,
+            platform_message_id: platform_message_id_from(result),
+            duration_ms: context[FlowChat::Instrumentation::DELIVERY_DURATION_KEY]
+          })
+        end
+
+        # The Bot API wraps every answer in an ok/result envelope.
+        def platform_message_id_from(result)
+          return nil unless result.is_a?(Hash)
+
+          result.dig("result", "message_id")
+        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,96 @@
+module FlowChat
+  module Telegram
+    module Middleware
+      # Maps a Telegram reply back to the choice key the flow branches on.
+      #
+      # callback_data is 1-64 *bytes*, not characters, and carries no
+      # character restrictions - Telegram types it as a byte string. Two
+      # things followed from sizing it in characters instead:
+      #
+      # - a label with multibyte characters overflowed the field and was
+      #   rejected by the API, because 64 characters of CJK or emoji is far
+      #   more than 64 bytes;
+      # - two labels sharing their first 64 characters were cut to the same
+      #   callback_data, which then matched neither key and failed the flow's
+      #   own validation, so the choice could not be picked at all.
+      #
+      # Both are gone once the titles are built to a byte budget and a set
+      # that would collide under that budget is numbered. Numbering is what
+      # keeps them apart, and it works here for the same reason it works
+      # everywhere else: a position prefix sits at the front and survives a
+      # cut from the right, where a suffix would be the first thing lost.
+      class ChoiceMapper
+        SESSION_KEY = "telegram.choice_mapping"
+        POSITION_KEY = "telegram.position_mapping"
+
+        # https://core.telegram.org/bots/api#inlinekeyboardbutton
+        CALLBACK_DATA_LIMIT = 64
+
+        def initialize(app)
+          @app = app
+          FlowChat.logger.debug { "Telegram::ChoiceMapper: Initialized" }
+        end
+
+        def call(context)
+          @context = context
+          @session = context.session
+
+          resolve_input
+
+          response = @app.call(context)
+          return response unless response
+
+          type, prompt, choices, media = response
+          choices = remember(choices) if choices.present?
+
+          [type, prompt, choices, media]
+        end
+
+        private
+
+        # Titles first, then positions. A tap sends the title as its
+        # callback_data and a user typing what they read sends the same
+        # string, so both land on the same entry. A position must lose to a
+        # title, or a choice labelled "1" could never be picked.
+        def resolve_input
+          return if @session.nil? || @context.input.blank?
+
+          input = @context.input.to_s
+          resolved = mapping[input] || positions[input]
+          return unless resolved
+
+          FlowChat.logger.info { "Telegram::ChoiceMapper: Resolving #{input} to #{resolved}" }
+          @context.input = resolved
+        end
+
+        def remember(choices)
+          return choices unless @session && choices.is_a?(Hash)
+
+          wire_choices = {}
+          choice_mapping = {}
+
+          titles = FlowChat::ChoiceTitles.build(choices, CALLBACK_DATA_LIMIT, measure: :bytes)
+
+          titles.each do |key, _label, title, _truncated|
+            wire_choices[title] = title
+            choice_mapping[title] = key
+          end
+
+          @session.set(SESSION_KEY, choice_mapping)
+          @session.set(POSITION_KEY, choices.keys.map.with_index(1) { |key, i| [i.to_s, key.to_s] }.to_h)
+
+          FlowChat.logger.debug { "Telegram::ChoiceMapper: Created mapping: #{choice_mapping}" }
+          wire_choices
+        end
+
+        def mapping
+          @session.get(SESSION_KEY) || {}
+        end
+
+        def positions
+          @session.get(POSITION_KEY) || {}
+        end
+      end
+    end
+  end
+end

data/lib/flow_chat/telegram/renderer.rb

@@ -0,0 +1,133 @@
+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
+
+      # callback_data arrives already sized to 64 bytes by
+      # FlowChat::Telegram::Middleware::ChoiceMapper, which is also what made
+      # it distinct from its neighbours - so this cut is a no-op on that path
+      # and exists only for a renderer driven without the mapper.
+      #
+      # It measures bytes, because that is the unit Telegram sizes the field
+      # in. Slicing 64 *characters* both overflowed the field on multibyte
+      # labels and could merge two keys into one callback_data.
+      def build_inline_keyboard(choice_hash)
+        buttons = choice_hash.map do |key, value|
+          {
+            text: FlowChat::TextTruncator.truncate(value.to_s, 64, measure: :bytes),
+            callback_data: FlowChat::TextTruncator.truncate(key.to_s, 64, measure: :bytes)
+          }
+        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/text_truncator.rb

@@ -0,0 +1,75 @@
+module FlowChat
+  # Shortens text to fit a display cap.
+  #
+  # Every renderer that fits a label into a platform's title limit needs this,
+  # and so does every choice mapper that has to know exactly what the user is
+  # looking at: a mapper that reimplemented the rule separately could drift
+  # from what the renderer actually renders, silently reopening the bug this
+  # class exists to prevent.
+  module TextTruncator
+    ELLIPSIS = "..."
+
+    # length is clamped to zero or more before anything else: String#[] with
+    # a negative second argument returns nil rather than raising, so a
+    # negative length (reachable from #number below, whose prefix can eat
+    # more than the whole cap at a small enough cap) would otherwise turn
+    # `nil + "..."` into a NoMethodError deep inside a render.
+    #
+    # Below 3 there is no room left for the ellipsis itself - it alone is 3
+    # characters - so a cap that small hard-truncates with no ellipsis
+    # rather than returning something longer than the cap it was supposed to
+    # respect.
+    # measure picks the unit the cap is expressed in. :bytes exists because
+    # Meta and Telegram both size these fields in bytes rather than
+    # characters - FlowChat::Instagram::Client#measure already draws the same
+    # distinction for message bodies, and for the same reason: a character
+    # count lets multibyte text through to be rejected by the platform.
+    def self.truncate(text, length, measure: :characters)
+      text = text.to_s
+      length = 0 if length.negative?
+      return text if size_of(text, measure) <= length
+
+      ellipsis = size_of(ELLIPSIS, measure)
+      return cut(text, length, measure) if length < ellipsis
+
+      cut(text, length - ellipsis, measure) + ELLIPSIS
+    end
+
+    # Prefixes text with its 1-based position on the rung ("1. ", "10. ",
+    # "100. ") and truncates the label to make room, so the combined string
+    # never exceeds cap. The prefix's length depends on position, so it has
+    # to be computed per choice rather than once for the whole rung: choice
+    # 10 loses one more character to its label than choice 1 does.
+    #
+    # Every renderer and choice mapper that numbers a choice's on-screen
+    # title shares this, for the same reason .truncate is shared: a mapper
+    # that reimplemented the prefix-and-truncate rule separately could drift
+    # from what the renderer actually renders, silently reopening the bug
+    # this class exists to prevent.
+    def self.number(text, position, cap, measure: :characters)
+      prefix = "#{position}. "
+      prefix + truncate(text.to_s, cap - size_of(prefix, measure), measure: measure)
+    end
+
+    def self.size_of(string, measure)
+      (measure == :bytes) ? string.bytesize : string.length
+    end
+    private_class_method :size_of
+
+    # Takes whole characters while they still fit the budget. Slicing bytes
+    # directly would cut a multi-byte sequence in half and hand the platform
+    # a string that is no longer valid UTF-8.
+    def self.cut(string, budget, measure)
+      return "" if budget <= 0
+      return string[0, budget] unless measure == :bytes
+
+      taken = +""
+      string.each_char do |char|
+        break if taken.bytesize + char.bytesize > budget
+        taken << char
+      end
+      taken
+    end
+    private_class_method :cut
+  end
+end