xip-facebook 0.22.0

data/VERSION

@@ -0,0 +1 @@
+0.22.0

data/lib/xip-facebook.rb

@@ -0,0 +1 @@
+require 'xip/facebook'

data/lib/xip/facebook.rb

@@ -0,0 +1,2 @@
+require 'xip/services/facebook/version'
+require 'xip/services/facebook/client'

data/lib/xip/services/facebook/client.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'http'
+
+require 'xip/services/facebook/message_handler'
+require 'xip/services/facebook/reply_handler'
+require 'xip/services/facebook/setup'
+
+module Xip
+  module Services
+    module Facebook
+      class Client < Xip::Services::BaseClient
+
+        FB_ENDPOINT = if ENV['FACEBOOK_API_VERSION'].present?
+          "https://graph.facebook.com/v#{ENV['FACEBOOK_API_VERSION']}/me"
+        else
+          "https://graph.facebook.com/v3.2/me"
+        end
+
+        attr_reader :api_endpoint, :reply
+
+        def initialize(reply:, endpoint: 'messages')
+          @reply = reply
+          access_token = "access_token=#{Xip.config.facebook.page_access_token}"
+          @api_endpoint = [[FB_ENDPOINT, endpoint].join('/'), access_token].join('?')
+        end
+
+        def transmit
+          res = self
+                  .class
+                  .http_client
+                  .post(api_endpoint, body: MultiJson.dump(reply))
+
+          if res.status.client_error? # HTTP 4xx error
+            # Messenger error sub-codes (https://developers.facebook.com/docs/messenger-platform/reference/send-api/error-codes)
+            case res.body
+            when /1545041/
+              raise Xip::Errors::UserOptOut
+            when /2018108/
+              raise Xip::Errors::UserOptOut
+            when /2018028/
+              raise Xip::Errors::InvalidSessionID.new('Cannot message users who are not admins, developers or testers of the app until pages_messaging permission is reviewed and the app is live.')
+            end
+          end
+
+          Xip::Logger.l(
+            topic: "facebook",
+            message: "Transmitted. Response: #{res.status.code}: #{res.body}"
+          )
+        end
+
+        def self.http_client
+          headers = {
+            'Content-Type' => 'application/json'
+          }
+          HTTP.timeout(connect: 15, read: 60).headers(headers)
+        end
+
+        def self.fetch_profile(recipient_id:, fields: nil)
+          if fields.blank?
+            fields = [:id, :name, :first_name, :last_name, :profile_pic]
+          end
+
+          query_hash = {
+            fields: fields.join(','),
+            access_token: Xip.config.facebook.page_access_token
+          }
+
+          uri = URI::HTTPS.build(
+            host: "graph.facebook.com",
+            path: "/#{recipient_id}",
+            query: query_hash.to_query
+          )
+
+          res = http_client.get(uri.to_s)
+          Xip::Logger.l(topic:
+            'facebook',
+            message: "Requested user profile for #{recipient_id}. Response: #{res.status.code}: #{res.body}"
+          )
+
+          if res.status.success?
+            MultiJson.load(res.body.to_s)
+          else
+            raise(
+              Xip::Errors::ServiceError,
+              "Facebook error #{res.status}: #{res.body}"
+            )
+          end
+        end
+
+        def self.track(recipient_id:, metric:, value:, options: {})
+          metric_values = [{
+            '_eventName' => metric,
+            '_valueToSum' => value
+          }]
+
+          metric_values.first.merge!(options)
+
+          params = {
+            event: 'CUSTOM_APP_EVENTS',
+            custom_events: MultiJson.dump(metric_values),
+            advertiser_tracking_enabled: 1,
+            application_tracking_enabled: 1,
+            extinfo: MultiJson.dump(['mb1']),
+            page_scoped_user_id: recipient_id,
+            page_id: Xip.config.facebook.page_id
+          }
+
+          uri = URI::HTTPS.build(
+            host: "graph.facebook.com",
+            path: "/#{Xip.config.facebook.app_id}/activities"
+          )
+
+          res = http_client.post(uri.to_s, body: MultiJson.dump(params))
+          Xip::Logger.l(
+            topic: "facebook",
+            message: "Sent custom event for metric: #{metric} and value: #{value}. Response: #{res.status}: #{res.body}"
+          )
+
+          if res.status.success?
+            MultiJson.load(res.body.to_s)
+          else
+            raise(
+              Xip::Errors::ServiceError,
+              "Facebook error #{res.status}: #{res.body}"
+            )
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/xip/services/facebook/events/message_event.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Xip
+  module Services
+    module Facebook
+
+      class MessageEvent
+
+        attr_reader :service_message, :params
+
+        def initialize(service_message:, params:)
+          @service_message = service_message
+          @params = params
+        end
+
+        def process
+          fetch_message
+          fetch_location
+          fetch_attachments
+        end
+
+        private
+
+          def fetch_message
+            if params.dig('message', 'quick_reply').present?
+              service_message.message = params.dig('message', 'text')
+              service_message.payload = params.dig('message', 'quick_reply', 'payload')
+            elsif params.dig('message', 'text').present?
+              service_message.message = params.dig('message', 'text')
+            end
+          end
+
+          def fetch_location
+            if params.dig('message', 'attachments').present? && params.dig('message', 'attachments').is_a?(Array)
+              params.dig('message', 'attachments').each do |attachment|
+                next unless attachment['type'] == 'location'
+
+                lat = attachment.dig('payload', 'coordinates', 'lat')
+                lng = attachment.dig('payload', 'coordinates', 'long')
+
+                service_message.location = {
+                  lat: lat,
+                  lng: lng
+                }
+              end
+            end
+          end
+
+          def fetch_attachments
+            if params.dig('message', 'attachments').present? && params.dig('message', 'attachments').is_a?(Array)
+              params.dig('message', 'attachments').each do |attachment|
+                # Seems to be a bug in Messenger, but in attachments of type `fallback`
+                # we are seeing the URL come in at the attachment-level rather than
+                # nested within the payload as the API specifies:
+                # https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messages
+                payload_url = if attachment.dig('payload', 'url').present?
+                  attachment['payload']['url']
+                else
+                  attachment['url']
+                end
+
+                service_message.attachments << {
+                  type: attachment['type'],
+                  url: payload_url
+                }
+              end
+            end
+          end
+
+      end
+
+    end
+  end
+end

data/lib/xip/services/facebook/events/message_reads_event.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Xip
+  module Services
+    module Facebook
+
+      class MessageReadsEvent
+
+        attr_reader :service_message, :params
+
+        def initialize(service_message:, params:)
+          @service_message = service_message
+          @params = params
+        end
+
+        def process
+          fetch_read
+        end
+
+        private
+
+          def fetch_read
+            service_message.read = { watermark: get_timestamp, seq: params['read']['seq'] }
+          end
+
+          def get_timestamp
+            Time.at(params['read']['watermark']/1000).to_datetime
+          end
+      end
+
+      module ReadsEvent
+        attr_accessor :read
+        def initialize(service:)
+          @read = {}
+          super
+        end
+      end
+
+    end
+  end
+
+
+  class ServiceMessage
+    prepend Services::Facebook::ReadsEvent
+  end
+end

data/lib/xip/services/facebook/events/messaging_referral_event.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Xip
+  module Services
+    module Facebook
+
+      class MessagingReferralEvent
+
+        attr_reader :service_message, :params
+
+        def initialize(service_message:, params:)
+          @service_message = service_message
+          @params = params
+        end
+
+        def process
+          fetch_referral
+        end
+
+        private
+
+          def fetch_referral
+            service_message.referral = params['referral']
+          end
+
+      end
+
+    end
+  end
+end

data/lib/xip/services/facebook/events/postback_event.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Xip
+  module Services
+    module Facebook
+
+      class PostbackEvent
+
+        attr_reader :service_message, :params
+
+        def initialize(service_message:, params:)
+          @service_message = service_message
+          @params = params
+        end
+
+        def process
+          fetch_payload
+          fetch_referral
+        end
+
+        private
+
+          def fetch_payload
+            service_message.payload = params.dig('postback', 'payload')
+          end
+
+          def fetch_referral
+            service_message.referral = params.dig('postback', 'referral')
+          end
+
+      end
+
+    end
+  end
+end

data/lib/xip/services/facebook/message_handler.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'xip/services/facebook/events/message_event'
+require 'xip/services/facebook/events/postback_event'
+require 'xip/services/facebook/events/message_reads_event'
+require 'xip/services/facebook/events/messaging_referral_event'
+
+module Xip
+  module Services
+    module Facebook
+
+      class MessageHandler < Xip::Services::BaseMessageHandler
+
+        attr_reader :service_message, :params, :headers, :facebook_message
+
+        def initialize(params:, headers:)
+          @params = params
+          @headers = headers
+        end
+
+        def coordinate
+          if facebook_is_validating_webhook?
+            respond_with_validation
+          else
+            # Queue the request processing so we can respond quickly to FB
+            # and also keep track of this message
+            Xip::Services::HandleMessageJob.perform_async(
+              'facebook',
+              params,
+              headers
+            )
+
+            # Relay our acceptance
+            [200, 'OK']
+          end
+        end
+
+        def process
+          @service_message = ServiceMessage.new(service: 'facebook')
+          @facebook_message = params['entry'].first['messaging'].first
+          service_message.sender_id = get_sender_id
+          service_message.target_id = get_target_id
+          service_message.timestamp = get_timestamp
+          process_facebook_event
+
+          service_message
+        end
+
+        private
+
+          def facebook_is_validating_webhook?
+            params['hub.verify_token'].present?
+          end
+
+          def respond_with_validation
+            if params['hub.verify_token'] == Xip.config.facebook.verify_token
+              [200, params['hub.challenge']]
+            else
+              [401, "Verify token did not match environment variable."]
+            end
+          end
+
+          def get_sender_id
+            facebook_message['sender']['id']
+          end
+
+          def get_target_id
+            facebook_message['recipient']['id']
+          end
+
+          def get_timestamp
+            Time.at(facebook_message['timestamp']/1000).to_datetime
+          end
+
+          def process_facebook_event
+            if facebook_message['message'].present?
+              message_event = Xip::Services::Facebook::MessageEvent.new(
+                service_message: service_message,
+                params: facebook_message
+              )
+            elsif facebook_message['postback'].present?
+              message_event = Xip::Services::Facebook::PostbackEvent.new(
+                service_message: service_message,
+                params: facebook_message
+              )
+            elsif facebook_message['read'].present?
+              message_event = Xip::Services::Facebook::MessageReadsEvent.new(
+                service_message: service_message,
+                params: facebook_message
+              )
+            elsif facebook_message['referral'].present?
+              message_event = Xip::Services::Facebook::MessagingReferralEvent.new(
+                service_message: service_message,
+                params: facebook_message
+              )
+            end
+
+            message_event.process
+          end
+      end
+
+    end
+  end
+end

data/lib/xip/services/facebook/reply_handler.rb

@@ -0,0 +1,502 @@
+# frozen_string_literal: true
+
+module Xip
+  module Services
+    module Facebook
+
+      class ReplyHandler < Xip::Services::BaseReplyHandler
+
+        attr_reader :recipient_id, :reply
+
+        def initialize(recipient_id: nil, reply: nil)
+          @recipient_id = recipient_id
+          @reply = reply
+        end
+
+        def text
+          check_if_arguments_are_valid!(
+            suggestions: reply['suggestions'],
+            buttons: reply['buttons']
+          )
+
+          template = unstructured_template
+          template['message']['text'] = reply['text']
+
+          if reply['suggestions'].present?
+            fb_suggestions = generate_suggestions(suggestions: reply['suggestions'])
+            template["message"]["quick_replies"] = fb_suggestions
+          end
+
+          # If buttons are present, we need to convert this to a button template
+          if reply['buttons'].present?
+            template['message'].delete('text')
+
+            fb_buttons = generate_buttons(buttons: reply['buttons'])
+            attachment = button_attachment_template(text: reply['text'], buttons: fb_buttons)
+            template['message']['attachment'] = attachment
+          end
+
+          template
+        end
+
+        def image
+          check_if_arguments_are_valid!(
+            suggestions: reply['suggestions'],
+            buttons: reply['buttons']
+          )
+
+          template = unstructured_template
+          attachment = attachment_template(
+            attachment_type: 'image',
+            attachment_url: reply['image_url']
+          )
+          template['message']['attachment'] = attachment
+
+          if reply['suggestions'].present?
+            fb_suggestions = generate_suggestions(suggestions: reply['suggestions'])
+            template["message"]["quick_replies"] = fb_suggestions
+          end
+
+          template
+        end
+
+        def audio
+          check_if_arguments_are_valid!(
+            suggestions: reply['suggestions'],
+            buttons: reply['buttons']
+          )
+
+          template = unstructured_template
+          attachment = attachment_template(
+            attachment_type: 'audio',
+            attachment_url: reply['audio_url']
+          )
+          template['message']['attachment'] = attachment
+
+          if reply['suggestions'].present?
+            fb_suggestions = generate_suggestions(suggestions: reply['suggestions'])
+            template["message"]["quick_replies"] = fb_suggestions
+          end
+
+          template
+        end
+
+        def video
+          check_if_arguments_are_valid!(
+            suggestions: reply['suggestions'],
+            buttons: reply['buttons']
+          )
+
+          template = unstructured_template
+          attachment = attachment_template(
+            attachment_type: 'video',
+            attachment_url: reply['video_url']
+          )
+          template['message']['attachment'] = attachment
+
+          if reply['suggestions'].present?
+            fb_suggestions = generate_suggestions(suggestions: reply['suggestions'])
+            template["message"]["quick_replies"] = fb_suggestions
+          end
+
+          template
+        end
+
+        def file
+          check_if_arguments_are_valid!(
+            suggestions: reply['suggestions'],
+            buttons: reply['buttons']
+          )
+
+          template = unstructured_template
+          attachment = attachment_template(
+            attachment_type: 'file',
+            attachment_url: reply['file_url']
+          )
+          template['message']['attachment'] = attachment
+
+          if reply['suggestions'].present?
+            fb_suggestions = generate_suggestions(suggestions: reply['suggestions'])
+            template["message"]["quick_replies"] = fb_suggestions
+          end
+
+          template
+        end
+
+        def cards
+          template = card_template(
+            sharable: reply["sharable"],
+            aspect_ratio: reply["aspect_ratio"]
+          )
+
+          fb_elements = generate_card_elements(elements: reply["elements"])
+          template["message"]["attachment"]["payload"]["elements"] = fb_elements
+
+          if reply['suggestions'].present?
+            fb_suggestions = generate_suggestions(suggestions: reply['suggestions'])
+            template["message"]["quick_replies"] = fb_suggestions
+          end
+
+          template
+        end
+
+        def list
+          template = list_template(
+            top_element_style: reply["top_element_style"]
+          )
+
+          fb_elements = generate_list_elements(elements: reply["elements"])
+          template["message"]["attachment"]["payload"]["elements"] = fb_elements
+
+          if reply["buttons"].present?
+            if reply["buttons"].size > 1
+              raise(ArgumentError, "Facebook lists support a single button attached to the list itsef.")
+            end
+
+            template["message"]["attachment"]["payload"]["buttons"] = generate_buttons(buttons: reply["buttons"])
+          end
+
+          template
+        end
+
+        def mark_seen
+          sender_action_template(action: 'mark_seen')
+        end
+
+        def enable_typing_indicator
+          sender_action_template(action: 'typing_on')
+        end
+
+        def disable_typing_indicator
+          sender_action_template(action: 'typing_off')
+        end
+
+        def delay
+          enable_typing_indicator
+        end
+
+        # generates property/value pairs required to set the profile
+        def messenger_profile
+          unless Xip.config.facebook.setup.present?
+            raise Xip::Errors::ConfigurationError, "Setup for Facebook is not specified in services.yml."
+          end
+
+          profile = {}
+          Xip.config.facebook.setup.each do |profile_option, _|
+            profile[profile_option] = self.send(profile_option)
+          end
+
+          profile
+        end
+
+        private
+
+          def unstructured_template
+            {
+              "recipient" => {
+                "id" => recipient_id
+              },
+              "message" => { }
+            }
+          end
+
+          def card_template(sharable: nil, aspect_ratio: nil)
+            template = {
+              "recipient" => {
+                "id" => recipient_id
+              },
+              "message" => {
+                "attachment" => {
+                  "type" => "template",
+                  "payload" => {
+                    "template_type" => "generic",
+                    "elements" => []
+                  }
+                }
+              }
+            }
+
+            if sharable.present?
+              template["message"]["payload"]["sharable"] = sharable
+            end
+
+            if aspect_ratio.present?
+              template["message"]["payload"]["image_aspect_ratio"] = aspect_ratio
+            end
+
+            template
+          end
+
+          def list_template(top_element_style: nil, buttons: [])
+            template = {
+              "recipient" => {
+                "id" => recipient_id
+              },
+              "message" => {
+                "attachment" => {
+                  "type" => "template",
+                  "payload" => {
+                    "template_type" => "list",
+                    "elements" => []
+                  }
+                }
+              }
+            }
+
+            if top_element_style.present?
+              unless ['large', 'compact'].include?(top_element_style)
+                raise(ArgumentError, "Facebook list replies only support 'large' or 'compact' as the top_element_style.")
+              end
+
+              template["message"]['attachment']["payload"]["top_element_style"] = top_element_style
+            end
+
+            if buttons.present?
+              unless buttons.size > 1
+                raise(ArgumentError, "Facebook lists only support a single button in the top element.")
+              end
+
+              template["message"]["payload"]["buttons"] = aspect_ratio
+            end
+
+            template
+          end
+
+          def element_template(element_type:, element:)
+            unless element["title"].present?
+              raise(ArgumentError, "Facebook card and list elements must have a 'title' attribute.")
+            end
+
+            template = {
+              "title" => element["title"]
+            }
+
+            if element["subtitle"].present?
+              template["subtitle"] = element["subtitle"]
+            end
+
+            if element["image_url"].present?
+              template["image_url"] = element["image_url"]
+            end
+
+            if element["default_action"].present?
+              default_action = generate_default_action(action_params: element["default_action"].first)
+              template["default_action"] = default_action
+            end
+
+            if element["buttons"].present?
+              if element_type == 'card' && element["buttons"].size > 3
+                raise(ArgumentError, "Facebook card elements only support 3 buttons.")
+              end
+
+              if element_type == 'list' && element["buttons"].size > 1
+                raise(ArgumentError, "Facebook list elements only support 1 button.")
+              end
+
+              fb_buttons = generate_buttons(buttons: element["buttons"])
+              template["buttons"] = fb_buttons
+            end
+
+            template
+          end
+
+          def attachment_template(attachment_type:, attachment_url:)
+            {
+              "type" => attachment_type,
+              "payload" => {
+                "url" => attachment_url
+              }
+            }
+          end
+
+          def button_attachment_template(text:, buttons:)
+            {
+              "type" => "template",
+              "payload" => {
+                "template_type" => "button",
+                "text"          => text,
+                "buttons"       => buttons
+              }
+            }
+          end
+
+          def sender_action_template(action:)
+            {
+              "recipient" => {
+                "id" => recipient_id
+              },
+              "sender_action" => action
+            }
+          end
+
+          def generate_card_elements(elements:)
+            if elements.size > 10
+              raise(ArgumentError, "Facebook cards can have at most 10 cards.")
+            end
+
+            fb_elements = elements.collect do |element|
+              element_template(element_type: 'card', element: element)
+            end
+
+            fb_elements
+          end
+
+          def generate_list_elements(elements:)
+            if elements.size < 2 || elements.size > 4
+              raise(ArgumentError, "Facebook lists must have 2-4 elements.")
+            end
+
+            fb_elements = elements.collect do |element|
+              element_template(element_type: 'list', element: element)
+            end
+
+            fb_elements
+          end
+
+          def generate_suggestions(suggestions:)
+            quick_replies = suggestions.collect do |suggestion|
+              case suggestion["type"]
+              when 'location'
+                quick_reply = { "content_type" => "location" }
+              when 'phone'
+                quick_reply = { "content_type" => "user_phone_number" }
+              when 'email'
+                quick_reply = { "content_type" => "user_email" }
+              when 'birthday'
+                quick_reply = { "content_type" => "user_birthday" }
+              when 'state'
+                quick_reply = { "content_type" => "user_state" }
+              when 'zip_code'
+                quick_reply = { "content_type" => "user_zip_code" }
+              else
+                quick_reply = {
+                  "content_type" => "text",
+                  "title" => suggestion["text"]
+                }
+
+                if suggestion["payload"].present?
+                  quick_reply["payload"] = suggestion["payload"]
+                else
+                  quick_reply["payload"] = suggestion["text"]
+                end
+
+                if suggestion["image_url"].present?
+                  quick_reply["image_url"] = suggestion["image_url"]
+                end
+              end
+
+              quick_reply
+            end
+
+            quick_replies
+          end
+
+          # Requires adding support for Buy, Log In, Log Out, and Share button types
+          def generate_buttons(buttons:)
+            fb_buttons = buttons.collect do |button|
+              case button['type']
+              when 'url'
+                _button = {
+                  "type" => "web_url",
+                  "url" => button["url"],
+                  "title" => button["text"]
+                }
+
+                if button["webview_height"].present?
+                  _button["webview_height_ratio"] = button["webview_height"]
+                end
+
+                if button['messenger_extensions'].present?
+                  _button['messenger_extensions'] = true
+                end
+
+                _button
+
+              when 'payload'
+                _button = {
+                  "type" => "postback",
+                  "payload" => button["payload"],
+                  "title" => button["text"]
+                }
+
+              when 'call'
+                _button = {
+                  "type" => "phone_number",
+                  "payload" => button["phone_number"],
+                  "title" => button["text"]
+                }
+
+              when 'login'
+                _button = {
+                  "type" => "account_link",
+                  "url" => button["url"]
+                }
+
+              when 'logout'
+                _button = {
+                  "type" => "account_unlink"
+                }
+
+              when 'nested'
+                _button = {
+                  "type" => "nested",
+                  "title" => button["text"],
+                  "call_to_actions" => generate_buttons(buttons: button["buttons"])
+                }
+
+              else
+                raise(Xip::Errors::ServiceImpaired, "Sorry, we don't yet support #{button["type"]} buttons yet!")
+              end
+
+              _button
+            end
+
+            fb_buttons
+          end
+
+          def generate_default_action(action_params:)
+            default_action = {
+              "type" => "web_url",
+              "url" => action_params["url"]
+            }
+
+            if action_params["webview_height"].present?
+              action_params["webview_height_ratio"] = action_params["webview_height"]
+            end
+
+            default_action
+          end
+
+          def check_if_arguments_are_valid!(suggestions:, buttons:)
+            if suggestions.present? && buttons.present?
+              raise(ArgumentError, "A reply cannot have buttons and suggestions!")
+            end
+          end
+
+          def greeting
+            Xip.config.facebook.setup.greeting.map do |greeting|
+              {
+                "locale" => greeting["locale"],
+                "text" => greeting["text"]
+              }
+            end
+          end
+
+          def persistent_menu
+            Xip.config.facebook.setup.persistent_menu.map do |persistent_menu|
+              {
+                "locale" => persistent_menu['locale'],
+                "composer_input_disabled" => (persistent_menu['composer_input_disabled'] || false),
+                "call_to_actions" => generate_buttons(buttons: persistent_menu['call_to_actions'])
+              }
+            end
+          end
+
+          def get_started
+            Xip.config.facebook.setup.get_started
+          end
+      end
+
+    end
+  end
+end