flow_chat 0.8.2 → 0.10.0

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

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

data/lib/flow_chat/messenger/renderer.rb

@@ -0,0 +1,150 @@
+require "flow_chat/renderers/markdown_support"
+
+module FlowChat
+  module Messenger
+    class Renderer
+      include FlowChat::Renderers::MarkdownSupport
+
+      attr_reader :message, :choices, :media
+
+      def initialize(message, choices: nil, media: nil)
+        @message = message
+        @choices = choices
+        @media = media
+      end
+
+      def render
+        return build_attachment if media && choices.blank?
+
+        result = case FlowChat::Meta::ChoiceLadder.rung_for(choice_count, limits)
+        when :none then build_text
+        when :quick_replies then build_quick_replies
+        when :carousel then build_carousel
+        when :numbered then build_text
+        end
+
+        attach_media(result)
+      end
+
+      private
+
+      # Instagram overrides both hooks: its own limits, and always_number
+      # because its interactive surfaces render on mobile only.
+      def limits
+        FlowChat::Config.messenger
+      end
+
+      def always_number?
+        false
+      end
+
+      # nil (no choices at all) is the only non-Hash tolerated: Prompt
+      # normalizes an Array upstream in the flow path, so the only way an
+      # Array reaches here is a direct client send, e.g.
+      # `context["messenger.client"].send_message(psid, msg, choices: [...])`.
+      # Silently returning 0 for that made the choices vanish from the render
+      # with no error at all; raising matches what WhatsApp's own
+      # build_selection_message does for the same input instead of
+      # disagreeing with it.
+      def choice_count
+        return 0 if choices.nil?
+        raise ArgumentError, "choices must be a Hash" unless choices.is_a?(Hash)
+
+        choices.length
+      end
+
+      # Neither Messenger nor Instagram renders markup, so the prompt is
+      # flattened rather than translated.
+      def body
+        text = to_plain_text(message)
+        return text unless FlowChat::Meta::ChoiceLadder.numbers_in_body?(choice_count, limits, always_number: always_number?)
+
+        "#{text}\n\n#{numbered_options}"
+      end
+
+      def numbered_options
+        choices.values.map.with_index(1) { |label, i| "#{i}. #{label}" }.join("\n")
+      end
+
+      # Covers both the :none rung and the :numbered rung above the carousel
+      # capacity: body already appends the numbered options when the ladder
+      # calls for it, so there is nothing left for a separate method to add.
+      def build_text
+        [:text, body, {}]
+      end
+
+      # Whether titles are numbered, and the enumeration order positions come
+      # from, are both decided by FlowChat::ChoiceTitles over this same
+      # `choices` hash - the choice mapper goes through the same module over
+      # the same hash, so the two can never disagree on which titles are
+      # shown, which is what lets the mapper use a title as the wire value.
+      def build_quick_replies
+        replies = FlowChat::ChoiceTitles.build(choices, limits.max_quick_reply_title).map do |key, _label, title, _truncated|
+          {
+            content_type: "text",
+            title: title,
+            payload: key
+          }
+        end
+
+        [:quick_replies, body, {quick_replies: replies}]
+      end
+
+      # One option is one button, and buttons live on elements, so the options
+      # are packed across elements rather than one element per option.
+      #
+      # FlowChat::ChoiceTitles.build runs once over the whole choice set,
+      # before slicing into elements: both the ambiguity decision and the
+      # resulting position numbers have to consider every choice together,
+      # not each element's slice in isolation. Two different slices could
+      # each hold a "Foo" that only collides once the whole set is in view,
+      # and the numbering an element's buttons carry has to continue where
+      # the previous element's left off (button 14 reads "14.", not "2." of
+      # its own element) - both are only correct computed globally.
+      def build_carousel
+        numbered_choices = FlowChat::ChoiceTitles.build(choices, limits.max_button_title)
+
+        elements = numbered_choices.each_slice(limits.max_buttons_per_element).map.with_index(1) do |slice, index|
+          first = (index - 1) * limits.max_buttons_per_element + 1
+          last = first + slice.length - 1
+
+          {
+            title: FlowChat::TextTruncator.truncate("Options #{first} to #{last}", limits.max_element_title),
+            buttons: slice.map do |key, _label, title, _truncated|
+              {
+                type: "postback",
+                title: title,
+                payload: key
+              }
+            end
+          }
+        end
+
+        [:carousel, body, {elements: elements}]
+      end
+
+      def build_attachment
+        [:attachment, to_plain_text(message), media_attachment_options]
+      end
+
+      # Media is additive: it does not change which choice surface is used.
+      # It rides along in options[:media] so the client can post it as its
+      # own message ahead of whichever rung the choice count would render
+      # with no media at all.
+      def attach_media(result)
+        return result unless media
+
+        type, content, options = result
+        [type, content, options.merge(media: media_attachment_options)]
+      end
+
+      def media_attachment_options
+        type = (media[:type] || :image).to_sym
+        options = {type: type}
+        options[:url] = media[:url] if media[:url]
+        options[:attachment_id] = media[:id] if media[:id]
+        options
+      end
+    end
+  end
+end

data/lib/flow_chat/meta/challenge.rb

@@ -0,0 +1,24 @@
+module FlowChat
+  module Meta
+    # The GET handshake Meta performs when a webhook URL is registered, as a
+    # decision rather than a response.
+    #
+    # Returns the challenge to echo, or nil when the request has not proved it
+    # is Meta. What to do with either answer belongs to the caller: a gateway
+    # renders it through its controller, an application receiving Meta's
+    # webhooks outside a gateway renders it its own way.
+    #
+    # WebhookVerification is the gateway's way in, and calls this.
+    module Challenge
+      # A configuration with no verify token must not verify anything. Without
+      # the presence check a missing token on both sides compares equal, and
+      # anyone could claim the endpoint by asking for the challenge.
+      def self.answer(params, verify_token)
+        return nil if verify_token.to_s.strip.empty?
+        return nil unless FlowChat::Security.secure_compare(params["hub.verify_token"].to_s, verify_token)
+
+        params["hub.challenge"]
+      end
+    end
+  end
+end

data/lib/flow_chat/meta/choice_ladder.rb

@@ -0,0 +1,37 @@
+module FlowChat
+  module Meta
+    # Which interactive surface renders a given number of choices.
+    #
+    # The renderer and the choice mapper both need this answer, and they must
+    # agree: the renderer decides what the user sees, the mapper decides what a
+    # reply is allowed to mean. Two copies of the arithmetic would drift into a
+    # screen whose replies cannot be resolved.
+    module ChoiceLadder
+      def self.rung_for(count, limits)
+        return :none if count.zero?
+        return :quick_replies if count <= limits.max_quick_replies
+        return :carousel if count <= carousel_capacity(limits)
+
+        :numbered
+      end
+
+      # The carousel holds elements, each holding buttons, and one option is one
+      # button.
+      def self.carousel_capacity(limits)
+        limits.max_carousel_elements * limits.max_buttons_per_element
+      end
+
+      # Whether the options are also listed, numbered, in the message body.
+      #
+      # always_number is for platforms whose interactive surfaces do not render
+      # everywhere. Without it a user who cannot see the buttons has no way to
+      # answer at all.
+      def self.numbers_in_body?(count, limits, always_number: false)
+        return false if count.zero?
+        return true if always_number
+
+        rung_for(count, limits) == :numbered
+      end
+    end
+  end
+end

data/lib/flow_chat/meta/configuration_error.rb

@@ -0,0 +1,7 @@
+module FlowChat
+  module Meta
+    # Raised when a Meta gateway cannot validate a signature because it was not
+    # configured to. Platforms override configuration_error_class to raise their own.
+    class ConfigurationError < StandardError; end
+  end
+end

data/lib/flow_chat/meta/gateway_identity.rb

@@ -0,0 +1,38 @@
+module FlowChat
+  module Meta
+    # What a Meta gateway must say about itself.
+    #
+    # The behavior modules in this namespace need a handful of the same values:
+    # which platform this is, how to name it to a developer, which error class to
+    # raise, what to tag logs with. Declaring them here rather than in whichever
+    # behavior module happens to be included first means a gateway can include
+    # one behavior without the other, and a gateway that forgets a value fails
+    # loudly rather than borrowing another platform's.
+    #
+    # NotImplementedError rather than a default: it descends from ScriptError,
+    # not StandardError, so it travels through the bare rescue in
+    # SignatureValidation instead of being swallowed into a false return that
+    # would read as "invalid signature" and drop every webhook.
+    module GatewayIdentity
+      def platform
+        raise NotImplementedError, "#{self.class.name} must define #platform"
+      end
+
+      # The product's name as a developer reading an error message expects it,
+      # which is not always the constant: Whatsapp the module, WhatsApp the product.
+      def platform_label
+        raise NotImplementedError, "#{self.class.name} must define #platform_label"
+      end
+
+      def configuration_error_class
+        raise NotImplementedError, "#{self.class.name} must define #configuration_error_class"
+      end
+
+      # Derived, because every gateway's class name already ends in the tag its
+      # logs use. Override only to pin the tag against a class rename.
+      def log_tag
+        self.class.name.split("::").last
+      end
+    end
+  end
+end