flow_chat 0.8.2 → 0.10.0

data/lib/flow_chat/http/gateway/simple.rb

@@ -3,34 +3,71 @@ module FlowChat
     module Gateway
       class Simple
         include FlowChat::Instrumentation
+        include FlowChat::GatewayAsyncSupport
 
         attr_reader :context
 
-        def initialize(app)
+        # Configure HTTP specific middleware stack
+        def self.configure_middleware_stack(builder, custom_middleware)
+          FlowChat.logger.debug { "Simple: Configuring HTTP middleware stack" }
+
+          builder.use custom_middleware
+          FlowChat.logger.debug { "Simple: Added custom middleware" }
+
+          builder.use FlowChat::Http::Middleware::ChoiceMapper
+          FlowChat.logger.debug { "Simple: Added Http::Middleware::ChoiceMapper" }
+        end
+
+        def initialize(app, user_params)
           @app = app
+          @user_params = user_params
+
+          validate_user_params!
         end
 
         def call(context)
           @context = context
-          params = context.controller.request.params
-          request = context.controller.request
-
-          # Extract basic request information
-          context["request.id"] = params["session_id"] || SecureRandom.uuid
-          context["request.msisdn"] = FlowChat::PhoneNumberUtil.to_e164(params["msisdn"])
-          context["request.user_id"] = params["user_id"] || context["request.msisdn"] || context["request.id"]
-          context["request.message_id"] = params["message_id"] || SecureRandom.uuid
+          @controller = context.controller
+          params = @controller.request.params
+          request = @controller.request
+
+          # Validate request method
+          unless request.get? || request.post?
+            @controller.head :bad_request
+            return
+          end
+
+          # Set request information from user_params
+          context["request.id"] = @user_params[:session_id]
+          context["request.user_id"] = @user_params[:user_id]
+          context["request.user_name"] = @user_params[:name] if @user_params[:name]
+          context["request.msisdn"] = @user_params[:msisdn] if @user_params[:msisdn]
+          context["request.email"] = @user_params[:email] if @user_params[:email]
+          context["request.message_id"] = SecureRandom.uuid
           context["request.timestamp"] = Time.current.iso8601
           context["request.gateway"] = :http_simple
           context["request.platform"] = :http
-          context["request.network"] = nil
-          context["request.method"] = request.method
-          context["request.path"] = request.path
-          context["request.user_agent"] = request.user_agent
-          context.input = params["input"] || params["message"]
-
-          # Instrument message received when user provides input
-          if context.input.present?
+          context["request.body"] = (params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params.to_h).transform_keys(&:to_s)
+
+          # HTTP-specific request metadata
+          context["http.method"] = request.method
+          context["http.path"] = request.path
+          context["http.user_agent"] = request.user_agent
+          context.input = params["input"].presence || ""
+
+          # Inbound media (optional): callers may submit a media URL
+          if params["media_url"].present?
+            media_type = params["media_type"].presence&.to_sym
+            media_type = :document unless FlowChat::Media::CANONICAL_TYPES.include?(media_type)
+            context["request.media"] = {
+              type: media_type,
+              url: params["media_url"],
+              mime_type: params["mime_type"].presence
+            }
+          end
+
+          # Instrument message received when user provides input (text or media)
+          if inbound_message?(context)
             instrument(Events::MESSAGE_RECEIVED, {
               from: context["request.user_id"],
               message: context.input,
@@ -38,31 +75,62 @@ module FlowChat
             })
           end
 
-          # Process the request
-          type, prompt, choices, media = @app.call(context)
+          # Determine routing: async enqueue, background execute, or inline
+          if should_enqueue_async?
+            # HTTP request with async enabled → enqueue job and return immediately
+            enqueue_async_job
+            @controller.render json: {status: "processing"}
+          else
+            # Background OR inline → process message
+            # Process the request
+            response = @app.call(context)
 
-          # Instrument message sent
-          instrument(Events::MESSAGE_SENT, {
-            to: context["request.user_id"],
-            session_id: context["request.id"],
-            message: context.input || "",
-            message_type: (type == :prompt) ? "prompt" : "terminal",
-            gateway: :http_simple,
-            platform: :http,
-            content_length: prompt.to_s.length,
-            timestamp: context["request.timestamp"]
-          })
-
-          # Render response as JSON
-          response_data = render_response(type, prompt, choices, media)
-          context.controller.render json: response_data
+            # Handle nil response (e.g., from middleware that handles the response itself)
+            unless response
+              return @controller.render json: {
+                type: :skip,
+                session_id: context["request.id"],
+                user_id: context["request.user_id"],
+                timestamp: context["request.timestamp"]
+              }
+            end
+
+            type, prompt, choices, media = response
+
+            # Instrument message sent
+            instrument(Events::MESSAGE_SENT, {
+              to: context["request.user_id"],
+              session_id: context["request.id"],
+              message: context.input || "",
+              message_type: (type == :prompt) ? "prompt" : "terminal",
+              gateway: :http_simple,
+              platform: :http,
+              content_length: prompt.to_s.length,
+              timestamp: context["request.timestamp"]
+            })
+
+            # Render response as JSON
+            response_data = render_response(type, prompt, choices, media)
+            @controller.render json: response_data
+          end
         end
 
         private
 
+        def validate_user_params!
+          required_keys = [:session_id, :user_id]
+
+          required_keys.each do |key|
+            unless @user_params.key?(key)
+              raise FlowChat::Http::ConfigurationError,
+                "HTTP Simple gateway requires :#{key} in user_params"
+            end
+          end
+        end
+
         def render_response(type, prompt, choices, media)
           rendered = FlowChat::Http::Renderer.new(prompt, choices: choices, media: media).render
-          
+
           {
             type: type,
             session_id: context["request.id"],
@@ -74,4 +142,4 @@ module FlowChat
       end
     end
   end
-end 
+end

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

@@ -0,0 +1,94 @@
+module FlowChat
+  module Http
+    module Middleware
+      # Maps a web client's reply back to the choice it belongs to.
+      #
+      # A web client renders the choices itself, so what it sends back is
+      # whatever it decided to send: the key it was given, or the label it
+      # actually put on the button. Sending the label is the better of the two,
+      # because a transcript then reads back as what the visitor pressed rather
+      # than as an internal id, but the flow branches on keys.
+      #
+      # So both are accepted. Nothing is truncated here - the client decides
+      # its own widths - so a set of distinct labels is passed through exactly
+      # as the flow wrote it.
+      #
+      # Matching is exact, with no normalization on either side. A client
+      # echoes back the string it was handed rather than a person typing it,
+      # so nothing drifts on the way - and every transform that could have
+      # absorbed such a drift can also merge two choices into one entry, which
+      # is how the second of a pair became unpickable in the first place.
+      #
+      # The one thing that does get rewritten is a set whose labels are
+      # identical. Two choices both labelled "Savings" cannot be told apart by
+      # a visitor reading them either, so FlowChat::ChoiceTitles numbers the
+      # whole set. Previously the second simply lost to the first
+      # (`mapping[label] ||= key`) and could not be picked at all.
+      class ChoiceMapper
+        SESSION_KEY = "http.choice_mapping"
+
+        # The client renders these, so there is no platform width to fit.
+        UNCAPPED = Float::INFINITY
+
+        def initialize(app)
+          @app = app
+          FlowChat.logger.debug { "Http::ChoiceMapper: Initialized HTTP choice mapping middleware" }
+        end
+
+        def call(context)
+          resolve_input(context)
+
+          type, prompt, choices, media = @app.call(context)
+
+          choices = remember(context, choices)
+
+          [type, prompt, choices, media]
+        end
+
+        private
+
+        def resolve_input(context)
+          return if context.input.blank?
+
+          mapping = context.session.get(SESSION_KEY) || {}
+          return if mapping.empty?
+
+          matched = mapping[context.input.to_s]
+          return unless matched
+
+          FlowChat.logger.info { "Http::ChoiceMapper: Resolving #{context.input} to #{matched}" }
+          context.input = matched
+        end
+
+        # Displayed title to key. Cleared once a question carries no choices, so
+        # an answer to a later question is never read as a choice from an
+        # earlier one.
+        #
+        # Labels that survive the fold distinctly are returned untouched, which
+        # is the ordinary case. Only a set that would collide under the fold is
+        # numbered, and then the numbered titles are what the client is given -
+        # so what the visitor reads is what this resolves.
+        #
+        # @return [Hash, nil] the choices to render
+        def remember(context, choices)
+          if choices.blank?
+            context.session.delete(SESSION_KEY)
+            return choices
+          end
+
+          mapping = {}
+          titled = {}
+
+          FlowChat::ChoiceTitles.build(choices, UNCAPPED).each do |key, _label, title, _truncated|
+            titled[key] = title
+            mapping[title] = key
+          end
+
+          context.session.set(SESSION_KEY, mapping)
+          FlowChat.logger.debug { "Http::ChoiceMapper: Created mapping: #{mapping}" }
+          titled
+        end
+      end
+    end
+  end
+end

data/lib/flow_chat/http/renderer.rb

@@ -24,18 +24,18 @@ module FlowChat
       def format_choices
         return unless choices.present?
 
-        choices.map { |key, value| { key: key, value: value } }
+        choices.map { |key, value| {key: key, value: value} }
       end
 
       def format_media
         return unless media.present?
 
         {
-          url: media[:url] || media[:path],
+          url: media[:url],
           type: media[:type] || :image,
           caption: media[:caption]
         }.compact
       end
     end
   end
-end 
+end

data/lib/flow_chat/input.rb

@@ -0,0 +1,86 @@
+module FlowChat
+  # A single inbound turn.
+  #
+  # Replaces the old "$media$"/"$location$"/"$contact$" sentinels: instead of
+  # overloading the input string with a control signal, a turn carries its text
+  # and (at most one) structured attachment as first-class fields.
+  #
+  # It behaves like its text wherever a string method is expected — so
+  # validators/transforms written for text (`input.strip`, `input.to_i`,
+  # `input.blank?`) keep working — while also exposing `#media`, `#location`,
+  # `#contact`, and `#attachment_type` for the attachment. The prompt gates on
+  # `#submitted?` (text OR attachment), so a caption-less photo still answers a
+  # screen even though its text is blank.
+  class Input
+    # Session marker for the "first message" gate. Not a turn signal — kept as a
+    # namespaced constant so `FlowChat::Input::START` continues to resolve.
+    START = "$start$"
+
+    # #media is always an Array<FlowChat::Media> (empty when none). It is a list
+    # even on single-media platforms so callers iterate uniformly and never
+    # silently drop the extra attachments a message can carry (e.g. Intercom).
+    attr_reader :text, :media, :location, :contact
+
+    def initialize(text: nil, media: nil, location: nil, contact: nil)
+      @text = text.nil? ? "" : text.to_s
+      @media = media || []
+      @location = location
+      @contact = contact
+    end
+
+    # Did the user send anything this turn — text OR an attachment? The prompt
+    # gates on this so a caption-less photo answers a screen. Distinct from
+    # #present?/#blank?, which follow the text (so text validators behave).
+    def submitted?
+      !@text.empty? || attachment?
+    end
+
+    def attachment?
+      !attachment_type.nil?
+    end
+
+    # The structured payload on this turn — the media list, or the location /
+    # contact hash — or nil. Pair with #attachment_type to know which.
+    def attachment
+      case attachment_type
+      when :media then media
+      when :location then location
+      when :contact then contact
+      end
+    end
+
+    # The kind of structured payload on this turn, or nil. At most one is ever
+    # present in a single message, so this is a safe discriminator.
+    def attachment_type
+      return :media if @media.any?
+      return :location if @location
+      return :contact if @contact
+      nil
+    end
+
+    def to_s
+      @text
+    end
+
+    def ==(other)
+      other = other.to_s if other.is_a?(FlowChat::Input)
+      @text == other
+    end
+
+    # Behave like the text for any other PUBLIC string method (strip, to_i,
+    # match?, length, empty?, ...), so text-oriented validators/transforms keep
+    # working. Private String methods are not exposed — respond_to_missing? and
+    # method_missing agree on public-only so `respond_to?` never lies.
+    def respond_to_missing?(name, include_private = false)
+      @text.respond_to?(name) || super
+    end
+
+    def method_missing(name, *args, &block)
+      if @text.respond_to?(name)
+        @text.send(name, *args, &block)
+      else
+        super
+      end
+    end
+  end
+end

data/lib/flow_chat/instagram/client.rb

@@ -0,0 +1,32 @@
+module FlowChat
+  module Instagram
+    class Client < FlowChat::Messenger::Client
+      private
+
+      def renderer_class
+        FlowChat::Instagram::Renderer
+      end
+
+      def platform
+        :instagram
+      end
+
+      def limits
+        FlowChat::Config.instagram
+      end
+
+      # Meta: "Message text must be UTF-8 and be 1,000 bytes or less." A
+      # character count would let multibyte text through to be rejected.
+      def measure(string)
+        string.bytesize
+      end
+
+      # Meta's Instagram send reference documents recipient and message only,
+      # with no messaging_type. Inheriting Messenger's would put an undocumented
+      # parameter on every Instagram send.
+      def messaging_type?
+        false
+      end
+    end
+  end
+end

data/lib/flow_chat/instagram/configuration.rb

@@ -0,0 +1,147 @@
+module FlowChat
+  module Instagram
+    class Configuration
+      include FlowChat::NamedConfiguration
+
+      # :facebook is the Instagram API with Facebook Login: the linked Page
+      # speaks through graph.facebook.com. :instagram is the Instagram API
+      # with Instagram Login: the Instagram professional account speaks for
+      # itself through graph.instagram.com, with no Page in the picture.
+      LOGIN_PATHS = [:facebook, :instagram].freeze
+
+      attr_accessor :access_token, :page_id, :instagram_account_id, :verify_token,
+        :app_id, :app_secret, :name, :skip_signature_validation
+      attr_reader :login
+
+      def initialize(name)
+        @name = name
+        @access_token = nil
+        @page_id = nil
+        @instagram_account_id = nil
+        @verify_token = nil
+        @app_id = nil
+        @app_secret = nil
+        @skip_signature_validation = false
+        @login = :facebook
+
+        FlowChat.logger.debug { "Instagram::Configuration: Initialized configuration with name: #{name || "anonymous"}" }
+
+        register_as(name) if name.present?
+      end
+
+      # Rejected rather than coerced: a typo here would otherwise silently
+      # pick the wrong host and the wrong account identifier, and fail only
+      # once a real send or webhook hits the wrong Meta product.
+      def login=(value)
+        symbol = value&.to_sym
+        unless LOGIN_PATHS.include?(symbol)
+          raise ArgumentError, "login must be one of #{LOGIN_PATHS.inspect}, got #{value.inspect}"
+        end
+
+        @login = symbol
+      end
+
+      def self.from_credentials
+        FlowChat.logger.info { "Instagram::Configuration: Loading configuration from credentials/environment" }
+
+        config = new(nil)
+
+        if defined?(Rails) && Rails.respond_to?(:application) && Rails.application&.credentials&.instagram
+          FlowChat.logger.debug { "Instagram::Configuration: Loading from Rails credentials" }
+          credentials = Rails.application.credentials.instagram
+          config.access_token = credentials[:access_token]
+          config.page_id = credentials[:page_id]
+          config.instagram_account_id = credentials[:instagram_account_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
+          config.login = (credentials[:login] || "facebook").to_sym
+        else
+          FlowChat.logger.debug { "Instagram::Configuration: Loading from environment variables" }
+          config.access_token = ENV["INSTAGRAM_ACCESS_TOKEN"]
+          config.page_id = ENV["INSTAGRAM_PAGE_ID"]
+          config.instagram_account_id = ENV["INSTAGRAM_ACCOUNT_ID"]
+          config.verify_token = ENV["INSTAGRAM_VERIFY_TOKEN"]
+          config.app_id = ENV["INSTAGRAM_APP_ID"]
+          config.app_secret = ENV["INSTAGRAM_APP_SECRET"]
+          config.skip_signature_validation = ENV["INSTAGRAM_SKIP_SIGNATURE_VALIDATION"] == "true"
+          config.login = (ENV["INSTAGRAM_LOGIN"] || "facebook").to_sym
+        end
+
+        if config.valid?
+          FlowChat.logger.info { "Instagram::Configuration: Configuration loaded successfully - #{config.login} login, account #{config.account_id}" }
+        else
+          FlowChat.logger.warn { "Instagram::Configuration: Incomplete configuration loaded - missing required fields" }
+        end
+
+        config
+      end
+
+      def valid?
+        # Both ids are required, because sending and receiving key on
+        # different ones and only on the :facebook path do they differ.
+        # account_id is what a send is addressed as (the Page there);
+        # instagram_account_id is what an inbound delivery names in entry.id
+        # on both paths, which is what webhook_account_id encodes.
+        #
+        # Checking only account_id passed a :facebook configuration that had
+        # never been given an instagram_account_id, and the gateway then
+        # rejected every delivery it received: the id it compares against was
+        # blank, and a blank expectation matches nothing. A configuration that
+        # answers the handshake and then refuses all traffic is worse than one
+        # that admits up front it is incomplete.
+        #
+        # 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? &&
+          verify_token && !verify_token.to_s.empty? &&
+          account_id && !account_id.to_s.empty? &&
+          webhook_account_id && !webhook_account_id.to_s.empty?)
+
+        FlowChat.logger.debug { "Instagram::Configuration: Configuration valid: #{is_valid}" }
+        is_valid
+      end
+
+      # What a send is addressed to. An account reached through a Page answers
+      # as that Page over graph.facebook.com; an account with no Page answers
+      # for itself over graph.instagram.com. This is not the id an inbound
+      # delivery names, which is webhook_account_id below.
+      def account_id
+        (login == :instagram) ? instagram_account_id : page_id
+      end
+
+      # The id an inbound webhook's entry.id names, which is a different
+      # question from account_id above and has a different answer on the
+      # Facebook Login path.
+      #
+      # The top-level object of a delivery decides the id space, and this
+      # gateway only ever handles `instagram` (see expected_webhook_object),
+      # which names the Instagram professional account. That holds on both
+      # paths, so unlike account_id this does not depend on login.
+      def webhook_account_id
+        instagram_account_id
+      end
+
+      def messages_url
+        "#{api_base_url}/#{account_id}/messages"
+      end
+
+      def attachment_upload_url
+        "#{api_base_url}/#{account_id}/message_attachments"
+      end
+
+      def api_base_url
+        (login == :instagram) ? FlowChat::Config.instagram.instagram_login_api_base_url : FlowChat::Config.instagram.api_base_url
+      end
+
+      def api_headers
+        {
+          "Authorization" => "Bearer #{access_token}",
+          "Content-Type" => "application/json"
+        }
+      end
+    end
+  end
+end

data/lib/flow_chat/instagram/configuration_error.rb

@@ -0,0 +1,7 @@
+module FlowChat
+  module Instagram
+    # Its own file so Zeitwerk can resolve it by name. See the note on
+    # FlowChat::Messenger::ConfigurationError.
+    class ConfigurationError < StandardError; end
+  end
+end

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

@@ -0,0 +1,63 @@
+module FlowChat
+  module Instagram
+    module Gateway
+      # Instagram DMs, on the shared Messenger Platform envelope.
+      #
+      # A sibling of the Messenger gateway rather than a subclass of it: the
+      # two differ in credentials, limits and subscription object, and
+      # neither owns the other.
+      class SendApi < FlowChat::Meta::MessagingGateway
+        def platform
+          :instagram
+        end
+
+        def gateway_name
+          :instagram_send_api
+        end
+
+        def configuration_class
+          FlowChat::Instagram::Configuration
+        end
+
+        def client_class
+          FlowChat::Instagram::Client
+        end
+
+        def renderer_class
+          FlowChat::Instagram::Renderer
+        end
+
+        def self.choice_mapper_class
+          FlowChat::Instagram::Middleware::ChoiceMapper
+        end
+
+        # Confirmed against a live delivery for a page-linked account: Meta's
+        # docs are ambiguous about whether these arrive under "page" or
+        # "instagram", and they arrive under "instagram". The delivery named
+        # the Instagram professional account in entry.id, not the linked Page,
+        # which is what webhook_account_id encodes.
+        FACEBOOK_LOGIN_WEBHOOK_OBJECT = "instagram"
+
+        # Kept as its own constant rather than sharing one with the path above:
+        # the two integrations are configured independently in Meta's
+        # dashboard, so a correction to one path's value must not silently
+        # change the other's.
+        INSTAGRAM_LOGIN_WEBHOOK_OBJECT = "instagram"
+
+        def expected_webhook_object
+          (@config.login == :instagram) ? INSTAGRAM_LOGIN_WEBHOOK_OBJECT : FACEBOOK_LOGIN_WEBHOOK_OBJECT
+        end
+
+        private
+
+        def configuration_error_class
+          FlowChat::Instagram::ConfigurationError
+        end
+
+        def platform_label
+          "Instagram"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+module FlowChat
+  module Instagram
+    module Middleware
+      class ChoiceMapper < FlowChat::Messenger::Middleware::ChoiceMapper
+        ID_KEY = "instagram.choice_mapping"
+        POSITION_KEY = "instagram.position_mapping"
+
+        private
+
+        def platform_limits
+          FlowChat::Config.instagram
+        end
+
+        # The body always carries numbers here, so a typed number must
+        # always resolve, not only above the carousel capacity.
+        def always_number?
+          true
+        end
+      end
+    end
+  end
+end

data/lib/flow_chat/instagram/renderer.rb

@@ -0,0 +1,23 @@
+module FlowChat
+  module Instagram
+    # Instagram's ladder is Messenger's algorithm with different constants.
+    # The gateways are siblings (Instagram's does not depend on Messenger's),
+    # but the renderers really are the same shape, so this is the one place
+    # Instagram inherits from Messenger rather than mirroring it.
+    class Renderer < FlowChat::Messenger::Renderer
+      private
+
+      def limits
+        FlowChat::Config.instagram
+      end
+
+      # Quick replies and carousels are mobile only on Instagram, so the
+      # options are always listed in the body as well. A user on desktop
+      # sees the prompt and nothing tappable, and without the list has no
+      # way to reply at all.
+      def always_number?
+        true
+      end
+    end
+  end
+end