flow_chat 0.9.0 → 0.10.0

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

@@ -0,0 +1,101 @@
+module FlowChat
+  module Intercom
+    module Middleware
+      # Maps an Intercom reply back to the choice it belongs to.
+      #
+      # Intercom has no interactive buttons, so the renderer writes the options
+      # out as a numbered list and asks the reader to reply with a number. That
+      # number has to come back to the choice key the flow branches on, the same
+      # job USSD's mapper does for a handset.
+      #
+      # A number is the only thing that resolves, as on USSD, and that is what
+      # the message asks for in as many words. It is also what makes this
+      # mapper safe by construction rather than by care: positions are unique
+      # whatever the labels say, so there is no equivalence under which two
+      # choices could collapse and nothing to check them against.
+      #
+      # Labels were matched too, case insensitively. That is what needed the
+      # care - two choices reading the same, or differing only in case, folded
+      # onto one entry and the second could not be picked by name at all. On a
+      # screen that prints a number beside every option and asks for one, the
+      # number already does that job unambiguously.
+      #
+      # Flow:
+      # 1. Flow returns choices with their own keys (e.g. {"sales" => "Sales"})
+      # 2. This middleware numbers them and remembers what each number meant
+      # 3. The renderer writes "1. Sales" and asks for a number
+      # 4. The reader replies "1"
+      # 5. This middleware turns it back into "sales"
+      # 6. The flow sees its own key
+      class ChoiceMapper
+        SESSION_KEY = "intercom.choice_mapping"
+
+        def initialize(app)
+          @app = app
+          FlowChat.logger.debug { "Intercom::ChoiceMapper: Initialized Intercom choice mapping middleware" }
+        end
+
+        def call(context)
+          @context = context
+          @session = context.session
+
+          resolve_input
+
+          type, prompt, choices, media = @app.call(context)
+
+          choices = remember(choices)
+
+          [type, prompt, choices, media]
+        end
+
+        private
+
+        def resolve_input
+          return if @context.input.blank?
+
+          mapping = @session.get(SESSION_KEY) || {}
+          return if mapping.empty?
+
+          # Surrounding whitespace is trimmed off a chat message before the
+          # lookup. Unlike a fold over labels, this cannot merge two choices:
+          # trimming leaves "1" and "2" as distinct as it found them.
+          matched = mapping[@context.input.to_s.strip]
+          return unless matched
+
+          FlowChat.logger.info { "Intercom::ChoiceMapper: Resolving #{@context.input} to #{matched}" }
+          @context.input = matched
+        end
+
+        # Numbers the choices and stores what each number meant.
+        #
+        # The renderer is what prints the number beside each label, so nothing
+        # is prefixed here - doing both would read as "1. 1. Savings".
+        #
+        # Cleared when a screen carries no choices, so an answer typed into a
+        # later free-text question is never read as a choice from an earlier
+        # menu. WhatsApp and Messenger each had this same bug fixed twice.
+        #
+        # @return [Hash, nil] the choices to render
+        def remember(choices)
+          if choices.blank?
+            @session.delete(SESSION_KEY)
+            return choices
+          end
+
+          numbered = {}
+          mapping = {}
+
+          choices.each_with_index do |(key, label), index|
+            number = (index + 1).to_s
+            numbered[number] = label.to_s
+            mapping[number] = key.to_s
+          end
+
+          @session.set(SESSION_KEY, mapping)
+          FlowChat.logger.debug { "Intercom::ChoiceMapper: Created mapping: #{mapping}" }
+          numbered
+        end
+      end
+    end
+  end
+end

data/lib/flow_chat/intercom/renderer.rb

@@ -24,7 +24,8 @@ module FlowChat
       private
 
       def build_text_message
-        [:text, to_html(message), {}]
+        link, options = render_media
+        [:text, to_html(message.to_s + link), options]
       end
 
       def build_selection_message
@@ -35,10 +36,27 @@ module FlowChat
         end
       end
 
+      # Choices are a numbered list rather than Intercom's own quick replies,
+      # and that is a decision rather than an oversight. Intercom does document
+      # reply_options with message_type "quick_reply" on an admin reply, and it
+      # was built here and reverted. Three reasons, in the order they matter:
+      #
+      # - The uuid of a clicked option comes back as quick_reply_option_uuid,
+      #   and only if the Intercom app is set to the *Unstable* API version.
+      #   Webhooks inherit that setting, so an app on a stable version receives
+      #   no metadata at all. Requiring an unstable API version for something as
+      #   basic as reading which option was chosen is not a thing a library can
+      #   ask of its users.
+      # - body is forbidden on a quick_reply, so a choice screen becomes two
+      #   conversation parts: one for the prompt, one for the buttons. In an
+      #   inbox a human reads, that doubles the length of every flow.
+      # - Intercom's own community reports the endpoint returning errors for
+      #   this shape.
+      #
+      # A numbered list needs none of that and works on every API version. If
+      # Intercom stabilises quick replies, the git history has the
+      # implementation; check those three things before restoring it.
       def build_interactive_message(choice_hash)
-        # For Intercom, we'll present choices as a formatted text message
-        # since Intercom doesn't have the same interactive elements as WhatsApp
-
         formatted_message = message.to_s
 
         unless formatted_message.empty?
@@ -53,7 +71,41 @@ module FlowChat
 
         formatted_message += "\nReply with the number of your choice."
 
-        [:text, to_html(formatted_message), {choices: choice_hash}]
+        link, options = render_media
+        [:text, to_html(formatted_message + link), options.merge(choices: choice_hash)]
+      end
+
+      # Intercom's admin reply only takes real attachments as image URLs
+      # (attachment_urls, documented specifically for images, max 10). Any
+      # other media type with a url - document, video, audio, sticker -
+      # becomes a markdown link in the body instead, since attachment_urls
+      # is documented for images and a non-image URL there may not render.
+      # An id with no url is another platform's upload handle (a WhatsApp
+      # media id, say) and means nothing to Intercom, so it is logged and
+      # dropped rather than raised: a multi-platform flow legitimately sets
+      # an id for whichever platform uploaded it, and one platform lacking
+      # the media should not fail the whole turn.
+      #
+      # Returns [markdown_suffix, options] - the suffix is appended to the
+      # message before markdown-to-HTML conversion so a link goes through
+      # the same sanitizer and allowed_tags as the rest of the body.
+      def render_media
+        return ["", {}] unless media
+
+        url = media[:url]
+        media_type = (media[:type] || :image).to_sym
+
+        unless url
+          FlowChat.logger.warn { "Intercom::Renderer: media id #{media[:id].inspect} is another platform's upload handle and means nothing to Intercom (no url given); sending the message without it" }
+          return ["", {}]
+        end
+
+        if media_type == :image
+          ["", {attachment_urls: [url]}]
+        else
+          label = media[:filename] || media_type.to_s.capitalize
+          ["\n\n[#{label}](#{url})", {}]
+        end
       end
 
       # MarkdownSupport overrides for Intercom-specific behavior

data/lib/flow_chat/media.rb

@@ -0,0 +1,121 @@
+require "net/http"
+require "uri"
+
+module FlowChat
+  # Value object wrapping a single inbound media item parsed by a gateway.
+  # Normalizes cross-platform differences (WhatsApp media-id, Telegram file_id,
+  # Intercom/HTTP direct URL) behind #url and #download.
+  class Media
+    # Maps platform-native media types to a canonical, cross-platform set.
+    # Telegram uses :photo/:voice where WhatsApp uses :image/:audio.
+    NORMALIZED_TYPES = {photo: :image, voice: :audio}.freeze
+
+    # The canonical media types FlowChat recognizes across platforms. Gateways
+    # that accept a caller-supplied type (e.g. HTTP) validate against this set.
+    CANONICAL_TYPES = %i[image video audio document sticker].freeze
+
+    attr_reader :platform, :client
+
+    def initialize(data, platform:, client: nil)
+      @data = data
+      @platform = platform
+      @client = client
+    end
+
+    # Canonical, cross-platform media type (:image, :video, :audio, :document, :sticker).
+    def type
+      NORMALIZED_TYPES.fetch(raw_type, raw_type)
+    end
+
+    # The platform-native type as parsed by the gateway (e.g. :photo, :voice on Telegram).
+    def raw_type
+      @data[:type]
+    end
+
+    def mime_type
+      @data[:mime_type]
+    end
+
+    def caption
+      @data[:caption]
+    end
+
+    def filename
+      @data[:filename] || @data[:file_name]
+    end
+
+    def id
+      @data[:id]
+    end
+
+    def file_id
+      @data[:file_id]
+    end
+
+    def [](key)
+      @data[key]
+    end
+
+    def to_h
+      @data.dup
+    end
+
+    # Serialize without the live platform client (a network object that may not
+    # marshal). This keeps a Media — and any FlowChat::Input holding it — safe to
+    # store in a session store. A deserialized Media has no client, so #url and
+    # #download degrade to nil rather than raising.
+    def marshal_dump
+      {data: @data, platform: @platform}
+    end
+
+    def marshal_load(state)
+      @data = state[:data]
+      @platform = state[:platform]
+      @client = nil
+    end
+
+    # Resolve a fetchable URL for the media. Memoized so repeated reads don't
+    # re-issue the platform lookup (WhatsApp get_media_url / Telegram getFile).
+    # Returns nil (rather than raising) if the lookup fails, matching #download.
+    def url
+      @url ||= case platform
+      when :whatsapp then client.get_media_url(id)
+      when :telegram then client.file_url(file_id)
+      else @data[:url]
+      end
+    rescue => e
+      FlowChat.logger.warn { "Media: url resolution failed: #{e.message}" }
+      nil
+    end
+
+    # Fetch the raw bytes of the media, or nil on failure (uniform across
+    # platforms). WhatsApp needs the client to attach auth headers; every other
+    # platform (Telegram, Intercom, HTTP) exposes a token-in-URL or public link,
+    # so we fetch the already-memoized #url directly — avoiding a second getFile
+    # round-trip on Telegram.
+    def download
+      case platform
+      when :whatsapp then client.download_media(id)
+      else fetch(url)
+      end
+    rescue => e
+      FlowChat.logger.warn { "Media: download failed: #{e.message}" }
+      nil
+    end
+
+    private
+
+    def fetch(resource_url)
+      return nil unless resource_url
+
+      uri = URI(resource_url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      response = http.get(uri.request_uri)
+      response.body if response.is_a?(Net::HTTPSuccess)
+    rescue => e
+      FlowChat.logger.warn { "Media: download failed for #{resource_url}: #{e.message}" }
+      nil
+    end
+  end
+end

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