flow_chat 0.9.0 → 0.10.1

data/lib/flow_chat/messenger/client.rb

@@ -0,0 +1,264 @@
+require "net/http"
+require "json"
+require "uri"
+
+module FlowChat
+  module Messenger
+    class Client
+      include FlowChat::Instrumentation
+
+      def initialize(config)
+        @config = config
+        FlowChat.logger.info { "Messenger::Client: Initialized for account #{@config.account_id}" }
+      end
+
+      # @param tag [String, nil] a Meta message tag (e.g. "HUMAN_AGENT") that
+      #   extends the free-form send window beyond 24 hours. The application
+      #   decides when a send qualifies; this only carries the value through
+      #   to every part of the send. Passed through unvalidated: Meta accepts
+      #   only HUMAN_AGENT as of 27 April 2026 and rejects anything else with
+      #   error 100, clearly enough that an allowlist here would only be one
+      #   more thing to keep in sync with Meta's own set.
+      def send_message(recipient_id, prompt, choices: nil, media: nil, tag: nil)
+        response = renderer_class.new(prompt, choices: choices, media: media).render
+        type, content, 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.
+        deliver(recipient_id, type, content, options, tag)
+      end
+
+      def send_text(recipient_id, text, tag: nil)
+        send_message(recipient_id, text, tag: tag)
+      end
+
+      # Shows the person a typing bubble while a turn is being worked out.
+      #
+      # Meta clears it when the next message arrives or after about twenty
+      # seconds, whichever comes first, so a caller holding one open for longer
+      # has to repeat it.
+      #
+      # Inherited by Instagram rather than overridden there. Meta documents
+      # sender actions under the Messenger Platform and lists only react and
+      # unreact for Instagram, but an Instagram send of typing_on is accepted
+      # and answered with the recipient id, same as Messenger. Confirmed
+      # against a live account, since the reference does not settle it.
+      def indicate_typing(recipient_id)
+        post_json(@config.messages_url, {recipient: {id: recipient_id}, sender_action: "typing_on"})
+      end
+
+      # Uploads a file for reuse and returns the id Meta assigned it.
+      def upload_media(url, type: :image)
+        payload = {
+          message: {
+            attachment: {
+              type: type.to_s,
+              payload: {url: url, is_reusable: true}
+            }
+          }
+        }
+
+        result = post_json(@config.attachment_upload_url, payload)
+        result && result["attachment_id"]
+      end
+
+      private
+
+      def renderer_class
+        FlowChat::Messenger::Renderer
+      end
+
+      def platform
+        :messenger
+      end
+
+      def limits
+        FlowChat::Config.messenger
+      end
+
+      # Anything over the platform's cap is rejected whole rather than trimmed by
+      # Meta, so long text goes as several messages. Only the last result is
+      # returned: it carries the id of the message the user ends up looking at.
+      #
+      # Media rides in options[:media] on every rung except :attachment, where
+      # it already is the message: it goes out as its own send, ahead of the
+      # choice message, because the choice surface is rendered exactly as it
+      # would be with no media at all. Every part - the media and every chunk
+      # of the choice message - carries the same tag.
+      def deliver(recipient_id, type, content, options, tag)
+        post_media(recipient_id, options[:media], tag) if options[:media]
+
+        case type
+        when :text
+          split_text(content).map { |chunk| post_message(recipient_id, {text: chunk}, tag) }.last
+        when :quick_replies
+          chunks = split_text(content)
+          # Quick replies belong on the final chunk, next to the question.
+          chunks[0..-2].each { |chunk| post_message(recipient_id, {text: chunk}, tag) }
+          post_message(recipient_id, {text: chunks.last, quick_replies: options[:quick_replies]}, tag)
+        when :carousel
+          post_body_text(recipient_id, content, tag)
+          post_message(recipient_id, {
+            attachment: {
+              type: "template",
+              payload: {template_type: "generic", elements: options[:elements]}
+            }
+          }, tag)
+        when :attachment
+          post_body_text(recipient_id, content, tag)
+          post_media(recipient_id, options, tag)
+        end
+      end
+
+      # content on these two branches is the numbered body Instagram's
+      # always_number? forces (or, on :attachment, just the flow's own
+      # message) - either can run over the platform's text cap on its own,
+      # with no relation to the template or attachment that follows, so it
+      # is split exactly like a plain text send rather than posted whole.
+      def post_body_text(recipient_id, content, tag)
+        return unless content.present?
+
+        split_text(content).each { |chunk| post_message(recipient_id, {text: chunk}, tag) }
+      end
+
+      def post_media(recipient_id, media_options, tag)
+        attachment_payload = media_options[:url] ? {url: media_options[:url], is_reusable: true} : {attachment_id: media_options[:attachment_id]}
+        post_message(recipient_id, {
+          attachment: {type: media_options[:type].to_s, payload: attachment_payload}
+        }, tag)
+      end
+
+      def post_message(recipient_id, message, tag)
+        payload = {recipient: {id: recipient_id}, message: message}
+
+        # The tag branch is not gated on messaging_type?: Instagram never
+        # documents RESPONSE, but it does document MESSAGE_TAG with
+        # HUMAN_AGENT, so a tagged send needs the field there too even
+        # though an untagged Instagram send omits it entirely.
+        if tag
+          payload[:messaging_type] = "MESSAGE_TAG"
+          payload[:tag] = tag
+        elsif messaging_type?
+          payload[:messaging_type] = "RESPONSE"
+        end
+
+        post_json(@config.messages_url, payload)
+      end
+
+      # Messenger documents messaging_type as required on a send. Instagram's
+      # reference does not mention it at all, so Instagram omits it rather than
+      # sending a parameter Meta never documented for that surface.
+      def messaging_type?
+        true
+      end
+
+      # Splits on whitespace so a word is never cut in half. Measured with the
+      # platform's own unit, which is bytes on Instagram and characters here.
+      #
+      # A single piece that is itself too large to fit in one chunk (a long
+      # URL, most often) cannot be handled by that whitespace splitting
+      # alone: with no smaller boundary inside it to break on, it would
+      # otherwise ride through untouched as one chunk over the cap, exactly
+      # the case this method exists to prevent. #hard_split below breaks it
+      # up directly.
+      def split_text(text)
+        limit = limits.max_text_length
+        return [text.to_s] if measure(text.to_s) <= limit
+
+        chunks = []
+        current = ""
+
+        text.to_s.split(/(\s+)/).each do |piece|
+          if measure(piece) > limit
+            chunks << current.strip if current.present?
+            oversized_chunks = hard_split(piece.strip, limit)
+            chunks.concat(oversized_chunks[0..-2])
+            current = oversized_chunks.last.to_s
+          elsif measure(current + piece) > limit && current.present?
+            chunks << current.strip
+            current = piece.lstrip
+          else
+            current += piece
+          end
+        end
+
+        chunks << current.strip if current.strip.present?
+        chunks
+      end
+
+      # Breaks a single oversized piece into cap-sized chunks one character
+      # at a time, so the cut always lands on a character boundary. Never a
+      # byte offset: on Instagram, where the cap is measured in bytes, a
+      # multibyte character sliced by byte position would leave one half a
+      # valid UTF-8 sequence and the other invalid, and #measure has no way
+      # to tell that apart from a character that legitimately does not fit.
+      def hard_split(piece, limit)
+        chunks = []
+        current = ""
+
+        piece.each_char do |char|
+          if current.present? && measure(current + char) > limit
+            chunks << current
+            current = char
+          else
+            current += char
+          end
+        end
+
+        chunks << current if current.present?
+        chunks
+      end
+
+      def measure(string)
+        string.length
+      end
+
+      def post_json(url, payload)
+        uri = URI(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+
+        request = Net::HTTP::Post.new(uri)
+        @config.api_headers.each { |key, value| request[key] = value }
+        request.body = payload.to_json
+
+        response = http.request(request)
+
+        if response.is_a?(Net::HTTPSuccess)
+          JSON.parse(response.body)
+        else
+          FlowChat.logger.error { "#{self.class.name}: API request failed - #{response.code}: #{response.body}" }
+          report_api_error(
+            "#{platform} API request failed",
+            response_code: response.code,
+            response_body: response.body
+          )
+          nil
+        end
+      rescue Net::OpenTimeout, Net::ReadTimeout => network_error
+        FlowChat.logger.error { "#{self.class.name}: Network timeout: #{network_error.class.name}" }
+        raise network_error
+      end
+
+      # FlowChat::Instrumentation only defines report_api_error at the module
+      # level (FlowChat::Instrumentation.report_api_error), not as an instance
+      # method, so it is not inherited through `include`. Every client that
+      # wants the shorthand defines its own wrapper; this mirrors the one in
+      # whatsapp/client.rb.
+      def report_api_error(message, response_code: nil, response_body: nil, error: nil)
+        FlowChat::Instrumentation.report_api_error(
+          message,
+          error: error,
+          platform: platform,
+          account_id: @config.account_id,
+          response_code: response_code,
+          response_body: response_body
+        )
+      end
+    end
+  end
+end

data/lib/flow_chat/messenger/configuration.rb

@@ -0,0 +1,103 @@
+module FlowChat
+  module Messenger
+    class Configuration
+      include FlowChat::NamedConfiguration
+
+      attr_accessor :access_token, :page_id, :verify_token, :app_id, :app_secret,
+        :name, :skip_signature_validation
+
+      def initialize(name)
+        @name = name
+        @access_token = nil
+        @page_id = nil
+        @verify_token = nil
+        @app_id = nil
+        @app_secret = nil
+        @skip_signature_validation = false
+
+        FlowChat.logger.debug { "Messenger::Configuration: Initialized configuration with name: #{name || "anonymous"}" }
+
+        register_as(name) if name.present?
+      end
+
+      def self.from_credentials
+        FlowChat.logger.info { "Messenger::Configuration: Loading configuration from credentials/environment" }
+
+        config = new(nil)
+
+        if defined?(Rails) && Rails.respond_to?(:application) && Rails.application&.credentials&.messenger
+          FlowChat.logger.debug { "Messenger::Configuration: Loading from Rails credentials" }
+          credentials = Rails.application.credentials.messenger
+          config.access_token = credentials[:access_token]
+          config.page_id = credentials[:page_id]
+          config.verify_token = credentials[:verify_token]
+          config.app_id = credentials[:app_id]
+          config.app_secret = credentials[:app_secret]
+          config.skip_signature_validation = credentials[:skip_signature_validation] || false
+        else
+          FlowChat.logger.debug { "Messenger::Configuration: Loading from environment variables" }
+          config.access_token = ENV["MESSENGER_ACCESS_TOKEN"]
+          config.page_id = ENV["MESSENGER_PAGE_ID"]
+          config.verify_token = ENV["MESSENGER_VERIFY_TOKEN"]
+          config.app_id = ENV["MESSENGER_APP_ID"]
+          config.app_secret = ENV["MESSENGER_APP_SECRET"]
+          config.skip_signature_validation = ENV["MESSENGER_SKIP_SIGNATURE_VALIDATION"] == "true"
+        end
+
+        if config.valid?
+          FlowChat.logger.info { "Messenger::Configuration: Configuration loaded successfully - page_id: #{config.page_id}" }
+        else
+          FlowChat.logger.warn { "Messenger::Configuration: Incomplete configuration loaded - missing required fields" }
+        end
+
+        config
+      end
+
+      def valid?
+        # 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? &&
+          page_id && !page_id.to_s.empty? &&
+          verify_token && !verify_token.to_s.empty?)
+
+        FlowChat.logger.debug { "Messenger::Configuration: Configuration valid: #{is_valid}" }
+        is_valid
+      end
+
+      # The account this configuration speaks for. Named generically, not
+      # page_id, so the shared gateway can check an inbound event's account
+      # without knowing which platform it holds.
+      def account_id
+        page_id
+      end
+
+      # The id an inbound webhook's entry.id names. Messenger only ever handles
+      # `page`, which names the Page, so this is the same id a send is
+      # addressed to. Instagram's two differ, which is why the gateway asks for
+      # this rather than reusing account_id.
+      def webhook_account_id
+        account_id
+      end
+
+      def messages_url
+        "#{api_base_url}/#{page_id}/messages"
+      end
+
+      def attachment_upload_url
+        "#{api_base_url}/#{page_id}/message_attachments"
+      end
+
+      def api_base_url
+        FlowChat::Config.messenger.api_base_url
+      end
+
+      def api_headers
+        {
+          "Authorization" => "Bearer #{access_token}",
+          "Content-Type" => "application/json"
+        }
+      end
+    end
+  end
+end

data/lib/flow_chat/messenger/configuration_error.rb

@@ -0,0 +1,9 @@
+module FlowChat
+  module Messenger
+    # Its own file so Zeitwerk can resolve it by name. Declared inside
+    # configuration.rb it existed only once that file had loaded for some other
+    # reason, so an application rescuing it, or a test naming it before anything
+    # touched the configuration class, got an uninitialized constant instead.
+    class ConfigurationError < StandardError; end
+  end
+end

data/lib/flow_chat/messenger/gateway/send_api.rb

@@ -0,0 +1,42 @@
+module FlowChat
+  module Messenger
+    module Gateway
+      # Facebook Messenger, on the shared Messenger Platform envelope.
+      class SendApi < FlowChat::Meta::MessagingGateway
+        def platform
+          :messenger
+        end
+
+        def gateway_name
+          :messenger_send_api
+        end
+
+        def configuration_class
+          FlowChat::Messenger::Configuration
+        end
+
+        def client_class
+          FlowChat::Messenger::Client
+        end
+
+        def renderer_class
+          FlowChat::Messenger::Renderer
+        end
+
+        def self.choice_mapper_class
+          FlowChat::Messenger::Middleware::ChoiceMapper
+        end
+
+        private
+
+        def configuration_error_class
+          FlowChat::Messenger::ConfigurationError
+        end
+
+        def platform_label
+          "Messenger"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,185 @@
+module FlowChat
+  module Messenger
+    module Middleware
+      # Maps a reply back to the choice key the flow used.
+      #
+      # Two key spaces can be live at once. A tap sends the payload the
+      # renderer put on the button, which is the title shown on it, and a user
+      # who types what they read sends that same string - so both resolve
+      # through one map. Only when a number is genuinely on screen does a
+      # typed digit mean a position, which is the second space.
+      #
+      # The title is the payload rather than a separately generated id
+      # because FlowChat::ChoiceTitles already guarantees the titles in a set
+      # are distinct, numbering the set when they would not be. A generated
+      # id needed its own uniqueness rule, and the one it had was lossy: it
+      # stripped punctuation, so "Yes!" produced the id "Yes", which was
+      # another choice's label exactly.
+      class ChoiceMapper
+        ID_KEY = "messenger.choice_mapping"
+        POSITION_KEY = "messenger.position_mapping"
+
+        def initialize(app)
+          @app = app
+          FlowChat.logger.debug { "#{self.class.name}: Initialized" }
+        end
+
+        def call(context)
+          @context = context
+          @session = context.session
+
+          handle_choice_input if intercept?
+
+          # The maps belong to exactly one screen: this turn's, if it had a
+          # resolvable answer, or one that already fell out of use otherwise.
+          # Either way nothing here is still owed to the next screen, so they
+          # are cleared unconditionally rather than asked whether they still
+          # look "live" - create_mappings immediately below repopulates them
+          # whenever the app actually returns choices.
+          #
+          # An earlier version asked stale_mappings? that question after
+          # handle_choice_input had already rewritten @context.input to the
+          # *resolved* value, which can equal one of the map's own keys (an
+          # Array choice's key is its label, and the wire value is the title
+          # built from that label), so the check answered "still live"
+          # about a value that was never a fresh reply. That let the maps
+          # survive into a free-text screen and reinterpret a typed answer
+          # there as the previous menu's choice. This was fixed once for
+          # WhatsApp in Task 6 and once here in Task 13; both fixes had the
+          # same shape and the same blind spot, which is why the guard is
+          # gone rather than patched a third time.
+          clear_mappings
+
+          type, prompt, choices, media = @app.call(context)
+
+          choices = create_mappings(choices) if choices.present?
+
+          [type, prompt, choices, media]
+        end
+
+        private
+
+        def platform_limits
+          FlowChat::Config.messenger
+        end
+
+        def always_number?
+          false
+        end
+
+        def id_key
+          self.class::ID_KEY
+        end
+
+        def position_key
+          self.class::POSITION_KEY
+        end
+
+        def get_id_mapping
+          @session.get(id_key) || {}
+        end
+
+        def get_position_mapping
+          @session.get(position_key) || {}
+        end
+
+        # Titles first, then positions. A tap sends the title as its payload
+        # 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, because a
+        # choice labelled "1" would otherwise be unreachable: its title is
+        # "1", and a bare digit is only a position when the screen was
+        # numbered at all.
+        def resolved_choice
+          input = @context.input.to_s
+          return nil if input.empty?
+
+          get_id_mapping[input] || get_position_mapping[input]
+        end
+
+        def intercept?
+          @context.input.present? && resolved_choice.present?
+        end
+
+        def handle_choice_input
+          original = resolved_choice
+          FlowChat.logger.info { "#{self.class.name}: Resolving input #{@context.input} to #{original}" }
+          @context.input = original
+        end
+
+        def clear_mappings
+          @session.delete(id_key)
+          @session.delete(position_key)
+        end
+
+        def create_mappings(choices)
+          cap = display_title_cap(choices.length)
+          return passthrough_mapping(choices) if cap.nil?
+
+          title_choices = {}
+          id_mapping = {}
+
+          FlowChat::ChoiceTitles.build(choices, cap).each do |key, label, title, _truncated|
+            title_choices[title] = label
+            id_mapping[title] = key
+          end
+
+          @session.set(id_key, id_mapping)
+
+          if number_choices?(choices)
+            @session.set(position_key, choices.keys.map.with_index(1) { |key, i| [i.to_s, key.to_s] }.to_h)
+          else
+            @session.delete(position_key)
+          end
+
+          title_choices
+        end
+
+        # On the :numbered rung the body already prints each full label beside
+        # its number, so the label itself is what is on screen and stays
+        # resolvable - nothing is truncated, so there is no shortened form to
+        # key on instead.
+        #
+        # A label shared by two choices is dropped rather than resolved to the
+        # first of them. It identifies neither on a screen that shows both, and
+        # the number printed next to each is the reply that does.
+        def passthrough_mapping(choices)
+          labels = choices.map { |key, label| [label.to_s, key.to_s] }
+          repeated = labels.map(&:first).tally
+
+          @session.set(id_key, labels.reject { |label, _| repeated[label] > 1 }.to_h)
+          @session.set(position_key, choices.keys.map.with_index(1) { |key, i| [i.to_s, key.to_s] }.to_h)
+          choices
+        end
+
+        # The title cap the renderer will use for these choices, or nil on
+        # the :none and :numbered rungs, where there is no separate title to
+        # alias: :none has no choices, and :numbered already lists each full
+        # label next to its number straight in the body, with nothing more
+        # to truncate. This calls the same FlowChat::Meta::ChoiceLadder the
+        # renderer consults, so the two cannot drift on which rung a given
+        # count lands on.
+        def display_title_cap(count)
+          case FlowChat::Meta::ChoiceLadder.rung_for(count, platform_limits)
+          when :quick_replies then platform_limits.max_quick_reply_title
+          when :carousel then platform_limits.max_button_title
+          end
+        end
+
+        # A position number is only worth resolving when one is genuinely on
+        # screen: on the :numbered rung, or wherever always_number? forces
+        # the renderer's #body to list one regardless of rung (Instagram,
+        # for a desktop user with no tappable surface at all), or on a
+        # quick-reply/carousel rung whose titles FlowChat::ChoiceTitles
+        # decided were ambiguous and prefixed with a number. always_number?
+        # only ever governs that body listing; it says nothing about whether
+        # a title itself was numbered, so it cannot answer this alone.
+        def number_choices?(choices)
+          count = choices.length
+          return true if FlowChat::Meta::ChoiceLadder.numbers_in_body?(count, platform_limits, always_number: always_number?)
+
+          FlowChat::ChoiceTitles.ambiguous?(choices, display_title_cap(count))
+        end
+      end
+    end
+  end
+end