facebook-messenger 1.0.0 → 1.1.0

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

@@ -2,8 +2,10 @@ module Facebook
   module Messenger
     class Configuration
       module Providers
-        # This is the base configuration provider. It raises errors so that you
-        # get nice ones.
+        # 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
           def valid_verify_token?(*)
             raise NotImplementedError

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

@@ -2,16 +2,21 @@ module Facebook
   module Messenger
     class Configuration
       module Providers
-        # Configuration provider for environment variables.
+        # The default configuration provider for environment variables.
         class Environment
           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

data/lib/facebook/messenger/error.rb

@@ -13,6 +13,11 @@ module Facebook
       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']
@@ -23,8 +28,16 @@ module Facebook
         @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
+        "#{@message} (subcode: #{subcode})"
       end
     end
   end

data/lib/facebook/messenger/incoming.rb

@@ -1,18 +1,25 @@
 require 'facebook/messenger/incoming/common'
 require 'facebook/messenger/incoming/message'
 require 'facebook/messenger/incoming/message_echo'
+require 'facebook/messenger/incoming/message_request'
 require 'facebook/messenger/incoming/delivery'
 require 'facebook/messenger/incoming/postback'
 require 'facebook/messenger/incoming/optin'
 require 'facebook/messenger/incoming/read'
 require 'facebook/messenger/incoming/account_linking'
 require 'facebook/messenger/incoming/referral'
+require 'facebook/messenger/incoming/payment'
+require 'facebook/messenger/incoming/policy_enforcement'
 
 module Facebook
   module Messenger
-    # The Incoming module parses and abstracts incoming requests from
-    # Facebook Messenger.
+    #
+    # Module Incoming parses and abstracts incoming requests from Messenger.
+    #
     module Incoming
+      #
+      # @return [Hash] Hash containing facebook messenger events and its event
+      #   handler classes.
       EVENTS = {
         'message' => Message,
         'delivery' => Delivery,
@@ -21,14 +28,22 @@ module Facebook
         'read' => Read,
         'account_linking' => AccountLinking,
         'referral' => Referral,
-        'message_echo' => MessageEcho
+        'message_echo' => MessageEcho,
+        'message_request' => MessageRequest,
+        'payment' => Payment,
+        'policy_enforcement' => PolicyEnforcement
       }.freeze
 
-      # Parse the given payload.
+      # Parse the given payload and create new object of class related
+      #   to event in payload.
+      #
+      # @see https://developers.facebook.com/docs/messenger-platform/webhook-reference
+      #
+      # @raise [Facebook::Messenger::Incoming::UnknownPayload] if event is not
+      #   registered in EVENTS constant
       #
-      # payload - A Hash describing a payload from Facebook.
+      # @param [Hash] payload A Hash describing a payload from Facebook.
       #
-      # * https://developers.facebook.com/docs/messenger-platform/webhook-reference
       def self.parse(payload)
         return MessageEcho.new(payload) if payload_is_echo?(payload)
 
@@ -39,10 +54,20 @@ module Facebook
         raise UnknownPayload, payload
       end
 
+      #
+      # Check if event is echo.
+      #
+      # @param [Hash] payload Request payload from facebook.
+      #
+      # @return [Boolean] If event is echo return true else false.
+      #
       def self.payload_is_echo?(payload)
         payload.key?('message') && payload['message']['is_echo'] == true
       end
 
+      #
+      # Class UnknownPayload provides errors related to incoming messages.
+      #
       class UnknownPayload < Facebook::Messenger::Error; end
     end
   end

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

@@ -1,18 +1,24 @@
 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

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

@@ -1,26 +1,73 @@
 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 the page of id from which the message is 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,
@@ -30,6 +77,13 @@ module Facebook
           Facebook::Messenger::Bot.deliver(payload, access_token: access_token)
         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,
@@ -39,6 +93,13 @@ module Facebook
           Facebook::Messenger::Bot.deliver(payload, access_token: access_token)
         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,
@@ -48,15 +109,28 @@ module Facebook
           Facebook::Messenger::Bot.deliver(payload, access_token: access_token)
         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: message,
+            message_type: Facebook::Messenger::Bot::MessageType::RESPONSE
           }
 
           Facebook::Messenger::Bot.deliver(payload, access_token: access_token)
         end
 
+        #
+        # Function returns the configured access token.
+        #
+        # @return [String] Access token.
+        #
         def access_token
           Facebook::Messenger.config.provider.access_token_for(recipient)
         end

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

@@ -2,6 +2,7 @@ module Facebook
   module Messenger
     module Incoming
       # The Delivery class represents the receipt of a delivered message.
+      # @see https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/message-deliveries
       class Delivery
         include Facebook::Messenger::Incoming::Common
 

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

@@ -1,12 +1,24 @@
 module Facebook
   module Messenger
     module Incoming
-      # The Message class represents an incoming Facebook Messenger message.
+      #
+      # Message class represents an incoming Facebook Messenger message event.
+      # @see https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messages
+      #
       class Message
         include Facebook::Messenger::Incoming::Common
 
+        #
+        # @return [Array] Supported attachments for message.
         ATTACHMENT_TYPES = %w[image audio video file location fallback].freeze
 
+        #
+        # Function returns unique id of message
+        # @see https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messages
+        #   Info about received message format.
+        #
+        # @return [String] Unique id of message.
+        #
         def id
           @messaging['message']['mid']
         end
@@ -15,34 +27,85 @@ module Facebook
           @messaging['message']['seq']
         end
 
+        #
+        # Function returns text of message
+        #
+        # @return [String] Text of message.
+        #
         def text
           @messaging['message']['text']
         end
 
+        #
+        # Whether message is echo or not?
+        #
+        # @return [Boolean] If message is echo return true else false.
+        #
         def echo?
           @messaging['message']['is_echo']
         end
 
+        #
+        # Function returns array containing attachment data
+        # @see https://developers.facebook.com/docs/messenger-platform/send-messages#sending_attachments
+        #   More info about attachments.
+        #
+        # @return [Array] Attachment data.
+        #
         def attachments
           @messaging['message']['attachments']
         end
 
+        #
+        # If facebook messenger built-in NLP is enabled, message will
+        #   contain 'nlp' key in response.
+        # @see https://developers.facebook.com/docs/messenger-platform/built-in-nlp
+        #   More information about built-in NLP.
+        #
+        #
+        # @return [Hash] NLP information about message.
+        #
+        def nlp
+          @messaging['message']['nlp']
+        end
+
+        #
+        # Function return app id from message.
+        #
+        # @return [String] App ID.
+        #
         def app_id
           @messaging['message']['app_id']
         end
 
+        #
+        # This meta programming defines function for
+        #   every attachment type to check whether the attachment
+        #   in message is of defined type or not.
+        #
         ATTACHMENT_TYPES.each do |attachment_type|
           define_method "#{attachment_type}_attachment?" do
             attachment_type?(attachment_type)
           end
         end
 
+        #
+        # Get the type of attachment in message.
+        #
+        # @return [String] Attachment type.
+        #
         def attachment_type
           return if attachments.nil?
 
           attachments.first['type']
         end
 
+        #
+        # Get the URL of attachment in message.
+        # URL is only available for attachments of type image/audio/video/file.
+        #
+        # @return [String] URL of attachment.
+        #
         def attachment_url
           return if attachments.nil?
           return unless %w[image audio video file].include? attachment_type
@@ -50,6 +113,12 @@ module Facebook
           attachments.first['payload']['url']
         end
 
+        #
+        # Get the location coordinates if attachment type is 'location'.
+        # @example [LATITUDE, LONGITUDE]
+        #
+        # @return [Array] Location coordinates.
+        #
         def location_coordinates
           return [] unless attachment_type?('location')
 
@@ -57,14 +126,30 @@ module Facebook
           [coordinates_data['lat'], coordinates_data['long']]
         end
 
+        #
+        # Get the payload of quick reply.
+        # @see https://developers.facebook.com/docs/messenger-platform/send-messages/quick-replies
+        #   More info about quick reply.
+        #
+        # @return [String] Payload string.
+        #
         def quick_reply
           return unless @messaging['message']['quick_reply']
 
           @messaging['message']['quick_reply']['payload']
         end
 
+        # @private
         private
 
+        #
+        # Check if attachment in message is of given type or not?
+        #
+        # @param [String] attachment_type Attachment type
+        #
+        # @return [Boolean] If type of attachment in message
+        #   and provided attachment type are same then return true else false.
+        #
         def attachment_type?(attachment_type)
           !attachments.nil? && attachments.first['type'] == attachment_type
         end