flow_chat 0.8.2 → 0.10.0

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

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