facebook-messenger 1.0.0 → 1.1.0

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

@@ -1,8 +1,8 @@
 module Facebook
   module Messenger
     module Incoming
-      # The Message echo class represents an
-      # incoming Facebook Messenger message
+      # The Message echo class represents an incoming Facebook Messenger message
+      # @see https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/message-echoes
       class MessageEcho < Message
       end
     end

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

@@ -0,0 +1,13 @@
+module Facebook
+  module Messenger
+    module Incoming
+      # The Message request class represents an
+      # incoming Facebook Messenger message request accepted by the user
+      class MessageRequest < Message
+        def accept?
+          @messaging['message_request'] == 'accept'
+        end
+      end
+    end
+  end
+end

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

@@ -1,16 +1,33 @@
 module Facebook
   module Messenger
     module Incoming
+      #
       # The Optin class represents an incoming Facebook Messenger optin,
       # which occurs when a user engages by using the Send-to-Messenger Plugin.
       #
-      # https://developers.facebook.com/docs/messenger-platform/plugin-reference
+      # @see https://developers.facebook.com/docs/messenger-platform/plugin-reference
+      #
       class Optin
         include Facebook::Messenger::Incoming::Common
 
+        #
+        # Function returns 'data-ref' attribute that was defined
+        #   with the entry point.
+        #
+        # @return [String] data-ref attribute.
+        #
         def ref
           @messaging['optin']['ref']
         end
+
+        #
+        # Function returns 'user_ref' attribute defined in checkbox plugin.
+        #
+        # @return [String] user-ref attribute.
+        #
+        def user_ref
+          @messaging['optin']['user_ref']
+        end
       end
     end
   end

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

@@ -0,0 +1,49 @@
+module Facebook
+  module Messenger
+    module Incoming
+      # The Payment class represents a successful purchase using the Buy Button
+      #
+      # https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/payment
+      class Payment
+        include Facebook::Messenger::Incoming::Common
+
+        # The payment portion of the payload.
+        class Payment
+          def initialize(payment)
+            @payment = payment
+          end
+
+          # Return String containing developer defined payload.
+          def payload
+            @payment['payload']
+          end
+
+          # Return hash containing the requested information from user when they
+          #   click buy button.
+          def user_info
+            @payment['requested_user_info']
+          end
+
+          # Return hash containing the payment credential information.
+          def payment_credential
+            @payment['payment_credential']
+          end
+
+          # Return hash containing the information about amount of purchase.
+          def amount
+            @payment['amount']
+          end
+
+          # Return string containing option_id of selected shipping option.
+          def shipping_option_id
+            @payment['shipping_option_id']
+          end
+        end
+
+        def payment
+          @payment ||= Payment.new(@messaging['payment'])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+module Facebook
+  module Messenger
+    module Incoming
+      # The PolicyEnforcement class represents an incoming webhook response from
+      # Facebook when they are notifying your app of a policy violation
+      #
+      # https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_policy_enforcement
+      class PolicyEnforcement
+        include Facebook::Messenger::Incoming::Common
+
+        def action
+          @messaging['policy_enforcement']['action']
+        end
+
+        def reason
+          @messaging['policy_enforcement']['reason']
+        end
+      end
+    end
+  end
+end

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

@@ -1,14 +1,18 @@
 module Facebook
   module Messenger
     module Incoming
-      # The Postback class represents an incoming Facebook Messenger postback.
+      # The Postback class represents an incoming Facebook Messenger
+      #   postback events.
+      # @see https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_postbacks
       class Postback
         include Facebook::Messenger::Incoming::Common
 
+        # Return String of developer defined payload.
         def payload
           @messaging['postback']['payload']
         end
 
+        # Return hash containing the referral information of user.
         def referral
           return if @messaging['postback']['referral'].nil?
           @referral ||= Referral::Referral.new(

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

@@ -2,13 +2,16 @@ module Facebook
   module Messenger
     module Incoming
       # The Read class represents the user reading a delivered message.
+      # @see https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/message-reads
       class Read
         include Facebook::Messenger::Incoming::Common
 
+        # Return time object when message is read by user.
         def at
           Time.at(@messaging['read']['watermark'] / 1000)
         end
 
+        # Return Integer defining the sequence number of message.
         def seq
           @messaging['read']['seq']
         end

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

@@ -1,9 +1,9 @@
 module Facebook
   module Messenger
     module Incoming
-      # The Referral class represents an incoming Facebook Messenger referral.
+      # Referral class represents an incoming Facebook Messenger referral event.
       #
-      # https://developers.facebook.com/docs/messenger-platform/referral-params
+      # @see https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_referrals
       class Referral
         include Facebook::Messenger::Incoming::Common
 
@@ -13,14 +13,17 @@ module Facebook
             @referral = referral
           end
 
+          # Return String of ref data set in referrer.
           def ref
             @referral['ref']
           end
 
+          # Return String of referral source.
           def source
             @referral['source']
           end
 
+          # Return String of referral type.
           def type
             @referral['type']
           end

data/lib/facebook/messenger/profile.rb

@@ -2,18 +2,31 @@ require 'httparty'
 
 module Facebook
   module Messenger
-    # This module handles changing messenger profile (menu, start & greeting).
     #
-    # https://developers.facebook.com/docs/messenger-platform/messenger-profile
+    # This module provide functionality to manage the messenger profile.
+    # @see https://developers.facebook.com/docs/messenger-platform/messenger-profile
+    #
     module Profile
       include HTTParty
 
-      base_uri 'https://graph.facebook.com/v2.6/me'
+      # Define base_uri for HTTParty.
+      base_uri 'https://graph.facebook.com/v2.9/me'
 
       format :json
 
       module_function
 
+      #
+      # Set the messenger profile.
+      #
+      # @raise [Facebook::Messenger::Profile::Error] if there is any error
+      #   in response.
+      #
+      # @param [Hash] settings Hash defining the profile settings.
+      # @param [String] access_token  Access token of facebook page.
+      #
+      # @return [Boolean] If profile is successfully set, return true.
+      #
       def set(settings, access_token:)
         response = post '/messenger_profile', body: settings.to_json, query: {
           access_token: access_token
@@ -24,6 +37,17 @@ module Facebook
         true
       end
 
+      #
+      # Unset the messenger profile.
+      #
+      # @raise [Facebook::Messenger::Profile::Error] if there is any error
+      #   in response.
+      #
+      # @param [Hash] settings Hash defining the profile settings.
+      # @param [String] access_token  Access token of facebook page.
+      #
+      # @return [Boolean] If profile is successfully removed, return true.
+      #
       def unset(settings, access_token:)
         response = delete '/messenger_profile', body: settings.to_json, query: {
           access_token: access_token
@@ -34,10 +58,23 @@ module Facebook
         true
       end
 
+      #
+      # Function raise error if response has error key.
+      #
+      # @raise [Facebook::Messenger::Profile::Error] if error is present
+      #   in response.
+      #
+      # @param [Hash] response Response hash from facebook.
+      #
       def raise_errors(response)
         raise Error, response['error'] if response.key? 'error'
       end
 
+      #
+      # Default HTTParty options.
+      #
+      # @return [Hash] Default HTTParty options.
+      #
       def default_options
         super.merge(
           headers: {
@@ -46,6 +83,9 @@ module Facebook
         )
       end
 
+      #
+      # Class Error provides errors related to profile subscriptions.
+      #
       class Error < Facebook::Messenger::FacebookError; end
     end
   end

data/lib/facebook/messenger/server.rb

@@ -12,13 +12,16 @@ module Facebook
       some time, check your app's secret token.
     HEREDOC
 
+    #
     # This module holds the server that processes incoming messages from the
     # Facebook Messenger Platform.
+    #
     class Server
       def self.call(env)
         new.call(env)
       end
 
+      # Rack handler for request.
       def call(env)
         @request = Rack::Request.new(env)
         @response = Rack::Response.new
@@ -34,8 +37,14 @@ module Facebook
         @response.finish
       end
 
+      # @private
       private
 
+      #
+      # Function validates the verification request which is sent by Facebook
+      #   to validate the entered endpoint.
+      # @see https://developers.facebook.com/docs/graph-api/webhooks#callback
+      #
       def verify
         if valid_verify_token?(@request.params['hub.verify_token'])
           @response.write @request.params['hub.challenge']
@@ -44,6 +53,10 @@ module Facebook
         end
       end
 
+      #
+      # Function handles the webhook events.
+      # @raise BadRequestError if the request is tampered.
+      #
       def receive
         check_integrity
 
@@ -52,12 +65,16 @@ module Facebook
         respond_with_error(error)
       end
 
+      #
       # Check the integrity of the request.
+      # @see https://developers.facebook.com/docs/messenger-platform/webhook#security
       #
-      # Raises BadRequestError if the request has been tampered with.
+      # @raise BadRequestError if the request has been tampered with.
       #
-      # Returns nothing.
       def check_integrity
+        # If app secret is not found in environment, return.
+        # So for the security purpose always add provision in
+        #   configuration provider to return app secret.
         return unless app_secret_for(parsed_body['entry'][0]['id'])
 
         unless signature.start_with?('sha1='.freeze)
@@ -75,17 +92,21 @@ module Facebook
         @request.env['HTTP_X_HUB_SIGNATURE'.freeze].to_s
       end
 
+      #
       # Verify that the signature given in the X-Hub-Signature header matches
       # that of the body.
       #
-      # Returns a Boolean.
+      # @return [Boolean] true if request is valid else false.
+      #
       def valid_signature?
         Rack::Utils.secure_compare(signature, signature_for(body))
       end
 
+      #
       # Sign the given string.
       #
-      # Returns a String describing its signature.
+      # @return [String] A string describing its signature.
+      #
       def signature_for(string)
         format('sha1=%s'.freeze, generate_hmac(string))
       end
@@ -115,13 +136,23 @@ module Facebook
         @body ||= @request.body.read
       end
 
+      #
       # Returns a Hash describing the parsed request body.
+      # @raise JSON::ParserError if body hash is not valid.
+      #
+      # @return [JSON] Parsed body hash.
+      #
       def parsed_body
         @parsed_body ||= JSON.parse(body)
       rescue JSON::ParserError
         raise BadRequestError, 'Error parsing request body format'
       end
 
+      #
+      # Function hand over the webhook event to handlers.
+      #
+      # @param [Hash] events Parsed body hash in webhook event.
+      #
       def trigger(events)
         # Facebook may batch several items in the 'entry' array during
         # periods of high load.
@@ -137,6 +168,11 @@ module Facebook
         end
       end
 
+      #
+      # If received request is tampered, sent 400 code in response.
+      #
+      # @param [Object] error Error object.
+      #
       def respond_with_error(error)
         @response.status = 400
         @response.write(error.message)

data/lib/facebook/messenger/server_no_error.rb

@@ -0,0 +1,36 @@
+require_relative 'server'
+
+module Facebook
+  module Messenger
+    # Server rescuing all errors sending the backtrace back to the chat
+    # FOR DEVELOPPING PURPOSE
+    class ServerNoError < Server
+      SCREAMING_FACE = "\xF0\x9F\x98\xB1".freeze
+      MAX_MESSAGE_LENGTH = 639
+
+      def call(env)
+        super
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        send(SCREAMING_FACE)
+        send(e.inspect)
+        send(e.backtrace.join("\n")[0..MAX_MESSAGE_LENGTH - 3] + '...')
+
+        @response.status = 200
+        @response.finish
+      end
+
+      private
+
+      def sender
+        parsed_body['entry'][0]['messaging'][0]['sender']
+      end
+
+      def send(text)
+        Bot.deliver({
+                      recipient: sender,
+                      message: { text: text }
+                    }, access_token: ENV['ACCESS_TOKEN'])
+      end
+    end
+  end
+end

data/lib/facebook/messenger/subscriptions.rb

@@ -2,16 +2,31 @@ require 'httparty'
 
 module Facebook
   module Messenger
-    # This module handles subscribing and unsubscribing Applications to Pages.
+    #
+    # Module Subscriptions handles subscribing and unsubscribing Applications
+    #   to Pages.
+    #
     module Subscriptions
       include HTTParty
 
-      base_uri 'https://graph.facebook.com/v2.6/me'
+      base_uri 'https://graph.facebook.com/v2.9/me'
 
       format :json
 
       module_function
 
+      #
+      # Function subscribe the facebook app to page.
+      # @see https://developers.facebook.com/docs/graph-api/reference/page/subscribed_apps
+      #
+      # @raise [Facebook::Messenger::Subscriptions::Error] if there is any error
+      #   in the response of subscribed_apps request.
+      #
+      # @param [String] access_token Access token of page to which bot has
+      #   to subscribe.
+      #
+      # @return [Boolean] TRUE
+      #
       def subscribe(access_token:)
         response = post '/subscribed_apps', query: {
           access_token: access_token
@@ -22,6 +37,18 @@ module Facebook
         true
       end
 
+      #
+      # Function unsubscribe the app from facebook page.
+      # @see https://developers.facebook.com/docs/graph-api/reference/page/subscribed_apps
+      #
+      # @raise [Facebook::Messenger::Subscriptions::Error] if there is any error
+      #   in the response of subscribed_apps request.
+      #
+      # @param [String] access_token Access token of page from which app has
+      #   to unsubscribe.
+      #
+      # @return [Boolean] TRUE
+      #
       def unsubscribe(access_token:)
         response = delete '/subscribed_apps', query: {
           access_token: access_token
@@ -32,10 +59,23 @@ module Facebook
         true
       end
 
+      #
+      # If there is any error in response, raise error.
+      #
+      # @raise [Facebook::Messenger::Subscriptions::Error] If there is error
+      #   in response.
+      #
+      # @param [Hash] response Response from facebook.
+      #
+      # @return Raise the error.
+      #
       def raise_errors(response)
         raise Error, response['error'] if response.key? 'error'
       end
 
+      #
+      # Class Error provides errors related to subscriptions.
+      #
       class Error < Facebook::Messenger::FacebookError; end
     end
   end