meta-messenger 2.1.2

data/lib/facebook/messenger/bot/error_parser.rb

@@ -0,0 +1,111 @@
+module Facebook
+  module Messenger
+    module Bot
+      # Parses and raises Facebook response errors for the send API.
+      class ErrorParser
+        INTERNAL_ERROR_CODES = {
+          1200 => []
+        }.freeze
+
+        ACCESS_TOKEN_ERROR_CODES = {
+          190 => []
+        }.freeze
+
+        ACCOUNT_LINKING_ERROR_CODES = {
+          10_303 => []
+        }.freeze
+
+        LIMIT_ERROR_CODES = {
+          4 => [2_018_022],
+          100 => [2_018_109],
+          613 => [nil]
+        }.freeze
+
+        BAD_PARAMETER_ERROR_CODES = {
+          100 => [nil, 2_018_001]
+        }.freeze
+
+        PERMISSION_ERROR_CODES = {
+          10 => [2_018_065, 2_018_108],
+          200 => [1_545_041, 2_018_028, 2_018_027, 2_018_021],
+          230 => [nil]
+        }.freeze
+
+        class << self
+          # Raise any errors in the given response.
+          #
+          # response - A HTTParty::Response object.
+          #
+          # Returns nil if no errors were found, otherwises raises appropriately
+          def raise_errors_from(response)
+            return unless response.key? 'error'
+
+            error = response['error']
+
+            error_code = error['code']
+            error_subcode = error['error_subcode']
+
+            raise_code_only_error(error_code, error) if error_subcode.nil?
+
+            raise_code_subcode_error(error_code, error_subcode, error)
+
+            # Default to unidentified error
+            raise FacebookError, error
+          end
+
+          private
+
+          def raise_code_only_error(error_code, args)
+            raise InternalError, args       if internal_error?(error_code)
+            raise AccessTokenError, args    if access_token_error?(error_code)
+            raise AccountLinkingError, args if account_linking_error?(
+              error_code
+            )
+          end
+
+          def raise_code_subcode_error(error_code, error_subcode, args)
+            raise LimitError, args        if limit_error?(error_code,
+                                                          error_subcode)
+            raise BadParameterError, args if bad_parameter_error?(error_code,
+                                                                  error_subcode)
+            raise PermissionError, args   if permission_error?(error_code,
+                                                               error_subcode)
+          end
+
+          def internal_error?(error_code)
+            INTERNAL_ERROR_CODES.key? error_code
+          end
+
+          def access_token_error?(error_code)
+            ACCESS_TOKEN_ERROR_CODES.key? error_code
+          end
+
+          def account_linking_error?(error_code)
+            ACCOUNT_LINKING_ERROR_CODES.key? error_code
+          end
+
+          def limit_error?(error_code, error_subcode)
+            limit_errors = LIMIT_ERROR_CODES[error_code]
+            return unless limit_errors
+
+            limit_errors.include? error_subcode
+          end
+
+          def bad_parameter_error?(error_code, error_subcode)
+            bad_parameter_errors = BAD_PARAMETER_ERROR_CODES[error_code]
+            return unless bad_parameter_errors
+
+            bad_parameter_errors.include? error_subcode
+          end
+
+          def permission_error?(error_code, error_subcode)
+            permission_errors = PERMISSION_ERROR_CODES[error_code]
+            return unless permission_errors
+
+            permission_errors.include? error_subcode
+          end
+        end
+      end
+    end
+  end
+end

data/lib/facebook/messenger/bot/exceptions.rb

@@ -0,0 +1,15 @@
+module Facebook
+  module Messenger
+    module Bot
+      # Base Facebook Messenger send API exception.
+      class SendError < Facebook::Messenger::FacebookError; end
+
+      class AccessTokenError < SendError; end
+      class AccountLinkingError < SendError; end
+      class BadParameterError < SendError; end
+      class InternalError < SendError; end
+      class LimitError < SendError; end
+      class PermissionError < SendError; end
+    end
+  end
+end

data/lib/facebook/messenger/bot/message_type.rb

@@ -0,0 +1,13 @@
+module Facebook
+  module Messenger
+    module Bot
+      # Supported message types
+      module MessageType
+        RESPONSE = 'RESPONSE'.freeze
+        UPDATE = 'UPDATE'.freeze
+        MESSAGE_TAG = 'MESSAGE_TAG'.freeze
+        NON_PROMOTIONAL_SUBSCRIPTION = 'NON_PROMOTIONAL_SUBSCRIPTION'.freeze
+      end
+    end
+  end
+end

data/lib/facebook/messenger/bot/messaging_type.rb

@@ -0,0 +1,12 @@
+module Facebook
+  module Messenger
+    module Bot
+      # Supported message types
+      module MessagingType
+        RESPONSE = 'RESPONSE'.freeze
+        UPDATE = 'UPDATE'.freeze
+        MESSAGE_TAG = 'MESSAGE_TAG'.freeze
+      end
+    end
+  end
+end

data/lib/facebook/messenger/bot/tag.rb

@@ -0,0 +1,27 @@
+module Facebook
+  module Messenger
+    module Bot
+      # Supported tags.
+      # Note: A tag is required when sending messages with the
+      # message type `MESSAGE_TAG`.
+      module Tag
+        COMMUNITY_ALERT               = 'COMMUNITY_ALERT'.freeze
+        CONFIRMED_EVENT_REMINDER      = 'CONFIRMED_EVENT_REMINDER'.freeze
+        NON_PROMOTIONAL_SUBSCRIPTION  = 'NON_PROMOTIONAL_SUBSCRIPTION'.freeze
+        PAIRING_UPDATE                = 'PAIRING_UPDATE'.freeze
+        APPLICATION_UPDATE            = 'APPLICATION_UPDATE'.freeze
+        ACCOUNT_UPDATE                = 'ACCOUNT_UPDATE'.freeze
+        PAYMENT_UPDATE                = 'PAYMENT_UPDATE'.freeze
+        PERSONAL_FINANCE_UPDATE       = 'PERSONAL_FINANCE_UPDATE'.freeze
+        SHIPPING_UPDATE               = 'SHIPPING_UPDATE'.freeze
+        RESERVATION_UPDATE            = 'RESERVATION_UPDATE'.freeze
+        ISSUE_RESOLUTION              = 'ISSUE_RESOLUTION'.freeze
+        APPOINTMENT_UPDATE            = 'APPOINTMENT_UPDATE'.freeze
+        GAME_EVENT                    = 'GAME_EVENT'.freeze
+        TRANSPORTATION_UPDATE         = 'TRANSPORTATION_UPDATE'.freeze
+        FEATURE_FUNCTIONALITY_UPDATE  = 'FEATURE_FUNCTIONALITY_UPDATE'.freeze
+        TICKET_UPDATE                 = 'TICKET_UPDATE'.freeze
+      end
+    end
+  end
+end

data/lib/facebook/messenger/bot.rb

@@ -0,0 +1,180 @@
+require 'facebook/messenger/bot/error_parser'
+require 'facebook/messenger/bot/exceptions'
+require 'facebook/messenger/bot/message_type'
+require 'facebook/messenger/bot/messaging_type'
+require 'facebook/messenger/bot/tag'
+
+module Facebook
+  module Messenger
+    #
+    # Module Bot provides functionality to sends and receives messages.
+    #
+    module Bot
+      include HTTParty
+
+      # Define base_uri for HTTParty.
+      base_uri 'https://graph.facebook.com/v20.0'
+
+      #
+      # @return [Array] Array containing the supported webhook events.
+      EVENTS = %i[
+        message
+        delivery
+        postback
+        optin
+        read
+        account_linking
+        referral
+        message_echo
+        payment
+        policy_enforcement
+        pass_thread_control
+        game_play
+        reaction
+        feed
+        leadgen
+      ].freeze
+
+      class << self
+        # Deliver a message with the given payload.
+        # @see https://developers.facebook.com/docs/messenger-platform/send-api-reference#request
+        #
+        # @raise [Facebook::Messenger::Bot::SendError] if there is any error
+        #   in response while sending message.
+        #
+        # @param [Hash] message The message payload
+        # @param [String] page_id The page to send the message from
+        #
+        # Returns a String describing the message ID if the message was sent,
+        # or raises an exception if it was not.
+        def deliver(message, page_id:)
+          access_token = config.provider.access_token_for(page_id)
+          app_secret_proof = config.provider.app_secret_proof_for(page_id)
+
+          query = { access_token: access_token }
+          query[:appsecret_proof] = app_secret_proof if app_secret_proof
+
+          response = post '/me/messages',
+                          body: JSON.dump(message),
+                          format: :json,
+                          query: query
+
+          Facebook::Messenger::Bot::ErrorParser.raise_errors_from(response)
+
+          response.body
+        end
+
+        # Reply to a Facebook comment.
+        # @see https://developers.facebook.com/docs/graph-api/reference/v20.0/object/comments
+        #
+        # @raise [Facebook::Messenger::Bot::SendError] if there is any error
+        #   in response while sending the comment.
+        #
+        # @param [Hash] comment The comment payload
+        # @param [String] page_id The page ID to send the comment from
+        #
+        # Returns a Hash describing the API response if the comment was sent,
+        # or raises an exception if it was not.
+        def reply_to_comment(comment_id, message, page_id:)
+          access_token = config.provider.access_token_for(page_id)
+          app_secret_proof = config.provider.app_secret_proof_for(page_id)
+
+          query = { access_token: access_token }
+          query[:appsecret_proof] = app_secret_proof if app_secret_proof
+
+          response = post "/#{comment_id}/comments",
+                          body: JSON.dump(message),
+                          format: :json,
+                          query: query
+
+          Facebook::Messenger::Bot::ErrorParser.raise_errors_from(response)
+
+          response.body
+        end
+
+        # Register a hook for the given event.
+        #
+        # @raise [ArgumentError] if received event is not registered.
+        #
+        # @param [String] event A String describing a Messenger event.
+        # @param [Block] block A code block to run upon the event.
+        #
+        # @return Save event and its block in hooks.
+        def on(event, &block)
+          unless EVENTS.include? event
+            raise ArgumentError,
+                  "#{event} is not a valid event; " \
+                  "available events are #{EVENTS.join(',')}"
+          end
+
+          hooks[event] = block
+        end
+
+        # Receive a given message from Messenger.
+        #
+        # @see https://developers.facebook.com/docs/messenger-platform/webhook-reference
+        #
+        # @param [Hash] payload A Hash describing the message.
+        #
+        # @return pass event and object of callback class to trigger function.
+        #
+        def receive(payload)
+          callback = Facebook::Messenger::Incoming.parse(payload)
+          event = Facebook::Messenger::Incoming::EVENTS.invert[callback.class]
+          trigger(event.to_sym, callback)
+        end
+
+        # Trigger the hook for the given event.
+        # Fetch callback for event from hooks and call it.
+        #
+        # @raise [KeyError] if hook is not registered for event
+        #
+        # @param [String] event A String describing a Messenger event.
+        # @param [Object] args Arguments to pass to the hook.
+        def trigger(event, *args)
+          hooks.fetch(event).call(*args)
+        rescue KeyError
+          warn "Ignoring #{event} (no hook registered)"
+        end
+
+        #
+        # Return a Hash of hooks.
+        #
+        # @return [Hash] Hash of hooks.
+        #
+        def hooks
+          @hooks ||= {}
+        end
+
+        #
+        # Deregister all hooks.
+        #
+        # @return [Hash] Assign empty hash to hooks and return it.
+        #
+        def unhook
+          @hooks = {}
+        end
+
+        #
+        # Default HTTParty options.
+        #
+        # @return [Hash] Default HTTParty options.
+        #
+        def default_options
+          super.merge(
+            read_timeout: 300,
+            headers: {
+              'Content-Type' => 'application/json'
+            }
+          )
+        end
+
+        private
+
+        def config
+          Facebook::Messenger.config
+        end
+      end
+    end
+  end
+end

data/lib/facebook/messenger/configuration/app_secret_proof_calculator.rb

@@ -0,0 +1,16 @@
+module Facebook
+  module Messenger
+    class Configuration
+      # We provide a service to calculate an app_secret_proof
+      class AppSecretProofCalculator
+        def self.call(app_secret, access_token)
+          OpenSSL::HMAC.hexdigest(
+            OpenSSL::Digest.new('SHA256'.freeze),
+            app_secret,
+            access_token
+          )
+        end
+      end
+    end
+  end
+end

data/lib/facebook/messenger/configuration/providers/base.rb

@@ -0,0 +1,48 @@
+require 'facebook/messenger/configuration/app_secret_proof_calculator'
+
+module Facebook
+  module Messenger
+    class Configuration
+      module Providers
+        # This is the base configuration provider.
+        #   User can overwrite this class to customize the environment variables
+        #   Be sure to implement all the functions as it raises
+        #   NotImplementedError errors.
+        class Base
+          # A default caching implentation of generating the app_secret_proof
+          # for a given page_id
+          def app_secret_proof_for(page_id = nil)
+            memo_key = [app_secret_for(page_id), access_token_for(page_id)]
+            memoized_app_secret_proofs[memo_key] ||=
+              calculate_app_secret_proof(*memo_key)
+          end
+
+          def valid_verify_token?(*)
+            raise NotImplementedError
+          end
+
+          def app_secret_for(*)
+            raise NotImplementedError
+          end
+
+          def access_token_for(*)
+            raise NotImplementedError
+          end
+
+          private
+
+          def calculate_app_secret_proof(app_secret, access_token)
+            Facebook::Messenger::Configuration::AppSecretProofCalculator.call(
+              app_secret,
+              access_token
+            )
+          end
+
+          def memoized_app_secret_proofs
+            @memoized_app_secret_proofs ||= {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/facebook/messenger/configuration/providers/environment.rb

@@ -0,0 +1,29 @@
+require 'facebook/messenger/configuration/providers/base'
+
+module Facebook
+  module Messenger
+    class Configuration
+      module Providers
+        # The default configuration provider for environment variables.
+        class Environment < Base
+          def valid_verify_token?(verify_token)
+            verify_token == ENV['VERIFY_TOKEN']
+          end
+
+          # Return String of app secret of Facebook App.
+          # Make sure you are returning the app secret if you overwrite
+          # configuration provider class as this app secret is used to
+          # validate the incoming requests.
+          def app_secret_for(*)
+            ENV['APP_SECRET']
+          end
+
+          # Return String of page access token.
+          def access_token_for(*)
+            ENV['ACCESS_TOKEN']
+          end
+        end
+      end
+    end
+  end
+end

data/lib/facebook/messenger/configuration/providers.rb

@@ -0,0 +1,13 @@
+require 'facebook/messenger/configuration/providers/environment'
+require 'facebook/messenger/configuration/providers/base'
+
+module Facebook
+  module Messenger
+    class Configuration
+      # The Providers module contains configuration providers that ship with the
+      # gem.
+      module Providers
+      end
+    end
+  end
+end

data/lib/facebook/messenger/configuration.rb

@@ -0,0 +1,12 @@
+require 'facebook/messenger/configuration/providers'
+
+module Facebook
+  module Messenger
+    #
+    # Class Configuration holds the configuration for bot.
+    #
+    class Configuration
+      attr_accessor :provider
+    end
+  end
+end

data/lib/facebook/messenger/error.rb

@@ -0,0 +1,44 @@
+module Facebook
+  module Messenger
+    # Base Facebook Messenger exception.
+    class Error < StandardError; end
+
+    # Base error class for Facebook API errors.
+    class FacebookError < Error
+      attr_reader :message
+      attr_reader :type
+      attr_reader :code
+      attr_reader :subcode
+      attr_reader :user_title
+      attr_reader :user_msg
+      attr_reader :fbtrace_id
+
+      #
+      # Constructor function.
+      #
+      # @param [Hash] error Hash containing information about error.
+      #
+      def initialize(error)
+        @message = error['message']
+        @type = error['type']
+        @code = error['code']
+        @subcode = error['error_subcode']
+        @user_title = error['error_user_title']
+        @user_msg = error['error_user_msg']
+        @fbtrace_id = error['fbtrace_id']
+      end
+
+      #
+      # Function to convert the error into string.
+      #
+      # @example
+      #   Error_Object.to_s #=> "Invalid OAuth access token. (subcode: 1234567)"
+      #
+      # @return [String] String describing the error message
+      #
+      def to_s
+        "#{@message} (subcode: #{subcode})"
+      end
+    end
+  end
+end

data/lib/facebook/messenger/incoming/account_linking.rb

@@ -0,0 +1,28 @@
+module Facebook
+  module Messenger
+    module Incoming
+      #
+      # The AccountLinking class represents an incoming Facebook Messenger
+      # Account Linking webhook, when the Linked Account
+      # or Unlink Account call-to-action have been tapped
+      #
+      # https://developers.facebook.com/docs/messenger-platform/webhook-reference/account-linking
+      #
+      class AccountLinking
+        include Facebook::Messenger::Incoming::Common
+
+        # Return String defining whether account in linked or not.
+        #
+        # @return [String] linked/unlinked.
+        def status
+          @messaging['account_linking']['status']
+        end
+
+        # The authorization code allows to match business user entity to PSID.
+        def authorization_code
+          @messaging['account_linking']['authorization_code']
+        end
+      end
+    end
+  end
+end

data/lib/facebook/messenger/incoming/common.rb

@@ -0,0 +1,131 @@
+module Facebook
+  module Messenger
+    module Incoming
+      #
+      # Common attributes for all incoming data from Facebook.
+      #
+      module Common
+        attr_reader :messaging
+
+        #
+        # Assign message to instance variable
+        #
+        # @param [Object] messaging Object of message.
+        #
+        def initialize(messaging)
+          @messaging = messaging
+        end
+
+        #
+        # Function return PSID of sender.
+        #
+        # @see https://developers.facebook.com/docs/messenger-platform/identity
+        #   Info about PSID.
+        # @see https://developers.facebook.com/docs/messenger-platform/webhook#format
+        #   Webhook event format.
+        #
+        # @return [String] PSID of sender.
+        #
+        def sender
+          @messaging['sender']
+        end
+
+        #
+        # Function return id of the page from which the message has arrived.
+        #
+        # @return [String] Facebook page id.
+        #
+        def recipient
+          @messaging['recipient']
+        end
+
+        #
+        # If the user responds to your message, the appropriate event
+        # (messages, messaging_postbacks, etc.) will be sent to your webhook,
+        # with a prior_message object appended. The prior_message object
+        # includes the source of the message the user is responding to, as well
+        # as the user_ref used for the original message send.
+        #
+        # @return [Hash] The 'prior_message' hash.
+        #
+        def prior_message
+          @messaging['prior_message']
+        end
+
+        #
+        # Function return timestamp when message is sent.
+        #
+        # @return [Object] Message time sent.
+        #
+        def sent_at
+          Time.at(@messaging['timestamp'] / 1000)
+        end
+
+        #
+        # Function send sender_action of 'typing_on' to sender.
+        # @see https://developers.facebook.com/docs/messenger-platform/send-messages/sender-actions
+        #   Info about sender actions.
+        #
+        # @return Send message to sender.
+        #
+        def typing_on
+          payload = {
+            recipient: sender,
+            sender_action: 'typing_on'
+          }
+
+          Facebook::Messenger::Bot.deliver(payload, page_id: recipient['id'])
+        end
+
+        #
+        # Function send sender_action of 'typing_off' to sender.
+        # @see https://developers.facebook.com/docs/messenger-platform/send-messages/sender-actions
+        #   Info about sender actions.
+        #
+        # @return Send message to sender.
+        #
+        def typing_off
+          payload = {
+            recipient: sender,
+            sender_action: 'typing_off'
+          }
+
+          Facebook::Messenger::Bot.deliver(payload, page_id: recipient['id'])
+        end
+
+        #
+        # Function send sender_action of 'mark_seen' to sender.
+        # @see https://developers.facebook.com/docs/messenger-platform/send-messages/sender-actions
+        #   Info about sender actions.
+        #
+        # @return Send message to sender.
+        #
+        def mark_seen
+          payload = {
+            recipient: sender,
+            sender_action: 'mark_seen'
+          }
+
+          Facebook::Messenger::Bot.deliver(payload, page_id: recipient['id'])
+        end
+
+        #
+        # Send reply to sender.
+        #
+        # @param [Hash] message Hash defining the message.
+        #
+        # @return Send reply to sender.
+        #
+        def reply(message)
+          payload = {
+            recipient: sender,
+            message: message,
+            message_type: Facebook::Messenger::Bot::MessageType::RESPONSE
+          }
+
+          Facebook::Messenger::Bot.deliver(payload, page_id: recipient['id'])
+        end
+      end
+    end
+  end
+end