flow_chat 0.9.0 → 0.10.1

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