flow_chat 0.9.0 → 0.10.1

data/lib/flow_chat/telegram/client.rb

@@ -179,6 +179,39 @@ module FlowChat
         api_request("getMe")
       end
 
+      # Get file metadata (including file_path) for an inbound file_id
+      def get_file(file_id)
+        api_request("getFile", {file_id: file_id})
+      end
+
+      # Build the download URL for an inbound file_id
+      def file_url(file_id)
+        # get_file answers nil when the API refused, so this cannot assume a
+        # hash back the way it did while every request returned its envelope.
+        file_path = get_file(file_id)&.dig("result", "file_path")
+        return nil unless file_path
+
+        "https://api.telegram.org/file/bot#{@config.bot_token}/#{file_path}"
+      end
+
+      # Download the raw bytes for an inbound file_id
+      def download_file(file_id)
+        url = file_url(file_id)
+        return nil unless url
+
+        uri = URI(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        response = http.get(uri.request_uri)
+
+        if response.is_a?(Net::HTTPSuccess)
+          response.body
+        else
+          FlowChat.logger.error { "Telegram::Client: File download error: #{response.code}" }
+          nil
+        end
+      end
+
       private
 
       def api_request(method, params = {})
@@ -195,9 +228,7 @@ module FlowChat
         response = http.request(request)
         result = JSON.parse(response.body)
 
-        if result["ok"]
-          FlowChat.logger.debug { "Telegram::Client: API request successful" }
-        else
+        unless result["ok"]
           FlowChat.logger.error { "Telegram::Client: API error - #{result["description"]}" }
           report_api_error(
             "Telegram API error: #{result["description"]}",
@@ -206,8 +237,17 @@ module FlowChat
             error_description: result["description"],
             chat_id: params[:chat_id]
           )
+
+          # nil on a refused send, the contract every other client here keeps.
+          # Answering with the parsed error envelope instead made the failure
+          # indistinguishable from a success to anything upstream:
+          # report_delivery_failure tests the result for nil, so a Telegram
+          # send that Meta refused was reported as delivered and could never
+          # reach on_delivery_failure.
+          return nil
         end
 
+        FlowChat.logger.debug { "Telegram::Client: API request successful" }
         result
       rescue Net::OpenTimeout, Net::ReadTimeout => network_error
         FlowChat.logger.error { "Telegram::Client: Network timeout: #{network_error.class.name}: #{network_error.message}" }
@@ -220,7 +260,10 @@ module FlowChat
           error: error,
           chat_id: params[:chat_id]
         )
-        {"ok" => false, "description" => error.message}
+
+        # nil for the same reason a refused send answers nil above: an
+        # envelope here reads as a delivery to everything upstream.
+        nil
       end
 
       def report_api_error(message, api_method: nil, error_code: nil, error_description: nil, error: nil, chat_id: nil)

data/lib/flow_chat/telegram/configuration.rb

@@ -1,9 +1,9 @@
 module FlowChat
   module Telegram
     class Configuration
-      attr_accessor :bot_token, :secret_token, :name, :skip_signature_validation
+      include FlowChat::NamedConfiguration
 
-      @@configurations = {}
+      attr_accessor :bot_token, :secret_token, :name, :skip_signature_validation
 
       def initialize(name)
         @name = name
@@ -43,46 +43,6 @@ module FlowChat
         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}" }

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

@@ -2,8 +2,6 @@ require "json"
 
 module FlowChat
   module Telegram
-    class ConfigurationError < StandardError; end
-
     module Gateway
       class BotApi
         include FlowChat::Instrumentation
@@ -104,7 +102,7 @@ module FlowChat
 
           extract_message_content!(message, context)
 
-          if context.input.present?
+          if inbound_message?(context)
             instrument(Events::MESSAGE_RECEIVED, {
               from: from["id"].to_s,
               message: context.input,
@@ -155,7 +153,7 @@ module FlowChat
               "latitude" => message["location"]["latitude"],
               "longitude" => message["location"]["longitude"]
             }
-            context.input = FlowChat::Input::LOCATION
+            context.input = ""
           elsif message["photo"]
             # Photos come as array, take highest resolution (last)
             photo = message["photo"].last
@@ -164,9 +162,10 @@ module FlowChat
               file_id: photo["file_id"],
               file_unique_id: photo["file_unique_id"],
               width: photo["width"],
-              height: photo["height"]
+              height: photo["height"],
+              caption: message["caption"]
             }
-            context.input = FlowChat::Input::MEDIA
+            context.input = message["caption"].presence || ""
           elsif message["video"]
             video = message["video"]
             context["request.media"] = {
@@ -176,9 +175,10 @@ module FlowChat
               width: video["width"],
               height: video["height"],
               duration: video["duration"],
-              mime_type: video["mime_type"]
+              mime_type: video["mime_type"],
+              caption: message["caption"]
             }
-            context.input = FlowChat::Input::MEDIA
+            context.input = message["caption"].presence || ""
           elsif message["audio"]
             audio = message["audio"]
             context["request.media"] = {
@@ -188,9 +188,10 @@ module FlowChat
               duration: audio["duration"],
               mime_type: audio["mime_type"],
               title: audio["title"],
-              performer: audio["performer"]
+              performer: audio["performer"],
+              caption: message["caption"]
             }
-            context.input = FlowChat::Input::MEDIA
+            context.input = message["caption"].presence || ""
           elsif message["document"]
             doc = message["document"]
             context["request.media"] = {
@@ -198,9 +199,10 @@ module FlowChat
               file_id: doc["file_id"],
               file_unique_id: doc["file_unique_id"],
               file_name: doc["file_name"],
-              mime_type: doc["mime_type"]
+              mime_type: doc["mime_type"],
+              caption: message["caption"]
             }
-            context.input = FlowChat::Input::MEDIA
+            context.input = message["caption"].presence || ""
           elsif message["voice"]
             voice = message["voice"]
             context["request.media"] = {
@@ -208,9 +210,10 @@ module FlowChat
               file_id: voice["file_id"],
               file_unique_id: voice["file_unique_id"],
               duration: voice["duration"],
-              mime_type: voice["mime_type"]
+              mime_type: voice["mime_type"],
+              caption: message["caption"]
             }
-            context.input = FlowChat::Input::MEDIA
+            context.input = message["caption"].presence || ""
           elsif message["sticker"]
             sticker = message["sticker"]
             context["request.media"] = {
@@ -222,9 +225,10 @@ module FlowChat
               is_animated: sticker["is_animated"],
               is_video: sticker["is_video"],
               emoji: sticker["emoji"],
-              set_name: sticker["set_name"]
+              set_name: sticker["set_name"],
+              caption: message["caption"]
             }
-            context.input = FlowChat::Input::MEDIA
+            context.input = message["caption"].presence || ""
           elsif message["contact"]
             context["request.contact"] = {
               phone_number: message["contact"]["phone_number"],
@@ -232,7 +236,7 @@ module FlowChat
               last_name: message["contact"]["last_name"],
               user_id: message["contact"]["user_id"]
             }
-            context.input = FlowChat::Input::CONTACT
+            context.input = ""
           else
             context.input = ""
           end
@@ -258,15 +262,7 @@ module FlowChat
           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
+          FlowChat::Security.secure_compare(@config.secret_token, provided_token.to_s)
         end
 
         def handle_message_inline(context, controller)
@@ -274,16 +270,38 @@ module FlowChat
           return unless response
 
           _type, prompt, choices, media = response
-          @client.send_message(context["request.id"], prompt, choices: choices, media: media)
+          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: :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
 

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

@@ -1,33 +1,94 @@
 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)
-          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
+          @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
 
-          # Store choices in session for validation
-          if response
-            _, _, choices, _ = response
-            if choices.is_a?(Hash)
-              context.session&.set("telegram_choices", choices)
-            end
+          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
 
-          response
+          @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

data/lib/flow_chat/telegram/renderer.rb

@@ -71,11 +71,19 @@ module FlowChat
         }]
       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: truncate_text(value.to_s, 64),
-            callback_data: key.to_s[0, 64]
+            text: FlowChat::TextTruncator.truncate(value.to_s, 64, measure: :bytes),
+            callback_data: FlowChat::TextTruncator.truncate(key.to_s, 64, measure: :bytes)
           }
         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

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

@@ -57,6 +57,16 @@ module FlowChat
           @context.input = original_choice
         end
 
+        # USSD is deliberately exempt from the fold every other choice mapper
+        # now takes. A numeric keypad can only ever send a position, and
+        # positions are unique by construction, so the relation this resolves
+        # on is already injective - there is no equivalence under which two
+        # choices could collapse into one another.
+        #
+        # Every other mapper has to be *given* that guarantee, by asking
+        # FlowChat::ChoiceTitles to number a set whose titles collide under
+        # its own resolver's fold. Nothing here needs to, and adding aliasing
+        # to this mapper would introduce the very ambiguity it does not have.
         def create_numbered_mapping(choices)
           # Choices are always a hash after normalize_choices
           numbered_choices = {}

data/lib/flow_chat/version.rb

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

data/lib/flow_chat/whatsapp/client.rb

@@ -25,14 +25,21 @@ module FlowChat
 
         # Use renderer to convert to structured response
         response = FlowChat::Whatsapp::Renderer.new(prompt, choices: choices, media: media).render
-        type, content, _options = response
+        _, _, options = response
+
+        # MESSAGE_SENT is instrumented by the gateway, not here. This wrapped
+        # the send in its own instrument block, and ActiveSupport::Notifications
+        # publishes a block event once the block returns whatever it returned -
+        # so the event fired even when the send had failed and this method was
+        # about to answer nil, and fired a second time when the gateway
+        # instrumented the same send. Every subscriber counted a successful
+        # send twice and a failed one once.
+        result = begin
+          # Above the button cap there is no interactive surface that can
+          # carry media (see the renderer), so it rides in options[:media]
+          # and goes out as its own message ahead of the choice message.
+          send_message_payload(build_message_payload(options[:media], to)) if options[:media]
 
-        result = instrument(Events::MESSAGE_SENT, {
-          to: to,
-          message_type: type.to_s,
-          content_length: content.to_s.length,
-          platform: :whatsapp
-        }) do
           message_data = build_message_payload(response, to)
           send_message_payload(message_data)
         end

data/lib/flow_chat/whatsapp/configuration.rb

@@ -1,12 +1,16 @@
 module FlowChat
   module Whatsapp
     class Configuration
+      include FlowChat::NamedConfiguration
+
+      # "Whatsapp" is the constant, "WhatsApp" is the product.
+      def self.configuration_label
+        "WhatsApp"
+      end
+
       attr_accessor :access_token, :phone_number_id, :verify_token, :app_id, :app_secret,
         :webhook_verify_token, :business_account_id, :name, :skip_signature_validation
 
-      # Class-level storage for named configurations
-      @@configurations = {}
-
       def initialize(name)
         @name = name
         @access_token = nil
@@ -60,56 +64,13 @@ module FlowChat
         config
       end
 
-      # Register a named configuration
-      def self.register(name, config)
-        FlowChat.logger.debug { "WhatsApp::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 { "WhatsApp::Configuration: Retrieved configuration '#{name}'" }
-          config
-        else
-          FlowChat.logger.error { "WhatsApp::Configuration: Configuration '#{name}' not found" }
-          raise ArgumentError, "WhatsApp 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 { "WhatsApp::Configuration: Configuration '#{name}' exists: #{exists}" }
-        exists
-      end
-
-      # Get all configuration names
-      def self.configuration_names
-        names = @@configurations.keys
-        FlowChat.logger.debug { "WhatsApp::Configuration: Available configurations: #{names}" }
-        names
-      end
-
-      # Clear all registered configurations (useful for testing)
-      def self.clear_all!
-        FlowChat.logger.debug { "WhatsApp::Configuration: Clearing all registered configurations" }
-        @@configurations.clear
-      end
-
-      # Register this configuration with a name
-      def register_as(name)
-        FlowChat.logger.debug { "WhatsApp::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? &&
+        # Wrapped so a predicate answers true or false rather than nil, which
+        # the bare && chain returns for a missing first field. Intercom and
+        # Telegram already do this and pin it in their tests.
+        is_valid = !!(access_token && !access_token.to_s.empty? &&
           phone_number_id && !phone_number_id.to_s.empty? &&
-          verify_token && !verify_token.to_s.empty?
+          verify_token && !verify_token.to_s.empty?)
 
         FlowChat.logger.debug { "WhatsApp::Configuration: Configuration valid: #{is_valid}" }
         is_valid

data/lib/flow_chat/whatsapp/configuration_error.rb

@@ -0,0 +1,9 @@
+module FlowChat
+  module Whatsapp
+    # Its own file so Zeitwerk can resolve it by name. Declared inside
+    # gateway/cloud_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