flow_chat 0.9.0 → 0.10.0

data/lib/flow_chat/config.rb

@@ -10,6 +10,37 @@ module FlowChat
     # When true, inject logger into middleware stack. Defaults to true in Rails development.
     mattr_accessor :inject_middleware_logger, default: defined?(Rails) && Rails.env.development?
 
+    # Called with the turn's context and the error when a gateway cannot
+    # deliver a reply the flow produced, before the error is re-raised.
+    #
+    # For the app that owns the turn, acting on records only it knows about: a
+    # gateway sends after the middleware stack has returned, so an app that
+    # recorded the reply has already recorded it as sent, and nothing
+    # downstream of the send can tell it otherwise.
+    #
+    # The whole context, because this is the app's own code reading what the
+    # app put there. Anything wanting only to watch deliveries fail should
+    # subscribe to message.delivery_failed instead, which carries no more than
+    # a successful send announces.
+    #
+    # Raising here would replace the delivery error with this one, so an
+    # exception is logged and dropped.
+    mattr_accessor :on_delivery_failure, default: nil
+
+    # Called with (context, result) once a reply has actually been delivered,
+    # where result is whatever the platform's client returned. The mirror of
+    # on_delivery_failure, and the only place an app can learn the id the platform
+    # gave a message: gateways deliver after the middleware stack has unwound, so
+    # a row written during the turn does not yet know it.
+    #
+    # Every gateway that delivers out of band names that id the same way, on the
+    # context as "delivery.platform_message_id", so an app does not have to know
+    # the shape of each platform's answer.
+    #
+    # Raising here would replace a successful send with an error, so an exception
+    # is logged and dropped.
+    mattr_accessor :on_delivery_success, default: nil
+
     # Session configuration object
     def self.session
       @session ||= SessionConfig.new
@@ -30,6 +61,16 @@ module FlowChat
       @http ||= HttpConfig.new
     end
 
+    # Messenger-specific configuration object
+    def self.messenger
+      @messenger ||= MessengerConfig.new
+    end
+
+    # Instagram-specific configuration object
+    def self.instagram
+      @instagram ||= InstagramConfig.new
+    end
+
     class SessionConfig
       attr_accessor :boundaries, :hash_identifiers, :identifier, :session_id_proc
 
@@ -67,10 +108,92 @@ module FlowChat
     end
 
     class WhatsappConfig
-      attr_reader :api_base_url
+      # api_base_url is writable, unlike the limits beside it. Those are facts
+      # about the platform that an application cannot change by disagreeing. The
+      # version in the host is a choice, and one an application has to be able
+      # to make: Meta retires a version roughly every two years and pins the
+      # webhook payloads it sends to whatever the app's dashboard says, so an
+      # application straddling two versions must be able to close the gap
+      # without waiting for a release here.
+      attr_accessor :api_base_url
+      attr_reader :max_buttons, :max_list_rows
+
+      def initialize
+        @api_base_url = "https://graph.facebook.com/v23.0"
+        # Meta: "You cannot have more than 3 buttons in an interactive message."
+        @max_buttons = 3
+        # Meta: "up to 10 sections, with up to 10 rows for all sections combined".
+        @max_list_rows = 10
+      end
+
+      # Bridges max_buttons/max_list_rows to the shape
+      # FlowChat::Meta::ChoiceLadder expects, so the renderer and the choice
+      # mapper can both ask it which rung a count lands on instead of each
+      # re-deriving the same two-threshold comparison independently.
+      #
+      # WhatsApp's list has no further structure the way Messenger's
+      # carousel has elements and buttons per element - it is just a flat
+      # row cap - so it is modelled as a single element holding every row
+      # (max_buttons_per_element: 1) purely to fit ChoiceLadder's
+      # carousel_capacity formula (elements * buttons_per_element). That
+      # shape stays private to this adapter rather than becoming
+      # max_buttons/max_list_rows' own public meaning, since "carousel" and
+      # "buttons per element" describe nothing WhatsApp actually has.
+      def ladder_limits
+        LADDER_LIMITS_SHAPE.new(max_buttons, max_list_rows, 1)
+      end
+
+      LADDER_LIMITS_SHAPE = Struct.new(:max_quick_replies, :max_carousel_elements, :max_buttons_per_element)
+    end
+
+    class MessengerConfig
+      # Writable for the same reason as WhatsappConfig's, above.
+      attr_accessor :api_base_url
+      attr_reader :max_text_length, :max_quick_replies,
+        :max_quick_reply_title, :max_carousel_elements, :max_buttons_per_element,
+        :max_button_title, :max_element_title
+
+      def initialize
+        @api_base_url = "https://graph.facebook.com/v23.0"
+        # Meta does not state a text limit for Messenger on any current reference
+        # page, unlike Instagram's documented 1,000 bytes. 2000 is the long-cited
+        # figure and is safe to be wrong about in this direction: the client
+        # splits text at this value rather than truncating it, so a limit set too
+        # low sends an extra message and one set too high gets rejected. Raise it
+        # only against a documented figure.
+        @max_text_length = 2000
+        @max_quick_replies = 13
+        @max_quick_reply_title = 20
+        @max_carousel_elements = 10
+        @max_buttons_per_element = 3
+        @max_button_title = 20
+        @max_element_title = 80
+      end
+    end
+
+    class InstagramConfig
+      # Both hosts writable, and separately: the two integration paths are
+      # configured independently at Meta, so an application moving one to a new
+      # version has not necessarily moved the other.
+      attr_accessor :api_base_url, :instagram_login_api_base_url
+      attr_reader :max_text_length, :max_quick_replies,
+        :max_quick_reply_title, :max_carousel_elements, :max_buttons_per_element,
+        :max_button_title, :max_element_title
 
       def initialize
+        # Facebook Login path: the linked Page speaks through the general Graph API host.
         @api_base_url = "https://graph.facebook.com/v23.0"
+        # Instagram Login path: the Instagram professional account speaks through its
+        # own host instead, with no Facebook Page in the picture at all.
+        @instagram_login_api_base_url = "https://graph.instagram.com/v23.0"
+        # Meta: "Message text must be UTF-8 and be 1,000 bytes or less."
+        @max_text_length = 1000
+        @max_quick_replies = 13
+        @max_quick_reply_title = 20
+        @max_carousel_elements = 10
+        @max_buttons_per_element = 3
+        @max_button_title = 20
+        @max_element_title = 80
       end
     end
 

data/lib/flow_chat/delivery_error.rb

@@ -0,0 +1,9 @@
+module FlowChat
+  # A reply the flow produced that the platform would not take.
+  #
+  # Raised by nothing: it exists so that a send which failed quietly, by
+  # answering nil rather than raising, still reaches on_delivery_failure and
+  # MESSAGE_DELIVERY_FAILED carrying something that names what happened. A
+  # subscriber written against a raising client sees the same shape either way.
+  class DeliveryError < StandardError; end
+end

data/lib/flow_chat/http/configuration_error.rb

@@ -0,0 +1,9 @@
+module FlowChat
+  module Http
+    # Its own file so Zeitwerk can resolve it by name. Declared inside
+    # gateway/simple.rb, which Zeitwerk maps to a different constant, it existed only
+    # once that file had loaded for some other reason, so an application
+    # rescuing it, or a test naming it first, got an uninitialized constant.
+    class ConfigurationError < StandardError; end
+  end
+end

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

@@ -1,7 +1,5 @@
 module FlowChat
   module Http
-    class ConfigurationError < StandardError; end
-
     module Gateway
       class Simple
         include FlowChat::Instrumentation
@@ -9,6 +7,17 @@ module FlowChat
 
         attr_reader :context
 
+        # 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
@@ -46,8 +55,19 @@ module FlowChat
           context["http.user_agent"] = request.user_agent
           context.input = params["input"].presence || ""
 
-          # Instrument message received when user provides input
-          if context.input.present?
+          # 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,

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/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